Mamba

Mamba is a Swift iOS, tvOS and macOS framework to parse, validate and write HTTP Live Streaming (HLS) data.

This framework is used in Comcast applications to parse, validate, edit and write HLS playlists to deliver video to millions of customers. It was written by the Comcast VIPER Player Platform team.

Mamba Project Goals:

• Simple-to-use parsing, editing and writing of HLS playlists.

• Maximum performance. We required our parsing library to parse very large HLS playlists (12 hour Video-On-Demand) on low end phones in a few milliseconds. A internal core C library is used for very fast parsing of large playlists.

Requires

• XCode 10.2+
• Swift 4+ (written in Swift 5)
• iOS 9+ or tvOS 9+ or macOS 10.13+

Usage

Parsing a HLS Playlist

Create an

PlaylistParser

let parser = PlaylistParser()

Parse your HLS playlist using the parser. Here's the asynchronous version:

let myPlaylistData: Data = ... // source of HLS data
let myPlaylistURL: URL = ... // the URL of this playlist resource

parser.parse(playlistData: myPlaylistData,
             url: myPlaylistURL,
             callback: { result in
                switch result {
                case .parsedVariant(let variant):
                    // do something with the parsed VariantPlaylist 
                    myVariantPlaylistHandler(variantPlaylist: variant)
                    break
                case .parsedMaster(let master):
                    // do something with the parsed MasterPlaylist 
                    myMasterPlaylistHandler(masterPlaylist: master)
                    break
                case .parseError(let error):
                    // handle the ParserError
                    myErrorHandler(error: error)
                    break
                }
})

And here's the synchronous version:

// note: could take several milliseconds for large transcripts!
let result = parser.parse(playlistData: myPlaylistData,
                          url: myPlaylistURL)
switch result {
case .parsedVariant(let variant):
    // do something with the parsed VariantPlaylist object
    myVariantPlaylistHandler(variantPlaylist: variant)
    break
case .parsedMaster(let master):
    // do something with the parsed MasterPlaylist object
    myMasterPlaylistHandler(masterPlaylist: master)
    break
case .parseError(let error):
    // handle the ParserError
    myErrorHandler(error: error)
    break
}

You now have an HLS playlist object.

MasterPlaylist and VariantPlaylist

These structs are in-memory representations of a HLS playlist.

They include:

• The

  URL

  of the playlist.
• An array of

  PlaylistTag

  s that represent each line in the HLS playlist. This array is editable, so you can make edits to the playlist.
• Utility functions to tell if a variant playlist is a Live, VOD or Event style playlist.
• Helpful functionality around the structure of a playlist. This structure is kept up to date behind the scenes as the playlist is edited.

  • VariantPlaylist

    : includes calculated references to the "header", "footer" and all the video segments and the metadata around them.

  • MasterPlaylist

    : includes calculated references to the variant streams and their URL's.

MasterPlaylist

VariantPlaylist

Validating a Playlist

Validate your playlist using the

PlaylistValidator

let variantPlaylist: VariantPlaylistInterface = myVariantPlaylistFactoryFunction()
let masterPlaylist: MasterPlaylistInterface = myMasterPlaylistFactoryFunction()

let variantissues = PlaylistValidator.validate(variantPlaylist: variantPlaylist)
let masterissues = PlaylistValidator.validate(masterPlaylist: masterPlaylist)

It returns an array of

PlaylistValidationIssue

We currently implement only a subset of the HLS validation rules as described in the HLS specification. Improving our HLS validation coverage would be a most welcome pull request!

Writing a HLS Playlist

Create a

PlaylistWriter

let writer = PlaylistWriter()

Write your HLS playlist to a stream.

let stream: OutputStream = ... // stream to receive the HLS Playlist

do {
   try writer.write(playlist: variantPlaylist, toStream: stream)
   try writer.write(playlist: masterPlaylist, toStream: stream)
}
catch {
    // there was an error severe enough for us to stop writing the data
}

There is also a utility function in the playlist to write out the playlist to a

Data

do {
    let variantData = try variantPlaylist.write()
    let masterData = try masterPlaylist.write()

// do something with the resulting data
myDataHandler(data: variantData)
myDataHandler(data: masterData)
}
catch {
    // there was an error severe enough for us to stop writing the data
}

Using Custom Tags

Natively, Mamba only understands HLS tags as defined in the Pantos IETF specification. If you'd like to add support for a custom set of tags, you'll need to create them as a object implementing

PlaylistTagDescriptor

PantosTag

If you have any custom

PlaylistTagDescriptor

PlaylistParser

enum MyCustomTagSet: String {
    // define your custom tags here
    case EXT_MY_CUSTOM_TAG = "EXT-MY-CUSTOM-TAG"
}

extension MyCustomTagSet: PlaylistTagDescriptor {
    ... // conform to HLSTagDescriptor here
}
let customParser = PlaylistParser(tagTypes: [MyCustomTagSet.self])

If there is specfic data inside your custom tag that you'd like to access, e.g.

#EXT-MY-CUSTOM-TAG:CUSTOMDATA1="Data1",CUSTOMDATA2="Data1"

you can define that data in an enum that conforms to

PlaylistTagValueIdentifier

enum MyCustomValueIdentifiers: String {
    // define your custom value identifiers here
    case CUSTOMDATA1 = "CUSTOMDATA1"
    case CUSTOMDATA2 = "CUSTOMDATA2"
}

extension MyCustomValueIdentifiers: PlaylistTagValueIdentifier {
    ... // conform to PlaylistTagValueIdentifier here
}

You can now look through

PlaylistTag

Important Note About Memory Safety

In order to achieve our performance goals, the internal C parser for HLS had to minimize the amount of heap memory allocated.

This meant that, for each

PlaylistTag

MasterPlaylist/VariantPlaylist

String

MambaStringRef

PlaylistTag

MasterPlaylist/VariantPlaylist

In general, this is no problem. Normal usage of a

MasterPlaylist/VariantPlaylist

PlaylistTag

If you do, for some reason, need to access

PlaylistTag

MasterPlaylist/VariantPlaylist

MambaStringRef

String

MambaStringRef

--

Note: We have legacy branches for mamba 1.x at our main 1.x branch and our develop 1.x branch. We are maintaining that branch, but may stop updating in the near future. Users are welcome to submit pull requests against the 1.x branches or potentially fork if they do not want to move to 2.0

--