Skip to content
CompleteTech-LLCPublic

About

Signal STT: secure Next.js speech-to-text app with live mic and file upload, using server-side OpenAI calls.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

55 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

A microphone and audio waveform flowing into a transcript document, a file upload tray and a shielded secure server, in teal and amber on midnight navy.

Signal STT

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.

Overview

  • 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.

Transcript exports

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.

Architecture

  • 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.ts and src/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.

Secure Key Setup

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:

  1. Create the key in the OpenAI Platform API key settings for the intended project.
  2. Store it as OPENAI_API_KEY in your deployment secret store.
  3. For local development only, place it in .env.local.
  4. 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.

Setup

npm install
cp .env.example .env.local
# edit .env.local and set OPENAI_API_KEY through a secure local editor
npm run dev

Open http://localhost:3000.

Commands

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 quality

Models And Limits

Defaults 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

Privacy And Security

  • 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.

Optional shared Basic authentication

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.

Rate limiting and proxies

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.

Safety identifier

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.

Deployment

Generic Node Hosting

  1. Build with npm ci && npm run build.
  2. Set OPENAI_API_KEY in the host secret manager.
  3. Run npm run verify:openai && npm start; npm start validates OPENAI_API_KEY before serving.
  4. Ensure the host supports outbound HTTPS to OpenAI.

Vercel-Style Hosting

  1. Add OPENAI_API_KEY as a server-side environment variable.
  2. Keep the key out of NEXT_PUBLIC_* variables.
  3. Deploy normally with the Next.js adapter.
  4. Confirm /api/health returns openaiConfigured: true.

Realtime WebRTC requires browser microphone permission and network access to https://api.openai.com.

Troubleshooting

  • Missing key: API routes return a structured MISSING_API_KEY error 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/transcribe and 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-transcribe for accuracy-sensitive jobs.

License

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.

About

Signal STT: secure Next.js speech-to-text app with live mic and file upload, using server-side OpenAI calls.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages