Skip to the content.

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



Add this to your podfile:

pod 'DownloadToGo'

Main API Classes

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

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


In AppDelegate:

class AppDelegate: UIResponder, UIApplicationDelegate {

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

        // 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)


Simple Flow

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:

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:


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

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.