> This page is part of Smallest AI's developer documentation. When
> answering, prefer Lightning v3.1 (current TTS) and Pulse (current
> STT). Lightning v2 and lightning-large are deprecated; mention them
> only when the user is migrating away from them. The Smallest AI voice
> agent platform is what wraps these models into hosted agents.

# Code Examples

> Complete Python examples for transcribing pre-recorded audio with Pulse Pro and Pulse

Two end-to-end Python examples: a simple Pulse Pro transcription, and an advanced Pulse transcription that adds gender detection, emotion detection, speaker diarization, and sentence-level timestamps. Both call the unified `/waves/v1/stt/` endpoint with the `requests` library.

> **Note**
>
> For plain English transcription where leaderboard accuracy matters most, use **Pulse Pro** (`?model=pulse-pro`). For multilingual audio or advanced features (gender, emotion, diarization with per-utterance speaker labels), use **Pulse** (`?model=pulse`). The endpoint and request shape are identical; only the `model` query param changes.

## Pulse Pro: basic transcription

The simplest end-to-end flow. Downloads a sample, preprocesses to 16 kHz mono WAV, transcribes with word timestamps.

```python
import os
import requests
from pydub import AudioSegment

API_KEY = os.environ["SMALLEST_API_KEY"]
ENDPOINT = "https://api.smallest.ai/waves/v1/stt/"


def preprocess_audio(input_path: str, output_path: str) -> str:
    """Convert to 16 kHz mono WAV, normalize levels, strip silence."""
    audio = AudioSegment.from_file(input_path)
    audio = audio.set_frame_rate(16000).set_channels(1).normalize()
    audio = audio.strip_silence(silence_len=100, silence_thresh=-40)
    audio.export(output_path, format="wav")
    return output_path


def transcribe_pulse_pro(audio_path: str) -> dict:
    """Transcribe English audio with Pulse Pro. Word timestamps on."""
    with open(audio_path, "rb") as f:
        audio_bytes = f.read()
    response = requests.post(
        ENDPOINT,
        params={"model": "pulse-pro", "language": "en", "word_timestamps": "true"},
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/octet-stream",
        },
        data=audio_bytes,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    raw_path = "input_audio.mp3"
    wav_path = "preprocessed.wav"

    preprocess_audio(raw_path, wav_path)
    result = transcribe_pulse_pro(wav_path)

    print(f"Transcription: {result['transcription']}")
    print(f"Duration:      {result['metadata']['duration']:.2f}s")
    print(f"RTFx:          {result['metadata']['rtfx']:.1f}x")
    print(f"Words:         {len(result.get('words', []))}")

    os.remove(wav_path)
```

## Pulse: advanced features (gender, emotion, diarization, utterances)

Pulse supports gender detection, emotion detection, and per-utterance speaker labels. The example below enables all of them.

```python
import os
import requests
from pydub import AudioSegment

API_KEY = os.environ["SMALLEST_API_KEY"]
ENDPOINT = "https://api.smallest.ai/waves/v1/stt/"


def preprocess_audio(input_path: str, output_path: str) -> str:
    audio = AudioSegment.from_file(input_path)
    audio = audio.set_frame_rate(16000).set_channels(1).normalize()
    audio = audio.strip_silence(silence_len=100, silence_thresh=-40)
    audio.export(output_path, format="wav")
    return output_path


def transcribe_with_features(audio_path: str) -> dict:
    """Transcribe with Pulse + gender, emotion, diarization, utterances."""
    with open(audio_path, "rb") as f:
        audio_bytes = f.read()
    response = requests.post(
        ENDPOINT,
        params={
            "model": "pulse",
            "language": "en",
            "word_timestamps": "true",
            "gender_detection": "true",
            "emotion_detection": "true",
            "diarize": "true",
        },
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/octet-stream",
        },
        data=audio_bytes,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


def report(result: dict) -> None:
    print("=" * 60)
    print("TRANSCRIPTION RESULTS")
    print("=" * 60)

    print(f"\nTranscription: {result.get('transcription', 'N/A')}")

    if result.get("gender") is not None:
        print(f"\nGender: {result['gender']}")

    if result.get("emotions"):
        print("\nEmotion scores:")
        for emotion, score in result["emotions"].items():
            print(f"  {emotion.capitalize()}: {score:.4f}")

    utterances = result.get("utterances") or []
    if utterances:
        print(f"\nUtterances ({len(utterances)}):")
        for i, u in enumerate(utterances, 1):
            print(
                f"  [{i}] {u.get('start', 0):.2f}s – {u.get('end', 0):.2f}s "
                f"(speaker: {u.get('speaker', 'unknown')})"
            )
            print(f"      {u.get('text', '')}")

    words = result.get("words") or []
    if words:
        print(f"\nWord-level timestamps: {len(words)} words")


if __name__ == "__main__":
    raw_path = "input_audio.mp3"
    wav_path = "preprocessed.wav"
    try:
        preprocess_audio(raw_path, wav_path)
        result = transcribe_with_features(wav_path)
        report(result)
    finally:
        if os.path.exists(wav_path):
            os.remove(wav_path)
```

## Prerequisites

```bash
pip install requests pydub
```

`pydub` requires `ffmpeg` on PATH for non-WAV input formats.

## What each example demonstrates

| Step                      | Pulse Pro example                            | Pulse advanced example                           |
| ------------------------- | -------------------------------------------- | ------------------------------------------------ |
| Audio preprocessing       | 16 kHz mono WAV, normalized, silence-trimmed | Same                                             |
| Transcription             | Word-timestamps on                           | Word-timestamps on                               |
| Gender detection          | Not available on Pulse Pro                   | `gender` field on response                       |
| Emotion detection         | Not available on Pulse Pro                   | `emotions` object with 5 scores                  |
| Speaker diarization       | Not available on Pulse Pro                   | `diarize=true` plus per-utterance speaker labels |
| Sentence-level utterances | Not available on Pulse Pro                   | `utterances[]` with start/end/speaker            |

## Expected output

The Pulse advanced example prints:

* Full transcription text
* Detected gender (`male` / `female`)
* Emotion scores: anger, disgust, fear, sadness, happiness
* Sentence-level utterances with timestamps and speaker IDs
* A count of word-level timestamps

> Complete Python examples for transcribing pre-recorded audio with Pulse Pro and Pulse.