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:
(alsa-record-raw-file "test.raw" 2 22050 16 False False Null pending)
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
|