Scripting

From Audacity Development Manual
Jump to: navigation, search
The scripting module is a plug-in for advanced users that allows Audacity to be driven from an external Python or Perl script. Commands are sent to Audacity over a 'named pipe'.

Any scripting language that supports named pipes can be used.
Scripting is most often used from Python.
  • The full set of Scripting Commands is listed at Scripting Reference.
  • Many of the commands in the Scriptables I and Scriptables II menus were created because they are useful in scripting.
  • Alternatives to Python scripting that use the same set of commands are:
    • Macros which follow a fixed set of steps, e.g. to convert many files from one format to another.
    • Nyquist, using the ';type tool' option. Nyquist is a built in LISP based language in Audacity.

What Scripting can do

Commands that Scripting uses are the same as in the Audacity macros feature. You can for example:

  • Select audio
  • Apply effects
  • Rearrange clips
  • Export the results.

Scripting goes beyond the simpler tasks and presets of macros. Using Python scripting can for example do calculations about regions to select, or can make decisions on the basis of number and types of tracks in a project. It is also possible to build additional user interface in Python, for example an extra toolbar, and have it send commands to Audacity over the pipe.


Caveats and Warnings

Warning icon Scripting drives Audacity from outside the Audacity user interface.
  • If you use mod-script-pipe to enable scripting, this weakens computer security, as malicious software that already has a foothold on your computer could potentially use this feature to gain more control.

See the advice below about not using scripting on a web server.

Warning icon Scripting support is mainly intended for use by developers.
  • When things "don't work" you will rarely get a message from Audacity saying why.
  • Details of the available scripting commands may well change between versions of Audacity.

There is a fuller list of limitations at the foot of this page.

Warning icon Scripting is NOT SUITABLE for providing a service on a web server.
  • The reason is that Audacity does not police or sanitise the instructions that arrive on the pipe. It just attempts to obey the instructions.
  • If someone can write to the pipe they can get Audacity to read and write files and to execute code on the machine running Audacity.

Enabling mod-script-pipe allows Audacity to be controlled from outside the Audacity User Interface. In some environments, such as a web server, that is too big a security risk.


Getting Started

Enable mod-script-pipe

Audacity now comes with a plug-in module called "mod-script-pipe". You enable it using the Audacity preferences.

After enabling it for the first time, you will need to restart Audacity. You can then check that it is enabled and was started by revisiting the preferences page.

  • Run Audacity
  • Go into edit->preferences->modules
    • Choose mod-script-pipe (which should show 'New') and change that to 'Enabled'.
  • Restart Audacity
  • Check that it now does show 'Enabled'.

This establishes that Audacity is finding mod-script pipe, and that the version is compatible (compiled on the same day).

Check mod-script-pipe works

You'll also need the scripting language Python (version 3.6 or later recommended) to try out the examples.

This python script is then the best way of checking that the pipe is working:

Using Scripting

After running pipe-test.py, you can use do("") at the python command line to try out commands. Each command name ends with a colon, and may be followed by parameters. For example: 

do("Help:")

Examples

More sample scripts are available here:


Commands

A table showing all the available scripting commands is at Scripting Reference.

Most commands in Audacity that are in the Audacity menus can be accessed via Scripting. Here is one example from that table:


Automation Id Action Parameters Description
SetLabel: Set Label... int Label, (default:0)

string Text, (default:unchanged)
double Start, (default:unchanged)
double End, (default:unchanged)
bool Selected, (default:unchanged)

 Modifies an existing label.

The following command in Python would set the first label in a project to the word 'Foo'. 

do("SetLabel: Text='Foo'")


Known Issues & Missing Features

Warning icon Some current issues:
  • Scripting only works with one project at a time.
  • For some menu commands, the project window must have focus for the command to succeed.
  • It's not straightforward to get 'output' responses from commands like GetInfo. You will need to parse the results in Python.
  • The commands could have stricter parameter validation and could give better error messages when they do not work.
  • There's no consistent way to abort or interrupt commands.
  • The scripting module is not unloaded when Audacity quits. This means the script pipes are not properly deleted.
  • There may be security problems relating to the use of pipes. You're advised not to use mod-script-pipe on a system with multiple simultaneous users.