Codebase reference

Codec has a Go music server, a Svelte web player, and a SwiftUI app for iPhone and iPad. This page maps the source for people reading or adapting it. For everyday use, start with the Loud format or hosting guide.

We’re not accepting contributions or pull requests right now. The source is available to read and use under the MIT license.

Source and release versions

This reference describes v0.1.7. The server packages include the web player and Ubuntu installation tools. Match the source tag to your release when investigating behavior. The hosting guide covers installation without building from source.

Where things live

How the apps connect

The Go server serves the built web interface and API from one address. Browsers use HTTP for library and media requests and server-sent events for playback updates. SwiftUI has its own views and audio engine and connects through CodecKit; it does not embed the web interface.

The server coordinates the shared library, queue, playback ownership, and position. Each client plays audio locally. Updating the website does not update an installed native app. A development Vite server is separate from this production arrangement.

Protocols and identity

Library, import, artwork, and Aux endpoints live under /api/v1; playback state, commands, and events use /api/v2/playback. The payload names loud.import.v1, loud.sync.v1, loud.playback.v2, and loud.aux.v1 remain compatibility identifiers despite the Codec app name. Track fingerprints connect imports, playlist membership, and media.

See server playback_v2.go and auth_tokens.go, web src/lib/sync.ts, and Swift PlaybackModels.swift. Authenticated clients use the configured server token; media consumers that cannot set headers can obtain a short-lived stream token.

Storage boundaries

The server’s --data directory holds codec-sync.sqlite, audio/, and artwork/. Its --web directory contains replaceable built web files. CLI staging libraries keep metadata in .loud/state.json; loud:// paths are logical identifiers, not ordinary filesystem paths.

Native library caches, artwork, and downloads live in the app’s container. The web app has separate browser storage and explicit audio downloads; its service worker caches the interface. Downloading in one client does not download into another.

Build and check locally

Run these from the repository root. Use the Bun version in package.json, the checked-in lockfile and the Go version in .go-version. iPhone and iPad app builds need macOS and Xcode.

bun install --frozen-lockfile
bun run dev                 # Web interface development
bun run build               # Production web files in build/
go -C sync-server build ./cmd/codec-sync-server

Checks have different scopes:

bun run check               # Svelte and TypeScript
bun run test:frontend       # Bun tests
bun run test:server         # Go tests
(cd ios/CodecMobile && swift test)  # CodecKit models and API client

swift test does not exercise SwiftUI, AVPlayer, or Metal. Use the Xcode Codec scheme on a dedicated simulator for app-hosted tests. bun run check:quick runs web, server, and contract checks; its schema checks require Python’s jsonschema package. These commands do not deploy anything.

Build server packages

The release builder requires Python 3.11 or newer, plus the pinned Bun and Go versions. It builds the web player once and packages Linux AMD64 and ARM64 servers with checksums and Ubuntu scripts:

bun run release:server -- --version my-build

Outputs go to dist/server/. Use a distinct version for a changed build; the installer rejects different contents under an installed version. Building packages does not publish a release or modify a server.

Optional import tool

codec_import is a separate source-built tool for local scanning, staging, artwork import and server transfers. It is not included in the Linux server package and is not required for the web player’s Settings → Import music flow.

The tool uses Rust code in src-tauri/: src/library/ owns library operations, src/sync_transfer.rs handles server transfers, and src/bin/codec_import.rs is the CLI. The desktop UI is paused; this import code and its tests remain supported. Building the CLI still requires Rust and the Tauri package’s platform dependencies. The shipped Go server, web player and Swift app do not depend on this tool.

Unzip the bundle first and keep its referenced files together. Use an empty staging directory: a server merge scans that entire directory. Replace the paths and server address below; the token file contains your private server token.

cargo build --release --manifest-path src-tauri/Cargo.toml --bin codec_import
mkdir -p ./staging-library
src-tauri/target/release/codec_import \
  ./staging-library ./my-collection/loud-import.json \
  --server https://your-server.example \
  --token-file /private/path/codec-token \
  --report ./import-report.json

bun run test:rust           # Import library and CLI tests

Omit --server and --token-file for a local-only import. Server imports match exact fingerprints and add missing media and memberships while preserving existing metadata and covers. The Loud format guide explains identities, playlist matching and artwork descriptors.

UI and theme reference

Web theme tokens live in src/app.css and src/lib/themes.ts. bun run gen:ios-themes generates their Swift counterpart, App/Themes.generated.swift. SwiftUI shared view primitives live in App/Views/Components.swift. Graphite is the default appearance.