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

# Python SDK

> Connect to Omi devices over Bluetooth, decode Opus audio, and transcribe in real-time using Deepgram

## Overview

A pip-installable Python SDK for connecting to Omi wearable devices over Bluetooth, decoding Opus-encoded audio, and transcribing it in real time using Deepgram.

Deepgram transcription requires `websockets` 14.0 or newer. The SDK's dependency declarations enforce this minimum for its authenticated WebSocket handshake.

<CardGroup cols={3}>
  <Card title="Bluetooth Connection" icon="bluetooth">
    Connect to any Omi device
  </Card>

  <Card title="Opus Decoding" icon="waveform">
    Decode Opus audio to PCM
  </Card>

  <Card title="Real-time Transcription" icon="microphone">
    Deepgram-powered STT
  </Card>
</CardGroup>

***

## Installation

### Prerequisites

The SDK requires the Opus audio codec library:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    brew install opus
    ```
  </Tab>

  <Tab title="Ubuntu/Debian">
    ```bash theme={null}
    sudo apt-get install libopus0 libopus-dev
    ```
  </Tab>

  <Tab title="CentOS/RHEL">
    ```bash theme={null}
    sudo yum install opus opus-devel
    ```
  </Tab>

  <Tab title="Fedora">
    ```bash theme={null}
    sudo dnf install opus opus-devel
    ```
  </Tab>
</Tabs>

### Install the SDK

<Tabs>
  <Tab title="From PyPI">
    ```bash theme={null}
    pip install omi-sdk
    ```
  </Tab>

  <Tab title="From Source">
    ```bash theme={null}
    git clone https://github.com/BasedHardware/omi.git
    cd omi/sdks/python
    pip install -e .
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Steps>
  <Step title="Set Up Your Environment">
    Get a free API key from [Deepgram](https://deepgram.com):

    ```bash theme={null}
    export DEEPGRAM_API_KEY=your_actual_deepgram_key
    ```
  </Step>

  <Step title="Find Your Omi Device">
    Scan for nearby Bluetooth devices:

    ```bash theme={null}
    omi-scan
    ```

    Look for a device named "Omi" and copy its MAC address:

    ```
    0. Omi [7F52EC55-50C9-D1B9-E8D7-19B83217C97D]
    ```
  </Step>

  <Step title="Write Your Code">
    ```python theme={null}
    import asyncio
    import os
    from omi import listen_to_omi, OmiOpusDecoder, transcribe
    from asyncio import Queue

    # Configuration
    OMI_MAC = "YOUR_OMI_MAC_ADDRESS_HERE"  # From omi-scan
    OMI_CHAR_UUID = "19B10001-E8F2-537E-4F6C-D104768A1214"  # Standard Omi audio UUID
    DEEPGRAM_API_KEY = os.getenv("DEEPGRAM_API_KEY")

    async def main():
        audio_queue = Queue()
        decoder = OmiOpusDecoder()

        def handle_audio(sender, data):
            pcm_data = decoder.decode_packet(data)
            if pcm_data:
                audio_queue.put_nowait(pcm_data)

        def handle_transcript(transcript):
            print(f"Transcription: {transcript}")
            # Save to file, send to API, etc.

        # Start transcription and device connection
        await asyncio.gather(
            listen_to_omi(OMI_MAC, OMI_CHAR_UUID, handle_audio),
            transcribe(audio_queue, DEEPGRAM_API_KEY, on_transcript=handle_transcript)
        )

    if __name__ == "__main__":
        asyncio.run(main())
    ```
  </Step>

  <Step title="Run the Example">
    ```bash theme={null}
    python examples/main.py
    ```

    The example will:

    * Connect to your Omi device via Bluetooth
    * Decode incoming Opus audio packets to PCM
    * Transcribe audio in real-time using Deepgram
    * Print transcriptions to the console
  </Step>
</Steps>

***

## API Reference

### Core Functions

| Function | Description |
| - | - |
| `omi.print_devices()` | Scan for Bluetooth devices |
| `omi.listen_to_omi(mac, uuid, handler)` | Connect to Omi device and receive audio |
| `omi.OmiOpusDecoder()` | Decode Opus audio to PCM |
| `omi.transcribe(queue, api_key)` | Real-time transcription via Deepgram |

### Command Line Tools

| Command | Description |
| - | - |
| `omi-scan` | Scan for nearby Bluetooth devices |

***

## Deepgram language selection

The Deepgram engine defaults to `en-US`. Set `language` to a language supported
by your chosen Deepgram model when transcribing other languages:

```python theme={null}
from omi.stt import create_transcriber

transcriber = create_transcriber("deepgram", api_key=DEEPGRAM_API_KEY, language="es")
await transcriber.run(audio_queue, on_transcript=handle_transcript)
```

The `omi.transcribe.transcribe` function also forwards `language="es"` through
its engine options. This selects a transcription language; it does not translate
audio or enable automatic language detection. See Deepgram's
[model and language support](https://developers.deepgram.com/docs/models-languages-overview).

## Development

### Stopping Deepgram transcription

Cancel and await the task running the transcriber to stop it. The SDK stops
sending PCM, sends Deepgram's `CloseStream`, and keeps receiving final transcripts
until the server closes or the receive timeout expires. `drain_timeout` bounds
both the terminal send and the receive wait (default: five seconds per phase).
Callbacks can therefore run while cancellation is being awaited. Set
`drain_timeout=0` on `create_transcriber("deepgram", ...)` to skip waiting for final
results; the terminal send still has a five-second timeout. A server EOF or
connection error follows the reconnect path; it does not send `CloseStream`.

### Local Development Setup

```bash theme={null}
git clone https://github.com/BasedHardware/omi.git
cd omi/sdks/python

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in editable mode
pip install -e .

# Install dev dependencies
pip install -e ".[dev]"
```

Run the SDK's hardware-free regression suite with `bash test.sh`. It uses the
repository's `uv` environment manager to test the minimum supported `websockets`
version and is also selected by the shared local/CI check manifest.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Opus library error" icon="circle-exclamation">
    Make sure the Opus audio codec is installed on your system. See the Prerequisites section above for installation commands.
  </Accordion>

  <Accordion title="Bluetooth permission errors on macOS" icon="apple">
    Go to **System Preferences → Privacy & Security → Bluetooth** and grant access to Terminal and Python.
  </Accordion>

  <Accordion title="Python version issues" icon="python">
    The SDK requires Python 3.10 or higher. Check your version with `python --version`.
  </Accordion>

  <Accordion title="Device not found" icon="bluetooth">
    Make sure your Omi device is powered on and nearby. Try running `omi-scan` to verify it's discoverable.
  </Accordion>

  <Accordion title="WebSocket issues" icon="plug">
    The SDK requires `websockets>=14.0`. Try upgrading: `pip install --upgrade "websockets>=14.0"`
  </Accordion>
</AccordionGroup>

***

## License

MIT License — built by the community.

***

## Related

<CardGroup cols={2}>
  <Card title="SDK Overview" icon="cube" href="/doc/developer/sdk/sdk">
    Compare all available SDKs
  </Card>

  <Card title="GitHub Source" icon="github" href="https://github.com/BasedHardware/omi/tree/main/sdks/python">
    View source code and contribute
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.