#include <CaptionManager.h>

Inheritance diagram for alexaClientSDK::captions::CaptionManager:

[legend]

Collaboration diagram for alexaClientSDK::captions::CaptionManager:

[legend]

Public Member Functions
RequiresShutdown methods
void	doShutdown () override

CaptionManagerInterface methods
void	onCaption (CaptionFrame::MediaPlayerSourceId sourceId, const CaptionData &captionData) override

void	setCaptionPresenter (const std::shared_ptr< CaptionPresenterInterface > &presenter) override

void	setMediaPlayers (const std::vector< std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface >> &mediaPlayers) override

void	addMediaPlayer (const std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface > &mediaPlayer) override

void	removeMediaPlayer (const std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface > &mediaPlayer) override

bool	isEnabled () const override

CaptionFrameParseListenerInterface methods
void	onParsed (const CaptionFrame &captionFrame) override

MediaPlayerObserverInterface methods
void	onPlaybackStarted (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onPlaybackFinished (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onPlaybackError (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::ErrorType &type, std::string error, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onPlaybackPaused (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onPlaybackResumed (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onPlaybackStopped (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

void	onFirstByteRead (CaptionFrame::MediaPlayerSourceId id, const avsCommon::utils::mediaPlayer::MediaPlayerState &state) override

Public Member Functions inherited from alexaClientSDK::captions::CaptionManagerInterface
virtual	~CaptionManagerInterface ()=default

Public Member Functions inherited from alexaClientSDK::captions::CaptionFrameParseListenerInterface
virtual	~CaptionFrameParseListenerInterface ()=default

Public Member Functions inherited from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface
virtual	~MediaPlayerObserverInterface ()=default

virtual void	onBufferUnderrun (SourceId, const MediaPlayerState &)

virtual void	onBufferRefilled (SourceId, const MediaPlayerState &)

virtual void	onBufferingComplete (SourceId, const MediaPlayerState &)

virtual void	onSeeked (SourceId, const MediaPlayerState &, const MediaPlayerState &)

virtual void	onTags (SourceId, std::unique_ptr< const VectorOfTags >, const MediaPlayerState &)

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

Static Public Member Functions
static std::shared_ptr< CaptionManager >	create (std::shared_ptr< CaptionParserInterface > parser, std::shared_ptr< TimingAdapterFactory > timingAdapterFactory=nullptr)

Additional Inherited Members
Public Types inherited from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface
enum	TagType { TagType::STRING, TagType::UINT, TagType::INT, TagType::DOUBLE, TagType::BOOLEAN }
	The different types of metadata "stream tags". More...

using	SourceId = MediaPlayerInterface::SourceId
	A type that identifies which source is currently being operated on. More...

typedef std::vector< TagKeyValueType >	VectorOfTags

Detailed Description

This class is the primary mediator between unprocessed captions content, one or more caption parsers, and an implementation of the CaptionPresenterInterface.

This class:

routes unparsed caption data to the caption parser
wraps caption text according to how much can fit on the screen, based on CaptionPresenterInterface::getWrapIndex()
notifies a CaptionPresenterInterface when and for how long each CaptionFrame should be shown
monitors media players to watch for when captions should be shown and hidden
may receive captions from multiple sources in parallel; caption focus will match with the originating media player's state.
is designed to work with en-US. While other languages may work fine, the breaks between words may be off, or the line wraps may not be accurate. If improved locale support is required, then the line break logic in the CaptionManager::onParsed() method should be modified to use a locale-safe method for determining the break points between words. One such method is supplied through ICU's BreakIterator: http://icu-project.org/apiref/icu4c/classicu_1_1BreakIterator.html

Member Function Documentation

◆ addMediaPlayer()

void alexaClientSDK::captions::CaptionManager::addMediaPlayer ( const std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface > & mediaPlayer )

overridevirtual

Adds a MediaPlayerInterface instance responsible for producing caption content. This media player will be appended to the list of active media players.

Parameters

mediaPlayer The media player which should be observed for media state changes.

Implements alexaClientSDK::captions::CaptionManagerInterface.

◆ create()

static std::shared_ptr<CaptionManager> alexaClientSDK::captions::CaptionManager::create	(	std::shared_ptr< CaptionParserInterface >	parser,
		std::shared_ptr< TimingAdapterFactory >	timingAdapterFactory = `nullptr`
	)

static

Creates a CaptionManager as as an observer of the provided MediaPlayerInterfaces so that playback state of the media players can be kept in sync with the captioned media.

Parameters

parser	Parsing implementation to use for parsing captions content.
timingAdapterGenerator	The generator used to produce `CaptionTimingAdapterInterface` objects on demand.

Returns: A ready to use CaptionManager.

◆ doShutdown()

void alexaClientSDK::captions::CaptionManager::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.

◆ isEnabled()

bool alexaClientSDK::captions::CaptionManager::isEnabled ( ) const

overridevirtual

Whether captions are enabled. Capability Agents may skip unnecessary processing if captions are disabled.

Returns: Whether captions is enabled.

Implements alexaClientSDK::captions::CaptionManagerInterface.

◆ onCaption()

void alexaClientSDK::captions::CaptionManager::onCaption	(	CaptionFrame::MediaPlayerSourceId	sourceId,
		const CaptionData &	captionData
	)

overridevirtual

Starts processing the provided CaptionData with the available parser. If no parser is present, then a warning will be logged to the console, and the CaptionData object will be ignored.

Parameters

sourceId	The ID of the media source for this caption.
captionData	The object containing the raw caption content and metadata.

Implements alexaClientSDK::captions::CaptionManagerInterface.

◆ onFirstByteRead()

void alexaClientSDK::captions::CaptionManager::onFirstByteRead	(	CaptionFrame::MediaPlayerSourceId	id,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &	state
	)

inlineoverridevirtual

This is an indication to the observer that the MediaPlayer has read its first byte of data.

Parameters

id	The id of the source to which this callback corresponds to.
state	Metadata about the media player state

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onParsed()

void alexaClientSDK::captions::CaptionManager::onParsed ( const CaptionFrame & captionFrame )

overridevirtual

Called by the caption parser implementation for each caption frame that has been parsed.

Parameters

captionFrame The single frame of captions, containing everything needed to be displayed.

Implements alexaClientSDK::captions::CaptionFrameParseListenerInterface.

◆ onPlaybackError()

void alexaClientSDK::captions::CaptionManager::onPlaybackError	(	CaptionFrame::MediaPlayerSourceId	id,
		const avsCommon::utils::mediaPlayer::ErrorType &	type,
		std::string	error,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &	state
	)

overridevirtual

This is an indication to the observer that the MediaPlayer encountered an error. Errors can occur during playback.

Note: The observer must quickly return from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

id	The id of the source to which this callback corresponds to.
type	The type of error encountered by the `MediaPlayerInterface`.
error	The error encountered by the `MediaPlayerInterface`.
state	Metadata about the media player state

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onPlaybackFinished()

void alexaClientSDK::captions::CaptionManager::onPlaybackFinished	(	CaptionFrame::MediaPlayerSourceId	id,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &	state
	)

overridevirtual

This is an indication to the observer that the MediaPlayer finished the source.

Note: The observer must quickly return to quickly from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

id	The id of the source to which this callback corresponds to.
state	Metadata about the media player state

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onPlaybackPaused()

void alexaClientSDK::captions::CaptionManager::onPlaybackPaused	(	CaptionFrame::MediaPlayerSourceId	,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &
	)

overridevirtual

This is an indication to the observer that the MediaPlayer has paused playing the source.

Note: The observer must quickly return from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

SourceId	The id of the source to which this callback corresponds to.
MediaPlayerState	Metadata about the media player state

Reimplemented from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onPlaybackResumed()

void alexaClientSDK::captions::CaptionManager::onPlaybackResumed	(	CaptionFrame::MediaPlayerSourceId	,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &
	)

overridevirtual

This is an indication to the observer that the MediaPlayer has resumed playing the source.

Note: The observer must quickly return from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

SourceId	The id of the source to which this callback corresponds to.
MediaPlayerState	Metadata about the media player state

Reimplemented from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onPlaybackStarted()

void alexaClientSDK::captions::CaptionManager::onPlaybackStarted	(	CaptionFrame::MediaPlayerSourceId	id,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &	state
	)

overridevirtual

This is an indication to the observer that the MediaPlayer has started playing the source specified by the id.

Note: The observer must quickly return to quickly from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

id	The id of the source to which this callback corresponds to.
state	Metadata about the media player state

Implements alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ onPlaybackStopped()

void alexaClientSDK::captions::CaptionManager::onPlaybackStopped	(	CaptionFrame::MediaPlayerSourceId	,
		const avsCommon::utils::mediaPlayer::MediaPlayerState &
	)

overridevirtual

This is an indication to the observer that the MediaPlayer has stopped the source.

Note: The observer must quickly return from this callback. Failure to do so could block the MediaPlayer from further processing.

Parameters

SourceId	The id of the source to which this callback corresponds to.
MediaPlayerState	Metadata about the media player state

Reimplemented from alexaClientSDK::avsCommon::utils::mediaPlayer::MediaPlayerObserverInterface.

◆ removeMediaPlayer()

void alexaClientSDK::captions::CaptionManager::removeMediaPlayer ( const std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface > & mediaPlayer )

overridevirtual

Removes the MediaPlayerInterface instance from the list of media players responsible for producing caption content. The rest of the list remains unchanged.

Parameters

mediaPlayer The media player to remove.

Implements alexaClientSDK::captions::CaptionManagerInterface.

◆ setCaptionPresenter()

void alexaClientSDK::captions::CaptionManager::setCaptionPresenter ( const std::shared_ptr< CaptionPresenterInterface > & presenter )

overridevirtual

Sets the CaptionPresenterInterface instance responsible for measuring styled caption text and displaying or hiding the captions. If called multiple times, the last CaptionPresenterInterface set will be the active presenter.

Parameters

presenter The CaptionPresenterInterface instance to use for caption text measurement and presentation.

Implements alexaClientSDK::captions::CaptionManagerInterface.

◆ setMediaPlayers()

void alexaClientSDK::captions::CaptionManager::setMediaPlayers ( const std::vector< std::shared_ptr< avsCommon::utils::mediaPlayer::MediaPlayerInterface >> & mediaPlayers )

overridevirtual

Sets the MediaPlayerInterface instances responsible for producing caption content. If called multiple times, the last vector of MediaPlayerInterface set will be the active media players.

Parameters

mediaPlayers The media players which should be observed for media state changes.

Implements alexaClientSDK::captions::CaptionManagerInterface.

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

/workplace/avs-device-sdk/Captions/Implementation/include/Captions/CaptionManager.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addMediaPlayer()

◆ create()

◆ doShutdown()

◆ isEnabled()

◆ onCaption()

◆ onFirstByteRead()

◆ onParsed()

◆ onPlaybackError()

◆ onPlaybackFinished()

◆ onPlaybackPaused()

◆ onPlaybackResumed()

◆ onPlaybackStarted()

◆ onPlaybackStopped()

◆ removeMediaPlayer()

◆ setCaptionPresenter()

◆ setMediaPlayers()