Basic Usage - LyreBirdAudio Docs

On this page

Using the Orchestrator
Managing Streams
Accessing Streams
Multiplex Streaming
Systemd Service
Health Monitoring

Using the Orchestrator

The Orchestrator is the recommended entry point for all management tasks. It provides a menu-driven interface that delegates to the individual specialized scripts.

sudo ./lyrebird-orchestrator.sh

Main Menu

Option	Action
1. Quick Setup Wizard	Guided first-time setup (install, map, configure, start)
2. MediaMTX Installation & Updates	Install, update, or check MediaMTX version
3. USB Device Management	Map devices, detect capabilities, validate configuration
4. Audio Streaming Control	Start, stop, restart streams; view status
5. System Diagnostics	Run quick, full, or debug health checks
6. Version Management	Update scripts, check versions, rollback
7. Logs & Status	View stream logs, system logs, service status

Managing Streams

The Stream Manager handles all FFmpeg process lifecycle. You can use it directly or through the Orchestrator.

Stream Manager Commands

start Detect USB devices, configure, and start all streams

stop Gracefully stop all running streams

restart Stop then start all streams

status Show status of all active streams and processes

monitor Check health and restart any failed streams (used by cron)

config Display current stream configuration

force-stop Force kill all streams and clean up stale files

install Install as systemd service with cron health monitoring

# Start all streams
sudo ./lyrebird-stream-manager.sh start

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

# Stop all streams
sudo ./lyrebird-stream-manager.sh stop

# Restart after configuration change
sudo ./lyrebird-stream-manager.sh restart

# Force cleanup (use when graceful stop fails)
sudo ./lyrebird-stream-manager.sh force-stop
sudo ./lyrebird-stream-manager.sh start

Accessing Streams

Streams are served over RTSP on port 8554. The stream path matches the device's friendly name.

Stream URLs

# Default pattern
rtsp://your-server-ip:8554/Device_1
rtsp://your-server-ip:8554/Device_2

# With custom device names (from udev mapping)
rtsp://192.168.1.100:8554/front-mic
rtsp://192.168.1.100:8554/rear-mic

RTSP Clients

Client	Command / Usage
ffplay	`ffplay rtsp://localhost:8554/Device_1`
VLC	`vlc rtsp://localhost:8554/Device_1`
FFmpeg (record)	`ffmpeg -i rtsp://ip:8554/Device_1 -c copy out.mkv`
OBS Studio	Add Source → Media Source → enter RTSP URL
GStreamer	`gst-launch-1.0 rtspsrc location=rtsp://... ! ...`

WebRTC Streaming

MediaMTX also provides WebRTC access via a built-in web player at:

http://your-server-ip:8889/Device_1

Multiplex Streaming

Multiplex mode combines multiple USB microphones into a single RTSP stream using FFmpeg audio filters. This is useful for recording all microphones as one feed or for centralized monitoring.

amix — Audio Mixing

Mixes all device inputs into a single stereo stream. All inputs are combined with equal weight.

sudo ./lyrebird-stream-manager.sh -m multiplex -f amix start
# Output: rtsp://host:8554/all_mics

amerge — Channel Merging

Concatenates inputs preserving separate channels. 3 stereo mics → 6-channel stream.

sudo ./lyrebird-stream-manager.sh -m multiplex -f amerge start
# Output: rtsp://host:8554/all_mics

Custom Stream Name

sudo ./lyrebird-stream-manager.sh -m multiplex -n studio start
# Output: rtsp://host:8554/studio

Feature	amix (Mixing)	amerge (Merging)
Output channels	Fixed (typically 2)	Sum of all inputs
Channel separation	Lost (mixed together)	Preserved per-device
Bandwidth	Lower	Higher
Post-processing	Limited	Full per-channel access
Best for	Monitoring, simple recording	Professional audio, forensics

Systemd Service (Recommended for Production)

For 24/7 operation, the stream manager must be installed as a systemd service. Without it, streams stop when the terminal session ends or the system reboots.

# Install and enable the service
sudo ./lyrebird-stream-manager.sh install
sudo systemctl enable mediamtx-audio
sudo systemctl start mediamtx-audio

# Service management
sudo systemctl status mediamtx-audio
sudo systemctl restart mediamtx-audio
sudo journalctl -u mediamtx-audio -f    # Follow live logs

The systemd installation also:

Creates a cron job at /etc/cron.d/mediamtx-monitor for health checks every 5 minutes
Enables systemd watchdog integration for process supervision
Configures graceful shutdown ordering

💡

When Direct Script Execution is OK

Running the script directly (without systemd) is fine for: one-time testing, development, debugging, or short manual recording sessions. For anything running continuously, use the systemd service.

Health Monitoring

# Quick health check (run daily)
sudo ./lyrebird-diagnostics.sh quick

# Full diagnostics (run weekly)
sudo ./lyrebird-diagnostics.sh full

# Monitor stream resources
./lyrebird-stream-manager.sh monitor

# View live logs
sudo tail -f /var/log/lyrebird-stream-manager.log
sudo tail -f /var/log/lyrebird/*.log

See the Diagnostics & Monitoring page for full details.