Snack sound extension commands v1.3

Important notice: the -file option of the sound command has been renamed -load since v1.2.

Manual for version 1.2

audio

initSnack

sound

spectrogram

spectrogram canvas item

spectrum section canvas item

waveform canvas item

NAME

SYNOPSIS

DESCRIPTION

The audio command is used to get and set properties of the audio device such as current input/output jack, supported ports, sample formats, sample frequencies, and gain.

Returns a list of supported sample formats.
 

Returns a list of supported sample frequencies.
 

Gets/sets the current input jack.
 

Returns a list of available input ports.
 

Gets/sets the current output jack.
 

Returns a list of available output ports.
 

Returns the current play gain value if invoked without a parameter, else sets it to the given value. Valid values are in the range 0-100.
 

Returns the current record gain value if invoked without a parameter, else sets it to the given value. Valid values are in the range 0-100.
 

BUGS

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

soundName option ?arg arg ...?

DESCRIPTION

CREATING SOUNDS

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

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. Any active play operation is stopped before the command is executed.

Byte swaps buffer. Any active play or record operation is stopped before the command is executed.

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.

Concatenates the sample data from sound to the end of soundName. The sounds must be of the same type. Any active play operation is stopped before the command is executed.

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). Any active play or record operation is stopped before the command is executed.

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.

Crops the sound to the given range [start end]. Any active play operation is stopped before the command is executed.

Cuts the given range [start end] from the sound. Any active play operation is stopped before the command is executed.

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?

Removes the sound command and frees the storage associated with it.

Removes all audio data from the sound.

Returns a list with information about the sound: {length frequency max min format channels fileFormat headerSize}

Inserts sound at sample. Optionally a range of samples to copy can be specified. Any active play operation is stopped before the command is executed.

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. Any active play operation is stopped before the length is changed.

Returns the largest positive sample value of the sound.

Returns the largest negative sample value of the sound.

Plays a sound. The sound command for in-memory sounds has the following form:

soundName play ?-start start? ?-end end? ?-output jack? ?-blocking boolean?

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.

File and channel based sounds have additional options:

-frequency, -channels, -format, -byteOrder, -eofCommand, -buffersize

The first three options are used to specify the characteristics of the audio data, as for the read command. It is possible to specify a command to be executed when end of file is reached using the -eofCommand option. 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.

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 are used as with the read. -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.

Reads new sound data from a file. The options are used when reading raw binary files, -frequency and -channels are used to set he 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, SMP, AU, SND, NIST (TIMIT), and RAW binary. The command returns the file format detected. Any active play or record operation is stopped before the command is executed.

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.

Stops current play or record operation.

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, SMP, AU, SND, and RAW.

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

OPTIONS

DESCRIPTION