Sound Plug-in Scripting Reference

Overview

The sound plugin implements sound effects that can be played, replayed, looped, or panned.

The sounds can be imported or exported from a variety of sound file formats as necessary.

Sounds are displayed as a wave table, so usually you will attach a sound to the object that uses it and then hide the sound.

Messages: nodestart, nodestop, nodemove, nodechange

Nodemove is sent when the position of the sound object changes.

Nodechange is sent when the sound's data changes.

Nodestop is sent when the sound is finished.

Nodestart is sent when the sound begins playing.

Commands and Functions

binaryget, binaryset

binary data $ = binaryget(node name $)
binaryset(node name $, binary data $)

Get or set binary data for any sound.

This routine is useful for serialization into xml and trading data between sounds.

boundsget, boundsset

rectangle $ = boundsget(node name $)
boundsset(node name $, rectangle $)

Get or set the boundary rectangle of the sound.

bytespersample

bytes per sample # = bytespersample(node name $)

Returns the bytes per sample for the sound.

compressionmethod

compression method $ = compressionmethod(node name $)

Returns the compression method for the sound, currently: standard or adpcm.

deletedata

deletedata(node name $)

Delete the data associated with this sound, if any.
See: isloaded

durationinms

duration in milliseconds # = durationinms(node name $)

Returns the sound duration in milliseconds. This is useful for creating a sound finished callback.

export

export(node name $, file name $)

Export the wave data. If no file is specified the user can select the export format and the file.

fullget, fullset, infoget, infoset

full $ = fullget(node name $)
fullset(node name $, full $)
info $ = infoget(node name $)
infoset(node name $, info $)

Get or set XML data that describes all the settings for this node.

The fullget and fullset routines have a header element with appropriate namespaces, infoget and infoset are an XML snippet for access as a property. Example:

mynode.info.title = "new title"

handlesget, handlesset

handles TF = handlesget(node name $)
handlesset(node name $, handles TF)

Turn on or off dragable handles for reshaping the node.

This routine is used by the system tool palettes for manual positioning.
See: markersget, markersset, partget, partset

hittest

hit TF = hittest(node name $, hor #, ver #)

Returns true if the point is in the sound.

import

import(node name $, file name $, is looped TF, compression method $)

Import wave data into a sound. Set the looped parameter to true if the sound will be used as a looped sound.

Compression method can be: user, standard, or adpcm.

The user method brings up a dialog for the user to select a compression method.

Standard is the Dreamfactory standard compression for high quality, adpcm is good for music.

isloaded

is loaded TF = isloaded(node name $)

Returns true if the sound has imported data and can be played.

isplaying

is playing TF = isplaying(node name $)

Returns true if the sound is currently playing.

lockedget, lockedset

is locked TF = lockedget(node name $)
lockedset(node name $, locked TF)

Use lockedset to preload a sound into RAM and lock it there.

loopget, loopset

loop TF = loopget(node name $)
loopset(node name $, loop TF)

Get or set the sound looping property. If true, the sound will loop when played.
See: import

makecall

result $ = makecall(phone number $, called name $, message $)

This command brings up a platform specific auto dialer dialog for starting a phone call.

The phone number string should be in human readable format, for Example:

"(408) 399-7454".

The called name and message are usually presented to the end user, depending on the platform specific implementation.

markersget, markersset

markers TF = markersget(node name $)
markersset(node name $, markers TF)

Turn on or off the node outline to show selection.

This routine is used by the system tool palettes to show that a node is selected.
See: handlesset, handlesget, partget, partset

panget, panset

pan # = panget(node name $)
panset(node name $, pan #)

Get or set the sound pan. This ranges from 0, for full left, to 255 for full right channel.

partget, partset

part # = partget(node name $, hor #, ver #)
partset(node name $, hor #, ver #, part #)

Get or set the points for an individual handle.
See: markersget, markersset, handlesset, handlesget

play

play(node name $)

Play the sound if it is loaded with imported wave data.

If the sound is currently playing nothing happens.
See: isloaded, import

priorityget, priorityset

priority # = priorityget(node name $)
priorityset(node name $, priority #)

Get or set the sound priority. This ranges from 0 for low priority to any number for higher priority.

The priority allows a set of prioritized sounds to be played over a limited number of channels.

record

record(node name $, sample rate #, bytes per sample #, compression method $, max length in millisecs #)

This command brings up a modal dialog and allows the user to record sound.

Sample rate must be 11025, 22050 or 44100. Bytes per sample must be 1 or 2.

Compression method must be: user, standard, or adpcm. User brings up a dialog to select standard or adpcm.

replay

replay(node name $)

Play the sound if it is loaded with imported wave data.

If the sound is currently playing it will be stopped and played again on the same channel.
See: isloaded, import

samplerate

sample rate # = samplerate(node name $)

Returns the sampling rate for the sound, 44100, 22050, or 11025.

sizedecompressed

size decompressed # = sizedecompressed(node name $)

Returns the decompressed size of the sound.

sizepacked

size packed # = sizepacked(node name $)

Returns the packed size of the sound. All sounds are stored compressed in memory and unpacked on the fly.

This is why displaying visible sound waveforms is not very fast.

stop

stop(node name $)

Stop the sound from playing.

volumeget, volumeset

volume # = volumeget(node name $)
volumeset(node name $, volume #)

Get or set the sound volume. This ranges from 0 for silent to 255 for full volume.

wavechannels

sound channels # = wavechannels()

Returns the number of currently allocated sound channels.
See: wavestart, wavestop, wavevolumeset

wavestart

wavestart(sound channels #)

Starts up the entire sound engine. Specify the desired number of sound channels for the session.
See: wavestop, wavechannels, wavevolumeset

wavestop

wavestop()

Stops up the entire sound engine.
See: wavestart, wavechannels, wavevolumeset

wavevolumeget, wavevolumeset

current volume # = wavevolumeget()
wavevolumeset(current volume #)

Set the master volume for the sound engine. The value can be between 1 and 10.
See: wavestart, wavestop, wavechannels