Scripting 6.1. Arguments to the script

You can cause a Praat script to prompt for arguments. The file `playSine.praat` may contain the following:

`form: “Play a sine wave”
` `positive: “Sine frequency (Hz)”, “377.0”
` `positive: “Gain (0..1)\", “0.3 (= not too loud)”
` `endform
` `Create Sound as pure tone: “sine” + string$ (sine_frequency),
` `... 1, 0, 1, 44100, sine_frequency, gain, 0.01, 0.01
` `Play
` `Remove
`

When running this script, the interpreter puts a settings window (form) on your screen, entitled “Play a sine wave”, with two fields, titled “Sine frequency (Hz)” and “Gain”, that have been provided with the standard values “377.0” and “0.3 (= not too loud)”, which you can change before clicking OK.

Inside the script, the field names can be accessed as variables: these have underscores instead of spaces, and the parentheses (Hz) have been chopped off. Note that the first letter of these variables is converted to lower case, so that you can assign to them in your script.

Inside the script, the value “0.3 (= not too loud)” will be known as 0.3, because this is a numeric field.

You can use the following field types in your forms:

`real`: `variable$`, `initialValue$`
  for real numbers.
`positive`: `variable$`, `initialValue$`
  for positive real numbers: the form issues an error message if the number that you enter is negative or zero (further on in the script, you can freely change it to any real number, including negatives ones such as -1.5, or zero).
`integer`: `variable$`, `initialValue$`
  for whole numbers: the form reads the number as an integer (further on in the script, you can give it any real value, e.g. 3.14).
`natural`: `variable$`, `initialValue$`
  for positive whole numbers: the form issues an error message if the number that you enter is negative or zero (further on in the script, you can give it any real value).
`word`: `variable$`, `initialValue$`
  for a string without spaces: the form only reads up to the first space (“oh yes” becomes “oh”; further on in the script, you can give the string any value, perhaps with spaces in it).
`sentence`: `variable$`, `initialValue$`
  for any short string.
`text`: `variable$`, `initialValue$`
  for any possibly long string (the variable name will show up above the field).
`text`: `numberOfLines`, `variable$`, `initialValue$`
  for any possibly very long string (multiple lines), `numberOfLines` can be between 1 and 33.
`boolean`: `variable$`, `initialValue`
  a check box will be shown; the initial value is 1 (on) or 0 (off).
`boolean`: `variable$`, `initialValue$`
  a check box will be shown; to switch it on, set the initial value to `“on”`, `“yes”`, `“ON”`, `“YES”`, `“On”` or `“Yes”`; to switch it off, set it to `“off”`, `“no”`, `“OFF”`, `“NO”`, `“Off”` or `“No”`.
`choice`: `variable$`, `initialValue`
  a multiple-choice box (or “radio box”) will be shown; the value is 1 or higher. This is followed by a series of:
`option`: `text$`
  an option button in a multiple-choice box (see example below).
`optionmenu`: `variable$`, `initialValue`
  a multiple-choice menu header will be shown; the value is 1 or higher. Just as `choice`, this is followed by:
`option`: `text$`
  an option in a multiple-choice menu (see example below).
`comment`: `text$`
  a line with any text.
`infile`: `variable$`, `initialValue$`
  for a full path to an existing file, usually for reading.
`outfile`: `variable$`, `initialValue$`
  for a full path to a new file, usually for saving.
`folder`: `variable$`, `initialValue$`
  for a full path to a folder.
`realvector`: `variable$`, `format$`, `initialValue$`
  for a vector with real values. The format can be `“(whitespace-separated)”` or `“(formula)”`; the initial value should then probably be something like `“10 -9 80”` or `“{ 10, -9, 80 }”`, respectively.
`realvector`: `numberOfLines`, `variable$`, `format$`, `initialValue$`
  use this if you want a field with less or more than the standard 7 lines.

`positivevector`: `variable$`, `format$`, `initialValue$`

`positivevector`: `numberOfLines`, `variable$`, `format$`, `initialValue$`
  use either of these if you want to check that all initial elements are positive real numbers.

`integervector`: `variable$`, `format$`, `initialValue$`

`integervector`: `numberOfLines`, variable , format`` , initialValue``
  use either of these if you want to check that all initial elements are whole numbers.

`naturalvector`: `variable$`, `format$`, `initialValue$`

`naturalvector`: `numberOfLines`, `variable$`, `format$`, `initialValue$`
  use either of these if you want to check that all initial elements are positive whole numbers.

Inside the script, strings are known as string variables, numbers as numeric variables. Consider the following form:

`form: “Sink it”
` `sentence: “Name of the ship”, “Titanic”
` `real: “Distance to the iceberg (m)”, “500.0”
` `natural: “Number of people”, “1800”
` `natural: “Number of boats”, “10”
` `endform
`

In the script following this form, the variables will be known as `name_of_the_ship$`, `distance_to_the_iceberg`, `number_of_people`, and `number_of_boats`.

The variable associated with a radio box will get a numeric as well as a string value:

`form: “Fill attributes”
` `comment: “Choose any colour and texture for your paintings”
` `choice: “Colour”, 5
` `option: “Dark red”
` `option: “Sea green”
` `option: “Navy blue”
` `option: “Canary yellow”
` `option: “Black”
` `option: “White”
` `choice: \"Texture”, 1
` `option: “Smooth”
` `option: “Rough”
` `option: “With holes”
` `endform
` `writeInfoLine: “You chose the colour ”, colour$, “ and the texture ”, texture$, “.”
`

This shows two multiple-choice boxes. In the Colour box, the fifth button (Black) is the standard value here. If you click “Navy blue” and then OK, the variable `colour` will have the value 3, and the variable `colour$` will have the value “Navy blue”. So you can test the value of the Colour box in either of the following ways:

`if colour = 4
`

or

`if colour$ = “Canary yellow\"
`

The field type `optionmenu` is completely analogous to `choice`, but uses up much less space on the screen:

`form: “Fill attributes”
` `comment: “Choose any colour and texture for your paintings”
` `optionmenu: “Colour”, 5
` `option: “Dark red”
` `option: “Sea green”
` `option: “Navy blue”
` `option: “Canary yellow”
` `option: “Black”
` `option: “White”
` `optionmenu: “Texture”, 1
` `option: “Smooth”
` `option: “Rough”
` `option: “With holes”
` `endform
` `writeInfoLine: “You chose the colour ”, colour$, “ and the texture ”, texture$, “.”
`

For the vector types `realvector`, `positivevector`, `integervector` and `naturalvector` you have to specify an initial format, which will be shown to the user:

`form: “Interesting times”
` `comment: “List the times that you are interested in”
` `realvector: “Fixed times (s)”, “(whitespace-separated)”, “0.5 1.7 2.8”
` `realvector: “Random times (s)”, “(formula)”, “randomUniform# (5, 0.0, 1.0)”
` `endform
` `writeInfoLine: “Your fixed times are ”, fixed_times#, “ and your random times are ”, random_times#, “.”
`

Clicking OK without editing the two fields may print

`Your fixed times are 0.5 1.7 2.8 and your random times are 0.754675 0.121393653 0.39856 0.8376572 0.387537.
`

The field types infile, outfile and folder always yield a full path. Consider the script `playFile.praat`, which contains the following:

`form: “Play file”
` `infile: “File to play”, “hello.wav”
` `endform
` `writeInfoLine: “You chose the file ”, file_to_play$, “.”
` `Read from file: file_to_play$
` `Play
` `Remove
`

If you just click OK and `playFile.praat` is in the folder `/Users/miep/research/usefulScripts`, then this will print

`You chose the file /Users/miep/research/usefulScripts/hello.wav.
`

into the Info window, and play the sound in that file.

You can combine two short fields into one by using `left` and `right`:

`form: “Get duration”
` `natural: “left Year range”, “1940”
` `natural: “right Year range”, “1945”
` `endform
` `duration = right_Year_range - left_Year_range
` `writeInfoLine: “The duration is ”, duration, “ years.”
`

The interpreter will only show the single text “Year range”, followed by two small text fields.

## Calling a script from another script

Scripts can be nested: the file `doremi.praat` may contain the following:

`runScript: “playSine.praat”, 550, 0.9
` `runScript: “playSine.praat”, 615, 0.9
` `runScript: “playSine.praat”, 687, 0.9
`

With `runScript`, Praat will not display a form window, but simply execute the script with the two arguments that you supply on the same line (e.g. 550 and 0.9).

Values for `choice` must be passed as strings:

`runScript: “fill attributes.praat”, “Navy blue”, “With holes”
`

Values for vectors can be passed either as a vector expression or as a white-space separated string, independently of the initial format:

`runScript: “interesting times.praat”, { 0.3, 0.5, 0.7, 2.0 }, “18000 0.3”
`

You can pass values for boolean either as the quoted strings “yes” and “no” (or their variants) or as the unquoted numbers 1 and 0.

In `runScript`, the path to the external script, as well as the paths to `infile`, `outfile` and `folder` parameters are taken relative to the folder of the current script. For instance, suppose that the current script is `/Users/miep/research/project19/analyse.praat` and contains:

`runScript: “../usefulScripts/playFile.praat”, “sounds/sound3.wav”
`

then running the current script will run the above-mentioned script `/Users/miep/research/usefulScripts/playFile.praat`, which will play the file `/Users/miep/research/project19/sounds/sound3.wav`.

### Links to this page

- `runScript`
- Scripting
- Scripting 6. Communication outside the script
- Scripting 6.6. Controlling the user
- Scripting 6.9. Calling from the command line