Snack sound extension commands v1.7.0

Manual for version 1.6

The command package require snack gives you access to all commands described below.
The command package require sound only gives you the sound::sound, sound::audio and sound::mixer commands which are equivalent to their snack counterparts.

snack::audio

snack::mixer

snack::sound

spectrogram canvas item

spectrum section canvas item

waveform canvas item

NAME

SYNOPSIS

DESCRIPTION

The audio command is used to get properties of audio devices such as supported sample encoding formats and sample frequencies.

Returns a list of supported sample encoding formats for the currently selected device.

Returns a list of supported sample frequencies for the currently selected device.

Returns a list of available audio input devices.

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.

Returns a list of available audio output devices.

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.

Selects an audio output device to be used as default.

Selects an audio input device to be used as default.

BUGS

NAME

SYNOPSIS

DESCRIPTION

The mixer command is used to get and set properties of mixer devices such as current input/output jack, supported ports, mixer lines, and gain.

Returns a list with the names of the channels for the specified line.

Returns a list of available mixer devices.

Gets/sets the current input jack.

Returns a list of available input ports.

Returns a list with the names of the lines of the mixer device.

Gets/sets the current output jack.

Returns a list of available output ports.

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.

Selects a mixer device to be used as default.

BUGS

NAME

SYNOPSIS

soundName option ?arg arg ...?

DESCRIPTION

CREATING SOUNDS

snack::sound ?soundName? ?-load filename?  ?-file filename?  ?-channel channelname? ?-frequency f? ?-channels n? ?-format fmt? ?-fileformat fmt? ?-skiphead n? ?-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

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.

Byte swaps buffer. Any active play or record operation is stopped before the command is executed. This command applies to in-memory sounds only.

The cget command retrieves the value of an option for a sound. Option can be any of the following: -load, -file, -channel, -frequency, -channels, -format, -skiphead, -byteorder, -guessproperties, and -buffersize.

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.

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.

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, -format, and -progress. 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. See the read command for a description on how to use the -progress option. This command applies to in-memory sounds only.

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.

Crops the sound to the given range [start end], i.e. all samples before and after these limits will be removed. This command applies to in-memory sounds only.

Cuts the given range [start end] from the sound, i.e. all samples between and including these limits will be removed. This command applies to in-memory sounds only.

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.

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

Computes the log FFT power spectrum of the sound at -start and returns a list of dB values. See the section item for the rest of the options. Optionally an ending point can be given, using -end. In this case the result is the average of consecutive FFT's in the specified range. Their default spacing is taken from -fftlength but this can be changed using the -skip option which tells how many points to move the FFT window each step.

Removes all audio data from the sound. This command applies to in-memory sounds only.

Returns a list with information about the sound. The entries are {length frequency max min format channels fileFormat headerSize}

Inserts sound at position. Optionally a range of samples to copy can be specified. This command applies to in-memory sounds only.

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.

Returns the largest positive sample value of the sound. A range of samples and a channel to be examined can be specified. The default is to check all channels and return the maximum value.

Returns the largest negative sample value of the sound. A range of samples and a channel to be examined can be specified. The default is to check all channels and return the minimum value.

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.

Returns a list of pitch values computed using the AMDF method. The values are spaced 10ms. A range of samples can be given using -start and -end. If a frequency range of valid pitch values is known this can be specified using the options -maxpitch and -minpitch. See the read command for a description on how to use the -progress option.

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? ?-device outputDevice?

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. The -device option selects which audio output device to use.

Reads new sound data from a file. Current supported file formats are WAV, MP3, AU, SND, AIFF, SMP, CSL, 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". In this case properties of the sound data can be specified by hand. -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, Lin8offset, Lin8, Alaw, and Mulaw are supported. -skiphead is used to skip an unknown header of size n bytes, and -byteorder is used to specify endianess.  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. It is possible to add a progress callback procedure which is to be called at regular intervalls using the option -progress. This procedure gets two arguments, first the string "Read sound" and then a double value specifying the fraction of the command that currently has been completed.  If the callback returns with an error code (return -code error) the read operation is cancelled. The convenience routine snack::progressCallback opens up a message box with an appropriate message if used as procedure to this option. 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.

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? ?-device inputDevice?

 
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. The -device option selects which audio input device to use.

File and channel based sounds have the options:

soundName record ?-input jack? ?-fileformat fmt? ?-device inputDevice?

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.
 

Reverses a sound. Optionally a range of samples can be specified. This command applies to in-memory sounds only.

Gets or sets sample number n. When setting samples one value should be specified 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 be read for all sound types but only be set for in-memory sounds.

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.

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, CSL, and RAW. The -fileformat option overrides the guess from file name extension. This command applies to in-memory sounds only. If you specify RAW file format the sound will be saved to file without a header using the natural byte order of the machine. This can be overridden using the option -byteorder. See the read command for a description on how to use the -progress option.

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

OPTIONS

DESCRIPTION

NAME

SYNOPSIS

OPTIONS

DESCRIPTION