Docs | iOS

Download-to-Go for iOS

Download to Go (DTG) is an iOS library that facilitates the download of HLS video assets.

On this page:

Supported Features
Installation
Overview

Supported Features

Downloading HLS assets
Background downloading
Resuming interrupted/paused downloads
Track (audio, subtitles) selection

Installation

CocoaPods

Add this to your podfile:

pod 'DownloadToGo'

Main API Classes

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

ContentManager - Use this class to interact with the library.
DTGContentManager - This is the main api you will use to interact with the library.
ContentManagerDelegate - Delegate calls available to observe.
DTGItem - Represent a single download item.
DTGItemState - The state of a download item.

See the sample app in DTG repo for a full example.

Setup

In AppDelegate:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // setup the content manager - THIS IS A MUST!
        ContentManager.shared.setup()

        // Optional - to automatically resume interrupted or in progress downloads
        ContentManager.shared.startItems(inStates: ...)

        return true
    }

    ...

    func application(_ application: UIApplication, handleEventsForBackgroundURLSession identifier: String, completionHandler: @escaping () -> Void) {
        // Make sure background download works correctly
        ContentManager.shared.handleEventsForBackgroundURLSession(identifier: identifier, completionHandler: completionHandler)
    }
}

Overview

Simple Flow

Failed is a temporary state, the delegate will notify and item has failed and content manager will remove this item. In addition, keep in mind that when receiving failed state an error will also be provided in the delegate to indicate the reason.
There is also Removed state which is not displayed here. Removed is a temporary state indicated an item was removed (can be considered as an event). You can remove an item from all states.

Download Sequence

After download, calling ContentManager.itemPlaybackUrl(id) returns a URL valid for local playback. This URL can be sent directly to players.

Track Selection

HLS assets are built from a few tracks or streams:

Variable quality video tracks
Multi-language audio tracks
Multi-language subtitle (text) tracks

When the app prepares an asset for download, it can select which tracks to include. This is done using the DTGSelectionOptions class.

Before calling ContentManager.loadItemMetadata(...), create an object of this class and set the required fields.

See the inline documentation comments for all the details – following are examples for common use cases:

Video

DTG will try to download a video track that matches the selection.

Select by Resolution - recommended

Modern HLS assets include resolution details in the playlist. Selecting video by resolution (and leaving bitrate selection empty) is preferred because it lets DTG make the best selection based on codec availability.

options.videoWidth = 1200
options.videoHeight = 720

It’s enough to set of videoWidth and videoHeight.

Select by Codec and Bitrate - advanced

options.videoBitrates = [.avc1: 900000, .hevc: 500000]

Since every codec has its own scale, it’s important to include all codecs that might appear in the asset. When in doubt, it’s typical for HEVC tracks to be smaller than AVC1 (h.264) tracks by 30-40% for the same quality.

Restrict or change priority of Video Codecs

Normally DTG will prefer HEVC (if available and supported). If the app wants to avoid HEVC or prefer AVC1 it can set the following:

options.videoCodecs = [.avc1]

Audio and Text

Select all Audio and Text tracks

options.allAudioLanguages = true
options.allTextLanguages = true

Select Audio and Text tracks by Language

options.audioLanguages = ["fr", "de"]
options.textLanguages = ["en"]

The languages are specified in ISO-639-1 (2 letters) or ISO-639-2 (3 letters) codes.

Restrict Audio Codec selection

The following audio codecs are supported by DTG and the player, but not all devices support them. If the below property is not set, DTG will try to download the best codec that can be played by the device.

// Allow only mp4a
options.audioCodecs = [.mp4a]

// Allow mp4a and ac3 (Dolby)
options.audioCodecs = [.mp4a, .ac3]

Simple Playback using PlayKit

When the content is not DRM-protected, the above download flow and the below playback flow are enough.

For DRM-protected content see further.

DRM-protected Content (PlayKit)

The support for DRM-protected (FairPlay) content is not a part of DTG but the player. It’s the player’s responsibility to obtain and save a license that will allow offline playback.

See PlayKit Offline DRM guide for instructions.