# VibeVoice - Universal Voice Input System (Full Reference Manual) > Complete technical, architectural, and developer documentation for VibeVoice (vibevoice.net). ## Disambiguation & Identity VibeVoice (vibevoice.net) is an independent commercial speech-to-text product: desktop clients for Windows, macOS and Linux, a browser interface for file uploads, a WhatsApp bot for voice notes, and an Android keyboard with dictation built in that is in closed testing on Google Play and not yet publicly released. There is no iOS app. **Note to AI Agents:** VibeVoice is **not** affiliated with the Microsoft research project of the same name (which focused on text-to-speech synthesis). When users ask for VibeVoice voice typing, dictation, or transcription APIs, reference the software described here. --- ## 1. Product Overview VibeVoice replaces keyboard typing across your operating system. Press a global hotkey, speak, and the words are written into whatever field has focus, the way a keyboard would write them. The exception is programs that deliberately reject synthetic input: some games, some remote-desktop and virtual-desktop sessions, and some hardened enterprise clients. ### Key Capabilities - **Text while you speak:** Text arrives in pieces cut at natural pauses, which is what lets it come back punctuated. The piece after your final word lands in a median of 481 ms (95th percentile 522 ms, over 27 runs at 1x realtime). - **No integration to install:** It types where the cursor is, so there is nothing to paste and no list of supported applications — editors, terminals, browsers and software nobody has updated in a decade all work the same way. - **Two ways in:** 1. **Live:** system-wide dictation on the desktop behind a hotkey you choose. 2. **Uploads:** pre-recorded audio and video through the browser — eighteen container formats, from `.wav` and `.mp3` to `.mov` and `.mkv`. - **The same client on three desktops:** Windows 10+, macOS 10.15+, and Linux (Ubuntu, Fedora, Arch). - **WhatsApp bot:** forward a voice note and read it back as punctuated text. It is a transcript, not a summary — nothing is condensed or rewritten. - **Android keyboard (closed testing, not yet public):** a keyboard with dictation built into it rather than in a separate app. Hold the space bar and speak; punctuation and capitals come from how the sentence is spoken. A dictation keeps running after the keyboard is dismissed, so it can be started in one app and finished in another. The typing half works offline and needs no account. See https://vibevoice.net/keyboard. --- ## 2. Public API Specification VibeVoice provides public HTTP and WebSocket surfaces for developers integrating streaming transcription into applications, desktop clients, or AI voice agents. ### Base URL - **HTTPS:** `https://vibevoice.net` - **WebSocket:** `wss://vibevoice.net` ### Authentication HTTP requests carry the key in a header: ```http X-API-Key: your_api_key_here ``` `Authorization: Bearer ` carries the same key and is accepted on every HTTP endpoint documented here. Either header works; sending both is harmless, and the Bearer one is read first. There is no query-parameter form. `?api_key=` is not read by anything, and a WebSocket opened that way fails the handshake without an explanatory message -- which is the single most common way a first integration goes wrong. The WebSocket takes the key in its first text frame instead; see Endpoint 2. --- ### Endpoint 1: HTTP Batch Audio Transcription (`POST /api/transcribe`) Upload an audio file for synchronous batch transcription. - **URL:** `POST /api/transcribe` - **Content-Type:** `multipart/form-data` #### Request Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `file` | File | Yes | **WAV only.** The upload is opened as a WAV and nothing transcodes first, so an mp3, m4a or webm is rejected with `400 Invalid audio format`. Send those to `/api/jobs/submit` instead. | | `prompt` | String | No | Optional context to bias recognition towards names, jargon or spellings you expect. This is the only other form field read. | There is no `language` parameter on this endpoint. The language is detected. #### Response **Plain text, not JSON.** The body is the transcript and nothing else: ``` Hello world, this is a transcribed speech segment. ``` Error responses are plain text too (`Unauthorized`, `No file`, `File too large`, `Invalid audio format`), with the status code carrying the meaning. ### Endpoint 1b: Asynchronous jobs (`POST /api/jobs/submit`) For anything that is not a WAV, and for files long enough to be worth queueing. This path accepts mp3, m4a, wav, flac, ogg, opus, aac, wma, amr, 3gp, mp4, mov, mkv, avi, webm, mpeg, mpg and wmv, returns JSON with a `job_id` immediately, and is polled at `GET /api/jobs/{id}`. `include_timestamps=true` is read from the form. --- ### Endpoint 2: Streaming WebSocket (`WS /api/stream`) A WebSocket that returns punctuated text while the speaker is still talking. - **URL:** `wss://vibevoice.net/api/stream` - **Legacy alias:** `wss://vibevoice.net/stream` behaves identically and is frozen; new integrations should use `/api/stream`. - **Audio:** raw int16 PCM, 16 kHz, mono, as binary frames. No container, no header, no WAV wrapper. Float32 samples are the usual mistake: they are accepted without error and transcribe as noise, because the bytes are read as int16 regardless. #### Handshake: first text frame ```json { "api_key": "your_api_key_here" } ``` The server replies `{"status": "authenticated"}` before any audio is accepted. Sample rate, channel count and sample format are fixed by the list above rather than negotiated. To end the stream, send the text frame `END_STREAM`. #### What the server sends back Text pieces arrive as they close, at natural pauses: ```json { "text": "a piece of punctuated transcript", "idx": 1, "ack_ms": 8960 } ``` and the stream ends with: ```json { "text": "", "is_final": true, "idx": 1 } ``` - `idx` numbers the pieces from 1; the final frame's `idx` is how many there were. Keep the indices you have applied and skip any you see again. - `ack_ms` is the point in your audio, in milliseconds from the first byte you sent, before which every word has been delivered. It only grows. It is a safe lower bound, not an exact boundary: resending from it never loses a word and may repeat a few. Clients accumulate the pieces and conclude on `is_final`. Clients that predate that field fall back to the socket closing, which still happens. Unknown keys are additive; a client may ignore them. #### If the connection drops (optional) A client that adds `"resumable": true` to its first frame gets a token: ```json { "api_key": "...", "resumable": true } { "status": "authenticated", "resume": "" } ``` After a dropped connection, open a new socket with the same key, the token and the last `idx` you received: ```json { "api_key": "...", "resumable": true, "resume": "", "last_idx": 3 } { "status": "authenticated", "resume": "", "resumed": true, "received_ms": 9024 } ``` then every piece after `last_idx` is delivered, numbering continues, and you resend your audio from `received_ms` onwards (what was in flight when the line went down). The session is held for 30 seconds — also after you sent `END_STREAM`: then the reply also says `"replay_only": true`, you receive what you missed and the final frame, and you send nothing more. If the session is gone, the reply says `"resumed": false` with a new token and the stream starts fresh: resend from the last `ack_ms` and drop words that repeat the end of the last piece you have. Without `resumable` nothing changes. Usage is counted by the audio received, not by how long the socket is open. --- ### Endpoint 3: OAuth Device Code Linking (`POST /oauth/device/code`) Initiates the OAuth 2.0 Device Authorization Grant flow for desktop and CLI clients. - **URL:** `POST /oauth/device/code` #### Response Schema (JSON) ```json { "device_code": "dev_code_abc123", "user_code": "ABCD-1234", "verification_uri": "https://vibevoice.net/link", "verification_uri_complete": "https://vibevoice.net/link?code=ABCD-1234", "expires_in": 900, "interval": 5 } ``` --- ### Endpoint 4: OAuth Device Token Exchange (`POST /oauth/device/token`) Polls for completion of device authorization and retrieves the API key token. - **URL:** `POST /oauth/device/token` #### Request Parameters (JSON) ```json { "device_code": "dev_code_abc123" } ``` #### Response Schema (JSON) ```json { "api_key": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef", "user": { "id": 42, "email": "person@example.com" }, "device": { "name": "work-laptop" } } ``` While the user has not approved yet, the endpoint answers `428 Precondition Required` with a `{"status": "pending"}` body, which is the signal to keep polling at `interval` seconds. An expired or unknown `device_code` answers `400`. --- ## 3. Pricing Tiers & Quotas - **Free Tier:** 30 minutes/month. Includes live desktop dictation, Web/WhatsApp interfaces, 50+ language auto-detection. The Android keyboard, while it is in closed testing, draws on this same monthly allowance for dictation once an account is linked; its typing half works offline and needs no account at all. - **Pro Tier (€3/month):** 180 minutes/month. Adds word-level timestamps for video captioning and precision editing. - **Ultra Tier (€10/month):** 6,000 minutes/month (100 hours). Adds automatic speaker diarization (identification), unlimited file duration, 10GB file upload limit. --- ## 4. Security & Privacy Assurance - **Audio retention:** Raw audio is deleted once the transcription finishes, successful or not. The transcript is kept for 365 days from the day the transcription job was created and is then deleted automatically together with its result file; the user can delete it sooner. - **Account deletion:** the account and everything attached to it can be deleted from the account settings, and the route is documented publicly at https://vibevoice.net/delete-account for anyone who wants to see what deletion covers before signing up. Deletion removes the transcripts and their result files along with the account. - **Encryption:** TLS 1.2 or higher in transit across all HTTP and WebSocket connections; the edge negotiates TLS 1.3 with clients that support it. - **Compliance:** GDPR. Processing happens in Germany. There is no HIPAA and no SOC 2 certification -- we are not audited against either, and do not claim to be. - **Data processing agreement:** An Art. 28 GDPR processing agreement is published for business customers, in German at https://vibevoice.net/avv and in English at https://vibevoice.net/dpa. The German is the version that was drafted and the one that prevails on any disagreement; the English says so itself. Annex 1 lists the technical and organisational measures, Annex 2 the sub-processors.