Difference between revisions of "Scripting Syntax"

From Audacity Wiki
Jump to: navigation, search
(Obsolete content now.)
(Updates.)
Line 2: Line 2:
  
 
{{ednote|1=
 
{{ednote|1=
 +
 
* '''James:''' The content of this page has now been corrected, updated and transferred to the alphamanual.   
 
* '''James:''' The content of this page has now been corrected, updated and transferred to the alphamanual.   
 
* I've implemented missing/incomplete commands.
 
* I've implemented missing/incomplete commands.
* I will probably remove the content here, and just use it for new features as they are developed}}
 
 
  
{{alert|This page is an obsolete proposal for extended scripting syntax.  The commands have been reworked and implemented and are documented in the manual.}}
+
{{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.}}
 
{{alert|When commands return a syntax error, the results may subsequently lag behind the requests, which can get confusing.}}
  
Line 13: Line 12:
 
This page contains information about an expanded Syntax for GetTrackInfo and SetTrackInfo for the scripting feature in Audacity.
 
This page contains information about an expanded Syntax for GetTrackInfo and SetTrackInfo for the scripting feature in Audacity.
  
==GetTrackInfo and SetTrackInfo, Expanded Syntax:==
 
  
===GetTrackInfo:===
+
==GetMenusPlus:==
  
Returns information about one track.
+
Gets a list of all the menu items in JSON format
 +
* [[WIT_Audacity_Menus|Sample output]]
  
In each of the following commands the value is returned if the setting exists.  Not clear what is returned if the setting does not.
 
  
 
'''Parameters:'''
 
'''Parameters:'''
{{Param|1=Type|2=Info to get. One of:
+
{{Param|1=''Dummy''|2=This parameter does not exist.}}
*Name
 
*StartTime
 
*EndTime
 
*Pan
 
*Gain
 
*Solo
 
*Mute
 
*Selected
 
*Linked
 
*Focused
 
}}
 
{{Param|1=TrackIndex|2=The number of the track to get info from}}
 
  
Name returns a string, StartTime, EndTime, Pan and gain return decimal values, the others boolean values.
 
  
 
'''Examples:'''
 
'''Examples:'''
 
{{Send_Receive_Title}}
 
{{Send_Receive_Title}}
{{Send_Receive|1=GetTrackInfo: Type=Selected TrackIndex=2|2=false}}
+
{{Send_Receive|1=GetMenusPlus|2=GetMenuPlus finished: OK}}
{{Send_Receive|1=GetTrackInfo: Type=Gain TrackIndex=3|2=0.5}}
 
 
 
 
 
===SetTrackInfo:===
 
  
{{alert|1=Type=Name is implemented and documented, but not these types yet.}}
+
==GetBoxes:==
  
 +
Gets a list of all the toolbars and buttons in JSON format
  
Sets information for one track.
 
  
 
'''Parameters:'''
 
'''Parameters:'''
{{Param|1=Type|2=Info to set. One of:
+
{{Param|1=''Dummy''|2=This parameter does not exist.}}
*Selected
 
*Solo
 
*Mute
 
N.B. 'Type' is not yet supported.
 
}}
 
{{Param|1=TrackIndex|2=The number of the track to set.<br>
 
0 is the top audio track.}}
 
{{Param|1=Setting|2=The value to set. One of
 
*true, 1 or yes (all three are treated the same)
 
*false, 0 or no (all three are treated the same)}}
 
  
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_Receive_Title}}
{{Send_Receive|1=SetTrackInfo: Type=Selected TrackIndex=2 Setting=true|2=SetTrackInfo finished: OK}}
+
{{Send_Receive|1=GetBoxes|2=GetBoxes finished: OK}}
{{Send_Receive|1= SetTrackInfo: Type=Solo TrackIndex=3 Setting=false|2=SetTrackInfo finished: OK}}
 
  
If the track index is out of range, or otherwise invalid, the following occurs:
 
{{Send_Receive_Title}}
 
{{Send_Receive|1=SetTrackInfo: Type=Selected TrackIndex=2 Setting=true|2=SetTrackInfo: Failed! Invalid TrackIndex}}
 
  
 +
==GetClips:==
  
==New Commands GetProjectInfo and SetProjectInfo:==
+
Gets a list of all the clips in JSON format
  
Returns the chosen information about the tracks in the current project.
 
  
 
'''Parameters:'''
 
'''Parameters:'''
{{Param|1=SelectedTracks|2=An integer (default: 0) identifying the track}}
+
{{Param|1=''Dummy''|2=This parameter does not exist.}}
{{Param|1=Type|2=Info to get. One of:
 
*Name
 
*NumberOfTracks
 
*SelectedTracks
 
*SoloTracks
 
*MuteTracks
 
*FocusedTrackID
 
(default: Name)}}
 
 
 
Name is the filename. 
 
  
  
 
'''Examples:'''
 
'''Examples:'''
 
{{Send_Receive_Title}}
 
{{Send_Receive_Title}}
{{Send_Receive|1=GetProjectInfo: Type=SoloTracks|2=001010000}}
+
{{Send_Receive|1=GetClips|2=GetClips finished: OK}}
{{Send_Receive|1=GetProjectInfo: Type=FocusedTrackID|2=5}}
 
{{Send_Receive|1=GetProjectInfo: Type=NumberOfTracks|2=9}}
 
 
 
  
'''SetProjectInfo:'''
 
  
Allows state of one parameter type on all of a project's tracks to be set.
+
==GetLabels:==
 
 
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.
 
 
* '1' means that parameter is asserted in that track, for example, for MuteTracks, a 1 will mute that track.
 
* '0' de-asserts it, for example for MuteTracks a 0 unmutes that track.
 
* 'x' will leave the indicated track in its current state.
 
 
 
 
 
 
 
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.
 
 
 
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.
 
  
 +
Gets a list of all the labels in JSON format
  
  
 
'''Parameters:'''
 
'''Parameters:'''
{{Param|1=Type|2=Info to set. One of:
+
{{Param|1=''Dummy''|2=This parameter does not exist.}}
*SelectedTracks
 
*SoloTracks
 
*MuteTracks}}
 
{{Param|1=SelectedTracks|2=A string of characters: {1,0,x} indicating Assert, Deassert or leave alone, respectively}}
 
 
 
  
  
 
'''Examples:'''
 
'''Examples:'''
 
{{Send_Receive_Title}}
 
{{Send_Receive_Title}}
{{Send_Receive|1=SetProjectInfo: Type=SoloTracks TrackSet=10010xxx1|2=SetProjectInfo finished: OK}}
+
{{Send_Receive|1=GetLabels|2=GetLabels finished: OK}}
{{Send_Receive|1=SetProjectInfo: Type=MuteTracks TrackSet=101000xxx|2=SetProjectInfo finished: OK}}
 
  
  
  
 
[[Category:For Developers]]
 
[[Category:For Developers]]

Revision as of 13:02, 18 January 2018

{{ednote|1=

  • James: The content of this page has now been corrected, updated and transferred to the alphamanual.
  • I've implemented missing/incomplete commands.


Warning icon 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.
Warning icon 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


Parameters:

Dummy: This parameter does not exist.


Examples:

Send Receive
GetMenusPlus GetMenuPlus finished: OK

GetBoxes:

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


Parameters:

Dummy: This parameter does not exist.


Examples:

Send Receive
GetBoxes GetBoxes finished: OK


GetClips:

Gets a list of all the clips in JSON format


Parameters:

Dummy: This parameter does not exist.


Examples:

Send Receive
GetClips GetClips finished: OK


GetLabels:

Gets a list of all the labels in JSON format


Parameters:

Dummy: This parameter does not exist.


Examples:

Send Receive
GetLabels GetLabels finished: OK