Scripting 8.1. The sendpraat subroutine

Sendpraat can be a subroutine for sending messages to a running Praat program.

## C syntax

`sendpraat7 (long timeOut, int fullTrust, const char *program, char *text);
`

## Arguments

`timeOut` (MacOS and Linux only)
  the number of seconds that `sendpraat` will wait for an answer before writing an error message. A `timeOut` of 0 means that the message will be sent asynchronously, i.e., that sendpraat will return immediately without issuing any error message.
`fullTrust`
  a boolean (0 or 1) that determines whether the script should be allowed to save files and call system commands (1), or not (0).
`program`
  the name of a running program that uses the Praat shell, e.g. "Praat". The first letter may be specified as lower or upper case; it will be converted to upper case for Windows or MacOS and to lower case for Linux.
`text`
  the script text to be sent. Sendpraat may alter this text!

## Example 1: killing a program

`char message [100], *errorMessage;
` `strcpy (message, "Quit");
` `errorMessage = sendpraat7 (0, 0, "praat", message);
` `if (errorMessage) fprintf (stderr, "%s", errorMessage);
`

This causes the program Praat to quit (gracefully), because Quit is a fixed command in one of the menus of that program. On MacOS and Linux, sendpraat returns immediately; on Windows, the timeOut argument is ignored. The return value errorMessage is a statically allocated string internal to sendpraat, and is overwritten by the next call to sendpraat.

## Example 2: playing a sound file in reverse

Suppose you have a sound file whose name is in the variable `fileName`, and you want the program Praat, which can play sounds, to play this sound backwards.

`char message [1000], *errorMessage;
` `snprintf (message,1000, "Read from file: ~%s\nPlay reverse\nRemove", fileName);
` `errorMessage = sendpraat7 (3000, 0, "praat", message);
`

This will work because Play reverse is an action command that becomes available in the dynamic menu when a Sound is selected. On Linux, sendpraat will allow Praat at most 3000 seconds to perform this.

## Example 3: executing a large script file

Sometimes, it may be unpractical to send a large script directly to sendpraat. Fortunately, the receiving program knows runScript:

`char message [100], *errorMessage;
` `strcpy (message, "runScript: \"doAll.praat\", 20");
` `errorMessage = sendpraat7 (0, 1, "praat", message);
`

This causes the program Praat to run the script `doAll.praat` with an argument of "20".

## How to download

You can download the source code of the sendpraat subroutine via https://praat.org/sendpraat.html or from https://www.fon.hum.uva.nl/praat/sendpraat.html.

## Instead

Instead of using `sendpraat`, you can also just take the following simple steps in your program:

  1. on Linux, write the Praat script that you want to run, and save it as `~/.config/Message.txt`;
  2. get Praat's process id from `~/.config/pid`;
  3. if Praat's process id is e.g. 1178, send it a SIGUSR1 signal: `kill -USR1 1178`

If the first line of your script is the comment “`# 999`”, where 999 stands for the process id of your program, Praat will send your program a SIGUSR2 signal back when it finishes handling the script. If you do not want to receive such a message (if your program has no handler for it, the SIGUSR2 signal will kill your program), then do not include such a line.

If the second line of your script is “`# --FULL-TRUST`”

## See also

To start a program from the command line instead and sending it a message, you would not use sendpraat, but instead run the program with a script file as an argument. See Scripting 6.9. Calling from the command line.

### Links to this page

- Scripting
- Scripting 8. Controlling Praat from another program
- Scripting 8.2. The sendpraat program