Troubleshooting

Start Here: Quick Check

Always run the built-in diagnostics first — they check all common failure points automatically:

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

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

The exit code tells you the severity:

No USB Devices Found

Symptom: Stream manager reports no USB audio devices, or device list is empty.

# Step 1: Check what Linux sees
lsusb | grep -i audio
arecord -l

# Step 2: Check ALSA device enumeration
cat /proc/asound/cards

# Step 3: Verify udev rules exist
sudo cat /etc/udev/rules.d/99-usb-soundcards.rules

# Step 4: Reload udev and check symlinks
sudo udevadm control --reload-rules
sudo udevadm trigger
ls -la /dev/snd/by-usb-port/

# Step 5: Re-run device mapping
sudo ./usb-audio-mapper.sh

# Step 6: Reboot (required for udev rules)
sudo reboot

Streams Won't Start

Symptom: Start command completes but no streams are active, or streams immediately die.

# Check stream manager logs
sudo tail -50 /var/log/lyrebird-stream-manager.log

# Check per-device FFmpeg logs
sudo tail -50 /var/log/lyrebird/*.log

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

# Check if MediaMTX is running
./install_mediamtx.sh status
curl -s http://localhost:9997/v3/paths/list | head -20

# Try a force-restart
sudo ./lyrebird-stream-manager.sh force-stop
sudo ./lyrebird-stream-manager.sh start

Common causes:

• MediaMTX is not running — start it first
• Configuration has an unsupported sample rate for the device
• Device is busy (another process has it open)
• Lock file is stale from a crashed previous run

# Check if device is busy
sudo lsof /dev/snd/*

# Remove stale lock file
sudo rm -f /run/mediamtx-audio.lock /run/mediamtx-audio.pid

Device Names Change After Reboot

Symptom: Device_1 becomes Device_2 after reboot, or devices swap names.

# Verify udev rules are in place
cat /etc/udev/rules.d/99-usb-soundcards.rules

# Check if symlinks exist
ls -la /dev/snd/by-usb-port/

# Reload udev
sudo udevadm control --reload-rules
sudo udevadm trigger

# Re-run mapper if rules are missing/incorrect
sudo ./usb-audio-mapper.sh

# Reboot to apply
sudo reboot

Permission Errors

Symptom: "Permission denied" errors when accessing audio devices or log directories.

# Add your user to the audio group
sudo usermod -a -G audio $USER

# Fix log directory permissions
sudo mkdir -p /var/log/lyrebird
sudo chmod 755 /var/log/lyrebird

# Fix state directory permissions
sudo mkdir -p /var/lib/mediamtx-ffmpeg
sudo chmod 755 /var/lib/mediamtx-ffmpeg

# Apply group changes (requires reboot or re-login)
sudo reboot

MediaMTX Crashes

Symptom: MediaMTX process dies unexpectedly, streams go offline.

# Check system resources
free -h
df -h
ulimit -n

# View crash logs
sudo journalctl -u mediamtx -n 100

# Increase file descriptor limits
sudo bash -c 'echo "* soft nofile 4096" >> /etc/security/limits.conf'
sudo bash -c 'echo "* hard nofile 8192" >> /etc/security/limits.conf'
sudo bash -c 'echo "mediamtx soft nofile 4096" >> /etc/security/limits.conf'
sudo bash -c 'echo "mediamtx hard nofile 8192" >> /etc/security/limits.conf'

# Restart the service
sudo systemctl restart mediamtx

High CPU Usage

Symptom: System becomes unresponsive, CPU at 100%.

# Identify which processes are hot
sudo ./lyrebird-stream-manager.sh monitor
top -p $(pgrep -f ffmpeg | tr '\n' ',')

Solutions:

• Reduce sample rate: change SAMPLE_RATE=48000 to 16000
• Use a lower bitrate: BITRATE=64k instead of 192k
• Reduce number of simultaneous streams
• Check for FFmpeg zombie process accumulation (ps aux | grep ffmpeg)

# Clean up zombie FFmpeg processes
sudo pkill -f ffmpeg
sudo ./lyrebird-stream-manager.sh start

Update Failed

Symptom: lyrebird-updater.sh reports errors, git conflicts, or update won't complete.

# Check repository state
git status
git stash list

# Check update status
./lyrebird-updater.sh --status

# Stash local changes and retry
git stash
./lyrebird-updater.sh

# Reset to known-good state
git reset --hard origin/main
git checkout $(git describe --tags --abbrev=0)
chmod +x *.sh

Debug Procedures

Enable Debug Mode

export DEBUG=1
sudo ./lyrebird-stream-manager.sh start

Test FFmpeg Directly

# Test ALSA capture for a specific device
arecord -D hw:0,0 -f cd -t wav -d 5 test.wav

# Test FFmpeg capture and publish
ffmpeg -f alsa -i hw:0,0 \
  -acodec libopus \
  -b:a 128k \
  -ar 48000 \
  -ac 2 \
  -f rtsp \
  rtsp://localhost:8554/test

Test RTSP Connectivity

# Check if port 8554 is listening
ss -tlnp | grep 8554

# Test RTSP connection
ffplay -i rtsp://localhost:8554/Device_1 -loglevel debug 2>&1 | head -50

# Check MediaMTX API
curl -s http://localhost:9997/v3/paths/list | python3 -m json.tool

Log Locations

# Follow all lyrebird logs in real time
sudo tail -f /var/log/lyrebird-stream-manager.log /var/log/lyrebird/*.log

# Follow systemd service logs
sudo journalctl -u mediamtx-audio -f

Collecting Debug Information for Bug Reports

When filing a GitHub issue, please include the following:

# 1. Run full diagnostics (safe to share)
sudo ./lyrebird-diagnostics.sh full > /tmp/diagnostics.txt 2>&1

# 2. Collect logs (review before sharing — may contain paths)
tar -czf /tmp/lyrebird-logs-$(date +%Y%m%d).tar.gz \
  /var/log/mediamtx.out \
  /var/log/lyrebird-stream-manager.log \
  /var/log/lyrebird/*.log \
  /etc/mediamtx/audio-devices.conf \
  /etc/udev/rules.d/99-usb-soundcards.rules 2>/dev/null

# 3. System info
cat /etc/os-release > /tmp/system-info.txt
uname -a >> /tmp/system-info.txt
lsusb >> /tmp/system-info.txt
bash --version >> /tmp/system-info.txt

Include /tmp/diagnostics.txt, the logs tarball, and /tmp/system-info.txt in your GitHub issue.