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.
- 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.
virtual ~ TSound ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called by Runtime to destroy an object.
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
Copyright©1995 Taligent,Inc. All rights reserved.