Quick Start

System Requirements

Operating System

Hardware

Software Dependencies

Verify these are installed before proceeding:

# Check required tools
bash --version           # Must be 4.0+
ffmpeg -version          # Required for audio capture
git --version            # Required for installation
lsusb                    # From usbutils package
arecord --version        # From alsa-utils package

# Install missing dependencies (Ubuntu/Debian)
sudo apt update
sudo apt install -y ffmpeg git usbutils alsa-utils curl

Optional but recommended:

sudo apt install -y jq          # Better MediaMTX API parsing
sudo apt install -y shellcheck  # For script validation (developers)

Clone the Repository

Option A: Latest Stable Release (Recommended for Production)

git clone https://github.com/tomtom215/LyreBirdAudio.git
cd LyreBirdAudio

# Checkout the latest tagged release
git checkout $(git describe --tags --abbrev=0)

chmod +x *.sh

Option B: Latest Main Branch

git clone https://github.com/tomtom215/LyreBirdAudio.git
cd LyreBirdAudio
chmod +x *.sh

Run the Setup Wizard

The Orchestrator provides a guided wizard that handles everything in one flow:

sudo ./lyrebird-orchestrator.sh

When the menu appears, select "Quick Setup Wizard". The wizard will:

1. Install MediaMTX

   Downloads the latest MediaMTX binary with SHA256 checksum verification and sets up a systemd service.

2. Map USB Audio Devices

   Scans connected USB microphones and creates persistent udev rules so device names never change across reboots.

3. Detect Hardware Capabilities

   Non-invasively analyzes each microphone's supported sample rates, channels, and formats to generate an optimal configuration.

4. Generate Configuration

   Creates /etc/mediamtx/audio-devices.conf with device-specific settings for the best audio quality.

5. Start Streams

   Launches FFmpeg for each device and publishes streams to MediaMTX with automatic recovery on failure.

6. Run Diagnostics

   Verifies all components are healthy and streams are accessible.

Access Your Streams

Streams are available at:

rtsp://your-server-ip:8554/Device_1
rtsp://your-server-ip:8554/Device_2
# etc.

Test with common players:

# Test with ffplay (from ffmpeg)
ffplay rtsp://localhost:8554/Device_1

# Test with VLC
vlc rtsp://localhost:8554/Device_1

# Record a stream
ffmpeg -i rtsp://your-ip:8554/Device_1 -c copy recording.mkv

Manual Installation

If you prefer step-by-step control or are automating the setup:

# Step 1: Install MediaMTX
sudo ./install_mediamtx.sh install

# Step 2: Map USB devices (interactive)
sudo ./usb-audio-mapper.sh

# Step 3: Reboot for udev rules to take effect
sudo reboot

# Step 4: Generate optimal configuration
sudo ./lyrebird-mic-check.sh -g

# Step 5: Start streams
sudo ./lyrebird-stream-manager.sh start

# Step 6 (Recommended): Install as systemd service for 24/7 operation
sudo ./lyrebird-stream-manager.sh install
sudo systemctl enable mediamtx-audio
sudo systemctl start mediamtx-audio

Verification

Run the built-in health check to confirm everything is working:

# Quick health check
sudo ./lyrebird-diagnostics.sh quick

# Check stream status
./lyrebird-stream-manager.sh status

The quick check verifies:

• MediaMTX is installed and running
• USB audio devices are detected
• FFmpeg streams are active
• RTSP port 8554 is listening
• System resources are healthy

Next Steps