View source for Manage Macros

{{ednote|'''Peter 06Mar18:''' 
{{advice|'''N.B.''' This page has multiple anchors in places.  This is to deal with the 2.3.0 functionality where Macros replaced Chains - but also to deal with older pre-existing links in the Forum which still will link to the chain anchors.}} }}
{{i18n}}
__NOTOC__
{{intro|'''''Manage Macros''''' allows you to edit, remove or rename existing Macros or add a new Macro and to apply Macros to you project or a set of files. Any [[Effect_Menu#built-in|built-in]], [[Effect Menu: LADSPA|LADSPA]], [[Effect Menu: LV2|LV2]], [[Effect Menu: Nyquist|Nyquist]], [[Effect Menu: VST|VST]] or [[Effect Menu: AudioUnit|Audio Unit]] (Mac) effect shown in the [[Effect Menu]] can be added to a Macro. You can also add plug-ins in any format that are shown in the [[Generate Menu|Generate]] or [[Analyze Menu|Analyze]] Menus (including [[Analyze Menu#vamp|Vamp]] analysis effects), the built-in [[Find Clipping]] analyzer and a number of export commands.<p>Macros may be applied to either the entirety of the current project or to a selection of files using the {{menu|Tools > [[Macros|Macros...]]}} command.</p><p>It is possible to use [[Noise Reduction]] in Macros but see [[Noise Reduction#macros|Noise Reduction Tips]] for how the Noise Profile is captured.</p> }}

:'''Accessed by:''' 
* The menu {{menu|[[Tools_Menu|Tools]] > Macros...}}, OR
* Using the {{button|Expand}} button in the [[Apply Macro|Macros Palette]] dialog.

:<span title="Manage Macros dialog showing Macro list (left) and command list for selected Macro (right)">[[Image:ManageMacros.png|link=]]</span>

{{note|For help with what the Macro effects do and how to set their parameters, see [[Effect Menu]] }}



<div id="chains"></div>
<div id="macros"></div>
==Select  Macro==
'''''Select Macro''''' contains a list of already defined Macros.  You can define the name of a new Macro and select which Macro is active. 

The left hand box in the dialog (labeled '''Select Macro''') contains a list of already defined Macros. Until you add a new Macro, it only has a single built-in "MP3 Conversion" Macro. You can:
*Use the {{Button|New}} button to create a new Macro
*Use left-click ''(or use the Up or Down keyboard arrows)'' to select the Macro you want to work on 
*Delete any user-added Macro with the {{Button|Remove}} button
*Rename any user-added Macro with the {{Button|Rename}} button
{{note|The Remove and Rename buttons are grayed out when the Macros that ship with Audacity are selected.}}


*{{button|New}}: Add a new Macro to the list.
*{{button|Remove}}: Remove the selected Macro from the list.
*{{button|Rename...}}: Rename the selected Macro.
*{{button|Import...}}: not currently active
*{{button|Export}}: not currently active


<div id="chain"></div>
<div id="macro"></div>
==Macro==
'''''Macro''''' lists the sequence of commands in order of first to last (End) for the Macro selected in the "Select Macros" box to left. 

*The Macro can include a number of common Audacity functions and effects to be executed in any order you specify.
*To create an audio file as part of the Macro process you must include an "Export" command (such as [[#export|'''Export as WAV''']]).  
*In many cases the parameters for each command in the Macro can be specified within the '''Manage Macros''' dialog. 

You can: 
*Add or remove commands for the selected Macro
*Change the order in which the commands execute in the Macro 
*Edit the parameters for some effects in the Macro  


===Command===
*{{button|Insert}}: Insert a new command into the list
*{{button|Edit}}: Edit the parameters of the currently selected command
*{{button|Delete}}: Delete the currently selected command in the list
*{{button|Move Up}}: Move the currently selected command up in the list
*{{button|Move Down}}: Move the currently selected command down in the list
*{{button|Defaults}}: This button is only active when the Audacity supplied Macros are selected in the "Select Macros" list on the left, and will reset the Macro to its default values.


<div id="edit"></div>
=== Editing an existing command === 
To edit an existing command double-click it, or use the '''Up''' or '''Down''' keyboard arrow to select it then press {{key|Space}}.  The parameter settings dialog for that command will be displayed.

<div id="insert"></div>
=== Inserting a new command===
To insert a new command in a Macro, left-click or use the '''Up''' or '''Down''' keyboard arrow to select an existing command; the new command to be inserted will be placed above this selected command. Then press {{button|Insert}}. 
*The "Select Command" dialog appears, listing all the available commands. Double-click a command from the list to insert it in the "Command" box, as shown in the image below after inserting "Normalize". 
:Alternatively, use the '''Up''' or '''Down''' keyboard arrow to select the command, then press {{key|Space}}. 
:<span title="Edit Macros 'Select Command' dialog showing default commands, with 'Normalize' selected and inserted">[[Image:SelectCommand.png|link=]]</span>

{{hint| &nbsp;
* The full list of all commands, with descriptions, is available at [[Scripting Reference]].
* Some 'scriptable' commands are particularly useful for Macros.  See these pages for details:
** [[Extra Menu: Scriptables I]] - most commonly useful scriptables. 
** [[Extra Menu: Scriptables II]] - less commonly useful scripatables, but also including '''Select''' and '''Set Track''', which combine functionality of several scriptables.
&nbsp;
}}


*If the command has editable parameters, the {{button|Edit Parameters}} button will be active. Clicking this button will bring up the dialog box for the effect where you can set the parameters as if you were applying the standalone effect.
*If you have previously created [[Manage presets|user presets]] for an effect you can use the {{button|Use Preset}} to select one for use with that effect in the Macro.
*Choose {{button|OK}} in the effect dialog to accept the parameters you entered, or {{button|Cancel}} to revert to the default parameters.
*Choose {{button|OK}} in the "Select Command" dialog to add the command to the Macro.
{{tip|1=
Macros will work on pre-existing selections you make in your project prior to running the Macro.  But the selection can be over-ridden by your Macro itself as there are Macro commands available to effect selections in the audio.  In particular '''All(Select All)''' will select the entire project and '''Select''' which is parameterizable ''(see the provided '''Fade Ends''' Macro for an example where the first and last one seconds of the audio are selected for the fades)''.
*If you want to select all tracks, and maintaining your current time selection, use "'''Select: First=0 Last=100'''".  It won't waste time twiddling its thumbs on the tracks that are not there. }}

<div id="export"></div>

===Export commands===
* There are four basic export commands available: '''Export as WAV''', '''Export as MP3''', '''Export as FLAC''' and '''Export as Ogg'''.
**See [[Apply Macro#apply|Apply Macro]] for details of naming and location of exported files.
{{advice|'''Parameters for export formats cannot be set in "Manage Macros".''' To configure export parameters for the Macro, click {{menuadvice|File > Export > [[File Menu: Export#exportaudio|Export Audio...]]}} to access the [[File Export Dialog|Export Audio Dialog]], click {{button|Options}}, set the parameters, press {{button|OK}} then {{button|Cancel}} the export. An [[Audio Tracks|audio track]] must be on screen in order to open the Export Audio Dialog.}}

===Special Export command===
*[[Extra Menu: Scriptables II#export2|'''Export2''']]:  there is also a special Export command [[Extra Menu: Scriptables II#export2|'''Export2''']] which enables you to export to a specific target file and format. When using '''Export2''' you have to give the '''''full''''' file name (including path and filename extension). <p>Note carefully that the filename is not dynamically changeable when running the Macro, once set in the Export2 parameters, so you may wish to create several Macros the Export2 each targeting different file locations, names and filetype.</p>
{{ednote|'''Peter 09Jan19:'''

Example:
"C:\Users\<username>\Desktop\my file.flac" (this works)

Not: C:\Users\<username>\Desktop\my file.flac (the file name is not quoted)

Not: "my file.flac" (no path given)

Not: "C:\Users\<username>\Desktop\myfile" (no file extension)

And for clarity of Steve's instructions here for others who may read this and want to use Export 2

The quote marks around the file pathing are supplied by Audacity once the Export2 command has been edited in setting up or edoting the Macro

When entering the pathing data in the edit parameters dialog for the command you don't put the quote marks i.e.
C:\Users\<username>\Desktop\my file.flac 
}}

===Deprecated Export commands===
The following two commands are now deprecated and may well be removed in future versions of Audacity.  They were  part of "'''CleanSpeech'''" ''(which has long been removed from Audacity)''.
* The '''Export as MP3 56k before''' and '''Export as MP3 56k after''' commands can be used respectively to export "before" and "after" '''''[[Glossary#mp3|MP3]]''''' files at 56&nbsp;kbps '''''[[Glossary#bit_rate|bit rate]]'''''  at any point in the Macro processing. This allows you to compare the result of one or more effects, or provide files for different purposes with and without a particular effect. 
** The name of the MP3 exported by the "Export as MP3 56k before" command is prefixed by "MasterBefore_" followed by the date and time. The name of the MP3 exported by the "Export as MP3 56k after" command is prefixed by "MasterAfter_" followed by the date and time. 


<div id="shrink"></div>

==Shrink - reduced Macros Palette dialog==
Use the {{button|Shrink}} button to show a reduced [[Apply Macro|Macros Palette]] dialog with a simple list of the existing Macros, enabling you to apply the Macros but not edit them. 

This smaller version is useful for presets. It stays open after applying a macro, so it is a palette of custom functions, and you can pick another and apply that. 

Using the {{button|Expand}} button on this reduced dialog will return you to the full [[#manage|Manage Macros]] dialog.

For more details see the [[Apply Macro|Macros Palette]] page.



<div id="apply"></div>
==Apply Macro to==
'''Apply Macro to''' enables you to make a Macro operate on either your current open project, or a set of selected external files.

See '''[[Apply Macro#apply|Macros Palette]]''' for details of how these two buttons operate.


==Cancel to exit the dialog==
The dialog will remain open on the screen, but allowing you to perform other Audacity functions.

To dismiss the dialog simply click on the {{button|Cancel}} button



<div id="share"></div>

==Sharing a Macro==

Each Macro is automatically saved as a separate text file with TXT '''''[[Glossary#extension|extension]]''''' in the "Macros" folder in Audacity's [[Preferences#stored|folder for application data]]. This allows you  to copy a Macro and send it to another user, or to copy another user's Macro into this folder so as to add to your own list of Macros. An updated list of Macros will be available next time you open "Manage Macros" in Audacity.



<div id="examples"></div>

== [[Macros Examples]] ==
See the [[Macros Examples]] page for examples of using Macros.


<div id="error"></div>
==Batch command not recognized error==
{{ednote|'''Peter 21Jan18:''' [[ToDo-2]]add a link to here from FAQ Errors> }}
{{note|1=
This error may sometimes occur for one or more commands in a Macro when updating from a previous Audacity version. The error may also occur if users sharing Macro have different Audacity versions or different versions of the plug-ins used in the Macro. The error will occur if:
* any command in the Macro uses a different text format than that recognized by the version of Audacity in use 
* any plug-ins listed in the Macro are missing, in an incorrect location or are incompatible with the version of Audacity in use. 
To resolve these errors, ensure you have compatible versions of all required plug-ins and that the plug-ins are [[FAQ:Installation and Plug-Ins#plug-ins|installed correctly]]. If necessary, use the "Manage Macros" dialog to delete the command that fails then insert a replacement command for the same effect from the "Select Command" dialog.
}}



[[Macros|'''<'''&nbsp; Back to: Macros]]