#include <MediaPlayerInterface.h>

Inheritance diagram for alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface:

[legend]

Public Types
using	SourceId = uint64_t
	A type that identifies which source is currently being operated on. This must be unique across all instances. More...

Public Member Functions
virtual	~MediaPlayerInterface ()=default

virtual SourceId	setSource (std::shared_ptr< avsCommon::avs::attachment::AttachmentReader > attachmentReader, const avsCommon::utils::AudioFormat *format=nullptr, const SourceConfig &config=emptySourceConfig())=0

virtual SourceId	setSource (std::shared_ptr< avsCommon::avs::attachment::AttachmentReader > attachmentReader, std::chrono::milliseconds offsetAdjustment, const avsCommon::utils::AudioFormat *format=nullptr, const SourceConfig &config=emptySourceConfig())=0

virtual SourceId	setSource (const std::string &url, std::chrono::milliseconds offset=std::chrono::milliseconds::zero(), const SourceConfig &config=emptySourceConfig(), bool repeat=false, const PlaybackContext &playbackContext=PlaybackContext())=0

virtual SourceId	setSource (std::shared_ptr< std::istream > stream, bool repeat=false, const SourceConfig &config=emptySourceConfig(), avsCommon::utils::MediaType format=avsCommon::utils::MediaType::UNKNOWN)=0

virtual bool	play (SourceId id)=0

virtual bool	stop (SourceId id)=0

virtual bool	stop (SourceId id, std::chrono::seconds timeToPipelineShutdown)

virtual bool	pause (SourceId id)=0

virtual bool	resume (SourceId id)=0

virtual bool	seekTo (SourceId id, std::chrono::milliseconds location, bool fromStart)

virtual std::chrono::milliseconds	getOffset (SourceId id)=0

virtual uint64_t	getNumBytesBuffered ()=0

virtual utils::Optional< avsCommon::utils::mediaPlayer::MediaPlayerState >	getMediaPlayerState (SourceId id)=0

virtual void	addObserver (std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > playerObserver)=0

virtual void	removeObserver (std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > playerObserver)=0

virtual utils::Optional< PlaybackAttributes >	getPlaybackAttributes ()

virtual std::vector< PlaybackReport >	getPlaybackReports ()

virtual utils::Optional< Fingerprint >	getFingerprint ()

Static Public Attributes
static const SourceId	ERROR = 0
	An `SourceId` used to represent an error from calls to `setSource()`. More...

Detailed Description

A MediaPlayerInterface allows for sourcing, playback control, navigation, and querying the state of media content. A MediaPlayerInterface implementation must only handle one source at a time.

Each playback controlling API call (i.e. play(), pause(), stop(), resume()) that succeeds will also result in a callback to the observer. To see how to tell when a method succeeded, please refer to the documentation of each method.

An implementation can call onPlaybackError() at any time. If an onPlaybackError() callback occurs while a plaback controlling API call is waiting for a callback, the original callback must not be made, and the implementation should revert to a stopped state. Any subsequent operations after an onPlaybackError() callback must be preceded by a new setSource() call.

Implementations must make a call to onPlaybackStopped() with the previous SourceId when a new source is set if the previous source was in a non-stopped state.

note A MediaPlayerInterface implementation must be able to support the various audio formats listed at: https://developer.amazon.com/docs/alexa/alexa-voice-service/recommended-media-support.html.

Member Typedef Documentation

◆ SourceId

using alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::SourceId = uint64_t

A type that identifies which source is currently being operated on. This must be unique across all instances.

Constructor & Destructor Documentation

◆ ~MediaPlayerInterface()

virtual alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::~MediaPlayerInterface ( )

virtualdefault

Destructor.

Member Function Documentation

◆ addObserver()

virtual void alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::addObserver ( std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > playerObserver )

pure virtual

Adds an observer to be notified when playback state changes.

Parameters

playerObserver The observer to send the notifications to.

◆ getFingerprint()

utils::Optional< Fingerprint > alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getFingerprint ( )

inlinevirtual

Get fingerprint

Returns: Media Player fingerprint

◆ getMediaPlayerState()

virtual utils::Optional<avsCommon::utils::mediaPlayer::MediaPlayerState> alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getMediaPlayerState ( SourceId id )

pure virtual

Returns the current state of the media player source, including the id and offset.

Parameters

id	The unique id of the source for the desired state.

Returns: Optional state including the offset. A blank Optional is returned if retrieving this information fails.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ getNumBytesBuffered()

virtual uint64_t alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getNumBytesBuffered ( )

pure virtual

Returns the number of bytes queued up in the media player buffers.

Returns: The number of bytes currently queued in this MediaPlayer's buffer.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ getOffset()

virtual std::chrono::milliseconds alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getOffset ( SourceId id )

pure virtual

Returns the offset, in milliseconds, of the media source.

Parameters

id	The unique id of the source on which to operate.

Returns: If the specified source is playing, the offset in milliseconds that the source has been playing will be returned. If the specified source is not playing, the last offset it played will be returned.

Deprecated:: Use getMediaPlayerState instead, which contains the offset

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ getPlaybackAttributes()

utils::Optional< PlaybackAttributes > alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getPlaybackAttributes ( )

inlinevirtual

Get PlaybackAttributes for the current stream being played. This method only needs to be implemented if your mediaplayer supports Premium Audio.

Returns: playbackAttributes The playback attributes for the current stream if premium audio is supported and it has an active source; otherwise, an empty object.

◆ getPlaybackReports()

std::vector< PlaybackReport > alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::getPlaybackReports ( )

inlinevirtual

Get list of PlaybackReports for current track. This method only needs to be implemented if your mediaplayer supports Premium Audio.

Returns: The list of PlaybackReport for current track if premium audio is supported and it has an active source; otherwise, an empty list.

◆ pause()

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::pause ( SourceId id )

pure virtual

Pauses playing audio specified by the setSource() call.

The source must be set before issuing pause(). If pause() is called

without making a setSource(), false will be returned.
when audio is not starting/resuming/playing, false will be returned.
when a play() or resume() call has already been made, but no callback has been issued yet for those functions, the audio stream will pause without playing any audio. Implementations must call both MediaPlayerObserverInterface::onPlaybackStarted() / MediaPlayerObserverInterface::onPlaybackResumed and MediaPlayerObserverInterface::onPlaybackPaused() in this scenario, as both the play() / resume() and the pause() are required to have corresponding callbacks.

If the id does not match the id of the active source, then false will be returned. If the pause() succeeded, true will be returned. When true is returned, a callback will be made to either MediaPlayerObserverInterface::onPlaybackPaused() or to MediaPlayerObserverInterface::onPlaybackError().

Parameters

id	The unique id of the source on which to operate.

Returns: true if the call succeeded, in which case a callback will be made, or false otherwise.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ play()

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::play ( SourceId id )

pure virtual

Starts playing audio specified by the setSource() call.

The source must be set before issuing play().

If play() is called

without making a setSource(), false will be returned.
when audio is already playing, false will be returned.
after a play() call has already been made but no callback or return code has been issued yet, false will be returned.

If the id does not match the id of the active source, then false will be returned. If the play() succeeded, true will be returned. When true is returned, a callback will be made to either MediaPlayerObserverInterface::onPlaybackStarted() or to MediaPlayerObserverInterface::onPlaybackError().

Parameters

id	The unique id of the source on which to operate.

Returns: true if the call succeeded, in which case a callback will be made, or false otherwise.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, alexaClientSDK::acsdkAlerts::renderer::test::TestMediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ removeObserver()

virtual void alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::removeObserver ( std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > playerObserver )

pure virtual

Removes an observer to be notified when playback state changes.

Parameters

playerObserver The observer to be removed

◆ resume()

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::resume ( SourceId id )

pure virtual

Resumes playing the paused audio specified by the setSource() call.

The source must be set before issuing resume(). If resume() is called

without making a setSource(), false will be returned.
when audio is already playing, false will be returned.
when audio is not paused, false will be returned.
after a resume() call has already been made but no callback or return code has been issued yet, false will be returned.

If the id does not match the id of the active source, then false will be returned. If the resume() succeeded, true will be returned. When true is returned, a callback will be made to either MediaPlayerObserverInterface::onPlaybackResumed() or to MediaPlayerObserverInterface::onPlaybackError().

Parameters

id	The unique id of the source on which to operate.

Returns: true if the call succeeded, in which case a callback will be made, or false otherwise.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ seekTo()

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::seekTo	(	SourceId	id,
		std::chrono::milliseconds	location,
		bool	fromStart
	)

inlinevirtual

Seek to a position within the current song. This should only be called after setSource, and while playing or after a call to stop(id, timeout) before the timeout period has expired. NOTE: A call to seekTo() while STOPPED will not result in playback starting. If the pipeline has shutdown, false will be returned, if the pipeline is still open, a onSeeked callback will be made with the requested location as the endState offset, but playback will not resume until play is called again.

NOTE: Default empty implementation to avoid build breakage.

Parameters

id	The unique id of the source on which to operate.
location	Seek location
fromStart	true if seek location is reletive to song start, false if reletive to current position.

Returns: true if the call succeeded, or false otherwise.

◆ setSource() [1/4]

virtual SourceId alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::setSource	(	std::shared_ptr< avsCommon::avs::attachment::AttachmentReader >	attachmentReader,
		const avsCommon::utils::AudioFormat *	format = `nullptr`,
		const SourceConfig &	config = `emptySourceConfig()`
	)

pure virtual

Set an AttachmentReader source to play. The source should be set before making calls to any of the playback control APIs. If any source was set prior to this call, that source will be discarded.

Note: A MediaPlayerInterface implementation must handle only one source at a time. An implementation must call MediaPlayerObserverInterface::onPlaybackStopped() with the previous source's id if there was a source set. Also, an implementation must call MediaPlayerObserverInterface::onBufferingComplete() when this source has been fully buffered

Parameters

attachmentReader	Object with which to read an incoming audio attachment.
format	The audioFormat to be used to interpret raw audio data.
config	Media configuration of source.

Returns: The SourceId that represents the source being handled as a result of this call. ERROR will be returned if the source failed to be set. Must be unique across all instances.

Implemented in alexaClientSDK::avsCommon::utils::mediaPlayer::test::MockMediaPlayer.

◆ setSource() [2/4]

virtual SourceId alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::setSource	(	std::shared_ptr< avsCommon::avs::attachment::AttachmentReader >	attachmentReader,
		std::chrono::milliseconds	offsetAdjustment,
		const avsCommon::utils::AudioFormat *	format = `nullptr`,
		const SourceConfig &	config = `emptySourceConfig()`
	)

pure virtual

Set an AttachmentReader source to play. The source should be set before making calls to any of the playback control APIs. If any source was set prior to this call, that source will be discarded.

Note: A MediaPlayerInterface implementation must handle only one source at a time. An implementation must call MediaPlayerObserverInterface::onPlaybackStopped() with the previous source's id if there was a source set. Also, an implementation must call MediaPlayerObserverInterface::onBufferingComplete() when this source has been fully buffered

Parameters

attachmentReader	Object with which to read an incoming audio attachment.
format	The audioFormat to be used to interpret raw audio data.
offsetAdjustment	Offset adjustment required for the offset reported
config	Media configuration of source.

Returns: The SourceId that represents the source being handled as a result of this call. ERROR will be returned if the source failed to be set. Must be unique across all instances.

Implemented in alexaClientSDK::avsCommon::utils::mediaPlayer::test::MockMediaPlayer.

◆ setSource() [3/4]

virtual SourceId alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::setSource	(	const std::string &	url,
		std::chrono::milliseconds	offset = `std::chrono::milliseconds::zero()`,
		const SourceConfig &	config = `emptySourceConfig()`,
		bool	repeat = `false`,
		const PlaybackContext &	playbackContext = `PlaybackContext()`
	)

pure virtual

Set a url source to play. The source should be set before making calls to any of the playback control APIs. If any source was set prior to this call, that source will be discarded.

Note: A MediaPlayerInterface implementation must handle only one source at a time. An implementation must call MediaPlayerObserverInterface::onPlaybackStopped() with the previous source's id if there was a source set. Also, an implementation must call MediaPlayerObserverInterface::onBufferingComplete() when this source has been fully buffered

Parameters

url	The url to set as the source.
offset	An optional offset parameter to start playing from when a `play()` call is made.
config	Media configuration of source.
repeat	An optional parameter to play the url source in a loop.
playbackContext	An optional parameter used for sending headers needed for data requests.

Returns: The SourceId that represents the source being handled as a result of this call. ERROR will be returned if the source failed to be set. Must be unique across all instances.

Implemented in alexaClientSDK::acsdkAlerts::renderer::test::TestMediaPlayer, alexaClientSDK::avsCommon::utils::mediaPlayer::test::MockMediaPlayer, alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ setSource() [4/4]

virtual SourceId alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::setSource	(	std::shared_ptr< std::istream >	stream,
		bool	repeat = `false`,
		const SourceConfig &	config = `emptySourceConfig()`,
		avsCommon::utils::MediaType	format = `avsCommon::utils::MediaType::UNKNOWN`
	)

pure virtual

Set an istream source to play. The source should be set before making calls to any of the playback control APIs. If any source was set prior to this call, that source will be discarded.

Note: A MediaPlayerInterface implementation must handle only one source at a time. An implementation must call MediaPlayerObserverInterface::onPlaybackStopped() with the previous source's id if there was a source set. Also, an implementation must call MediaPlayerObserverInterface::onBufferingComplete() when this source has been fully buffered

Parameters

stream	Object from which to read an incoming audio stream.
repeat	Whether the audio stream should be played in a loop until stopped.
config	Media configuration of source.
format	The `MediaType` audio encoding format of the incoming audio stream.

Returns: The SourceId that represents the source being handled as a result of this call. ERROR will be returned if the source failed to be set. Must be unique across all instances.

Implemented in alexaClientSDK::acsdkAlerts::renderer::test::TestMediaPlayer, alexaClientSDK::avsCommon::utils::mediaPlayer::test::MockMediaPlayer, alexaClientSDK::mediaPlayer::MediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ stop() [1/2]

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::stop ( SourceId id )

pure virtual

Stops playing the audio specified by the setSource() call.

The source must be set before issuing stop().

Once stop() has been called, subsequent play() calls will fail. If stop() is called when audio has already stopped, false will be returned. If the id does not match the id of the active source, then false will be returned. If the stop() succeeded, true will be returned. When true is returned, a callback will be made to either MediaPlayerObserverInterface::onPlaybackStopped() or to MediaPlayerObserverInterface::onPlaybackError().

Parameters

id	The unique id of the source on which to operate.

Returns: true if the call succeeded, in which case a callback will be made, or false otherwise.

Implemented in alexaClientSDK::mediaPlayer::MediaPlayer, alexaClientSDK::acsdkAlerts::renderer::test::TestMediaPlayer, and alexaClientSDK::mediaPlayer::android::AndroidSLESMediaPlayer.

◆ stop() [2/2]

virtual bool alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::stop	(	SourceId	id,
		std::chrono::seconds	timeToPipelineShutdown
	)

inlinevirtual

Stops playing the audio specified by the setSource() call, but will keep the pipeline open for a set time. NOTE: This call is optional, and may not be implemented by all MediaPlayers

The source must be set before issuing stop().

Once stop() has been called, and the pipeline has shutdown, subsequent play() calls will fail. However, if play() is called while the pipeline remains open, playback will continue from the stopped location, or, if seekTo() is called while the pipeline is open, and play() also called while the pipeline is open, then playback will resume from the location specified in the seekTo() call. If stop() is called when audio has already stopped, false will be returned. If the id does not match the id of the active source, then false will be returned. If the stop() succeeded, true will be returned. When true is returned, a callback will be made to either MediaPlayerObserverInterface::onPlaybackStopped() or to MediaPlayerObserverInterface::onPlaybackError().

Parameters

id	The unique id of the source on which to operate.
timeToPipelineShutdown	The pipeline will be kept open for this long, and during that time, a call to will resume playback from the stopped location (or seeked location, if seek is called)

Returns: true if the call succeeded, in which case a callback will be made, or false otherwise.

Member Data Documentation

◆ ERROR

const SourceId alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface::ERROR = 0

static

An SourceId used to represent an error from calls to setSource().

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

/workplace/avs-device-sdk/AVSCommon/Utils/include/AVSCommon/Utils/MediaPlayer/MediaPlayerInterface.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ SourceId

Constructor & Destructor Documentation

◆ ~MediaPlayerInterface()

Member Function Documentation

◆ addObserver()

◆ getFingerprint()

◆ getMediaPlayerState()

◆ getNumBytesBuffered()

◆ getOffset()

◆ getPlaybackAttributes()

◆ getPlaybackReports()

◆ pause()

◆ play()

◆ removeObserver()

◆ resume()

◆ seekTo()

◆ setSource() [1/4]

◆ setSource() [2/4]

◆ setSource() [3/4]

◆ setSource() [4/4]

◆ stop() [1/2]

◆ stop() [2/2]

Member Data Documentation

◆ ERROR