Snack sound extension commands v1.4
(Last updated January 26, 1999)
Manual for version
1.3
Manual for version
1.2
The command package require snack gives you access to all commands
described below. The command package require sound only gives you
the sound and audio commands. No graphics because it is an
extension to Tcl only.
-
audio
-
initSnack
-
sound
-
spectrogram (deprecated)
-
spectrogram canvas item
-
spectrum section canvas item
-
waveform canvas item
NAME
audio - Get/set properties of the audio device
SYNOPSIS
audio property ?arg?
DESCRIPTION
The audio command is used to get and set properties of the audio device
such as current input/output jack, supported ports, sample encoding formats, sample
frequencies, and gain.
audio formats
Returns a list of supported sample encoding formats.
audio frequencies
Returns a list of supported sample frequencies.
audio input ?jack?
Gets/sets the current input jack.
audio inputs
Returns a list of available input ports.
audio output ?jack?
Gets/sets the current output jack.
audio outputs
Returns a list of available output ports.
audio play_gain ?value?
Returns the current play gain value if invoked without a parameter.
If a an integer value is given play gain is set to the given value. Valid
values are in the range 0-100.
audio record_gain ?value?
Returns the current record gain value if invoked without a parameter.
If a an integer value is given record gain is set to the given value. Valid
values are in the range 0-100.
BUGS
This command is in a state of
development. Solaris, Linux, and HP-UX have the most complete implementation.
SGI users should use the system audio panel.
NAME
initSnack - Initialize the Snack extension
SYNOPSIS
initSnack
OPTIONS
None.
DESCRIPTION
This command should be run before any features of the Snack extension are
used. It makes sure that the Snack library is actually loaded into memory
before any of the non-command features (e.g. canvas items) are used.
NAME
sound - Create and manipulate
sounds
SYNOPSIS
sound ?name? ?options?
DESCRIPTION
CREATING SOUNDS
sound ?name?
?-load filename? ?-file filename? ?-channel channelname?
?-frequency f? ?-channels n? ?-format fmt?
SOUND COMMAND
soundName append variable ?-frequency
f? ?-channels n? ?-format fmt? ?-skipHead n? ?-byteOrder endianess? ?-start
start? ?-end end?
soundName byteswap
soundName cget option
soundName concatenate sound
soundName configure option value
soundName convert option value
soundName copy sound ?-start start? ?-end
end?
soundName cut sound
soundName crop start end
soundName data variable ?-frequency f? ?-channels
n? ?-format fmt? ?-skipHead n? ?-byteOrder endianess? ?-start start?
?-end end?
soundName data ?-start start? ?-end end?
?-fileFormat fileformat?-byteOrder ?endianess?
soundName destroy
soundName flush
soundName info
soundNameinsert sound sample ?-start start?
?-end end?
soundName max
soundName min
soundName length ?n? ?-units u?
soundName pause
soundName play ?-start start? ?-end end? ?-output
jack? ?-blocking boolean? -command ?callback?
soundName read filename ?-frequency
f? ?-channels n? ?-format fmt? ?-skipHead n? ?-byteOrder endianess?
?-start start? ?-end end?
soundName record ?-frequency f? ?-channels n?
?-format fmt? ?-input jack?
soundName sample n ?value? ...
soundName stop
soundName write filename ?-start
start? ?-end end?
NAME
sound - Create and manipulate sounds
SYNOPSIS
sound soundName
soundName option ?arg arg ...?
DESCRIPTION
A sound is an object which handles audio data. Sound objects can interact
with files, variables, canvas items and the audio hardware.
CREATING SOUNDS
The sound command is used to create, delete, and operate on sound objects.
It can take several different forms, depending on the option argument.
The legal forms are:
sound ?soundName? ?-load filename?
?-file filename? ?-channel channelname? ?-frequency f? ?-channels
n? ?-format fmt?
soundName specifies the name of the sound. If it is omitted then
Snack picks a name of the form soundn, where n is an integer.
The -load option specifies that the file filename should be read
into memory after creating the sound. The -file option specifies an on-disk
file which should be linked to the sound. The -channel options specifies
that audio data resides on a channel which should be linked to the sound.
In these cases the audio data is not loaded into memory, which is useful
when playing large files or when using streaming audio. However, the Snack
canvas item types, e.g. waveform, can not be linked to sounds of these
types.
SOUND COMMAND
When a sound is created, Tcl also creates a new command whose name is the
same as the sound name specified. This command may be used to invoke various
operations on the sound. The following commands are possible for sounds:
soundName append variable ?-frequency
f? ?-channels n? ?-format fmt? ?-skipHead n? ?-byteOrder endianess? ?-start
start? ?-end end?
Appends binary string data to the end of soundName.
soundName byteswap
Byte swaps buffer. Any active play or record operation is stopped before
the command is executed.
soundName cget option
The cget command retrieves the value of an option for a sound. Option
can be any of the following: -load, -file, -channel, -frequency, -channels,
and -format.
soundName concatenate sound
Concatenates the sample data from sound to the end of soundName.
The sounds must be of the same type.
soundName configure option value ...
The configure command sets options for a sound. Options can be any
of the following: -load, -file, -channel, -frequency, -channels, and
-format. A value of 1 or larger must be specified for the channels
options (MONO, or STEREO are also valid). Possible values for sample encoding
format are LIN16, LIN8, ALAW, or MULAW (hardware dependent).
soundName convert option value ...
The convert command is used to convert a sound to a different sample encoding, sample frequency, or number of channels. Options can be any
of the following: -frequency, -channels, and -format. A value of 1 or larger must be specified for the -channels option (MONO, or STEREO are also valid). Only conversions from many channels to one or the reverse are possible. Values for sample encoding format are LIN16, LIN8, ALAW, or MULAW. The current sample frequency conversion algorithm is simple and may not be suitable for all needs.
soundName copy sound ?-start start?
?-end end?
Copies sample data from sound. Optionally a range of samples
to copy can be specified. Any active play operation is stopped before the
command is executed if the format of the new sound differs from the current.
soundName crop start end
Crops the sound to the given range [start end].
soundName cut start end
Cuts the given range [start end] from the sound.
soundName data ?variable? ?option value?
...
Loads sound data from, or writes to, a binary string.
When loading data the same options apply as for the read command:
soundName data variable ?-frequency f? ?-channels n? ?-format
fmt? ?-skipHead n? ?-byteOrder endianess? ?-start start? ?-end end?
The command returns the file format detected. Any active play operation
is stopped before data is loaded.
When writing data to a binary string -start and -end options
can be given (as for the write command). Also, a -fileFormat
option can be given if the file format should be different from the original.
In the case of RAW file format the endianess can be specified as either
bigEndian or littleEndian.
soundName data ?-start start? ?-end end? ?-fileFormat
fileformat? -byteOrder ?endianess?
soundName destroy
Removes the sound command and frees the storage associated with it.
soundName flush
Removes all audio data from the sound.
soundName info
Returns a list with information about the sound: {length frequency
max min format channels fileFormat headerSize}
soundName insert sound sample ?-start start?
?-end end?
Inserts sound at sample. Optionally a range of samples to copy can
be specified.
soundName length ?n? ?-units u?
Gets or sets the length of the sound in number of samples (default),
or seconds, by setting u to either SAMPLES or SECONDS. If the new
length is larger than the current the sound is padded with additional silence.
soundName max
Returns the largest positive sample value of the sound.
soundName min
Returns the largest negative sample value of the sound.
soundName pause
Pause current play/record operation. Next pause invocation resumes
play/record. If there is a queue of sounds to play, each of them can pause
play back using pause.
soundName play ?option value? ...
Plays a sound. All options are ignored if play is used to resume
a paused play operation. If a play command is issued while another
one is in progress, the latter one is queued up and played after the first
one. The sound command for in-memory sounds has the following form:
soundName play ?-start start? ?-end end? ?-output jack?
?-blocking boolean? ?-command callback?
A range of samples to play can be specified using the -start
and -end options. The -output option is used to specify any
of the possible output ports returned by the audio outputs
command, such as 'Speaker', 'Headphones', or 'Line Out'. The -blocking
option is used to specify whether playback should be asynchronous or not,
i.e. if it is to be played in the background or if the play command
should return only after the sound has been played. Asynchronous playback
from tclsh is only possible if the event loop is running, using for example
vwait. The -command option specifies a command to be executed
when the end of the sound is reached.
File and channel based sounds have additional options:
-frequency, -channels, -format, -byteOrder,
-buffersize
The first three options are used to specify the characteristics of the
audio data, as for the read command. Byte order
can be specified as littleEndian or bigEndian using the -byteOrder
option. The -buffersize option is used to specify the size of the
internal buffer in samples.
soundName record ?option value? ...
Starts recording data from the audio device into the sound. The sound
command for in-memory sounds has the following form:
soundName record ?-frequency f? ?-channels n? ?-format fmt?
?-input jack?
The options -frequency, -channels, and -format behave
the same as for the read command. -input
specifies one of the available input ports returned by the audio
inputs command, for example 'Microphone' or 'Line In'.
File and channel based sounds have additional options:
-fileFormat, -byteOrder, -buffersize
A -fileFormat option can be given in order to specify the file
format when writing data to a channel. Byte order can be specified as littleEndian
or bigEndian using the -byteOrder option. The -buffersize
option is used to specify the size of the internal buffer in samples.
soundName read filename ?-frequency
f? ?-channels n? ?-format fmt? ?-skipHead n? ?-byteOrder endianess?
?-start start? ?-end end?
Reads new sound data from a file. The options are used when reading
raw binary files, -frequency and -channels are used to set
the sampling frequency and the number of channels (MONO/STEREO). The -format
option is used to specify sample encoding format. Currently, the formats
LIN16, ALAW, and MULAW are supported. -skipHead is used to skip
an unknown header of size n bytes, and -byteOrder is used
to specify endianess. Current supported file formats are WAV, AU,
SND, AIFF, SMP, NIST (TIMIT), and RAW binary. The command returns the file
format detected. If neither byte order nor sample encoding are specified
for a raw file, then the command tries to infer this information. Any active
play operation is stopped before the command is executed, if the format
of the new sound data differs from the current.
soundName sample n ?value? ...
Gets or sets sample number n. Specify one value for each channel.
You can use a ? character to specify that you don't want to change a certain
value, i. e. snd sample 10000 ? 1000, would set the right channel of sample
number 10000 of sound snd to the value of 1000 without influencing the
left channel.
soundName stop
Stops current play or record operation. If there is a queue of sounds
to play, each of them can stop playback using stop. If a callback
was registered using the -command option to play it is not
executed.
soundName write filename ?-start
start? ?-end end? ?-fileFormat fileformat?
Writes sound data to a file. Optionally a range of samples to save
can be specified using the -start and -end options. The file
format is guessed from the filename extension. Currently, the supported
formats are WAV, AU, SND, AIFF, SMP, and RAW. The -fileFormat option
overrides the guess from file name extension.
NAME
spectrogram - Real time spectrogram widget (deprecated, use spectrogram canvas item)
SYNOPSIS
spectrogram pathName ?options value option value ...?
OPTIONS
-height size
-width size
-sound name
-winlength length
-fftlength length
-preemphasisfactor factor
-pixelspersecond value
-xscrollcommand value
-scrollincrement value
-brightness value
-contrast value
-topfrequency frequency
-colormap colorlist
DESCRIPTION
The option -fftlength specifies the number of fft points (8, 16,
32, 64, 128, 256, 512, 1024, 2048, or 4096), -winlength specifies
the size of the hamming window (8-fftlength). -start and -end
controls which part of the sound to display. -pixelspersecond determines
the scaling factor in the x-direction. If the -width option is also
given only the last part of the sound is shown according to both values.
-brightness and -contrast takes values beteween
-100.0 and 100.0. -topfrequency is the frequency value at
the top of the spectrogram. -colormap is a list of colors.
At least two must be specified. The first color is used for the lowest
intensity in the spectrogram. An empty list gives the default 32 level
grey scale. See also the code examples in the widget demonstration.
NAME
spectrogram - Spectrogram canvas item
SYNOPSIS
pathName create spectrogram x y ?options value option
value ...?
OPTIONS
-height size
-width size
-sound name
-winlength length
-fftlength length
-preemphasisfactor factor
-pixelspersecond value
-tags tagList
-start sample
-end sample
-channel value
-brightness value
-contrast value
-topfrequency frequency
-gridtspacing value
-gridfspacing value
-gridcolor color
-colormap colorlist
DESCRIPTION
The option -fftlength specifies the number of fft points (8, 16,
32, 64, 128, 256, 512, 1024, 2048, or 4096), -winlength specifies
the size of the hamming window (8-fftlength). -pixelspersecond determines
the scaling factor in the x-direction. -start and -end controls
which part of the sound to display. Use the -channel option to select
which channel to show for multichannel sounds. Use left, right, both, all,
-1 (all) or a channel number counting from 0. If the -width
option is also given only the last part of the sound is shown according
to both values. -brightness and -contrast takes
values beteween -100.0 and 100.0. -topfrequency is the frequency
value at the top of the spectrogram. -gridtspacing is the
spacing between markers in seconds (default 0 means no grid) and -gridfspacing
is the frequency spacing in Hz (default 0 means no grid). -gridcolor
specifies the color of the grid. A colormap for the spectrogram is given
with the -colormap option. It takes a list of colors as parameter
and at least two must be specified. The first color is used for the lowest
intensity in the spectrogram. An empty list gives the default 32 level
grey scale. Currently spectrograms have a width limit of 32767 pixels.
See also the code examples in the widget demonstration.
NAME
section - Spectrum section canvas item
SYNOPSIS
pathName create section x y ?options value option
value ...?
OPTIONS
-height size
-width size
-sound name
-winlength length
-fftlength length
-preemphasisfactor factor
-tags tagList
-start sample
-end sample
-channel value
-fill value
-stipple value
-topfrequency frequency
-frame boolean
DESCRIPTION
The option -fftlength specifies the number of fft points (8, 16,
32, 64, 128, 256, 512, 1024, 2048, or 4096), -winlength specifies
the size of the hamming window (8-fftlength). -start and -end
controls which part of the sound to display. -topfrequency
is the frequency value at the right end of the section. Use the -channel
option to select which channel to show for multichannel sounds. Use left,
right, both, all, -1 (all) or a channel number counting from 0. -frame
specifies whether a frame will be drawn. See also the code examples in
the widget demonstration.
NAME
waveform - Waveform canvas item
SYNOPSIS
pathName create waveform x y ?option value option
value ...?
OPTIONS
-height size
-width size
-sound name
-fill color
-stipple bitmap
-start sample
-end sample
-channel value
-pixelspersecond value
-zerolevel boolean
-tags tagList
-frame boolean
-limit value
-subsample value
DESCRIPTION
The options -start and -end controls which part of the sound
to display. -pixelspersecond determines the scaling factor in the
x-direction. If the -width option is also given only the last part
of the sound is shown according to both values. Use the -channel
option to select which channel to show for multichannel sounds. Use left,
right, both, all, -1 (all) or a channel number counting from 0. Use -limit
to specify the maximal shown value for the sound amplitude. -zerolevel
specifies whether the zero level will be displayed and -frame whether
a frame will be drawn. See also the code examples in the widget demonstration.
The -subsample option is useful for large sounds to specify
how much detail the waveform should show. A value of 1 uses every sample
in the sound to draw the waveform envelope, which can be slow for large
sounds. A value of 10 uses every 10th. The default value 0 subsamples the
waveform in such a way that only 100000 samples are used regardless of
the waveform length.
Snack home