Scripting reference
This page lists scripting commands.
Yes these are the same commands as in the menus, same as in "Commands and Shortcuts" too, just presented differently.
- Presented in a format useful to people using:
- Macros or
- Python Scripting or
- AUD-DO.
- Most of this page is automatically generated.
A few commands are intentionally omitted from the Macro Manager (such as "Close:") because they are unsuitable for use in Macros.
This table shows the items in the menus that are scriptable.
- The Scripting Ids, parameters and defaults are all likely to change between versions.
- Boolean values must be given as 1 (true) or 0 (false).
The File Menu provides commands for creating, opening and saving Audacity projects and importing and exporting audio files
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
New: | New | none | Creates a new empty project window, to start working on new or imported tracks. |
Open: | Open... | none | Presents a standard dialog box where you can select either audio files, a list of files (.LOF) or an Audacity Project file to open. |
Close: | Close | none | Closes the current project window, prompting you to save your work if you have not saved. |
SaveProject: | Save Project | none | Various ways to save a project. |
CompactProject: | Compact Project | none | Compact your project to save disk space. |
PageSetup: | Page Setup... | none | Opens the standard Page Setup dialog box prior to printing |
Print: | Print... | none | Prints all the waveforms in the current project window (and the contents of Label Tracks or other tracks), with the Timeline above. Everything is printed to one page. |
Exit: | Exit | none | Closes all project windows and exits Audacity. If there are any unsaved changes to your project, Audacity will ask if you want to save them. |
Various ways to save a project.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
Save: | Save Project | none | Saves the current Audacity project .AUP3 file. |
SaveAs: | Save Project As... | none | Same as "Save Project" above, but allows you to save a copy of an open project to a different name or location |
SaveCopy: | Save Lossless Copy of Project... | none | Saves the current Audacity project .AUP3 file. |
SaveCompressed: | Save Compressed Copy of Project... | none | Saves in the audacity .aup3 project file format, but compressed (Suitable for mailing) |
For exporting audio files
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
ExportMp3: | Export as MP3 | none | Exports to an MP3 file |
ExportWav: | Export as WAV | none | Exports to a WAV file |
ExportOgg: | Export as OGG | none | Exports to an OGG file |
Export: | Export Audio... | none | Exports to an audio file. |
ExportSel: | Export Selected Audio... | none | Exports selected audio to a file. |
ExportLabels: | Export Labels... | none | Exports audio at one or more labels to file(s). |
ExportMultiple: | Export Multiple... | none | Exports multiple audio files in one process, one file for each track if there are multiple audio tracks, or labels can be added which then define the length of each exported file. |
ExportMIDI: | Export MIDI... | none | Exports MIDI (note tracks) to a MIDI file. |
For importing audio files or label files into your project
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
ImportAudio: | Audio... | none | Similar to 'Open', except that the file is added as a new track to your existing project. |
ImportLabels: | Labels... | none | Launches a file selection window where you can choose to import a single text file into the project containing point or region labels. For more information about the syntax for labels files, see Importing and Exporting Labels. |
ImportMIDI: | MIDI... | none | Imports a MIDI (MIDI or MID extension) or Allegro (GRO) file to a Note Track where simple cut-and-paste edits can be performed. The result can be exported with the File > Export> > Export MIDI command. Note: Currently, MIDI and Allegro files cannot be played. |
ImportRaw: | Raw Data... | none | Attempts to import an uncompressed audio file that might be "raw" data without any headers to define its format, might have incorrect headers or be otherwise partially corrupted, or might be in a format that Audacity is unable to recognize. Raw data in textual format cannot be imported. |
The Edit Menu provides standard edit commands (Undo, Redo, Cut, Copy, Paste and Delete) plus many other commands specific to editing audio or labels
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
Undo: | Undo | none | Undoes the most recent editing action. |
Redo: | Redo | none | Redoes the most recently undone editing action. |
Cut: | Cut | none | Removes the selected audio data and/or labels and places these on the Audacity clipboard. By default, any audio or labels to right of the selection are shifted to the left. |
Delete: | Delete | none | Removes the selected audio data and/or labels without copying these to the Audacity clipboard. By default, any audio or labels to right of the selection are shifted to the left. |
Copy: | Copy | none | Copies the selected audio data to the Audacity clipboard without removing it from the project. |
Paste: | Paste | none | Inserts whatever is on the Audacity clipboard at the position of the selection cursor in the project, replacing whatever audio data is currently selected, if any. |
Duplicate: | Duplicate | none | Creates a new track containing only the current selection as a new clip. |
EditMetaData: | Metadata... | none | The Metadata Editor modifies information about a track, such as the artist and genre. Typically used with MP3 files. |
Preferences: | Preferences... | none | Preferences let you change most of the default behaviors and settings of Audacity. On Mac, Preferences are in the Audacity Menu and the default shortcut is ⌘ + ,. |
For more "advanced" removal of audio
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SplitCut: | Split Cut | none | Same as Cut, but none of the audio data or labels to right of the selection are shifted. |
SplitDelete: | Split Delete | none | Same as Delete, but none of the audio data or labels to right of the selection are shifted. |
Silence: | Silence Audio | none | Replaces the currently selected audio with absolute silence. Does not affect label tracks. |
Trim: | Trim Audio | none | Deletes all audio but the selection. If there are other separate clips in the same track these are not removed or shifted unless trimming the entire length of a clip or clips. Does not affect label tracks. |
Create or remove separate clips in the audio track. A clip inside an audio track is a separate section of that track which has been split so that it can be manipulated somewhat independently of the other clips in the track.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
Split: | Split | none | Splits the current clip into two clips at the cursor point, or into three clips at the selection boundaries. |
SplitNew: | Split New | none | Does a Split Cut on the current selection in the current track, then creates a new track and pastes the selection into the new track. |
Join: | Join | none | If you select an area that overlaps one or more clips, they are all joined into one large clip. Regions in-between clips become silence. |
Disjoin: | Detach at Silences | none | In a selection region that includes absolute silences, creates individual non-silent clips between the regions of silence. The silence becomes blank space between the clips. |
These commands are to add and edit labels.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
EditLabels: | Edit Labels... | none | Brings up a dialog box showing all of your labels in a keyboard-accessible tabular view. Handy buttons in the dialog let you insert or delete a label, or import and export labels to a file. See Labels Editor for more details. |
AddLabel: | Add Label at Selection | none | Creates a new, empty label at the cursor or at the selection region. |
AddLabelPlaying: | Add Label at Playback Position | none | Creates a new, empty label at the current playback or recording position. |
PasteNewLabel: | Paste Text to New Label | none | Pastes the text on the Audacity clipboard at the cursor position in the currently selected label track. If there is no selection in the label track a point label is created. If a region is selected in the label track a region label is created. If no label track is selected one is created, and a new label is created. |
TypeToCreateLabel: | Type to Create a Label (on/off) | none | When a label track has the yellow focus border, if this option is on, just type to create a label. Otherwise you must create a label first. |
Labeled Audio commands apply standard Edit Menu commands to the audio of one or more regions that are labeled. The labels themselves are not affected.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
CutLabels: | Cut | none | Same as the Cut command, but operates on labeled audio regions. |
DeleteLabels: | Delete | none | Same as the Delete command, but operates on labeled audio regions. |
SplitCutLabels: | Split Cut | none | Same as the Split Cut command, but operates on labeled audio regions. |
SplitDeleteLabels: | Split Delete | none | Same as the Split Delete command, but operates on labeled audio regions. |
SilenceLabels: | Silence Audio | none | Same as the Silence Audio command, but operates on labeled audio regions. |
CopyLabels: | Copy | none | Same as the Copy command, but operates on labeled audio regions. |
SplitLabels: | Split | none | Same as the Split command, but operates on labeled audio regions or points. |
JoinLabels: | Join | none | Same as the Join command, but operates on labeled audio regions or points. You may need to select the audio and use Edit > Clip Boundaries > Join, to join all regions or points. |
DisjoinLabels: | Detach at Silences | none | Same as the Detach at Silences command, but operates on labeled audio regions. |
Select Menu has commands that enable you make selections of tracks or parts of the tracks in your project.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SelectAll: | All | none | Selects all of the audio in all of the tracks. |
SelectNone: | None | none | Deselects all of the audio in all of the tracks. |
SelCursorStoredCursor: | Cursor to Stored Cursor Position | none | Selects from the position of the cursor to the previously stored cursor position |
StoreCursorPosition: | Store Cursor Position | none | Stores the current cursor position for use in a later selection |
ZeroCross: | At Zero Crossings | none | Moves the edges of a selection region (or the cursor position) slightly so they are at a rising zero crossing point. |
Tracks
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SelAllTracks: | In All Tracks | none | Extends the current selection up and/or down into all tracks in the project. |
SelSyncLockTracks: | In All Sync-Locked Tracks | none | Extends the current selection up and/or down into all sync-locked tracks in the currently selected track group. |
For modifying, saving and restoring a selection.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SetLeftSelection: | Left at Playback Position | none | When Audacity is playing, recording or paused, sets the left boundary of a potential selection by moving the cursor to the current position of the green playback cursor (or red recording cursor). Otherwise, opens the "Set Left Selection Boundary" dialog for adjusting the time position of the left-hand selection boundary. If there is no selection, moving the time digits backwards creates a selection ending at the former cursor position, and moving the time digits forwards provides a way to move the cursor forwards to an exact point. |
SetRightSelection: | Right at Playback Position | none | When Audacity is playing, recording or paused, sets the right boundary of the selection, thus drawing the selection from the cursor position to the current position of the green playback cursor (or red recording cursor). Otherwise, opens the "Set Right Selection Boundary" dialog for adjusting the time position of the right-hand selection boundary. If there is no selection, moving the time digits forwards creates a selection starting at the former cursor position, and moving the time digits backwards provides a way to move the cursor backwards to an exact point. |
SelTrackStartToCursor: | Track Start to Cursor | none | Selects a region in the selected track(s) from the start of the track to the cursor position. |
SelCursorToTrackEnd: | Cursor to Track End | none | Selects a region in the selected track(s) from the cursor position to the end of the track. |
SelTrackStartToEnd: | Track Start to End | none | Selects a region in the selected track(s) from the start of the track to the end of the track. |
SelSave: | Store Selection | none | Stores the end points of a selection for later reuse. |
SelRestore: | Retrieve Selection | none | Retrieves the end points of a previously stored selection. |
For making a selection of a frequency range.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
ToggleSpectralSelection: | Toggle Spectral Selection | none | Changes between selecting a time range and selecting the last selected spectral selection in that time range. This command toggles the spectral selection even if not in Spectrogram view, but you must be in Spectrogram view to use the spectral selection in one of the Spectral edit effects. |
NextHigherPeakFrequency: | Next Higher Peak Frequency | none | When in Spectrogram view, snaps the center frequency to the next higher frequency peak, moving the spectral selection upwards. |
NextLowerPeakFrequency: | Next Lower Peak Frequency | none | When in Spectrogram views snaps the center frequency to the next lower frequency peak, moving the spectral selection downwards. |
For modifying a selection, taking account of clips.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SelPrevClipBoundaryToCursor: | Previous Clip Boundary to Cursor | none | Selects from the current cursor position back to the right-hand edge of the previous clip. |
SelCursorToNextClipBoundary: | Cursor to Next Clip Boundary | none | Selects from the current cursor position forward to the left-hand edge of the next clip. |
SelPrevClip: | Previous Clip | none | Moves the selection to the previous clip. |
SelNextClip: | Next Clip | none | Moves the selection to the next clip. |
View Menu has commands that determine the amount of detail you see in all the tracks in the project window. It also lets you show or hide Toolbars and some additional windows such as Undo History.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
UndoHistory: | History... | none | Brings up the History window which can then be left open while using Audacity normally. History lists all undoable actions performed in the current project, including importing. |
Karaoke: | Karaoke... | none | Brings up the Karaoke window, which displays the labels in a "bouncing ball" scrolling display |
MixerBoard: | Mixer Board... | none | Mixer Board is an alternative view to the audio tracks in the main tracks window. Analogous to a hardware mixer board, each audio track is displayed in a Track Strip. |
ShowExtraMenus: | Extra Menus (on/off) | none | Shows extra menus with many extra less-used commands. |
ShowClipping: | Show Clipping (on/off) | none | Option to show or not show audio that is too loud (in red) on the wave form. |
Zoom in/out on the horizontal axis. Show more detail or show a longer length of time.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
ZoomIn: | Zoom In | none | Zooms in on the horizontal axis of the audio displaying more detail over a shorter length of time. |
ZoomNormal: | Zoom Normal | none | Zooms to the default view which displays about one inch per second. |
ZoomOut: | Zoom Out | none | Zooms out displaying less detail over a greater length of time. |
ZoomSel: | Zoom to Selection | none | Zooms in or out so that the selected audio fills the width of the window. |
ZoomToggle: | Zoom Toggle | none | Changes the zoom back and forth between two preset levels. |
AdvancedVZoom: | Advanced Vertical Zooming | none | Enable for left-click gestures in the vertical scale to control zooming. |
Controls the sizes of tracks.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
FitInWindow: | Fit to Width | none | Zooms out until the entire project just fits in the window. |
FitV: | Fit to Height | none | Adjusts the height of all the tracks until they fit in the project window. |
CollapseAllTracks: | Collapse All Tracks | none | Collapses all tracks to take up the minimum amount of space. |
ExpandAllTracks: | Expand Collapsed Tracks | none | Expands all collapsed tracks to their original size before the last collapse. |
Move forward/backwards through the audio
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SkipSelStart: | Selection Start | none | When there is a selection, moves the cursor to the start of the selection and removes the selection. |
SkipSelEnd: | Selection End | none | When there is a selection, moves the cursor to the end of the selection and removes the selection. |
Toolbars can be used to determine which of the Audacity toolbars are displayed. By default all toolbars are shown except Spectral Selection and Scrub
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
ResetToolbars: | Reset Toolbars | none | Using this command positions all toolbars in default location and size as they were when Audacity was first installed |
ShowTransportTB: | Transport Toolbar | none | Controls playback and recording and skips to start or end of project when neither playing or recording |
ShowToolsTB: | Tools Toolbar | none | Chooses various tools for selection, volume adjustment, zooming and time-shifting of audio |
ShowRecordMeterTB: | Recording Meter Toolbar | none | Displays recording levels and toggles input monitoring when not recording |
ShowPlayMeterTB: | Playback Meter Toolbar | none | Displays playback levels |
ShowMixerTB: | Mixer Toolbar | none | Adjusts the recording and playback volumes of the devices currently selected in Device Toolbar |
ShowEditTB: | Edit Toolbar | none | Cut, copy, paste, trim audio, silence audio, undo, redo, zoom tools |
ShowTranscriptionTB: | Play-at-Speed Toolbar | none | Plays audio at a slower or faster speed than normal, affecting pitch |
ShowScrubbingTB: | Scrub Toolbar | none | Controls playback and recording and skips to start or end of project when neither playing or recording |
ShowDeviceTB: | Device Toolbar | none | Selects audio host, recording device, number of recording channels and playback device |
ShowSelectionTB: | Selection Toolbar | none | Controls the sample rate of the project, snapping to the selection format and adjusts cursor and region position by keyboard input |
ShowSpectralSelectionTB: | Spectral Selection Toolbar | none | Displays and lets you adjust the current spectral (frequency) selection without having to be in Spectrogram view |
Transport Menu commands let you play or stop, loop play, scrub play or record (including timed and sound activated recordings).
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
RescanDevices: | Rescan Audio Devices | none | Rescan for audio devices connected to your computer, and update the playback and recording dropdown menus in Device Toolbar |
These commands control playback in Audacity. You can Start, Stop or Pause playback of the audio in your project.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
PlayStop: | Play/Stop | none | Starts and stops playback or stops a recording (stopping does not change the restart position). Therefore using any play or record command after stopping with "Play/Stop" will start playback or recording from the same Timeline position it last started from. You can also assign separate shortcuts for Play and Stop. |
PlayStopSelect: | Play/Stop and Set Cursor | none | Starts playback like "Play/Stop", but stopping playback sets the restart position to the stop point. When stopped, this command is the same as "Play/Stop". When playing, this command stops playback and moves the cursor (or the start of the selection) to the position where playback stopped. |
Pause: | Pause | none | Temporarily pauses playing or recording without losing your place. |
These commands control recording in Audacity. You can Start, Stop or Pause recording in your project. You can either start a recording on your existing track or on a new track.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
Record1stChoice: | Record | none | Starts recording at the end of the currently selected track(s). |
Record2ndChoice: | Record New Track | none | Recording begins on a new track at either the current cursor location or at the beginning of the current selection. |
TimerRecord: | Timer Record... | none | Brings up the Timer Record dialog. |
PunchAndRoll: | Punch and Roll Record | none | Re-record over audio, with a pre-roll of audio that comes before. |
Pause: | Pause | none | Temporarily pauses playing or recording without losing your place. |
Scrubbing is the action of moving the mouse pointer right or left so as to adjust the position, speed or direction of playback, listening to the audio at the same time - a convenient way to quickly navigate the waveform to find a particular event of interest. Speed changes are made by rotating the mouse wheel while scrubbing.
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
Scrub: | Scrub | none | Scrubbing is the action of moving the mouse pointer right or left so as to adjust the position, speed or direction of playback, listening to the audio at the same time. |
Seek: | Seek | none | Seeking is similar to Scrubbing except that it is playback with skips, similar to using the seek button on a CD player. |
ToggleScrubRuler: | Scrub Ruler | none | Shows (or hides) the scrub ruler, which is just below the timeline. |
These commands let you move the cursor to the start or end of the selection, track or any adjacent Clip that you may have
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
CursSelStart: | Selection Start | none | Moves the left edge of the current selection to the center of the screen, without changing the zoom level. |
CursSelEnd: | Selection End | none | Moves the right edge of the current selection to the center of the screen, without changing the zoom level. |
CursTrackStart: | Track Start | none | Moves the cursor to the start of the selected track. |
CursTrackEnd: | Track End | none | Moves the cursor to the end of the selected track. |
CursPrevClipBoundary: | Previous Clip Boundary | none | Moves the cursor position back to the right-hand edge of the previous clip |
CursNextClipBoundary: | Next Clip Boundary | none | Moves the cursor position forward to the left-hand edge of the next clip |
CursProjectStart: | Project Start | none | Moves the cursor to the beginning of the project. |
CursProjectEnd: | Project End | none | Moves the cursor to the end of the project. |
This submenu lets you manage and set various options for transport (playing and recording) in Audacity
Scripting Id | Action | Parameters | Description |
|---|---|---|---|
SoundActivationLevel: | Sound Activation Level... | none | Sets the activation level above which Sound Activated Recording will record. |
SoundActivation: | Sound Activated Recording (on/off) | none | Toggles on and off the Sound Activated Recording option. |
PinnedHead: | Pinned Play/Record Head (on/off) | none | You can change Audacity to play and record with a fixed head pinned to the Timeline. You can adjust the position of the fixed head by dragging it |
Overdub: | Overdub (on/off) | none | Toggles on and off the Overdub option. |
SWPlaythrough: | Software Playthrough (on/off) | none | Toggles on and off the Software Playthrough option. |
Tracks Menu provides commands for creating and removing tracks, applying operations to selected tracks such as mixing, resampling or converting from stereo to mono, and lets you add or edit labels.
Scripting Id | Action |
|---|