Technical Documentation

This document provides detailed technical information about the MediaMTX RTSP Audio Setup, including architecture, component interactions, configuration details, and advanced troubleshooting.

Table of Contents

• [Architecture Overview](#architecture-overview)
• [Component Details](#component-details)
• [Configuration Reference](#configuration-reference)
• [Advanced Usage](#advanced-usage)
• [Technical Troubleshooting](#technical-troubleshooting)
• [Security Considerations](#security-considerations)
• [Performance Tuning](#performance-tuning)

Architecture Overview

The system consists of two main components:

1. MediaMTX Server: A lightweight RTSP/RTMP/HLS/WebRTC server that handles media streaming protocols
2. Audio Capture Service: A systemd service that detects audio devices and streams them to MediaMTX

Process Flow

USB Audio Devices → ALSA → ffmpeg → MediaMTX → RTSP/RTMP/HLS Clients

1. USB audio devices are detected via ALSA
2. ffmpeg captures audio and encodes it (MP3 @ 160kbit)
3. Streams are published to MediaMTX via RTSP
4. Clients connect to MediaMTX to consume audio streams

Component Details

MediaMTX Server

• Binary Location: /usr/local/mediamtx/mediamtx
• Configuration: /etc/mediamtx/mediamtx.yml
• Service: mediamtx.service
• Logs: /var/log/mediamtx/mediamtx.log
• User: mediamtx (system user)

MediaMTX is configured with custom ports to avoid conflicts:

• RTSP: 18554 (standard is 8554)
• RTMP: 11935 (standard is 1935)
• HLS: 18888
• WebRTC: 18889
• Metrics: 19999

Audio Capture Service

• Script Location: /usr/local/bin/startmic.sh
• Original Script Backup: /usr/local/bin/startmic.sh.original
• Configuration: /etc/audio-rtsp/config
• Service: audio-rtsp.service
• Logs: /var/log/audio-rtsp/audio-streams.log and /var/log/audio-rtsp/service-error.log

The audio capture service uses ffmpeg with the following parameters:

• Audio input: ALSA (plughw:CARD=$CARD_ID,DEV=0)
• Audio channels: 1 (mono) for capture, 2 (stereo) for output
• Codec: MP3 (libmp3lame)
• Bitrate: 160kbps
• Transport: RTSP over TCP

Configuration Reference

MediaMTX Configuration

The minimal MediaMTX configuration at /etc/mediamtx/mediamtx.yml includes:

logLevel: info
logDestinations: [stdout, file]
logFile: /var/log/mediamtx/mediamtx.log

rtspAddress: :18554
rtmpAddress: :11935
hlsAddress: :18888
webrtcAddress: :18889

metrics: yes
metricsAddress: :19999

paths:
  all:

This configuration allows any path to be published, which is suitable for dynamic audio device detection.

Audio RTSP Service Configuration

The configuration at /etc/audio-rtsp/config controls the behavior of the audio streaming service:

# RTSP server port (default: 8554, configured: 18554)
RTSP_PORT=18554

# Number of seconds to wait before restart attempts
RESTART_DELAY=10

# Maximum number of restart attempts before giving up
MAX_RESTART_ATTEMPTS=5

# Logging level (debug, info, warning, error)
LOG_LEVEL=info

# Path to the log directory
LOG_DIR=/var/log/audio-rtsp

# Log rotation settings
LOG_ROTATE_DAYS=7

Advanced Usage

Custom Stream Parameters

To modify the ffmpeg parameters for all streams, edit the /usr/local/bin/startmic.sh file. Look for the ffmpeg command line and adjust parameters as needed.

For example, to change the audio quality:

# Change from:
ffmpeg -nostdin -f alsa -ac 1 -i "plughw:CARD=$CARD_ID,DEV=0" \
      -acodec libmp3lame -b:a 160k -ac 2 -content_type 'audio/mpeg' \
      -f rtsp "$RTSP_URL" -rtsp_transport tcp &

# To (example for higher quality):
ffmpeg -nostdin -f alsa -ac 1 -i "plughw:CARD=$CARD_ID,DEV=0" \
      -acodec libmp3lame -b:a 256k -ac 2 -content_type 'audio/mpeg' \
      -f rtsp "$RTSP_URL" -rtsp_transport tcp &

Running Behind a Reverse Proxy

If you want to expose the streams through a reverse proxy like Nginx, add an RTSP proxy configuration:

stream {
    server {
        listen 8554;
        proxy_pass 127.0.0.1:18554;
        proxy_timeout 3m;
        proxy_connect_timeout 3m;
    }
}

Excluding Specific Audio Devices

The default implementation skips certain known system audio devices. To exclude additional devices, modify the condition in startmic.sh:

# Find this block:
if [ "$CARD_ID" =~ ^(bcm2835_headpho](/tomtom215/mediamtx-rtsp-setup/wiki/vc4-hdmi|HDMI)$-); then
    echo "Skipping system audio device: $CARD_ID"
    continue
fi

# Modify to add your device IDs:
if [ "$CARD_ID" =~ ^(bcm2835_headpho](/tomtom215/mediamtx-rtsp-setup/wiki/vc4-hdmi|HDMI|your_device_id)$-); then
    echo "Skipping system audio device: $CARD_ID"
    continue
fi

Technical Troubleshooting

Debugging Audio Device Detection

To manually list all audio capture devices:

arecord -l

To test audio capture from a specific device:

# Replace CARD_ID with your device ID
arecord -D plughw:CARD=CARD_ID,DEV=0 -d 10 -f cd test.wav

Monitoring RTSP Session Activity

To see active RTSP sessions:

# Install netstat if not available
apt-get install net-tools

# Check connections to the RTSP port
netstat -tan | grep 18554

Testing MediaMTX Directly

To publish a test stream directly to MediaMTX:

ffmpeg -f lavfi -i "sine=frequency=1000:sample_rate=44100" -acodec libmp3lame -b:a 128k -f rtsp rtsp://localhost:18554/test

To connect to the test stream:

ffplay rtsp://localhost:18554/test

Debugging ffmpeg Issues

If you suspect ffmpeg issues, you can run it manually with more verbose output:

ffmpeg -v debug -nostdin -f alsa -ac 1 -i "plughw:CARD=CARD_ID,DEV=0" \
      -acodec libmp3lame -b:a 160k -ac 2 -content_type 'audio/mpeg' \
      -f rtsp rtsp://localhost:18554/test -rtsp_transport tcp

Security Considerations

Network Security

By default, MediaMTX and the audio streams are accessible to anyone on your network. Consider:

1. Firewall Configuration: Restrict access to the streaming ports

   # Allow only specific IPs to access RTSP
   sudo ufw allow from 192.168.1.0/24 to any port 18554 proto tcp
   

2. RTSP Authentication: Modify MediaMTX configuration to require authentication:

   paths:
     all:
       readUser: myuser
       readPass: mypass
   

System User Permissions

The MediaMTX service runs as the mediamtx user, while the audio-rtsp service runs as root (to access audio devices). To improve security:

1. Create a dedicated user for audio streaming with only the necessary permissions
2. Add this user to the audio group to access sound devices

Performance Tuning

System Resource Allocation

For systems running many audio streams, consider adjusting:

1. Process Priorities:

   # Give higher priority to ffmpeg processes
   echo 'RTPRIO=99' >> /etc/security/limits.conf
   echo '* - rtprio 99' >> /etc/security/limits.conf
   

2. Memory Allocation:

   # Add to /etc/systemd/system/audio-rtsp.service in the [Service] section
   MemoryHigh=500M
   MemoryMax=1G
   

Network Buffer Tuning

For improved network performance:

# Add to /etc/sysctl.conf
net.core.rmem_max=8388608
net.core.wmem_max=8388608

CPU Usage Optimization

If you're experiencing high CPU usage:

1. Lower the audio quality:

   -b:a 96k  # Lower bitrate
   

2. Reduce the sample rate:

   -ar 22050  # Half of CD quality
   

3. Use a more efficient codec if supported by your clients:

   -acodec aac -b:a 96k
   

Further Customization

Supporting Additional Audio Processing

To add audio processing (like compression, noise reduction):

ffmpeg -nostdin -f alsa -ac 1 -i "plughw:CARD=$CARD_ID,DEV=0" \
      -af "compand=0|0:1|1:-90/-60|-60/-40|-40/-30|-20/-20:6:0:-90:0.2" \
      -acodec libmp3lame -b:a 160k -ac 2 -content_type 'audio/mpeg' \
      -f rtsp "$RTSP_URL" -rtsp_transport tcp &

This example adds dynamic range compression to make quiet sounds louder and loud sounds quieter.