> ## Documentation Index > Fetch the complete documentation index at: https://developer.suki.ai/llms.txt > Use this file to discover all available pages before exploring further. # Audio Dictation > Learn how Audio Dictation turns spoken speech into real-time text. Align on workflow decisions, choose Dictation APIs, Web SDK, or Dictation SDK, then design where transcript text lands in your app
Audio Dictation converts spoken speech into text in real time. Instead of typing into fields or note sections, providers can speak naturally while your application receives intermediate and final transcripts to insert, review, and save.
Audio Dictation lets you convert provider speech into transcribed text while a Dictation session is active. Providers and patients speak and your application receives intermediate and final transcripts in real time. You insert that text into a field, note section, or stream it your downstream workflow, then let the provider review and save. Audio Dictation is speech-to-text and is different from ambient note generation workflows. ### When to use Ambient vs Audio Dictation Ambient and Audio Dictation solve different problems. * Use **Ambient** when you want Suki to listen to a clinical conversation and help generate documentation from the encounter. Refer to [Ambient clinical documentation](/documentation/concepts/ambient-clinical-notes/ambient-documentation). * Use **Audio Dictation** when the provider needs direct control over the exact content, wording, structure, and pace of documentation. In most scenarios, organizations need both. Design your UX so providers know when to start ambient, when to switch into Dictation, and when to use Dictation to correct ambient-generated content. When you use Audio Dictation, it helps clinicians to: * Speak naturally and receive transcribed text in real time. * Insert text into fields, note sections, or a scratchpad without manual typing. * Correct transcript text while clinical context is still fresh. * Save or submit documentation after review. **What you build for Audio Dictation to work** * You need to choose where dictated text should land in your application. * Capture provider speech with Dictation APIs, Web SDK, or Dictation SDK modalities. * Receive intermediate and final transcript text. * Insert text into the active target in your application, then let the provider review and save the transcript text. ## Choose your path to build Audio Dictation Suki provides three integration options for Audio Dictation workflows. Pick the one that matches how much UI and streaming control you want Suki to own, and how much you want to own, then open the matching quickstart to get started. **If you need:** full control over sessions, WebSocket audio, and transcript handling in your own UI. Your application owns create session, stream audio, render transcripts, and save text.
Dictation Basic Usage
**If you need:** browser-based Dictation inside your own page layout and fields. Suki provides Dictation components and shared auth. Your application owns field focus and where final text goes.
Web SDK Dictation
**If you need:** hosted iframe-based Dictation with in-field or scratchpad modes. Suki manages the hosted Dictation experience. Your application handles callbacks that insert text into your UI.
Dictation SDK Quickstart
Use this table if you are still deciding which modality to use: | Scenario | Best fit | | ---------------------------------------------------------------------------------------- | -------------- | | You create sessions, stream on `/ws/transcribe`, and handle transcripts in your own code | Dictation APIs | | Your backend or non-browser client owns audio capture | Dictation APIs | | Browser app in JavaScript or React with your own page layout and fields | Web SDK | | Dictation into a specific input with a Suki-hosted iframe | Dictation SDK | | Dictation in a scratchpad panel, not tied to one field | Dictation SDK | Do not have credentials yet? Complete the following steps: * Complete [Partner onboarding](/documentation/get-started/partner-onboarding) * Then [Partner authentication](/documentation/how-to/partner-authentication) to get an `sdp_suki_token` * Staging base URL for API examples: `https://sdp.suki-stage.com` or ask your Suki representative for the staging base URL. ### Verify your first Dictation workflow Before you design the full production workflow for Audio Dictation, confirm that your staging integration can complete the Dictation path for the product you chose: * Authenticate successfully for your chosen product. * Start Dictation against a real target in your UI, such as a field, note section, or scratchpad. * Capture provider speech. * Receive transcript text in your UI or SDK callbacks. * Insert or display that text in the active target. * Let the provider correct the text, then save it in your application. After you have verified that your Dictation path works end to end on staging, continue with field targeting, mode choice, and rollout measurement for production. ## How Audio Dictation works Across products, the clinician workflow for Audio Dictation is the same. The only difference is who owns each step. Refer to the table below to see who owns each step for each modality. ```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}} flowchart LR A[Provider chooses field
or note section] --> B[Start dictation] B --> C[Capture speech] C --> D[Receive transcript
text] D --> E[Insert text into
active target] E --> F[Provider reviews
and corrects] F --> G[Save documentation] style A fill:#FFF394,stroke:#333,color:#000 style B fill:#FFF394,stroke:#333,color:#000 style C fill:#FFF394,stroke:#333,color:#000 style D fill:#FFF394,stroke:#333,color:#000 style E fill:#FFF394,stroke:#333,color:#000 style F fill:#FFF394,stroke:#333,color:#000 style G fill:#FFF394,stroke:#333,color:#000 ``` | Step | Dictation SDK | Web SDK | Dictation APIs | | ------------------- | ------------------------------- | ------------------------------ | ---------------------------------------- | | Start Dictation | Hosted iframe / SDK controls | SDK Dictation components | Your app creates the session | | Capture audio | Hosted experience | Browser capture in SDK | Your app streams over WebSocket | | Get transcript text | Callbacks | Component events and callbacks | Your app handles transcript frames | | Place text in UI | Your app inserts from callbacks | Your app owns field targets | Your app owns rendering and insert logic | If you are building with Partner APIs, follow [Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage) for how to create a session, stream audio, receive transcripts, and end the session. ## Decide before you build your workflow Before you pick Dictation APIs, Web SDK, or Dictation SDK for production, align on a few product decisions. Agree where dictated text lands, which Dictation mode you need, how providers move between fields, and how Ambient and Dictation work together if you offer both. These choices shape UX, integration timeline, and which Suki products you combine for a best-fit solution. Use the following sections to align your team. Be clear about **where** transcript text goes in your application. Common targets includes * free-text note editor * single chart field * note section * scratchpad panel Dictation returns speech-to-text. It does not generate an Ambient clinical note or Form filling structured fields. Start with one target workflow, for example one high-use chart field or one note section. A focused first path is easier to pilot and measure. Ambient and Dictation solve different problems. Ambient listens to the visit and generates a structured clinical note after the session ends. Dictation gives the provider real-time control over exact wording in a field or note area. Many organizations need both. Decide early whether your app supports Dictation only, or Ambient plus Dictation. Make the choice obvious in the UI. Providers should know when to run an ambient session for the visit and when to dictate into a field, including when Dictation is used to correct ambient-generated text. Mode choice depends on the product you use: * **In-field Dictation:** Hosted Dictation over a specific input. Supported by [Dictation SDK](/dictation-sdk/guides/in-field-mode) and Web SDK Dictation (`mode="in-field"`). * **Scratchpad Dictation:** Hosted Dictation in a panel that is not tied to one field. Supported by [Dictation SDK](/dictation-sdk/guides/scratchpad-mode) and Web SDK Dictation (`mode="scratchpad"`). * **API-owned UI:** Your application owns create session, `/ws/transcribe` streaming, transcript rendering, and insert logic. Use [Dictation APIs](/documentation/how-to/dictation/dictation-basic-usage). Pick the mode that matches how providers move through documentation. Do not force scratchpad UX when the workflow is one focused field. Decide when transcript text becomes part of the chart. For Dictation SDK and Web SDK Dictation, commit text through callbacks such as `onSubmit`, and optionally `onDraft` when the provider leaves without a final commit. Use a stable `fieldId` so your app knows which field to update. You can seed Dictation with `initialText` when the field already has content. For Dictation APIs, your application owns how partial and final transcript frames update the UI, and when the provider saves the final text in your EHR workflow. Partner webhooks for session completion are documented for Ambient and Form filling workflows. Dictation integrations rely on the live WebSocket transcript path and your application save logic. Providers should be able to correct transcript text while the visit context is still fresh. Decide: * Whether correction happens in the field as text arrives, or after a longer dictate completes. * How providers switch fields without inserting navigation commands into clinical text. * When documentation is final in your application: save, sign, or submit. If your application supports voice commands, handle those commands in your app workflow. Keep commands separate from dictated clinical text so a navigation command does not become part of the note. ## Design the clinician workflow After those decisions are clear, turn them into a Dictation workflow your team can build. Use this table to align on the answers. | Question | Example answer | Why it matters | | :------------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Where does dictated text land? | One chart field, then expand | Dictation is for exact wording you place in your UI. For structured medical forms, use [Form filling](/documentation/concepts/form-filling/form-filling). | | In-field, scratchpad, or API-owned UI? | In-field for focused charting | Mode choice drives Dictation SDK and Web SDK setup. API path means you own the full UI. | | How do providers move between fields? | Explicit field focus in your app | Avoid treating navigation speech as clinical text. | | How should providers review output? | Correct live in the field | Live correction works better than waiting until the end of a long dictate. | | When is documentation final? | Save after provider review | Make save, sign, and submit states explicit in your application. | | Do you also offer Ambient? | Yes, separate entry points | Providers need a clear Ambient vs Dictation path. See [Ambient clinical documentation](/documentation/concepts/ambient-clinical-notes/ambient-documentation). | Across Suki's products, the path stays the same: choose a target, start Dictation, capture speech, receive transcript text, insert it, then let the provider review and save. ## How to implement Audio Dictation Next, align on the following implementation choices. These choices decide which Dictation product you use, how audio is captured, and how text reaches your UI. ### 1. Map the end-to-end Dictation workflow Walk the documentation task from focused field to saved text. For each step, name who owns it: your app, Suki hosted UI, or your backend. Typical stages: 1. Provider focuses a field, note section, or scratchpad target. 2. Start Dictation for that target. 3. Capture provider speech. 4. Receive intermediate and final transcript text. 5. Insert text into the active target. 6. Let the provider correct the text, then save it in your application. If you also ship Ambient, map the handoff between ambient note review and Dictation correction so providers are not unsure which product to use. ### 2. Choose your audio capture strategy Dictation quality depends on clear speech capture and a stable real-time transcript path. Pick the product that matches who should own the microphone UI and transcript handling. | Capture path | Best for | What you own | Where to start | | :-------------------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- | | **Dictation SDK** | Hosted iframe Dictation with in-field or scratchpad modes | Field targeting, `fieldId`, callbacks (`onSubmit`, optional `onDraft`), save logic | [Dictation SDK quickstart](/dictation-sdk/quickstart) | | **Web SDK Dictation** | Browser apps already on `@suki-sdk/js` or `@suki-sdk/react` | Field focus, mode (`in-field` or `scratchpad`), where final text goes | [Web SDK Dictation](/web-sdk/dictation-overview) | | **Dictation APIs** | Custom UI or non-browser capture you control | Create session, `/ws/transcribe` frames, transcript rendering, end session | [Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage) | For Dictation APIs, stream on **`GET /ws/transcribe`**. Send audio as documented for Dictation, use **`AUDIO_END`** when an utterance finishes, and handle partial and final frames with `is_final`. One Dictation session can support multiple speech bursts when the session returns to `READY` or `IDLE`. Refer to [Dictation audio streaming](/documentation/how-to/audio-streaming/dictation-streaming) and [Audio capture best practices](/documentation/how-to/audio-streaming/audio-capture-best-practices). #### Design for clean real-time audio Good audio is critical for Audio Dictation quality. Capture clear speech so Suki can return accurate transcript text in real time. Design your Dictation workflow so providers can: * Confirm that recording has started and stopped * See transcript text as speech is processed * Notice microphone or network issues during the session * Correct text while clinical context is still fresh If you use **Dictation APIs**, your application owns the UI, audio streaming, transcript rendering, and save logic. If you use the **Web SDK**, Suki provides Dictation components and your application owns field targets. If you use the **Dictation SDK**, Suki provides the hosted Dictation experience, and your application owns callbacks that insert text into your UI. ### 3. Choose your Dictation mode and commit model Decide how the provider starts Dictation and how text is committed. | Approach | What you configure | Best for | | :--------------- | :------------------------------------------------------------- | :-------------------------------------------- | | **In-field** | Hosted Dictation bound to one input with a stable `fieldId` | Chart fields and note sections | | **Scratchpad** | Hosted Dictation panel, then your app places text where needed | Longer free-text draft before paste or insert | | **API-owned UI** | Your rendering of partial and final transcript frames | Fully custom Dictation UX | For Dictation SDK and Web SDK, implement `onSubmit` so committed text reaches the right field. Use `onDraft` when you need text from an incomplete session. Seed with `initialText` when the field already has content. Refer to [Callbacks](/dictation-sdk/guides/callbacks) for Dictation SDK behavior. ### 4. Place text in your UI and save it Dictation ends when your application has the transcript text the provider accepts. There is no Ambient-style clinical note retrieval step and no documented Dictation partner webhook completion flow. **For Dictation SDK and Web SDK** * Map `fieldId` to the correct input in your UI. * Apply committed text from `onSubmit`. * Save or submit through your existing EHR or chart workflow. **For Dictation APIs** * Update your UI from WebSocket transcript frames. * Keep a cumulative transcript as frames arrive, including the complete transcript returned when you end the session when your integration uses that response. * Persist the final text in your application after provider review. Do not treat Dictation transcript text as ambient note content or Form filling `generated_values`. Keep each product’s output on its own save path. ## Common integration patterns and use cases Design your Dictation integration around where transcribed text must land and whether you own the streaming pipeline yourself or use an SDK. The following patterns show common ways to build Dictation workflows: Capture provider Dictation during in-person encounters and return transcribed text to your documentation workflow. Capture provider Dictation in browser or API workflows used during virtual visits, then place transcript text into your documentation screens. Stream Dictation into note fields, forms, or scratchpad areas using Web SDK or Dictation SDK patterns. Own session lifecycle, audio capture, and transcript handling end to end with Partner REST and WebSocket APIs. ## Measure success for Audio Dictation Treat measurement as something you own. Define what **better** and **worse** means for your Audio Dictation workflow, track it where the work happens (your app + EHR), and use the findings before and after you deploy Dictation in production. | Metric type | Examples you can track | What it tells you | | --------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- | | **Time** | Time to complete a note section, documentation time per encounter | Whether Dictation reduces typing load | | **Quality and trust** | Edits after insert, re-dictate rate, accepted transcript segments | Whether providers trust live transcript text | | **Rework** | Discarded transcripts, sections rewritten from scratch | Whether dictated text needs too much cleanup | | **Reliability** | Session failures, stream failures, empty transcripts | Whether the integration is stable in production | | **Adoption** | Active Dictation users, sessions per provider, fields completed by voice | Whether clinicians use Dictation in real workflows | Start with a small set of metrics, for example time to complete target fields, edit rate after insert, and session failure rate, and later add more metrics as you deploy Dictation in production. ## Next steps **[Dictation audio streaming](/documentation/how-to/audio-streaming/dictation-streaming)** - Stream Dictation audio on `/ws/transcribe`. **[Dictation basic usage](/documentation/how-to/dictation/dictation-basic-usage)** - Build Dictation with Partner APIs when you own the streaming pipeline. **[Web SDK Dictation](/web-sdk/dictation-overview)** - Add Dictation to browser JavaScript or React applications. **[Dictation SDK quickstart](/dictation-sdk/quickstart)** - Embed hosted in-field or scratchpad Dictation. **[Partner authentication](/documentation/how-to/partner-authentication)** - Get an `sdp_suki_token` for API and SDK calls.