Session 1
Script Editor & Command History

Command History

Praat constantly records your GUI actions, i.e. you don't have to start recording - it's always on. This mechanism is called command history. Think of it as a list of instructions (GUI actions) in the order you invoked them. When you open Praat the history is empty, but when you start clicking around each action (with some rare exceptions) is recorded and generates a new list item in the history. This happens hidden in the background and until you start Praat scripting you wouldn't notice anything about the command history.

If you want to make use of the history you need to open the Praat script editor. Two commands in the editor's Edit menu are relevant for managing the history: Paste history and Clear history. The Paste command generates a list of statements (= a Praat script) reflecting everything you've done so far since starting Praat. If you start Praat in the morning and paste the history after several hours of hard phonetic work the resulting list is pretty huge. Usually that's not what you want.

Macro recording workflow

Instead, what you usually want is to start recording with a specific action and to end recording after a distinct sequence of actions. To achieve this you need the Clear history command which simply clears the command history of everything which was recorded so far. After invoking Clear history the command history is empty, like when you start up Praat. Therefore, the recommended workflow for macro recording is as follows:

1. open the script editor
2. clear history
3. perform GUI actions (you can close or minimize the script editor meanwhile - or just ignore it)
4. back in the script editor paste history
5. continue with 2.

Here's an example. Consider we want a macro that creates a tone, plays it, and does a pitch analysis. First, we open the script editor (New Praat script) and clear the history (Edit > Clear history). Then we switch to Praat Objects and create a tone (New > Sound > Create Sound as pure tone...) with standard settings. We click the Play button to listen to the newly created tone, then we run a pitch analysis (Analyse periodicity > To Pitch...) with standard settings. Finally, we return to the script editor and paste the history (Edit > Paste history). That's it. Praat translated the GUI actions into syntactically structured statements, one statement per line (we'll have a more detailed look at statements and their syntax in the next session). The newly created macro/script should look like this:

Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
To Pitch: 0, 75, 600

If it looks like the code block below instead, you are using an old Praat version (5.3.43 or older) and should update (cf. Introduction and the hints on old functions in the manual):

Create Sound as pure tone... tone 1 0 0.4 44100 440 0.2 0.01 0.01 
Play
To Pitch... 0 75 600

If it looks like the following code block, you have a Praat version between 5.3.44 and 5.3.62, generating an intermediate syntax, and you should update as well.

do ("Create Sound as pure tone...", "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01)
do ("Play")
do ("To Pitch...", 0, 75, 600)

Let's try and run the script: click Run in the Run menu of the script editor. As expected, a new tone is created, played, and pitch processed. You can run the script as often as you like (and consequently populate the list of objects with numerous Sound and Pitch objects) and you can save it for later use (CTRL-s / CMD-s).

If you want to extent the macro simply repeat the workflow: clear history - perform actions - paste history. For example, if you want to listen to the pitch analysis as a hum, clear the history, activate Praat Objects (make sure that a pitch object is selected) and play the hum (Sound > Hum). Back in the script editor place the cursor in the last (empty) line, paste the history, and run the script.

Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
To Pitch: 0, 75, 600
Hum

Limitations of command history

That worked. Now try this: Clear the history, switch to Praat Objects (make sure that a pitch object is selected), and print the maximum pitch to the Praat Info window (Query > Get maximum...). After closing Praat Info, switch to the script editor, paste the history (last line), and run the script. The script looks fine with the new statement added but it behaves not as expected, because it doesn't produce the desired Praat Info output. (In newer Praat versions query commands behave like expected, i.e. the query result is written to Praat Info. I don't know exactly when that changed.)

Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
To Pitch: 0, 75, 600
Hum
Get maximum: 0, 0, "Hertz", "Parabolic"

There's nothing wrong with the script (otherwise an error message would appear), it's just that query commands behave different in scripts than in the GUI. In the GUI, query commands are executed and the result is displayed in Praat Info; in scripts, the query is executed and that's it. The Praat scripting engine assumes that you want to handle the query result inside the script, for example in a formula or as a setting (if that is what you want you need to assign the result to a variable, cf. Variables). If writing the result to Praat Info is actually what you intended, you must tell the script to do so explicitly (cf. Generating Output).

That's the first (minor) trouble when working with command history: some commands behave different in scripts. Fortunately, as far as I know, only query commands are concerned. But there's more (and worse) trouble waiting. Imagine you want your script to open a newly created tone in a sound editor window. First, let's delete the last three lines of the existing script:

Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play

Run the shortened script, clear the history, switch to Praat Objects, and click View & Edit to open the sound editor. Now zoom in (View > Zoom in) several times for a detailed view of the sinus wave. Switch back to the script editor and paste the history:

Create Sound as pure tone: "tone", 1, 0, 0.4, 44100, 440, 0.2, 0.01, 0.01
Play
Edit
Zoom in
Zoom in
Zoom in
Zoom in

As you see I've clicked Zoom in four times and each click was recorded in a separate line; if you clicked only two times, of course there will be only two lines in your script. (Note that command history translates the GUI command View & Edit to the script command Edit. That's for historical reasons. If you like, you can change the command to View & Edit by hand.) Ok, the script looks as expected, let's run it. The first three statements are executed—a tone is created, replayed and opened in a sound editor. Then the script exits with an error message:

What happened? While recording the macro we inadvertently switched the command environment, from Praat Objects (Create Sound, Play, and Edit are Praat Objects commands, also called shell commands) to the sound editor (Zoom in is an editor command). Unfortunately, this environment change is not recorded, nonetheless it's important for the script to know about. With only one sound editor open this seems gratuitous, but with two or more editors open the script obviously needs to know which editor you want to zoom in. Consequently, we must indicate environment changes manually in our scripts. You'll learn how to do this in the session on scripting environments.