{"id":20331108,"url":"https://github.com/comcast/mamba","last_synced_at":"2025-04-12T20:42:05.474Z","repository":{"id":44623824,"uuid":"88876515","full_name":"Comcast/mamba","owner":"Comcast","description":"Mamba is a Swift iOS, tvOS and macOS framework to parse, validate and write HTTP Live Streaming (HLS) data.","archived":false,"fork":false,"pushed_at":"2024-12-04T03:52:17.000Z","size":953,"stargazers_count":186,"open_issues_count":8,"forks_count":39,"subscribers_count":17,"default_branch":"develop","last_synced_at":"2025-04-04T00:07:51.212Z","etag":null,"topics":["avfoundation","hls","ios","macos","swift","tvos"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Comcast.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-20T14:41:38.000Z","updated_at":"2025-03-20T01:17:04.000Z","dependencies_parsed_at":"2024-06-21T14:23:42.965Z","dependency_job_id":"9338cefe-e90d-4ead-a431-16bdb5e3067f","html_url":"https://github.com/Comcast/mamba","commit_stats":{"total_commits":173,"total_committers":16,"mean_commits":10.8125,"dds":0.5202312138728324,"last_synced_commit":"263f3c786d8d2ca919e9493ff622f8212fb1954c"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fmamba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fmamba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fmamba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Comcast%2Fmamba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Comcast","download_url":"https://codeload.github.com/Comcast/mamba/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631668,"owners_count":21136554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avfoundation","hls","ios","macos","swift","tvos"],"created_at":"2024-11-14T20:18:46.792Z","updated_at":"2025-04-12T20:42:05.453Z","avatar_url":"https://github.com/Comcast.png","language":"Swift","readme":"[![Build Status](https://secure.travis-ci.org/Comcast/mamba.svg)](https://travis-ci.org/Comcast/mamba) \n[![Code Coverage from codecov](https://codecov.io/gh/Comcast/mamba/branch/develop/graph/badge.svg)](https://codecov.io/gh/Comcast/mamba)\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Cocoapod status](https://img.shields.io/cocoapods/v/mamba.svg)](https://cocoapods.org/pods/mamba)\n[![GitHub release](https://img.shields.io/github/release/Comcast/mamba.svg)](https://github.com/Comcast/mamba/releases)\n[![License](https://img.shields.io/cocoapods/l/mamba.svg)](https://raw.githubusercontent.com/Comcast/mamba/master/LICENSE.md)\n[![Platform](https://img.shields.io/cocoapods/p/mamba.svg?style=flat)]()\n\nMamba\n===\n\nMamba is a Swift iOS, tvOS and macOS framework to parse, validate and write [HTTP Live Streaming (HLS)](https://tools.ietf.org/html/draft-pantos-http-live-streaming-23) data.\n\nThis 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](https://stackoverflow.com/jobs/companies/comcast-viper) Player Platform team.\n\n_Mamba Project Goals:_\n\n* **Simple-to-use parsing, editing and writing** of HLS playlists.\n\n* **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.\n\n## Requires\n\n* XCode 10.2+\n* Swift 4+ (written in Swift 5)\n* iOS 9+ _or_ tvOS 9+ _or_ macOS 10.13+\n\n## Usage\n\n### _Parsing a HLS Playlist_\n\nCreate an `PlaylistParser`. \n\n```swift\nlet parser = PlaylistParser()\n```\n\nParse your HLS playlist using the parser. Here's the asynchronous version:\n\n```swift\nlet myPlaylistData: Data = ... // source of HLS data\nlet myPlaylistURL: URL = ... // the URL of this playlist resource\n\nparser.parse(playlistData: myPlaylistData,\n             url: myPlaylistURL,\n             callback: { result in\n                switch result {\n                case .parsedVariant(let variant):\n                    // do something with the parsed VariantPlaylist \n                    myVariantPlaylistHandler(variantPlaylist: variant)\n                    break\n                case .parsedMaster(let master):\n                    // do something with the parsed MasterPlaylist \n                    myMasterPlaylistHandler(masterPlaylist: master)\n                    break\n                case .parseError(let error):\n                    // handle the ParserError\n                    myErrorHandler(error: error)\n                    break\n                }\n})\n```\n\nAnd here's the synchronous version:\n\n```swift\n// note: could take several milliseconds for large transcripts!\nlet result = parser.parse(playlistData: myPlaylistData,\n                          url: myPlaylistURL)\nswitch result {\ncase .parsedVariant(let variant):\n    // do something with the parsed VariantPlaylist object\n    myVariantPlaylistHandler(variantPlaylist: variant)\n    break\ncase .parsedMaster(let master):\n    // do something with the parsed MasterPlaylist object\n    myMasterPlaylistHandler(masterPlaylist: master)\n    break\ncase .parseError(let error):\n    // handle the ParserError\n    myErrorHandler(error: error)\n    break\n}\n```\n\nYou now have an HLS playlist object.\n\n### _MasterPlaylist and VariantPlaylist_\n\nThese structs are in-memory representations of a HLS playlist.\n\nThey include:\n\n* The `URL` of the playlist.\n* 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.\n* Utility functions to tell if a variant playlist is a Live, VOD or Event style playlist.\n* Helpful functionality around the structure of a playlist. This structure is kept up to date behind the scenes as the playlist is edited.\n *  `VariantPlaylist`: includes calculated references to the \"header\", \"footer\" and all the video segments and the metadata around them. \n *  `MasterPlaylist`: includes calculated references to the variant streams and their URL's.\n\n`MasterPlaylist` and `VariantPlaylist` objects are highly editable.\n\n### _Validating a Playlist_\n\nValidate your playlist using the `PlaylistValidator`.\n\n```swift\nlet variantPlaylist: VariantPlaylistInterface = myVariantPlaylistFactoryFunction()\nlet masterPlaylist: MasterPlaylistInterface = myMasterPlaylistFactoryFunction()\n\nlet variantissues = PlaylistValidator.validate(variantPlaylist: variantPlaylist)\nlet masterissues = PlaylistValidator.validate(masterPlaylist: masterPlaylist)\n```\n\nIt returns an array of `PlaylistValidationIssue`s found with the playlist. They each have a description and a severity associated with them.\n\n*We currently implement only a subset of the HLS validation rules as described in the [HLS specification](https://tools.ietf.org/html/draft-pantos-http-live-streaming-23). Improving our HLS validation coverage would be a most welcome pull request!*\n\n### _Writing a HLS Playlist_\n\nCreate a `PlaylistWriter`.\n\n```swift\nlet writer = PlaylistWriter()\n```\n\nWrite your HLS playlist to a stream.\n\n```swift\nlet stream: OutputStream = ... // stream to receive the HLS Playlist\n\ndo {\n   try writer.write(playlist: variantPlaylist, toStream: stream)\n   try writer.write(playlist: masterPlaylist, toStream: stream)\n}\ncatch {\n    // there was an error severe enough for us to stop writing the data\n}\n```\n\nThere is also a utility function in the playlist to write out the playlist to a `Data` object.\n\n```\ndo {\n    let variantData = try variantPlaylist.write()\n    let masterData = try masterPlaylist.write()\n    \n    // do something with the resulting data\n    myDataHandler(data: variantData)\n    myDataHandler(data: masterData)\n}\ncatch {\n    // there was an error severe enough for us to stop writing the data\n}\n```\n\n### _Using Custom Tags_\n\nNatively, Mamba only understands HLS tags as defined in the [Pantos IETF specification](https://tools.ietf.org/html/draft-pantos-http-live-streaming-23). If you'd like to add support for a custom set of tags, you'll need to create them as a object implementing `PlaylistTagDescriptor`. Please look at `PantosTag` or one of the examples in the unit tests for sample code.\n\nIf you have any custom `PlaylistTagDescriptor` collections you'd like to parse alongside the standard Pantos tags, pass them in through this `PlaylistParser` initializer:\n\n```swift\nenum MyCustomTagSet: String {\n    // define your custom tags here\n    case EXT_MY_CUSTOM_TAG = \"EXT-MY-CUSTOM-TAG\"\n}\n\nextension MyCustomTagSet: PlaylistTagDescriptor {\n    ... // conform to HLSTagDescriptor here\n}\n\nlet customParser = PlaylistParser(tagTypes: [MyCustomTagSet.self])\n```\n\nIf there is specfic data inside your custom tag that you'd like to access, e.g.\n\n```\n#EXT-MY-CUSTOM-TAG:CUSTOMDATA1=\"Data1\",CUSTOMDATA2=\"Data1\"\n```\n\nyou can define that data in an enum that conforms to `PlaylistTagValueIdentifier`:\n\n```swift\nenum MyCustomValueIdentifiers: String {\n    // define your custom value identifiers here\n    case CUSTOMDATA1 = \"CUSTOMDATA1\"\n    case CUSTOMDATA2 = \"CUSTOMDATA2\"\n}\n\nextension MyCustomValueIdentifiers: PlaylistTagValueIdentifier {\n    ... // conform to PlaylistTagValueIdentifier here\n}\n```\n\nYou can now look through `PlaylistTag` objects for your custom tag values just as if it were a valuetype defined in the HLS specification.\n\n### _Important Note About Memory Safety_\n\nIn order to achieve our performance goals, the internal C parser for HLS had to minimize the amount of heap memory allocated.\n\nThis meant that, for each `PlaylistTag` object that is included in a `MasterPlaylist/VariantPlaylist`, instead of using a swift `String` to represent data, we use a `MambaStringRef`, which is a object that is a reference into the memory of the original data used to parse the playlist. This greatly speeds parsing, but comes at a cost: **these `PlaylistTag` objects are unsafe to use beyond the lifetime of their parent `MasterPlaylist/VariantPlaylist`**. \n\nIn general, this is no problem. Normal usage of a `MasterPlaylist/VariantPlaylist` would be (1) Parse the playlist, (2) Edit by manipulating `PlaylistTag`s (3) Write the playlist. \n\nIf you do, for some reason, need to access `PlaylistTag` data beyond the lifetime of the parent `MasterPlaylist/VariantPlaylist` object, you'll need to make a copy of all `MambaStringRef` data of interest into a regular swift `String`. There's a string conversion function in `MambaStringRef` to accomplish this.\n\n--\n\n_Note: We have legacy branches for mamba 1.x at [our main 1.x branch](https://github.com/Comcast/mamba/tree/main_1.x) and [our develop 1.x branch](https://github.com/Comcast/mamba/tree/develop_1.x). 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_\n\n--\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomcast%2Fmamba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcomcast%2Fmamba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcomcast%2Fmamba/lists"}