radio-broadcaster 0.0.2

A CLI application for radio broadcasting

Radio Broadcaster

Broadcast internet radio streams over Bluetooth LE Audio (Auracast) using Python. This tool allows you to stream audio from any HTTP/HTTPS audio source to Bluetooth LE Audio receivers with support for custom manufacturer data and encryption.

Features

• Stream internet radio over Bluetooth LE Audio (Auracast)
• Support for custom manufacturer-specific data in BLE advertising
• Optional broadcast encryption
• Customizable broadcast name
• Verbose logging for debugging
• Pure Python implementation using PyAV and Bumble

Requirements

• Python 3.12+
• Bluetooth LE Audio compatible interface (USB Bluetooth adapter or serial connection)
• Internet connection for radio stream

Tested Hardware

This project is tested with the hci_uart_bumble controller which provides a serial-based HCI interface for Bluetooth LE Audio.

Note: While other controllers may work, we only test and recommend the hci_uart_bumble controller. Other controllers are not tested against this project.

Installation

Development Setup

1. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Linux/macOS
# or
venv\Scripts\activate  # On Windows

2. Install the package in editable mode with dev dependencies:

pip install -e ".[dev]"

Production Install

pip install .

Usage

# Show help
radio-broadcaster --help

# Show version
radio-broadcaster --version

# Broadcast a radio stream
radio-broadcaster <URL>

# Broadcast with custom name
radio-broadcaster <URL> -n "My Station"

# Broadcast with encryption
radio-broadcaster <URL> -c "my-password"

# Broadcast with manufacturer data (example: Nordic Semiconductor)
radio-broadcaster <URL> --manufacturer-data 0x0059:010203

# Broadcast with verbose output
radio-broadcaster <URL> --verbose

# Broadcast with custom transport (serial port)
radio-broadcaster <URL> -t "serial:/dev/ttyACM0,1000000"

Options

• -t, --transport SPEC: Bumble transport specifier (default: usb:0)
  • Examples: usb:0, hci:0, serial:/dev/ttyACM0,1000000
• -n, --name NAME: Broadcast name visible to receivers (default: "Radio Broadcaster")
• -c, --code PASSWORD: Encryption password (max 16 characters)
• --manufacturer-data COMPANY_ID:HEX_DATA: Manufacturer-specific data (can be used multiple times)
  • Example: 0x0059:010203 (Nordic Semiconductor with data 01 02 03)
• -v, --verbose: Enable verbose output
• -V, --version: Show version information and exit

Development

Continuous Integration

This project uses GitHub Actions to automatically run quality checks on all pushes and pull requests:

• Tests: Runs all pytest tests
• Type Checking: Verifies type annotations with mypy
• Code Formatting: Checks code style with black
• Linting: Runs ruff for code quality

All checks must pass before merging to main or develop branches.

Releases and PyPI Publishing

Releases are automatically published to PyPI when you create a GitHub release or push a tag matching v* (e.g., v1.0.0). The publishing workflow uses PyPI's Trusted Publishers feature, which authenticates via GitHub's OIDC token without requiring stored secrets.

To create a release:

1. Update the version in pyproject.toml if needed
2. Commit the changes: git commit -m "Bump version to X.Y.Z"
3. Create and push a git tag: git tag vX.Y.Z && git push origin vX.Y.Z
4. The GitHub Actions workflow automatically builds and publishes the package to PyPI

The package will be available at https://pypi.org/project/radio-broadcaster/

Running Tests

pytest

Code Formatting

black src tests

Linting

ruff check src tests

Type Checking

mypy src

License

Apache License 2.0