whisper-api 0.1.0

package/NOTICE

@@ -0,0 +1,22 @@
+whisper-api
+Copyright (C) 2026 Alexey Abramov
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version. See the LICENSE file for the full text.
+
+This product bundles or depends on third-party software:
+
+- whisper.cpp (https://github.com/ggml-org/whisper.cpp) — MIT License.
+  Built/invoked at runtime for the native transcription engine.
+- Whisper models (OpenAI) — distributed under the MIT License; GGML conversions
+  hosted at https://huggingface.co/ggerganov/whisper.cpp.
+- @huggingface/transformers / transformers.js — Apache-2.0 License.
+- onnxruntime-node — MIT License.
+- ffmpeg-static (bundled FFmpeg binaries) — FFmpeg is licensed under LGPL/GPL;
+  see https://github.com/eugeneware/ffmpeg-static for build details.
+- fastify and @fastify/* plugins — MIT License.
+
+The names "Whisper" and "OpenAI" are used only to describe API compatibility.
+This project is not affiliated with or endorsed by OpenAI.

package/README.md

@@ -0,0 +1,163 @@
+# whisper-api
+
+[![CI](https://github.com/alexey-a-abramov/whisper-api/actions/workflows/ci.yml/badge.svg)](https://github.com/alexey-a-abramov/whisper-api/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/alexey-a-abramov/whisper-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/alexey-a-abramov/whisper-api/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/alexey-a-abramov/whisper-api/badge)](https://scorecard.dev/viewer/?uri=github.com/alexey-a-abramov/whisper-api)
+[![npm version](https://img.shields.io/npm/v/whisper-api.svg)](https://www.npmjs.com/package/whisper-api)
+[![npm downloads](https://img.shields.io/npm/dm/whisper-api.svg)](https://www.npmjs.com/package/whisper-api)
+[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/node/v/whisper-api.svg)](https://nodejs.org)
+
+**Self-hostable, OpenAI-compatible Whisper speech-to-text endpoint you can stand up on any machine with one command.**
+
+It speaks the exact same HTTP API as OpenAI's `POST /v1/audio/transcriptions`, so any tool, SDK, or app that talks to OpenAI Whisper can point at *your* server instead — your audio never leaves your box. Transcription runs locally via [whisper.cpp](https://github.com/ggml-org/whisper.cpp) (fast, GPU-capable) or a pure-JavaScript ONNX engine ([transformers.js](https://github.com/huggingface/transformers.js)) that needs no compiler.
+
+```bash
+npx whisper-api init     # pick models, download them, mint an API key
+npx whisper-api start    # serve the OpenAI-compatible endpoint
+```
+
+---
+
+## Features
+
+- 🔌 **Drop-in OpenAI compatibility** — `/v1/audio/transcriptions`, `/v1/audio/translations`, `/v1/models`. Repoint any OpenAI client's `base_url` and it just works.
+- 🧠 **Dual engine, auto-detected** — native **whisper.cpp** (CPU + NVIDIA CUDA / Apple Metal, up to `large-v3`) when available, transparent fallback to the portable **ONNX** engine so `npx` works on a bare VPS with no build tools.
+- 🔑 **API key management** — generate, list, and revoke bearer keys. Only salted SHA-256 hashes are stored; raw keys are shown once.
+- 🚦 **Per-key rate limiting** and configurable upload size limits.
+- 📦 **Background model downloads** with progress, from tiny (75 MB) to large-v3 (3.1 GB).
+- 🩺 **`/health` endpoint** and a minimal **web status page** at `/`.
+- 🚀 **Turnkey deployment** — Dockerfile, docker-compose, systemd unit, and an nginx/Caddy TLS reverse-proxy sample.
+
+## Requirements
+
+- **Node.js ≥ 20**.
+- That's it for the ONNX engine. For the native **whisper.cpp** engine you also need `git`, `cmake`, and a C/C++ compiler (or a prebuilt `whisper-cli` binary pointed to by `WHISPER_CPP_BIN`). FFmpeg is bundled via `ffmpeg-static` — nothing to install.
+
+## Quick start
+
+```bash
+# 1. Interactive setup — choose engine, select & download models, create your first key
+npx whisper-api init
+
+# 2. Start the server (defaults to 0.0.0.0:8080)
+npx whisper-api start
+
+# 3. From any other machine / app:
+curl http://YOUR_SERVER:8080/v1/audio/transcriptions \
+  -H "Authorization: Bearer sk-wapi-..." \
+  -F file=@audio.m4a \
+  -F model=whisper-1
+```
+
+## Using it from a third-party app
+
+Anything that supports the OpenAI API works — just change the base URL and key.
+
+**Python (official `openai` SDK):**
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="https://transcribe.example.com/v1", api_key="sk-wapi-...")
+with open("meeting.m4a", "rb") as f:
+    print(client.audio.transcriptions.create(model="whisper-1", file=f).text)
+```
+
+**Node (official `openai` SDK):**
+
+```js
+import OpenAI from "openai";
+import fs from "node:fs";
+
+const client = new OpenAI({ baseURL: "https://transcribe.example.com/v1", apiKey: "sk-wapi-..." });
+const out = await client.audio.transcriptions.create({
+  model: "whisper-1",
+  file: fs.createReadStream("meeting.m4a"),
+});
+console.log(out.text);
+```
+
+**Other OpenAI-compatible apps** (Open WebUI, n8n, LibreChat, Raycast, …): set **Base URL** to `https://your-server/v1` and **API key** to a key from `whisper-api key generate`.
+
+## CLI
+
+| Command | Description |
+| --- | --- |
+| `whisper-api init` | Interactive setup: engine, models, first API key. |
+| `whisper-api start [-p 8080] [--host 0.0.0.0] [-m base.en] [-e auto]` | Start the API server. |
+| `whisper-api models list` | List available and installed models. |
+| `whisper-api models pull <name>` | Download a model (e.g. `large-v3`). |
+| `whisper-api models rm <name>` | Remove a downloaded GGML model. |
+| `whisper-api key generate [-n name]` | Mint a new API key (shown once). |
+| `whisper-api key list` | List keys with status and last use. |
+| `whisper-api key revoke <id\|prefix>` | Revoke a key. |
+| `whisper-api status` | Show config, installed models, and key count. |
+| `whisper-api build-engine` | Build whisper.cpp from source for native speed. |
+
+### Models
+
+`tiny`, `base`, `small`, `medium` (and `.en` English-only variants), `large-v3-turbo`, `large-v3`. The OpenAI alias **`whisper-1`** maps to your configured default model.
+
+## HTTP API
+
+All `/v1/*` routes require `Authorization: Bearer <key>`. `/health` and `/` are public.
+
+### `POST /v1/audio/transcriptions`
+`multipart/form-data`:
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `file` | ✅ | Audio/video file (any format FFmpeg can read). |
+| `model` | | Model name or `whisper-1`. Defaults to your configured model. |
+| `language` | | ISO-639-1 hint, e.g. `en`. |
+| `response_format` | | `json` (default), `verbose_json`, `text`, `srt`, `vtt`. |
+| `temperature` | | Sampling temperature. |
+| `prompt` | | Decoding/vocabulary hint. |
+
+`json` → `{ "text": "..." }`. `verbose_json` adds `language`, `duration`, and `segments[]`.
+
+### `POST /v1/audio/translations`
+Same fields; transcribes **and translates to English**.
+
+### `GET /v1/models`
+OpenAI-shaped model list. ・ **`GET /health`** → `{ status, engine, model, activeKeys, uptime, version }`.
+
+## Configuration
+
+State lives in `~/.whisper-api/` (override with `WHISPER_API_HOME`): `config.json`, `keys.json`, `models/` (GGML), `cache/` (ONNX weights), `bin/` (built whisper.cpp). Any setting can be overridden by environment variables — see [`.env.example`](.env.example).
+
+## Deployment
+
+**Docker:**
+
+```bash
+docker compose up -d --build
+docker compose exec whisper-api node bin/whisper-api.js key generate
+curl localhost:8080/health
+```
+
+**systemd + nginx:** see [`deploy/whisper-api.service`](deploy/whisper-api.service) and [`deploy/nginx.conf`](deploy/nginx.conf) (includes a Caddy alternative). Run behind TLS; audio uploads can be large, so the samples raise `client_max_body_size` and proxy timeouts.
+
+## Security
+
+- Keys are random 256-bit secrets prefixed `sk-wapi-`; only their SHA-256 hashes are stored (`keys.json`, mode `600`). Compared in constant time.
+- Bind to `127.0.0.1` and terminate TLS at a reverse proxy for public deployments.
+- Per-key rate limiting (`WHISPER_API_RATE_MAX`, default 120/min) and a 25 MB upload cap by default.
+- This repo runs **CodeQL** code scanning, **OpenSSF Scorecard**, and **Dependabot**. To report a vulnerability privately, see [`SECURITY.md`](SECURITY.md).
+
+## Development
+
+```bash
+npm install
+npm run dev -- init      # run the CLI from source via tsx
+npm run typecheck
+npm test
+npm run build            # bundle to dist/ with tsup
+```
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the contribution workflow and coding conventions.
+
+## License
+
+[AGPL-3.0-or-later](LICENSE). If you run a modified version as a network service, the AGPL requires you to offer your users the corresponding source. See [`NOTICE`](NOTICE) for third-party attributions. "Whisper" and "OpenAI" are referenced only to describe API compatibility; this project is not affiliated with OpenAI.

package/bin/whisper-api.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// whisper-api CLI entrypoint. Thin shim that loads the bundled program.
+import "../dist/whisper-api.js";

package/deploy/nginx.conf

@@ -0,0 +1,33 @@
+# Reverse proxy + TLS termination for whisper-api.
+# Pair with certbot for Let's Encrypt certificates.
+#
+#   sudo cp deploy/nginx.conf /etc/nginx/sites-available/whisper-api
+#   sudo ln -s /etc/nginx/sites-available/whisper-api /etc/nginx/sites-enabled/
+#   sudo certbot --nginx -d transcribe.example.com
+#   sudo nginx -t && sudo systemctl reload nginx
+
+server {
+    listen 80;
+    server_name transcribe.example.com;
+    # certbot inserts the HTTPS server block and the 80->443 redirect.
+    location / {
+        proxy_pass         http://127.0.0.1:8080;
+        proxy_http_version 1.1;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+
+        # Audio uploads can be large; raise limits and timeouts.
+        client_max_body_size 200m;
+        proxy_read_timeout   600s;
+        proxy_send_timeout   600s;
+        proxy_request_buffering off;
+    }
+}
+
+# --- Caddy alternative (Caddyfile) -------------------------------------------
+# transcribe.example.com {
+#     reverse_proxy 127.0.0.1:8080
+#     request_body { max_size 200MB }
+# }

package/deploy/whisper-api.service

@@ -0,0 +1,31 @@
+# systemd unit for whisper-api.
+# Install:
+#   sudo cp deploy/whisper-api.service /etc/systemd/system/
+#   sudo useradd --system --home /var/lib/whisper-api --create-home whisper || true
+#   sudo -u whisper npx whisper-api@latest init       # one-time setup as the service user
+#   sudo systemctl daemon-reload && sudo systemctl enable --now whisper-api
+[Unit]
+Description=whisper-api (self-hosted OpenAI-compatible Whisper endpoint)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=whisper
+Group=whisper
+Environment=WHISPER_API_HOME=/var/lib/whisper-api
+Environment=WHISPER_API_HOST=127.0.0.1
+Environment=WHISPER_API_PORT=8080
+# Pin a version for reproducible deploys; npx caches it after first run.
+ExecStart=/usr/bin/npx --yes whisper-api@latest start
+Restart=on-failure
+RestartSec=3
+# Hardening
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/whisper-api
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target