Snack sound extension commands v1.7.0

Last updated 

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

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

SYNOPSIS

snack::audio property ?arg? ...

DESCRIPTION

snack::audio formats snack::audio frequencies snack::audio inputDevices
Returns a list of available audio input devices.
snack::audio play_gain ?value? snack::audio outputDevices
Returns a list of available audio output devices.
snack::audio record_gain ?value? snack::audio selectOutput ?device?
Selects an audio output device to be used as default.
snack::audio selectInput ?device?
Selects an audio input device to be used as default.

BUGS

        This command is beta.

NAME

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

SYNOPSIS

snack::mixer property ?arg? ...

DESCRIPTION

snack::mixer channels line snack::mixer devices
Returns a list of available mixer devices.
snack::mixer input ?jack? snack::mixer inputs snack::mixer lines snack::mixer output ?jack? snack::mixer outputs snack::mixer volume line ?varName? ?varName? snack::mixer select ?device?
Selects a mixer device to be used as default.

BUGS

        This command is in a beta state.



NAME
        snack::sound - Create and manipulate sounds
SYNOPSIS
        snack::sound ?name? ?options?
DESCRIPTION
CREATING SOUNDS
        snack::sound ?name? ?-load filename?  ?-file filename?  ?-channel channelname? ?-frequency f? ?-channels n? ?-format fmt?
SOUND COMMAND
soundName append variable ?-frequency f? ?-channels n? ?-format fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-guessproperties boolean?
soundName byteswap
soundName cget option
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 ?-frequency f? ?-channels n? ?-format 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 value -preemphasis factor
soundName flush
soundName info
soundName insert sound position ?-start start? ?-end end?
soundName max ?-start start? ?-end end? ?-channel value?
soundName min ?-start start? ?-end end? ?-channel value?
soundName length ?n? ?-units u?
soundName pause
soundName pitch ?-start start? ?-end end? ?-maxpitch val? ?-minpitch val? ?-progress callback?
soundName play ?-start start? ?-end end? ?-output jack? ?-blocking boolean? -command ?callback?
soundName read filename ?-frequency f? ?-channels n? ?-format fmt? ?-skiphead n? ?-byteorder endianess??-start start? ?-end end? ?-guessproperties boolean?
soundName record ?-input jack? ?-append boolean?
soundName reverse ?-start start? ?-end end?
soundName sample n ?value? ...
soundName stop
soundName write filename ?-start start? ?-end end? ?-fileformat fileformat? ?-progress procedure? -byteorder ?endianess?


NAME

snack::sound - Create and manipulate sounds

SYNOPSIS

snack::sound soundName

soundName option ?arg arg ...?

DESCRIPTION

A sound is an object which handles audio data. Sound objects can interact with files, variables, canvas items and the audio hardware.

CREATING SOUNDS

The sound command is used to create, delete, and operate on 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? ?-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

When a sound object is created, Tcl also creates a new command whose name is the same as the sound. This command may be used to invoke various operations on the sound. The following commands are possible for sounds objects:

soundName append variable ?-frequency f? ?-channels n? ?-format fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-fileformat fmt? ?-guessproperties boolean?

soundName byteswap soundName cget option soundName concatenate sound soundName configure option value ... soundName convert option value ... soundName copy sound ?-start start? ?-end end? soundName crop start end soundName cut start end soundName data ?variable? ?option value? ... soundName destroy soundName dBPowerSpectrum ?-start sample? ?-end sample? ?-fftlength length? ?-windowlength length? ?-skip samples? ?-channel value? ?-preemphasisfactor factor? soundName flush soundName info soundName insert sound position ?-start start? ?-end end? soundName length ?n? ?-units u? soundName max ?-start start? ?-end end? ?-channel value? soundName min ?-start start? ?-end end? ?-channel value? soundName pause soundName pitch ?-start start? ?-endend? ?-maxpitch val? ?-minpitch val? ?-progress callback? soundName play ?option value? ... soundName read filename ?-fileformat fmt? ?-frequency f? ?-channels n? ?-format fmt? ?-skiphead n? ?-byteorder endianess? ?-start start? ?-end end? ?-guessproperties boolean? ?-progress procedure? soundName record ?option value? ... soundName reverse ?-start start? ?-end end? soundName sample n ?value? ... soundName stop soundName write filename ?-start start? ?-end end? ?-fileformat fileformat? ?-byteorder endianess? ?-progress procedure?


NAME

spectrogram - Spectrogram canvas item

SYNOPSIS

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

OPTIONS

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

DESCRIPTION

This command draws a spectrogram of a sound on a canvas. The options -anchor, and -tags work as for ordinary 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), -winlength specifies the size of the hamming window, which should be equal to or less than the number of FFT points. -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to the FFT. -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. 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. -topfrequency is the frequency value at the top of the spectrogram. -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. Currently spectrograms have a width limit of 32767 pixels.
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
-channel value
-end sample
-fftlength length
-fill value
-frame boolean
-height size
-maxvalue value
-minvalue value
-preemphasisfactor factor
-skip points
-sound name
-start sample
-stipple value
-tags tagList
-topfrequency frequency
-width size
-winlength length

DESCRIPTION

This command draws an FFT log power spectrum section of a sound on a canvas. The options -anchor, -fill, -stipple, and -tags work as for ordinary 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), -winlength specifies the size of the hamming window, which should be equal to or less than the number of FFT points. -preemphasisfactor is used to specify the amount of preemphasis applied to the signal prior to the FFT. -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.
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 value
-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 on a canvas. The options -anchor, -fill, -stipple, and -tags work as for ordinary 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 which also gives the width. 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 maximal shown value for the sound amplitude. -zerolevel specifies whether the zero level will be displayed and -frame whether a frame will be drawn. 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 values. Using large values may lead to incorrect envelope shapes. The option -shapefile is used to specify a file for storing/retrieving precomputed waveform shape information. If the file doesn't exist it is created. 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.
See also code examples in the widget demonstration.



Snack home