whisper_web/CLAUDE.md

CLAUDE.md — Read this first, every session

This is the single source of truth for any agent working in this repo. If anything you're told conflicts with this file, this file wins.

1. What we are building

A browser-first speech-to-text web app powered by OpenAI Whisper, running through Transformers.js (@huggingface/transformers).

Anonymous users (no login) can:

• Run Whisper models fully in the browser (no data leaves the device).
• Choose which Whisper model to use (tiny → large, English-only and multilingual, quantized variants).
• Keep working when the network — or our own server — is offline (installable PWA + cached model weights).
• Accelerate inference with WebGPU, falling back to WASM automatically.
• Transcribe from an uploaded audio/video file.

Logged-in users (Passport.js) get all of the above, plus:

• A toggle to choose where inference runs: their own device (browser engine) or the server the app is deployed on (server engine).
• The server engine MUST use faster-whisper (CTranslate2) for inference — not Transformers.js (see Decisions.md D-013). faster-whisper cannot run in a browser (no WASM build of CTranslate2), so the browser engine stays on Transformers.js.

2 How to run things

Default to using Bun instead of Node.js.

• Use bun <file> instead of node <file> or ts-node <file>
• Use bun test instead of jest or vitest
• Use bun build <file.html|file.ts|file.css> instead of webpack or esbuild
• Use bun install instead of npm install or yarn install or pnpm install
• Use bun run <script> instead of npm run <script> or yarn run <script> or pnpm run <script>
• Use bunx <package> <command> instead of npx <package> <command>
• Bun automatically loads .env, so don't use dotenv.

APIs

• Bun.serve() supports WebSockets, HTTPS, and routes. Don't use express.
• bun:sqlite for SQLite. Don't use better-sqlite3.
• Bun.redis for Redis. Don't use ioredis.
• Bun.sql for Postgres. Don't use pg or postgres.js.
• WebSocket is built-in. Don't use ws.
• Prefer Bun.file over node:fs's readFile/writeFile
• Bun.$ls instead of execa.

Testing

Use bun test to run tests.

import { test, expect } from "bun:test";

test("hello world", () => {
  expect(1).toBe(1);
});

Frontend

Use HTML imports with Bun.serve(). Don't use vite. HTML imports fully support React, CSS, Tailwind.

Server:

import index from "./index.html"

Bun.serve({
  routes: {
    "/": index,
    "/api/users/:id": {
      GET: (req) => {
        return new Response(JSON.stringify({ id: req.params.id }));
      },
    },
  },
  // optional websocket support
  websocket: {
    open: (ws) => {
      ws.send("Hello, world!");
    },
    message: (ws, message) => {
      ws.send(message);
    },
    close: (ws) => {
      // handle close
    }
  },
  development: {
    hmr: true,
    console: true,
  }
})

HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. <link> tags can point to stylesheets and Bun's CSS bundler will bundle.

<html>
  <body>
    <h1>Hello, world!</h1>
    <script type="module" src="./frontend.tsx"></script>
  </body>
</html>

With the following frontend.tsx:

import React from "react";
import { createRoot } from "react-dom/client";

// import .css files directly and it works
import './index.css';

const root = createRoot(document.body);

export default function Frontend() {
  return <h1>Hello, world!</h1>;
}

root.render(<Frontend />);

Then, run index.ts

bun --hot ./index.ts

For more information, read the Bun API docs in node_modules/bun-types/docs/**.mdx.