Component Reference

Quick Reference Table

🎛️ Orchestrator

lyrebird-orchestrator.sh — Unified management interface that delegates to all other scripts. This is the recommended entry point for all operations.

Usage

sudo ./lyrebird-orchestrator.sh

Features

• Interactive TUI menu for all operations
• Quick Setup Wizard for first-time configuration
• Hardware capability inspection and display
• SHA256 integrity verification for sourced scripts
• Automatic detection of outdated script names
• Comprehensive logging to /var/log/lyrebird-orchestrator.log

Exit Codes

📡 Stream Manager

lyrebird-stream-manager.sh — Core audio streaming script. Detects USB microphones, manages FFmpeg processes, monitors stream health, and provides automatic recovery with exponential backoff.

Usage

# Individual streams (default)
sudo ./lyrebird-stream-manager.sh start

# Multiplex (mix all mics)
sudo ./lyrebird-stream-manager.sh -m multiplex -f amix start

# Multiplex (merge channels)
sudo ./lyrebird-stream-manager.sh -m multiplex -f amerge start

# Custom multiplex stream name
sudo ./lyrebird-stream-manager.sh -m multiplex -n studio start

Commands

Features

• Wrapper-based FFmpeg supervision with exponential backoff (10s → 300s)
• Health monitoring via MediaMTX REST API
• Dual-lookup config (friendly name first, then full device ID, then defaults)
• CPU, memory, and file descriptor monitoring
• Lock file prevents concurrent executions
• Graceful shutdown with process tree termination
• Per-device FFmpeg log files with rotation

Exit Codes

🔌 USB Audio Mapper

usb-audio-mapper.sh — Creates persistent udev rules that give USB audio devices stable names across reboots, even when USB enumeration order changes.

Usage

# Interactive mode (guided wizard)
sudo ./usb-audio-mapper.sh

# Non-interactive (for automation)
sudo ./usb-audio-mapper.sh -n -d "Device" -v XXXX -p YYYY -f friendly-name

# Test USB port detection
sudo ./usb-audio-mapper.sh --test

# Debug mode
sudo ./usb-audio-mapper.sh --debug

Options

Output

The script creates:

• /etc/udev/rules.d/99-usb-soundcards.rules — udev rules file
• /dev/snd/by-usb-port/Device_N — Persistent symlinks (after reboot)

🎙️ Capability Checker

lyrebird-mic-check.sh — Non-invasively detects USB audio hardware capabilities via the ALSA proc filesystem. Never opens devices (won't interrupt active streams).

Usage

# List all detected devices
./lyrebird-mic-check.sh

# Show details for device index 0
./lyrebird-mic-check.sh 0

# Generate configuration file (recommended)
sudo ./lyrebird-mic-check.sh -g --quality=normal

# Validate existing configuration
sudo ./lyrebird-mic-check.sh -V

# JSON output for scripting
./lyrebird-mic-check.sh --json

# Restore configuration from backup
sudo ./lyrebird-mic-check.sh --restore

# Dry-run (preview without writing)
./lyrebird-mic-check.sh -g --dry-run

What It Detects

• Supported sample rates (16kHz, 44.1kHz, 48kHz, 96kHz, etc.)
• Channel configurations (mono, stereo)
• Supported audio formats and bit depths
• Device busy state (non-destructively)
• USB audio adapter chip type (with warnings for limited chips)

🩺 Diagnostics

lyrebird-diagnostics.sh — Comprehensive system health checker with 20+ checks covering devices, services, connectivity, and resources.

Usage

# Quick check (essential systems, fast)
sudo ./lyrebird-diagnostics.sh quick

# Full check (comprehensive analysis)
sudo ./lyrebird-diagnostics.sh full

# Debug check (maximum verbosity)
sudo ./lyrebird-diagnostics.sh debug

Options

Exit Codes

📦 MediaMTX Installer

install_mediamtx.sh — Downloads, verifies, and installs MediaMTX with atomic updates and automatic rollback on failure.

Usage

# Install latest version
sudo ./install_mediamtx.sh install

# Install specific version
sudo ./install_mediamtx.sh -V v1.15.0 install

# Update existing installation
sudo ./install_mediamtx.sh update

# Check current status
./install_mediamtx.sh status

# Verify installation integrity
sudo ./install_mediamtx.sh verify

# Uninstall MediaMTX
sudo ./install_mediamtx.sh uninstall

# Dry-run (show what would happen)
sudo ./install_mediamtx.sh --dry-run install

Options

Features

• Platform-aware: Linux (x86_64, ARM64, ARMv7, ARMv6), macOS, FreeBSD
• SHA256 checksum verification of downloaded binaries
• Atomic installation (writes to temp, then renames)
• Automatic rollback if verification fails
• Built-in upgrade support for MediaMTX 1.15.0+
• Creates dedicated mediamtx service user
• Generates default mediamtx.yml if not present

🔔 Webhook Alerts

lyrebird-alerts.sh — Pure-Bash webhook alerting with rate limiting and deduplication. No new dependencies required.

Usage

# Interactive setup wizard
./lyrebird-alerts.sh setup

# Send test alert
./lyrebird-alerts.sh test

# Send a custom alert
./lyrebird-alerts.sh send --level warning --title "Alert" --message "Something happened"

# Check configuration status
./lyrebird-alerts.sh status

# Show current config
./lyrebird-alerts.sh config

Supported Webhook Types

Configuration

# /etc/lyrebird/alerts.conf
LYREBIRD_ALERT_ENABLED=true
LYREBIRD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
LYREBIRD_WEBHOOK_TYPE="discord"
LYREBIRD_ALERT_RATE_LIMIT=300    # Seconds between duplicate alerts
LYREBIRD_HOSTNAME="field-unit-1"
LYREBIRD_LOCATION="North Forest"

Pre-Built Alert Functions

# Source in your scripts
source ./lyrebird-alerts.sh

alert_stream_down "mic1" "FFmpeg process died"
alert_stream_up "mic1"
alert_device_disconnect "USB_Mic_2"
alert_disk_warning "/" "82%"
alert_mediamtx_down
alert_network_down

📊 Prometheus Metrics

lyrebird-metrics.sh — Exports operational metrics in Prometheus/OpenMetrics text format for Grafana dashboards.

Usage

# One-time metrics output (stdout)
./lyrebird-metrics.sh

# Start HTTP server (for Prometheus scraping)
./lyrebird-metrics.sh serve --port 9100

# Export only stream metrics
./lyrebird-metrics.sh --streams-only

# Export only system metrics
./lyrebird-metrics.sh --system-only

Available Metrics

# Service status
lyrebird_mediamtx_up 1
lyrebird_mediamtx_uptime_seconds 3600

# Per-stream metrics
lyrebird_stream_active{name="mic1"} 1
lyrebird_stream_uptime_seconds{name="mic1"} 1800

# USB device status
lyrebird_usb_devices_total 3
lyrebird_usb_device_connected{name="mic1"} 1

# System resources
lyrebird_cpu_usage_percent 15.5
lyrebird_memory_usage_percent 45.2
lyrebird_disk_usage_percent{mount="/"} 62
lyrebird_load_average_1m 0.5

Prometheus Configuration

# prometheus.yml
scrape_configs:
  - job_name: 'lyrebird'
    static_configs:
      - targets: ['field-unit-1:9100']
    scrape_interval: 30s

💾 Storage Management

lyrebird-storage.sh — Manages disk space with configurable retention policies. Essential for long-running deployments.

Usage

# Check storage status
./lyrebird-storage.sh status

# Run cleanup (respects retention policy)
sudo ./lyrebird-storage.sh cleanup

# Emergency cleanup (aggressive)
sudo ./lyrebird-storage.sh emergency

# Monitor mode (continuous)
./lyrebird-storage.sh monitor --interval 300

Configuration

# /etc/lyrebird/storage.conf
RECORDING_RETENTION_DAYS=30   # Keep recordings for 30 days
LOG_RETENTION_DAYS=7          # Keep logs for 7 days
DISK_WARNING_PERCENT=80       # Warn at 80% disk usage
DISK_CRITICAL_PERCENT=90      # Critical at 90% usage
RECORDING_DIR="/var/recordings"
LOG_DIR="/var/log/lyrebird"

Automated Cleanup

# /etc/cron.d/lyrebird-storage
0 3 * * * root /path/to/lyrebird-storage.sh cleanup --quiet
*/15 * * * * root /path/to/lyrebird-storage.sh monitor --once

🔄 Version Manager

lyrebird-updater.sh — Safe git-based version management with transaction-based updates and automatic rollback.

Usage

# Interactive menu
./lyrebird-updater.sh

# Check for updates
./lyrebird-updater.sh --status

# List available versions
./lyrebird-updater.sh --list

# Rollback to previous version
./lyrebird-updater.sh --rollback

# Run post-update migrations manually
sudo ./lyrebird-updater.sh --migrate

Exit Codes

📚 Shared Library

lyrebird-common.sh — Utility functions shared across all scripts via sourcing. All scripts work with or without it (fallback definitions included).

Provided Functions

Exit Code Constants

E_SUCCESS=0
E_PERMISSION=2
E_MISSING_DEPS=3
E_CONFIG_ERROR=4
E_LOCKED=5