AlexaClientSDK  1.20.1
A cross-platform, modular SDK for interacting with the Alexa Voice Service
Classes | Public Member Functions | Static Public Member Functions | List of all members
alexaClientSDK::mediaPlayer::MediaPlayer Class Reference

#include <MediaPlayer.h>

Inheritance diagram for alexaClientSDK::mediaPlayer::MediaPlayer:
Inheritance graph
[legend]
Collaboration diagram for alexaClientSDK::mediaPlayer::MediaPlayer:
Collaboration graph
[legend]

Public Member Functions

 ~MediaPlayer ()
 
void doShutdown () override
 
Overridden MediaPlayerInterface methods.
SourceId setSource (std::shared_ptr< avsCommon::avs::attachment::AttachmentReader > attachmentReader, const avsCommon::utils::AudioFormat *format=nullptr, const avsCommon::utils::mediaPlayer::SourceConfig &config=avsCommon::utils::mediaPlayer::emptySourceConfig()) override
 
SourceId setSource (const std::string &url, std::chrono::milliseconds offset=std::chrono::milliseconds::zero(), const avsCommon::utils::mediaPlayer::SourceConfig &config=avsCommon::utils::mediaPlayer::emptySourceConfig(), bool repeat=false, const avsCommon::utils::mediaPlayer::PlaybackContext &playbackContext=avsCommon::utils::mediaPlayer::PlaybackContext()) override
 
SourceId setSource (std::shared_ptr< std::istream > stream, bool repeat=false, const avsCommon::utils::mediaPlayer::SourceConfig &config=avsCommon::utils::mediaPlayer::emptySourceConfig(), avsCommon::utils::MediaType format=avsCommon::utils::MediaType::UNKNOWN) override
 
bool play (SourceId id) override
 
bool stop (SourceId id) override
 
bool pause (SourceId id) override
 
bool resume (SourceId id) override
 
uint64_t getNumBytesBuffered () override
 
std::chrono::milliseconds getOffset (SourceId id) override
 
avsCommon::utils::Optional< avsCommon::utils::mediaPlayer::MediaPlayerStategetMediaPlayerState (SourceId id) override
 
void addObserver (std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > observer) override
 
void removeObserver (std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface > observer) override
 
Overridden SpeakerInterface methods.
bool setVolume (int8_t volume) override
 
bool setMute (bool mute) override
 
bool getSpeakerSettings (avsCommon::sdkInterfaces::SpeakerInterface::SpeakerSettings *settings) override
 
Overridden PipelineInterface methods.
void setAppSrc (GstAppSrc *appSrc) override
 
GstAppSrc * getAppSrc () const override
 
void setDecoder (GstElement *decoder) override
 
GstElement * getDecoder () const override
 
GstElement * getPipeline () const override
 
guint queueCallback (const std::function< gboolean()> *callback) override
 
guint attachSource (GSource *source) override
 
gboolean removeSource (guint tag) override
 
Overridden UrlContentToAttachmentConverter::ErrorObserverInterface methods.
void onError () override
 
void onWriteComplete () override
 
Overridden SourceObserverInterface methods.
void onFirstByteRead () override
 
- Public Member Functions inherited from alexaClientSDK::avsCommon::utils::RequiresShutdown
 RequiresShutdown (const std::string &name)
 
virtual ~RequiresShutdown ()
 Destructor. More...
 
const std::string & name () const
 
void shutdown ()
 
bool isShutdown () const
 
- Public Member Functions inherited from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface
virtual ~MediaPlayerInterface ()=default
 
virtual bool stop (SourceId id, std::chrono::seconds timeToPipelineShutdown)
 
virtual bool seekTo (SourceId id, std::chrono::milliseconds location, bool fromStart)
 
virtual utils::Optional< PlaybackAttributesgetPlaybackAttributes ()
 
virtual std::vector< PlaybackReportgetPlaybackReports ()
 
virtual utils::Optional< FingerprintgetFingerprint ()
 
- Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::SpeakerInterface
virtual ~SpeakerInterface ()=default
 
- Public Member Functions inherited from alexaClientSDK::avsCommon::sdkInterfaces::audio::EqualizerInterface
virtual ~EqualizerInterface ()=default
 
- Public Member Functions inherited from alexaClientSDK::playlistParser::UrlContentToAttachmentConverter::ErrorObserverInterface
virtual ~ErrorObserverInterface ()=default
 
- Public Member Functions inherited from alexaClientSDK::playlistParser::UrlContentToAttachmentConverter::WriteCompleteObserverInterface
virtual ~WriteCompleteObserverInterface ()=default
 
- Public Member Functions inherited from alexaClientSDK::mediaPlayer::SourceObserverInterface
virtual ~SourceObserverInterface ()=default
 

Static Public Member Functions

static std::shared_ptr< MediaPlayercreate (std::shared_ptr< avsCommon::sdkInterfaces::HTTPContentFetcherInterfaceFactoryInterface > contentFetcherFactory=nullptr, bool enableEqualizer=false, std::string name="", bool enableLiveMode=false)
 

Additional Inherited Members

- Public Types inherited from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface
using SourceId = uint64_t
 A type that identifies which source is currently being operated on. This must be unique across all instances. More...
 
- Static Public Attributes inherited from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface
static const SourceId ERROR = 0
 An SourceId used to represent an error from calls to setSource(). More...
 

Detailed Description

Class that handles creation of audio pipeline and playing of audio data.

Constructor & Destructor Documentation

◆ ~MediaPlayer()

alexaClientSDK::mediaPlayer::MediaPlayer::~MediaPlayer ( )

Destructor.

Member Function Documentation

◆ addObserver()

void alexaClientSDK::mediaPlayer::MediaPlayer::addObserver ( std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface playerObserver)
overridevirtual

Adds an observer to be notified when playback state changes.

Parameters
playerObserverThe observer to send the notifications to.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ attachSource()

guint alexaClientSDK::mediaPlayer::MediaPlayer::attachSource ( GSource *  source)
overridevirtual

Attach the source to the worker thread.

Parameters
sourceThe source to be executed on the worker thread.
Returns
The ID (greater than 0) of the source. 0 if there is an error.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ create()

std::shared_ptr< MediaPlayer > alexaClientSDK::mediaPlayer::MediaPlayer::create ( std::shared_ptr< avsCommon::sdkInterfaces::HTTPContentFetcherInterfaceFactoryInterface contentFetcherFactory = nullptr,
bool  enableEqualizer = false,
std::string  name = "",
bool  enableLiveMode = false 
)
static

Creates an instance of the MediaPlayer.

Parameters
contentFetcherFactoryUsed to create objects that can fetch remote HTTP content.
enableEqualizerFlag, indicating whether equalizer should be enabled for this instance.
nameReadable name for the new instance.
enableLiveModeFlag, indicating if the player is in live mode.
Returns
An instance of the MediaPlayer if successful else a nullptr.

◆ doShutdown()

void alexaClientSDK::mediaPlayer::MediaPlayer::doShutdown ( )
overridevirtual

Prepares/enables this object to be deleted. This should be the last function called on this object prior to deleting (or resetting) its shared_ptr.

Warning
  • Attempting to call functions on this object after calling shutdown() can result in undefined behavior.
  • Neglecting to call shutdown() on this object can result in resource leaks or other undefined behavior.

Implements alexaClientSDK::avsCommon::utils::RequiresShutdown.

◆ getAppSrc()

GstAppSrc * alexaClientSDK::mediaPlayer::MediaPlayer::getAppSrc ( ) const
overridevirtual

Gets the appSrc element of the AudioPipeline.

Returns
The appSrc element.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ getDecoder()

GstElement * alexaClientSDK::mediaPlayer::MediaPlayer::getDecoder ( ) const
overridevirtual

Gets the decoder element of the AudioPipeline.

Returns
The decoder element.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ getMediaPlayerState()

Optional< MediaPlayerState > alexaClientSDK::mediaPlayer::MediaPlayer::getMediaPlayerState ( SourceId  id)
overridevirtual

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

Parameters
idThe 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ getNumBytesBuffered()

uint64_t alexaClientSDK::mediaPlayer::MediaPlayer::getNumBytesBuffered ( )
overridevirtual

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

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

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ getOffset()

std::chrono::milliseconds alexaClientSDK::mediaPlayer::MediaPlayer::getOffset ( SourceId  id)
overridevirtual

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

Parameters
idThe 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

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ getPipeline()

GstElement * alexaClientSDK::mediaPlayer::MediaPlayer::getPipeline ( ) const
overridevirtual

Gets the pipeline of the AudioPipeline.

Returns
The pipeline.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ getSpeakerSettings()

bool alexaClientSDK::mediaPlayer::MediaPlayer::getSpeakerSettings ( avsCommon::sdkInterfaces::SpeakerInterface::SpeakerSettings settings)
overridevirtual

Return a SpeakerSettings object to indicate the current settings of the SpeakerInterface.

Parameters
[out]settingsA SpeakerSettings object if successful.
Returns
Whether the operation was successful.

Implements alexaClientSDK::avsCommon::sdkInterfaces::SpeakerInterface.

◆ onError()

void alexaClientSDK::mediaPlayer::MediaPlayer::onError ( )
overridevirtual

Notification that an error has occurred in the streaming of content.

Implements alexaClientSDK::playlistParser::UrlContentToAttachmentConverter::ErrorObserverInterface.

◆ onFirstByteRead()

void alexaClientSDK::mediaPlayer::MediaPlayer::onFirstByteRead ( )
overridevirtual

This indicates that the first bytes of data have been read from the source.

Implements alexaClientSDK::mediaPlayer::SourceObserverInterface.

◆ onWriteComplete()

void alexaClientSDK::mediaPlayer::MediaPlayer::onWriteComplete ( )
overridevirtual

Notification that the attachement has had all data written to it

Implements alexaClientSDK::playlistParser::UrlContentToAttachmentConverter::WriteCompleteObserverInterface.

◆ pause()

bool alexaClientSDK::mediaPlayer::MediaPlayer::pause ( SourceId  id)
overridevirtual

Pauses playing audio specified by the setSource() call.

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

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
idThe 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ play()

bool alexaClientSDK::mediaPlayer::MediaPlayer::play ( SourceId  id)
overridevirtual

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
idThe 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ queueCallback()

guint alexaClientSDK::mediaPlayer::MediaPlayer::queueCallback ( const std::function< gboolean()> *  callback)
overridevirtual

Queue the specified callback for execution on the worker thread.

Parameters
callbackThe callback to queue.
Returns
The ID of the queued callback (for calling g_source_remove).

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ removeObserver()

void alexaClientSDK::mediaPlayer::MediaPlayer::removeObserver ( std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface playerObserver)
overridevirtual

Removes an observer to be notified when playback state changes.

Parameters
playerObserverThe observer to be removed

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ removeSource()

gboolean alexaClientSDK::mediaPlayer::MediaPlayer::removeSource ( guint  tag)
overridevirtual

Remove the callback from the worker thread.

Parameters
TheID of the queued callback.
Returns
Whether the removal is successful.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ resume()

bool alexaClientSDK::mediaPlayer::MediaPlayer::resume ( MediaPlayer::SourceId  id)
overridevirtual

To resume playback after a pause, call resume. Calling play will reset the pipeline and source, and will not resume playback.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ setAppSrc()

void alexaClientSDK::mediaPlayer::MediaPlayer::setAppSrc ( GstAppSrc *  appSrc)
overridevirtual

Sets the appSrc element in the AudioPipeline.

Parameters
appSrcThe element the appSrc of AudioPipeline should be set to.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ setDecoder()

void alexaClientSDK::mediaPlayer::MediaPlayer::setDecoder ( GstElement *  decoder)
overridevirtual

Sets the decoder element in the AudioPipeline

Parameters
decoderThe element the decoder of AudioPipeline should be set to.

Implements alexaClientSDK::mediaPlayer::PipelineInterface.

◆ setMute()

bool alexaClientSDK::mediaPlayer::MediaPlayer::setMute ( bool  mute)
overridevirtual

Set the mute of the speaker.

Parameters
muteRepresents whether the speaker should be muted (true) or unmuted (false).
Returns
Whether the operation was successful.

Implements alexaClientSDK::avsCommon::sdkInterfaces::SpeakerInterface.

◆ setSource() [1/3]

MediaPlayer::SourceId alexaClientSDK::mediaPlayer::MediaPlayer::setSource ( std::shared_ptr< avsCommon::avs::attachment::AttachmentReader attachmentReader,
const avsCommon::utils::AudioFormat format = nullptr,
const avsCommon::utils::mediaPlayer::SourceConfig config = avsCommon::utils::mediaPlayer::emptySourceConfig() 
)
overridevirtual

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
attachmentReaderObject with which to read an incoming audio attachment.
formatThe audioFormat to be used to interpret raw audio data.
configMedia 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ setSource() [2/3]

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

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
urlThe url to set as the source.
offsetAn optional offset parameter to start playing from when a play() call is made.
configMedia configuration of source.
repeatAn optional parameter to play the url source in a loop.
playbackContextAn 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ setSource() [3/3]

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

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
streamObject from which to read an incoming audio stream.
repeatWhether the audio stream should be played in a loop until stopped.
configMedia configuration of source.
formatThe 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.

◆ setVolume()

bool alexaClientSDK::mediaPlayer::MediaPlayer::setVolume ( int8_t  volume)
overridevirtual

Set the absolute volume of the speaker. volume will be [AVS_SET_VOLUME_MIN, AVS_SET_VOLUME_MAX], and implementers of the interface must normalize the volume to fit the needs of their drivers.

Parameters
volumeA volume to set the speaker to.
Returns
Whether the operation was successful.

Implements alexaClientSDK::avsCommon::sdkInterfaces::SpeakerInterface.

◆ stop()

bool alexaClientSDK::mediaPlayer::MediaPlayer::stop ( SourceId  id)
overridevirtual

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
idThe 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.

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerInterface.


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

AlexaClientSDK 1.20.1 - Copyright 2016-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0