Sound mixer. More...

#include <sound_handler.h>

Inheritance diagram for gnash::sound::sound_handler:

Public Types
typedef unsigned long	StreamBlockId
	Identifier of a streaming sound block.
Public Member Functions
virtual	~sound_handler ()
virtual void	stop_all_sounds ()
	Remove all scheduled request for playback of sound buffer slots.
virtual int	create_sound (std::auto_ptr< SimpleBuffer > data, const media::SoundInfo &sinfo)
	Create a sound buffer slot, for on-demand playback.
virtual void	stopEventSound (int sound_handle)
	Remove scheduled requests to play the specified sound buffer slot.
virtual void	stopAllEventSounds ()
	Stop all instances of all playing event sounds.
virtual void	delete_sound (int sound_handle)
	Discard the sound data for an embedded event sound.
void	startSound (int id, int loops, const SoundEnvelopes *env, bool allowMultiple, unsigned int inPoint=0, unsigned int outPoint=std::numeric_limits< unsigned int >::max())
	Start playback of an event sound.
bool	isSoundPlaying (int id) const
	Check if an event sound is playing.
virtual void	set_volume (int sound_handle, int volume)
	Sets the volume for a given event sound.
virtual unsigned int	get_duration (int sound_handle) const
	Gets the duration in milliseconds of an event sound.
virtual unsigned int	tell (int sound_handle) const
	Gets the playhead position in milliseconds of an event sound.
virtual int	get_volume (int sound_handle) const
	Gets the volume for a given sound buffer slot.
virtual int	createStreamingSound (const media::SoundInfo &sinfo)
virtual void	stopStreamingSound (int handle)
	Remove scheduled requests to play the specified sound buffer slot.
virtual StreamBlockId	addSoundBlock (std::auto_ptr< SimpleBuffer > data, size_t sampleCount, int seekSamples, int streamId)
virtual media::SoundInfo *	get_sound_info (int handle) const
	Returns a SoundInfo object for the sound with the given id.
void	playStream (int handle, StreamBlockId blockId)
	Start playback of a streaming sound, if not playing already.
int	getStreamBlock (int handle) const
	Get the identifier for the block playing in a specific stream.
int	getFinalVolume () const
	Get the volume to apply to mixed output.
void	setFinalVolume (int v)
	Set the volume to apply to mixed output.
virtual void	reset ()
	Discard all sound inputs (slots and aux streamers) and clear scheduling.
virtual void	mute ()
	Call this to mute audio.
virtual void	unmute ()
	Call this to unmute audio.
virtual bool	is_muted () const
	Returns whether or not sound is muted.
virtual void	pause ()
	gnash calls this to pause audio
virtual void	unpause ()
	gnash calls this to unpause audio
bool	isPaused () const
	return true if audio is paused
virtual InputStream *	attach_aux_streamer (aux_streamer_ptr ptr, void *udata)
	Plug an external InputStream into the mixer.
virtual void	unplugInputStream (InputStream *id)
	Unplug an external InputStream from the mixer.
size_t	numSoundsStarted () const
	Special test-fuction. Reports how many times a sound has been started.
size_t	numSoundsStopped () const
	Special test-fuction. Reports how many times a sound has been stopped.
virtual void	fetchSamples (boost::int16_t *to, unsigned int nSamples)
	Fetch mixed samples.
virtual void	mix (boost::int16_t outSamples, boost::int16_t inSamples, unsigned int nSamples, float volume)=0
	Mix nSamples from inSamples to outSamples, with given volume.
void	setAudioDump (const std::string &wavefile)
	Request to dump audio to the given filename.
bool	streamingSound () const
	Check if a streaming sound is playing.
Protected Member Functions
	sound_handler (media::MediaHandler *m)
virtual void	plugInputStream (std::auto_ptr< InputStream > in)
	Plug an InputStream to the mixer.
virtual void	unplugAllInputStreams ()
	Unplug all input streams.
bool	hasInputStreams () const
	Does the mixer have input streams ?
virtual void	delete_all_sounds ()
	Stop and delete all sounds.

Detailed Description

Sound mixer.

Stores the audio found by the parser and plays on demand. Also allows plugging auxiliary streamers for ActionScript driven sound (Sound, NetStream).

The main interface this class exposes to hosting application is fetching of sound samples, in couples of signed 16bit integers (left channel, right channel) in PCM. See fetchSamples.

Implementations of this class willing to allow hosting application to use a thread for fetching audio should make sure to take care about mutex protecting the relevant datastores. The default implementation uses NO locking.

Todo:: rename to gnash::sound::Mixer ?

The sound_handler class stores embedded sounds. Embedded sounds can be either streaming sounds (embedded in many StreamSoundBlock tags through the SWF) or event sounds (defined in a single DefineSoundTag). The interface is partly divided into separate functions for these types of sound. TODO: separate the functions fully.

Member Typedef Documentation

typedef unsigned long gnash::sound::sound_handler::StreamBlockId

Identifier of a streaming sound block.

Use coupled with a soundId for fully qualified identifier

Constructor & Destructor Documentation

gnash::sound::sound_handler::~sound_handler ( ) [virtual]

References delete_all_sounds(), and unplugAllInputStreams().

gnash::sound::sound_handler::sound_handler ( media::MediaHandler * m ) [inline, protected]

Member Function Documentation

sound_handler::StreamBlockId gnash::sound::sound_handler::addSoundBlock	(	std::auto_ptr< SimpleBuffer >	data,
		size_t	sampleCount,
		int	seekSamples,
		int	streamId
	)		`[virtual]`

Append data for a streaming sound.

Gnash's parser calls this to fill up soundstreams data.

Parameters:

data	The sound data to be stored. May not be null. This should be appropriately padded (

See also:: MediaHandler::getInputPaddingBytes()), or a reallocation will take place here.

Parameters:

sampleCount	Number of samples in the data
seekSamples	Offset of sound to frame data
streamId	The soundhandlers id of the sound we want to add data to

Returns:: a handler for the new block for use in playStream()

Exceptions:

SoundException on error

Reimplemented in gnash::sound::SDL_sound_handler.

References _, assert, and gnash::sound::StreamingSoundData::append().

Referenced by gnash::SWF::StreamSoundBlockTag::loader().

InputStream * gnash::sound::sound_handler::attach_aux_streamer	(	aux_streamer_ptr	ptr,
		void *	udata
	)		`[virtual]`

Plug an external InputStream into the mixer.

This is called by AS classes NetStream or Sound to attach callback, so that audio from the classes will be played through the soundhandler.

This is actually only used by the SDL sound_handler. It uses these "auxiliary" streamers to fetch decoded audio data to mix and send to the output channel.

The "aux streamer" will be called with the 'udata' pointer as first argument, then will be passed a pointer to buffer of samples as second argument and the number of samples to fetch as third.

The callbacks should fill the given buffer if possible, and return the number of samples actually fetched and an eof flag (last argument). The callback will be detached if it sets the 'eof' output parameter to true.

Parameters:

ptr	The pointer to the callback function
udata	User data pointer, passed as first argument to the registered callback.

Returns:: an InputStream pointer, for passing to unplugInputStream. Callers do not own the InputStream, and should NOT realy on it to be point to allocated memory! It is meant to be used as an identifier for the newly created mixer channel.

Todo:: change to plugInputStream(InputStream* str), implement in base class

See also:: unplugInputStream

References assert, and plugInputStream().

Referenced by gnash::BufferedAudioStreamer::attachAuxStreamer(), and setAudioDump().

int gnash::sound::sound_handler::create_sound	(	std::auto_ptr< SimpleBuffer >	data,
		const media::SoundInfo &	sinfo
	)		`[virtual]`

Create a sound buffer slot, for on-demand playback.

Event sound functions:

Parameters:

data	The sound data to be stored. May not be null. This should be appropriately padded (

See also:: MediaHandler::getInputPaddingBytes()), or a reallocation will take place here.

Parameters:

sinfo A SoundInfo object containing info about samplerate, samplecount, stereo etc.

Returns:: handle for later identification.

Reimplemented in gnash::sound::SDL_sound_handler.

Referenced by gnash::SWF::define_sound_loader().

int gnash::sound::sound_handler::createStreamingSound ( const media::SoundInfo & sinfo ) [virtual]

Streaming sound functions:

Reimplemented in gnash::sound::SDL_sound_handler.

Referenced by gnash::SWF::SoundStreamHeadTag::loader().

void gnash::sound::sound_handler::delete_all_sounds ( ) [protected, virtual]

Stop and delete all sounds.

This is used only on reset.

References gnash::key::i, gnash::key::e, assert, gnash::sound::EmbedSound::numPlayingInstances(), and gnash::sound::StreamingSoundData::numPlayingInstances().

Referenced by ~sound_handler(), gnash::sound::AOS4_sound_handler::~AOS4_sound_handler(), gnash::sound::AOS4_sound_handler::reset(), gnash::sound::Mkit_sound_handler::~Mkit_sound_handler(), and gnash::sound::Mkit_sound_handler::reset().

void gnash::sound::sound_handler::delete_sound ( int sound_handle ) [virtual]

Discard the sound data for an embedded event sound.

Only embedded event sounds are deleted; this happens when the associated sound_sample is deleted.

Parameters:

sound_handle The id for the event sound to be deleted

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References _.

Referenced by gnash::sound_sample::~sound_sample().

void gnash::sound::sound_handler::fetchSamples	(	boost::int16_t *	to,
		unsigned int	nSamples
	)		`[virtual]`

Fetch mixed samples.

We run through all the plugged InputStreams fetching decoded audio blocks and mixing them into the given output stream.

Parameters:

to The buffer to write mixed samples to. Buffer must be big enough to hold nSamples samples.

nSamples The amount of samples to fetch. NOTE: this number currently refers to "mono" samples due to some bad design decision. It is so expected that the user fetches 44100 * 2 samples which has to be interpreted as series of left,right channel couples. TODO: use actual number of samples so that it's expected to fetch 44100 per second and let expose a function to give interpretation of what comes back (how many bytes per channel, which format).

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References isPaused(), getFinalVolume(), fill, gnash::image::end(), gnash::sound::InputStream::fetchSamples(), gnash::sound::InputStream::samplesFetched(), mix(), and is_muted().

Referenced by gnash::DumpGui::writeSamples().

unsigned int gnash::sound::sound_handler::get_duration ( int sound_handle ) const [virtual]

Gets the duration in milliseconds of an event sound.

Parameters:

sound_handle The id of the event sound

Returns:: the duration of the sound in milliseconds

Reimplemented in gnash::sound::SDL_sound_handler.

References gnash::sound::EmbedSound::soundinfo, gnash::media::SoundInfo::getSampleCount(), and gnash::media::SoundInfo::getSampleRate().

media::SoundInfo * gnash::sound::sound_handler::get_sound_info ( int handle ) const [virtual]

Returns a SoundInfo object for the sound with the given id.

Note: This should only be used for streaming sounds. The SoundInfo object is still owned by the soundhandler.

Parameters:

soundHandle The soundhandlers id of the sound we want some info about.

Returns:: a pointer to the SoundInfo object for the sound with the given id or 0 if no such sound exists.

Reimplemented in gnash::sound::SDL_sound_handler.

Referenced by gnash::SWF::StreamSoundBlockTag::loader().

int gnash::sound::sound_handler::get_volume ( int sound_handle ) const [virtual]

Gets the volume for a given sound buffer slot.

Only use for event sounds!

Parameters:

sound_handle The sound to get the volume for.

Returns:: the sound volume level as an integer from 0 to 100, where 0 is off and 100 is full volume. The default setting is 100.

Reimplemented in gnash::sound::SDL_sound_handler.

int gnash::sound::sound_handler::getFinalVolume ( ) const [inline]

Get the volume to apply to mixed output.

Sound output functions.

Returns:: percent value. 100 is full, 0 is none. Can be negative or over 100 too.

Referenced by fetchSamples().

int gnash::sound::sound_handler::getStreamBlock ( int handle ) const

Get the identifier for the block playing in a specific stream.

This is used by movie_root to check which part of the stream is actually playing. Streaming sound is used to synchronize the frame rate. The returned block id can be matched with a specific frame.

Parameters:

handle The handle of the stream sound to query.

Returns:: The identifier of the stream block that the sound_handler is currently playing (it may be only approximate, as we can't really know what's coming out of the speakers). Returns -1 if the specified stream sound is not playing or doesn't exist.

References gnash::key::i.

Referenced by gnash::movie_root::advance().

bool gnash::sound::sound_handler::hasInputStreams ( ) const [protected]

Does the mixer have input streams ?

Referenced by gnash::sound::AOS4_sound_handler::fetchSamples(), gnash::sound::AOS4_sound_handler::unpause(), gnash::sound::Mkit_sound_handler::fetchSamples(), gnash::sound::Mkit_sound_handler::unpause(), gnash::sound::SDL_sound_handler::fetchSamples(), and gnash::sound::SDL_sound_handler::unpause().

bool gnash::sound::sound_handler::is_muted ( ) const [virtual]

Returns whether or not sound is muted.

Returns:: true if muted, false if not

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

Referenced by gnash::Gui::toggleSound(), and fetchSamples().

bool gnash::sound::sound_handler::isPaused ( ) const [inline]

return true if audio is paused

Referenced by fetchSamples(), and gnash::sound::AOS4_sound_handler::audioTask().

bool gnash::sound::sound_handler::isSoundPlaying ( int id ) const

Check if an event sound is playing.

Note: this should not be used for streaming sounds.

Parameters:

id	Id of the sound buffer slot check for being alive

References gnash::sound::EmbedSound::isPlaying().

virtual void gnash::sound::sound_handler::mix	(	boost::int16_t *	outSamples,
		boost::int16_t *	inSamples,
		unsigned int	nSamples,
		float	volume
	)		`[pure virtual]`

Mix nSamples from inSamples to outSamples, with given volume.

Parameters:

outSamples	The output samples buffer, to mix to. Must be big enough to contain nSamples. Can be larger.
inSamples	The input samples buffer, to mix in. It is non-const as this method is allowed to mess with content, for example to apply volume. TODO: why not applying volume upstream ?!
nSamples	The amount of samples to mix in.
volume	The volume to apply to input samples, as a fraction (0..1)

TODO: this interface says nothing about how many channels we're going to mix. It should, to be a sane interface. Maybe, a Mixer instance should be created, initialized with number of channels, at each fetching.

Implemented in gnash::sound::NullSoundHandler.

Referenced by gnash::sound::NullSoundHandler::mix(), and fetchSamples().

void gnash::sound::sound_handler::mute ( ) [virtual]

Call this to mute audio.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

Referenced by gnash::Gui::toggleSound().

size_t gnash::sound::sound_handler::numSoundsStarted ( ) const [inline]

Special test-fuction. Reports how many times a sound has been started.

Deprecated:: Use a TestingSoundHanlder !

size_t gnash::sound::sound_handler::numSoundsStopped ( ) const [inline]

Special test-fuction. Reports how many times a sound has been stopped.

Deprecated:: Use a TestingSoundHanlder !

virtual void gnash::sound::sound_handler::pause ( ) [inline, virtual]

gnash calls this to pause audio

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

Referenced by gnash::Gui::stop(), and gnash::Gui::pause().

void gnash::sound::sound_handler::playStream	(	int	handle,
		StreamBlockId	blockId
	)

Start playback of a streaming sound, if not playing already.

TODO: the samples count in the stream sound head (stored in a SoundInfo object) should drive the timeline while a stream is playing. TODO: only the number of samples advertised in each stream block should be played for mp3 sounds, not the complete data! Currently we don't store this value.

Parameters:

handle	Id of the sound buffer slot schedule playback of.
blockId	Identifier of the block to start decoding from.

References gnash::key::s, gnash::sound::StreamingSoundData::isPlaying(), gnash::sound::StreamingSoundData::empty(), gnash::sound::StreamingSoundData::createInstance(), plugInputStream(), gnash::key::e, and _.

Referenced by gnash::SWF::StreamSoundBlockTag::executeActions().

void gnash::sound::sound_handler::plugInputStream ( std::auto_ptr< InputStream > in ) [protected, virtual]

Plug an InputStream to the mixer.

Parameters:

in	The InputStream to plug, ownership transferred

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References second, and _.

Referenced by playStream(), startSound(), and attach_aux_streamer().

void gnash::sound::sound_handler::reset ( ) [virtual]

Discard all sound inputs (slots and aux streamers) and clear scheduling.

Gnash calls this on movie restart.

The function should stop all sounds and get ready for a "parse from scratch" operation.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References stop_all_sounds().

Referenced by gnash::movie_root::reset().

void gnash::sound::sound_handler::set_volume	(	int	sound_handle,
		int	volume
	)		`[virtual]`

Sets the volume for a given event sound.

Only used by the AS Sound class

Parameters:

sound_handle	The handle of the event sound to set volume for.
volume	A number from 0 to 100 representing a volume level. 100 is full volume and 0 is no volume. The default setting is 100.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References volume.

void gnash::sound::sound_handler::setAudioDump ( const std::string & wavefile )

Request to dump audio to the given filename.

Every call to this function starts recording to a new file, closing any existing other dump.

References attach_aux_streamer().

Referenced by gnash::Gui::start().

void gnash::sound::sound_handler::setFinalVolume ( int v ) [inline]

Set the volume to apply to mixed output.

Parameters:

v	percent value. 100 is full, 0 is none. Can be negative or over 100 too.

References test::v.

void gnash::sound::sound_handler::startSound	(	int	id,
		int	loops,
		const SoundEnvelopes *	env,
		bool	allowMultiple,
		unsigned int	inPoint = `0`,
		unsigned int	outPoint = `std::numeric_limits<unsigned int>::max()`
	)

Start playback of an event sound.

All scheduled sounds will be played on next output flush.

Parameters:

id	Id of the sound buffer slot to schedule playback of.
loops	loops == 0 means play the sound once (1 means play it twice, etc)
inPoint	Offset in output samples this instance should start playing from. These are post-resampling samples (44100 for one second of samples).
outPoint	Offset in output samples this instance should stop playing at. These are post-resampling samples (44100 for one second of samples). Use std::numeric_limits<unsigned int>::max() for no limit (default if missing)
env	Some eventsounds have some volume control mechanism called envelopes. They basically tells that from sample X the volume should be Y.
allowMultiple	If false, the sound will not be scheduled if there's another instance of it already playing.

References _, gnash::sound::EmbedSound::soundinfo, gnash::media::SoundInfo::getDelaySeek(), LOG_ONCE, gnash::sound::swfToOutSamples(), gnash::media::SoundInfo::getFormat(), gnash::sound::EmbedSound::isPlaying(), gnash::sound::EmbedSound::empty(), IF_VERBOSE_MALFORMED_SWF, gnash::sound::EmbedSound::createInstance(), plugInputStream(), and gnash::key::e.

Referenced by gnash::Button::mouseEvent(), and gnash::SWF::StartSoundTag::executeActions().

void gnash::sound::sound_handler::stop_all_sounds ( ) [virtual]

Remove all scheduled request for playback of sound buffer slots.

Mixed functions: This applies both to streaming and event sounds.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

References gnash::key::i, and gnash::key::e.

Referenced by reset().

void gnash::sound::sound_handler::stopAllEventSounds ( ) [virtual]

Stop all instances of all playing event sounds.

Reimplemented in gnash::sound::SDL_sound_handler.

References gnash::key::i, and gnash::key::e.

void gnash::sound::sound_handler::stopEventSound ( int sound_handle ) [virtual]

Remove scheduled requests to play the specified sound buffer slot.

Stop all instances of the specified event sound if it's playing. (Normally a full-featured sound API would take a handle specifying the *instance* of a playing sample, but SWF is not expressive that way.)

Parameters:

sound_handle id for the sound to be stopped

Reimplemented in gnash::sound::SDL_sound_handler.

References _.

Referenced by gnash::Button::mouseEvent(), and gnash::SWF::StartSoundTag::executeActions().

void gnash::sound::sound_handler::stopStreamingSound ( int handle ) [virtual]

Remove scheduled requests to play the specified sound buffer slot.

Parameters:

sound_handle The sound_handlers id for the sound to be stopped.

Reimplemented in gnash::sound::SDL_sound_handler.

References assert.

bool gnash::sound::sound_handler::streamingSound ( ) const

Check if a streaming sound is playing.

Returns:: true if any streaming sound is playing, false if not.

References gnash::key::e.

Referenced by gnash::movie_root::advance().

unsigned int gnash::sound::sound_handler::tell ( int sound_handle ) const [virtual]

Gets the playhead position in milliseconds of an event sound.

Parameters:

sound_handle The id of the event sound

Returns:: The playhead position of the sound in milliseconds

Reimplemented in gnash::sound::SDL_sound_handler.

References gnash::sound::EmbedSound::isPlaying(), gnash::sound::EmbedSound::firstPlayingInstance(), and gnash::sound::InputStream::samplesFetched().

void gnash::sound::sound_handler::unmute ( ) [virtual]

Call this to unmute audio.

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

Referenced by gnash::Gui::toggleSound().

virtual void gnash::sound::sound_handler::unpause ( ) [inline, virtual]

gnash calls this to unpause audio

Reimplemented in gnash::sound::AOS4_sound_handler, gnash::sound::SDL_sound_handler, and gnash::sound::Mkit_sound_handler.

Referenced by gnash::Gui::play(), and gnash::Gui::start().

void gnash::sound::sound_handler::unplugAllInputStreams ( ) [protected, virtual]

Unplug all input streams.

Referenced by ~sound_handler(), gnash::sound::AOS4_sound_handler::~AOS4_sound_handler(), and gnash::sound::Mkit_sound_handler::~Mkit_sound_handler().

void gnash::sound::sound_handler::unplugInputStream ( InputStream * id ) [virtual]

Unplug an external InputStream from the mixer.

This is called by AS classes NetStream or Sound to dettach callback, so that audio from the classes no longer will be played through the soundhandler.

Parameters:

id	The key identifying the auxiliary streamer, as returned by attach_aux_streamer.

Reimplemented in gnash::sound::SDL_sound_handler.

References _.

Referenced by gnash::BufferedAudioStreamer::attachAuxStreamer(), and gnash::BufferedAudioStreamer::detachAuxStreamer().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation