Class: TSound

Declaration: Sound.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPlayer

Inherited By:

None.

Purpose:

Plays and records sound files. Permits adjustment of playback and recoding gain. Most casual users of sound should use this class. You can also use TSound to play an arbitrary audio sequence.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Not intended to be derived.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TSound::TSound

TSound ()
TSound (const TFileSystemEntity & fileEntity, MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead, MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead)
TSound (TDirectory & directory, const TFileSystemEntityName& fileName, MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead, MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead)
TSound (const TSound &)

Interface Category:

API.

Purpose:

Default constructor. Creates an uninitialized TSound.
Normal constructor. Opens an existing sound file for playback or recording.
Normal constructor. Creates a sound file if necessary and opens it for playback or recording.
Copy constructor.

Calling Context:

Called to create an undefined object that is immediately assigned to or streamed into.
Called when you have the file system entity corresponding to a sound file that you want to play or record.
Called when you have the path and file name for a sound file that you want to play or record.
Called to copy an object.

Parameters:

Takes no parameters.
const TFileSystemEntity & fileEntity -The entity corresponding to the sound file to play or record.
MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead -Specifies non-owners' permissions for the file system.
TDirectory & directory -The directory in which the sound file is located or is to be created.
const TFileSystemEntityName& fileName -The name of the sound file to play or record.
MOpenFile::EPermissionsForMe forMe =MOpenFile::kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile::EPermissionsForOthers forOthers =MOpenFile::kAllowRead -Specifies non-owners' permissions for the file system.
const TSound & -The TSound to copy.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kInvalidType if TSound cannot handle the sequence's audio type. Throws TTimeMediaException::kCannotPlaySequence if the file format is unknown.

Concurrency:

Multithread safe.

Other Considerations:

Note: The file system entity parameter used in constructing objects of this class contains an absolute pathname. When streamed, objects will continue to reference a file on the machine of origin.

Member Function: TSound::~TSound

virtual ~ TSound ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::operator=

TSound & operator =(const TSound &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TSound & -The TSound to copy.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::PlayFromBegin

virtual void PlayFromBegin ()

Interface Category:

API.

Purpose:

A convenience function to play from the beginning of a sound. It is equivalent to Seek(TTime::kZero); Play();

Calling Context:

Call directly to play the sound starting at the beginning. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::IsSyncable

virtual bool IsSyncable () const

Interface Category:

API.

Purpose:

Specifies whether TSound implementation supports synchronization.

Calling Context:

Call directly to determine whether full API is supported on a specific platform. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

bool -true if full API is supported, false if API is only partially supported.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetFileSystemEntity

virtual TFileSystemEntity GetFileSystemEntity () const

Interface Category:

API.

Purpose:

Provides access to the file system entity associated with the sound file, if any.

Calling Context:

Call directly to obtain information about the sound file. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

TFileSystemEntity -The file system entity for the current sound file. If no sequence has been specified or if file system information is not available because sequence has been adopted rather than created by TSound, an invalid entity is returned.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetMediaComponentType

virtual const TMediaComponentType& GetMediaComponentType () const

Interface Category:

API.

Purpose:

Determines the media type and category of this player. Provides the values of TMediaType::GetAudio for the media type and TMediaComponentType::GetConveniencePlayer for the component category.

Calling Context:

Used by the Media Registry.

Parameters:

Takes no parameters.

Return Value:

const TMediaComponentType& -The media component type value associated with this player.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::Play

virtual void Play ()

Interface Category:

API.

Purpose:

Starts playback of the sound and returns immediately. Playback begins from the current position in the sound. The position is similar to a play head on a tape recorder.

Calling Context:

Call directly to play the sound. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized. Throws TTimeMediaException::kNoSequence if the sequence has been orphaned and no new sequence has been adopted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::Stop

virtual void Stop ()

Interface Category:

API.

Purpose:

Stops playback or recording immediately. If not playing or recording, does nothing.

Calling Context:

Call directly to stop a playing or recording sound. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::WaitUntilComplete

virtual void WaitUntilComplete ()

Interface Category:

API.

Purpose:

Blocks the calling thread until playback or recording finishes.

Calling Context:

Call directly. Play and Record return immediately, so use this call when you want all processing in a thread to stop until playback or recording stops. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::IsPlaying

virtual bool IsPlaying () const

Interface Category:

API.

Purpose:

Determines whether the sound is playing.

Calling Context:

Call directly to determine if a sound is playing.

Parameters:

Takes no parameters.

Return Value:

Returns true if the sound is playing, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::AdviseWillPlay

virtual void AdviseWillPlay ()

Interface Category:

API.

Purpose:

Hints to the sound that you are going to call play soon. Gives the sound a chance to perform time-consuming preparation for playback (such as paging in the first few seconds of a sound file) in advance of Play being called.

Calling Context:

Call directly. Needed only if you require minimum latency between calling Play and the start of the actual playback. You rarely need to call AdviseWillPlay.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized. Throws TTimeMediaException::kNoSequence if the sequence has been orphaned and no new sequence has been adopted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetPreroll

virtual void GetPreroll (TTime & preroll) const

Interface Category:

API.

Purpose:

Returns the worst case delay that can occur before playback starts. The time is relative to the real-time clock.

Calling Context:

Call directly. If you want to start a sound exactly at time x: 1) Synchronize the sound to a clock. 2) Call GetPreroll to get the preroll time. 3) Call Play at least preroll seconds in advance of time x. The sound starts playing at time x.

Parameters:

TTime & preroll -The preroll time. You can pass in TSeconds, TMilliseconds, TSamples, or any TTime derived class.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetDuration

virtual void GetDuration (TTime & duration) const

Interface Category:

API.

Purpose:

Fills in the TTime with the length of the sound.

Calling Context:

Call directly to determine how long a sound is. Used by Media UI Framework.

Parameters:

TTime & duration -The duration. You can pass in TSeconds, TMilliseconds, TSamples, or any TTime derived class.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::Seek

virtual void Seek (const TTime & position)

Interface Category:

API.

Purpose:

Sets the current position in the sound.

Calling Context:

Call directly to jump to a specific point in the sound. Works while stopped, playing, or recording. Used by Media UI Framework.

Parameters:

const TTime & position -The position you want to seek to. You can pass in TSeconds, TMilliseconds, TSamples, or any TTime derived class.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized. Throws TTimeMediaException::kNoSequence if the sequence has been orphaned and no new sequence has been adopted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetPosition

virtual void GetPosition (TTime & position) const

Interface Category:

API.

Purpose:

Fills in the TTime with the current position.

Calling Context:

Call directly to determine the current position of the sound. Works at all times regardless of whether sound is stopped, recording, or playing. Used by Media UI Framework.

Parameters:

TTime & position -The current position. You can pass in TSeconds, TMilliseconds, TSamples, or any TTime derived class.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetClock

virtual void GetClock (TSyncableClockSurrogate & internalClock) const

Interface Category:

API.

Purpose:

Returns a clock surrogate that is synced to the sound's internal clock. You can synchronize another TPlayer to this sound using this clock.

Calling Context:

Call directly when you want the sound to be a master clock in a master/slave clock relationship. Used by Media UI Framework.

Parameters:

TSyncableClockSurrogate & internalClock -The surrogate for the sound's clock.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SyncTo

virtual void SyncTo (const TSyncableClockSurrogate & externalClock, double rate =1.0, const TTime & offset =TTime :: kZero)

Interface Category:

API.

Purpose:

Synchronizes the sound to the specified clock.

Calling Context:

Call directly to synchronize the sound to an external clock. Used by Media UI Framework.

Parameters:

const TSyncableClockSurrogate & externalClock -The external clock to sync to.
double rate =1.0 -The sound runs at this rate relative to the external clock.
const TTime & offset =TTime :: kZero -The sound's clock (and current position) is offset from the external clock's time by this amount.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SyncToKeepMyTime

virtual void SyncToKeepMyTime (const TSyncableClockSurrogate & externalClock, double rate =1.0)

Interface Category:

API.

Purpose:

Synchronizes the sound to the specified clock.

Calling Context:

Call directly when you want to synchronize the sound to an external clock, but want the sound clock's time (and hence the sound's current position) to be unchanged. Used by Media UI Framework.

Parameters:

const TSyncableClockSurrogate & externalClock -The external clock to sync to.
double rate =1.0 -The sound runs at this rate relative to the external clock.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SyncToSelf

virtual void SyncToSelf ()

Interface Category:

API.

Purpose:

Synchronizes the sound to its own internal clock, as opposed to an external clock. Internal sync is the default behavior of a newly constructed TSound.

Calling Context:

Call directly when you no longer want the sound to be synchronized to an external clock. It undoes the effect of SyncTo or SyncToKeepMyTime. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::AdoptSequence

virtual void AdoptSequence (TMediaSequence * hadBetterBeAnAudioSequence)

Interface Category:

API.

Purpose:

Loads an audio sequence into the sound. The sound now owns the storage for the audio sequence, so don't delete the sequence unless you get it back by calling OrphanSequence.

Calling Context:

Call directly if you have created an audio sequence (sound file, sine wave, and so on) and want this TSound to play it. Used by Media UI Framework.

Parameters:

TMediaSequence * hadBetterBeAnAudioSequence -The audio sequence to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::OrphanSequence

virtual TMediaSequence * OrphanSequence ()

Interface Category:

API.

Purpose:

Ejects an audio sequence from the sound, returning a pointer to the sequence. The sound no longer owns the storage for the sequence. It is up to you to delete the sequence.

Calling Context:

Call directly to remove the audio sequence from the sound. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

TMediaSequence* -The audio sequence ejected from the sound. If no sequence has been specified, returns NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::IsRecordable

virtual bool IsRecordable () const

Interface Category:

API.

Purpose:

Determines if the sound can be recorded into.

Calling Context:

Call directly to determine at runtime whether the sound has a writable audio sequence in it. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

Returns true if the audio sequence can be recorded into.

Exceptions:

Throws TTimeMediaException::kNoSequence if no sequence has been specified.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::Record

virtual void Record ()

Interface Category:

API.

Purpose:

Starts recording and returns immediately. Call Stop to stop recording. Call WaitUntilComplete to block until recording is finished. Note that a TSound, like all TPlayers, is either recording, stopped, or playing. It cannot record and play at the same time.

Calling Context:

Call directly to start recording. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized. Throws TTimeMediaException::kNoSequence if the sequence has been orphaned and no new sequence has been adopted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::IsRecording

virtual bool IsRecording () const

Interface Category:

API.

Purpose:

Determines if the sound is recording.

Calling Context:

Call directly to determine whether a sound is recording. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

Returns true if the sound is recording.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::AdviseWillRecord

virtual void AdviseWillRecord ()

Interface Category:

API.

Purpose:

Performs time-consuming preparation for recording.

Calling Context:

Call directly. Use only if you require minimal latency between calling Record and the actual start of recording. You rarely need to call AdviseWillRecord. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized. Throws TTimeMediaException::kNoSequence if the sequence has been orphaned and no new sequence has been adopted.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::CreateStoppedInterest

virtual TInterest * CreateStoppedInterest ()

Interface Category:

API.

Purpose:

Creates a TInterest that can be used to get notification when the sound stops playing.

Calling Context:

Call directly to get notification when a sound stops. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

TInterest * -An interest that you can pass into a notification connection.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SetInputGain

virtual void SetInputGain (double gain)

Interface Category:

API.

Purpose:

Sets the input gain of the sound. Used to adjust the recording level.

Calling Context:

Call directly to raise or lower the recording level. Used by Media UI Framework.

Parameters:

double gain -The input gain factor. The signal is multiplied by this number. A value of 1.0 leaves the level unchanged. Values >1.0 raise the level, while values between 1.0 and 0.0 reduce the level. A value of 0.0 yields silence.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetInputGain

virtual double GetInputGain () const

Interface Category:

API.

Purpose:

Returns the input gain value. Input gain adjusts the recording level.

Calling Context:

Call directly to determine the recording level. The default value is 1.0. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

double -The input gain factor. The default is 1.0 for a newly constructed sound.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SetOutputGain

virtual void SetOutputGain (double gain)

Interface Category:

API.

Purpose:

Sets the output gain of the sound. Used to adjust the playback volume.

Calling Context:

Called to raise or lower the playback volume. Used by Media UI Framework.

Parameters:

double gain -The output gain factor. The signal is multiplied by this number. A value of 1.0 leaves the volume unchanged. Values >1.0 raise the volume, while values between 1.0 and 0.0 reduce the volume. A value of 0.0 yields silence.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetOutputGain

virtual double GetOutputGain () const

Interface Category:

API.

Purpose:

Returns the output gain. The output gain adjusts the playback volume.

Calling Context:

Call directly to determine the playback volume. The default value is 1.0. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

double -The input gain factor. The default is 1.0.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::SetRate

virtual void SetRate (double rate)

Interface Category:

API.

Purpose:

Changes the rate of playback of the sound. By definition, this affects the pitch of the sound.

Calling Context:

Call directly to change the pitch of the sound during playback. Used by Media UI Framework.

Parameters:

double rate -The playback rate. A value of 1.0 leaves the rate unchanged. A value of 2.0 raises the pitch an octave, while a value of 0.5 reduces the pitch an octave.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kUninitializedComponent if the object is uninitialized.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::GetRate

virtual double GetRate () const

Interface Category:

API.

Purpose:

Returns the playback rate.

Calling Context:

Call directly to determine the playback rate. The default value is 1.0. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

double -The playback rate.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call directly to stream in data. Used by Media Registry and UI Framework.

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:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to stream out the object. Used by Media Registry and UI Framework.

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:

Multithread safe.

Other Considerations:

None.

Member Function: TSound::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:

Multithread safe.

Other Considerations:

None.

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