Difference between revisions of "Scripting Syntax"

From Audacity Wiki
Jump to: navigation, search
m (GetTrackInfo and SetTrackInfo, Expanded Syntax:)
(Marked page for deletion)
 
(15 intermediate revisions by 5 users not shown)
Line 1: Line 1:
=Overview=
+
* See also [https://manual.audacityteam.org/man/scripting.html scripting] in the manual.
This page contains information about an expanded Syntax for GetTrackInfo and SetTrackInfo for the scripting feature in Audacity.
 
  
==GetTrackInfo and SetTrackInfo, Expanded Syntax:==
+
{{ednote|[[ToDo-2]]'''Steve 30Jun20:''' This page needs to be deleted,  
 +
* links to it updating,
 +
* discussion moving to a new page or meging with related content.
  
===GetTrackInfo:===
 
GetTrackInfo: Type=[Name, Selected, Solo, Mute, Linked, Focused, Pan, Gain] TrackIndex=n 
 
  
'''New Type Parameters:'''
+
<pre>
::;Pan
+
{{ednote|1= &nbsp;
::;Gain
+
'''James:''' The old content of this page has now been corrected, updated and transferred to the alphamanual. 
:::If provided, response contains a decimal value of the Pan or Gain setting for that channel
+
* I've implemented missing/incomplete commands.
 +
* We need a rethink of presentation of commands.
 +
** The current format is much too verbose.
 +
** Something like the [https://alphamanual.audacityteam.org/man/Keyboard_Shortcut_Reference Shortcuts page] in the manual might be more use.
 +
}}
  
::;Solo
 
::;Mute
 
::;Selected
 
::;Linked
 
::;Focused
 
:::If provided, response contains a boolean value of that setting for the TrackIndex channel
 
  
'''Examples:'''
+
{{alert|This page is work in progress. The commands here are currently only available in some alpha builds, and the documentation may not quite match the commands implemented. That is why this is in the wiki rather than in the alphamanual. }}
{|
+
{{alert|When commands return a syntax error, the results may subsequently lag behind the requests, which can get confusing.}}
|'''Send'''
 
|'''Receive'''
 
|-
 
|
 
  GetTrackInfo: Type=Selected TrackIndex=2
 
|
 
  false
 
|-
 
|
 
GetTrackInfo: Type=Gain TrackIndex=3
 
|
 
0.5
 
|}
 
  
 +
=Overview=
 +
This page contains information about an expanded Syntax for GetTrackInfo and SetTrackInfo for the scripting feature in Audacity.
  
  
===SetTrackInfo:===
+
==GetMenusPlus:==
SetTrackInfo: Type=[Name, Selected, Solo, Mute] TrackIndex=n Setting=[true, false, 1, 0, yes, no]
 
  
where n is the number of the track, starting with 1 as the top audio track.
+
Gets a list of all the menu items in JSON format
 +
* [[WIT_Audacity_Menus|Sample output]]
  
'''New Type Parameters:'''
 
Solo
 
Mute
 
Selected
 
  
 +
'''Parameters:'''
 +
{{Param|1=''Dummy''|2=This parameter does not exist.}}
  
Note that Solo and Mute only work on Audio Tracks. On tracks other than Audio Tracks, nothing is changed,
 
there is no check, nor is there an error message, there is simply nothing done.
 
  
 
'''Examples:'''
 
'''Examples:'''
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=GetMenusPlus|2=GetMenuPlus finished: OK}}
|'''Receive'''
 
|-
 
|
 
SetTrackInfo: Type=Selected TrackIndex=2 Setting=true
 
|
 
SetTrackInfo finished: OK
 
|-
 
|
 
SetTrackInfo: Type=Solo TrackIndex=3 Setting=false
 
|
 
SetTrackInfo finished: OK
 
|}
 
 
 
If the track index is out of range, or otherwise invalid, the following occurs:
 
{|
 
|'''Send'''
 
|'''Receive'''
 
|-
 
|
 
SetTrackInfo: Type=Selected TrackIndex=2 Setting=true
 
|
 
SetTrackInfo: Failed! Invalid TrackIndex
 
|}
 
 
 
==New Commands GetProjectInfo and SetProjectInfo:==
 
<div class="editornote"> ''Not yet implemented in Audacity 1.3.8'' </div>
 
  
 +
==GetBoxes:==
  
'''GetProjectInfo:'''
+
Gets a list of all the toolbars and buttons in JSON format
GetProjectInfo: Type=[Name, SoloTracks, MuteTracks, SelectedTracks, FocusedTrackID]
 
              //  and possible future parameters: [SampleRate, NumberOfTracks, etc.]
 
  
Allows information about all project's tracks to be returned to the script.
 
  
 
'''Parameters:'''
 
'''Parameters:'''
 +
{{Param|1=''Dummy''|2=This parameter does not exist.}}
  
::;SelectedTracks
 
:::An integer (default: 0) identifying the track
 
 
::;Type
 
:::Info to get. One of: Name, SelectedTracks, SoloTracks, MuteTracks, FocusedTrackID (default: Name)
 
  
 
'''Examples:'''
 
'''Examples:'''
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=GetBoxes|2=GetBoxes finished: OK}}
|'''Receive'''
 
|-
 
|
 
GetProjectInfo: Type=SoloTracks
 
|
 
001010000
 
GetProjectInfo finished: OK
 
|-
 
|
 
GetProjectInfo: Type=FocusedTrackID
 
|
 
4
 
GetProjectInfo finished: OK
 
|}
 
  
  
'''SetProjectInfo:'''
+
==GetClips:==
SetProjectInfo: Type=[Name, SoloTracks, MuteTracks, SelectedTracks] TrackSet=10110100xxx
 
  
Allows the state of one parameter on all project's tracks to be set to a particular value.
+
Gets a list of all the clips in JSON format
  
The TrackSet parameter represents the setting for tracks numbering left to right, starting with 1, as in 12345...
 
  
The characters in the string represent enabling (1) disabling (0), or leaving alone (x) the parameter indicated by Type=ParamTracks for each channel.
+
'''Parameters:'''
+
{{Param|1=''Dummy''|2=This parameter does not exist.}}
'1' means that parameter is asserted in that track, for example, for MuteTracks, a 1 will mute that track.
 
  
'0' de-asserts it, i.e. unmutes it.
 
  
'x' will leave the indicated track in its current state.
+
'''Examples:'''
 +
{{Send_Receive_Title}}
 +
{{Send_Receive|1=GetClips|2=GetClips finished: OK}}
  
  
 +
==GetLabels:==
  
Note that the string length is not required to match the number of channels in a project.  If the string of 1s and 0s is shorter than the number of channels, then channels beyond the “reach” of the TrackSet string are untouched.  If the TrackSet string is longer than the number of channels in the project, then those characters in the string beyond the last track in the project are ignored.
+
Gets a list of all the labels in JSON format
  
Note also that there is no checking done for any mismatch between the TrackSet string length and the actual number of tracks in a session project.  We could decide to return a condition flag indicating the mismatch as the TrackSet string being either too long or too short, if this is deemed important.
 
  
 +
'''Parameters:'''
 +
{{Param|1=''Dummy''|2=This parameter does not exist.}}
  
  
'''Parameters:'''
+
'''Examples:'''
 
+
{{Send_Receive_Title}}
::;Type
+
{{Send_Receive|1=GetLabels|2=GetLabels finished: OK}}
:::Info to get. One of: Name, SelectedTracks, SoloTracks, MuteTracks, FocusedTrackID (default: Name)
+
</pre>
 +
}}
  
::;SelectedTracks
 
:::A string of characters: {1,0,x} indicating Assert, Deassert or leave alone, respectively
 
  
'''Examples:'''
+
[[Category:For Developers]]
{|
 
|'''Send'''
 
|'''Receive'''
 
|-
 
|
 
SetProjectInfo: Type=SoloTracks
 
|
 
001010000
 
|-
 
|
 
SetProjectInfo: Type=FocusedTrackID
 
|
 
4
 
|}
 

Latest revision as of 20:27, 30 June 2020

ToDo-2Steve 30Jun20: This page needs to be deleted,
  • links to it updating,
  • discussion moving to a new page or meging with related content.


{{ednote|1=  
'''James:''' The old content of this page has now been corrected, updated and transferred to the alphamanual.  
* I've implemented missing/incomplete commands.
* We need a rethink of presentation of commands.
** The current format is much too verbose.
** Something like the [https://alphamanual.audacityteam.org/man/Keyboard_Shortcut_Reference Shortcuts page] in the manual might be more use.
}}


{{alert|This page is work in progress.  The commands here are currently only available in some alpha builds, and the documentation may not quite match the commands implemented.  That is why this is in the wiki rather than in the alphamanual. }}
{{alert|When commands return a syntax error, the results may subsequently lag behind the requests, which can get confusing.}}

=Overview=
This page contains information about an expanded Syntax for GetTrackInfo and SetTrackInfo for the scripting feature in Audacity.


==GetMenusPlus:==

Gets a list of all the menu items in JSON format
* [[WIT_Audacity_Menus|Sample output]]


'''Parameters:'''
{{Param|1=''Dummy''|2=This parameter does not exist.}}


'''Examples:'''
{{Send_Receive_Title}}
{{Send_Receive|1=GetMenusPlus|2=GetMenuPlus finished: OK}}

==GetBoxes:==

Gets a list of all the toolbars and buttons in JSON format


'''Parameters:'''
{{Param|1=''Dummy''|2=This parameter does not exist.}}


'''Examples:'''
{{Send_Receive_Title}}
{{Send_Receive|1=GetBoxes|2=GetBoxes finished: OK}}


==GetClips:==

Gets a list of all the clips in JSON format


'''Parameters:'''
{{Param|1=''Dummy''|2=This parameter does not exist.}}


'''Examples:'''
{{Send_Receive_Title}}
{{Send_Receive|1=GetClips|2=GetClips finished: OK}}


==GetLabels:==

Gets a list of all the labels in JSON format


'''Parameters:'''
{{Param|1=''Dummy''|2=This parameter does not exist.}}


'''Examples:'''
{{Send_Receive_Title}}
{{Send_Receive|1=GetLabels|2=GetLabels finished: OK}}