A macOS app for software-defined radio (SDR) streaming. It tunes an RTL-SDR USB device, demodulates FM/AM/HD Radio signals, and streams audio to a web browser via a built-in HTTP/HTTPS server powered by LiveAudioServer. The same interface shown in the app's AntennaHead tab (based on LocalRadio) is available in a browser on any device on the local network.
Project site & interactive web-UI demo: https://antennahead-app.github.io
- macOS 14 (Sonoma) or later
- Xcode 15 or later
- An RTL-SDR USB dongle (optional — audio device and custom-task sources work without one)
All dependencies are resolved by Swift Package Manager when the project is opened in Xcode:
| Package | Purpose |
|---|---|
| GRDB | SQLite database (frequencies, categories, settings) |
| LiveAudioServer | Embedded streaming server (AAC/HLS over HTTP/HTTPS) |
| PipelineHelpers | Pipeline runner shared with ControlBooth |
| SharedLogging | Shared log store + viewer window shared with ControlBooth |
| librtlsdr | RTL-SDR driver (XCFramework) |
| swift-certificates | TLS certificate generation |
| swift-asn1 | ASN.1 / DER encoding (for PKCS#12 export) |
| swift-crypto | P-256 key generation for self-signed TLS certs |
The LiveAudioServer helper binary is also vendored at AntennaHead/LiveAudioServer for use as a subprocess; refresh it manually when updating the LAS package.
LiveAudioServer, PipelineHelpers, and SharedLogging are
local Swift packages, referenced by relative path (../LiveAudioServer,
../PipelineHelpers, ../SharedLogging) rather than by
URL — Xcode can only resolve them if this repo is checked out with those three
as sibling directories. The antennahead-workspace
umbrella project's bootstrap.sh sets up exactly that layout; use it instead
of cloning this repo standalone if you plan to build from source rather than
just consuming released binaries.
- Clone the repo:
git clone https://github.com/dsward2/AntennaHead.git cd AntennaHead - Open
AntennaHead.xcodeprojin Xcode. - Select the AntennaHead scheme and your Mac as the destination.
- Build and run (
⌘R).
SPM dependencies are fetched automatically on first build. No brew or manual tooling is required.
| Service | Protocol | Default Port |
|---|---|---|
| AntennaHead interface (browser access) | HTTP | 8090 |
| AntennaHead interface (browser access) | HTTPS | 8094 |
| LiveAudioServer stream | HTTP | 8080 |
| LiveAudioServer stream | HTTPS | 8443 |
| RTL-SDR status feed | UDP | 6021 |
| Pipeline audio input | UDP | 6020 |
| ControlBooth audio input | UDP | 6019 |
| Speech-to-text caption feed | UDP | 6023 |
| Filler fade control | UDP | 6026 |
| Filler announcement audio | UDP | 6027 |
| Filler mixer control | UDP | 6028 |
Most ports are configurable from the Configuration tab → Change Configuration… sheet. The speech-to-text caption feed (6023), the filler fade control (6026), and the filler announcement audio/mixer-control pair (6027 / 6028) are fixed internal constants — loopback only, both ends owned by AntennaHead — and are not exposed in that sheet. Changes restart the streaming servers.
- AntennaHead tab and browser access — Full-featured LocalRadio-compatible interface, shown in the app's AntennaHead tab and also accessible from any browser on the LAN. Supports favorites, categories, frequency tuner, audio devices, and custom pipeline tasks.
- FM / AM / HD Radio — Demodulates signals via
rtl_fmand optional stereo demux helper. - Audio devices — Stream from any Core Audio input device as an audio source.
- Custom tasks — Define arbitrary shell pipelines (via PipelineHelpers) as audio sources.
- HTTPS — Optional TLS with auto-generated self-signed cert or a user-supplied
.p12. Toggle on/off in the Security tab without discarding the certificate. - HTTP Authentication — Optional username/password protection forwarded to LiveAudioServer.
- FCC search — Look up US broadcast stations by frequency or call sign.
- ControlBooth — Optional bidirectional Apple Events remote-control channel. See Docs/AppleEvents.md.
AntennaHead can be remotely controlled by the companion ControlBooth app over a bidirectional Apple Events channel. Enable the integration in the Configuration tab. See Docs/AppleEvents.md for the full protocol description.
- The app is sandboxed. Helper processes (
LiveAudioServer,rtl_fm, stereodemux) are launched as child processes with--exit-with-parentwatchdogs so they are reaped if the parent exits. - The web server and all DB access run on the
@MainActor. Nonisolated network routing dispatches back to the main actor for any state access. - Port and bitrate settings are persisted in a SQLite database (Application Support/AntennaHead/).
- TLS certificates are stored in the macOS keychain and exported to a PKCS#12 file for the LiveAudioServer subprocess.
See individual source files and Web/credits.html for third-party credits and licenses.