Audio utilities Isis software documentation

Audio utilities

This library defines several helpful objects and routines for handling audio in Isis. The utilities described here operate on top of the low-level audio interface on your machine, which varies depending on your operating system. For Linux, the ALSA library handles low-level audio details.

Please note that on most systems, in order for any audio to be heard, audio channels must be unmuted and set to an appropriate volume using an audio mixer program such as amixer, alsamixer, or gmix. Isis does not currently interface with mixers.

Simple playback and recording

(audio-play-raw-file filename chans rate bits unsigned bigendian) # play audio from a named file (audio-play-raw-port port chans rate bits unsigned bigendian secs) # play audio from a port (audio-record-raw-file filename chans rate bits unsigned bigendian secs stopfunc) # record audio and save it in a named file (audio-record-raw-port port chans rate bits unsigned bigendian secs stopfunc) # record audio and send it on a port These functions play and record raw PCM audio either to a disk file filename or to any Isis port port. All four functions block until the desired audio has been completely played or recorded. Each returns True if successful, Null if not. The arguments in each mean the same thing:

chans the number of channels of audio (1 or 2)

rate the sampling rate (usually 8000, 11025, 22050, or 44100)

bits number of bits per sample (8 or 16)

unsigned boolean flag, True if samples are in unsigned format (typically True for 8-bit audio, False for 16-bit audio)

bigendian boolean flag, True if samples are in big-endian format (typically False for PCs, True for Macintosh)

secs For playback: number of seconds to play, or if Null, audio will be played until the end of the file or until the port is closed.
For recording: number of seconds to record, or if Null, audio will be recorded continuously until the stopfunc is triggered.
Fractional values are allowed.

stopfunc a function to trigger recording to stop, or pass Null if no trigger is needed. The recording routines will call this function several times per second, and as long as it returns False audio recording will continue. When it returns True recording will stop and the function will return. Useful if you don't know for how long you will want to record audio.

For example, you can use pending as the stopfunc to record audio until the user presses return on the keyboard:

Audio player object

The audio player object provides an easy way to play audio in parallel with other activities. Each audio player can play one sound at a time, but you may create as many audio players as you need, up to the maximum number of simultaneous audio streams supported by your sound card.

Creating audio players

(set aplayer (new-audio-player chans rate bits unsigned bigendian)) new-audio-player creates a new audio player object for playing audio of the specified characteristics. See the table above for an explanation of the 5 arguments. It returns a procedure that you will invoke later to control the audio player. For best efficiency, all the audio players needed for a particular application should be created at the beginning of the program rather than in an "on-demand" fashion.

Setting the audio source

(aplayer [ap-file filename]) # play from named file (aplayer [ap-port port]) # play from port (aplayer [ap-seek secs]) # seek to a point in file The ap-file and ap-port commands set the playback source either to a named file or to an Isis port. ap-seek seeks to a particular starting position in the audio file (if possible), specified in seconds (fractional values are allowed).

Controlling playback

(aplayer [ap-play { secs } ]) (aplayer [ap-process]) (aplayer [ap-stop]) The ap-play command initiates audio playback. You may specify an optional number of seconds for which to play, otherwise audio will play until the end of the file or until the port is closed. However, audio will not continue to play unless the ap-process command is invoked at least once per second. Ideally you should call ap-process exactly once each time through your program's main loop. If it is not called often enough, the playback may lose continuity. The ap-stop command stops the audio playback, and it may be resumed at the same point with a later ap-play command.

Closing down

(aplayer [ap-quit]) The ap-quit command closes down the movie player and releases any resources allocated to it.

Example

This example program is an interactive audio playback application where the user can start and stop audio playback and set the playback position using simple keyboard commands. See if you can change the program to control the audio player via a different interface. Try also to add more audio players and play more than one sound at the same time.

Handling WAVE format audio

Simple playback

(audio-play-wave-file filename) This function plays a sound recorded in the WAVE file format. It expects only the name of the file, and it will block until the audio has been completely played. Returns True if successful, Null if not.

Conversion

(audio-wave-to-raw infilename outfilename) (audio-raw-to-wave infilename outfilename chans rate bits) These functions convert audio files between WAVE format and raw PCM format. Each expects an input and output filename. audio-raw-to-wave expects 3 more arguments describing the audio stored in the raw sound file. These arguments mean the same thing as those described in the table above. Both functions return True if successful, and Null if not.

WAVE headers

(audio-read-wave-header port) # returns [ chans rate bits datasize offset ] (audio-write-wave-header port chans rate bits datasize) These functions read and write headers for the WAVE file format. Pass the Isis port that is open for reading or writing of the WAVE file.

The read function returns a list of 5 items that includes the number of audio channels, sampling rate, bits per sample, size of audio in bytes, and the offset of the audio from the start of the file in bytes. This offset may be used to seek to the start of the audio segment of the file. If unsuccessful, the read function returns Null.

The write function expects the same information (except for the offset) and writes the WAVE header to the port. The normal procedure is to create a new file, write the WAVE header, and then write datasize bytes of raw PCM audio to the file before closing it.

Other utilities

(audio-calc-size secs chans rate bits) This function calculates and returns the exact size in bytes of the specified number of seconds of audio with the given characteristics (number of channels, sampling rate, bits per sample). In the case of audio samples larger than a single byte, the routine properly rounds its result down to the nearest audio frame boundary.

Requirements:

Scripts: (load "audio-utilities.isis")
Other: An Isis compatible audio library should be installed and functional

`chans`	the number of channels of audio (1 or 2)
`rate`	the sampling rate (usually 8000, 11025, 22050, or 44100)
`bits`	number of bits per sample (8 or 16)
`unsigned`	boolean flag, `True` if samples are in unsigned format (typically `True` for 8-bit audio, `False` for 16-bit audio)
`bigendian`	boolean flag, `True` if samples are in big-endian format (typically `False` for PCs, `True` for Macintosh)
`secs`	For playback: number of seconds to play, or if `Null`, audio will be played until the end of the file or until the port is closed. For recording: number of seconds to record, or if `Null`, audio will be recorded continuously until the `stopfunc` is triggered. Fractional values are allowed.
`stopfunc`	a function to trigger recording to stop, or pass `Null` if no trigger is needed. The recording routines will call this function several times per second, and as long as it returns `False` audio recording will continue. When it returns `True` recording will stop and the function will return. Useful if you don't know for how long you will want to record audio.

Scripts:	`(load "audio-utilities.isis")`
Other:	An Isis compatible audio library should be installed and functional