Secure full-stack speech-to-text app built with Next.js, React, TypeScript, and server-side OpenAI API calls. It is for developers who want a small, self-hosted transcription UI (live microphone or file upload) that keeps the OpenAI API key on the server.
Status: early prototype (version 0.1.0, not published as a package). It needs your own OpenAI API key and a project with access to the configured transcription models. To try it, see Setup.
- Live Mic mode sends the browser's WebRTC SDP offer to the app's own server route, which exchanges it with the OpenAI Realtime API, and shows partial/final transcript updates.
- File Upload mode validates common audio/video files and transcribes them through a server-only API route.
- Transcript workspace supports editing, copy, clear, TXT/JSON export, and SRT/VTT export when timestamp segments exist.
- No persistent storage is used by default. Uploads are handled in memory and are not written to disk.
TXT and JSON export the text currently shown in the workspace, including live drafts and edits,
when its order and event identity are established. A persistent live content-identity warning is
also included if it was removed by an edit. SRT and VTT require valid original timestamps for every
segment.
Editing the text or adding live speech invalidates that alignment, so subtitle exports are disabled
and JSON exports an empty segments list. The configured file models use JSON transcription and
do not promise timestamp segments; synthetic timestamp fixtures are not evidence of provider
availability. Realtime events do not supply segment timestamps. Starting live capture alone does
not relabel an existing upload. Realtime provenance uses the same-origin X-STT-Model response
header when it contains a bounded valid model identifier; otherwise its model is unknown. Combined
text uses model: "mixed" when known sources differ, omits model when either is unknown, and omits
language unless both sources share the same known, non-auto language. Fallback uses the file
transcription response's provenance, not a presumed realtime model.
Live transcription uses the documented transcription item_id to associate deltas, final
transcripts and failures. An event_id identifies an event, not an utterance. Predecessor IDs
order overlapping items as direct predecessor chains. An explicit null predecessor marks the first
item; an item with an unknown predecessor is provisional and is not irreversibly committed. Late
metadata can reorder provisional items. While their order is unconfirmed the preview is provisional
and Copy/TXT/JSON are disabled. Stop retains available text, marking each unresolved item
[Live item; order unconfirmed] so the exported sequence does not claim to be chronological.
Editing a provisional preview fences that session, so late metadata cannot repair the edited text.
Any nonempty edit made while provisional text is present remains unexportable until you explicitly
confirm its displayed order or keep it with an [Edited live text; order unconfirmed] label. Stop
also applies that label, even if the edit currently has no text. Use Clear or successfully
replace the workspace with an upload to discard the uncertain edit; erasing the textarea alone does
not resolve it. The label leaves the edited text and its whitespace intact.
Editing text that already contains an uncertainty label also requires an explicit choice again,
so removing the label in an ordinary edit cannot silently turn unconfirmed order into fact.
Unidentified partial events have a separate event-identity uncertainty: repeated text could be
distinct speech or a repeated delivery. Their preview is retained without text-based deduplication,
but Copy/TXT/JSON are disabled until a valid final replaces that item's draft. Stop, channel close,
failure, or fallback retains available unidentified partial text with an event-identity warning;
the order warning is independent and both appear when applicable. Editing uncertain or warned text
requires a separate explicit choice to retain the identity warning or confirm the displayed text;
confirming order alone does not confirm event identity. Clear or a successful replacement discards it.
Contradictory or duplicate first-item metadata, conflicting terminal events, and conflicting
audio/non-audio identities fence the session. A failed predecessor is terminal: available partial
text is retained, successors can continue, and the workspace shows a warning.
Recognized non-input-audio item kinds, non-input-audio content types, and system or assistant roles
are identity claims even when other metadata is unknown. They conflict with an input-audio claim
for the same item ID in either arrival order; missing or unrecognized metadata alone remains neutral.
Recognizing these claims does not enable tools or qualify live-provider behavior.
For a created user message with exactly one input_audio content part, its optional reference
transcript is not added as speech. A completed transcription for the same item must match it
exactly, including an explicitly supplied content index of zero. If the completion arrived first,
a matching reference can still supply predecessor metadata. If the reference arrives first, the
app waits for its matching completion; Copy/TXT/JSON are disabled and the reference is not shown as
accepted text. Stop or session termination omits an unconfirmed reference, visibly warns that
speech may be missing, and retains already accepted text. The omission warning remains through
later sessions until Clear or a successful replacement upload. Conflicting references, completions,
or content indexes fence the session. References on other item shapes, multiple content parts,
and other unsupported transcript-bearing payloads are not accepted.
The tracker supports at most one audio content part per item. An explicit content index must be a nonnegative safe integer and must agree across partial, completed, and failed transcription events and with the position of any known audio part in created-item metadata. Multiple audio parts, malformed indexes, and conflicting indexes fence the session before their text or predecessor metadata can be merged or discarded. An index without created metadata identifies the one observed part; missing or unrecognized metadata is otherwise neutral. For compatibility, an event with no index is treated as belonging to that same part, so the app cannot distinguish multiple parts if their events omit indexes and no metadata reveals them. This is a conservative client policy, not a claim that the provider emits these shapes.
When this content-identity fence is reached, already accepted text is retained, but later or rejected speech may be missing. The workspace, Stop result, copies, and TXT/JSON exports retain a content-identity warning; the warning survives edits and later sessions until Clear or a successful replacement upload. Timed exports are unavailable while this warning is retained.
Realtime turn detection is disabled for the configured model. Press Finish turn after speaking
to send an explicit input_audio_buffer.commit; listening continues. Each commit has a distinct
client event ID. A new, identified server acknowledgement for an item not already acknowledged in
this session releases the pending turn; an error does so only when its nested client event ID
matches that turn. The server acknowledgement does not echo
the client ID, so this assumes the one outstanding commit receives its acknowledgement before the
next commit. An acknowledgement without a server event ID cannot safely release a turn, and a later
acknowledgement for the same item cannot establish a new turn: Stop and retry, or wait for an
identified acknowledgement for a new item. Wait for transcription and ordering metadata
before pressing Stop. Stop releases capture immediately and does not wait for a commit or final
response; any available unresolved text is retained with the labels described above. If the active
data channel closes, capture stops and Retry is available; uncommitted audio and pending results may
be lost, and audio already sent cannot be retracted. No recording is uploaded or turn committed
automatically. No periodic commits are sent. These controls have synthetic coverage only, not live
provider or browser-media qualification.
Clearing, editing, or replacing the workspace during a live session fences all subsequent events from that session, including events for unknown predecessors. Missing or conflicting item IDs, malformed tracked events, unexpected transcript fields, contradictory ordering, or resource limits also pause acceptance of further events rather than guessing their identity or order. A visible message asks you to Stop and Start a new session; the microphone is not automatically stopped by this realtime transcript fence. If microphone permission or realtime setup is still pending, a workspace edit, clear, or successful replacement upload instead retires that setup and stops any acquired capture; that session cannot later start fallback recording. During local fallback recording, the same actions stop capture and discard the recording before upload, so it will not be transcribed. If fallback transcription is already in flight, cancellation is best effort: the result is discarded, but audio already sent cannot be retracted and may already have been transcribed. A successful fallback transcription appends to existing text and any retained live draft instead of replacing them. Retry while fallback recording discards that recording and reports the disposition. If a recorder stops unexpectedly, capture is released immediately and its audio stays in this tab until you choose Transcribe recording or Discard recording; it is not uploaded automatically. If recording reports an error, only chunks already received are retained for this choice and they may be incomplete. An older upload cannot replace a later edit, clear, new upload, or live session. Text in rejected events is not captured and may need to be repeated in the new session.
For one session, the tracker retains at most 1,024 item IDs (including referenced predecessors),
4,096 event IDs, and 1,000,000 UTF-16 code units each of pending transcript and reference text
combined, resolved item text, and serialized event payloads retained for deduplication. Each item or
event ID is limited to 256 code units. A data-channel message over 1,100,000 code units is also
refused before JSON parsing.
Reaching a limit fences the session instead of evicting IDs that could still be needed to reject
late events. All observed server event kinds share the same event-ID space. Exact repeated payloads
with the same nonempty event_id are suppressed before ordering or turn state changes; conflicting
or malformed IDs fence the session. Payloads are
retained only in bounded browser-session memory, not displayed or logged, and released when the
tracker finishes or the workspace changes. Omitted event IDs are treated as unidentified; a present null ID is malformed:
registration metadata can still establish order, but an unidentified acknowledgement cannot
release a pending turn. Without an event ID, a repeated delta is indistinguishable from legitimate
repeated text and is appended with the uncertainty treatment above; a final transcript replaces the
item's accumulated draft. Acknowledged item IDs are tracked separately within the item limit. An
uncorrelated error leaves the turn pending and reports an unknown outcome with Stop/retry guidance;
it is not proof of commit failure. A safely handled server error with no pending turn shows fixed
guidance to check the transcript or Stop and retry if needed; it does not assert that a particular
turn or the session failed. These rules have synthetic test coverage, not live provider qualification.
app/api/transcribe/route.ts: multipart upload API, size checks, rate limiting, server-side transcription.app/api/realtime/call/route.ts: exchanges the browser's WebRTC SDP offer with OpenAI server-side; the raw OpenAI API key and no provider tokens ever reach the browser.src/lib/constants.ts: centralized model names, MIME types, extensions, and limits.src/lib/config.ts: server-only environment loading and startup/runtime validation helpers.src/server/fileTranscription.ts: OpenAI Audio Transcriptions API wrapper.src/server/realtime.ts: Realtime transcription call (SDP exchange) wrapper.src/server/rateLimit.ts: in-memory rate limiter, client identification, and hashed safety identifiers.proxy.tsandsrc/server/basicAuth.ts: optional shared HTTP Basic authentication for pages and API routes.src/lib/transcriptExport.ts: TXT, JSON, SRT, and VTT export helpers.components/stt-app.tsx: Live Mic, File Upload, and transcript workspace UI.
Create a project-scoped OpenAI Platform API key (this repo uses the name production-stt-app in examples) through your approved organization secret workflow, then install it as a server-only secret:
- Create the key in the OpenAI Platform API key settings for the intended project.
- Store it as
OPENAI_API_KEYin your deployment secret store. - For local development only, place it in
.env.local. - Do not commit
.env.local; it is ignored by.gitignore.
The app never prints, logs, or exposes the raw key. npm run validate:env checks that OPENAI_API_KEY is present and key-shaped, and that optional Basic authentication is configured completely. npm run verify:openai checks whether the configured project can see the configured STT models.
npm install
cp .env.example .env.local
# edit .env.local and set OPENAI_API_KEY through a secure local editor
npm run devOpen http://localhost:3000.
npm run dev
npm run build
npm start
npm run validate:env
npm run verify:openai
npm run smoke:upload
npm run lint
npm run format
npm run typecheck
npm run test
npm run test:e2e
npm run qualityDefaults are centralized in src/lib/constants.ts and can be overridden through environment variables:
- Live STT:
gpt-realtime-whisper - File STT default:
gpt-4o-mini-transcribe - File STT higher accuracy:
gpt-4o-transcribe - Upload limit: 25 MB by default
- Audio is sent to OpenAI for transcription.
- Audio and transcripts are not stored by this app by default.
- OpenAI calls run server-side. The browser sends WebRTC SDP offers to the server, and the server exchanges them with OpenAI.
- Logs exclude raw audio, full transcripts, tokens, keys, and secrets.
- The API includes request size checks, MIME/extension validation, rate limiting, timeouts, structured errors, and a healthcheck.
- Docker builds exclude local
.env*files through.dockerignore; pass secrets only at runtime. - Authentication is off by default. Anyone who can reach an unprotected app can spend your OpenAI quota. Enable the optional Basic authentication below or put it behind an authenticating reverse proxy, VPN, or similar access control before exposing it.
Set both BASIC_AUTH_USER and BASIC_AUTH_PASSWORD as server-only environment variables. Browsers prompt for these credentials before opening the app and reuse them for same-origin API requests. Use a strong password and HTTPS outside local development: Basic authentication encodes credentials but does not encrypt them. Never put these values in NEXT_PUBLIC_* variables.
The username cannot contain a colon, and neither value may contain control characters. The UTF-8 encoded username:password pair is limited to 6,144 bytes.
Every page and API request is protected except the exact /api/health endpoint, which remains available to health probes. Both paid API routes also validate credentials themselves before reading uploads or contacting OpenAI. Authenticated mutations reject cross-site browser requests and opaque or foreign origins. Origin checks compare the full scheme, host, and port. Set BASIC_AUTH_PUBLIC_ORIGIN to the exact browser-facing origin, such as http://127.0.0.1:3000 locally or https://stt.example.com behind TLS termination, without a trailing slash. When authentication is enabled, missing or malformed values cause all protected requests to return HTTP 503; production startup validation also rejects them. The check never derives the canonical origin from Host, forwarding headers, or the internally reconstructed request URL. Configure the public ingress and backend access appropriately for your deployment. Credentialed scripts without an Origin header remain supported. An incomplete or invalid configuration returns HTTP 503 instead of allowing access; production startup validation also rejects it. Leave both variables empty to disable authentication.
The authentication browser suite exercises real local HTTP with a configured origin and a second server with the origin unset. It does not exercise TLS termination: a synthetic local HTTPS proxy could test scheme handling with a locally trusted test certificate and a configured HTTPS origin, but would not validate a production ingress, certificate chain, header sanitization, or backend isolation. Validate those separately in the target deployment.
This is one shared account, without individual users, sessions, or a logout button. Anyone sharing the credentials shares the same rate-limit bucket and safety identifier, regardless of IP. A per-user identity provider or authenticating reverse proxy remains appropriate for multi-user deployments. Scripts calling the paid APIs must also supply the configured Basic credentials.
The application does not rate-limit failed authentication attempts. Use a strong, unique password and an upstream access control or brute-force protection where needed.
The built-in rate limiter is in-memory and per process. Authenticated requests are keyed by their verified Basic username. Without Basic authentication, Next.js route handlers do not expose the socket address, and X-Forwarded-For / X-Real-IP can be forged by any client, so by default these headers are ignored and all callers share one rate-limit bucket (RATE_LIMIT_MAX_REQUESTS per RATE_LIMIT_WINDOW_MS in total).
If the app runs behind a reverse proxy you control that sets X-Forwarded-For (appending the real client address) or X-Real-IP, set TRUST_PROXY=true. The limiter then keys buckets on the right-most X-Forwarded-For entry (the one your proxy added), falling back to X-Real-IP. Only enable this when the app is not directly reachable by clients, otherwise they can forge the header.
With Basic authentication, realtime requests send OpenAI an OpenAI-Safety-Identifier header containing a salted SHA-256 hash of the verified username. Otherwise, when TRUST_PROXY=true, the identifier hashes the client address. Neither the raw username nor IP is sent upstream. Set SAFETY_IDENTIFIER_SALT to a long random secret to keep identifiers stable across restarts; otherwise a random per-process salt is used. Without authentication or TRUST_PROXY the header is omitted.
- Build with
npm ci && npm run build. - Set
OPENAI_API_KEYin the host secret manager. - Run
npm run verify:openai && npm start;npm startvalidatesOPENAI_API_KEYbefore serving. - Ensure the host supports outbound HTTPS to OpenAI.
- Add
OPENAI_API_KEYas a server-side environment variable. - Keep the key out of
NEXT_PUBLIC_*variables. - Deploy normally with the Next.js adapter.
- Confirm
/api/healthreturnsopenaiConfigured: true.
Realtime WebRTC requires browser microphone permission and network access to https://api.openai.com.
- Missing key: API routes return a structured
MISSING_API_KEYerror and production startup validation fails safely. - Key present but transcription fails: run
npm run verify:openai. A key can be present while the project still lacks active billing, model allowlist access, or permission to use the configured STT models. - Upload route smoke test: with the dev or production server running, run
npm run smoke:upload. It sends a tiny generated WAV through/api/transcribeand reports sanitized status/error metadata. - Unsupported file: check file type, extension, and size.
- Realtime fails before connecting: check that the OpenAI project has active billing and access to
gpt-realtime-whisper. Local recording fallback is used only for browser/network microphone failures, not server-side OpenAI access failures. - OpenAI HTTP 500 during realtime setup: confirm the project has active billing and access to the configured realtime transcription model. A configured key is not enough if the project is not active for paid API usage.
- Long files: shorten or compress the file, then retry.
- Upstream failures: retry later or switch file mode to
gpt-4o-transcribefor accuracy-sensitive jobs.
Code and documentation are released under the MIT License.
Production auth HTTP test plan: build with synthetic environment values, then run the built server directly with next start to bypass the startup validator. On an isolated loopback port, check that missing and malformed public origins return 503 for authenticated and unauthenticated page requests and both paid POST routes, with and without Origin, while /api/health remains available. Restart with a valid public origin and check the 401 challenge, authenticated page access, cross-site 403, and an originless authenticated POST with an invalid body (400). Use only synthetic credentials and invalid request bodies so no provider request is made. Separately run npm run validate:env through the synthetic subprocess tests to cover startup validation.
