AudioMarker

You have a raw audio file. You want to add timestamped chapters, cover art, proper metadata. Simple, right?

In reality, it's an uphill battle.

Back when I was producing electronic music podcasts, GarageBand could encode M4A/M4B files with built-in chapters. It was tedious, but it worked. Apple has since dropped this feature — and nobody really stepped up.

Today, options are limited: obscure command-line tools, inflexible paid apps, or heavy dependencies like FFmpeg that you can't ship in an iOS app. Nothing native, nothing Swift, nothing truly built for Apple developers.

AudioMarker fills this gap.

AudioMarker is a production-ready Swift library for enriching your audio files with metadata, chapters, artwork and synchronized lyrics.

The core library is pure Swift with zero external dependencies. All parsing and writing — whether ID3v2 for MP3 or ISOBMFF/iTunes atoms for M4A — happens at the byte level, with streaming I/O that never loads audio data into memory. Even on a 3-hour podcast, memory footprint stays minimal.

Two interfaces, same power:

A Swift library — Drop into your iPhone, iPad, Mac and Vision Pro apps. Zero external dependencies, 100% native, App Store compatible.

A CLI tool — 17 commands for command-line processing, automation and CI/CD pipelines.

The list is long, and that's intentional. When working with audio, you want a tool that handles all cases — not just the easy 80%.

Let's start with the simplest case: reading an audio file and displaying its info.

AudioMarkerEngine is the unified entry point. It auto-detects the format from magic bytes and file extension, then dispatches to the appropriate reader — you don't need to worry about whether it's an MP3, M4A or M4B.

AudioMarker supports 30 metadata fields across 7 categories. Here's how to write the most common ones:

Artwork format is auto-detected from magic bytes — no need to specify whether it's JPEG or PNG.

For the curious, here's the complete list organized by category:

These fields cover both the ID3v2 spec (TXXX, WXXX, PRIV, UFID frames...) and iTunes atoms for M4A. AudioMarker writes in the correct format based on file type.

Chapters transform a monolithic audio file into a navigable experience. Podcast, audiobook, DJ mix — everything becomes more accessible with proper chaptering.

AudioMarker automatically handles IN/OUT points: you don't need to specify each chapter's end time, it's calculated from the next chapter's start.

The Enhanced Podcast format (popularized by Apple in the 2000s) allows associating a link and image with each chapter. Perfect for show notes, sponsors, or visual references.

For M4A/M4B files, AudioMarker writes chapters in two formats simultaneously:

This dual writing guarantees maximum compatibility without any extra effort on your part.

Have chapters in an external format? Or want to export to a specific format? AudioMarker supports 7 exchange formats with bidirectional import/export (except Markdown, export only).

Example export to Podlove JSON:

You can also import directly into an audio file:

Beyond chapters, AudioMarker handles synchronized lyrics — timestamped text that displays in real-time during playback. Three complexity levels are supported.

For karaoke, each word can have its own timing. AudioMarker uses LyricSegment to split a line into pieces:

For podcasts with multiple speakers, or audio drama, you can identify who's speaking on each line:

When writing to M4A, AudioMarker automatically chooses the best storage format:

You don't need to think about it — the right choice is made for you.

4 formats are supported for lyrics exchange:

TTML supports full round-trips — speakers, styles and regions survive export/import.

Before publishing an enriched audio file, it's better to verify everything is consistent. AudioValidator inspects an AudioFileInfo and reports potential issues:

You can create your own rules via the ValidationRule protocol:

You can configure the engine to automatically validate before each write:

When you have 200 podcast episodes to process, doing it one by one isn't an option. BatchProcessor processes multiple files in parallel with bounded TaskGroup concurrency — you control how many files are processed simultaneously.

To display a progress bar or indicator, use processWithProgress which returns an AsyncStream:

Supported batch operations: .read, .write(_:), .strip, .exportChapters(format:outputURL:).

AudioTimestamp is the type used throughout AudioMarker to represent a point in time. It offers millisecond precision and parsing/formatting utilities:

The engine accepts several configuration options:

ID3 padding is an important optimization: if you frequently modify a file's tags, sufficient padding avoids rewriting the entire audio file on each modification.

audio-marker is the command-line interface that exposes all library features. Perfect for scripts, automation and CI/CD pipelines.

AudioMarker implements several audio standards. Here are the references for those who want to understand what's happening under the hood:

The package is organized in distinct modules with clear separation of concerns:

The AudioMarker module has zero external dependencies. Only the CLI depends on swift-argument-parser for argument parsing.

Add the package to your Package.swift:

Then add the dependency to your target:

AudioMarker is at version 0.1.0 with all features documented above. Here's what's planned for future releases: