Class Documentation

Name:Sound
Version:1.0
ID:ID_SOUND
Status:Stable
Category:Audio
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2002-2003. All rights reserved.
Short:  Plays and records sound samples in a variety of different data formats.



Description

The purpose of the Sound class is to provide the means for any program to load and play sound files. By default all loading and saving of sound data is in WAVE format. Other audio formats can be supported through Sound class extensions, if available.

The Sound class uses an abstract channeling and mixing system, so you will never have to be concerned with channel numbers when playing audio. Left and right speakers are fully supported for stereo playback. If necessary you can use the panning support to play samples through a single speaker.

Smart, transparent streaming is enabled by default. This means that if you try to play an audio file that is considerably larger than normal, the sound object will opt to play it from disk. You can alter or force streaming behaviour through the Stream field.

The Sound class is fully compatible with the Dynamic Markup Language. The following example illustrates playback of a sound sample one octave higher than its normal frequency:

   <sound src="athene:audio/samples/nocturnalsilence.wav" note="C6"/>

When used in scripting, a sound object will automatically destroy itself once the audio sample has played through to the end. You can prevent this behaviour if you make the sound static, or enable the LOOP flag to play the sample continuously.

Actions

The Sound class supports the following actions:

Activate  Plays an audio sample.
ClosingTag  If the object is non-static, this action will start the execution process and then the object will self-destruct.
Deactivate  Stops the audio sample and resets the playback position.
Disable  Temporarily pauses a sound up until the next Enable action.
Enable  Continues playing a sound if it has been disabled.
GetUnlistedField  This action is supported for retrieving unlisted field values.
Init  Prepares a sound object for usage.
Reset  Stops audio playback, resets configuration details and restores the playback position to the start of the sample.
SaveToObject  Saves Sound data to a data object.
Seek  Seeks to a new position within a Sound object.
SetUnlistedField  Descriptive tags may be attached to a sound object via the unlisted field mechanism.

Structure

The Sound object consists of the following public fields:

Active  Returns TRUE if the sound is currently playing.
Audio  Refers to an audio object to use for digital audio output.
Author  The name of the person or company that created the sound sample.
BitsPerSample  Indiates the bit rate of the audio sample.
BufferLength  Defines the size of the buffer to use when streaming is enabled.
BytesPerSecond  The flow of bytes-per-second when the sample is played at normal frequency.
Compression  Determines the amount of compression used when saving an audio sample.
Copyright  Copyright details of an audio sample.
Data  Points to the sampled data of a sound object.
Description  Long description for an audio sample.
Disclaimer  The disclaimer associated with an audio sample.
Flags  Optional initialisation flags.
Frequency  The frequency of a sampled sound is specified here.
Header  Contains the first 128 bytes of data in a sample's file header.
Length  Indicates the total byte-length of sample data.
Location  The location of a Sound's audio data.
LoopEnd  The byte position at which sample looping will end.
LoopStart  The byte position at which sample looping begins.
Note  The musical note to use when playing a sound sample.
Octave  The octave to use for sample playback.
Pan  Determines the horiziontal position of a sound when played through stereo speakers.
Playback  The playback frequency of a sound sample can be altered here.
Position  The current playback position.
Priority  The priority of a sound in relation to other sound samples being played.
Software  The name of the application that was used to record a sample.
Static  Set to TRUE to make the object static.
Stream  Tells the system what method it should use in determining whether a sample needs to be streamed.
Title  The title of the audio.
Volume  The volume to use when playing a sound sample.
Field:Active
Short:Returns TRUE if the sound is currently playing.
Type:LONG
Status:Get

Read this field if you need to know wether or not the sound object is currently playing through the audio system.


Field:Audio
Short:Refers to an audio object to use for digital audio output.
Type:LONG
Status:Read/Init

If you would like to specify an audio object to use for the output of digital audio, you may make a reference to that object here. Otherwise, you should leave this field as is and the sound object will select the default "SystemAudio" object on initialisation.


Field:Author
Short:The name of the person or company that created the sound sample.
Type:STRING
Status:Unlisted

The name of the person or organisation that created a sample's audio data is normally specified here. This provides a means for the original author to claim credit for the audio sample.


Field:BitsPerSample
Short:Indiates the bit rate of the audio sample.
Type:LONG
Status:Read

This field is set when you initialise an audio sample. You will typically find that it is set to value of 8 or 16 to indicate an 8-bit or 16-bit sample rate.


Field:BufferLength
Short:Defines the size of the buffer to use when streaming is enabled.
Type:LONG
Status:Read/Init

You can set this field if you wish to precisely alter the size of the buffer to use when streaming. When manually choosing a buffer size, it is usually best to keep the size between 64 and 128k. Some systems may ignore the BufferLength field if the audio system uses a streaming method that is incompatible with this field.


Field:BytesPerSecond
Short:The flow of bytes-per-second when the sample is played at normal frequency.
Type:LONG
Status:Read

This field is set on initialisation. It tells you the total number of bytes per second that will be played if the sample is played back at its normal frequency.


Field:Compression
Short:Determines the amount of compression used when saving an audio sample.
Type:LONG
Status:Read/Write

Setting the Compression field will determine how much compression is applied when saving an audio sample. The range of compression is 0 to 100%, with 100% being the strongest level available while 0% is no compression. This field is ignored if the file format does not support compression.


Field:Copyright
Short:Copyright details of an audio sample.
Type:STRING
Status:Unlisted

Copyright details related to an audio sample may be specified here. The copyright should be short and to the point, for example "Copyright Beacon (c) 2002. All rights reserved."


Field:Data
Short:Points to the sampled data of a sound object.
Type:APTR
Status:Get/Init

This field points to the actual sample data contained by a sound object. The length of the data is specified in the object's Length field. For platform compatibility reasons, you need to call the Lock action on a sound object before reading the Data field. When are finished with the sample data, call the Unlock action to update the sound object with your changes.

This field may return a value of NULL if it is not possible to gain access to sample data.


Field:Description
Short:Long description for an audio sample.
Type:STRING
Status:Unlisted

A long description for an audio sample may be entered in this field. There is no strict limit on the length of the description. It is recommended that this field be used to describe what the audio was recorded from.


Field:Disclaimer
Short:The disclaimer associated with an audio sample.
Type:STRING
Status:Unlisted

If it is necessary to associate a disclaimer with an audio sample, the legal text may be entered in this field.


Field:Flags
Short:Optional initialisation flags.
Type:LONG
Prefix:SDF
Status:Read/Init

You can specify flags in this field that will affect sound object behaviour. Valid flags are:

FlagDescription
LOOPEnables sample looping. The LoopStart and LoopEnd fields determine where the looping area lies within the sample data.
NEWSet this flag if you are creating a sound sample from scratch (e.g. for audio recording purposes).
QUERYIf you set this flag then the sound object will retrieve sample information from the sound source, but will not load the sample data when you initialise the object.
RESTRICTPLAYThis flag restricts the sample playback so that it can only play on one audio channel at any given time. This is very useful if the sample is played very often and you do not want it taking up all of the available audio channels.
STEREOThis flag is set automatically on initialisation if the sound sample has left and right output channels.
STREAMThis read-only flag indicates that streaming has been enabled.
TERMINATEIf set, the sound object will automatically kill itself when the audio has completely played through.

Field:Frequency
Short:The frequency of a sampled sound is specified here.
Type:LONG
Status:Get/Set

This field specifies the frequency of the sampled sound data. If the frequency cannot be determined from the Source, this field may remain as NULL. Please note that if you want to set the level of frequency that is used when the sound is played, you need to set the Playback field.


Field:Header
Short:Contains the first 128 bytes of data in a sample's file header.
Type:POINTER
Status:Get

The Header field is a pointer to a 128 byte buffer that contains the first 128 bytes of information read from an audio file on initialisation. This special field is considered to be helpful only to developers writing add on components for the sound class.

The buffer that is referred to by the Header field is not populated until the Init action is called on the sound object.


Field:Length
Short:Indicates the total byte-length of sample data.
Type:LONG
Status:Get/Set

This field specifies the length of the sample data in bytes. To get the length of the sample in seconds, divide this value by the BytesPerSecond field.


Field:Location
Short:The location of a Sound's audio data.
Type:STRING
Status:Get/Set

This field must refer to a file that contains the audio data that you want to load. If you are creating a new sound object by setting the NEW flag, you can avoid setting the Location field.


Field:LoopEnd
Short:The byte position at which sample looping will end.
Type:LONG
Status:Read/Set

When using looped samples (though the SDF_LOOP flag) you can opt to set the LoopEnd field if you wish for the sample to end at a position that is earlier than the sample's actual length. The LoopEnd value is specified in bytes and must be less or equal to the length of the sample and greater than the LoopStart variable.


Field:LoopStart
Short:The byte position at which sample looping begins.
Type:LONG
Status:Read/Set

When using looped samples (though the SDF_LOOP flag) you can opt to set the LoopStart field if you wish for the loop to begin at a position other than zero. The LoopStart value is specified in bytes and must be less than the length of the sample and the LoopEnd variable.

Note that the LoopStart variable does not affect the position at which playback occurs for the first time - it only affects the restart position when the end of the sample is reached.


Field:Note
Short:The musical note to use when playing a sound sample.
Type:LONG/STRING
Status:Read/Set

Set the Note field when you want to alter the playback frequency of a sound sample. By setting this field as opposed to the Playback frequency, you can assure that the sample is played at correct scale.

The Note field can be set using either string or integer based format. If you are using the integer format, the number that you choose reflects on the position on a musical keyboard. A value of zero refers to the middle C key. Each octave is measured in sets of 12 notes, so a value of 24 would indicate a C note at 3 times normal playback. To play at lower values, simply choose a negative integer to slow down sample playback.

Setting the Note field with the string format is useful if human readability is important to you. The correct format here is "KEY,OCTAVE,SHARP". Here are some examples:

   C5, D7#, G2, E3S

The middle C key for this format is "C5". The maximum octave that you can achieve for the string format is 9 and the lowest is 0. You can use either the S character or the # character for referral to a sharp note.


Field:Octave
Short:The octave to use for sample playback.
Type:LONG
Status:Read/Set

The Octave field determines the octave to use when playing back a sound sample. The default setting is zero, which represents the octave at which the sound was sampled. Setting a negative octave will lower the playback rate, while positive values raise the playback rate. The minimum octave setting is -5 and the highest setting is +5.

The octave can also be adjusted by setting the Note field. Setting the Octave field directly is useful if you need to quickly double or halve the playback rate.


Field:Pan
Short:Determines the horiziontal position of a sound when played through stereo speakers.
Type:FLOAT
Status:Read/Set

Altering the Pan field allows you determine the "horizontal position" when a sound is played through stereo speakers. The default value for this field is zero, which plays the sound through both speakers. The minimum value is -100, which forces play through the left speaker and the maximum value is 100, which forces play through the right speaker.


Field:Playback
Short:The playback frequency of a sound sample can be altered here.
Type:LONG
Status:Read/Set

Set this field if you want to determine the exact frequency of a sample's playback. You can set the playback frequency at any time, this includes during audio playback if you want to make real-time adjustments to a sample's audio output rate.


Field:Position
Short:The current playback position.
Type:LONG
Status:Get/Set

The current playback position of the audio sample is indicated in this field. You may read this field at any time to determine the current byte position of a playing sample. Writing to the field will alter the position of the playback header, either when the sample is next played, or immediately if it is currently playing.


Field:Priority
Short:The priority of a sound in relation to other sound samples being played.
Type:LONG
Status:Get/Set

The priority of your Sound goes here. This field is used to determine if your Sound should be played when all available channels are busy. Naturally, higher priorities are played over samples with low priorities.

The minimum priority value allowed is -100, the maximum is 100.


Field:Software
Short:The name of the application that was used to record a sample.
Type:STRING
Status:Unlisted

The Software field declares the name of the application that was used to record or generate the original audio data.


Field:Static
Short:Set to TRUE to make the object static.
Type:BOOLEAN
Status:Read/Init

To make the object static, set this field to TRUE. If the object is not made static then it will self-destruct when a closing tag is received.


Field:Stream
Short:Tells the system what method it should use in determining whether a sample needs to be streamed.
Type:LONG
Prefix:STREAM
Status:Read/Init

Set the Stream field when you want to tell the system exactly how you want it to determine streaming behaviour. The following table illustrates your options:

CommandDescription
NEVERThis option turns off streaming altogether. The sound class will make every attempt to load the entire sample into memory.
SMARTSmart streaming is the default. If the sample appears to be relatively small with respect to available system RAM, it will be loaded into memory. Otherwise it will be streamed.
ALWAYSThis option ensures that the sample will be streamed, assuming its size is greater than 32k.

Field:Title
Short:The title of the audio.
Type:STRING
Status:Get/Set

If the author of a sound sample has assigned a title to it, then it must be declared through the Title field.


Field:Volume
Short:The volume to use when playing a sound sample.
Type:LONG
Status:Read/Set

The field specifies the volume of a sound, which lies in the range 0 - 100%. A volume of zero will not be heard, while a volume of 100 is the loudest. Using SetField() allows you to dynamically alter a sample's volume while it is playing.