Class Documentation
Sound |
1.0 |
ID_SOUND |
Stable |
Audio |
December 2003 |
Rocklyte Systems |
Rocklyte Systems, 2002-2003. All rights reserved. |
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:
LOOP | Enables sample looping. The LoopStart and LoopEnd fields determine where the looping area lies within the sample data. |
NEW | Set this flag if you are creating a sound sample from scratch (e.g. for audio recording purposes). |
QUERY | If 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. |
RESTRICTPLAY | This 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. |
STEREO | This flag is set automatically on initialisation if the sound sample has left and right output channels. |
STREAM | This read-only flag indicates that streaming has been enabled. |
TERMINATE | If 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:
NEVER | This option turns off streaming altogether. The sound class will make every attempt to load the entire sample into memory. |
SMART | Smart 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. |
ALWAYS | This 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.
|
|