feat: pronunciation dictionaries docs

fern/assistants/pronunciation-dictionaries.mdx

@@ -0,0 +1,233 @@
+---
+title: Pronunciation dictionaries
+subtitle: Control how your AI assistant pronounces specific words and phrases
+slug: assistants/pronunciation-dictionaries
+---
+
+## Overview
+
+Pronunciation dictionaries allow you to customize how your AI assistant pronounces specific words, names, acronyms, or technical terms. This feature is particularly useful for ensuring consistent pronunciation of brand names, proper nouns, or industry-specific terminology that might be mispronounced by default.
+
+**Note:** Pronunciation dictionaries are exclusive to ElevenLabs voices and require specific model configurations.
+
+## How Pronunciation Dictionaries Work
+
+<Steps>
+  <Step title="Create Pronunciation Rules">
+    Define specific words or phrases and how they should be pronounced using either phonetic notation or word substitutions.
+  </Step>
+
+  <Step title="Upload Dictionary to Vapi">
+    Create a pronunciation dictionary through Vapi's API with your custom rules.
+  </Step>
+
+  <Step title="Configure Your Assistant">
+    Associate the pronunciation dictionary with your assistant's voice configuration.
+  </Step>
+
+  <Step title="Automatic Application">
+    When your assistant encounters the specified words during conversation, it will use your custom pronunciations automatically.
+  </Step>
+</Steps>
+
+## Sample Audio Examples
+
+Below are examples demonstrating the difference between pronunciations with and without pronunciation dictionaries:
+
+Corrected pronunciations:
+- "Nginx" → "Engine-X" (using alias rule)
+- "Kubernetes" → "/ˌkuːbərˈneɪtiːz/" (using phoneme rule)
+
+**Without Pronunciation Dictionary:**
+<audio controls src="/static/audio/without-pronunciation-dictionary.wav">Your browser does not support the audio element.</audio>
+
+**With Pronunciation Dictionary:**
+<audio controls src="/static/audio/with-pronunciation-dictionary.wav">Your browser does not support the audio element.</audio>
+
+
+## Prerequisites
+
+- A Vapi assistant configured with an ElevenLabs voice
+- Understanding of phonetic notation (IPA or CMU Arpabet) for phoneme-based rules
+- Access to Vapi's API for dictionary creation
+
+## Types of Pronunciation Rules
+
+### Phoneme Rules
+
+Phoneme rules specify exact pronunciation using phonetic alphabets. These provide the most precise control over pronunciation.
+
+**Supported Alphabets:**
+- **IPA (International Phonetic Alphabet)**: More universal, uses symbols like `/tə'meɪtoʊ/`
+- **CMU Arpabet**: ASCII-based format, uses notation like `T AH M EY T OW`
+
+**Model Compatibility:**
+Phoneme rules only work with specific ElevenLabs models:
+- `eleven_turbo_v2`
+- `eleven_flash_v2`
+
+### Alias Rules
+
+Alias rules replace words with alternative spellings or phrases. These work with all ElevenLabs models and are useful for:
+- Converting acronyms to full phrases (e.g., "UN" → "United Nations")
+- Providing phonetic spellings for difficult words
+- Standardizing pronunciation across different contexts
+
+## Implementation
+
+<Steps>
+  <Step title="Create a Pronunciation Dictionary">
+    Use Vapi's API to create a pronunciation dictionary with your custom rules.
+
+    ```bash
+    POST https://api.vapi.ai/provider/11labs/pronunciation-dictionary
+    Content-Type: application/json
+    Authorization: Bearer YOUR_API_KEY
+    ```
+
+    ```json
+    {
+      "name": "My Custom Dictionary",
+      "rules": [
+        {
+          "stringToReplace": "tomato",
+          "type": "phoneme",
+          "phoneme": "/tə'meɪtoʊ/",
+          "alphabet": "ipa"
+        },
+        {
+          "stringToReplace": "Vapi",
+          "type": "phoneme", 
+          "phoneme": "V AE P IY",
+          "alphabet": "cmu-arpabet"
+        },
+        {
+          "stringToReplace": "UN",
+          "type": "alias",
+          "alias": "United Nations"
+        }
+      ]
+    }
+    ```
+
+    The API will respond with:
+    ```json
+    {
+      "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
+      "versionId": "xJl0ImZzi3cYp61T0UQG",
+      "name": "My Custom Dictionary",
+      "rules": [...],
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+    ```
+  </Step>
+
+  <Step title="Configure Your Assistant's Voice">
+    Update your assistant configuration to use the pronunciation dictionary.
+
+    ```json
+    {
+      "voice": {
+        "model": "eleven_turbo_v2_5",
+        "voiceId": "sarah",
+        "provider": "11labs",
+        "stability": 0.5,
+        "similarityBoost": 0.75,
+        "pronunciationDictionaryLocators": [
+          {
+            "pronunciationDictionaryId": "rjshI10OgN6KxqtJBqO4",
+            "versionId": "xJl0ImZzi3cYp61T0UQG"
+          }
+        ]
+      }
+    }
+    ```
+
+    <Note>
+      When a pronunciation dictionary is added, SSML parsing will be automatically enabled for your assistant.
+    </Note>
+  </Step>
+
+  <Step title="Test Your Pronunciation">
+    Create a test call or use the Vapi playground to verify that your custom pronunciations are working correctly.
+  </Step>
+</Steps>
+
+## Using Your Own ElevenLabs Account (BYOK)
+
+If you're using your own ElevenLabs API key (Bring Your Own Key), you can create pronunciation dictionaries directly in your ElevenLabs account and reference them in Vapi:
+
+1. Create a pronunciation dictionary in your ElevenLabs account
+2. Note the `pronunciationDictionaryId` and `versionId` from ElevenLabs
+3. Use these IDs in your Vapi assistant configuration:
+
+```json
+{
+  "voice": {
+    "model": "eleven_turbo_v2_5",
+    "voiceId": "your-voice-id",
+    "provider": "11labs",
+    "pronunciationDictionaryLocators": [
+      {
+        "pronunciationDictionaryId": "your-elevenlabs-dict-id",
+        "versionId": "your-elevenlabs-version-id"
+      }
+    ]
+  }
+}
+```
+
+## Managing Pronunciation Dictionaries
+
+### List Your Dictionaries
+
+```bash
+GET https://api.vapi.ai/provider/11labs/pronunciation-dictionary
+Authorization: Bearer YOUR_API_KEY
+```
+
+### Update Dictionary Rules
+
+```bash
+PATCH https://api.vapi.ai/provider/11labs/pronunciation-dictionary/{dictionaryId}
+Content-Type: application/json
+Authorization: Bearer YOUR_API_KEY
+```
+
+```json
+{
+  "rules": [
+    {
+      "stringToReplace": "tomato",
+      "type": "phoneme",
+      "phoneme": "/tə'mɑːtoʊ/",
+      "alphabet": "ipa"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+<Note>
+- **Case Sensitivity**: Pronunciation dictionary searches are case-sensitive. Create separate entries for different capitalizations if needed.
+- **Order Matters**: Rules are applied in the order they appear in the dictionary. The first matching rule is used.
+- **Testing**: Always test pronunciation changes with your specific voice and model combination.
+- **Phoneme Accuracy**: Ensure proper stress marking for multi-syllable words when using phoneme rules.
+- **Model Compatibility**: Remember that phoneme rules only work with specific ElevenLabs models.
+</Note>
+
+## Common Issues
+
+**Pronunciation Not Applied**
+- Verify you're using a compatible ElevenLabs model for phoneme rules
+- Check that the `stringToReplace` exactly matches the text in your content (case-sensitive)
+- Ensure the pronunciation dictionary is properly referenced in your voice configuration
+
+**SSML Conflicts**
+- When pronunciation dictionaries are enabled, SSML parsing is automatically activated
+- Ensure any existing SSML tags in your content are properly formatted
+
+**Performance Impact**
+- Large dictionaries may slightly increase processing time
+- Consider organizing rules by frequency of use for optimal performance 

fern/docs.yml

@@ -146,6 +146,8 @@ navigation:
                 path: assistants/assistant-hooks.mdx
               - page: Background speech denoising
                 path: assistants/background-speech-denoising.mdx
+              - page: Pronunciation dictionaries
+                path: assistants/pronunciation-dictionaries.mdx
           - section: Model configurations
             icon: fa-light fa-waveform-lines
             contents: