A pure-Swift implementation of the Common Media Application Format (ISO/IEC 23000-19) plus the underlying ISO Base Media File Format hierarchy. Read, write, validate, and surface typed metadata for fragmented MP4 / CMAF media. Cross-platform from day one. Zero C vendoring. Swift 6.2 strict concurrency. 3,575 tests across macOS and Linux. The container and codec foundation of the Atelier Socle streaming ecosystem.
0.1.2 — refinement patch over the v0.1.1 surface. CLI refactored to the idiomatic library + thin executable pattern (unblocks xcodebuild test on Apple platforms); swift-crypto declared-but-unwired dependency removed; industry-grade uniform DocC coverage achieved with 94 new test-traceable code samples (113 swift blocks across 25 articles). Purely additive on the public typed surface — zero breaking change. APIs may evolve before 1.0 based on community feedback. The library ships two products (CMAFKit + opt-in CMAFKitDRM) and a companion executable (cmafkit-cli).
A refinement patch that closes the architectural cohesion gap with
the peer ecosystem (swift-hls-kit, swift-srt-kit, swift-rtmp-kit,
swift-icecast-kit) and brings the DocC catalog to industry-grade
uniform coverage. Every new code sample traces to an existing test.
| Refinement | What changed | Why |
|---|---|---|
| CLI architecture | New CMAFKitCommands library target + thin CMAFKitCLI executable wrapper |
Mirrors peer-lib pattern; unblocks xcodebuild test -scheme swift-cmaf-kit-Package -destination 'platform=macOS' on Apple platforms |
| DocC enrichment | +94 swift code samples across 22 articles (14 → 113 blocks ecosystem-wide) | Industry-grade uniform coverage; every sample traces to a specific @Test (zero invention) |
| Dependency cleanup | swift-crypto removed (declared but unwired) |
Phase A audit verified zero import Crypto call sites; 3 SPM dependencies → 2 |
| Catalog migration | CMAFKitCLI.docc/ → CMAFKitCommands.docc/ |
The testable library owns the catalog (peer-lib convention) |
| ProtoBuf docs | ProtocolBufferReader / ProtocolBufferWriter doc comments expanded |
Legitimises public visibility for consumers implementing custom DRM providers |
- +94 swift code samples across 22 documentation articles
- Zero public symbol removed since v0.1.1
- Zero forbidden patterns introduced
- 3 SPM dependencies → 2 (
swift-cryptoremoved;swift-argument-parser+swift-docc-pluginremaining) - Coverage ≥ 92 % global maintained (93.53 %)
xcodebuild test -scheme swift-cmaf-kit-Package -destination 'platform=macOS'→TEST SUCCEEDED(the headline behavioural validation of 0.1.2)xcodebuild buildmatrix 5 Apple platforms →BUILD SUCCEEDED × 5- Linux Docker (
swift:6.2-jammy, Swift 6.2.4) →Test run with 3 574 tests passed - DocC × 3 (CMAFKit + CMAFKitDRM + CMAFKitCommands) → zero warnings
See CHANGELOG.md [0.1.2] for the complete shipped surface.
- Swift 6.2 toolchain (strict concurrency)
- macOS 14 / iOS 17 / iPadOS 17 / tvOS 17 / watchOS 10 / visionOS 1 / Linux (Swift 6.2)
- Xcode 26 (when building via xcodebuild)
- Zero external dependencies in
CMAFKit/CMAFKitDRM. The CLI depends only on Apple'sswift-argument-parser.
Swift Package Manager:
// Package.swift
dependencies: [
.package(url: "https://github.com/atelier-socle/swift-cmaf-kit.git", from: "0.1.0"),
],
targets: [
.target(
name: "MyApp",
dependencies: [
.product(name: "CMAFKit", package: "swift-cmaf-kit"),
// optional — typed DRM init-data decoding
.product(name: "CMAFKitDRM", package: "swift-cmaf-kit"),
]
)
]import CMAFKit
import Foundation
let avc = AVCDecoderConfigurationRecord(
profileIndication: .baseline,
profileCompatibility: AVCProfileCompatibility(rawValue: 0xE0),
levelIndication: .level3,
lengthSize: .fourBytes,
sequenceParameterSets: [AVCParameterSet(rbspBytes: Data([0x67, 0x42, 0xC0, 0x1E]))],
pictureParameterSets: [AVCParameterSet(rbspBytes: Data([0x68, 0xCE, 0x3C, 0x80]))]
)
let video = CMAFTrackConfiguration(
trackID: 1, kind: .video, profile: .basic, timescale: 90_000,
language: "und",
videoFields: CMAFTrackConfiguration.VideoFields(
width: 1920, height: 1080,
codec: .avc1, codecConfiguration: .avc(avc),
frameRate: .init(numerator: 30, denominator: 1)
)
)
// Write
let initBytes = try CMAFInitSegmentWriter(configurations: [video]).emit()
// Read back
let reader = try await CMAFInitSegmentReader(bytes: initBytes)
print(reader.tracks().count, "track(s)")- ISOBMFF parsing — every box from ISO/IEC 14496-12 needed for streaming, with typed surfaces and byte-perfect unknown-box round-trip preservation
- Init segments —
CMAFInitSegmentReader(stateless value type) reconstructs the typedCMAFTrackConfigurationlist from aftyp+moovbyte stream; handler-dispatched video / audio / subtitle / metadata resolution per ISO/IEC 14496-12 §8 - Media segments —
CMAFMediaSegmentReader(actor) ingests segment-by-segment, yields typedCMAFParsedSamplevalues with per-sample bytes, duration, composition-time offset, sync flag, decode time, and (when encrypted) IV + subsample partitions - Track analysis — codec, profile, encryption scheme, language, video dimensions, audio sample rate / channel count, HDR / Dolby Vision metadata, closed-caption channels, edit list
- Box registry — pluggable
BoxRegistryfor custom box parsers; default registry covers 100+ ISOBMFF / CMAF boxes
- Init segments —
CMAFInitSegmentWritercomposes theftyp+moovtree from typed track configurations; brand composition selectsiso6+ the CMAF major brand (cmfc/cmf2/cmff/cmfl/cmfs/cmfd/cmfh) + codec-specific compatible brands - Media segments —
CMAFMediaSegmentWriter(actor) emitsmoof+mdatfragments with monotonictfdtand sample-accuratetrunoffsets; supports multi-fragment segments and LL-HLS partial chunks viaCMAFPartialChunkBoundary - Fragment boundaries —
CMAFFragmentBoundarypredicates:sampleCount(N)/durationSeconds(N)/onSyncSample/custom(predicate); SAP rule enforced at runtime (every video fragment opens on a sync sample) - Sample entries — automatic dispatch to the right sample-entry composer per codec (10 video, 8 audio, 3 subtitle, 4 metadata codecs)
- Encrypted output —
encv/encasample-entry rewrite,sinf/schm/schi/tencemission,sencboxes with per-sample IVs + optional subsample partitions - Segment indices —
sidx/prft/emsgemission for DASH-aligned content; LL-HLS partial chunks per IETF RFC 8216bis-15 §B
- CMAF —
CMAFConformanceValidatorenforces 10+ rules from ISO/IEC 23000-19 §7 (SAP at fragment head, uniform track ID per traf, declared tracks, encryption symmetry,iso6+cmfcbrand presence,mfhdsequence monotonicity, per-tracktfdtmonotonicity) - DASH —
DASHConformanceValidatorenforces the ISO BMFF profile (ISO/IEC 23009-1 §6.3) and DASH-IF IOP recommendations (sidxmandatory,prftNTP signalling,emsgtimescale alignment, segment-duration consistency, timescale ≥ 1000) - Low-Latency HLS —
LLHLSConformanceValidatorenforces IETF RFC 8216bis-15 §B partial-chunk rules (first sample sync ↔ INDEPENDENT, uniquemfhd.sequence_number, PART-TARGET enforcement, first-chunk INDEPENDENT flag, per-fragmenttfdtmonotonicity) - Structural integrity — every typed parser throws a precise
ISOBoxError/CMAFReaderErroron malformed input, never silently degrades - Reports —
CMAFValidationReportaggregates issues across validators; each issue carries severity (error / warning / info), rule reference (spec section number), description, optional track ID, optional segment index
- All four schemes per ISO/IEC 23001-7 —
cenc(AES-CTR full-sample),cbc1(AES-CBC full-sample),cens(AES-CTR pattern),cbcs(AES-CBC pattern; the HLS FairPlay mode) - Pattern encryption —
crypt_byte_block/skip_byte_blockparameters forcensandcbcs - Per-sample metadata — typed
CMAFSampleInput.EncryptionMetadatacarries the IV + optional subsample partitions; the reader recovers them byte-perfectly - PSSH passthrough —
ProtectionSystemSpecificHeaderBoxcarries any DRM system's init data verbatim; the opt-inCMAFKitDRMtarget lifts it to typed shapes - No key material in the library — CMAFKit packages and parses encrypted content; key acquisition and decryption live in the operator's downstream pipeline
Typed pssh.data decoders for 9 publicly-registered DRM systems:
| System | Wire format | Status |
|---|---|---|
| Widevine | WidevineCencHeader Protocol Buffer (10 fields) |
full typing |
| PlayReady | PRO + WRMHEADER XML v4.0 / 4.1 / 4.2 / 4.3 | full typing |
| FairPlay Streaming | Apple Modular DRM binary | full typing |
| ClearKey | W3C EME §9 JSON + RFC 4648 §5 base64url | full typing |
| Marlin | Marlin Broadband BBA URN + inner payload | full typing |
| ChinaDRM | KID array per GY/T 277.2 + operator inner | full typing |
| Nagra Connect | proprietary, NDA-only | opaque wrapper (closed-spec) |
| Verimatrix Multi-DRM | proprietary | opaque wrapper (closed-spec) |
| Adobe Primetime | discontinued 2020 | opaque wrapper (deprecated service) |
Round-trip is byte-perfect for the six fully-typed providers (canonical-order encoding for Widevine + PlayReady; deterministic JSON for ClearKey) and for the three opaque wrappers (bytes preserved verbatim). Honest treatment of closed-spec providers is documented in each provider's file header — no fake-typing.
- In-band SEI extraction — CEA-608 byte pairs and CEA-708 DTVCC packets carried inside AVC / HEVC SEI
user_data_registered_itu_t_t35messages with the ATSC A/72 signature;ClosedCaptionExtractoractor surfaces typedClosedCaptionData - DTVCC reassembly — cross-NAL DTVCC packet reassembly per CTA-708-E §6 + SCTE-128 §8
- Out-of-band caption tracks — typed
c608andc708sample entries per ISO/IEC 14496-30 §11.2 / §11.3 - 67-case CCService enum — CEA-608 channels
cc1..cc4+ CEA-708 servicesservice1..service63, with extended 7-bit service number support
- HDR10 — SMPTE ST 2086 mastering display colour volume (
mdcv) + CTA-861.3 content light level (clli) - HLG / HDR10+ — colour-information box variants per ISO/IEC 14496-12 §8.5.2.2 + ISO/IEC 23001-8
- Dolby Vision — Profile 5 / 7 / 8.x / 10 with
DolbyVisionConfigurationBox(dvcC/dvvC/dvwC/lhvC) + Enhancement Layer config; HDR10-compatible base-layer signalling - ICC colour profiles — full
profcolour information box reader + writer with element-relativemlucoffsets per ICC.1:2010 + ICC.1:2022 §10.13 (Adobe / ColorSync / Argyll CMS cross-encoder interop verified)
- Apple platforms — macOS 14, iOS 17, iPadOS 17, tvOS 17, watchOS 10, visionOS 1; xcodebuild matrix runs on every release
- Linux — Swift 6.2 toolchain (
swift:6.2-jammy); 3,574 tests / 3,574 pass; zero conditional dependencies (noswift-crypto, no platform shims) - Strict concurrency — every public type is
Sendable; zero@unchecked Sendable, zerononisolated(unsafe), zero@preconcurrency, zeroTask.detached
| Standard | Section / Scope |
|---|---|
| ISO/IEC 14496-12 (ISO BMFF) | full box hierarchy |
| ISO/IEC 14496-14 (MPEG-4 sample entry) | mp4a |
| ISO/IEC 14496-15 (NAL unit carriage) | avcC / hvcC |
| ISO/IEC 14496-30 (Timed Text) | wvtt / stpp / c608 / c708 |
| ISO/IEC 23000-19 (CMAF) | 7 profiles, conformance validator |
| ISO/IEC 23001-7 (CENC) | 4 schemes |
| ISO/IEC 23001-8 (CICP) | colour primaries / transfer / matrix |
| ISO/IEC 23008-2 (HEVC) | full bitstream parsing |
| ISO/IEC 23008-3 (MPEG-H 3D Audio) | mhm1 / mhm2 |
| ISO/IEC 23009-1 (DASH ISO BMFF) | sidx / prft / emsg |
| ITU-T H.264 / H.265 | NAL units, parameter sets, VUI, HRD, SEI |
| IETF RFC 8216bis-15 (LL-HLS) | partial chunks |
| IETF RFC 9639 (FLAC) | frame header + metadata blocks |
| AOMedia AV1 | sequence header, OBU framing |
| WebM VP8 / VP9 | codec config records |
| ETSI TS 102 366 (AC-3 / E-AC-3) | AC3SpecificBox |
| ETSI TS 103 190-2 (AC-4) | AC4SpecificBox |
| W3C WebVTT / TTML2 / IMSC1 | subtitle formats |
| CTA-608-E / CTA-708-E | closed captions |
| ATSC A/72 / SCTE-128 | SEI signalling |
| ICC.1:2010 / 2022 | colour profile elements |
| Google Widevine | CencHeader Protocol Buffer |
| Microsoft PlayReady | PRO + WRMHEADER v4.0-4.3 |
| Apple FairPlay Streaming | Modular DRM binary |
| W3C EME ClearKey | JSON init data |
| MDC Marlin Broadband | BBA URN |
| GY/T 277.2 ChinaDRM | KID array |
| IETF RFC 4648 §5 | base64url |
| DASH-IF IOP | DRM system ID registry |
See the DocC catalog for the full API documentation. The library is organised in eleven layered modules where lower layers cannot reference upper layers (BinaryIO → Media → ISOBMFF → CodecBitstream → CodecSampleEntries → Color → Encryption → Fragmentation → Reader → Validator → CMAFProfiles).
A high-level overview is in Showcase.md.
| Library | Role |
|---|---|
| swift-cmaf-kit (this repo) | ISO BMFF / CMAF / CENC foundation |
| swift-hls-kit | HLS playlists + segments — depends on CMAFKit |
| swift-dash-kit (future) | DASH manifests + segments |
| swift-rtmp-kit | RTMP transport over TCP |
| swift-srt-kit | SRT transport over UDP |
| swift-icecast-kit | Icecast / Shoutcast HTTP audio |
| swift-capture-kit | Audio + video capture |
CMAFKit ships the container, codec, conformance, and encryption surface. CMAFKitDRM is an opt-in second library product that lifts the opaque pssh.data field carried by ISOBMFF pssh boxes into typed shapes per the public specifications of nine DRM systems. Consumers that do not need DRM typing depend on CMAFKit only.
cmafkit-cli is the companion executable:
cmafkit-cli probe init.mp4 # per-track metadata
cmafkit-cli validate init.mp4 --profile cmaf # conformance validator
cmafkit-cli dump-tree init.mp4 --depth 3 # box hierarchy
cmafkit-cli decrypt-init init.mp4 --output json # typed DRM init dataEvery subcommand accepts --output text|json|table and is read-only (never modifies the input file). The decrypt-init subcommand parses pssh init data; it never handles decryption key material.
swift test # 3575+ tests
xcodebuild test -scheme swift-cmaf-kit-Package \
-destination 'platform=macOS' # Apple platforms
docker run --rm -v "$(pwd):/repo" -w /repo \
swift:6.2-jammy bash -c "swift test" # Linux parityThe 6-platform xcodebuild matrix (macOS / iOS Sim / iPadOS Sim / tvOS Sim / watchOS Sim / visionOS Sim) is run for every release.
Contributions welcome. Pull requests must:
- Pass
swift teston macOS + Linux - Pass
swift-format lint --strictandswiftlint --strict - Cite the relevant standard in the doc comment for any new public symbol
- Add tests for any new behaviour
Apache 2.0 — see LICENSE.
CMAFKit is developed by Atelier Socle SAS. The library is built against the public specifications cited in the standards coverage table above; we acknowledge the standards organisations (ISO/IEC, ITU-T, IETF, ETSI, W3C, CTA, SCTE, DASH-IF, AOMedia) whose specifications make interoperable streaming media possible.