Snack sound extension commands v1.6.5
(Last updated January 10, 2000)
Manual for version 1.5
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.
-
audio
-
sound
-
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 channels mixer
Returns a list with the names of the channels for the specified mixer.
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 mixers
Returns a list with the names of the mixers of the mixer device.
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.
audio volume mixer ?varName? ?varName?
Return the current volume setting for mixer. Optionally link
a Tcl variable to the value. If two variable names are specified they are
used for the left and right channels respectively.
audio update
Update all variables which have been linked to mixer properties to
reflect the current settings of the mixer.
BUGS
This command is not fully implemented
on all platforms. Solaris, Linux, and HP-UX have the most complete implementation.
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? ?-guessproperties boolean?
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? ?-guessproperties boolean?
soundName data ?-start start? ?-end end??-fileformat
fileformat?-byteorder ?endianess?
soundName destroy
soundName fft -start sample -fftlength
length -windowlength length -channel value -preemphasis factor
soundName flush
soundName info
soundName insert 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? ?-guessproperties boolean?
soundName record ?-input jack? ?-append boolean?
soundName reverse ?-start start? ?-end end?
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? ?-fileformat fmt? ?-skiphead boolean? ?-byteorder endianess?
?-guessproperties boolean? ?-buffersize n?
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
option 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. A value of 1 or larger must be specified for
the -channels option (MONO, or STEREO are also valid). -fileformat
works as for the read command. Possible values for sample encoding
format are LIN16, LIN8OFFSET, LIN8, ALAW, or MULAW (hardware dependent).
-skiphead
is used to skip an unknown file header of size n bytes. Byte order
can be specified as littleEndian or bigEndian using the
-byteorder
option. The option -guessproperties is used to specify that Snack
should try to infer properties, such as byte order, sample encoding format,
and frequency for raw files by analyzing the contents of the files. Byte
order is almost always detected correctly. For channel based sounds the
-buffersize
option can be used to specify the size of the internal buffer in samples.
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? ?-fileformat fmt? ?-guessproperties boolean?
Appends binary string data to the end of soundName. The same
options apply as for the read command. This command applies to in-memory
sounds only.
soundName byteswap
Byte swaps buffer. Any active play or record operation is stopped before
the command is executed. This command applies to in-memory sounds only.
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, i.e. have the same frequency, sample
encoding format, and number of channels). This command applies to in-memory
sounds only.
soundName configure option value ...
The configure command sets options for a sound. Options can be any
of the following: -load, -file, -channel, -frequency, -channels, -format,
-skiphead, -byteorder, -guessproperties, and -buffersize. See
the sound command for information on how to use the
options.
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, LIN8OFFSET,
LIN8, ALAW, or MULAW. The current sample frequency conversion algorithm
is simple and may not be suitable for all needs. This command applies to
in-memory sounds only.
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.
This command applies to in-memory sounds only.
soundName crop start end
Crops the sound to the given range [start end]. This command
applies to in-memory sounds only.
soundName cut start end
Cuts the given range [start end] from the sound. This command
applies to in-memory sounds only.
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??-fileformat
fmt? ?-guessproperties boolean?
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?
This command applies to in-memory sounds only.
soundName destroy
Removes the sound command and frees the storage associated with it.
soundName fft ?-start sample? ?-fftlength
length? ?-winlength length? ?-channel value? ?-preemphasisfactor factor?
Experimental command, will change name in version 1.7. Computes the
FFT log power spectrum of the sound starting at -startpos and returns
a list of the dB values. See the
section item for
the rest of the options.
soundName flush
Removes all audio data from the sound. This command applies to in-memory
sounds only.
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. This command applies to in-memory sounds only.
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 ?-start start? ?-end end?
?-channel value?
Returns the largest positive sample value of the sound. A range of
samples and a channel to be examined can be specified.
soundName min ?-start start? ?-end end?
?-channel value?
Returns the largest negative sample value of the sound. A range of
samples and a channel to be examined can be specified.
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. 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.
soundName read filename ?-frequency
f? ?-channels n? ?-format fmt? ?-skiphead n? ?-byteorder endianess??-start
start? ?-end end? ?-fileformat fmt? ?-guessproperties boolean?
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, MP3,
AU, SND, AIFF, SMP, and RAW binary. The command returns the file format
detected. It is possible to force a file to be read as RAW using "-fileformat
RAW".
The option -guessproperties is used to specify that Snack should
try to infer properties, such as byte order, sample encoding format, and
frequency for raw files by analyzing the contents of the files. Byte order
is almost always detected correctly. Any active play operation is stopped
before the command is executed, if the format of the new sound data differs
from the current. This command applies to in-memory sounds only.
soundName record ?option value? ...
Starts recording data from the audio device into the sound object.
For in-memory sound objects the command has the following form:
soundName record ?-input jack? ?-append boolean?
The -input option specifies one of the available input ports returned
by the audio inputs command. -append specifies
that new audio data should be appended at the end of the existing sound
instead of replacing it.
File and channel based sounds have the options:
soundName record ?-input jack? ?-fileformat fmt?
The -fileformat option can be used to specify the file format
to be used when writing data to a channel. In this case there is no file
name to infer the format from.
soundName reverse ?-start start? ?-end end?
Reverses a sound. Optionally a range of samples can be specified.
This command applies to in-memory sounds only.
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 ? 999", would set the right channel of sample
number 10000 of sound snd to the value of 999 without influencing the left
channel. Samples can only be set for in-memory sounds.
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. 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. This command applies to in-memory sounds
only.
NAME
spectrogram - Spectrogram canvas item
SYNOPSIS
pathName create spectrogram x y ?options value option
value ...?
OPTIONS
-anchor anchorPos
-brightness value
-channel value
-colormap colorlist
-contrast value
-end sample
-fftlength length
-gridcolor color
-gridfspacing value
-gridtspacing value
-height size
-pixelspersecond value
-preemphasisfactor factor
-sound name
-start sample
-tags tagList
-topfrequency frequency
-width size
-winlength length
DESCRIPTION
This command draws a spectrogram of a sound on a canvas. The options -anchor,
and -tags work as for ordinary Tk canvas items. -sound specifies
which sound object to link to and -height the height of the spectrogram.
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, which should be equal to or less than the
number of FFT points. -preemphasisfactor is used to specify the
amount of preemphasis applied to the signal prior to the FFT. -start
and -end controls which part of the sound to display. -pixelspersecond
determines the scaling factor in the x-direction. The -width option
specifies the width of the spectrogram. If both -width and -pixelspersecond
are specified the spectrogram will be cut at one end depending on if a
-start
or -end option was also given. 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 (left). The default
is to show all, i.e. to add all channels. -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
-anchor anchorPos
-channel value
-end sample
-fftlength length
-fill value
-frame boolean
-height size
-maxvalue value
-minvalue value
-preemphasisfactor factor
-sound name
-start sample
-stipple value
-tags tagList
-topfrequency frequency
-width size
-winlength length
DESCRIPTION
This command draws an FFT log power spectrum section of a sound on a canvas.
The options -anchor, -fill, -stipple, and -tags
work as for ordinary Tk canvas line items. -sound specifies which
sound object to link to and -height and -width the height/width
of the section.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, which should be equal to or less
than the number of FFT points. -preemphasisfactor is used to specify
the amount of preemphasis applied to the signal prior to the FFT. -start
and -end controls which part of the sound to display. -topfrequency
is the frequency value at the right end of the section. -maxvalue
and -minvalue specify the range (in dB) which will be shown (default
0.0 to -80.0). 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 (left). The default is to show all, i.e.
to add all channels. -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
-anchor anchorPos
-channel value
-end sample
-fill color
-frame boolean
-height size
-limit value
-pixelspersecond value
-shapefile filename
-sound name
-start sample
-stipple bitmap
-subsample value
-tags tagList
-width size
-zerolevel boolean
DESCRIPTION
This command draws the waveform of a sound on a canvas. The options -anchor,
-fill, -stipple, and -tags work as for ordinary Tk
canvas line items. -sound specifies which sound object to link to
and -height the height of the waveform. The options -start
and -end controls which part of the sound to display. -pixelspersecond
determines the scaling factor in the x-direction which also gives the width.
The -width option specifies the width of the waveform. If both -width
and -pixelspersecond are specified the waveform will be cut at one
end depending on if a -start or -end option was also given.
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. The default is to show all, i.e. to add all channels. 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. The -subsample option is useful for
large sounds to specify how precisely they should be analyzed for shape
calculation. The default value 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. Care should be used when specifying values. Using large
values may lead to incorrect envelope shapes. The option -shapefile
is used to specify a file for storing/retrieving precomputed waveform shape
information. If the file doesn't exist it is created. If it exists it is
accessed instead of the sound data itself, thus speeding up on-screen display.
There exists two convenience routines, snack::openShapeMsgBox and snack::closeShapeMsgBox,
which can be used to enclose a create waveform statement when using
the shape file functionality. These will open/close a message box telling
the user that a shape computation is taking place, see the demo cool.tcl
for an example of this.
See also code examples in the widget demonstration.
Snack home