Scripting

From Audacity Development Manual
Jump to: navigation, search
The scripting module is a plugin 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.

The plugin mod-script-pipe is now shipped with Audacity (Windows and macOS) and just needs to be enabled using Modules preferences.
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, for example 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

Advice 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.

Advice Scripting support is mainly intended for use by developers.
  • When things "do not 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.

Alert Scripting is NOT SUITABLE for providing a service on a web server.
  • The reason is that Audacity does not police or sanitize 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

The plugin module "mod-script-pipe" is not enabled by default in Audacity, so must be enabled in 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.

Check mod-script-pipe works

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

A simple Python test script is provided to check that the pipe is working:

Using Scripting

After checking that the "pipe_test.py" script works, you could try adding other commands to the end of the pipe_test.py script. Each command name ends with a colon, and may be followed by parameters. For example: 

do_command("Help:")

For practical scripting, the script "pipeclient.py" provides a useful starting point:

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:


Scripting 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 string "SetLabel: Text='Foo'" sent from Python would set the first label in a project to the word 'Foo'.

Using "pipe_test.py", the command could be sent with: 

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

Using "pipeclient.py" as a command-line script, simply type the command at the prompt: 

Enter command or 'Q' to quit: SetLabel: Text='Foo'


Known Issues & Missing Features

Advice 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.