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

# Smart Punctuation Integration Guide

> Learn how to prevent unexpected whitespace from being added in your text when smart punctuation is supported by the editor

Speech to text can be used to create a verbatim transcript of the audio; however, punctuation is essential for coherent documentation. Two settings are available for users to control how [punctuation](/stt/punctuation) is added during dictation/transcription: `spokenPunctuation` and `automaticPunctuation`. These settings are mutually exclusive, and when both are set to true in the configuration, `spokenPunctuation` will take precedence over `automaticPunctuation`.

Some applications provide support for **"smart punctuation"**: Transformation of plain ASCII characters to look nicer and be more readable in modern text editors. Such smart transformations, however, can cause issues with speech-to-text integrations. This guide will explain how to render punctuation correctly so that extra whitespace is not unexpectedly added into the text.

<Tip>
  The goal of this guide is to ensure text from Corti speech to text presents consistently across all applications, without unwanted substitutions, spacing, or character transformations.
</Tip>

***

## Core Principal

* Insert **plain Unicode punctuation** exactly as received from STT (e.g., `U+0022` for `"`, `U+0027` for `'`, `U+000A` for line breaks, etc.)
* Disable or bypass any "smart punctuation" or auto-formatting features in the target editor when possible

## Recommendations for Correct Handling of Smart Punctuation

| Punctuation                                   | "Smart" form | Risk                                                    | Correct Handling                                                                                                |
| :-------------------------------------------- | :----------: | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Quotes** (`"`, `'`)                         |    “ ” ‘ ’   | Adds spaces or mis-guesses direction                    | Disable smart quotes; trim spaces before/after                                                                  |
| **Apostrophes** (`'`)                         |       ’      | Curly apostrophe may break contractions                 | Keep '; use `U+2019` only if deliberate typography                                                              |
| **New line** (`\n`)                           |              | Some editors auto-convert to paragraph breaks or ignore | Preserve \n as single line break; map explicitly to platform’s line-separator rule                              |
| **New paragraph** (`\n\n`)                    |              | May collapse or double-space inconsistently             | Treat as paragraph boundary; insert exactly two newlines unless target API defines separate paragraph insertion |
| **Hyphens or Dashes** (`-`)                   |       —      | Converts to en/em dash; may add or remove spaces        | STT should output only the hyphen `U+002D`; disable dash substitution; define spacing manually                  |
| **Ellipsis** (`...`)                          |       …      | Single-character ellipsis affects truncation logic      | Keep `...`; insert `U+2026` only for typographic output                                                         |
| **Fractions or Symbols** (`1/2`, `%`, `(tm)`) |     ½ % ©    | Encoding or semantic changes                            | Insert literal ASCII; disable replacements                                                                      |
| **Non-breaking space**                        |   `U+00A0`   | Alters spacing, wrapping, or copy/paste                 | Normalize to standard space `U+0020`                                                                            |

## Specific Handling for the Most Common Edit Controls

| Environment                                                      | Behavior                                        | Integration Recommendation                                                             |
| :--------------------------------------------------------------- | :---------------------------------------------- | :------------------------------------------------------------------------------------- |
| **Windows** <br />(`Edit`, `TextBox`, `RichEdit`, `WPF TextBox`) | Generally plain text; some intercept key events | Insert text directly via API, not simulated typing                                     |
| **macOS or iOS** <br />(`NSTextView`, `UITextView`)              | Smart punctuation enabled by default            | Set `smartQuotesType = .no`, `smartDashesType = .no`, `smartInsertDeleteType = .no`    |
| **Web** <br />(`<input>`, `<textarea>`, `contentEditable`)       | Plugins may alter punctuation                   | Disable plugins or escape entities (`&quot;`, `&#39;`)                                 |
| **PowerBuilder / TX / TE Edit**                                  | Uses OS substitution rules                      | Insert via API; trim spaces post-insert                                                |
| **EHRs or other native applications**                            | Proprietary editors                             | Insert via official text APIs; never simulate typing; normalize spaces after insertion |
| **Microsoft Word / Office**                                      | AutoCorrect substitutions                       | Turn off "Smart Quotes," "Hyphens with Dash," and "Replace three dots with ellipsis"   |
| **Apple Pages / TextEdit**                                       | Substitutions per document                      | Turn off substitutions: Edit → Substitutions → disable Smart Quotes/Dashes             |

## Normalizing Spacing and Hidden Characters

| Problem                        | Regex Correction |
| :----------------------------- | :--------------- |
| Space after opening quote      | `([“‘])\s+ → \1` |
| Space before closing quote     | `\s+([”’]) → \1` |
| Extra space around hyphen/dash | `\s*-\s* → -`    |
| Non-breaking space             | `\u00A0 →`       |
| Redundant newlines             | `\n{3,} → \n\n`  |

## Recap / Integration Checklist

| Step | Action                                                                                                                                                                                                             |
| :--: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   1  | Insert STT text via API (no keystroke simulation)                                                                                                                                                                  |
|   2  | Disable smart punctuation features per control                                                                                                                                                                     |
|   3  | Escape text when passing through HTML or CMS layers                                                                                                                                                                |
|   4  | Normalize spaces, hyphens, and line breaks post-insert                                                                                                                                                             |
|   5  | Test standard and edge cases to ensure comprehensive coverage of expected punctuation use                                                                                                                          |
|      | <Check>**Result**: All punctuation (quotes, apostrophes, dashes, ellipses, spaces, and line breaks) renders consistently across editors and applications, with no hidden formatting or spacing artifacts. </Check> |

<br />

<Note>Please [contact us](https://help.corti.app) if you have questions or need further assistance.</Note>