◣               █▀▄ █▀▀ █▀█ █▀▄ █▀▄ █▀█ █▀▀ █ █
       █◣         ║┇   █ █ █   █ █ █ █ █ █ █ █ █   █ █
  ◣    ██◣❚       ║┇   █ █ █   █ █ █ █ █ █ █ █ █   █ █
━╸█►◄█████████ ◗╺━║┇━━ █▀▄ █▀▀ █▀█ █ █ █▀▄ █▀█ █   █▀▄
  ◤    ██◤❚       ║┇   █ █ █   █ █ █ █ █ █ █ █ █   █ █
       █◤         ║┇   █ █ █   █ █ █ █ █ █ █ █ █   █ █
       ◤               ▀ ▀ ▀▀▀ ▀ ▀ ▀▀  ▀▀  ▀ ▀ ▀▀▀ ▀ ▀
                       • • • • • • • • • • • • • • • •

readback is a real-time ATC (Air Traffic Control) transcription tool that captures system audio, transcribes it using local ATC-fine-tuned Whisper models, and formats the output with aviation-specific syntax highlighting. Useful for flight simmers on VATSIM and IVAO networks who (like me) struggle with following ATC communications.

Disclaimer: Transcription is far from perfect. The AI will make mistakes with fast speech, accents, background noise, and similar-sounding words. Always verify critical information (altitudes, headings, frequencies) and ask ATC to repeat if unsure. Never use for real-world aviation.

Demo

https://github.com/user-attachments/assets/ed01c017-d08e-44b2-9b5f-d2fce4dc9e95

System requirements

• macOS: Works on Apple Silicon (M1/M2/M3). Intel Macs may work if they have a dedicated AMD GPU, but no guarantees.
• Windows / Linux: A dedicated GPU (NVIDIA CUDA or Vulkan-compatible) is strongly recommended. AMD graphics card may work too, or not.

While I’ve done my best to ensure readback works across macOS, Linux, and Windows, I don’t have a lab full of different devices to test every possible hardware combination. If you run into audio capture issues or find ways to improve performance on specific platforms, please feel free to open an issue or submit a pull request. I’d love to improve cross-platform support with the help of the community.

Installation

Step 1: Platform prerequisites

These are required to run readback and/or to build native addons when no prebuilt binary is available.

macOS: xcode-select --install

Windows: Install Visual Studio Build Tools with the C++ workload (MSVC).

Linux (system-output capture): install one of:

• PipeWire: sudo apt install pipewire-bin (provides pw-cat)
• PulseAudio: sudo apt install pulseaudio-utils (provides parec)

Linux (only if native addons must compile): sudo apt-get update && sudo apt-get install -y cmake build-essential python3

Step 2: Install Node.js

You need Node.js version 22 or higher. Install the version labeled LTS from: https://nodejs.org/en/download/ (or use a Node version manager)

Verify: node --version (should be v22.x.x or newer)

Step 3: Install readback globally

npm install -g readback

If the instal fails with native build / node-gyp errors, install the build tools above and retry.

Usage

In your terminal, run:

readback

First time run

The first time you run readback, it will check if necessary models exist on your machine and guide you through the download process. Models are stored in ~/.readback/models.

After all models are installed, readback will attempt to capture your system audio. This may trigger an operating system security prompt asking for microphone or audio recording permissions.

Please grant this permission. Although readback listens to output (what you hear), operating systems often classify this as "Microphone" or "Screen Recording" access. Once granted, you may need to restart your terminal or the application.

Options

To list all available options run:

readback --help

Exiting

Press Ctrl + C

Updating

Open Terminal and run:

npm update -g readback

Uninstalling

Uninstall npm package

Open Terminal and run:

readback --purge && npm uninstall -g readback

This will first delete the .readback folder in your home directory and then uninstall the globally installed npm module.

License

MIT License - See repository for details

Credits

This project would not be possible without the ATC-fine-tuned Whisper models provided by Jack Tol.

Issues and contributions

Found a bug or want to add features? Submit issues or pull requests on the GitHub repository.

Reporting issues

When filing a bug, please attach your session log from:

~/.readback/logs/

Happy flying!