Technical How-To

How to Configure Liquidsoap for Professional Radio Streaming

Complete technical walkthrough for installing Liquidsoap, writing automation scripts, configuring live DJ support, and streaming to Shoutcast Net servers.

45 min setup Advanced Production Ready
Liquidsoap command line configuration terminal showing script compilation and successful connection to Shoutcast Icecast streaming server

Overview

This guide walks you through installing Liquidsoap on Ubuntu/Debian, writing your first automation script, configuring live DJ input via harbor, adding playlists and failover logic, applying audio processing, and streaming the output to Shoutcast Net. By the end, you'll have a production-ready radio automation system.

Prerequisites
  • Linux server (Ubuntu 22.04 LTS or Debian 12 recommended)
  • Root or sudo access
  • Basic command line knowledge
  • Shoutcast Net account with server credentials
  • Music files organized with proper metadata

Step 1: Install Liquidsoap

Liquidsoap is available in most Linux distribution repositories. For Ubuntu/Debian, installation is straightforward:

Update package list and install Liquidsoap:
sudo apt update
sudo apt install liquidsoap liquidsoap-plugin-all -y

This installs Liquidsoap with all available plugins including MP3, AAC, Vorbis encoders, and various audio processing libraries.

Verify installation:
liquidsoap --version

You should see version information (e.g., "Liquidsoap 2.2.x"). If you need the latest features, install via OPAM or build from source following official documentation.

Additional Dependencies

For full functionality, install audio libraries:

sudo apt install lame libmp3lame-dev libfdk-aac-dev ffmpeg -y

Step 2: Prepare Your Music Library

Create a directory structure for your music and playlists:

mkdir -p /var/liquidsoap/music
mkdir -p /var/liquidsoap/playlists
mkdir -p /var/liquidsoap/jingles
mkdir -p /var/liquidsoap/logs

Upload your music files to /var/liquidsoap/music/. Ensure files have proper ID3 tags (artist, title, album) for metadata display.

Create a simple playlist file:
nano /var/liquidsoap/playlists/main.m3u

Add paths to your music files (one per line):

/var/liquidsoap/music/song1.mp3
/var/liquidsoap/music/song2.mp3
/var/liquidsoap/music/song3.mp3
Pro Tip: Normalize Audio

Use tools like ffmpeg-normalize or mp3gain to ensure consistent loudness across your library. Target -14 LUFS for streaming radio. This prevents jarring volume changes between tracks.

Step 3: Write Your First Liquidsoap Script

Create a basic automation script that plays a playlist and streams to Shoutcast Net:

nano /var/liquidsoap/radio.liq

Add the following basic configuration:

#!/usr/bin/liquidsoap

# Set log file
settings.log.file.set(true)
settings.log.file.path.set("/var/liquidsoap/logs/liquidsoap.log")

# Define your Shoutcast Net server details
host = "your-server.shoutcastnet.com"
port = 8000
password = "your-source-password"
mount = "/stream"

# Create a playlist source
music = playlist(
  mode="randomize",
  reload_mode="watch",
  "/var/liquidsoap/playlists/main.m3u"
)

# Apply smart crossfade (3 seconds)
music = crossfade(duration=3.0, music)

# Apply audio normalization
music = normalize(music)

# Output to Shoutcast
output.icecast(
  %mp3(bitrate=128),
  host=host,
  port=port,
  password=password,
  mount=mount,
  name="My Radio Station",
  description="Powered by Liquidsoap and Shoutcast Net",
  genre="Various",
  url="https://www.shoutcastnet.com",
  music
)
Configuration Notes
  • Replace your-server.shoutcastnet.com with your actual Shoutcast Net server hostname
  • Set password to your source password from Shoutcast Net control panel
  • Adjust mount to match your mount point (e.g., "/radio" or "/stream")
  • Change station name, description, genre, and URL to match your station

Make the script executable and test it:

chmod +x /var/liquidsoap/radio.liq
liquidsoap /var/liquidsoap/radio.liq

If configured correctly, you'll see connection messages and your stream will go live. Press Ctrl+C to stop.

Step 4: Add Live DJ Support with Harbor

Harbor allows DJs to connect directly to your Liquidsoap instance. Add this to your script before the output section:

# Harbor input for live DJ connections
live = input.harbor(
  "live",
  port=8001,
  password="your-dj-password"
)

# Fallback: if live is available, use it; otherwise use music
radio = fallback(
  track_sensitive=false,
  [live, music]
)

# Apply crossfade only to music, not live input
radio = crossfade(duration=3.0, radio)

# Apply normalization
radio = normalize(radio)

# Output this combined source instead of just music
output.icecast(
  %mp3(bitrate=128),
  host=host,
  port=port,
  password=password,
  mount=mount,
  name="My Radio Station",
  description="Powered by Liquidsoap and Shoutcast Net",
  genre="Various",
  url="https://www.shoutcastnet.com",
  radio  # Changed from 'music' to 'radio'
)

Now DJs can connect using any Icecast-compatible encoder (BUTT, Mixxx, OBS) to:

DJ Connection Details
  • Host: Your server IP or domain
  • Port: 8001
  • Mount: /live
  • Password: your-dj-password
  • Protocol: Icecast2

When a DJ connects, Liquidsoap automatically switches from playlist to live feed. When they disconnect, it seamlessly returns to the playlist.

Step 5: Advanced Features - Scheduling and Jingles

Add time-based switching and jingle insertion:

# Multiple playlists for different times
morning_show = playlist("/var/liquidsoap/playlists/morning.m3u")
evening_show = playlist("/var/liquidsoap/playlists/evening.m3u")
overnight = playlist("/var/liquidsoap/playlists/overnight.m3u")

# Jingles playlist
jingles = playlist(
  mode="randomize",
  reload_mode="watch",
  "/var/liquidsoap/playlists/jingles.m3u"
)

# Time-based switching (24-hour format, server time)
scheduled = switch([
  ({6h-12h}, morning_show),    # 6 AM - 12 PM
  ({18h-24h}, evening_show),   # 6 PM - Midnight
  ({true}, overnight)          # Default: overnight
])

# Insert jingle every 5 tracks
music_with_jingles = rotate(
  weights=[5, 1],
  [scheduled, jingles]
)

# Rest of your script continues...
# Apply crossfade, normalization, harbor, etc.
Smart Crossfading

Liquidsoap can detect silence at track beginnings/endings and adjust crossfade timing automatically. Add smart_crossfade for even smoother transitions that respect your audio cues.

Step 6: Audio Processing and Effects

Add professional audio processing to your stream:

# Normalize volume to -14 LUFS (broadcast standard)
radio = normalize(target=-14.0, radio)

# Apply compression (reduce dynamic range)
radio = compress(
  attack=50.0,     # milliseconds
  release=400.0,   # milliseconds
  threshold=-10.0, # dB
  ratio=3.0,       # compression ratio
  gain=3.0,        # makeup gain in dB
  radio
)

# Add a subtle high-pass filter to reduce rumble
radio = filter.iir.eq.high(freq=80.0, radio)

# Brick-wall limiter to prevent clipping
radio = limit(threshold=-1.0, radio)

# Apply stereo enhancement (subtle widening)
radio = stereo.width(0.7, radio)

These processing chains make your stream sound more professional and consistent. Adjust parameters based on your content type (music vs. talk).

Processing Order Matters

Apply effects in this order for best results: EQ → Compression → Normalization → Limiting. Over-processing can make audio sound unnatural, so adjust conservatively and test with real content.

Step 7: Create Systemd Service for Auto-Start

Configure Liquidsoap to start automatically on boot and restart on failure:

sudo nano /etc/systemd/system/liquidsoap.service

Add this service configuration:

[Unit]
Description=Liquidsoap Radio Automation
After=network.target sound.target

[Service]
Type=simple
User=liquidsoap
Group=liquidsoap
ExecStart=/usr/bin/liquidsoap /var/liquidsoap/radio.liq
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Create a dedicated user for security:

sudo useradd -r -s /bin/false liquidsoap
sudo chown -R liquidsoap:liquidsoap /var/liquidsoap/

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable liquidsoap
sudo systemctl start liquidsoap
sudo systemctl status liquidsoap

Check logs with:

sudo journalctl -u liquidsoap -f

Troubleshooting Common Issues

  • Verify server hostname, port, and password in your script
  • Check firewall rules allow outbound connections to Shoutcast server port
  • Test connectivity: telnet your-server.shoutcastnet.com 8000
  • Check Liquidsoap logs for detailed error messages
  • Ensure mount point doesn't have a leading slash conflict (try both "/stream" and "stream")

  • Check file paths are absolute (e.g., /var/liquidsoap/music/song.mp3)
  • Verify file permissions: Liquidsoap user needs read access to music files
  • Test playlist format: must be plain text with one file path per line
  • Check for unsupported file formats (Liquidsoap requires codecs installed)
  • Look for error messages in /var/liquidsoap/logs/liquidsoap.log

  • Verify harbor port (8001) is open in firewall: sudo ufw allow 8001/tcp
  • Check if port is bound: sudo netstat -tulpn | grep 8001
  • Ensure DJ uses correct mount point (e.g., /live)
  • Verify DJ password matches script configuration
  • Test with BUTT or another Icecast encoder using Icecast2 protocol

  • Reduce compression/limiting parameters if over-processed
  • Check source file quality: garbage in, garbage out
  • Increase MP3 bitrate: %mp3(bitrate=192) for better quality
  • Disable normalization temporarily to test if it's the cause
  • Monitor CPU usage: if maxed out, reduce processing or upgrade server

Next Steps and Optimization

Add Monitoring

Install Liquidsoap's telnet server for runtime monitoring and control. Access metadata, listener counts, and control sources remotely.

Implement Logging

Log played tracks to a database for royalty reporting and analytics. Use Liquidsoap's on_metadata callbacks.

Backup Configuration

Version control your Liquidsoap scripts with Git. Automate backups of playlists and configuration to prevent data loss.

Web Control Panel

Consider Azuracast or Libretime for web-based management. These platforms wrap Liquidsoap with user-friendly interfaces.

Learning Resources

Ready to Go Live?

Now that your Liquidsoap automation is configured, stream to Shoutcast Net for global delivery, CDN acceleration, and detailed listener analytics. Get started with a free trial or choose a plan that fits your audience size.

View Pricing Plans Read Full Blog Article

Need help integrating Liquidsoap with Shoutcast Net? Contact our support team for configuration assistance.