--- --- Snack Manual

Snack v2.2.10 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

snack::audio - Get/set properties of audio devices

SYNOPSIS

snack::audio property ?arg? ...

DESCRIPTION

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

snack::audio active

Returns 1 or 0 depending on whether there is any current activity on the audio device.
snack::audio currentSound
Returns the name of any sound object currently used for playback or record.
snack::audio elapsedTime
Returns the time in seconds since playback or recording started on the audio device.
snack::audio encodings
Returns a list of supported sample encoding formats for the current selected device.
snack::audio inputDevices
Returns a list of available audio input devices.
snack::audio playLatency
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.
snack::audio pause
Toggles between pause/play for all playback on the audio device.
snack::audio play
Resumes paused playback on the audio device.
snack::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.
snack::audio outputDevices
Returns a list of available audio output devices.
snack::audio rates
Returns a list of supported sample rates for the current selected device.
snack::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.
snack::audio selectOutput device
Selects an audio output device to be used as default.
snack::audio scaling ?factor?
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.
snack::audio selectInput device
Selects an audio input device to be used as default.
snack::audio stop
Stops all playback on the audio device.

NAME

snack::debug - Control Snack debugging facilities

SYNOPSIS

snack::debug level ?logFile? ?audioDumpFile?

DESCRIPTION

The debug command is used to control the debugging facilities of Snack. The level flag is an integer (1-5) specifying the detail level of the generated debug log. Level 1 just prints entry/exit points of sound commands during execution. An optional second filename argument can be given to specify a file where the log will be written. An optional third filename can be given to specify a file where a raw dump of all audio being played through the audio device is to be generated. The sound file will be created in RAW (headerless) format. Note that debugging has to be turned on for each individual sound object of interest. Reports on bugs/problems with Snack should typically include a minimal script that shows the problem, any associated sound files, and a debug log in order to facilitate a quick solution.

NAME

snack::filter - Create and manipulate filters

SYNOPSIS

snack::filter type ?arg? ...

filterName option ?arg arg ...?

DESCRIPTION

The filter command is used to create filter objects. These can interact with sound objects either using the sound filter command or during playback. Note that since a filter object may contain state information about a sound stream it should only be used for one play operation at a time.

FILTER COMMAND

When a filter object is created, Snack returns the name of a newly created object command. This command may be used to invoke various operations on the filter.

filterCmd configure ?arg ...?

Configures the filter command, see the filter types for their respective options.
filterCmd destroy
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.

FILTER TYPES

Current filter 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.
echo inGain outGain delay decay ?delay decay ...?
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.
fade direction type length ?floor?
An envelope filter for creating fades. The option direction should be either in or out. The option type one of linear, exponential, or logarithmic. length should be given in milliseconds. If needed a minimum fade level (value between 0 and 1.0) can be given as parameter four.
formant frequency bandwidth
A formant filter with given frequency and bandwidth.
generator frequency ?amplitude? ?shape? ?type? ?ntot?
A signal generator with given frequency and amplitude. 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. shape is a value between 0.0 and 1.0 used to influence the shape of the signal. It is only useful for rectangle, triangle, or sine types. Use a value of 0.5 with rectangle to get a square wave or with triangle to get a triangle wave. Use a value of 0.0 with sine to get a sine wave and with triangle to get a sawtooth wave. See the demo formant.tcl for an interactive demonstration. ntot specifies how many samples to generate. The default, -1, will generate forever.
iir ?-denominator list? ?-dither value? ?-impulse list? ?-noise value? ?-numerator list?
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.
map val ?val val val ...?
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.
reverb outGain time delay ?delay ...?
A reverb effect. outGain is a value between 0.0 and 1.0. time and delay are given in milliseconds.

BUGS

        This command still needs work.

NAME

snack::mixer - Get/set properties of mixer devices
 

SYNOPSIS

snack::mixer property ?arg? ...

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.

snack::mixer channels line

Returns a list with the names of the channels for the specified line.
snack::mixer devices
Returns a list of available mixer devices.
snack::mixer input ?jack? ?varName?
Gets/sets the current input jack. Optionally link a boolean Tcl variable.
snack::mixer inputs
Returns a list of available input ports.
snack::mixer lines
Returns a list with the names of the lines of the mixer device.
snack::mixer output ?jack? ?varName?
Gets/sets the current output jack. Optionally link a boolean Tcl variable.
snack::mixer outputs
Returns a list of available output ports.
snack::mixer update
Updates all linked variables to reflect the status of the mixer device.
snack::mixer volume line ?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.
snack::mixer select ?device?
Selects a mixer device to be used as default.

NAME
        snack::sound - Create and manipulate sounds
SYNOPSIS
        snack::sound ?name? ?options?
DESCRIPTION
CREATING SOUNDS
        snack::sound ?name? ?-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?
SOUND COMMAND
soundName append variable ?-rate f? ?-channels n? ?-encoding fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-guessproperties boolean?
soundName cget option
soundName changed flag
soundName concatenate sound
soundName configure option value ...
soundName convert option value
soundName copy sound ?-start start? ?-end end?
soundName cut sound start end
soundName crop start end
soundName data variable ?-rate f? ?-channels n? ?-encoding fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-guessproperties boolean?
soundName data ?-start start? ?-end end? ?-fileformat fileformat? ?-byteorder endianess?
soundName destroy
soundName dBPowerSpectrum ?-start sample? ?-end sample? ?-skip samples? ?-fftlength length? ?-windowlength length? ?-channel channel? ?-preemphasisfactor factor? ?-windowtype type? ?-analysistype type? ?-lpcorder n?
soundName filter filterName ?-start sample? ?-end sample? ?-continedrain boolean? ?-progress callback?
soundName flush
soundName formant ?-start sample? ?-end sample? ?-framelength t? ?-numformants n? ?-windowlength length? ?-preemphasisfactor factor? ?-windowtype type? ?-lpctype? ?-lpcorder n? ?-ds_freq? ?-nom_f1_freq? ?-progress callback?
soundName info
soundName insert sound position ?-start start? ?-end end?
soundName lastIndex
soundName length ?n? ?-unit u?
soundName max ?-start start? ?-end end? ?-channel channel?
soundName min ?-start start? ?-end end? ?-channel channel?
soundName mix sound ?-start start? ?-end end? ?-mixscaling factor? ?-prescaling factor? ?-progress callback?
soundName pause
soundName pitch ?-method m? ?-start start? ?-end end? ?-framelength t? ?-windowlength length? ?-maxpitch val? ?-minpitch val? ?-progress callback?
soundName play ?-start start? ?-end end? ?-output jack? ?-blocking boolean? -command ?callback? ?-device outputDevice? ?-devicerate rate? ?-devicechannels channels?
soundName power ?-start sample? ?-end sample? ?-framelength length? ?-windowlength length? ?-windowtype type? ?-preemphasisfactor factor? ?-channel channel? ?-progress callback?
soundName powerSpectrum ?-start sample? ?-end sample? ?-skip samples? ?-fftlength length? ?-windowlength length? ?-channel channel? ?-preemphasisfactor factor? ?-windowtype type? ?-analysistype type? ?-lpcorder n?
soundName read filename ?-rate f? ?-channels n? ?-encoding fmt? ?-skiphead n? ?-byteorder endianess??-start start? ?-end end? ?-guessproperties boolean ?-progress callback?
soundName record ?-input jack? ?-append boolean? ?-device inputDevice?
soundName reverse ?-start start? ?-end end? ?-progress callback?
soundName sample n ?value? ...
soundName speatures ?-start start? ?-end end? ?-channel channel? ?-framelength length? ?-windowlength length? ?-preemphasisfactor factor? ?-windowtype type? ?-nchannels n? ?-ncoeff n? ?-cepstrallifter boolean? ?-energy boolean? ?-zeromean boolean? ?-zerothcepstralcoeff boolean? ?-lowcutoff freq? ?-highcutoff freq?
soundName stop
soundName write filename ?-start start? ?-end end? ?-fileformat fileformat? ?-progress callback? -byteorder ?endianess?

NAME

snack::sound - Create and manipulate sounds

SYNOPSIS

snack::sound soundName

soundName option ?arg arg ...?

DESCRIPTION

The snack::sound command is used to create sound objects. Sound objects can interact with files, variables, canvas items and the audio hardware.

CREATING SOUNDS

The sound command is used to create sound objects. It can take several different forms, depending on the option argument. The legal forms are:

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.
soundName cget option
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.
soundName changed flag
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, if individual samples are changed using the sample command these will not be tracked for performance 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.
soundName concatenate sound
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.
soundName configure option value ...
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.
soundName convert option value ...
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.
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], i.e. all samples before and after these limits will be removed. This command applies to in-memory sounds only.
soundName cut start end
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.
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 ?-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.

soundName destroy
Removes the sound command and frees the storage associated with it.
soundName dBPowerSpectrum ?-start sample? ?-end sample? ?-fftlength length? ?-windowlength length? ?-windowtype type? ?-skip samples? ?-channel channel? ?-preemphasisfactor factor? ?-analysistype type? ?-lpcorder n?
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.
soundName filter filterName ?-start sample? ?-end sample? ?-continuedrain boolean? ?-progress callback?
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.
soundName flush
Removes all audio data from the sound. This command applies to in-memory sounds only.
soundName formant ?-start sample? ?-end sample? ?-framelength t? ?-numformants n? ?-windowlength length? ?-preemphasisfactor factor? ?-windowtype type? ?-lpctype? ?-lpcorder n? ?-ds_freq? ?-nom_f1_freq? ?-progress callback?
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.
soundName info
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"}
soundName insert sound position ?-start start? ?-end end?
Inserts sound at position. Optionally a range of samples to insert can be specified. This command applies to in-memory sounds only.
soundName lastIndex
Returns the last sample index of the sound object.
soundName length ?n? ?-unit 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 channel?
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.
soundName min ?-start start? ?-end end? ?-channel channel?
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.
soundName mix sound ?-start start? ?-end end? ?-mixscaling factor? ?-prescaling factor? ?-progress callback?
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.
soundName pause
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.
soundName pitch ?-method m? ?-start start? ?-end end? ?-framelength t? ?-windowlength length? ?-maxpitch val? ?-minpitch val? ?-progress callback?
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.
soundName play ?-start start? ?-end end? ?-output jack??-blocking boolean? ?-command callback? ?-device outputDevice? ?-filter filter? ?-devicerate f? ?-devicechannels n?
Plays a sound. A start position can be specified using the -start option and an end position using the -end option. The values should be given in samples and the end of the sound can be given as -1. 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.
soundName power ?-start sample? ?-end sample? ?-framelength length? ?-windowlength length? ?-windowtype type? ?-preemphasisfactor factor? ?-channel channel? ?-progress callback?
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.
soundName powerSpectrum ?-start sample? ?-end sample? ?-fftlength length? ?-windowlength length? ?-windowtype type? ?-skip samples? ?-channel channel? ?-preemphasisfactor factor? ?-analysistype type? ?-lpcorder n?
Computes the FFT power spectrum of the sound at -start and returns a list of magnitude 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.
soundName read filename ?-fileformat fmt? ?-rate f? ?-channels n? ?-encoding fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-guessproperties boolean? ?-progress callback?
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.
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? ?-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

soundName reverse ?-start start? ?-end end? ?-progress callback?
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.
soundName sample n ?value? ...
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.
soundName speatures sound ?-start start? ?-end end? ?-channel channel? ?-framelength length? ?-windowlength length? ?-preemphasisfactor factor? ?-windowtype type? ?-nchannels n? ?-ncoeff n? ?-cepstrallifter boolean? ?-energy boolean? ?-zeromean boolean? ?-zerothcepstralcoeff boolean? ?-lowcutoff freq? ?-highcutoff freq?
Compute speech recognition feature vectors. The resulting parameters will be stored in sound. Parameterization and options are compatible with the ones used by the The Hidden Markov Model Toolkit (HTK).
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. Any callbacks registered using the -command option of the play command will not be executed.
soundName write filename ?-start start? ?-end end? ?-fileformat fileformat? ?-byteorder endianess? ?-progress callback?
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

spectrogram - Spectrogram canvas item

SYNOPSIS

pathName create spectrogram x y ?options value option value ...?

OPTIONS

-anchor anchorPos
-brightness value
-channel channel
-colormap colorlist
-contrast value
-debug level
-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
-windowtype type
-winlength length

DESCRIPTION

This command draws the spectrogram of a sound. The options -anchor, and -tags work as for other 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). The default value is 256. The option -windowtype is used to select windowing function, (valid values are Hamming, Hanning, Bartlett, Blackman, or Rectangle). The default window type is Hamming. -winlength specifies the size of the hamming window, which should be equal to or less than the number of FFT points. The default window length is 128. -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to the FFT calculation, default 0.97. -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. Currently, spectrograms have a width limit of 32767 pixels. 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 with the default being 0.0. -topfrequency is the frequency value at the top of the spectrogram, default is the Nyquist frequency. -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. The flag -debug is used to control debug output for the item. The option takes a level argument, an integer in the range 1-5, specifying the detail of the trace information.
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
-analysistype type
-channel channel
-debug level
-end sample
-fftlength length
-fill color
-frame boolean
-height size
-lpcorder n
-maxvalue value
-minvalue value
-preemphasisfactor factor
-skip points
-sound name
-start sample
-stipple value
-tags tagList
-topfrequency frequency
-width size
-windowtype type
-winlength length

DESCRIPTION

This command draws the FFT log power spectrum section of a sound. The options -anchor, -fill, -stipple, and -tags work as for other 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). The default value is 512. The option -windowtype is used to select windowing function, (valid values are Hamming, Hanning, Bartlett, Blackman, or Rectangle). The default window type is Hamming. -analysistype is either FFT (default) or LPC, for LPC analysis the order is specified using -lpcorder (default 20). -winlength specifies the size of the window, which should be equal to or less than the number of FFT points. The default window length is 128. -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to the FFT calculation (default 0.0). -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 around the spectrum section. The flag -debug is used to control debug output for the item. The option takes a level argument, an integer in the range 1-5, specifying the detail of the trace information.
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 channel
-debug level
-end sample
-fill color
-frame boolean
-height size
-limit value
-pixelspersecond value
-progress procedure
-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. The options -anchor, -fill, -stipple, and -tags work as for other 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. 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 maximum shown value for the sound amplitude. -zerolevel specifies whether the zero level will be displayed (default yes) and -frame whether a frame will be drawn around the waveform (default no). 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 this because a large value could lead to an incorrect envelope shape. The option -shapefile is used to specify a file for storing/retrieving precomputed waveform shape information. The file specified is created if it does not already exist. If it exists it is accessed instead of the sound data itself, thus speeding up on-screen display. There exists two convenience routines, snack::deleteInvalidShapeFile and snack::makeShapeFileDeleteable, which can be used to enclose a create waveform statement when using the shape file functionality. These will make sure that shape files are handled properly, see the demo cool.tcl, for an example of this. See the read command for a description on how to use the -progress option. The flag -debug is used to control debug output for the item. The option takes a level argument, an integer in the range 1-5, specifying the detail of the trace information.
See also code examples in the widget demonstration.

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.

Snack home