Skip to content

Commit e962abf

Browse files
github-actions[bot]github-actions[bot]
authored
chore: sync docs to README files (#3675)
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
1 parent a4e1f6c commit e962abf

File tree

3 files changed

+284
-535
lines changed

3 files changed

+284
-535
lines changed

‎sdks/python/README.md‎

Lines changed: 94 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,97 @@
11
<!-- This file is auto-generated from docs/doc/developer/sdk/python.mdx. Do not edit manually. -->
2-
# 🎧 Omi Python SDK
2+
## Overview
3+
4+
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.
5+
6+
<CardGroup cols={3}>
7+
<Card title="Bluetooth Connection" icon="bluetooth">
8+
Connect to any Omi device
9+
</Card>
10+
<Card title="Opus Decoding" icon="waveform">
11+
Decode Opus audio to PCM
12+
</Card>
13+
<Card title="Real-time Transcription" icon="microphone">
14+
Deepgram-powered STT
15+
</Card>
16+
</CardGroup>
17+
18+
19+
## Quick Start
20+
21+
<Steps>
22+
<Step title="Set Up Your Environment">
23+
Get a free API key from [Deepgram](https://deepgram.com):
24+
25+
```bash
26+
export DEEPGRAM_API_KEY=your_actual_deepgram_key
27+
```
28+
</Step>
29+
<Step title="Find Your Omi Device">
30+
Scan for nearby Bluetooth devices:
31+
32+
```bash
33+
omi-scan
34+
```
35+
36+
Look for a device named "Omi" and copy its MAC address:
37+
38+
```
39+
0. Omi [7F52EC55-50C9-D1B9-E8D7-19B83217C97D]
40+
```
41+
</Step>
42+
<Step title="Write Your Code">
43+
```python
44+
import asyncio
45+
import os
46+
from omi import listen_to_omi, OmiOpusDecoder, transcribe
47+
from asyncio import Queue
48+
49+
# Configuration
50+
OMI_MAC = "YOUR_OMI_MAC_ADDRESS_HERE" # From omi-scan
51+
OMI_CHAR_UUID = "19B10001-E8F2-537E-4F6C-D104768A1214" # Standard Omi audio UUID
52+
DEEPGRAM_API_KEY = os.getenv("DEEPGRAM_API_KEY")
53+
54+
async def main():
55+
audio_queue = Queue()
56+
decoder = OmiOpusDecoder()
57+
58+
def handle_audio(sender, data):
59+
pcm_data = decoder.decode_packet(data)
60+
if pcm_data:
61+
audio_queue.put_nowait(pcm_data)
62+
63+
def handle_transcript(transcript):
64+
print(f"Transcription: {transcript}")
65+
# Save to file, send to API, etc.
66+
67+
# Start transcription and device connection
68+
await asyncio.gather(
69+
listen_to_omi(OMI_MAC, OMI_CHAR_UUID, handle_audio),
70+
transcribe(audio_queue, DEEPGRAM_API_KEY, on_transcript=handle_transcript)
71+
)
72+
73+
if __name__ == "__main__":
74+
asyncio.run(main())
75+
```
76+
</Step>
77+
<Step title="Run the Example">
78+
```bash
79+
python examples/main.py
80+
```
81+
82+
The example will:
83+
- Connect to your Omi device via Bluetooth
84+
- Decode incoming Opus audio packets to PCM
85+
- Transcribe audio in real-time using Deepgram
86+
- Print transcriptions to the console
87+
</Step>
88+
</Steps>
89+
90+
91+
## Development
92+
93+
### Local Development Setup
394

4-
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**.
5-
6-
## 📦 Installation
7-
8-
### Prerequisites
9-
The Omi SDK requires the Opus audio codec library to be installed on your system:
10-
11-
**macOS:**
12-
```bash
13-
brew install opus
14-
```
15-
16-
**Ubuntu/Debian:**
17-
```bash
18-
sudo apt-get install libopus0 libopus-dev
19-
```
20-
21-
**CentOS/RHEL/Fedora:**
22-
```bash
23-
sudo yum install opus opus-devel # CentOS/RHEL
24-
sudo dnf install opus opus-devel # Fedora
25-
```
26-
27-
### Option 1: Install from PyPI (when published)
28-
```bash
29-
pip install omi-sdk
30-
```
31-
32-
### Option 2: Install from source
33-
```bash
34-
git clone https://github.com/BasedHardware/omi.git
35-
cd omi/sdks/python
36-
pip install -e .
37-
```
38-
39-
## 🚀 Quick Start
40-
41-
### 1. Set up your environment
42-
```bash
43-
# Get a free API key from https://deepgram.com
44-
export DEEPGRAM_API_KEY=your_actual_deepgram_key
45-
```
46-
47-
### 2. Find your Omi device
48-
```bash
49-
# Scan for nearby Bluetooth devices
50-
omi-scan
51-
```
52-
53-
Look for a device named "Omi" and copy its MAC address:
54-
```
55-
0. Omi [7F52EC55-50C9-D1B9-E8D7-19B83217C97D]
56-
```
57-
58-
### 3. Use in your Python code
59-
```python
60-
import asyncio
61-
import os
62-
from omi import listen_to_omi, OmiOpusDecoder, transcribe
63-
from asyncio import Queue
64-
65-
# Configuration
66-
OMI_MAC = "YOUR_OMI_MAC_ADDRESS_HERE" # From omi-scan
67-
OMI_CHAR_UUID = "19B10001-E8F2-537E-4F6C-D104768A1214" # Standard Omi audio UUID
68-
DEEPGRAM_API_KEY = os.getenv("DEEPGRAM_API_KEY")
69-
70-
async def main():
71-
audio_queue = Queue()
72-
decoder = OmiOpusDecoder()
73-
74-
def handle_audio(sender, data):
75-
pcm_data = decoder.decode_packet(data)
76-
if pcm_data:
77-
audio_queue.put_nowait(pcm_data)
78-
79-
def handle_transcript(transcript):
80-
# Custom transcript handling
81-
print(f"🎤 {transcript}")
82-
# Save to file, send to API, etc.
83-
84-
# Start transcription and device connection
85-
await asyncio.gather(
86-
listen_to_omi(OMI_MAC, OMI_CHAR_UUID, handle_audio),
87-
transcribe(audio_queue, DEEPGRAM_API_KEY, on_transcript=handle_transcript)
88-
)
89-
90-
if __name__ == "__main__":
91-
asyncio.run(main())
92-
```
93-
94-
### 4. Run the example
95-
96-
The included example demonstrates connecting to an Omi device and real-time transcription:
97-
98-
```bash
99-
# 1. Set your Deepgram API key
100-
export DEEPGRAM_API_KEY=your_actual_deepgram_key
101-
102-
# 2. Find your Omi device MAC address
103-
omi-scan
104-
105-
# 3. Update examples/main.py with your device's MAC address
106-
# Edit line 10: OMI_MAC = "YOUR_DEVICE_MAC_HERE"
107-
108-
# 4. Run the example
109-
python examples/main.py
110-
```
111-
112-
The example will:
113-
- Connect to your Omi device via Bluetooth
114-
- Decode incoming Opus audio packets to PCM
115-
- Transcribe audio in real-time using Deepgram
116-
- Print transcriptions to the console
117-
118-
## 📚 API Reference
119-
120-
### Core Functions
121-
- `omi.print_devices()` - Scan for Bluetooth devices
122-
- `omi.listen_to_omi(mac, uuid, handler)` - Connect to Omi device
123-
- `omi.OmiOpusDecoder()` - Decode Opus audio to PCM
124-
- `omi.transcribe(queue, api_key)` - Real-time transcription
125-
126-
### Command Line Tools
127-
- `omi-scan` - Scan for nearby Bluetooth devices
128-
129-
## 🔧 Development
130-
131-
### Local development setup
13295
```bash
13396
git clone https://github.com/BasedHardware/omi.git
13497
cd omi/sdks/python
@@ -144,18 +107,8 @@ pip install -e .
144107
pip install -e ".[dev]"
145108
```
146109

147-
## 🧩 Troubleshooting
148-
149-
- **Opus library error**: Make sure Opus audio codec is installed (see Prerequisites section)
150-
- **Bluetooth permission errors on macOS**: Go to System Preferences → Privacy & Security → Bluetooth and grant access to Terminal and Python
151-
- **Python version**: Requires Python 3.10+
152-
- **Omi device**: Make sure device is powered on and nearby
153-
- **WebSocket issues**: SDK uses `websockets>=11.0`
154-
155-
## 📄 License
156110

157-
MIT License — this is an unofficial SDK built by the community, not affiliated with Omi.
111+
## License
158112

159-
## 🙌 Credits
113+
MIT License — this is an unofficial SDK built by the community.
160114

161-
Built by the Omi community using Omi hardware and Deepgram's transcription engine.

0 commit comments

Comments
 (0)