Writing fragmented MPEG-4 files for HTTP Live Streaming

At a glance

Project structure

fmp4writer/
├── main.swift
├── Configuration.swift
├── TrackLoading.swift
├── SegmentGeneration.swift
├── IndexFileGeneration.swift
└── Error.swift

The flat folder is architectural: files are named for sequential pipeline responsibilities rather than UI features or layers.

Overall architecture

flowchart LR
    CLI["main.swift"] --> Config["FMP4WriterConfiguration"]
    CLI --> Load["loadTracks"]
    Load --> Source["SourceMedia"]
    Source --> RW["ReaderWriter"]
    RW --> Subject["Segment Subject"]
    Subject --> Files["Segment file writer"]
    Subject --> Index["Index-file reducer"]
    Index --> Playlist["m3u8 writer"]

Reference code

fmp4writer/main.swift:41 — top-level composition fans one segment stream into two sinks (abridged).

let segmentGenerator = PassthroughSubject<Segment, Error>()
let indexFileGenerator = segmentGenerator.reduceToIndexFile(using: config)

let segmentFileWriter = segmentGenerator.tryMap { segment in
    let name = segment.fileName(forPrefix: config.segmentFileNamePrefix)
    try segment.data.write(to: outputDirectoryURL.appendingPathComponent(name))
}

segmentAndIndexFileWriter = segmentFileWriter.merge(with: indexFileWriter)
    .sink(receiveCompletion: { completion in /* finish */ }, receiveValue: {})

This is a dataflow-oriented command-line architecture: main.swift composes stages, while stage files own transformations.

Ownership and state

classDiagram
    Main *-- FMP4WriterConfiguration
    Main *-- ReaderWriter : retained token
    Main *-- AnyCancellable : retained sink
    ReaderWriter *-- AVAssetReader
    ReaderWriter *-- AVAssetWriter
    ReaderWriter *-- AVAssetReaderOutput
    ReaderWriter *-- AVAssetWriterInput
    ReaderWriter o-- Subject : supplied

Ownership evidence

fmp4writer/main.swift:20 and fmp4writer/SegmentGeneration.swift:35 — top-level tokens retain the async graph; ReaderWriter owns AVFoundation components (abridged).

var segmentGenerationToken: Any?
var segmentAndIndexFileWriter: AnyCancellable?

class ReaderWriter<S>: NSObject, AVAssetWriterDelegate
where S: Subject, S.Output == Segment, S.Failure == Error {
    private let assetReader: AVAssetReader
    private let assetWriter: AVAssetWriter
    private let subject: S
    private let audioReaderOutput: AVAssetReaderOutput
    private let videoReaderOutput: AVAssetReaderOutput
}

Class and protocol design

classDiagram
    class Subject {
        <<protocol>>
    }
    class AVAssetWriterDelegate {
        <<protocol>>
    }
    ReaderWriter ..|> AVAssetWriterDelegate
    ReaderWriter --> Subject : generic output
    PassthroughSubject ..|> Subject
    Segment --> IndexFileState : reduced into

Reference code

fmp4writer/SegmentGeneration.swift:19 — the producer is generic over Combine’s capability rather than a concrete subject (abridged).

func generateSegments<S>(sourceMedia: SourceMedia,
                         configuration: FMP4WriterConfiguration,
                         subject: S) -> Any?
where S: Subject, S.Output == Segment, S.Failure == Error {
    let readerWriter = try ReaderWriter(
        sourceMedia: sourceMedia,
        configuration: configuration,
        subject: subject
    )
    readerWriter.start()
    return readerWriter
}

The generic boundary is protocol-oriented but narrow: callers choose any matching Subject; ReaderWriter adapts AVAssetWriterDelegate callbacks into Segment values.

Access control

fmp4writer/SegmentGeneration.swift:35 (abridged):

class ReaderWriter<S>: NSObject, AVAssetWriterDelegate
where S: Subject, S.Output == Segment, S.Failure == Error {
    private let assetReader: AVAssetReader
    private let assetWriter: AVAssetWriter
    private let audioDone = PassthroughSubject<Void, Error>()
    private let videoDone = PassthroughSubject<Void, Error>()
    private var done: AnyCancellable?
    private var segmentIndex = 0
}

Logic ownership and placement

Design patterns

Naming conventions

• Files and functions name pipeline stages (TrackLoading, generateSegments, reduceToIndexFile).
• Data carriers are nouns (SourceMedia, Segment, IndexFileState, FMP4WriterConfiguration).
• ReaderWriter names its paired framework ownership; private properties retain framework vocabulary.
• Configuration fields describe output artifacts (segmentFileNamePrefix, indexFileName) and constraints.

Architecture takeaways

• Make the executable entry point a composition root and keep transformations in stage files.
• Adapt framework delegate callbacks into a typed stream when multiple downstream consumers need the same events.
• Retain asynchronous producers and subscriptions explicitly for their required lifetime.
• Use private ownership inside the stateful reader/writer and immutable values between stages.

Source map

Source caveat: the archive uses callback-based AVFoundation loading and Combine. This document describes that source architecture without inferring a newer implementation.

• Official Apple documentation