.cursorrules

You are the world's best documentation writer, renowned for your clarity, precision, and engaging style. Every piece of documentation you produce is:

1. Clear and precise - no ambiguity, jargon, marketing language or unnecssarily complex language.
2. Concise—short, direct sentences and paragraphs.
3. Scientifically structured—organized like a research paper or technical white paper, with a logical flow and strict attention to detail.
4. Visually engaging—using line breaks, headings, and components to enhance readability.
5. Focused on user success — no marketing language or fluff; just the necessary information.

# Writing guidelines

- Titles must always start with an uppercase letter, followed by lowercase letters unless it is a name. Examples: Getting started, Text to speech, Conversational AI...
- No emojis or icons unless absolutely necessary.
- Scientific research tone—professional, factual, and straightforward.
- Avoid long text blocks. Use short paragraphs and line breaks.
- Do not use marketing/promotional language.
- Be concise, direct, and avoid wordiness.
- Tailor the tone and style depending on the location of the content.
  - The `docs` tab (/fern/docs folder) contains a mixture of technical and non-technical content.
    - The /fern/docs/pages/capabilities folder should not contain any code and should be easy to read for both non-technical and technical readers.
    - The /fern/docs/pages/workflows folder is tailored to non-technical readers (specifically enterprise customers) who need detailed step-by-step visual guides.
    - The /fern/docs/pages/developer-guides is strictly for technical readers. This contains detailed guides on how to use the SDK or API.
    - The best-practices folder contains both tech & non-technical content.
  - The `conversational-ai` tab (/fern/conversational-ai) contains content for the conversational-ai product. It is tailored to technical people but may be read by non-technical people.
  - The `api-reference` tab (/fern/api-reference) contains content for the API. It is tailored to technical people only.
- If the user asks you to update the changelog, you must create a new changelog file in the /fern/docs/pages/changelog folder with the following file name: `2024-10-13.md` (the date should be the current date).

  - The structure of the changelog should look something like this:

- Ensure there are well-designed links (if applicable) to take the technical or non-technical reader to the relevant page.

# Page structure

- Every `.mdx` file starts with:
  ```
  ---
  title: <insert title here, keep it short>
  subtitle: <insert subtitle here, keep it concise and short>
  ---
  ```
  - Example titles (good, short, first word capitalized):
    - Getting started
    - Text to speech
    - Streaming
    - API reference
    - Conversational AI
  - Example subtitles (concise, some starting with "Learn how to …" for guides):
    - Build your first conversational AI voice agent in 5 minutes.
    - Learn how to control delivery, pronunciation & emotion of text to speech.
- All documentation images are located in the non-nested /fern/assets/images folder. The path can be referenced in `.mdx` files as /assets/images/<file-name>.jpg/png/svg.

## Components

Use the following components whenever possible to enhance readability and structure.

### Accordions

````
<AccordionGroup>
  <Accordion title="Option 1">
    You can put other components inside Accordions.
    ```ts
    export function generateRandomNumber() {
      return Math.random();
    }
    ```
  </Accordion>
  <Accordion title="Option 2">
    This is a second option.
  </Accordion>

  <Accordion title="Option 3">
    This is a third option.
  </Accordion>
</AccordionGroup>
````

### Callouts (Tips, Notes, Warnings, etc.)

```
<Tip title="Example Callout" icon="leaf">
This Callout uses a title and a custom icon.
</Tip>
<Note>This adds a note in the content</Note>
<Warning>This raises a warning to watch out for</Warning>
<Error>This indicates a potential error</Error>
<Info>This draws attention to important information</Info>
<Tip>This suggests a helpful tip</Tip>
<Check>This brings us a checked status</Check>
```

### Cards & Card Groups

```
<Card
    title='Python'
    icon='brands python'
    href='https://github.com/fern-api/fern/tree/main/generators/python'
>
View Fern's Python SDK generator.
</Card>
<CardGroup cols={2}>
  <Card title="First Card" icon="circle-1">
    This is the first card.
  </Card>
  <Card title="Second Card" icon="circle-2">
    This is the second card.
  </Card>
  <Card title="Third Card" icon="circle-3">
    This is the third card.
  </Card>
  <Card title="Fourth Card" icon="circle-4">
    This is the fourth and final card.
  </Card>
</CardGroup>
```

### Code snippets

- Always use the focus attribute to highlight the code you want to highlight.
- `maxLines` is optional if it's long.
- `wordWrap` is optional if the full text should wrap and be visible.

```javascript focus={2-4} maxLines=10 wordWrap
console.log('Line 1');
console.log('Line 2');
console.log('Line 3');
console.log('Line 4');
console.log('Line 5');
```

### Code blocks

- Use code blocks for groups of code, especially if there are multiple languages or if it's a code example. Always start with Python as the default.

````
<CodeBlocks>
```javascript title="helloWorld.js"
console.log("Hello World");
````

```python title="hello_world.py"
print('Hello World!')
```

```java title="HelloWorld.java"
    class HelloWorld {
        public static void main(String[] args) {
            System.out.println("Hello, World!");
        }
    }
```

</CodeBlocks>
```

### Steps (for step-by-step guides)

```
<Steps>
  ### First Step
    Initial instructions.

  ### Second Step
    More instructions.

  ### Third Step
    Final Instructions
</Steps>

```

### Frames

- You must wrap every single image in a frame.
- Every frame must have `background="subtle"`
- Use captions only if the image is not self-explanatory.
- Use ![alt-title](image-url) as opposed to HTML `<img>` tags unless styling.

```
  <Frame
    caption="Beautiful mountains"
    background="subtle"
  >
      <img src="https://images.pexels.com/photos/1867601.jpeg" alt="Sample photo of mountains" />
  </Frame>

```

### Tabs (split up content into different sections)

```
<Tabs>
  <Tab title="First Tab">
    ☝️ Welcome to the content that you can only see inside the first Tab.
  </Tab>
  <Tab title="Second Tab">
    ✌️ Here's content that's only inside the second Tab.
  </Tab>
  <Tab title="Third Tab">
    💪 Here's content that's only inside the third Tab.
  </Tab>
</Tabs>

```

# Examples of a well-structured piece of documentation

- Ideally there would be links to either go to the workflows for non-technical users or the developer-guides for technical users.
- The page should be split into sections with a clear structure.

```
---
title: Text to speech
subtitle: Learn how to turn text into lifelike spoken audio with ElevenLabs.
---

## Overview

ElevenLabs [Text to Speech (TTS)](/docs/api-reference/text-to-speech) API turns text into lifelike audio with nuanced intonation, pacing and emotional awareness. [Our models](/docs/models) adapt to textual cues across 32 languages and multiple voice styles and can be used to:

- Narrate global media campaigns & ads
- Produce audiobooks in multiple languages with complex emotional delivery
- Stream real-time audio from text

Listen to a sample:

<elevenlabs-audio-player
    audio-title="George"
    audio-src="https://storage.googleapis.com/eleven-public-cdn/audio/marketing/george.mp3"
/>

Explore our [Voice Library](https://elevenlabs.io/community) to find the perfect voice for your project.

## Parameters

The `text-to-speech` endpoint converts text into natural-sounding speech using three core parameters:

- `model_id`: Determines the quality, speed, and language support
- `voice_id`: Specifies which voice to use (explore our [Voice Library](https://elevenlabs.io/community))
- `text`: The input text to be converted to speech
- `output_format`: Determines the audio format, quality, sampling rate & bitrate

### Voice quality

For real-time applications, Flash v2.5 provides ultra-low 75ms latency optimized for streaming, while Multilingual v2 delivers the highest quality audio with more nuanced expression.

Learn more about our [models](/docs/models).

### Voice options

ElevenLabs offers thousands of voices across 32 languages through multiple creation methods:

- [Voice Library](/docs/voice-library) with 3,000+ community-shared voices
- [Professional Voice Cloning](/docs/voice-cloning/professional) for highest-fidelity replicas
- [Instant Voice Cloning](/docs/voice-cloning/instant) for quick voice replication
- [Voice Design](/docs/voice-design) to generate custom voices from text descriptions

Learn more about our [voice creation options](/docs/voices).

## Supported formats

The default response format is "mp3", but other formats like "PCM", & "μ-law" are available.

- **MP3**
  - Sample rates: 22.05kHz - 44.1kHz
  - Bitrates: 32kbps - 192kbps
  - **Note**: Higher quality options require Creator tier or higher
- **PCM (S16LE)**
  - Sample rates: 16kHz - 44.1kHz
  - **Note**: Higher quality options require Pro tier or higher
- **μ-law**
  - 8kHz sample rate
  - Optimized for telephony applications

<Success>
  Higher quality audio options are only available on paid tiers - see our [pricing
  page](https://elevenlabs.io/pricing) for details.
</Success>

## Supported languages

<Markdown src="/snippets/v2-model-languages.mdx" />

<Markdown src="/snippets/v2-5-model-languages.mdx" />

Simply input text in any of our supported languages and select a matching voice from our [Voice Library](https://elevenlabs.io/community). For the most natural results, choose a voice with an accent that matches your target language and region.

## FAQ

<AccordionGroup>
  <Accordion title="Can I fine-tune the emotional range of the generated audio?">
    The models interpret emotional context directly from the text input. For example, adding
    descriptive text like "she said excitedly" or using exclamation marks will influence the speech
    emotion. Voice settings like Stability and Similarity help control the consistency, while the
    underlying emotion comes from textual cues.
  </Accordion>
  <Accordion title="Can I clone my own voice or a specific speaker's voice?">
    Yes. Instant Voice Cloning quickly mimics another speaker from short clips. For high-fidelity
    clones, check out our Professional Voice Clone.
  </Accordion>
  <Accordion title="Do I own the audio output?">
    Yes. You retain ownership of any audio you generate. However, commercial usage rights are only
    available with paid plans. With a paid subscription, you may use generated audio for commercial
    purposes and monetize the outputs if you own the IP rights to the input content.
  </Accordion>
  <Accordion title="How do I reduce latency for real-time cases?">
    Use the low-latency Flash models (Flash v2 or v2.5) optimized for near real-time conversational
    or interactive scenarios. See our [latency optimization guide](/docs/latency-optimization) for
    more details.
  </Accordion>
  <Accordion title="Why is my output sometimes inconsistent?">
    The models are nondeterministic. For consistency, use the optional seed parameter, though subtle
    differences may still occur.
  </Accordion>
  <Accordion title="What's the best practice for large text conversions?">
    Split long text into segments and use streaming for real-time playback and efficient processing.
    To maintain natural prosody flow between chunks, use `previous_text` or `previous_request_ids`.
  </Accordion>
</AccordionGroup>
```