com.brightcove.player.offline

Class MediaDownloadable

java.lang.Object

com.brightcove.player.offline.MediaDownloadable

Direct Known Subclasses:

DashDownloadable, Mp4Downloadable

public abstract class MediaDownloadable
extends java.lang.Object

An abstract class that holds information related to a remote media (Video) to be downloaded and responsible to manage the download of its components such as video, audio and text.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MediaDownloadable.DownloadEventListener Interface definition for a callback to be invoked when a media download is either completed, cancelled or failed because an error has occurred.
static interface	MediaDownloadable.MediaFormatListener Interface definition for a callback to be invoked when the video tracks have been read and are available.
static interface	MediaDownloadable.OnVideoSizeCallback

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	AUDIO_LANGUAGE_ROLES The key for the Bundle which returns the available audio language roles as ArrayList, matching the size and indexes of AUDIO_LANGUAGES.
static java.lang.String	AUDIO_LANGUAGES The key for the Bundle which returns the available audio languages as ArrayList
static java.lang.String	CAPTIONS The key for the Bundle which returns the available captions as ArrayList
protected android.os.Bundle	configurationBundle
protected android.content.Context	context
static java.lang.String	DEFAULT_MPD_NAME The name of that will be used for saving DASH manifest.
protected MediaDownloadable.DownloadEventListener	downloadEventListener
protected DownloadManager	downloadManager
protected long	estimatedSize
protected RequestConfig	requestConfig
protected Video	video
static java.lang.String	VIDEO_RENDITIONS The key for the Bundle which returns the available video renditions as ArrayList

Constructor Summary

Constructors

Constructor and Description
MediaDownloadable(android.content.Context context, Video video, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig)

Method Summary

Modifier and Type	Method and Description
boolean	cancelDownload() Cancels download of the media if it has not been completed yet.
static MediaDownloadable	create(android.content.Context context, java.lang.String videoUrl, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig) Creates the best MediaDownloadable for the given video url on the supported delivery types.
static MediaDownloadable	create(android.content.Context context, Video video, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig) Creates the best MediaDownloadable for the given video based on the supported delivery types.
protected DownloadManager.Request	createDownloadRequest(android.net.Uri requestUri, android.net.Uri destinationUri) Create a download request which can be enqueued with the DownloadManager.
boolean	deleteDownload() Deletes the offline copy of the media.
protected void	enqueueDownloadRequest(DownloadManager.Request... requests) Enqueues a list of download requests to the download manager.
void	estimatedSize(MediaDownloadable.OnVideoSizeCallback callback) Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.
android.os.Bundle	getConfigurationBundle()
java.io.File	getDownloadDirectory() Gets the directory the will hold all the assets related to this media.
DownloadStatus	getDownloadStatus() Checks the overall download status by inspecting the status of each request in the entire download set.
long	getEstimatedSize() Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.
abstract void	getMediaFormatTracksAvailable(MediaDownloadable.MediaFormatListener mediaFormatListener) An asynchronous call to retrieve the MediaFormat tracks available for the current video.
protected abstract java.util.HashMap<java.lang.String,java.io.Serializable>	getMediaProperties()
protected void	onMediaDownloadCancelled() Called when the media download has been removed before the download has completed.
protected void	onMediaDownloadComplete(DownloadStatus status) Called when the media download has completed successfully.
protected void	onMediaDownloadDeleted() Called when the media download has been removed after the download has completed.
protected void	onMediaDownloadFailed(DownloadStatus status) Called when the media download has failed.
protected void	onMediaDownloadPaused(DownloadStatus status) Called when the media download has been paused.
protected void	onMediaDownloadProgress(DownloadStatus status) Called when the media download progress has changed.
protected void	onMediaDownloadRequested() This method will be called when the MediaDownloadable starts to process the download request.
protected void	onMediaDownloadStarted() This method will be called when the MediaDownloadable starts to download the media.
int	pauseDownload() Attempts to pause download of this media.
static void	registerDownloadable(DeliveryType deliveryType, java.lang.Class<? extends MediaDownloadable> downloadableClass) Registers the downloadable class that must be used to handled download of the specified media delivery type.
boolean	requestDownload() Requests the media to be downloaded asynchronously.
int	resumeDownload() Attempts to resume download of this media.
void	setConfigurationBundle(android.os.Bundle bundle)
void	setVideoBitrate(int videoBitrate) Sets the video bitrate cap which will be used to determine what rendition will be downloaded.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MPD_NAME

public static final java.lang.String DEFAULT_MPD_NAME

The name of that will be used for saving DASH manifest.

See Also:

Constant Field Values

VIDEO_RENDITIONS

public static final java.lang.String VIDEO_RENDITIONS

The key for the Bundle which returns the available video renditions as ArrayList

See Also:

Constant Field Values

AUDIO_LANGUAGES

public static final java.lang.String AUDIO_LANGUAGES

The key for the Bundle which returns the available audio languages as ArrayList

See Also:

Constant Field Values

AUDIO_LANGUAGE_ROLES

public static final java.lang.String AUDIO_LANGUAGE_ROLES

The key for the Bundle which returns the available audio language roles as ArrayList, matching the size and indexes of AUDIO_LANGUAGES.

See Also:

Constant Field Values

CAPTIONS

public static final java.lang.String CAPTIONS

The key for the Bundle which returns the available captions as ArrayList

See Also:

Constant Field Values

configurationBundle

protected final android.os.Bundle configurationBundle

context

protected final android.content.Context context

downloadManager

protected final DownloadManager downloadManager

video

protected final Video video

downloadEventListener

protected final MediaDownloadable.DownloadEventListener downloadEventListener

requestConfig

protected final RequestConfig requestConfig

estimatedSize

protected long estimatedSize

Constructor Detail

MediaDownloadable

public MediaDownloadable(@NonNull
                         android.content.Context context,
                         @NonNull
                         Video video,
                         @Nullable
                         MediaDownloadable.DownloadEventListener downloadEventListener,
                         @Nullable
                         RequestConfig requestConfig)

Method Detail

getMediaFormatTracksAvailable

public abstract void getMediaFormatTracksAvailable(@NonNull
                                                   MediaDownloadable.MediaFormatListener mediaFormatListener)

An asynchronous call to retrieve the MediaFormat tracks available for the current video. The result will be given through the MediaDownloadable.MediaFormatListener listener.

Note: Only the video type DeliveryType.DASH is currently supported.

Parameters:

mediaFormatListener - the media format listener

registerDownloadable

public static void registerDownloadable(@NonNull
                                        DeliveryType deliveryType,
                                        @NonNull
                                        java.lang.Class<? extends MediaDownloadable> downloadableClass)

Registers the downloadable class that must be used to handled download of the specified media delivery type.

Parameters:

deliveryType - the deliverty type

downloadableClass - the media downloadable class.

create

@Nullable
public static MediaDownloadable create(@NonNull
                                                 android.content.Context context,
                                                 @NonNull
                                                 Video video,
                                                 @Nullable
                                                 MediaDownloadable.DownloadEventListener downloadEventListener,
                                                 @Nullable
                                                 RequestConfig requestConfig)

Creates the best MediaDownloadable for the given video based on the supported delivery types.

Parameters:

context - the context of the application.

video - the video to be downloaded.

requestConfig - the request configuration object passed to the DownloadManager.

Returns:

null if the video is not flagged for offline playback or if no suitable delivery type was found in the video, otherwise reference to a MediaDownloadable that can be used download/manage the video.

create

@Nullable
public static MediaDownloadable create(@NonNull
                                                 android.content.Context context,
                                                 @NonNull
                                                 java.lang.String videoUrl,
                                                 @Nullable
                                                 MediaDownloadable.DownloadEventListener downloadEventListener,
                                                 @Nullable
                                                 RequestConfig requestConfig)

Creates the best MediaDownloadable for the given video url on the supported delivery types.

Parameters:

context - the context of the application.

videoUrl - the fully qualified URL of the video to be downloaded.

requestConfig - the request configuration object passed to the download manager.

Returns:

null if no suitable delivery type was found in the video, otherwise reference to a MediaDownloadable that can be used download/managed the video.

setVideoBitrate

public void setVideoBitrate(int videoBitrate)

Sets the video bitrate cap which will be used to determine what rendition will be downloaded. If there's no rendition lower than the video bitrate provided, the next higher will be picked.

Parameters:

videoBitrate - the video bitrate

getDownloadDirectory

@NonNull
public java.io.File getDownloadDirectory()

Gets the directory the will hold all the assets related to this media.

Returns:

the directory the will hold all the assets related to this media.

getEstimatedSize

public long getEstimatedSize()

Returns the estimated total size of the media, which includes all assets such video, audio and subtitles. Please note the method should be called after calling requestDownload()

The actual size of the media that will be used by the host device may vary based on the partition type and format of the storage.

Returns:

the approximate size of the media

estimatedSize

public void estimatedSize(MediaDownloadable.OnVideoSizeCallback callback)

Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.

The actual size of the media that will be used by the host device may vary based on the partition type and format of the storage. This method requires the Media Manifest to estimate the size, therefore it might download the manifest and store it to the directory provided in the RequestConfig() object in the constructor, if it has not been done already.

Parameters:

callback - the approximate size of the media.

getConfigurationBundle

public android.os.Bundle getConfigurationBundle()

setConfigurationBundle

public void setConfigurationBundle(android.os.Bundle bundle)

enqueueDownloadRequest

@NonNull
protected void enqueueDownloadRequest(@NonNull
                                               DownloadManager.Request... requests)

Enqueues a list of download requests to the download manager. The actual status of the download request will be published to the downloadEventListener. Please use getDownloadStatus() to query the download status.

Please note that this method must only be called once to enqueue all download requests.

Parameters:

requests - an array of download requests

Throws:

java.lang.IllegalStateException - If the video has been already queued for download.

onMediaDownloadRequested

protected void onMediaDownloadRequested()

This method will be called when the MediaDownloadable starts to process the download request.

getMediaProperties

@NonNull
protected abstract java.util.HashMap<java.lang.String,java.io.Serializable> getMediaProperties()

onMediaDownloadStarted

protected void onMediaDownloadStarted()

This method will be called when the MediaDownloadable starts to download the media.

onMediaDownloadPaused

protected void onMediaDownloadPaused(@NonNull
                                     DownloadStatus status)

Called when the media download has been paused.

onMediaDownloadProgress

protected void onMediaDownloadProgress(@NonNull
                                       DownloadStatus status)

Called when the media download progress has changed.

onMediaDownloadComplete

protected void onMediaDownloadComplete(@NonNull
                                       DownloadStatus status)

Called when the media download has completed successfully.

onMediaDownloadFailed

protected void onMediaDownloadFailed(@NonNull
                                     DownloadStatus status)

Called when the media download has failed.

onMediaDownloadCancelled

protected void onMediaDownloadCancelled()

Called when the media download has been removed before the download has completed.

onMediaDownloadDeleted

protected void onMediaDownloadDeleted()

Called when the media download has been removed after the download has completed.

requestDownload

public boolean requestDownload()

Requests the media to be downloaded asynchronously.

Returns:

true if the request was successfully placed in the download queue, otherwise false. Please note that a true value does not mean that media has been downloaded successfully. The actual status of the download request will be published to the downloadEventListener. Please use getDownloadStatus() to query the download status.

Throws:

java.lang.IllegalStateException - If the video has been already queued for download.

pauseDownload

public int pauseDownload()

Attempts to pause download of this media.

Returns:

the status of the media download.

resumeDownload

public int resumeDownload()

Attempts to resume download of this media.

Returns:

the status of the media download.

cancelDownload

public boolean cancelDownload()

Cancels download of the media if it has not been completed yet. If the media has been downloaded already, then calling this method will have no effect. Please call deleteDownload() method instead to delete the media.

Returns:

true if the media was found in the download queue and cancelled, otherwise false.

deleteDownload

public boolean deleteDownload()

Deletes the offline copy of the media. If the media has not been fully downloaded yet, then it will be removed from the download queue and any partially download assets belonging to the media will be deleted.

Returns:

true if the media was removed from the download queue and the storage, otherwise false.

getDownloadStatus

public DownloadStatus getDownloadStatus()

Checks the overall download status by inspecting the status of each request in the entire download set. Please note that this is a blocking call. Checking the status of large media with multiple assets may take time.

createDownloadRequest

@NonNull
protected DownloadManager.Request createDownloadRequest(@NonNull
                                                                 android.net.Uri requestUri,
                                                                 @NonNull
                                                                 android.net.Uri destinationUri)

Create a download request which can be enqueued with the DownloadManager.

Parameters:

requestUri - the request uri

destinationUri - the destination uri

Returns:

the download request

See Also:

enqueueDownloadRequest(DownloadManager.Request...)