omaralbeik / m3ukit

Modern framework for parsing m3u files

M3UKit

Modern framework for parsing m3u files.

---

Features

• Parse playlists from a String, local file, or any URL.
• Capable of parsing large playlists with hundreds of thousands of media items.
• Sync/Async parsing.
• Season/Episode number extraction for TV show media items.
• Media kind extraction from URL path.

Usage

1. Create a parser

let parser = PlaylistParser()

2. Parse a playlist

The playlist parser can parse a playlist from any source that conforms to the protocol PlaylistSource, by default: String, and URL.

let url = URL(string: "https://domain.com/link/to/m3u/file")
let playlist = try parser.parse(url)

or

let url = Bundle.main.url(forResource: "playlist", withExtension: "m3u")!
let playlist = try parser.parse(url)

or

let raw = """
#EXTM3U
#EXTINF:-1 tvg-id="DenHaagTV.nl",Den Haag TV (1080p)
http://wowza5.video-streams.nl:1935/denhaag/denhaag/playlist.m3u8
"""
let playlist = try parser.parse(raw)

M3UKit also supports asynchronous parsing with a completion handler or with the new async/await API

parser.parse(url) { result in
    switch result {
    case .success(let playlist):
        // consume playlist
    case .failure(let error):
        // handle error
    }
}

or

let playlist = try await parser.parse(url)

---

Schema

M3U exposes one model; Playlist, with the following schema:

Playlist
└── medias

Media
├── duration
├── attributes
├── kind
├── name
└── url

Attributes
├── id (tvg-id)
├── name (tvg-name)
├── country (tvg-country)
├── language (tvg-language)
├── logo (tvg-logo)
├── channelNumber (tvg-chno)
├── shift (tvg-shift)
├── groupTitle (group-title)
├── seasonNumber
└── episodeNumber

Kind
├── movie
├── series
├── live
└── unknown

---

Installation

Swift Package Manager

The Swift Package Manager is a tool for managing the distribution of Swift code.

1. Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/omaralbeik/M3UKit.git", from: "0.8.1")
]

2. Build your project:

$ swift build

CocoaPods

To integrate M3UKit into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'M3UKit', :git => 'https://github.com/omaralbeik/M3UKit.git', :tag => '0.8.1'

Carthage

To integrate M3UKit into your Xcode project using Carthage, specify it in your Cartfile:

github "omaralbeik/M3UKit" ~> 0.8.1

Manually

Add the Sources folder to your Xcode project.

---

Thanks

Special thanks to Bashar Ghadanfar for helping with the regex patterns used for parsing m3u files 👏

---

License

M3UKit is released under the MIT license. See LICENSE for more information.

m3ukit's Issues

Special characters in M3U file can fail parsing

http://bit.ly/022qseed breaks the parser, It contains a special character at the beginning which makes the code in file "PlaylistParser" to fail with error "ParsingError.invalidSource".

Would be possible to treat this case in the parser? Something like

guard rawString.<remove-illegal-chars>.starts(with: filePrefix) else {
       throw ParsingError.invalidSource
 }

[Feature Request] Add total counters

Could we add a few options where we could get total counters. What I mean is can we get a total count of how many Categories are in each playlist, totals for each kind (movie, series, live, etc) there are, and so on.

[Feature request] Add parsing error types/descriptions

It would be nice to have how to know what cause the parsing to fail, so I can have a way to inform the user what is wrong

[Bug] Wrong URL assigned to media if playlist file contains other markers

When parsing a M3U file if it contains any extra markers such as "#EXTGRP" the last URL used is then wrong

For example a file like this

#EXTM3U
#EXTINF:-1 tvg-id="TV1" tvg-name="TV1" tvg-logo="" group-title="TV Group 1",TV 1
#EXTGRP:TV GROUP 1
https://URL1.com
#EXTINF:-1 tvg-id="TV2" tvg-name="TV2" tvg-logo="" group-title="TV Group 2",TV 2
#EXTGRP:TV GROUP 2
https://URL2.com

You end up with the following metadataLine and url:

- "#EXTINF:-1 tvg-id=\"TV1\" tvg-name=\"TV1\" tvg-logo=\"\" group-title=\"TV Group 1\",TV 1"
▿ #EXTGRP:TV%20GROUP%201
  - _url: #EXTGRP:TV%20GROUP%201 #0
    - super: NSObject

- "#EXTINF:-1 tvg-id=\"TV2\" tvg-name=\"TV2\" tvg-logo=\"\" group-title=\"TV Group 2\",TV 2"
▿ https://URL1.com
  - _url: https://URL1.com #0
    - super: NSObject

M3UKit cannot be installed by CocoaPods