$image\logo.gif$ xch_sound

This is an <img> field which specifies a command related to sound.

The xch_sound tag may have the following values:

play	Begins playing the associated href.
loop	Begins playing the associated href. The sound will loop continuously until a 'play', ‘stop’ or 'stoploop' is received.
stop	Stops any currently playing sound immediately.
stoploop	Stops any currently playing sound at the end of the current loop.

Other Attributes

HREF

If the play or loop values are specified, then this tag specifies the URL of the sound file.

EVENT

This attribute specifies the sound events that should cause commands to be sent to the world. The following events are currently supported:

complete

A command will be sent when the sound file finishes playing.

Note: This event will not be triggered if the sound file is terminated via an xch_sound=stop command. The 'complete' event is only sent when the sound file plays to completion (this includes when stopped via xch_sound=stoploop).

For a more complete explanation of event notification, see the section below.

MD5

This attribute specifies the MD5 value for this user. The MD5 value is passed to the world server through the PUEBLOCLIENT command.

This attribute is used only when method=xch_cmd is specified.

ACTION

If the MD5 attribute is specified, then the action attribute may be specified to override the command sent to the world when a requested sound event occurs. If this attribute is not specified, or the MD5 attribute is incorrect or missing, then the PUEBLOSOUND command is sent.

OPTIONS

This attribute specifies options for the sound command. Options must be specified in a string delimited with spaces or commas. A combination of the following options may be used:

queue

If this option is specified, the sound file is queued if the sound device is busy playing another sound. This option may only be used with the xch_sound=play command.

If this option is not specified, then playing a sound causes any sounds using a device to terminate.

Event notification

You can be notified when a sound file has completed playing. You do this by specifying the event attribute and optionally the action and MD5 attributes.

The event attribute specifies the events for which you wish notification. Currently, the only event supported is the 'complete' event, which is triggered when the sound is finished playing. When this occurs, you receive the PUEBLOSOUND command followed by the event name. For example, if you specified the following command:

Then the specified MIDI file would play. When the end of the MIDI file was reached, the following command would be sent to the world:

PUEBLOSOUND complete

By definition, a looped sound never completes, so no 'complete' notification will ever be sent, unless you issue the ‘stoploop’ command.

Using the action and MD5 attributes, you can change the command that is sent to the world. The value of the action attribute is the command that is sent to the world, providing that the MD5 attribute matches the value sent to the world through the PUEBLOCLIENT command. For example, if the sound was played using the following command:

Then the specified WAVE file would play. When the end of the sound file was reached, the following command would be sent to the world:

_on_explosion complete

Examples

This tag loads the specified URL and begin playing the midi file:

Also see

Pueblo Enhancers Guide

xch_device

xch_volume

xch_speech