Tethertone Open Source: Code, Roadmap and Contributing

At a glance

lines of Swift: ~3.1k
lines of Kotlin: ~3.3k
shared-module unit tests: 36
runtime dependencies on the Mac: 0

The Mac app uses only Apple frameworks: SwiftUI, ScreenCaptureKit, AVFoundation, Network and Core Image. The Android app uses Jetpack Compose, CameraX, ZXing and kotlinx. Neither app includes analytics or crash reporting, and neither talks to any server but your own devices.

License

Tethertone is released under the MIT License, © Tethertone contributors. You may use, copy, modify, merge, publish, distribute, sublicense and sell copies, provided the copyright notice and license text are included. The software comes with no warranty.

Repository map

macos/          SwiftUI app: capture, TCP server, QR pairing, adb setup
android/
  shared/       Kotlin Multiplatform: protocol, pairing, jitter buffer, client
  androidApp/   Compose UI, QR scanner, foreground playback service
  desktopSink/  headless JVM client for testing without a phone
docs/           ARCHITECTURE, PROTOCOL, BUILDING, TROUBLESHOOTING
tools/probe.py  independent protocol conformance client
scripts/        release.sh — builds every release artifact

Start with ARCHITECTURE.md for the big picture, then PROTOCOL.md for the wire format.

Contributing

Bug reports, fixes, documentation and testing on more phones are all welcome.

Found a bug? Use the bug report form. Include your macOS and Android versions, the phone model, the capture method and route, and what the Mac's Activity card shows.
Want to fix something? Fork the repository, make one logical change, and run the same checks CI runs:

cd macos && ./build.sh && ./Tethertone.app/Contents/MacOS/Tethertone --selftest
cd ../android && ./gradlew :shared:jvmTest :androidApp:assembleDebug

Open a pull request describing what changed and how you tested it, on which Mac and which phone.

Security issues go through private advisories, not public issues. Everyone taking part follows the Code of Conduct.

Principles

Native on both sides. Swift on the Mac for ScreenCaptureKit and proper permission handling; Kotlin on Android for AudioTrack and a real foreground service.
Two implementations, one contract. Any protocol change updates the spec, the Swift codec and self-test, the Kotlin codec and tests, and the Python probe together.
Platform-free core. The client's logic lives in commonMain with no Android types, so it is tested on the JVM in seconds.
Honest UI. Show real numbers: RTT, underruns, loss, drift. When something can't be done, say so and say what to do instead.
Your devices only. No accounts, no telemetry, no cloud relay.

Roadmap

Candidates, not promises. Discussion and pull requests welcome.

Shipped
0.2.0: renamed to TethertoneFormerly AudioBridge. New app identifiers on both platforms, so it installs as a new app.
Shipped
0.1.0: first public releaseUniversal macOS app, Android app, USB and Wi-Fi, drift correction, QR pairing.
Next
Core Audio process tapsmacOS 14.2+ can capture system audio with only the “System Audio Recording” permission, with no Screen Recording indicator and no BlackHole.
Next
Optional Opus compressionAbout 128 kbit/s instead of 1.5 Mbit/s, for VPN and mobile-data use.
Next
Encrypted transportKeep the one-scan pairing, but encrypt the stream for untrusted networks.
Next
Notarized macOS builds and store listingsNo Gatekeeper prompt; F-Droid and Google Play distribution.
Idea
More platformsWindows and Linux senders, or an iOS receiver, built on the documented protocol.
Idea
Per-app captureStream one app, not the whole mix.

Known gaps

No encryption. The token authenticates; it doesn't conceal. Use USB or a VPN on untrusted networks.
Not notarized. macOS asks you to confirm the first launch.
Multiple listeners are supported but tested only with two phones.
Build tooling: the Kotlin Multiplatform + com.android.library plugin pairing is deprecated in AGP 9 and needs migrating before AGP 10.

Credits

BlackHole by Existential Audio, the optional loopback driver. It isn't bundled.
ZXing for QR decoding, and CameraX for the camera.
Jetpack Compose, Kotlin Multiplatform and kotlinx.coroutines / serialization.

The source of this website is also open: AimenSayoud/tethertone-website.

Open source