aace::audio::AudioOutput Class Reference

Classes
struct	PlaybackContext

Public Types
enum	MutedState {   MutedState::MUTED,   MutedState::UNMUTED }
using	MediaState = aace::audio::AudioOutputEngineInterface::MediaState
using	MediaError = aace::audio::AudioOutputEngineInterface::MediaError
using	FocusAction = aace::audio::AudioOutputEngineInterface::FocusAction

Public Member Functions
virtual bool	prepare (std::shared_ptr< AudioStream > stream, bool repeating)=0
virtual bool	prepare (const std::string &url, bool repeating, const PlaybackContext &playbackContext)=0
virtual void	mayDuck ()=0
virtual bool	play ()=0
virtual bool	stop ()=0
virtual bool	pause ()=0
virtual bool	resume ()=0
virtual bool	startDucking ()=0
virtual bool	stopDucking ()=0
virtual int64_t	getPosition ()=0
virtual bool	setPosition (int64_t position)=0
virtual int64_t	getDuration ()=0
virtual int64_t	getNumBytesBuffered ()
virtual bool	volumeChanged (float volume)=0
virtual bool	mutedStateChanged (MutedState state)=0
void	mediaStateChanged (MediaState state)
void	mediaError (MediaError error, const std::string &description="")
void	audioFocusEvent (FocusAction action)

Static Public Attributes
static const int64_t	TIME_UNKNOWN = -1

Detailed Description

AudioOutput should be extended to play audio data provided by the Engine.

After returning true from a playback-controlling method invocation from the Engine (i.e. play(), pause(), stop(), resume()), it is required that platform implementation notify the Engine of a playback state change by calling one of mediaStateChanged() with the new MediaState or mediaError() with the MediaError. The Engine expects no call to mediaStateChanged() in response to an invocation for which the platform returned false.

The platform implementation may call mediaError() or mediaStateChanged() with MediaState::BUFFERING at any time during a playback operation to notify the Engine of an error or buffer underrun, respectively. When the media player resumes playback after a buffer underrun, the platform implementation should call mediaStateChanged() with MediaState::PLAYING.

Note

The AudioOutput platform implementation should be able to support the audio formats recommended by AVS for a familiar Alexa experience: https://developer.amazon.com/docs/alexa-voice-service/recommended-media-support.html

Member Typedef Documentation

MediaState

using aace::audio::AudioOutput::MediaState = aace::audio::AudioOutputEngineInterface::MediaState

Describes the playback state of the platform media player

See also

aace::alexa::MediaPlayerEngineInterface::MediaState

MediaError

using aace::audio::AudioOutput::MediaError = aace::audio::AudioOutputEngineInterface::MediaError

Describes an error during a media playback operation

See also

aace::alexa::MediaPlayerEngineInterface::MediaError

FocusAction

using aace::audio::AudioOutput::FocusAction = aace::audio::AudioOutputEngineInterface::FocusAction

Describes a focus action platform interface reports or requests

See also

aace::audio::AudioOutputEngineInterface::FocusAction

Member Enumeration Documentation

MutedState

enum aace::audio::AudioOutput::MutedState

strong

Enumerator
MUTED	The audio channel state id muted.
UNMUTED	The audio channel state id unmuted.

Member Function Documentation

prepare() [1/2]

virtual bool aace::audio::AudioOutput::prepare ( std::shared_ptr< AudioStream >  stream, bool  repeating  )

pure virtual

Notifies the platform implementation to prepare for playback of an AudioStream audio source. After returning true, the Engine will call play() to initiate audio playback.

Parameters

[in]	stream	The AudioStream object that provides the platform implementation audio data to play.
[in]	repeating	true if the platform should loop the audio when playing.

Returns

true if the platform implementation successfully handled the call, else false

prepare() [2/2]

virtual bool aace::audio::AudioOutput::prepare ( const std::string &  url, bool  repeating, const PlaybackContext &  playbackContext  )

pure virtual

Notifies the platform implementation to prepare for playback of a URL audio source. After returning true, the Engine will call play() to initiate audio playback.

Parameters

[in]	url	The URL audio source to set in the platform media player
[in]	repeating	true if the platform should loop the audio when playing.
[in]	playbackContext	The context related to playback of an audio item.

Returns

true if the platform implementation successfully handled the call, else false

mayDuck()

virtual void aace::audio::AudioOutput::mayDuck ( )

pure virtual

Notifies the platform implementation only if prepared media allows platform interface to duck the volume if any high priority audio stream is in the focus. If platform interface ducks the volume, report the state using audioFocusEvent always. If mayDuck is not called, platform interface can assume that media is not allowed to duck.

play()

virtual bool aace::audio::AudioOutput::play ( )

pure virtual

Notifies the platform implementation to start playback of the current audio source. After returning true, the platform implementation must call mediaStateChanged() with MediaState.PLAYING when the media player begins playing the audio or mediaError() if an error occurs.

Returns

true if the platform implementation successfully handled the call, else false

stop()

virtual bool aace::audio::AudioOutput::stop ( )

pure virtual

Notifies the platform implementation to stop playback of the current audio source. After returning true, the platform implementation must call mediaStateChanged() with MediaState.STOPPED when the media player stops playing the audio or immediately if it is already stopped, or mediaError() if an error occurs. A subsequent call to play() will be preceded by calls to prepare() and setPosition().

Returns

true if the platform implementation successfully handled the call, else false

pause()

virtual bool aace::audio::AudioOutput::pause ( )

pure virtual

Notifies the platform implementation to pause playback of the current audio source. After returning true, the platform implementation must call mediaStateChanged() with MediaState.STOPPED when the media player pauses the audio or mediaError() if an error occurs. A subsequent call to resume() will not be preceded by calls to prepare() and setPosition().

Returns

true if the platform implementation successfully handled the call, else false

resume()

virtual bool aace::audio::AudioOutput::resume ( )

pure virtual

Notifies the platform implementation to resume playback of the current audio source. After returning true, the platform implementation must call mediaStateChanged() with MediaState.PLAYING when the media player resumes the audio or mediaError() if an error occurs.

Returns

true if the platform implementation successfully handled the call, else false

startDucking()

virtual bool aace::audio::AudioOutput::startDucking ( )

pure virtual

Notifies the platform implementation to move the playback in background. If platform implementation supports audio ducking, reduce the media player volume according to platform guidelines.

Returns

true if the platform implementation successfully attenuated the volume, else false. If false is returned, stopDucking call will not be received.

stopDucking()

virtual bool aace::audio::AudioOutput::stopDucking ( )

pure virtual

Notifies the platform implementation to move the playback in foreground. If platform implementation supports audio ducking, restore the media player volume to original value.

Returns

true if the platform implementation successfully restored the volume, else false. If false is returned, internal state considers that platform implementation is still in the ducked state which may result into unexpected behavior.

getPosition()

virtual int64_t aace::audio::AudioOutput::getPosition ( )

pure virtual

Returns the current playback position of the platform media player. If the audio source is not playing, the most recent position played should be returned.

Returns

The platform media player's playback position in milliseconds, or TIME_UNKNOWN if the current media position is unknown or invalid.

setPosition()

virtual bool aace::audio::AudioOutput::setPosition ( int64_t  position )

pure virtual

Notifies the platform implementation to set the playback position of the current audio source in the platform media player.

Parameters

[in]

position

The playback position in milliseconds to set in the platform media player

Returns

true if the platform implementation successfully handled the call, else false

getDuration()

virtual int64_t aace::audio::AudioOutput::getDuration ( )

pure virtual

Returns the duration of the current audio source. If the duration is unknown, then TIME_UNKNOWN should be returned.

Returns

The duration of the current audio source in milliseconds, or TIME_UNKNOWN.

getNumBytesBuffered()

int64_t aace::audio::AudioOutput::getNumBytesBuffered ( )

virtual

Returns the amount of audio data buffered.

Returns

the number of bytes of the audio data buffered, or 0 if it's unknown.

volumeChanged()

virtual bool aace::audio::AudioOutput::volumeChanged ( float  volume )

pure virtual

Notifies the platform implementation to set the volume of the output channel. The volume value should be scaled to fit the needs of the platform.

Parameters

[in]

volume

The volume to set on the output channel. volume is in the range [0,1].

Returns

true if the platform implementation successfully handled the call, else false

mutedStateChanged()

virtual bool aace::audio::AudioOutput::mutedStateChanged ( MutedState  state )

pure virtual

Notifies the platform implementation to apply a muted state has changed for the output channel

Parameters

[in]

state

The muted state to apply to the output channel. MutedState::MUTED when the output channel be muted, MutedState::UNMUTED when unmuted

Returns

true if the platform implementation successfully handled the call, else false

mediaStateChanged()

void aace::audio::AudioOutput::mediaStateChanged

(

MediaState

state

)

Notifies the Engine of an audio playback state change in the platform implementation. Must be called when the platform media player transitions between stopped and playing states.

Parameters

[in]

state

The new playback state of the platform media player

See also

MediaState

mediaError()

void aace::audio::AudioOutput::mediaError	(	MediaError	error,
		const std::string &	description = ""
	)

Notifies the Engine of an error during audio playback

Parameters

[in]	error	The error encountered by the platform media player during playback
[in]	description	A description of the error

See also

MediaError

audioFocusEvent()

void aace::audio::AudioOutput::audioFocusEvent

(

FocusAction

action

)

Request engine to perform the action mentioned in the parameter.

Parameters

[in]

action

An FocusAction platform interface wishes to request.

Member Data Documentation

TIME_UNKNOWN

const int64_t aace::audio::AudioOutput::TIME_UNKNOWN = -1

static

Used when audio time is unknown or indeterminate.