Configuration

Audio Device Configuration

Device-specific audio settings live in /etc/mediamtx/audio-devices.conf. This file uses a simple KEY=VALUE format (bash environment variables) that the stream manager reads at startup.

Auto-Generate Configuration (Recommended)

The lyrebird-mic-check.sh script detects your hardware capabilities and writes an optimal configuration:

# Generate with normal quality (recommended default)
sudo ./lyrebird-mic-check.sh -g

# Generate with high quality (more bandwidth)
sudo ./lyrebird-mic-check.sh -g --quality=high

# Generate with low quality (speech / bandwidth-constrained)
sudo ./lyrebird-mic-check.sh -g --quality=low

# Preview what would be generated without writing (dry-run)
./lyrebird-mic-check.sh -g --dry-run

Manual Configuration Format

Settings use a DEVICE_<NAME>_<PARAMETER>=value pattern. Device names are sanitized (special characters → underscores, uppercased).

# /etc/mediamtx/audio-devices.conf

# ── Device-specific settings (by friendly name) ──────────────────
DEVICE_USB_MICROPHONE_SAMPLE_RATE=48000
DEVICE_USB_MICROPHONE_CHANNELS=2
DEVICE_USB_MICROPHONE_BITRATE=192k
DEVICE_USB_MICROPHONE_CODEC=opus

# ── Device-specific settings (by full device ID, guaranteed unique) ──
DEVICE_USB_MANUFACTURER_MODEL_SERIAL_00000000_SAMPLE_RATE=48000
DEVICE_USB_MANUFACTURER_MODEL_SERIAL_00000000_CHANNELS=2
DEVICE_USB_MANUFACTURER_MODEL_SERIAL_00000000_BITRATE=128k

# ── Fallback defaults ─────────────────────────────────────────────
DEFAULT_SAMPLE_RATE=48000
DEFAULT_CHANNELS=2
DEFAULT_BITRATE=128k
DEFAULT_CODEC=opus
DEFAULT_THREAD_QUEUE=8192

Available Parameters

Validate Configuration

# Check configuration against detected hardware capabilities
sudo ./lyrebird-mic-check.sh -V

# Also validates MediaMTX config
/usr/local/bin/mediamtx --check /etc/mediamtx/mediamtx.yml

Configuration Files

Runtime State Files

Environment Variables

All configuration can be overridden via environment variables. This is useful for custom deployments, Docker-adjacent setups, or testing alternative values.

Stream Manager

# MediaMTX paths
MEDIAMTX_BINARY="/usr/local/bin/mediamtx"
MEDIAMTX_CONFIG_DIR="/etc/mediamtx"
MEDIAMTX_CONFIG_FILE="/etc/mediamtx/mediamtx.yml"
MEDIAMTX_DEVICE_CONFIG="/etc/mediamtx/audio-devices.conf"
MEDIAMTX_LOG_FILE="/var/log/mediamtx.out"
MEDIAMTX_HOST="localhost"
MEDIAMTX_API_PORT="9997"

# Process management
MEDIAMTX_PID_FILE="/run/mediamtx-audio.pid"
MEDIAMTX_LOCK_FILE="/run/mediamtx-audio.lock"
MEDIAMTX_FFMPEG_DIR="/var/lib/mediamtx-ffmpeg"

# Timing
STREAM_STARTUP_DELAY=10         # Seconds before starting streams
USB_STABILIZATION_DELAY=5       # Seconds to wait after USB events
RESTART_STABILIZATION_DELAY=15  # Seconds between restart attempts

# Recovery
MAX_WRAPPER_RESTARTS=50         # Max auto-restarts before giving up
WRAPPER_SUCCESS_DURATION=300    # Seconds to count as "successful run"
MAX_CONSECUTIVE_FAILURES=5      # Max failures before escalation
INITIAL_RESTART_DELAY=10        # Starting exponential backoff (seconds)
MAX_RESTART_DELAY=300           # Maximum backoff delay (5 minutes)

# Resource thresholds
MAX_FD_WARNING=500              # File descriptor warning level
MAX_FD_CRITICAL=1000            # File descriptor critical level
MAX_CPU_WARNING=20              # CPU % warning per stream
MAX_CPU_CRITICAL=40             # CPU % critical per stream

# Audio defaults (when not in config file)
DEFAULT_SAMPLE_RATE=48000
DEFAULT_CHANNELS=2
DEFAULT_CODEC=opus
DEFAULT_BITRATE=128k
DEFAULT_THREAD_QUEUE=8192

# Debugging
DEBUG=1                         # Enable verbose output

Usage Examples

# Use custom log location
FFMPEG_LOG_DIR=/mnt/storage/logs sudo ./lyrebird-stream-manager.sh start

# Increase startup delay for slow USB hubs
STREAM_STARTUP_DELAY=20 sudo ./lyrebird-stream-manager.sh start

# Enable debug output
export DEBUG=1
sudo ./lyrebird-stream-manager.sh start

# Install MediaMTX to a custom prefix
MEDIAMTX_PREFIX=/opt/mediamtx sudo ./install_mediamtx.sh install

MediaMTX Integration

MediaMTX serves RTSP, WebRTC, HLS, and RTMP. LyreBirdAudio configures and manages the MediaMTX process. The main configuration is at /etc/mediamtx/mediamtx.yml.

Default Port Assignments

Management Modes

MediaMTX API

The REST API (port 9997) is available for programmatic stream management:

# List all active paths/streams
curl http://localhost:9997/v3/paths/list

# Get info for a specific stream
curl http://localhost:9997/v3/paths/get/Device_1

# Check MediaMTX health
curl http://localhost:9997/v3/config/global/get

Quality Tiers

The capability checker provides three quality presets. Choose based on your use case:

Codec Comparison

High-Quality Example

# High quality music streaming
DEVICE_STUDIO_MIC_SAMPLE_RATE=96000
DEVICE_STUDIO_MIC_CHANNELS=2
DEVICE_STUDIO_MIC_BITRATE=256k
DEVICE_STUDIO_MIC_CODEC=opus

Low-Bandwidth Speech Example

# Speech/monitoring (bandwidth-constrained)
DEVICE_FIELD_MIC_SAMPLE_RATE=16000
DEVICE_FIELD_MIC_CHANNELS=1
DEVICE_FIELD_MIC_BITRATE=64k
DEVICE_FIELD_MIC_CODEC=opus