Difference between revisions of "Scripting Syntax"

From Audacity Wiki
Jump to: navigation, search
(Templatified the parameters and examples. Made compatible with manual page so that we can easily merge them later.)
Line 5: Line 5:
  
 
===GetTrackInfo:===
 
===GetTrackInfo:===
GetTrackInfo: Type=[Name, Selected, Solo, Mute, Linked, Focused, Pan, Gain] TrackIndex=n 
 
  
'''New Type Parameters:'''
+
Returns information about one track.
::;Pan
+
 
::;Gain
+
In each of the following commands the value is returned if the setting exists.  Not clear what is returned if the setting does not.
:::If provided, response contains a decimal value of the Pan or Gain setting for that channel
+
 
 +
'''Parameters:'''
 +
{{Param|1=Type|2=Info to get. One of:
 +
*Pan
 +
*Gain
 +
*Solo
 +
*Mute
 +
*Selected
 +
*Linked
 +
*Focused
 +
Pan and gain return decimal values, the others boolean values.
 +
}}
 +
{{Param|1=TrackIndex|2=The number of the track to get info from}}
  
::;Solo
 
::;Mute
 
::;Selected
 
::;Linked
 
::;Focused
 
:::If provided, response contains a boolean value of that setting for the TrackIndex channel
 
  
 
'''Examples:'''
 
'''Examples:'''
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=GetTrackInfo: Type=Selected TrackIndex=2|2=false}}
|'''Receive'''
+
{{Send_Receive|1=GetTrackInfo: Type=Gain TrackIndex=3|2=0.5}}
|-
 
|
 
GetTrackInfo: Type=Selected TrackIndex=2
 
|
 
false
 
|-
 
|
 
GetTrackInfo: Type=Gain TrackIndex=3
 
|
 
0.5
 
|}
 
  
  
 +
===SetTrackInfo:===
  
===SetTrackInfo:===
+
Sets information for one track.
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.
+
'''Parameters:'''
 +
{{Param|1=Type|2=Info to set. One of:
 +
*Selected
 +
*Solo
 +
*Mute
 +
N.B. 'Name' is not yet supported.
 +
}}
 +
{{Param|1=TrackIndex|2=The number of the track to set.<br>
 +
1 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)}}
  
'''New Type Parameters:'''
 
Solo
 
Mute
 
Selected
 
  
  
Note that Solo and Mute only work on Audio Tracks. On tracks other than Audio Tracks, nothing is changed,  
+
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.
there is no check, nor is there an error message, there is simply nothing done.
 
  
 
'''Examples:'''
 
'''Examples:'''
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=SetTrackInfo: Type=Selected TrackIndex=2 Setting=true|2=SetTrackInfo finished: OK}}
|'''Receive'''
+
{{Send_Receive|1= SetTrackInfo: Type=Solo TrackIndex=3 Setting=false|2=SetTrackInfo finished: OK}}
|-
 
|
 
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:
 
If the track index is out of range, or otherwise invalid, the following occurs:
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=SetTrackInfo: Type=Selected TrackIndex=2 Setting=true|2=SetTrackInfo: Failed! Invalid TrackIndex}}
|'''Receive'''
+
 
|-
 
|
 
SetTrackInfo: Type=Selected TrackIndex=2 Setting=true
 
|
 
SetTrackInfo: Failed! Invalid TrackIndex
 
|}
 
  
 
==New Commands GetProjectInfo and SetProjectInfo:==
 
==New Commands GetProjectInfo and SetProjectInfo:==
<div class="editornote"> ''Not yet implemented in Audacity 1.3.8'' </div>
 
  
 +
Returns the chosen information about the tracks in the current project.
  
'''GetProjectInfo:'''
+
'''Parameters:'''
GetProjectInfo: Type=[Name, SoloTracks, MuteTracks, SelectedTracks, NumberOfTracks, FocusedTrackID]
+
{{Param|1=SelectedTracks|2=An integer (default: 0) identifying the track}}
              //  and possible future parameters: [SampleRate, etc.]
+
{{Param|1=Type|2=Info to get. One of:
 
+
*Name
Allows information about all project's tracks to be returned to the script.
+
*SelectedTracks
 +
*SoloTracks
 +
*MuteTracks
 +
*FocusedTrackID
 +
(default: Name)}}
  
'''Parameters:'''
 
  
::;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=GetProjectInfo: Type=SoloTracks|2=001010000}}
|'''Receive'''
+
{{Send_Receive|1=GetProjectInfo: Type=FocusedTrackID|2=5}}
|-
+
{{Send_Receive|1=GetProjectInfo: Type=NumberOfTracks|2=9}}
|
 
GetProjectInfo: Type=SoloTracks
 
|
 
001010000
 
|-
 
|
 
GetProjectInfo: Type=FocusedTrackID
 
|
 
5
 
|-
 
|
 
GetProjectInfo: Type=NumberOfTracks
 
|
 
9
 
|}
 
  
  
 
'''SetProjectInfo:'''
 
'''SetProjectInfo:'''
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.
+
Allows state of one parameter type on all of a project's tracks to be set.
  
 
The TrackSet parameter represents the setting for tracks numbering left to right, starting with 1, as in 12345...
 
The TrackSet parameter represents the setting for tracks numbering left to right, starting with 1, as in 12345...
Line 127: Line 93:
 
The characters in the string represent enabling (1) disabling (0), or leaving alone (x) the parameter indicated by Type=ParamTracks for each channel.
 
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.
+
* '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.
  
'0' de-asserts it, i.e. unmutes it.
 
  
'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.
  
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.
+
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.
 
 
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:'''
 
'''Parameters:'''
 +
{{Param|1=Type|2=Info to get. One of:
 +
*SelectedTracks
 +
*SoloTracks
 +
*MuteTracks}}
 +
{{Param|1=SelectedTracks|2=A string of characters: {1,0,x} indicating Assert, Deassert or leave alone, respectively}}
  
::;Type
 
:::Info to get. One of: SelectedTracks, SoloTracks, MuteTracks
 
  
::;SelectedTracks
 
:::A string of characters: {1,0,x} indicating Assert, Deassert or leave alone, respectively
 
  
 
'''Examples:'''
 
'''Examples:'''
{|
+
{{Send_Receive_Title}}
|'''Send'''
+
{{Send_Receive|1=SetProjectInfo: Type=SoloTracks TrackSet=10010xxx1|2=SetProjectInfo finished: OK}}
|'''Receive'''
+
{{Send_Receive|1=SetProjectInfo: Type=MuteTracks TrackSet=101000xxx|2=SetProjectInfo finished: OK}}
|-
+
 
|
 
SetProjectInfo: Type=SoloTracks TrackSet=10010xxx1
 
|
 
SetProjectInfo finished: OK
 
|-
 
|
 
SetProjectInfo: Type=MuteTracks TrackSet=101000xxx
 
|
 
SetProjectInfo finished: OK
 
|}
 
  
  
 
[[Category:For Developers]]
 
[[Category:For Developers]]

Revision as of 21:57, 14 December 2009

Overview

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

GetTrackInfo and SetTrackInfo, Expanded Syntax:

GetTrackInfo:

Returns information about one track.

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:

Type: Info to get. One of:
  • Pan
  • Gain
  • Solo
  • Mute
  • Selected
  • Linked
  • Focused

Pan and gain return decimal values, the others boolean values.

TrackIndex: The number of the track to get info from


Examples:

Send Receive
GetTrackInfo: Type=Selected TrackIndex=2 false
GetTrackInfo: Type=Gain TrackIndex=3 0.5


SetTrackInfo:

Sets information for one track.

Parameters:

Type: Info to set. One of:
  • Selected
  • Solo
  • Mute

N.B. 'Name' is not yet supported.

TrackIndex: The number of the track to set.

1 is the top audio track.

Setting: 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)


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:

Send 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:

Returns the chosen information about the tracks in the current project.

Parameters:

SelectedTracks: An integer (default: 0) identifying the track
Type: Info to get. One of:
  • Name
  • SelectedTracks
  • SoloTracks
  • MuteTracks
  • FocusedTrackID

(default: Name)



Examples:

Send Receive
GetProjectInfo: Type=SoloTracks 001010000
GetProjectInfo: Type=FocusedTrackID 5
GetProjectInfo: Type=NumberOfTracks 9


SetProjectInfo:

Allows state of one parameter type on all of a project's tracks to be set.

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.


Parameters:

Type: Info to get. One of:
  • SelectedTracks
  • SoloTracks
  • MuteTracks
SelectedTracks: A string of characters: {1,0,x} indicating Assert, Deassert or leave alone, respectively


Examples:

Send Receive
SetProjectInfo: Type=SoloTracks TrackSet=10010xxx1 SetProjectInfo finished: OK
SetProjectInfo: Type=MuteTracks TrackSet=101000xxx SetProjectInfo finished: OK