IcecastKit

When you listen to a web radio or a live audio stream, there's a server behind it that receives the broadcaster's feed and redistributes it to listeners. That server is often Icecast — an open-source project by the Xiph.org foundation — or SHOUTcast, its historical counterpart.

The concept: a source client connects to the server, sends a continuous audio stream (MP3, AAC, Ogg…), and the server redistributes it to all connected listeners over HTTP. Simple on the surface, but the protocol has its subtleties — PUT vs SOURCE negotiation, HTTP Basic or plaintext password authentication, binary ICY metadata interleaved into the stream, automatic source ports for SHOUTcast, and disconnect handling.

While building the Atelier Socle streaming ecosystem — PodcastFeedMaker for RSS feeds, HLSKit for HTTP Live Streaming — the missing piece was live broadcasting to Icecast and SHOUTcast servers. Not a wrapper around a C library, not a shell script — a proper native Swift client, with Swift 6.2 structured concurrency, zero dependencies in the core, and cross-platform TCP transport (Network.framework on Apple, POSIX sockets on Linux).

I looked. Nothing existed in Swift. IcecastKit was born from that need.

Version 0.2.0 — Broadcast Engine — transforms IcecastKit from a simple streaming client into a full broadcast engine: adaptive bitrate with congestion detection, simultaneous multi-destination publishing, bandwidth probing, connection quality scoring, local recording with file rotation, relay/ingest from existing streams, advanced authentication (Digest, Bearer, query token), server presets for 7 platforms, and Prometheus and StatsD metrics export. All backed by 1246 tests and 97.13% coverage.

Version 0.3.0 adds ADTS wrapping (ISO 13818-7) for sending raw AAC without worrying about framing, enables TCP_NODELAY on both transport layers to eliminate Nagle buffering on small audio frames, and moves monitoring off the critical send path. 1281 tests.

Version 0.2.0 — Broadcast Engine — adds 9 major modules:

Version 0.3.0 adds ADTS wrapping and transport optimizations:

The new send(rawAAC:audioConfiguration:) API lets you send raw AAC encoder output without worrying about ADTS framing. IcecastKit automatically builds the compliant 7-byte header per ISO 13818-7 with sync word, profile, sample rate index, channel configuration and frame length:

IcecastKit is a pure Swift library for streaming audio to Icecast and SHOUTcast servers. It covers the entire broadcast lifecycle: connection, authentication, audio data transmission, metadata updates, real-time statistics, and graceful disconnection. All with strict Sendable conformance end to end.

Connect to an Icecast server, stream audio data, update the now-playing metadata, and disconnect gracefully — in a few lines:

Via Swift Package Manager, by adding the dependency to your Package.swift:

Then add it to your target:

The TCP transport adapts automatically: Network.framework on Apple platforms, POSIX sockets on Linux.

You can configure a full station with name, genre, bitrate, sample rate and channels. The client negotiates the best protocol automatically — trying modern HTTP PUT first, then falling back to legacy SOURCE if the server is pre-2.4.0:

Parse a connection URL into a configuration and credentials in one call. Supports icecast://, shoutcast://, http://, and https:// schemes:

SHOUTcast v1 uses password-only authentication. IcecastKit automatically connects to the source port (listener port + 1) and sends the password line followed by icy-* stream headers:

SHOUTcast v2 extends v1 with stream IDs for multi-stream servers. The password is sent as password:#streamId:

The AsyncStream-based event bus lets you react in real time to connection state changes, metadata updates, errors, and periodic statistics:

IcecastKit handles automatic reconnection when a connection is lost mid-stream. Four presets are available, and custom policies are supported with jitter to prevent thundering herd problems:

The reconnection delay follows: min(initialDelay × backoffMultiplier^attempt, maxDelay) ± jitter. Non-recoverable errors (authentication failure, mountpoint in use, content type rejected) transition directly to .failed without retrying. Calling disconnect() during reconnection cancels the loop immediately.

IcecastKit handles full encoding and decoding of the ICY binary wire format for inline stream embedding. Unicode support, escaped quotes, and custom fields:

The MetadataInterleaver inserts metadata blocks into an audio stream at fixed byte intervals. It's an actor that tracks its position across multiple calls, so you can feed audio data in any chunk size:

Server-side metadata updates via the Icecast admin HTTP API are the preferred method (over inline metadata). You can also query global server statistics and per-mountpoint stats:

When adminCredentials are set on IcecastConfiguration, IcecastClient.updateMetadata() automatically uses the admin API and falls back to inline metadata if the admin endpoint returns 404:

IcecastKit auto-detects the audio content type from a filename extension:

IcecastClient is an actor — all operations are inherently thread-safe. You can safely call send() and updateMetadata() from multiple concurrent tasks without data races:

IcecastKit monitors network conditions in real time and emits bitrate recommendations. The NetworkConditionMonitor detects congestion via EWMA latency spikes, RTT spikes, and bandwidth slowdowns. AudioQualityStep provides per-format bitrate tiers (MP3: 7 steps from 32–320 kbps, plus AAC, Opus, Vorbis). Three presets (conservative, responsive, aggressive) plus full custom configuration:

The MultiIcecastClient actor lets you stream to multiple servers simultaneously with independent connections and failure isolation. Destinations can be added or removed live while streaming. Each destination has its own reconnection policy:

IcecastBandwidthProbe measures upload bandwidth and latency before committing to a live stream. The result includes measured bandwidth, average write latency, latency class, a stability score and a format-aware bitrate recommendation:

Connection quality scoring provides a composite score (0.0–1.0) computed from five weighted metrics: write latency (30%), throughput (25%), stability (20%), send success (15%), reconnection (10%). QualityGrade is Comparable with five levels:

Quality events arrive via the event stream: .qualityChanged(_:) and .qualityWarning(_:).

The StreamRecorder actor writes audio to disk with automatic file rotation. Rotation can be size-based or time-based. Filenames support dynamic tokens ({date}, {mountpoint}, {index}) and extensions are auto-detected by format:

Recording integrates with IcecastClient via IcecastConfiguration.recording for auto-start recording. Events: .recordingStarted, .recordingStopped, .recordingFileRotated.

The IcecastRelay actor pulls audio from an existing Icecast or SHOUTcast stream. It handles ICY metadata demuxing, content type detection, and can be chained with IcecastClient for relay-to-publish or with StreamRecorder for relay-to-record:

IcecastKit supports six authentication methods via the IcecastAuthentication enum. Beyond classic HTTP Basic and SHOUTcast password, version 0.2.0 adds Digest (RFC 7616 with MD5 and SHA-256 — the password never goes on the wire), Bearer token, query token, and automatic URL credential parsing/stripping:

IcecastServerPreset provides one-line configuration for 7 popular streaming platforms. Port, authentication method, protocol and default mountpoint are preconfigured:

IcecastKit can export streaming metrics to Prometheus (OpenMetrics format) or StatsD (UDP datagrams). The IcecastMetricsExporter protocol defines the common interface, and labels are auto-generated from configuration (mountpoint, server) with consumer overrides:

Exported metrics: bytes_sent, stream_duration_seconds, current_bitrate, metadata_updates_total, reconnections_total, write_latency_ms, peak_bitrate, connection_quality_score. Labels are auto-generated from configuration (mountpoint, server) with consumer overrides.

The library is organized into 16 clearly separated modules, each with a well-defined responsibility:

icecast-cli provides command-line streaming, bandwidth probing, relaying, connection testing, and server diagnostics with colored terminal output and structured exit codes (0 = success, 2 = connection error, 3 = auth error, 4 = file error, 6 = server error, 7 = timeout).

IcecastKit is part of the Atelier Socle streaming ecosystem: