Snack v2.2 manual

snack::audio

snack::debug

snack::filter

snack::mixer

snack::sound

spectrogram canvas item

spectrum section canvas item

waveform canvas item

 

Standard extension packages (sound, snackogg, snacksphere)

 

Snack library

NAME

SYNOPSIS

DESCRIPTION

snack::audio encodings

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

Returns a list of supported sample rates for the current selected device.

Returns a list of available audio input devices.

Sets/queries (in ms) how much sound will be queued up at any time to the audio device for playback. A low value makes new sound samples reach the loudspeakers quickly at the risk of gaps in the output stream. An appropriate value should be chosen with regard to processor speed and load. The default value has been choosen to give adequate performance for a mix of tasks and might be to low for simple playback in some cases. If spurious gaps in the playback stream occur, try using a latency of a couple of thousand milliseconds. On UNIX systems, the environment variable PLAYLATENCY can also be used to control this property.

Toggles between pause/play for all playback on the audio device.

Resumes paused playback on the audio device.

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.

Scale the global output stream by multiplying with factor. Useful to prevent clipping when playing many simultaneous sounds. If no value is specified the current factor is returned, default is 1.0.

Selects an audio input device to be used as default.

Stops all playback on the audio device.

NAME

SYNOPSIS

DESCRIPTION

NAME

SYNOPSIS

filterName option ?arg arg ...?

DESCRIPTION

FILTER COMMAND

filterCmd configure ?arg ...?

Configures the filter command, see the filter types for their respective options.

Removes the filter command and frees the storage associated with it. If the filter is currently used for playback an unfiltered stream will be output as soon as the internal buffer has been played.

FILTERS TYPES

compose filter filter ...

Creates a new filter which is a linear combination of two or more other filters. The output of the first is fed into the input of the next and so on.

Creates an echo effect. inGain is a multiplicative factor applied on the input stream. outGain is applied on the output. Both factors should be between 0.0 and 1.0.  For each echo a delay/decay pair should be specified. The delay is specified in milliseconds and decay is a factor relative to inGain.

A formant filter with given frequency and bandwidth.

A signal generator with given frequency and amplitude. shape is a value between 0.0 and 1.0 used to influence the shape of the signal. type can be any of rectangle, triangle, sine, noise, or sampled. In the case of sampled the generator will repeatedly get data from the sound it is applied on. ntot specifies how many samples to generate. The default, -1, will generate forever.

Creates an IIR or FIR filter. For FIR filters the coefficients are given as a list using the -impulse option. For IIR filters the coefficients are given as lists using the options -numerator and -denominator. The option -dither specifies the amount of triangular dithering to add to the output. The option -noise specifies the amount of additive gaussian noise to add to the output.

Applies a linear transformation on each sample frame. For one channel sounds this is simply a multiplication. For multi-channel sounds, a transformation matrix can be specified with values row by row. One column per channel is needed. If mono output is used, only one row needs to be specified. If stereo output is used, only two rows needs to be specified. If only one value is specified and the filter is used for multi-channel data, each channel is multiplied with the given value.

A reverb effect. outGain is a value between 0.0 and 1.0. time and delay are given in milliseconds.

BUGS

NAME

SYNOPSIS

DESCRIPTION

snack::mixer channels line

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. Optionally link a boolean Tcl variable.

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. Optionally link a boolean Tcl variable.

Returns a list of available output ports.

Updates all linked variables to reflect the status of the mixer device.

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.

NAME

SYNOPSIS

soundName option ?arg arg ...?

DESCRIPTION

CREATING SOUNDS

snack::sound ?soundName? ?-load filename?  ?-file filename?  ?-channel channelname? ?-rate f? ?-channels n? ?-encoding fmt? ?-fileformat fmt? ?-skiphead n? ?-byteorder endianess? ?-guessproperties boolean?  ?-buffersize n? ?-precision prec? ?-changecommand procedure? ?-debug level?

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. A value of 1 or larger must be specified for the -channels option (Mono, or Stereo are also valid). If not specified a default value of 1 is assumed. Possible values for sample encoding format, given using the -encoding option, are Lin16, Lin8offset, Lin8, Lin24, Lin32, Float, Alaw, or Mulaw. Default encoding is Lin16. The option -rate can take any positive value but usually only sample rates supported by the audio hardware are useful. Note that the default value is 16000, a common value for speech related applications, but less frequent for other uses, such as music. -fileformat works as for the read command. -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 sample rate for a raw file by analyzing the contents of the file. 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. The option -precision is used to specify if sound data is to be handled using simple or double precision internally. -changecommand is used to specify a procedure which is to be called every time a property of the sound is changed. This is the Tcl level counterpart of Snack_AddCallback(). The procedure should expect one argument, one of the strings New, More, or Destroy. This feature is particularly useful when embedding sound objects in other higher level constructs. The flag -debug is used to control debug output for operations on the sound object. The option takes a level argument, an integer in the range 1-5, specifying the detail of the trace information.

SOUND COMMAND
When a sound object is created, Snack also creates a new object command whose name is the same as the sound. This command is used to invoke various operations (or sub-commands) on the sound. This is the current set:

soundName append variable ?-rate f? ?-channels n? ?-encoding 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.

The cget command retrieves the current value of an option for a sound. Option can be any of the following: -load, -file, -channel, -rate, -channels, -encoding, -skiphead, -byteorder, -guessproperties, -precision, and -buffersize. See the sound command for more information on these.

This command is used to inform Snack that the sound object has been modified. Normally Snack tracks changes to sound objects automatically, but in a few cases this must be performed explicitly. For example, setting of samples using the sample command is not tracked for preformance reasons. Here a changed command might be necessary. flag can be either New or More. New is used for any type of change while More only applies to the case where more samples has been appended.

Concatenates the sample data from sound to the end of soundName. The sound to be added must be of the same type as the base sound, i.e. have the same sample rate, sample encoding format, and number of channels). Note that even an initially empty sound has these properties defined. This command applies to in-memory sounds only.

The configure command is used to set options for a sound. Options can be any of the following: -load, -file, -channel, -rate, -channels, -encoding, -skiphead, -byteorder, -guessproperties, -precision, -debug and -buffersize. See the sound command for more information on these.

The convert command is used to convert a sound to a different sample encoding, sample rate, or number of channels. Options can be any of the following: -rate, -channels, -encoding, 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, Lin24, Lin32, Float, Alaw, or Mulaw. The current sample rate 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 ?-rate f? ?-channels n? ?-encoding 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. Optionally an end 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 specifies how many points to move the FFT window forward at each step. See the section item for the rest of the options.

Applies the filter filterName to the sound. Optionally, a range to apply the filter on can be specified. The -continuedrain option specifies whether the filter should be allowed to drain out past the end point. See the read command for a description on how to use the -progress option. This command applies to in-memory sounds only.

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

Estimates speech formant trajectories. Dynamic programming is used to optimize trajectory estimates by imposing frequency continuity constraints. The formant frequencies are selected from candidates proposed by solving for the roots of the linear predictor polynomial computed periodically. The local costs of all possible mappings of the complex roots to formant frequencies are computed at each frame based on the frequencies and bandwidths of the component formants for each mapping. The cost of connecting each of these mappings with each of the mappings in the previous frame is then minimized using a modified Viterbi algorithm. The command returns a list with one element per frame, each containg a list with formant and bandwidth values, {F1 F2 ... B1 B2 ...}. The first row corresponds to a start time of half the window length, see the -windowlength option. The option -numformants controls how many formants to calculate (default 4, maximum 7). The -framelength option specifies the intervals between the values (default 0.01). The option -windowtype is used to select windowing function, (valid values are Cos^4 (default), Hamming, Hanning, or Rectangle). -windowlength specifies the size of the window in seconds (default 0.049). -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to windowing (default 0.7). A range of samples can be given using -start and -end. -lpctype is either 0 (autocorrelation) or 1 (stabilized covariance). The order of the LPC analysis specified using -lpcorder (default 12). The option -ds_freq specifies the sampling rate of the data to be used in the formant frequency analysis (default 10000). -nom_f1_freq specifies the nominal value of the first formant frequency. This value is used to adjust the nominal values of all other formants and of the ranges over which the formants are permitted to exist. The default value of 500Hz assumes that the vocal tract length is 17 cm and that the speed of sound is 34000 cm/sec. Nominal F1 values scale directly with sound velocity and inversely with vocal-tract length. See the read command for a description on how to use the -progress option.

Returns a list with information about the sound. The entries are {length rate "maximum sample" "minimum sample" "sample encoding" "number of channels" "file format" "header size in bytes"}

Inserts sound at position. Optionally a range of samples to insert 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.

Copies sample data from sound. Optionally a range of samples, where the mix operation will be applied, can be specified. The -mixscaling option controls how much to scale soundName before mixing. The option -prescaling controls how much to scale the original sound before mixing. This command applies to in-memory sounds only.

Pause current play/record operation. Next pause invocation resumes play/record. If several play operations for one sound object are in progress all of them are paused using pause.

Returns a list of pitch values computed using either the normalized cross correlation function and dynamic programming or the AMDF method. This is selected using the -method option, by specifying either ESPS or AMDF. For ESPS the output list will contain 4 fields for each frame, pitch, probability of voicing, local root mean squared measurements, and the peak normalized cross-correlation value that was found to determine the output pitch value. The values are spaced according to the -framelength option (default 0.01). The first row corresponds to either 0.0 (for AMDF), or to half the window length (for ESPS), see the -windowlength option. 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 (default 400) and -minpitch (default 60). -windowlength specifies the size of the window in seconds (default 0.0075). See the read command for a description on how to use the -progress option.

Plays a sound. A range of samples to be played 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 is only possible if the event loop is running, e.g., if the script uses the wish interpreter with a graphical user interface. Otherwise the event loop needs to be started 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. The -filter option is used to specify a filter which is to be applied during output. The audio device can be opened with different properties from those of the sound object using -devicerate and -devicechannels, which might be useful in some rare cases. The option -starttime is used to schedule the start of playback (in ms) relative to a previous play operation. 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 new sound will start to play as soon as possible given the internal buffering. The lag before the sound is audible can be controlled using the snack::audio latency command.

Returns a list of windowed log power values. The -framelength option specifies the intervals between the values. The option -windowtype is used to select windowing function, (valid values are Hamming, Hanning, Bartlett, Blackman, or Rectangle). -windowlength specifies the size of the window in points. -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to windowing. A range of samples can be given using -start and -end. See the read command for a description on how to use the -progress option and the section item for the -channel option.

Reads new sound data from a file. Current supported file formats are WAV, MP3, AU, SND, AIFF, SD, 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 the properties of the sound data should be specified by hand. -rate and -channels are used to set the sampling rate and the number of channels (Mono/Stereo). The -encoding option is used to specify sample encoding format. Currently, the formats Lin16, Lin8offset, Lin8, Lin24, Lin32, Float, Alaw, and Mulaw are supported. -skiphead is used to skip an unknown header of size n bytes, and -byteorder is used to specify endianess (bigEndian/littleEndian).  The option -guessproperties is used to specify that Snack should try to infer properties, such as byte order, sample encoding format, and sample rate for raw files by analyzing the contents of the file. Byte order is almost always detected correctly. It is possible to add a progress callback procedure which is to be called at regular intervals using the -progress option. This procedure is called with 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 argument 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.

Note that recording is only possible if the event loop is running, e.g., if the script uses the wish interpreter with a graphical user interface. Otherwise the event loop needs to be started using for example vwait. Just using after n between a record/stop command pair is not enough. Use something like after n {set flag 1} ; vwait flag in order to make sure the event loop is kept active

Reverses a sound. Optionally a range of samples to be reversed can be specified. See the read command for a description on how to use the -progress option. 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. A ? character can be used to specify that a certain value should not be affected, 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 can 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. Any callbacks registered using the -command option of the play command will not be 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 inferred 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. 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

Standard extension packages

The following packages are included in the Snack distribution or can be downloaded separately.

sound

The sound package gives you the snack::audio, snack::filter, snack::mixer, and snack::sound commands. Basicly the same functions as the snack package except for graphics. This is useful on some systems if you want to use the tclsh interpreter.

snackogg

The snackogg package adds support for the Ogg/Vorbis compressed sound file format. Ogg format files and streams are detected automatically. Encoding is supported. Simply use the extension .ogg when writing files or use the option -fileformat ogg. When creating Ogg files the additional options -nominalbitrate, -maxbitrate, -minbitrate, and -comment apply.

snacksphere

The snacksphere package adds support for reading the NIST/Sphere sound file formats. Sphere files are detected automatically.