Skip to content
stergiosbaPublic

About

Connect to Bluetooth speakers and play audio from Python. Uses Kokoro-82M Model for TTS functionality.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Blue-voice 🟦🔊

Connect to a Bluetooth speaker and play beeps or AI-generated speech from a Raspberry Pi.


Quickstart

uv run python tests/test.py play XX:XX:XX:XX:XX:XX

This connects to a bluetooth speaker (e.g. a Sony SRS-XB100) and plays three test tones (440 Hz, 880 Hz, 1760 Hz).


Scripts

Script Description
examples/kokoro_chunkwise.py TTS live — generate speech with Kokoro, play each sentence as it's produced
examples/kokoro_stich.py TTS stitched — generate all text first, concatenate with silence gaps, then play as one buffer
tests/test.py Beeps — connect & play test tones over Bluetooth
tests/benchmark.py Speed test — measure real-time factor (RTF) for short / medium / long text

examples/kokoro_chunkwise.py — TTS (chunk-by-chunk)

uv run python ko.py

Generates speech with Kokoro-82M and plays each sentence through the speaker as it arrives. Uses the KPipeline generator — audio plays chunk-by-chunk with no stitching delay. Note: This script uses .env file with 'SPEAKER_MAC' entry. Make sure to define this.

examples/kokoro_stich.py — TTS (stitched)

uv run python examples/stitch_and_play.py

Generates all text first, then concatenates the audio chunks with ~0.2 s silence gaps between paragraphs, and plays the full buffer in one shot. Cleaner playback with no gaps between sentences within a paragraph. Note: This script uses .env file with 'SPEAKER_MAC' entry. Make sure to define this.

tests/test.py — Beep tones

# Play 440 → 880 → 1760 Hz tones
uv run python tests/test.py play XX:XX:XX:XX:XX:XX

# Scan for nearby devices
uv run python tests/test.py scan

tests/benchmark.py — Speed evaluation on RPI 5

uv run python tests/benchmark.py

Measures real-time factor (RTF): seconds of wall-clock time per second of generated audio.

Label Chars Audio out Gen time RTF
short 25 1.95 s 4.14 s 2.12
medium 97 6.58 s 12.02 s 1.83
long 335 21.25 s 36.47 s 1.72
Total 29.77 s 52.63 s 1.77

RTF < 1 = faster than real-time. On this Pi (Cortex-A76, 8 GB RAM), Kokoro runs at ~1.8× real-time — a paragraph takes ~36 s to generate 21 s of speech.


Python API

from bluevoice import BluetoothSpeaker

speaker = BluetoothSpeaker("XX:XX:XX:XX:XX:XX")
speaker.connect()

# Beeps
speaker.play_tone(440, 2.0)    # 440 Hz for 2 seconds
speaker.play_sweep(200, 2000)  # frequency sweep

# WAV file
speaker.play_wav("recording.wav")

speaker.disconnect()

Lower-level modules are also available:

from bluevoice import bluetooth, audio, output

# Bluetooth control
bluetooth.scan_devices(timeout=10)
bluetooth.connect("XX:XX:XX:XX:XX:XX")
bluetooth.disconnect("XX:XX:XX:XX:XX:XX")

# Audio generation
data = audio.generate_sine_wave(440, 2.0)   # S16_LE PCM bytes

# Output backends (auto-detects: ALSA → subprocess → file)
out = output.auto_output(rate=44100, channels=2)
out.play(data)
out.close()

TTS: Kokoro-82M

Text-to-speech uses the Kokoro-82M model via the kokoro PyPI package:

from kokoro import KPipeline

pipeline = KPipeline(lang_code="a")            # American English
gen = pipeline("Hello world!", voice="af_heart")
for gs, ps, audio in gen:
    # audio is a float32 torch.Tensor at 24000 Hz
    pass

Available voices

Voice Description
af_heart Female, American English (default)
af_bella, af_nicole, af_sarah Female, American English
am_adam, am_echo, am_liam Male, American English
bf_emma, bf_isabella Female, British English
bm_george, bm_lewis Male, British English

Audio backends

The output module tries each backend in order:

  1. ALSA — direct PCM playback via ctypes / libasound2
  2. Subprocess — pipes PCM to aplay, paplay, or ffplay if available
  3. File — writes to a WAV file (always works, guaranteed fallback)

Requirements

  • Python 3.12+
  • BlueZ (bluetoothctl)
  • ALSA (libasound2)
  • PulseAudio + pulseaudio-module-bluetooth (for A2DP Bluetooth audio)
  • 8 GB RAM recommended for Kokoro TTS
sudo apt-get install -y pulseaudio pulseaudio-module-bluetooth
pulseaudio --start

The stack:

  • ALSA via ctypes for audio playback (no external audio libraries)
  • bluetoothctl subprocess for pairing and connecting
  • Kokoro-82M text-to-speech model (via kokoro + torch)

About

Connect to Bluetooth speakers and play audio from Python. Uses Kokoro-82M Model for TTS functionality.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages