Class: TAudioSequence

Declaration: AudioSequence.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMediaSequence

Inherited By:

TAudioIFFSequence TQuickTimeAudioSequence

Purpose:

Represents raw digital sound data. It is an abstraction for a sequence of sound samples. To use the metaphor of a cassette and a cassette recorder, TAudioSequence represents a cassette. TAudioSequence can be handed to a TAudioPlayer, which can play the cassette. TAudioPlayer is like a tape recorder with a cassette in it. TAudioSequence has member functions that are used to access and modify the sound samples in the sequence. These functions use a memory-mapped interface, where the audio data is mapped into memory and directly accessed by the client. An audio sequence can be read-only.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TAudioIFFSequence derives from this class. Deriving classes must override the following pure virtual member functions: GetDurationInSamples, SeekToSample, GetPositionInSamples, Read, Write, and CreateSubrange. Deriving classes may need to override IsReadOnly (default behavior is to return true), and assignment, Hash, IsEqual, and streaming operators if new data members are added. Other responsibilities: Deriving classes must specify the audio type(s) they support and the number of channels they contain by calling AddAudioType and SetNumberOfChannels.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TAudioSequence::~TAudioSequence

virtual ~ TAudioSequence ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called by Runtime to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::SetChosenAudioType

virtual void SetChosenAudioType (const TAudioType & theChosenType)

Interface Category:

API.

Purpose:

Some sequences can supply data in a number of formats. This function sets the chosen type for the audio sequence. When reading data from a sequence, data of the chosen type is passed back. When writing data, the sequence expects the data of the chosen type.

Calling Context:

Called by deriving classes to specify default data format you want it to provide audio data. Requested type must have been previously added by a call to AddAudioType. Also called by base class stream-in operator. You can call CreatePreferredTypeList to see what types of audio data this sequence supports. You can call ChoosePreferredType to have the sequence return what it thinks should be the chosen type, given a set of possible types.

Parameters:

const TAudioType & theChosenType -The type you want the data supplied in.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kInvalidType if the requested type is not supported by the sequence.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::CreateChosenAudioType

TAudioType * CreateChosenAudioType () const

Interface Category:

API.

Purpose:

Some sequences can supply data in a number of formats. This function returns a copy of the chosen type for the audio sequence. When reading data from a sequence, data of the chosen type is passed back. When writing data, the sequence expects the data of the chosen type.

Calling Context:

Call directly to find out in what format the sequence will provide audio data. You can call CreatePreferredTypeList to see what types of audio data this sequence supports. You can call ChoosePreferredType to have the sequence return what it thinks should be the chosen type, given a set of possible types.

Parameters:

Takes no parameters.

Return Value:

A pointer to a copy of the selected audio type.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The client is responsible for deleting the storage associated with the pointer returned.

Member Function: TAudioSequence::IsReadOnly

virtual bool IsReadOnly () const

Interface Category:

API.

Purpose:

Returns true if the sequence cannot be written.

Calling Context:

Call directly to see if the sequence cannot be written.

Parameters:

Takes no parameters.

Return Value:

Returns true if the sequence cannot be written, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::GetNumberOfChannels

long GetNumberOfChannels () const

Interface Category:

API.

Purpose:

Returns the number of interleaved channels in the audio data. Some sequences store stereo and other multichannel formats as interleaved samples. For stereo, the left channel is stored first followed by the right channel.

Calling Context:

Call directly to determine how many channels are in the audio sequence.

Parameters:

Takes no parameters.

Return Value:

long -The number of channels of interleaved audio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::GetDurationInSamples

virtual TSamples :: Position GetDurationInSamples () const

Interface Category:

API.

Purpose:

Returns the total number of samples in the audio sequence.

Calling Context:

Call directly to determine how long the sequence is. Used by GetDuration.

Parameters:

Takes no parameters.

Return Value:

virtual TSamples :: Position -The number of samples.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::Seek

virtual void Seek (const TTime & position)

Interface Category:

API.

Purpose:

Seeks to a specific time in the sequence.

Calling Context:

Call directly to seek to a time.

Parameters:

const TTime & position -The time to seek to. You can pass in any TTime derived (for example TSeconds, TMilliseconds, TSamples).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::SeekToSample

virtual void SeekToSample (TSamples :: Position position)

Interface Category:

API.

Purpose:

Seeks to a specific sample position in the sequence.

Calling Context:

Call directly to seek to a specific sample. Used by Seek.

Parameters:

TSamples :: Position position -The position to seek to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::GetPosition

virtual void GetPosition (TTime & position) const

Interface Category:

API.

Purpose:

Fills in the TTime with the current position in the file.

Calling Context:

Call directly to get the position in units of time.

Parameters:

TTime & position -The time to be filled in with the current time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::GetPositionInSamples

virtual TSamples :: Position GetPositionInSamples () const

Interface Category:

API.

Purpose:

Returns the current position in the file.

Calling Context:

Call directly to get the position in samples. Used by GetPosition.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::Read

virtual TSamples::Position Read (TMemorySurrogate & fillThis, TSamples::Position numberOfSamplesToRead)

Interface Category:

API.

Purpose:

Reads a block of memory from the sequence starting at the current Seek position. The Seek position is moved to the end of the block actually read.

Calling Context:

Call directly when reading data. Used by SoundServer.

Parameters:

TMemorySurrogate & fillThis -The block of memory to receive data from the sequence.
TSamples::Position numberOfSamplesToRead -The desired number of samples to read from the sequence.

Return Value:

TSamples::Position -The number of samples actually read.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::Write

virtual TSamples::Position Write (const TMemorySurrogate & dataToWrite, TSamples::Position numberOfSamplesToWrite)

Interface Category:

API.

Purpose:

Writes a block of memory into the sequence starting at the current Seek position. The Seek position is moved to the end of the block actually written. The Duration of the sequence is updated if changed by Write.

Calling Context:

Call directly when writing data. Used by SoundServer.

Parameters:

const TMemorySurrogate & dataToWrite -The block of memory to copy into the sequence.
TSamples::Position numberOfSamplesToWrite -The desired number of samples to write into the sequence.

Return Value:

TSamples::Position -The number of samples actually written.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::DeepCopy

virtual void DeepCopy (TAudioSequence &) const

Interface Category:

API.

Purpose:

Copies the audio data from one audio sequence to another. All data in this sequence is lost.

Calling Context:

Call directly to copy audio data from one sequence to another. This is an expensive operation, as potentially megabytes of audio data are copied.

Parameters:

TAudioSequence & -The sequence to copy.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kInvalidType if the sequence being copied to is of an incompatible type.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::CreateSubrange

virtual TMediaSequence * CreateSubrange (const TMediaRange & range) const

Interface Category:

API.

Purpose:

Creates a new audio sequence that is a subset of the audio sequence. The range specifies the start time and duration of the subset.

Calling Context:

Call directly to create a subset of an audio sequence. Unlike DeepCopy, CreateSubrange does not copy actual data, just references to the data. This is an inexpensive operation.

Parameters:

const TMediaRange & range -A range specifying the start and duration of the subset.

Return Value:

TMediaSequence* -A new audio sequence that is a subset of the original.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::GetDuration

void GetDuration (TTime & duration) const

Interface Category:

API.

Purpose:

Returns the duration of the audio sequence.

Calling Context:

Call directly to determine how long the sequence is.

Parameters:

TTime & duration -The duration. You can pass in any TTime derived class, (for example TSeconds, TMilliseconds, TSamples).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::CreatePreferredTypeList

virtual void CreatePreferredTypeList (TSequenceOf<TMediaType> & typeList) const

Interface Category:

API.

Purpose:

Some sequences can supply data in a number of formats. This function fills in the TSequenceOf parameter with the types of audio data the audio sequence supports. The audio data types are represented by TAudioType.

Calling Context:

Call directly to determine at runtime what types of audio data a sequence supports. Used by TAudioPlayer.

Parameters:

TSequenceOf<TMediaType> & typeList -The sequence to be filled in with the audio types.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::ChoosePreferredType

virtual TMediaType * ChoosePreferredType (const TSequenceOf<TMediaType> & theChoices) const

Interface Category:

API.

Purpose:

Given a collection of audio types, returns the type that the sequence can most easily supply. Some sequences can supply data in a number of formats.

Calling Context:

Call directly to find out the format the audio sequence would prefer to supply its data in. After calling this, you can then call SetChosenType to tell the audio sequence to supply the data in this format.

Parameters:

const TSequenceOf<TMediaType> & theChoices -A sequence of TAudioTypes.

Return Value:

TMediaType* -A pointer to a TAudioType that the sequence would prefer to supply its data in or NIL if no selection can be made. The instance of TAudioType pointed to is one of the types found in the passed in the TSequenceOf parameter. Don't delete it unless you created it.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call directly to stream in data. Used by SoundServer.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the versions don't match.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to stream out data. Used by SoundServer.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::TAudioSequence

TAudioSequence ()
TAudioSequence (const TAudioSequence &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Protected -Not to be called directly. Called by deriving classes when creating an undefined object that will immediately be assigned to or streamed into.
Protected -Not to be called directly. Called by deriving classes to copy an object.

Parameters:

Takes no parameters.
const TAudioSequence & -The audio sequence to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::operator=

TAudioSequence & operator =(const TAudioSequence &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call directly when an object is assigned to another compatible object.

Parameters:

const TAudioSequence & -The audio sequence to copy.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::SetNumberOfChannels

virtual void SetNumberOfChannels (long numberOfChannels)

Interface Category:

API.

Purpose:

Sets the number of interleaved audio channels. Some sequences store stereo and other multichannel formats as interleaved samples. For stereo, the left channel is stored first, followed by the right channel.

Calling Context:

Called by deriving classes to set the number of channels. This value is stored in TAudioSequence.

Parameters:

long numberOfChannels -The number of interleaved audio channels.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::AddAudioType

virtual void AddAudioType (const TAudioType & newType)

Interface Category:

API.

Purpose:

Adds the audio type to the sequence list of preferred types.

Calling Context:

Called by deriving classes to add each supported audio type to the preferred type list. This list is maintained by TAudioSequence.

Parameters:

const TAudioType & newType -The audio type to add.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TAudioSequence::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called by collection classes to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.