readback 0.0.0-alpha.4 → 0.0.0-alpha.6

package/README.md

@@ -1,28 +1,42 @@
-# 🎧 readback
+```
+█▀▄ █▀▀ █▀█ █▀▄ █▀▄ █▀█ █▀▀ █ █ 
+█▀▄ █▀▀ █▀█ █ █ █▀▄ █▀█ █   █▀▄ 
+█ █ █   █ █ █ █ █ █ █ █ █   █ █ 
+▀ ▀ ▀▀▀ ▀ ▀ ▀▀  ▀▀  ▀ ▀ ▀▀▀ ▀ ▀
+```
 
 **readback** is a real-time ATC (Air Traffic Control) transcription tool that captures system audio, transcribes it using local ATC-fine-tuned [Whisper](https://en.wikipedia.org/wiki/Whisper_(speech_recognition_system)) models, and formats the output with aviation-specific syntax highlighting. Useful for flight simmers on [VATSIM](https://vatsim.net) and [IVAO](https://www.ivao.aero) networks who (like me) struggle with following ATC communications.
 
-## ⚠️ Disclaimer
+> **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.
+
+## Installation
+
+### Step 1: Build tools (only if prebuilt binaries are unavailable)
+
+Most users won’t need this. It’s only required if npm can’t find a compatible prebuilt binary for a native dependency (e.g. `smart-whisper`, `native-recorder-nodejs`) and falls back to building from source.
+
+**macOS**: `xcode-select --install`
 
-**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.
+**Windows**: Install Visual Studio Build Tools with the C++ workload (MSVC).
 
-## 🚀 Installation
+**Linux (Debian/Ubuntu)**: `sudo apt-get install build-essential python3`
 
-### Step 1: Install build tools for native modules:
+### Step 2 (Linux only): System audio capture tools
 
-**macOS**: Install Xcode Command Line Tools with `xcode-select --install`
+On Linux, readback captures system audio by spawning either PipeWire (`pw-cat`) or PulseAudio (`parec`).
 
-**Windows**: Install Visual Studio Build Tools with C++ workload from visualstudio.microsoft.com
+Install one of the following:
 
-**Linux**: Install build essentials with `sudo apt-get install build-essential cmake` (Debian/Ubuntu) or equivalent for your distribution
+- PipeWire: `sudo apt install pipewire-bin` (provides `pw-cat`)
+- PulseAudio: `sudo apt install pulseaudio-utils` (provides `parec`)
 
-### Step 2: Install Node.js
+### Step 3: Install Node.js
 
-You need Node.js version 22.18.0 or higher installed on your system:
+You need Node.js version 22 or higher installed on your system:
 
-1. **Download Node.js**: Go to https://nodejs.org/en/download/ and download the **LTS version** (Long Term Support)
-2. **Install**: Run the downloaded installer
-3. **Verify**: Open Terminal, type `node --version` and hit the enter key (you should see something like `v24.x.x`)
+3.1. **Download Node.js**: Go to https://nodejs.org/en/download/ and download the **LTS version** (Long Term Support)
+3.2. **Install**: Run the downloaded installer
+3.3. **Verify**: Open Terminal, type `node --version` and hit the enter key (you should see something like `v24.x.x`)
 
 ### Step 3: Install readback globally
 
@@ -34,32 +48,40 @@ npm install -g readback
 
 This installs readback globally so you can run it from anywhere.
 
+If the instal fails with node-gyp errors, install Step 1 tools and retry.
+
 ---
 
-## 🎮 Usage
+## Usage
 
 In your terminal, run:
 ```bash
 readback
 ```
 
-The first time you run readback, it will check if a model exists in `~/.readback/models` and ask you to download a Whisper model (Medium ~1.5GB or Large ~3GB). Models are stored in `~/.readback/models`.
+### 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
 
-> 💡I recommend using **medium** since it's faster and the quality difference to large is negligible.
- 
-You can bring your own model too:
+To list all available options run:
 
 ```bash
-MODEL_PATH=~/path/to/your-model-ggml.bin readback
+readback --help
 ```
 
 ### Exiting
 
-Press `Ctrl+C`
+Press <kbd>Ctrl</kbd> + <kbd>C</kbd>
 
 ---
 
-## ⬆️️ Updating
+## Updating
 
 Open Terminal and run:
 
@@ -69,36 +91,36 @@ npm update -g readback
 
 ---
 
-## 🗑️ Uninstalling
+## Uninstalling
 
 ### Uninstall npm package
 
 Open Terminal and run:
 
 ```bash
-npm uninstall -g readback
+readback --purge && npm uninstall -g readback
 ```
 
-Delete the `.readback` folder in your home directory.
+This will first delete the `.readback` folder in your home directory and then uninstall the globally installed npm module.
 
 ---
 
-## 📝 License
+## License
 
 MIT License - See repository for details
 
 ---
 
-## 🙏 Credits
+## Credits
 
-This project would not be possible without the ATC-fine-tuned models provided by [Jack Tol](https://huggingface.co/jacktol).
+This project would not be possible without the ATC-fine-tuned Whisper models provided by [Jack Tol](https://huggingface.co/jacktol).
 
 ---
 
-## 🐛 Issues and contributions
+## Issues and contributions
 
 Found a bug or want to add features? Submit issues or pull requests on the [GitHub repository](https://github.com/borisdiakur/readback).
 
 ---
 
-**👋🏻 Happy flying!**
+Happy flying!

package/dist/bin/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import "../src/banner.js";
+import { Command } from "commander";
+import { styleText } from "node:util";
+import { ensureAllModels, purgeData } from "../src/setup-manager.js";
+import { cleanTranscript } from "../src/cleaner.js";
+import { startCapture } from "../src/capture.js";
+import { startupCleanup } from "../src/startup-cleanup.js";
+import packageJson from "../package.json" with { type: "json" };
+import { BottomStatusLine } from "../src/status-line.js";
+import { printTranscript } from "../src/presentation/renderer.js";
+await startupCleanup();
+const program = new Command();
+program
+    .version(packageJson.version)
+    .description(`${packageJson.name}\n${packageJson.description}`)
+    .option("--debug", "Enable debug output showing token stream")
+    .option("--raw", "Disable all cleaning and formatting")
+    .option("--no-altitude", "Disable altitude formatting")
+    .option("--no-callsigns", "Disable callsign detection and normalization")
+    .option("--no-colors", "Disable coloring")
+    .option("--no-fl", "Disable flight level abbreviation")
+    .option("--no-frequency", "Disable frequency formatting")
+    .option("--no-heading", "Disable heading formatting")
+    .option("--no-keywords", "Disable keyword highlighting")
+    .option("--no-numbers", "Disable number-word conversion")
+    .option("--no-phonetic", "Disable phonetic formatting")
+    .option("--no-qnh", "Disable qnh formatting")
+    .option("--no-runways", "Disable runway formatting")
+    .option("--no-speed", "Disable speed formatting")
+    .option("--no-squawk", "Disable squawk formatting")
+    .option("--no-waypoints", "Disable waypoint formatting")
+    .option("--purge", "Delete all data including downloaded models and exit")
+    .helpOption("-h, --help", "Display this help text")
+    .parse(process.argv);
+const opts = program.opts();
+if (opts.purge) {
+    purgeData();
+    process.exit(0);
+}
+let sigintSeen = false;
+process.on("SIGINT", () => {
+    if (sigintSeen)
+        return;
+    sigintSeen = true;
+    console.log("\nBye!");
+    process.exit(0);
+});
+const paths = await ensureAllModels();
+const status = new BottomStatusLine();
+startCapture(async (text) => {
+    if (opts.raw) {
+        console.log(text);
+        return;
+    }
+    const result = cleanTranscript(text, {
+        altitude: opts.altitude,
+        callsigns: opts.callsigns,
+        colors: opts.colors,
+        debug: opts.debug,
+        fl: opts.fl,
+        frequency: opts.frequency,
+        heading: opts.heading,
+        keywords: opts.keywords,
+        numbers: opts.numbers,
+        phonetic: opts.phonetic,
+        qnh: opts.qnh,
+        raw: opts.raw,
+        runways: opts.runways,
+        speed: opts.speed,
+        squawk: opts.squawk,
+        waypoints: opts.waypoints,
+    });
+    if (opts.debug) {
+        console.log("   " + styleText("dim", JSON.stringify(result.tokens)));
+    }
+    printTranscript(result.output, status);
+}, status, paths.asr);

package/dist/package.json

@@ -0,0 +1,59 @@
+{
+    "name": "readback",
+    "version": "0.0.0-alpha.6",
+    "description": "Transcribes ATC transmissions into readable text.",
+    "keywords": [
+        "ATC",
+        "aviation"
+    ],
+    "homepage": "https://github.com/borisdiakur/readback#readme",
+    "bugs": {
+        "url": "https://github.com/borisdiakur/readback/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/borisdiakur/readback.git"
+    },
+    "license": "MIT",
+    "author": "Boris Diakur (https://borisdiakur.de)",
+    "type": "module",
+    "main": "dist/bin/index.js",
+    "bin": {
+        "readback": "dist/bin/index.js"
+    },
+    "files": [
+        "dist/",
+        "models/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "start": "node ./dist/bin/index.js",
+        "start:debug": "node ./dist/bin/index.js --debug",
+        "build": "tsc",
+        "build:start": "tsc && npm start",
+        "build:watch": "tsc --watch",
+        "extractNavData": "node scripts/extract-nav-data.ts",
+        "test": "node --test tests/**/*.spec.ts",
+        "test:cover": "node --experimental-test-coverage --test tests/**/*.spec.ts"
+    },
+    "dependencies": {
+        "cli-progress": "^3.12.0",
+        "cmake-js": "^8.0.0",
+        "commander": "^14.0.3",
+        "native-recorder-nodejs": "^1.2.0",
+        "onnxruntime-node": "^1.24.1",
+        "smart-whisper": "^0.8.1",
+        "speex-resampler": "^3.0.1",
+        "wrap-ansi": "^9.0.2"
+    },
+    "devDependencies": {
+        "@types/cli-progress": "^3.11.6",
+        "@types/node": "^25.2.2",
+        "prettier": "^3.8.1",
+        "typescript": "^5.9.3"
+    },
+    "engines": {
+        "node": ">=22"
+    }
+}

package/dist/src/asr-task.js

@@ -0,0 +1,14 @@
+import { Whisper } from "smart-whisper";
+let whisper = null;
+let loadedPath = null;
+export default async function run({ audio, asrModelPath }) {
+    if (!whisper || loadedPath !== asrModelPath) {
+        whisper = new Whisper(asrModelPath, { gpu: true });
+        loadedPath = asrModelPath;
+    }
+    const audioData = new Float32Array(audio);
+    const task = await whisper.transcribe(audioData, { language: "en" });
+    const result = await task.result;
+    const text = result.map((s) => s.text.trim().toLowerCase()).join(" ");
+    return { text };
+}

package/dist/src/asr-worker.js

@@ -0,0 +1,37 @@
+import { Whisper } from "smart-whisper";
+const ASR_MODEL_PATH = process.env.ASR_MODEL_PATH;
+if (!ASR_MODEL_PATH) {
+    throw new Error("ASR_MODEL_PATH environment variable not set");
+}
+let whisper;
+async function init() {
+    try {
+        whisper = new Whisper(ASR_MODEL_PATH, { gpu: true });
+        if (process.send)
+            process.send({ ready: true });
+    }
+    catch (err) {
+        console.error(" ASR worker init failed:", err);
+        process.exit(1);
+    }
+}
+process.on("message", async (msg) => {
+    if (!msg.audio || msg.audio.length === 0)
+        return;
+    try {
+        const audioData = new Float32Array(msg.audio);
+        const task = await whisper.transcribe(audioData, {
+            language: "en",
+        });
+        const result = await task.result;
+        const text = result.map((s) => s.text.trim().toLowerCase()).join(" ");
+        if (process.send)
+            process.send({ text: text, seq: msg.seq });
+    }
+    catch (err) {
+        console.error(" ASR worker processing error:", err);
+        if (process.send)
+            process.send({ text: "", seq: msg.seq, error: String(err) });
+    }
+});
+init();

package/dist/src/bandpass.js

@@ -0,0 +1,57 @@
+export class BandpassFilter {
+    x1 = 0;
+    x2 = 0;
+    y1 = 0;
+    y2 = 0;
+    // Coefficients
+    b0 = 0;
+    b1 = 0;
+    b2 = 0;
+    a1 = 0;
+    a2 = 0;
+    constructor(sampleRate, centerFreq, q) {
+        this.recalculate(sampleRate, centerFreq, q);
+    }
+    recalculate(sampleRate, centerFreq, q) {
+        // Standard BPF (Constant Peak Gain) implementation
+        const w0 = (2 * Math.PI * centerFreq) / sampleRate;
+        const alpha = Math.sin(w0) / (2 * q);
+        const a0 = 1 + alpha;
+        this.b0 = alpha / a0;
+        this.b1 = 0;
+        this.b2 = -alpha / a0;
+        this.a1 = (-2 * Math.cos(w0)) / a0;
+        this.a2 = (1 - alpha) / a0;
+        // Reset state on recalc (optional, avoids pop)
+        this.reset();
+    }
+    reset() {
+        this.x1 = 0;
+        this.x2 = 0;
+        this.y1 = 0;
+        this.y2 = 0;
+    }
+    process(input) {
+        const output = new Float32Array(input.length);
+        // Local copy for speed
+        let { x1, x2, y1, y2 } = this;
+        const { b0, b1, b2, a1, a2 } = this;
+        for (let i = 0; i < input.length; i++) {
+            const x = input[i];
+            // Direct Form I or II (this is DFI)
+            const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+            output[i] = y;
+            // Shift
+            x2 = x1;
+            x1 = x;
+            y2 = y1;
+            y1 = y;
+        }
+        // Save state
+        this.x1 = x1;
+        this.x2 = x2;
+        this.y1 = y1;
+        this.y2 = y2;
+        return output;
+    }
+}

package/dist/src/banner.js

@@ -0,0 +1,19 @@
+import { styleText } from "node:util";
+import packageJson from "../package.json" with { type: "json" };
+const g = (t) => styleText(["dim", "white"], t);
+const w = (t) => styleText(["whiteBright"], t);
+const a = (t) => t
+    .split("")
+    .map((c, i) => i < 2 ||
+    i > t.length - 2 ||
+    i === Math.floor(t.length / 2) - 1 ||
+    i === Math.floor(t.length / 2) + 1 ||
+    (i + 1) % 2 === 0
+    ? g(c)
+    : w(c))
+    .join("");
+const v = styleText("dim", " v" + packageJson.version);
+console.log(a("█▀▄ █▀▀ █▀█ █▀▄ █▀▄ █▀█ █▀▀ █ █"));
+console.log(a("█▀▄ █▀▀ █▀█ █ █ █▀▄ █▀█ █   █▀▄"));
+console.log(a("█ █ █   █ █ █ █ █ █ █ █ █   █ █"));
+console.log(a("▀ ▀ ▀▀▀ ▀ ▀ ▀▀  ▀▀  ▀ ▀ ▀▀▀ ▀ ▀") + v);