Files & Directories
Open & Save
Of course, a script can open files as objects and save objects as files using the menu items of the
# open a sound file in the working directory Read from file: "recording.wav" # open a sound file in some other directory Read from file: "C:/Data/Recordings/recording.wav" # open a long sound file in some other directory Open long sound file: "C:/Data/Recordings/long_recording.wav" # save a sound object as WAV file (sound object must be selected!) Save as WAV file: "C:/Data/Tones/tone.wav" # save a TextGrid as text file (TextGrid object must be selected!) Save as text file: "C:/Data/Tones/tone.TextGrid"
You recognize the pattern: Copy the GUI command and provide a filename (including the path if necessary) as a string argument.
Notes on terminology:
- directory and folder are synonyms; I prefer directory
- the working directory is the home directory of the script, i.e. the directory containing the script file
- a path or path name identifies a directory in the file system
- a file extension is a filename suffix like .wav or .txt
- filename is the name of a file, usually including the file extension; if it is meant to exclude the extension, this is mentioned specifically (and/or called proper filename)
- I'll call the full specification of a file including its path and its name a file specification; a file specification is sufficient to uniquely identify a file in the file system
|file specification||(WIN:) C:/Data/Recordings/recording.wav
|filename w/o extension
(This terminology is only valid for this tutorial; I don't claim universal validity…)
Let the user choose
Using GUI commands and literal file specifications is straightforward but not really flexible, because the file specification is fixated in the script. If you rather want the script user to choose a file specification, use one of these two commands:
- to open files:
- to save files:
Both commands activate the standard file selection dialog of the operating system, where the user can navigate the file system and select a target directory and a filename for opening/saving. Alternatively, you can implement a form (see Input Forms) to ask for a file specification. But then, the user is obliged to key in the full file specification—that's not user-friendly and it is error-prone. With
chooseWriteFile$ the user is presented with a familiar interface, navigating with the mouse (or with keyboard shortcuts), which is less vulnerable and much more convenient!
chooseReadFile$ expects one string argument, which serves as window title of the file selection dialog, and it returns the chosen file specification. It doesn't open the file! The idea is, to assign the returned file specification to a variable so that you can take care of the file opening with an extra statement. An example:
# let the user choose a sound filename$ = chooseReadFile$: "Open a sound file" # open the selected file Read from file: filename$
The first statement opens a file selection dialog titled Open a sound file; here's the Mac version:
The chosen file specification is assigned to filename$ and the file is opened with the second statement. If the script user cancels file selection, filename$ is empty and the script would terminate with an error message. To avoid this and make the script more robust, the variable filename$ should be tested with a conditional, bypassing the Read statement if filename$ is empty. Here's an implementation to give you a taste of conditionals:
filename$ = chooseReadFile$: "Open a sound file" if filename$ <> "" Read from file: filename$ endif
A conditional is enclosed by
endif. The condition is given after the
if. In the example, I've used the
<> operator, which means unequal, to compare the variable with an empty string. So the first line of the conditional could be translated to if filename$ is unequal to an empty string, meaning if filename$ is not empty. The enclosed
Read statement is only executed if the condition is true, i.e. only if filename$ is not empty.
chooseWriteFile$ works similar, except that it expects an additional argument, specifying a filename suggestion. This statement:
filename$ = chooseWriteFile$: "Save as...", "mysound.wav"
opens a dialog, titled Save as… with the suggested filename mysound.wav in the input field:
The script user can navigate the file system to select a target directory and either confirm the suggested name or choose another. As soon as Save is clicked, the chosen file specification is assigned to the variable to be processed further. Again, I recommend a robust implementation using a conditional to handle the Cancel situation:
filename$ = chooseWriteFile$: "Save as...", "mysound.wav" if filename$ <> "" Save as WAV file: filename$ endif
Finally, if a script creates and names a collection of objects and needs to know only a directory, where to save the collection,
chooseDirectory$ can be used to display a directory selection dialog. The command expects one argument (the window title) and returns the selected path:
dir_name$ = chooseDirectory$: "Choose a directory"
The actual saving process is then usually implemented with the help of a loop.