Difference between revisions of "Scripting Syntax"

From Audacity Wiki
Jump to: navigation, search
m (New Commands GetProjectInfo and SetProjectInfo:)
m (New Commands GetProjectInfo and SetProjectInfo:)
Line 109: Line 109:
 
  GetProjectInfo: Type=FocusedTrackID
 
  GetProjectInfo: Type=FocusedTrackID
 
|
 
|
  9
+
  5
 
|-
 
|-
 
|
 
|

Revision as of 14:08, 10 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:

GetTrackInfo: Type=[Name, Selected, Solo, Mute, Linked, Focused, Pan, Gain] TrackIndex=n

New Type Parameters:

Pan
Gain
If provided, response contains a decimal value of the Pan or Gain setting for that channel
Solo
Mute
Selected
Linked
Focused
If provided, response contains a boolean value of that setting for the TrackIndex channel

Examples:

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


SetTrackInfo:

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.

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

Not yet implemented in Audacity 1.3.8


GetProjectInfo:

GetProjectInfo: Type=[Name, SoloTracks, MuteTracks, SelectedTracks, NumberOfTracks, FocusedTrackID]
             //  and possible future parameters: [SampleRate, etc.] 

Allows information about all project's tracks to be returned to the script.

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:

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.

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, i.e. unmutes it.

'x' will leave the indicated track in its current state.


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.

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:

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