Snack v2.0b2 manual

snack::audio

snack::filter

snack::mixer

snack::sound

spectrogram canvas item

spectrum section canvas item

waveform canvas item

 

Snack library

NAME

SYNOPSIS

DESCRIPTION

snack::audio encodings

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

Returns a list of supported sample rates for the currently 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 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.

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

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

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 should be specified with values row by row. One column per channel is needed. If mono or stereo output is used, only one respective two rows need to be specified.

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.

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 second and so on.

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?

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, Lin24, Lin32, Float, Alaw, or Mulaw. -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 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. The option -precision is used to specify if sound data is to be handled using simple or double precision internally.

SOUND COMMAND

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 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.

Concatenates the sample data from sound to the end of soundName. The sounds must be of the same type, i.e. have the same sample rate, 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, -rate, -channels, -encoding, -skiphead, -byteorder, -guessproperties, -precision, 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 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. 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.

Applies the filter filterName to the sound. This command applies to in-memory sounds only.

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 rate max min encoding 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 number of instances playing of a sound object all of them are paused 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 starts to play as soon as possible. The lag before this new sound is audible can be controlled using the snack::audio latency command. 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? ?-filter filter? ?-rate? ?-channels?

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. 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 -rate and -channels, useful if exact control is needed. The option -starttime is used to schedule the start of playback (in ms) relative to a previous play operation.

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 properties of the sound data can 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, 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 sample rate 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

The command package require snack gives you access to all commands described above.
There is also a package called sound which gives you the sound::audio, sound::filter, sound::mixer, and sound::sound commands which are equivalent to their snack counterparts. This is useful on some systems if you want to use the tclsh interpreter.