handy-remote-server 1.0.0

package/README.md

@@ -0,0 +1,39 @@
+# Handy Remote Server 🎙️
+
+A lightweight standalone inference server for [Handy](https://github.com/cjpais/Handy), allowing you to transcribe audio from external devices, weak computers, and more.
+
+## Installation
+
+The easiest way to run the external inference server is using `npx`:
+
+```bash
+npx handy-remote-server
+```
+
+_(You must have Node.js and npm installed)_
+
+## Usage
+
+When you run the server for the first time, it will automatically download the **GigaAM v3** model (Russian-only fast architecture model) if it's not present.
+
+It will also generate a unique Bearer API Token for your active session:
+
+```bash
+Your API KEY is: xxxxx-xxxxx-xxxxx-xxxxx
+Handy Remote Server is running on port 3000
+```
+
+1. Open **Handy** on your client machine.
+2. Go to **Settings > General**, select the `Remote` engine.
+3. Provide the Server URL: `http://<your-server-ip>:3000`
+4. Provide the generated Token.
+5. All audio chunks will now be transcribed by the server!
+
+## How it works
+
+The `handy-remote-server` spins up a tiny Express server alongside a heavily optimized Rust CLI (`rust-infer`) powered by `transcribe-rs`. Audio files are dispatched sequentially from the Node server directly into the Rust engine.
+
+### Environment variables
+
+- `PORT` - defaults to `3000`
+- `API_KEY` - defaults to an auto-generated token in development. Set this to a permanent token for production.

package/dist/index.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const multer_1 = __importDefault(require("multer"));
+const child_process_1 = require("child_process");
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+const app = (0, express_1.default)();
+const port = process.env.PORT || 3000;
+// Set up API KEY
+let API_KEY = process.env.API_KEY;
+if (!API_KEY) {
+    API_KEY = crypto_1.default.randomBytes(32).toString('hex');
+    console.log(`\n======================================================`);
+    console.log(`Server started without API_KEY in environment variables.`);
+    console.log(`Generated a new token for this session.`);
+    console.log(`Your API KEY is: ${API_KEY}`);
+    console.log(`======================================================\n`);
+}
+// Ensure models directory exists
+const modelsDir = path_1.default.join(__dirname, '..', 'models');
+if (!fs_1.default.existsSync(modelsDir)) {
+    fs_1.default.mkdirSync(modelsDir, { recursive: true });
+}
+// Authentication middleware
+app.use((req, res, next) => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+        return res.status(401).json({ error: 'Missing or invalid Authorization header' });
+    }
+    const token = authHeader.split(' ')[1];
+    if (token !== API_KEY) {
+        return res.status(403).json({ error: 'Invalid API Key' });
+    }
+    next();
+});
+// Configure multer to store uploaded files in a temp directory
+const uploadDir = path_1.default.join(__dirname, '..', 'uploads');
+if (!fs_1.default.existsSync(uploadDir)) {
+    fs_1.default.mkdirSync(uploadDir, { recursive: true });
+}
+const storage = multer_1.default.diskStorage({
+    destination: function (req, file, cb) {
+        cb(null, uploadDir);
+    },
+    filename: function (req, file, cb) {
+        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
+        cb(null, file.fieldname + '-' + uniqueSuffix + '.wav');
+    }
+});
+const upload = (0, multer_1.default)({ storage: storage });
+// Model download logic
+const GIGAAM_MODEL_URL = 'https://blob.handy.computer/giga-am-v3.int8.onnx';
+const gigaamModelPath = path_1.default.join(modelsDir, 'gigaam.onnx');
+async function downloadFile(url, dest) {
+    if (fs_1.default.existsSync(dest))
+        return;
+    console.log(`Downloading ${url} to ${dest}...`);
+    fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+    const arrBuffer = await response.arrayBuffer();
+    fs_1.default.writeFileSync(dest, Buffer.from(arrBuffer));
+    console.log(`Downloaded ${dest}`);
+}
+async function ensureModels() {
+    await downloadFile(GIGAAM_MODEL_URL, gigaamModelPath);
+}
+let inferProcess = null;
+let isReady = false;
+let resolvers = {};
+ensureModels().then(() => {
+    // Spawn the rust background process
+    let inferProcessPath = process.env.INFER_CLI_PATH || path_1.default.join(__dirname, '..', 'rust-infer', 'target', 'release', 'rust-infer');
+    if (!fs_1.default.existsSync(inferProcessPath)) {
+        inferProcessPath = path_1.default.join(__dirname, '..', 'rust-infer', 'target', 'debug', 'rust-infer');
+    }
+    console.log(`Using inference CLI: ${inferProcessPath}`);
+    inferProcess = (0, child_process_1.spawn)(inferProcessPath, [gigaamModelPath], { stdio: ['pipe', 'pipe', 'inherit'] });
+    inferProcess.stdout.on('data', (data) => {
+        const lines = data.toString().split('\n').map((l) => l.trim()).filter(Boolean);
+        for (const line of lines) {
+            if (line === 'READY') {
+                isReady = true;
+                console.log('Inference worker is ready.');
+                continue;
+            }
+            try {
+                const parsed = JSON.parse(line);
+                const resolverCount = Object.keys(resolvers).length;
+                if (resolverCount > 0) {
+                    const firstKey = Object.keys(resolvers)[0];
+                    resolvers[firstKey](parsed);
+                }
+            }
+            catch (e) {
+                console.log('Got non-JSON output from worker:', line);
+            }
+        }
+    });
+    inferProcess.on('exit', (code) => {
+        console.log(`Inference worker exited with code ${code}`);
+        process.exit(code || 1);
+    });
+}).catch(e => {
+    console.error('Failed to download models:', e);
+    process.exit(1);
+});
+// Queue for pending transcriptions to send them sequentially to the single worker
+const requestQueue = [];
+let isProcessing = false;
+function processQueue() {
+    if (isProcessing || requestQueue.length === 0 || !isReady)
+        return;
+    isProcessing = true;
+    const req = requestQueue.shift();
+    // Register resolver
+    resolvers[req.file] = (result) => {
+        delete resolvers[req.file];
+        isProcessing = false;
+        // Clean up temp file
+        if (fs_1.default.existsSync(req.file)) {
+            fs_1.default.unlinkSync(req.file);
+        }
+        req.resolve(result);
+        // Process next
+        process.nextTick(processQueue);
+    };
+    // Send path to worker via stdin
+    inferProcess.stdin.write(req.file + '\n');
+}
+// The route
+app.post('/transcribe', express_1.default.raw({ type: 'audio/wav', limit: '50mb' }), async (req, res) => {
+    if (!isReady) {
+        return res.status(503).json({ error: 'Models are still loading' });
+    }
+    // If using express.raw, the body is a Buffer
+    if (!req.body || !Buffer.isBuffer(req.body)) {
+        return res.status(400).json({ error: 'Invalid audio body. Send raw WAV bytes with Content-Type: audio/wav' });
+    }
+    const tempFilePath = path_1.default.join(uploadDir, `upload-${Date.now()}-${Math.random().toString(36).substring(7)}.wav`);
+    fs_1.default.writeFileSync(tempFilePath, req.body);
+    const result = await new Promise((resolve) => {
+        requestQueue.push({ file: tempFilePath, resolve });
+        processQueue();
+    });
+    res.json(result);
+});
+app.listen(port, () => {
+    console.log(`Handy Remote Server is running on port ${port}`);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "handy-remote-server",
+  "version": "1.0.0",
+  "description": "Remote Transcription Server for Handy",
+  "main": "dist/index.js",
+  "bin": {
+    "handy-remote-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "ts-node src/index.ts",
+    "postinstall": "cd rust-infer && cargo build --release"
+  },
+  "files": [
+    "dist",
+    "rust-infer/Cargo.toml",
+    "rust-infer/src"
+  ],
+  "keywords": [
+    "handy",
+    "transcription",
+    "stt",
+    "remote",
+    "server"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "dependencies": {
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "multer": "^2.1.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/multer": "^2.1.0",
+    "@types/node": "^25.3.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/rust-infer/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "rust-infer"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+hound = "3.5.1"
+serde_json = "1.0.149"
+transcribe-rs = { version = "0.2.8", features = ["whisper", "parakeet", "moonshine", "sense_voice", "gigaam"] }

package/rust-infer/src/main.rs

@@ -0,0 +1,121 @@
+use std::io::{self, BufRead, Write};
+use std::path::PathBuf;
+use transcribe_rs::{engines::gigaam::GigaAMEngine, TranscriptionEngine};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // We get model and config path from args or default
+    let args: Vec<String> = std::env::args().collect();
+    
+    let model_path = if args.len() > 1 {
+        args[1].clone()
+    } else {
+        let mut d = std::env::current_dir()?;
+        d.push("models");
+        d.push("gigaam.onnx");
+        d.to_string_lossy().to_string()
+    };
+    
+    // Auto-download logic or print error if missing
+    if !PathBuf::from(&model_path).exists() {
+        eprintln!("Model file not found: {}. Please ensure model file exists.", model_path);
+        std::process::exit(1);
+    }
+    
+    eprintln!("Loading GigaAM model from {}...", model_path);
+    
+    let mut engine = GigaAMEngine::new();
+    engine.load_model(std::path::Path::new(&model_path)).map_err(|e| format!("Failed to load GigaAM model: {}", e))?;
+    
+    eprintln!("Model loaded. Ready to transcribe.");
+    println!("READY"); // Signal to Node.js that we are ready
+    io::stdout().flush()?;
+    
+    let stdin = io::stdin();
+    for line in stdin.lock().lines() {
+        let line = line?;
+        let line = line.trim();
+        if line.is_empty() {
+            continue;
+        }
+        
+        if line == "EXIT" {
+            break;
+        }
+        
+        // Line format: "file_path"
+        let wav_path = line;
+        
+        // Read the file and convert to f32
+        match read_wav(wav_path) {
+            Ok(samples) => {
+                match engine.transcribe_samples(samples, None) {
+                    Ok(result) => {
+                        let json = serde_json::json!({
+                            "status": "success",
+                            "text": result.text
+                        });
+                        println!("{}", json.to_string());
+                    },
+                    Err(e) => {
+                        let json = serde_json::json!({
+                            "status": "error",
+                            "error": format!("Transcription failed: {}", e)
+                        });
+                        println!("{}", json.to_string());
+                    }
+                }
+            },
+            Err(e) => {
+                let json = serde_json::json!({
+                    "status": "error",
+                    "error": format!("Failed to read WAV: {}", e)
+                });
+                println!("{}", json.to_string());
+            }
+        }
+        io::stdout().flush()?;
+    }
+    
+    Ok(())
+}
+
+fn read_wav(path: &str) -> Result<Vec<f32>, Box<dyn std::error::Error>> {
+    let mut reader = hound::WavReader::open(path)?;
+    let spec = reader.spec();
+    
+    let mut samples = Vec::new();
+    match spec.sample_format {
+        hound::SampleFormat::Int => {
+            if spec.bits_per_sample == 16 {
+                for sample in reader.samples::<i16>() {
+                    let s = sample? as f32 / i16::MAX as f32;
+                    samples.push(s);
+                }
+            } else {
+                return Err("Only 16-bit integer WAV is supported".into());
+            }
+        },
+        hound::SampleFormat::Float => {
+            if spec.bits_per_sample == 32 {
+                for sample in reader.samples::<f32>() {
+                    samples.push(sample?);
+                }
+            } else {
+                return Err("Only 32-bit float WAV is supported".into());
+            }
+        }
+    }
+    
+    // Multi-channel to mono (simple average)
+    if spec.channels > 1 {
+        let channels = spec.channels as usize;
+        let mut mono = Vec::with_capacity(samples.len() / channels);
+        for chunk in samples.chunks(channels) {
+            let sum: f32 = chunk.iter().sum();
+            mono.push(sum / channels as f32);
+        }
+        samples = mono;
+    }
+    
+    Ok(samples)
+}