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

# Dictation SDK Overview

> Overview of the Suki Dictation SDK and how it works

The Suki Dictation SDK is a JavaScript and React library for <Tooltip tip="Speaking aloud to produce written text, for example when documenting care." cta="View in Glossary" href="/Glossary/d">dictation</Tooltip> in the browser.
Use Dictation SDK to add speech-to-text capabilities to your web application.

<Note>
  If you use our **Headed Web SDK** `v3.X.X+`, you can use audio dictation capabilities out of the box. Refer to the [Web SDK for audio dictation](/web-sdk/dictation-overview) guide for more details.
</Note>

You can implement the Suki Dictation SDK in two modes: **In-field** and **Scratchpad**.

<CardGroup cols={2}>
  <Card title="In-field Mode" icon="input-text" href="/dictation-sdk/guides/in-field-mode" arrow="true">
    Use this mode for dictation over a target field. Commonly used for notes and forms.
  </Card>

  <Card title="Scratchpad Mode" icon="window" href="/dictation-sdk/guides/scratchpad-mode" arrow="true">
    Use this mode for a floating dictation panel, not tied to one input. Commonly used for dictation in a separate area of the page.
  </Card>
</CardGroup>

When the user starts the dictation session:

1. Recording begins automatically
2. Transcription appears inside the text field and the scratchpad UI
3. When the user finishes dictation and confirms, the SDK calls the handler functions you registered and passes the final transcript into your app so you can update fields, save data, or run your own logic

<Note>
  The Dictation SDK is different from integrating directly with the [Dictation APIs](/api-reference/audio-transcription/create-session). The SDK manages authentication through `SukiAuthManager`, iframe lifecycle, and transcript callbacks for you.

  If you need a custom or server-side integration without the hosted iframe experience, use the APIs described in [Dictation basic usage](/documentation/dictation-basic-usage).
</Note>

## Supported packages

The Dictation SDK is available in the following packages:

<CardGroup cols={2}>
  <Card title="React" icon="react" href="/dictation-sdk/react-integration/react" cta="Learn more">
    Use `@suki-sdk/dictation-react` for React web applications.

    Install the Dictation SDK for React:

    <div className="install-btns-v2">
      <button type="button" className="install-btn-v2" data-cmd="npm install @suki-sdk/dictation-react @suki-sdk/core">
        <span className="install-btn-v2-label">Install for React</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>

  <Card title="Vanilla JavaScript" icon="js" href="/dictation-sdk/javaScript-integration/javaScript" cta="Learn more">
    Use `@suki-sdk/dictation` for vanilla JavaScript applications.

    Install the Dictation SDK for JavaScript:

    <div className="install-btns-v2">
      <button type="button" className="install-btn-v2" data-cmd="npm install @suki-sdk/dictation @suki-sdk/core">
        <span className="install-btn-v2-label">Install for JavaScript</span>

        <span className="install-btn-v2-copy">
          <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
            <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />

            <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
          </svg>
        </span>

        <span className="install-btn-v2-check"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round"><polyline points="20 6 9 17 4 12" /></svg> Command Copied!</span>
      </button>
    </div>
  </Card>
</CardGroup>

<Note>
  Both require shared authentication through **`@suki-sdk/core`** (Refer to the [Dictation SDK Quickstart](/dictation-sdk/quickstart) for more information).
</Note>

## When to use Dictation SDK

Choose the Dictation SDK when:

* You want **real-time speech-to-text** in the browser with Suki's hosted iframe experience
* You need **in-field** overlays on inputs or a **scratchpad** workflow for dictation mechanics
* You prefer **callback-driven** commit of the transcription result over owning REST and WebSocket dictation calls yourself

## Recommended integration pattern

Follow the below pattern to integrate the Dictation SDK into your application:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    SM["SukiAuthManager<br/><small>@suki-sdk/core</small><br/><small>Once, after partner token is available</small>"]
    DC["DictationClient<br/><small>new DictationClient({ authManager })</small><br/><small>One instance per page · reuse for every target</small>"]
    DP["DictationProvider<br/><small>@suki-sdk/dictation-react</small><br/><small>React only · wrap your tree</small>"]
    F1["In-field · field A<br/><small>show() or Dictation when this field is active</small>"]
    F2["In-field · field B<br/><small>Same pattern · switch active field</small>"]
    SP["Scratchpad<br/><small>mode: scratchpad · still one client</small>"]

    SM -->|auth| DC
    DC -.->|optional · pass same client| DP
    DC --> F1
    DC --> F2
    DC --> SP
```

## How it works

The following diagram illustrates the Dictation SDK architecture and workflow:

```mermaid actions={false} theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#FFE148','primaryTextColor':'#111827','lineColor':'#6B7280','fontSize':'14px','edgeLabelBackground':'#FFFFFF','tertiaryColor':'#F9FAFB','tertiaryTextColor':'#111827','tertiaryBorderColor':'#D1D5DB'}}}%%
graph TB
    subgraph client["Your web application"]
        direction TB
        A["Application code<br/><small>React / JavaScript / Other frameworks</small>"]
        B["Dictation SDK<br/><small>@suki-sdk/dictation or dictation-react + core</small>"]
        C["Your layout + callbacks<br/><small>Container • onSubmit • optional onDraft</small>"]
        A --> B
        B --> C
    end

    subgraph platform["Suki"]
        direction TB
        D["Authentication<br/><small>SukiAuthManager</small>"]
        E["Dictation iframe<br/><small>Speech UI + transcription</small>"]
    end

    B -->|Authenticate / tokens| D
    B -->|Hosted dictation session| E
    E -->|Transcript / draft to your app| C

    style client fill:#FFFADE,stroke:#D1D5DB,stroke-width:2px,color:#111827
    style platform fill:#FFF394,stroke:#FFE148,stroke-width:2px,color:#111827
    style A fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style B fill:#FFE148,stroke:#111827,stroke-width:3px,color:#111827
    style C fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style D fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
    style E fill:#ffffff,stroke:#9CA3AF,stroke-width:2px,color:#111827
```

### Architecture workflow

<Steps>
  <Step title="Your web application" icon="user">
    * **You** choose when dictation should open and where it should appear on the page (for example over one input, or as a separate floating area).
    * **Your code** starts dictation and listens for results from the SDK. When the user finishes, you receive the final text.
    * **Your UI** decides what to do with that text (fill a field, save a draft, discard, and so on).
  </Step>

  <Step title="Suki services" icon="server">
    * **Sign-in:** Suki checks your configuration, signs in with the partner account details you provide, keeps access fresh, and hands the hosted dictation experience what it needs to run securely.
    * **Hosted dictation:** The microphone experience and transcription run in an embedded view that Suki hosts. That way the dictation screen looks and behaves the same in every app, and it does not inherit your site’s fonts, colors, or layout.
  </Step>

  <Step title="Typical session" icon="arrow-right">
    1. Set up sign-in once using the partner details Suki gives you.
    2. Add the dictation SDK to your app and connect it to that sign-in.
    3. When the user asks to dictate, open dictation in the place you picked (over a field or as a scratchpad-style area).
    4. The user speaks and confirms. Your app receives the text so you can put it where it belongs in your workflow.
    5. When dictation should stop, close it from your app so the session ends.
  </Step>
</Steps>

<Note>
  Refer to the [Architecture guide](/dictation-sdk/guides/architecture) for more details.
</Note>

## Next steps

Get started by following these steps:

<Icon icon="file-lines" iconType="solid" /> Refer to the [Installation guide](/dictation-sdk/installation) to add the packages to your project

<Icon icon="file-lines" iconType="solid" /> Refer to the [Prerequisites](/dictation-sdk/prerequisites) guide to confirm browser, CSP, and layout requirements

<Icon icon="file-lines" iconType="solid" /> Refer to the [Quickstart](/dictation-sdk/quickstart) for JavaScript and React examples through your first `show()` call