Relay

Hear. Relay. Understand.

• License
• How to contribute
• Code of conduct

---

Overview

Relay is a macOS app for live speech transcription and translation. It can listen to your microphone, system audio, or both, transcribe speech with WhisperKit, translate text with Apple Translation, and present the results in a lightweight on-screen overlay with a menu bar interface.

Examples:

• Live subtitles for a meeting or call.
• Translate spoken content from a video, stream, or webinar.
• Keep a transcript and translation overlay available while you work.

---

How it works

1. Relay captures audio from the microphone and/or system output.
2. The audio pipeline prepares chunks for speech-to-text processing.
3. WhisperKit produces transcript segments.
4. Apple Translation translates those segments into the selected target language when that language pair is available.
5. Relay updates the transcript, translation, overlay, and menu bar state from the app flow.

flowchart LR
    mic["Microphone audio"] --> input["Audio input pipeline"]
    sys["System audio"] --> input
    input --> stt["WhisperKit transcription"]
    stt --> flow["Relay app flow"]
    flow -->|"Optional translation requests"| translate["Apple Translation"]
    translate --> flow
    flow --> overlay["Overlay UI"]

Loading

---

Key features

• Live transcription from microphone input, system audio, or both at the same time.
• Live translation of transcript segments into the selected target language.
• A persistent overlay window for transcript and translation output.
• Menu bar controls for quick source toggles and troubleshooting actions.
• Local diagnostics export for support and release validation.

---

Requirements

• macOS 26 or newer.
• Xcode with support for the current project format and macOS 26 SDK.
• Homebrew for installing local development tools.
• Ruby and Bundler for coverage tooling.

---

Installation

1. Install development dependencies: brew bundle install && bundle install.
2. Open Relay.xcodeproj in Xcode.
3. Build and run the Relay scheme.
4. Grant microphone access when macOS prompts for it.
5. If you want translation, make sure the required Apple Translation language resources are installed on the machine.

---

Limitations

• Relay currently targets macOS 26 or newer.
• Translation depends on Apple Translation support on the current Mac and on the installed language resources for the selected language pair.
• Speech-to-text depends on WhisperKit being included in the build and on the required model being available locally.
• Microphone transcription requires microphone permission.
• System audio capture depends on macOS runtime support, device availability, and successful audio tap startup.

---

Troubleshooting

• No microphone transcript:
  Check the macOS microphone permission settings and make sure Relay is allowed to access the microphone.
• No translation output:
  Confirm that Apple Translation is available on the Mac and that the selected language pair is supported and the required resources are installed.
• System audio is unavailable:
  Retry listening, then check audio device availability and whether macOS supports system audio capture on the current machine.
• WhisperKit is unavailable or speech recognition does not start:
  Rebuild Relay with WhisperKit package support. On first use, start listening with network access so the speech model can be downloaded if needed.
• A transient error keeps repeating:
  Stop and restart listening. If the problem continues, export diagnostics from the Troubleshooting menu and inspect or share the ZIP file.

---

Project structure

• Relay/App: app lifecycle, session state, diagnostic actions, and menu bar integration.
• Relay/Core: coordination, source supervision, and transcription and translation pipelines.
• Relay/Presentation: snapshot-to-UI mapping and UI projection.
• Relay/Services: audio capture, speech-to-text, translation, and permissions.
• Relay/UI and Relay/Window: overlay presentation and window management.
• Relay/Models: domain and pipeline models.
• Relay/Utilities: diagnostic storage/export, task supervision, and supporting utilities.
• RelayTests: unit and behavior tests for app, core, services, and UI logic.

---

Development

Validation

• Run all configured pre-commit checks for all files: make check
• Run Xcode static analysis: make analyze

Tests

• Run tests: make test
• Run tests with coverage checks: make test-coverage

To run tests without benchmarks, set RUN_BENCHMARKS=false.

Release

• Build unsigned release artifacts: ./scripts/build_release_unsigned.sh
• Start the release process: make release V=1.0.2

---

Diagnostics support flow

Relay stores local diagnostics under:

~/Library/Application Support/Relay/Diagnostics

Use the Relay menu bar:

Troubleshooting -> Export diagnostics

Export behavior:

• Default export path: ~/Downloads/Relay-support-YYYYMMDD-HHMMSS.zip
• If a file with that name already exists, Relay appends -1, -2, and so on to the filename.
• Diagnostics retention keeps up to 14 days and caps total diagnostics storage at 200 MB.
• Export includes recent Relay logs and recent matching Relay crash reports.
• Transcript and translation text are excluded by default.
• Full transcript and translation text are included only when the Include transcript and translation text checkbox is explicitly enabled.

If you need help from a maintainer, please:

1. Reproduce the issue.
2. Export diagnostics from the Troubleshooting menu.
3. Share the generated ZIP file and include clear reproduction steps.

---

Release docs

• Release checklist: RELEASE_CHECKLIST.md