Python SDK

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.

Bluetooth Connection

Connect to any Omi device

Opus Decoding

Decode Opus audio to PCM

Real-time Transcription

Deepgram-powered STT

Installation

Prerequisites

The SDK requires the Opus audio codec library:

macOS
Ubuntu/Debian
CentOS/RHEL
Fedora

brew install opus

sudo apt-get install libopus0 libopus-dev

sudo yum install opus opus-devel

sudo dnf install opus opus-devel

Install the SDK

From PyPI
From Source

pip install omi-sdk

git clone https://github.com/BasedHardware/omi.git
cd omi/sdks/python
pip install -e .

Quick Start

Set Up Your Environment

Get a free API key from Deepgram:

export DEEPGRAM_API_KEY=your_actual_deepgram_key

Find Your Omi Device

Scan for nearby Bluetooth devices:

omi-scan

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

0. Omi [7F52EC55-50C9-D1B9-E8D7-19B83217C97D]

Write Your Code

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

Run the Example

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

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:

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.

Development

Local Development Setup

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

Opus library error

Make sure the Opus audio codec is installed on your system. See the Prerequisites section above for installation commands.

Bluetooth permission errors on macOS

Go to System Preferences → Privacy & Security → Bluetooth and grant access to Terminal and Python.

Python version issues

The SDK requires Python 3.10 or higher. Check your version with python --version.

Device not found

Make sure your Omi device is powered on and nearby. Try running omi-scan to verify it’s discoverable.

WebSocket issues

The SDK requires websockets>=14.0. Try upgrading: pip install --upgrade "websockets>=14.0"

License

MIT License — built by the community.

SDK Overview

Compare all available SDKs

GitHub Source

View source code and contribute

Get Started

Core Development

DIY Guide

Info

Overview

Bluetooth Connection

Opus Decoding

Real-time Transcription

Installation

Prerequisites

Install the SDK

Quick Start

API Reference

Core Functions

Command Line Tools

Deepgram language selection

Development

Local Development Setup

Troubleshooting

License

SDK Overview

GitHub Source

​Overview

Bluetooth Connection

Opus Decoding

Real-time Transcription

​Installation

​Prerequisites

​Install the SDK

​Quick Start

​API Reference

​Core Functions

​Command Line Tools

​Deepgram language selection

​Development

​Local Development Setup

​Troubleshooting

​License

​Related

SDK Overview

GitHub Source

Overview

Installation

Prerequisites

Install the SDK

Quick Start

API Reference

Core Functions

Command Line Tools

Deepgram language selection

Development

Local Development Setup

Troubleshooting

License

Related