SpeechGPT: a browser client for voice conversations with ChatGPT

What SpeechGPT actually is, and who it is built for

SpeechGPT is a web application that enables you to converse with ChatGPT, according to its README. The distinction that matters is where the work happens. This is a client: it captures audio, converts it to text, sends the text to a chat completion endpoint, and speaks the reply. The README lists two intended uses, improving language speaking skills and having fun chatting with ChatGPT, and the language-learning framing explains several design choices. The app supports over 100 languages, ships a mobile-friendly layout, and stores data locally.

The audience is narrow but real. If you already hold an OpenAI API key and want a voice loop in a browser tab rather than a native app, the repository gives you a complete front end without a server component. If you are looking for an assistant that manages your account, bills you, or keeps your history in the cloud, this is the wrong shape of project. There is no backend in the top-level layout: no server directory, no API routes, no database. The entries are a Vite app (index.html, src/, vite.config.ts), a Dockerfile, an nginx.conf, and configuration files.

One caveat on the framing. The README's privacy claim, that all data is stored locally, is about storage, not about transmission. Text still travels to whichever chat endpoint you configure, and speech audio travels to Azure or Amazon if you select those synthesis services.

The speech-to-text-to-speech loop and where each credential goes

The dependency list is the clearest documentation of the architecture. Speech recognition comes from react-hook-speech-to-text, with microsoft-cognitiveservices-speech-sdk and @aws-sdk/client-transcribe-streaming available as alternatives. Synthesis uses the browser's built-in voices by default, with microsoft-cognitiveservices-speech-sdk for Azure TTS and @aws-sdk/client-polly plus @aws-sdk/polly-request-presigner for Amazon Polly. The chat call goes through the openai package. Persistence uses Dexie, which is a wrapper over IndexedDB, and dexie-react-hooks binds that store to React components. State management is Redux Toolkit, routing is react-router-dom, and markdown replies render through react-markdown with highlight.js.

So the data flow is: microphone to a recognition provider, transcript to the OpenAI chat API, response text to a synthesis provider, audio to the speakers, and the whole exchange into IndexedDB. Every provider boundary is a place where a key is needed, and the app puts those keys in two different places depending on how you deploy. The Dockerfile declares seven build arguments, VITE_OPENAI_API_KEY, VITE_OPENAI_HOST, VITE_AWS_REGION, VITE_AWS_ACCESS_KEY_ID, VITE_AWS_ACCESS_KEY, VITE_AZURE_REGION and VITE_AZURE_KEY, and promotes each to an environment variable before running bun run build. Because Vite inlines VITE_-prefixed variables at build time, those values end up in the shipped JavaScript bundle. That is a deliberate trade-off for a client-only app, and it is the single most important thing to understand before you build an image.

The README's tutorial takes a different route: it tells you to open Settings and enter the OpenAI API key under the Chat section, and to switch the synthesis service to Azure TTS or Amazon Polly and enter the corresponding region and keys under Synthesis. Those runtime settings are what the local-storage claim refers to. Which path wins depends on whether the build-time variables were set to real values or left at the REPLACE_WITH_YOUR_OWN placeholder.

Installing SpeechGPT with Docker and having a first conversation

The README offers three deployment routes. The quickest is the published image, which the README labels arm64. Pull it, then run it on port 8080.

docker pull hahahumble/speechgpt

docker run -d -p 8080:8080 --name speechgpt hahahumble/speechgpt

The README says to visit http://localhost:8080/ to access the application. If you would rather build from source, the repository ships a Dockerfile that uses oven/bun:1 as the builder stage, installs with bun install --frozen-lockfile, runs bun run build, and serves the result from nginx:alpine with the bundled nginx.conf.

docker build -t speechgpt:arm64 -f Dockerfile .

docker run -d -p 8080:8080 --name=speechgpt speechgpt

Either way, the first real use is the same. Open the app, go to Settings, navigate to the Chat section, and paste an OpenAI API key. The README points to an external tutorial if you do not have one. Then return to the conversation view, press the microphone control, and speak. You should see your words appear as text, followed by a streamed reply that the browser reads aloud. If nothing is transcribed, the recognition path is the suspect, not the chat call; the built-in recognizer depends on browser support, and Azure Speech Services is the documented alternative.

For a local development loop, package.json defines dev, build, preview and format scripts and pins the package manager to bun@1.2.18. The README defers environment setup to docs/developer-guide.md rather than repeating it, so read that file before running anything.

Build-time keys, browser support and the limits of a client-only design

The most consequential limitation is structural. There is no server in this repository, so there is nowhere for a secret to live that the browser cannot see. If you build an image with real values in VITE_OPENAI_API_KEY or VITE_AZURE_KEY, anyone who loads the page can read them from the bundle. The README's runtime Settings flow avoids baking keys into the artifact, but it moves them into the browser's local storage instead, which is only as safe as the device. For a personal instance on a laptop, that is a reasonable trade. For a shared or public deployment, it is not, and the README does not document an auth layer, a proxy, or a rate limit that would change the calculus.

Speech recognition is the second weak point. The app includes built-in recognition and integrations with Azure Speech Services and Amazon Transcribe, but built-in recognition is a browser capability, and the README does not state which browsers are supported or what happens when the capability is missing. The dependency react-device-detect suggests the UI adapts to the device, but adaptation is not the same as a documented fallback.

Third, the README does not document rollback, migration between versions, or what happens to locally stored conversations when the IndexedDB schema changes. Dexie supports versioned schemas, and the source would show how they are declared, but a reader of the README alone cannot plan an upgrade. The release history compounds this: the two most recent releases listed are v0.5.0 and v0.5.1, both dated 2023-05-15, while package.json declares version 1.0.0. The repository's last push was on 2026-07-11, so it is not archived and not abandoned, but the tagged releases do not track the current state of the code. Treat main as the artifact, not a release.

How SpeechGPT differs from the ChatGPT voice mode and from server-side voice stacks

The obvious comparison is ChatGPT's own voice mode, and the difference is control rather than capability. A hosted voice mode owns the pipeline end to end: you do not choose the recognizer, you do not choose the voice vendor, and you do not hold the API key. SpeechGPT inverts all three. You pick between built-in recognition, Azure, and Amazon Transcribe, you pick between built-in synthesis, Azure TTS, and Polly, and you supply the OpenAI credentials yourself. The cost of that control is that you also own the failure modes: an expired key, a region mismatch, or a browser without the recognition API are your problems, and the README's troubleshooting section does not exist.

The second comparison is with server-side voice stacks, where a backend holds the keys, brokers the audio, and stores transcripts. That architecture solves the secret-exposure problem and enables multi-user features. SpeechGPT does none of that, and it is the wrong tool if you need shared conversation history, user accounts, or an audit trail. What it offers instead is a small surface: a static bundle, an nginx config, and a local database. For a single user who wants a voice loop and does not want to run a server, that is the whole point.

Licence, maintenance and what an upgrade actually costs

The project is licensed under the MIT license, per the README and the LICENSE file at the repository root. MIT permits use, modification and redistribution with the licence and copyright notice preserved; it provides no warranty. That matters here because the app handles API credentials. If you redistribute a build, you are distributing software that expects users to enter their own keys, and the security of those keys is outside anything the licence addresses. This is a description of the licence terms, not legal advice.

On maintenance, the facts are limited. The repository is not archived, and the last push was on 2026-07-11. The most recent tagged releases are v0.5.0 and v0.5.1 from 2023-05-15, while package.json reports version 1.0.0, so the release tags are stale relative to the code. There is a CHANGELOG.md, and the README links to it for notable changes, but the version numbering does not give you a reliable upgrade signal.

The practical upgrade path is a rebuild. Because the Dockerfile resolves dependencies with bun install --frozen-lockfile against bun.lock, a rebuild of main picks up whatever the lockfile pins. Dependencies include the openai package at ^3.2.1 and the AWS SDK packages at ^3.303.0, both of which are older lines; moving forward means either accepting what the lockfile holds or updating the lockfile and rebuilding. Since conversations live in the browser's IndexedDB rather than in the image, replacing a container does not wipe history, but the README does not promise that the schema will keep working across versions. Back up the browser profile before a major jump if the history matters to you.

Editorial conclusion

Adopt SpeechGPT if you want a small, MIT-licensed front end that turns speech into ChatGPT turns and keeps the transcript in the browser, and you are willing to supply your own OpenAI key and to read the source when the README stops short. Do not adopt it if you need a maintained release cadence, a documented upgrade path, or a hosted service with support. Before deploying, check three things in the repository: which environment variables the build expects, whether your browser supports the built-in speech recognition path, and how the Azure or Polly credentials you set in Settings are stored.

Frequently asked questions

Official sources

1. hahahumble/speechgpt on GitHub
2. License: MIT
3. Project website
4. README
5. Releases