Key Design Decisions

API Reference

useTranscriber() — src/useTranscriber.ts

The primary hook that manages the full transcription lifecycle. The Whisper model is loaded lazily on the first transcribe() call and reused for all subsequent calls.

Returns TranscriberState:

TranscriberStatus values:

ModelProgressEvent interface (internal — emitted by @xenova/transformers):

Example:

const { status, progress, progressLabel, transcript, error, transcribe, reset } =
  useTranscriber();

<input
  type="file"
  accept="audio/*"
  onChange={(e) => transcribe(e.target.files![0])}
/>

{status === "loading-model" && <p>{progressLabel} ({progress}%)</p>}
{status === "transcribing"  && <p>{progressLabel}</p>}
{status === "done"          && <p>{transcript}</p>}
{status === "error"         && <p className="text-red-500">{error}</p>}

<button onClick={reset}>Reset</button>

uploadPdfToBackend() — src/api/transcriptApi.ts

Optional helper for uploading a PDF blob to a backend endpoint. Not used in the default in-browser flow.

uploadPdfToBackend(
  baseUrl: string,
  pdfBlob: Blob,
  filename: string
): Promise<UploadResult>

Interfaces:

/** Successful upload — server returned a PDF or acknowledged with JSON. */
interface UploadSuccess {
  ok: true;
  blob: Blob;   // Server's response PDF, or the original blob as fallback
}

/** Failed upload — network error, non-2xx status, or retries exhausted. */
interface UploadFailure {
  ok: false;
  error: string; // Human-readable failure reason
}

/** Discriminated union — narrow with `if (result.ok)` before accessing `result.blob`. */
type UploadResult = UploadSuccess | UploadFailure;

Returns UploadResult — never throws; all errors are captured in { ok: false, error }.

Retries up to 3 times with a 2-second delay on network errors or 503 responses (cold-start friendly).

Example:

const result = await uploadPdfToBackend(
  import.meta.env.VITE_API_BASE_URL,
  myBlob,
  "transcript.pdf"
);

if (result.ok) {
  const url = URL.createObjectURL(result.blob);
  window.open(url);
} else {
  console.error("Upload failed:", result.error);
}

Internal helpers — src/useTranscriber.ts

These are not exported but are documented here for contributors.

withTimeout<T>(promise, ms, message)

Races a promise against a deadline. Rejects with message if ms elapses first. Used to guard both model loading and transcription against indefinite hangs.

normalizeResult(result)

Normalises the heterogeneous output shapes from @xenova/transformers (plain string, { text } object, or array of segment objects) into a single trimmed string.

friendlyError(err)

Maps raw error messages to concise user-facing strings. Recognises timeout, network, out-of-memory, and codec failure patterns.

decodeAudioFileTo16kMono(file)

Decodes any browser-supported audio file to a 16 kHz mono Float32Array via the Web Audio API. Internally calls downmixToMono() and resampleLinear(), then rejects silent audio early.

downmixToMono(channels)

Averages an array of per-channel PCM buffers into a single mono buffer. Returns the input unchanged when only one channel is present.

resampleLinear(input, sourceRate, targetRate)

Linear-interpolation resampler. Converts PCM from any source rate to targetRate. Returns the input unchanged when rates are equal.

Environment Variables

Browser Compatibility

Note: The app requires AudioContext and WebAssembly support. Both are available in all modern browsers.

License

MIT

Backend

Transcript PDF API

A lightweight Express + TypeScript backend that accepts a base64-encoded PDF and streams it back as a downloadable file attachment.

Architecture

src/index.ts          ← single entry point; no routing modules needed at this scale

The server is intentionally flat — no database, no auth, no middleware layers beyond what is necessary:

1. Express handles HTTP parsing and routing.
2. CORS is enabled globally so any frontend origin can call the API.
3. express.json({ limit: '50mb' }) allows large base64 payloads (a 30 MB PDF encodes to ~40 MB of base64).
4. The single POST route decodes the base64 string into a Buffer in-memory and writes it directly to the response — no disk I/O, no temp files, no streaming library needed.
5. Filename sanitisation strips non-safe characters and guarantees a .pdf extension before setting Content-Disposition.

There is no persistence layer. Every request is stateless — the decoded PDF is never stored anywhere on the server.

Setup & Install

npm install
npm run build
npm run dev

The server listens on the port defined by the PORT environment variable, defaulting to 9039.

Environment Variables

TypeScript Interfaces

These interfaces are defined in src/index.ts and describe the exact shape of every request body and response object used by the API.

TranscriptPdfBody

Shape of the JSON body accepted by POST /api/transcript/pdf.

interface TranscriptPdfBody {
  /** Base64-encoded PDF binary data (required) */
  pdf_base64?: string;

  /** Optional filename for the downloaded file (defaults to "transcript") */
  filename?: string;
}

HealthResponse

Shape of the JSON body returned by GET /api/health.

interface HealthResponse {
  status: string;     // always "ok" when the server is running
  timestamp: string;  // ISO 8601 UTC timestamp of the response
}

ErrorResponse

Shape of every error JSON body returned by the API.

interface ErrorResponse {
  error: string;  // human-readable description of what went wrong
}

API Endpoints

All responses use application/json unless otherwise noted.

GET /api/health

Returns the current health status of the server. Useful for uptime checks and load-balancer probes.

Example request

curl -s http://localhost:9039/api/health

Example response

{
  "status": "ok",
  "timestamp": "2026-04-22T12:00:00.000Z"
}

POST /api/transcript/pdf

Accepts a base64-encoded PDF and returns it as a downloadable application/pdf file attachment.

How it works:

1. Validates that pdf_base64 is present in the request body.
2. Decodes the base64 string into a raw binary Buffer in-memory.
3. Sanitises the optional filename field — non-safe characters are replaced with _ and a .pdf extension is appended if missing.
4. Sets Content-Type, Content-Disposition, and Content-Length headers, then sends the buffer directly to the client.

Nothing is written to disk at any point.

Request body (application/json)

Example request

curl -s -X POST http://localhost:9039/api/transcript/pdf \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_base64": "JVBERi0xLjQKJ...",
    "filename": "my_transcript"
  }' \
  --output my_transcript.pdf
  # --output saves the binary response directly to a local file

Example request body

{
  "pdf_base64": "JVBERi0xLjQKJ...",
  "filename": "my_transcript"
}

Success response

Returns the raw PDF binary (not JSON) with the following headers:

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="my_transcript.pdf"
Content-Length: <byte length of the decoded PDF>

Note: Because the response body is binary, do not attempt to parse it as JSON. Use --output <file> in curl or handle the Blob in a browser fetch call.

Error responses

Example error request (missing field)

curl -s -X POST http://localhost:9039/api/transcript/pdf \
  -H "Content-Type: application/json" \
  -d '{}'
# Returns: {"error":"Missing pdf_base64 field"}

Filename Sanitisation Rules

The filename field goes through the following transformations before being used in the Content-Disposition header:

1. Defaults to "transcript" if omitted or empty.
2. Any character that is not alphanumeric, _, -, ., or a space is replaced with _.
3. If the result does not already end in .pdf, .pdf is appended automatically.

This Express backend / api completed archive review with strong static results. Structure, dependency manifests, documentation, functional source, and common risk patterns were checked by the Tetrees verification pipeline; runtime phases are stated separately. Final verified scores after isolated runtime evidence: overall 8.3 and security 9. Final verified scores after isolated runtime evidence: overall 8.3 and security 9. Final verified scores after isolated runtime evidence: overall 8.3 and security 9. Final verified scores after isolated runtime evidence: overall 8.3 and security 9. Final verified scores after isolated runtime evidence: overall 8.6 and security 9.