Download to Go - Android

Download to Go (DTG) is an Android library that facilitates the download of video assets, withan emphasis on DASH and HLS.

The library is external to the Player SDK, and is added separately by the application.

Supported Video Formats

  • MPEG-DASH
    • Clear and Widevine
    • Currently only streams generated by Kaltura MediaPrep are supported
    • Track selection
  • HLS
    • Clear only
    • No track selection
  • Widevine Classic
    • Must be single-bitrate for proper playback
  • MP4

Project Setup

The simplest way to get up and running is by using JitPack’s Maven repository.

1) Add JitPack’s repository to the top-level build.gradle:

	allprojects {
		repositories {
			...
			maven { url "https://jitpack.io" }
		}
	}

2) Add the dependency:

	dependencies {
	    compile 'com.kaltura:playkit-dtg-android:v2.0.0'
	}

Replace v2.0.0 with the latest release.

JitPack provides more options and information.

Alternative Setup

As with any Open Source library, you can also clone the repository from GitHub and add it to your project:

1) Add a reference to the project in settings.gradle:

    include ':dtglib'
    project(':dtglib').projectDir = file('../../playkit-dtg-android/dtglib')

2) Add the local dependency in build.gradle:

    dependencies {
        compile project(":dtglib");
    }

Now when you build your own project, DTGLib gets built as well. However, this setup should only be used when you want to contribute to DTGLib development.

Usage

The following classes/interfaces are the public API of the library:

    com.kaltura.dtg.
        - ContentManager
        - DownloadItem
        - DownloadState
        - DownloadStateListener

Please see their Javadoc comments.

Following are some basic sequence diagrams.

Start and Stop the Service

PlantUML diagram

New Download Sequence

PlantUML diagram

Track Selection

Tracks are selected, by type, using a TrackSelector object. A TrackSelector is obtained by calling getTrackSelector() on a DownloadItem.
Given a TrackSelector, the application performs selection:

List<DownloadItem.Track> tracks = trackSelector.getAvailableTracks(AUDIO);
// Application logic for track filtering.
trackSelector.setSelectedTracks(AUDIO, filteredTracks)
// Repeat for other track types (VIDEO, TEXT)

trackSelector.apply();

Sequence Diagram

PlantUML diagram

Interactive Selection Before Download is Started

In this scenario, the metadata for an item was downloaded, the default tracks were selected, but the download wasn’t yet started.
The application calls item.getTrackSelector(), makes a selection and applies it. The selected tracks are downloaded as part of the normal download.

Interactive Selection After Download is Finished

The entire item has downloaded. The user now decides to download additional tracks - such as another audio language.
The application calls item.getTrackSelector(), makes a selection and applies it. Then, item.startDownload() is called again, to start downloading the extra tracks.

Preference-based Selection

The application may have a policy on track selection, for example:
- Always choose the highest quality video
- Always prefer audio in the user’s UI language

The ContentManager calls the application’s listener method onTracksAvailable() with an open TrackSelector. The application selects tracks to download and when onTracksAvailable() returns, the selection is applied.

If no selection was made, some defaults are applied instead. However, it’s recommended that the application adopts its own defaults.

If the application can select tracks without user interaction, it is best to do so inside the onTracksAvailable() handler. It avoids writing data to the database that will be discarded immediately after.

Track Selection Samples

Select the video track with the lowest bitrate:

    List<DownloadItem.Track> videoTracks = trackSelector.getAvailableTracks(DownloadItem.TrackType.VIDEO);
    DownloadItem.Track minVideo = Collections.min(videoTracks, DownloadItem.Track.bitrateComparator);
    trackSelector.setSelectedTracks(DownloadItem.TrackType.VIDEO, Collections.singletonList(minVideo));

Select all available tracks:

    void selectAllAvailableTracksByType(DownloadItem.TrackSelector trackSelector, DownloadItem.TrackType trackType) {
        List<DownloadItem.Track> availableTracks = trackSelector.getAvailableTracks(trackType);
        trackSelector.setSelectedTracks(trackType, availableTracks);
    }

Then, from onAvailableTracks():

    selectAllAvailableTracksByType(trackSelector, DownloadItem.TrackType.AUDIO);
    selectAllAvailableTracksByType(trackSelector, DownloadItem.TrackType.TEXT);

Default Selection

  • Video: highest bitrate track
  • Audio: highest bitrate version of the first language
  • Text: first track.