<!-- This file is auto-generated from docs/doc/developer/sdk/python.mdx. Do not edit manually. -->
# 🎧 Omi Python SDK
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**.
## 📦 Installation
### Prerequisites
The Omi SDK requires the Opus audio codec library to be installed on your system:
**macOS:**
```bash
brew install opus
```
**Ubuntu/Debian:**
```bash
sudo apt-get install libopus0 libopus-dev
```
**CentOS/RHEL/Fedora:**
```bash
sudo yum install opus opus-devel # CentOS/RHEL
sudo dnf install opus opus-devel # Fedora
```
### Option 1: Install from PyPI (when published)
```bash
pip install omi-sdk
```
### Option 2: Install from source
```bash
git clone https://github.com/BasedHardware/omi.git
cd omi/sdks/python
pip install -e .
```
## 🚀 Quick Start
### 1. Set up your environment
```bash
# Get a free API key from https://deepgram.com
export DEEPGRAM_API_KEY=your_actual_deepgram_key
```
### 2. Find your Omi device
```bash
# 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. Use in your Python code
```python
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):
# Custom transcript handling
print(f"🎤 {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
The included example demonstrates connecting to an Omi device and real-time transcription:
```bash
# 1. Set your Deepgram API key
export DEEPGRAM_API_KEY=your_actual_deepgram_key
# 2. Find your Omi device MAC address
omi-scan
# 3. Update examples/main.py with your device's MAC address
# Edit line 10: OMI_MAC = "YOUR_DEVICE_MAC_HERE"
# 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
- `omi.print_devices()` - Scan for Bluetooth devices
- `omi.listen_to_omi(mac, uuid, handler)` - Connect to Omi device
- `omi.OmiOpusDecoder()` - Decode Opus audio to PCM
- `omi.transcribe(queue, api_key)` - Real-time transcription
### Command Line Tools
- `omi-scan` - Scan for nearby Bluetooth devices
## 🔧 Development
### Local development setup
```bash
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
- **Opus library error**: Make sure Opus audio codec is installed (see Prerequisites section)
- **Bluetooth permission errors on macOS**: Go to System Preferences → Privacy & Security → Bluetooth and grant access to Terminal and Python
- **Python version**: Requires Python 3.10+
- **Omi device**: Make sure device is powered on and nearby
- **WebSocket issues**: SDK uses `websockets>=11.0`
## 📄 License
MIT License — this is an unofficial SDK built by the community, not affiliated with Omi.
## 🙌 Credits
Built by the Omi community using Omi hardware and Deepgram's transcription engine.
Raw data
{
"_id": null,
"home_page": null,
"name": "omi-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "omi, bluetooth, audio, transcription, deepgram, wearable",
"author": null,
"author_email": "Omi Community <support@omi.me>, Tae <0xkevtae@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/2f/a8d5d8fec6d31124fad07df5214c60a6cdff920e3888299163f15bc46288/omi_sdk-0.2.1.tar.gz",
"platform": null,
"description": "<!-- This file is auto-generated from docs/doc/developer/sdk/python.mdx. Do not edit manually. -->\n# \ud83c\udfa7 Omi Python SDK \n\nA pip-installable Python SDK for connecting to **Omi wearable devices** over **Bluetooth**, decoding **Opus-encoded audio**, and transcribing it in **real time using Deepgram**.\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\nThe Omi SDK requires the Opus audio codec library to be installed on your system:\n\n**macOS:**\n```bash\nbrew install opus\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt-get install libopus0 libopus-dev\n```\n\n**CentOS/RHEL/Fedora:**\n```bash\nsudo yum install opus opus-devel # CentOS/RHEL\nsudo dnf install opus opus-devel # Fedora\n```\n\n### Option 1: Install from PyPI (when published)\n```bash\npip install omi-sdk\n```\n\n### Option 2: Install from source\n```bash\ngit clone https://github.com/BasedHardware/omi.git\ncd omi/sdks/python\npip install -e .\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Set up your environment\n```bash\n# Get a free API key from https://deepgram.com\nexport DEEPGRAM_API_KEY=your_actual_deepgram_key\n```\n\n### 2. Find your Omi device\n```bash\n# Scan for nearby Bluetooth devices\nomi-scan\n```\n\nLook for a device named \"Omi\" and copy its MAC address:\n```\n0. Omi [7F52EC55-50C9-D1B9-E8D7-19B83217C97D]\n```\n\n### 3. Use in your Python code\n```python\nimport asyncio\nimport os\nfrom omi import listen_to_omi, OmiOpusDecoder, transcribe\nfrom asyncio import Queue\n\n# Configuration\nOMI_MAC = \"YOUR_OMI_MAC_ADDRESS_HERE\" # From omi-scan\nOMI_CHAR_UUID = \"19B10001-E8F2-537E-4F6C-D104768A1214\" # Standard Omi audio UUID\nDEEPGRAM_API_KEY = os.getenv(\"DEEPGRAM_API_KEY\")\n\nasync def main():\n audio_queue = Queue()\n decoder = OmiOpusDecoder()\n \n def handle_audio(sender, data):\n pcm_data = decoder.decode_packet(data)\n if pcm_data:\n audio_queue.put_nowait(pcm_data)\n \n def handle_transcript(transcript):\n # Custom transcript handling\n print(f\"\ud83c\udfa4 {transcript}\")\n # Save to file, send to API, etc.\n \n # Start transcription and device connection\n await asyncio.gather(\n listen_to_omi(OMI_MAC, OMI_CHAR_UUID, handle_audio),\n transcribe(audio_queue, DEEPGRAM_API_KEY, on_transcript=handle_transcript)\n )\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 4. Run the example\n\nThe included example demonstrates connecting to an Omi device and real-time transcription:\n\n```bash\n# 1. Set your Deepgram API key\nexport DEEPGRAM_API_KEY=your_actual_deepgram_key\n\n# 2. Find your Omi device MAC address\nomi-scan\n\n# 3. Update examples/main.py with your device's MAC address\n# Edit line 10: OMI_MAC = \"YOUR_DEVICE_MAC_HERE\"\n\n# 4. Run the example\npython examples/main.py\n```\n\nThe example will:\n- Connect to your Omi device via Bluetooth\n- Decode incoming Opus audio packets to PCM\n- Transcribe audio in real-time using Deepgram\n- Print transcriptions to the console\n\n## \ud83d\udcda API Reference\n\n### Core Functions\n- `omi.print_devices()` - Scan for Bluetooth devices\n- `omi.listen_to_omi(mac, uuid, handler)` - Connect to Omi device\n- `omi.OmiOpusDecoder()` - Decode Opus audio to PCM\n- `omi.transcribe(queue, api_key)` - Real-time transcription\n\n### Command Line Tools\n- `omi-scan` - Scan for nearby Bluetooth devices\n\n## \ud83d\udd27 Development\n\n### Local development setup\n```bash\ngit clone https://github.com/BasedHardware/omi.git\ncd omi/sdks/python\n\n# Create virtual environment\npython3 -m venv venv\nsource venv/bin/activate\n\n# Install in editable mode\npip install -e .\n\n# Install dev dependencies\npip install -e \".[dev]\"\n```\n\n## \ud83e\udde9 Troubleshooting\n\n- **Opus library error**: Make sure Opus audio codec is installed (see Prerequisites section)\n- **Bluetooth permission errors on macOS**: Go to System Preferences \u2192 Privacy & Security \u2192 Bluetooth and grant access to Terminal and Python\n- **Python version**: Requires Python 3.10+\n- **Omi device**: Make sure device is powered on and nearby\n- **WebSocket issues**: SDK uses `websockets>=11.0`\n\n## \ud83d\udcc4 License\n\nMIT License \u2014 this is an unofficial SDK built by the community, not affiliated with Omi.\n\n## \ud83d\ude4c Credits\n\nBuilt by the Omi community using Omi hardware and Deepgram's transcription engine.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Omi wearable device",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://docs.omi.me/doc/developer/sdk/python",
"Homepage": "https://www.omi.me/",
"Repository": "https://github.com/BasedHardware/omi"
},
"split_keywords": [
"omi",
" bluetooth",
" audio",
" transcription",
" deepgram",
" wearable"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d3662a7b1f179ed0a9f2ca871d9591ea9cc8fd9f45e8bc8df82cc60671f1e1e",
"md5": "88621922903db546a22603ccc9307551",
"sha256": "3c7b6c25038f98c2aa6abee53b279bd615f9636a843c8e0459933804a0b6193f"
},
"downloads": -1,
"filename": "omi_sdk-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88621922903db546a22603ccc9307551",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7472,
"upload_time": "2025-08-23T22:45:34",
"upload_time_iso_8601": "2025-08-23T22:45:34.578405Z",
"url": "https://files.pythonhosted.org/packages/6d/36/62a7b1f179ed0a9f2ca871d9591ea9cc8fd9f45e8bc8df82cc60671f1e1e/omi_sdk-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d12fa8d5d8fec6d31124fad07df5214c60a6cdff920e3888299163f15bc46288",
"md5": "ea65cb3179001d02f7329aa521026f03",
"sha256": "ab5421a562e16e14509a40a2c7b645db86db2252aba748fa34580838523b13fb"
},
"downloads": -1,
"filename": "omi_sdk-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "ea65cb3179001d02f7329aa521026f03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7568,
"upload_time": "2025-08-23T22:45:35",
"upload_time_iso_8601": "2025-08-23T22:45:35.825119Z",
"url": "https://files.pythonhosted.org/packages/d1/2f/a8d5d8fec6d31124fad07df5214c60a6cdff920e3888299163f15bc46288/omi_sdk-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 22:45:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BasedHardware",
"github_project": "omi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "omi-sdk"
}
JSON
