Skip to main content

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

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: 
brew install opus

​
Install the SDK

pip install omi-sdk

​
Quick Start

1

Set Up Your Environment

Get a free API key from Deepgram:
export DEEPGRAM_API_KEY=your_actual_deepgram_key
2

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

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

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

FunctionDescription
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

CommandDescription
omi-scanScan for nearby Bluetooth devices

​
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]"

​
Troubleshooting

Make sure the Opus audio codec is installed on your system. See the Prerequisites section above for installation commands.
Go to System Preferences → Privacy & Security → Bluetooth and grant access to Terminal and Python.
The SDK requires Python 3.10 or higher. Check your version with python --version.
Make sure your Omi device is powered on and nearby. Try running omi-scan to verify it’s discoverable.
The SDK uses websockets>=11.0. Try upgrading: pip install --upgrade websockets

​
License

MIT License — this is an unofficial SDK built by the community.

SDK Overview

Compare all available SDKs

GitHub Source

View source code and contribute