atelier-socle/swift-cmaf-kit

Status

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

What's new in 0.1.2

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 |

Metrics

• +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-crypto removed; swift-argument-parser + swift-docc-plugin remaining)
• Coverage ≥ 92 % global maintained (93.53 %)

Validation

• xcodebuild test -scheme swift-cmaf-kit-Package -destination 'platform=macOS' → TEST SUCCEEDED (the headline behavioural validation of 0.1.2)
• xcodebuild build matrix 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.

Requirements

• 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's swift-argument-parser.

Installation

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"),
        ]
    )
]

Quick start

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

Features

Reading

• 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 typed CMAFTrackConfiguration list from a ftyp + moov byte stream; handler-dispatched video / audio / subtitle / metadata resolution per ISO/IEC 14496-12 §8
• Media segments — CMAFMediaSegmentReader (actor) ingests segment-by-segment, yields typed CMAFParsedSample values 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 BoxRegistry for custom box parsers; default registry covers 100+ ISOBMFF / CMAF boxes

Writing

• Init segments — CMAFInitSegmentWriter composes the ftyp + moov tree from typed track configurations; brand composition selects iso6 + the CMAF major brand (cmfc / cmf2 / cmff / cmfl / cmfs / cmfd / cmfh) + codec-specific compatible brands
• Media segments — CMAFMediaSegmentWriter (actor) emits moof + mdat fragments with monotonic tfdt and sample-accurate trun offsets; supports multi-fragment segments and LL-HLS partial chunks via CMAFPartialChunkBoundary
• Fragment boundaries — CMAFFragmentBoundary predicates: 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 / enca sample-entry rewrite, sinf / schm / schi / tenc emission, senc boxes with per-sample IVs + optional subsample partitions
• Segment indices — sidx / prft / emsg emission for DASH-aligned content; LL-HLS partial chunks per IETF RFC 8216bis-15 §B

Validating

• CMAF — CMAFConformanceValidator enforces 10+ rules from ISO/IEC 23000-19 §7 (SAP at fragment head, uniform track ID per traf, declared tracks, encryption symmetry, iso6 + cmfc brand presence, mfhd sequence monotonicity, per-track tfdt monotonicity)
• DASH — DASHConformanceValidator enforces the ISO BMFF profile (ISO/IEC 23009-1 §6.3) and DASH-IF IOP recommendations (sidx mandatory, prft NTP signalling, emsg timescale alignment, segment-duration consistency, timescale ≥ 1000)
• Low-Latency HLS — LLHLSConformanceValidator enforces IETF RFC 8216bis-15 §B partial-chunk rules (first sample sync ↔ INDEPENDENT, unique mfhd.sequence_number, PART-TARGET enforcement, first-chunk INDEPENDENT flag, per-fragment tfdt monotonicity)
• Structural integrity — every typed parser throws a precise ISOBoxError / CMAFReaderError on malformed input, never silently degrades
• Reports — CMAFValidationReport aggregates issues across validators; each issue carries severity (error / warning / info), rule reference (spec section number), description, optional track ID, optional segment index

Encrypting (Common Encryption)

• 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_block parameters for cens and cbcs
• Per-sample metadata — typed CMAFSampleInput.EncryptionMetadata carries the IV + optional subsample partitions; the reader recovers them byte-perfectly
• PSSH passthrough — ProtectionSystemSpecificHeaderBox carries any DRM system's init data verbatim; the opt-in CMAFKitDRM target 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

DRM init-data typing (opt-in CMAFKitDRM)

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.

Closed captions

• In-band SEI extraction — CEA-608 byte pairs and CEA-708 DTVCC packets carried inside AVC / HEVC SEI user_data_registered_itu_t_t35 messages with the ATSC A/72 signature; ClosedCaptionExtractor actor surfaces typed ClosedCaptionData
• DTVCC reassembly — cross-NAL DTVCC packet reassembly per CTA-708-E §6 + SCTE-128 §8
• Out-of-band caption tracks — typed c608 and c708 sample entries per ISO/IEC 14496-30 §11.2 / §11.3
• 67-case CCService enum — CEA-608 channels cc1..cc4 + CEA-708 services service1..service63, with extended 7-bit service number support

HDR and Dolby Vision

• 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 prof colour information box reader + writer with element-relative mluc offsets per ICC.1:2010 + ICC.1:2022 §10.13 (Adobe / ColorSync / Argyll CMS cross-encoder interop verified)

Cross-platform

• 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 (no swift-crypto, no platform shims)
• Strict concurrency — every public type is Sendable; zero @unchecked Sendable, zero nonisolated(unsafe), zero @preconcurrency, zero Task.detached

Standards coverage

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

Architecture

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.

Atelier Socle ecosystem

| 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 vs CMAFKitDRM

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.

CLI

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 data

Every 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.

Testing

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 parity

The 6-platform xcodebuild matrix (macOS / iOS Sim / iPadOS Sim / tvOS Sim / watchOS Sim / visionOS Sim) is run for every release.

Contributing

Contributions welcome. Pull requests must:

• Pass swift test on macOS + Linux
• Pass swift-format lint --strict and swiftlint --strict
• Cite the relevant standard in the doc comment for any new public symbol
• Add tests for any new behaviour

License

Apache 2.0 — see LICENSE.

Acknowledgments

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.

Package Metadata

Repository: atelier-socle/swift-cmaf-kit

Default branch: main

README: README.md