> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build your own Wispr Flow: a voice dictation app on PyAI

> Build a Wispr Flow-style voice dictation app on PyAI Hear streaming: push-to-talk mic capture, PCM16 over one WebSocket, interim partials rendered at the cursor, finals committed as you speak.

A voice dictation app is one streaming speech-to-text loop plus a handful of UX
decisions. **PyAI Hear streaming** is the engine: your app captures the mic,
sends PCM16 audio frames up one WebSocket, and receives fast, revisable
**partial** results (measured 185-205 ms to first partial on real speech,
in-region) plus stable **final** results when each phrase settles. The whole
app is how you render those two result types at the user's cursor.

Wispr Flow is the better buy for end users who want a finished, polished
consumer app with system-wide OS integration. Building on PyAI makes sense when
dictation is a feature inside *your* product: CRM note entry, medical or legal
scribing, field-report capture, accessibility tooling, or a dictation bar you
ship to your own users.

## What you're building

```mermaid theme={null}
flowchart LR
  key[Hotkey / push-to-talk] --> mic[Mic capture]
  mic --> pcm[PCM16 frames, 16 kHz]
  pcm -->|binary WS| hear[Hear streaming]
  hear -->|partial: revisable| grey[Greyed text at cursor]
  hear -->|final: stable| commit[Committed text at cursor]
  grey -.->|replaced by| commit
```

The UX contract that makes dictation feel instant: show partials immediately as
provisional text (greyed, never committed), then replace them with finals as
they land. The user sees words forming while they speak, and the text field
only ever keeps stable output.

## The PyAI stack for this build

| Piece                      | PyAI product             | Endpoint                              | Scope                                 |
| -------------------------- | ------------------------ | ------------------------------------- | ------------------------------------- |
| Streaming transcription    | Hear (streaming)         | `wss /v1/audio/transcriptions/stream` | `hear:stream`                         |
| Long-form audio (optional) | Hear (batch, discounted) | `POST /v1/transcription/jobs`         | `hear:transcribe` + `transcribe:jobs` |

That is the whole stack. Everything else (the hotkey, the cursor insertion, the
text field) is your app.

## Build order

<Steps>
  <Step title="Get a key with hear:stream">
    An instant [sandbox key](/quickstart) works for building. Production keys
    are created in the [console](https://console.pyai.com).
  </Step>

  <Step title="Open the streaming socket">
    Connect to `wss://api.pyai.com/v1/audio/transcriptions/stream` and pass the
    key as the `pyai-key.<API_KEY>` subprotocol (browsers cannot set headers on
    a WebSocket). The full wire protocol, including query params and close
    codes, is in the [streaming STT guide](/guides/streaming-stt).
  </Step>

  <Step title="Capture mic audio as PCM16 frames">
    Use an AudioWorklet in the browser (or the native mic API on desktop) and
    stream 16 kHz PCM16 chunks of about 20 ms each as binary frames.
  </Step>

  <Step title="Render partials greyed, commit finals">
    Each partial replaces the previous provisional text at the cursor; each
    final locks in. This one rule is most of what makes dictation feel
    professional instead of jittery.
  </Step>

  <Step title="Add the dictation polish">
    Push-to-talk vs. always-on, a `{"type":"commit"}` flush when the user
    pauses or releases the key, filler-word handling, and auto-punctuation
    preferences. These are app-level decisions; the guide above covers the
    commit semantics.
  </Step>
</Steps>

## When to buy Wispr Flow instead

Buy it when the customer is an individual who wants a finished app that works
everywhere on their machine, with per-app tone and years of polish, and does
not want to build anything. Build on PyAI when dictation lives inside a product
you ship, when you need the transcript stream in your own systems, or when you
want usage-based pricing instead of per-user subscriptions.

## FAQ

### How fast is PyAI dictation latency?

On real speech, measured in-region, Hear streaming returns its first partial in
185-205 ms. Partials are revisable by design (they refine as the phrase
settles); finals are the stable text your app commits.

### What languages can a PyAI dictation app support?

English is the GA, benchmarked language today. Other language codes are
accepted as hints, but accuracy for them is not published yet. See the
[language support reference](/reference/language-support) for current status.

### Can I run dictation inside my own desktop or mobile app?

Yes. The socket takes raw PCM16 frames from any capture source (browser
AudioWorklet, native mic APIs, a telephony leg), so the same integration works
in an Electron app, a mobile app, or a web app.

### What does it cost to build this on PyAI?

Dictation meters as transcription minutes, billed per second by default with no
seats or subscriptions. Current rates are on the
[pricing page](https://pyai.com/pricing).

## Start building

The [streaming STT guide](/guides/streaming-stt) has the complete wire
protocol, browser capture code, and the partial/final rendering pattern, or
scaffold a working live-captions demo in one command:

```bash theme={null}
npm create pyai-app@latest browser-hear-live-captions
```