controlsound statement

controlsound

IDENTIFIER

PROPERTY

VALUE

The controlsound statement controls playback of a sound file.

Parameters

This statement has three parameters:

identifier – identifier for the sound (sound must already be playing).

property – playback command or optional sound property. See below for detailed descriptions of the different playback commands and sound properties that can be specified. Properties can be specified in either upper or lower case, for example STOP or stop.

value – the value for the property specified by the previous parameter.

Description

This statement controls playback of a sound file. Before using the controlsound statement you must already have started playback of the sound file, and you must have specified an identifier for the sound. In this example, playback has been started with the identifier specified as Chimes.

playsound "~/Sounds/Big Ben Chime.aiff","IDENTIFIER","Chimes"

For the duration of the playback of this sound, you can control the sound with the controlsound statement. For example, this code would pause the chimes.

controlsound "Chimes","pause"

Later, the chimes could be resumed from where they left off like this:

controlsound "Chimes","play"

Or, you could start the playback over from the beginning:

controlsound "Chimes","position",0,"play"

If the specified sound has finished playing (or has been stopped), the controlsound statement will stop with an error. This code first tries to resume the Chimes sound. If the sound wasn’t already playing, it starts the playback from scratch.

controlsound "Chimes","play"
if error
    playsound "~/Sounds/Big Ben Chime.aiff","IDENTIFIER","Chimes"
endif

The procedure doesn’t wait for the sound to finish playing. The specified sound will be played in the background. The sound duration could be one second or it could be five hours, it doesn’t matter – once the sound is started it will continue to play while you perform other tasks. In the example above the chimes will continue to play until they finish – you can’t pause or stop them.

Playback Commands

There are three playback commands available: pause, play (or resume) and stop.

The pause command temporarily pauses sound playback. Though the sound temporarily stops playing, it is still active so you can send it further commands.

The play command resumes playback from the previously paused spot. You can also use resume.

The stop command stops the playback. Once you have issued this command, the sound is over - you can’t send any further commands. If the sound has code associated with it (see the playsound statement) that code will automatically run.

Playback Position

Usually a sound plays sequentially from start to finish. However, you can “jump” the sound to any spot. This code will jump the sound to the one minute mark (60 seconds).

controlsound "Interview","position",60

Note: You can use the soundinfo( function to find out the current position of the sound.

let soundDictionary = soundinfo("Interview")
let currentPosition = val(getdictionaryvalue(soundDictionary,"Position","0"))

Volume

Usually a sound is played at maximum volume based on the overall volume settings for your computer. You can, however, play a sound at a relatively reduced volume. The volume is specified from 0 (muted) to 1 (full volume according to your computer volume settings). For example, this code changes the chimes to half volume.

controlsound "Chimes","VOLUME",0.5

See Also

info("sounds") -- returns a carriage return delimited list of all currently playing sounds.
playsound -- starts playing a sound file.
soundduration( -- returns the duration (in seconds) of the specified playing sound.
sounddurationhhmmss( -- returns the duration (in hours:minutes:seconds) of the specified playing sound.
soundinfo( -- returns a dictionary that contains all of the properties of a sound.
soundplaying( -- returns true if the specified sound is currently playing, false if it is paused or not playing at all.
soundposition( -- returns the current playback position (in seconds) of the specified playing sound.
soundpositionhhmmss( -- returns the current playback position (in hours:minutes:seconds) of the specified playing sound.
soundprogress( -- returns the progress of the played sound from 0 to 1.
soundstatus( -- returns the status of the specified sound: stopped, playing or paused.
soundvolume( -- returns the current volume of the specified playing sound.

History

Version	Status	Notes
10.2	New	New in this version.