English | 中文
A local-first macOS personal radio player with an AI host.
VoxRadio combines a native SwiftUI player with Apple Music, a local VoxCPM2 TTS sidecar, a lightweight Text DJ, and optional Memory. It is designed to start with a calm Daily Opening and then get out of the way while music plays.
Public preview: macOS 15+, local development project, not a signed consumer app. The fastest path uses Mock TTS and does not download a model.
- Daily Opening: prepares a short weather, agenda, and music-aware host segment, with replay, skip, and Apple Music handoff states.
- Now Playing: keeps the current music or opening segment as the first screen instead of turning the app into a service dashboard.
- Music Discovery: searches Apple Music and presents song, artist, and album paths when MusicKit is configured.
- Text DJ: accepts short natural-language listening requests and keeps quick playback controls available when the DJ provider is unavailable.
- Local sidecars: TTS, DJBrain, and Memory are explicit HTTP services with health checks and graceful degradation.
- Validation composition: app-level endpoint injection and disabled clients make side-effect-free local verification possible.
See docs/ARCHITECTURE.md for the app/service boundary, data flow, and reliability rules.
- macOS 15 or newer;
- full Xcode with the macOS toolchain selected;
- Python 3.11 or 3.12 for the real TTS path; Mock TTS has no model dependency;
- Python 3.12+ for the DJBrain sidecar and its checks.
Start the mock sidecar:
scripts/start_demo_tts.shThen open the project:
open VoxRadio.xcodeprojIn Xcode, select the VoxRadio scheme and the My Mac destination. The app
can also run without sidecars and will use local demo fallbacks for the player
flow.
Useful commands:
scripts/voxradio-services status
scripts/voxradio-services smoke
scripts/voxradio-services stopThe default local endpoints are loopback-only:
- TTS:
127.0.0.1:8765 - DJBrain:
127.0.0.1:8787 - Memory: managed by
scripts/voxradio-memory
The real path is deliberately explicit. It may install Python dependencies, download model files, and take several minutes on first use:
scripts/start_real_tts.sh
services/tts/scripts/smoke_real_tts.shKeep model files and generated audio outside Git. The repository contains the sidecar and its tests, not VoxCPM2 weights.
Real search and playback require the contributor's own Apple Developer configuration, a MusicKit-capable bundle identifier, user authorization, and an Apple Music subscription. The local demo and unit tests do not provide a MusicKit entitlement or redistribute music.
swift run VoxRadioCoreChecks
swift test
TTS_PYTHON=python3.11
DJBRAIN_PYTHON=python3.12
"$TTS_PYTHON" services/tts/tests/run_checks.py
"$DJBRAIN_PYTHON" services/djbrain/tests/run_checks.py
git diff --checkUse the full path to your supported Python executable when python3.11 or
python3.12 is not on PATH.
For an app build:
xcodebuild -project VoxRadio.xcodeproj \
-scheme VoxRadio \
-configuration Debug \
-derivedDataPath .build/xcode-derived \
buildVoxRadio is designed for local use. Do not commit ~/.voxradio, Memory
databases, auth files, provider tokens, raw transcripts, generated WAV files,
or model weights. Read SECURITY.md before sharing logs.
The app may request access to Apple Music, location, calendar, and reminders when those features are enabled. You control those permissions in macOS.
- The project is macOS-only and currently distributed as source.
- Real VoxCPM2 synthesis depends on local hardware, model availability, and Python environment setup.
- Apple Music features need signing and user authorization.
- Text DJ quality depends on the configured local provider.
- Memory is optional; the app remains useful with no-memory mode and degraded sidecars.
Start with CONTRIBUTING.md. Focused pull requests and redacted reproducible reports are especially welcome.
The project code is released under the MIT License. Third-party services, model weights, Apple Music content, and referenced design resources remain subject to their own terms.