> ## 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.

<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 |

***

## Development

### 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]"
```

***

## 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 uses `websockets>=11.0`. Try upgrading: `pip install --upgrade websockets`
  </Accordion>
</AccordionGroup>

***

## License

MIT License — this is an unofficial SDK 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>