Ply Radio

Author

• Jason Page <jsp@pagetelegram.com>
• Organization: Amfile.org

Features

• 🎵 Automated Music Playback - Shuffle and play MP3 files from a directory
• 🎙️ TTS Announcements - Dynamic track announcements using Festival TTS
• 📻 Flexible Output Options:
- Local soundcard playback only - Icecast/Shoutcast streaming only - Both local and streaming simultaneously
• 🔊 Customizable Jingles - Set custom jingle messages and intervals
• ⚙️ Comprehensive CLI Options - Full control via command-line switches
• 🔄 Auto-reconnect - Automatic reconnection to Icecast/Shoutcast servers
• 🐧 Debian Packages - Easy installation via .deb packages for x86-64 and ARM64

Quick Start

Local Playback Only

bash
ply -l -d /path/to/music

Stream to Icecast with Local Playback

bash
ply -s -H radio.example.com -P mypassword -d /path/to/music

Stream Only (No Local Playback)

bash
ply -s -n -H radio.example.com -P mypassword -b 192k -d /path/to/music

Installation

Prerequisites

On Debian/Ubuntu/Raspbian:

bash
sudo apt update
sudo apt install mpg123 festival lame ffmpeg alsa-utils

From Debian Package

#### x86-64 (amd64)

bash
sudo dpkg -i ply-radio10.0amd64.deb
sudo apt-get install -f  # Install any missing dependencies

#### ARM64 (Raspberry Pi, etc.)

bash
sudo dpkg -i ply-radio10.0arm64.deb
sudo apt-get install -f

From Source

If you want to build from source, you'll need shc installed:

bash
sudo apt install shc

Then build:

bash
For x86-64

./build.sh

For ARM64 (run on ARM64 hardware)

./build-arm64.sh

Command-Line Options

Audio Source Options

• -d <directory> - Music directory path (default: ./music)

Playback Options

• -l - Local playback only (soundcard only, no streaming)
• -s - Enable streaming to Icecast/Shoutcast
• -n - No local playback (streaming only)

Jingle Options

• -j <text> - Jingle message text
• -t <number> - Number of tracks before jingle (default: 4, 0 to disable)
• -f <file> - Pre-generated jingle MP3 file (default: jingle.mp3)

Icecast/Shoutcast Options

• -H <host> - Icecast/Shoutcast host or IP
• -p <port> - Icecast/Shoutcast port (default: 8000)
• -P <password> - Icecast/Shoutcast source password
• -m <mount> - Icecast mount point (default: stream)
• -b <bitrate> - Stream bitrate (default: 128k, e.g., 64k, 192k, 320k)

Stream Metadata Options

• -N <name> - Stream name (default: Ply Radio Stream)
• -D <description> - Stream description
• -G <genre> - Stream genre (default: Various)
• -U <url> - Stream website URL

Audio Format Options

• -r <rate> - Sample rate (default: 44100)
• -c <channels> - Audio channels (default: 2)

Other Options

• -v - Show version information
• -h - Show help message

Examples

Basic Local Radio

bash
ply -l -d ~/Music -j "Welcome to My Radio!" -t 3

Professional Streaming Setup

bash
ply -s \
    -H stream.example.com \
    -P secret_password \
    -m live.mp3 \
    -b 192k \
    -d /var/music \
    -N "My Awesome Radio" \
    -D "The best music 24/7" \
    -G "Electronic" \
    -U "https://myradio.com" \
    -j "This is My Awesome Radio, playing the best electronic music!"

Raspberry Pi FM Transmitter + Stream

bash
ply -s \
    -H radio.example.com \
    -P mypassword \
    -d /home/pi/music \
    -t 5 \
    -j "You're listening to Pi FM on 88.0 MHz and online at pifm.com!"

Low-Bandwidth Streaming (for limited connections)

bash
ply -s -n -H radio.host.com -P pass -b 64k -r 22050 -d /music

Systemd Service Setup

Basic Setup

• Create a dedicated user (recommended):

bash
sudo useradd -r -s /bin/false -g audio ply
sudo mkdir -p /var/lib/ply-radio/music
sudo chown -R ply:audio /var/lib/ply-radio

• Copy your music:

bash
sudo cp -r /path/to/music/* /var/lib/ply-radio/music/

• Create service file /etc/systemd/system/ply-radio.service:

ini
[Unit]
Description=Ply Internet Radio
After=network.target sound.target

[Service]
Type=simple
User=ply
Group=audio
WorkingDirectory=/var/lib/ply-radio
ExecStart=/usr/bin/ply -s \
    -H your.icecast.server \
    -P your_password \
    -d /var/lib/ply-radio/music \
    -N "Your Station Name" \
    -j "Your jingle message here!"
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

• Enable and start:

bash
sudo systemctl daemon-reload
sudo systemctl enable ply-radio
sudo systemctl start ply-radio

• Check status:

bash
sudo systemctl status ply-radio
sudo journalctl -u ply-radio -f

More examples are available in /usr/share/ply-radio/examples/ after installation.

Building Packages

x86-64

bash
./build.sh

This creates build/ply-radio10.0amd64.deb

ARM64

On ARM64 hardware (Raspberry Pi, etc.):

bash
./build-arm64.sh

This creates build/ply-radio10.0arm64.deb

Architecture

Ply uses a producer-consumer architecture:
• Writer Process - Scans music directory, generates playlists, creates TTS announcements, and writes audio to a named pipe
• Reader Process(es) - Reads from the named pipe and outputs to:
- Local soundcard (via aplay) - Icecast/Shoutcast server (via ffmpeg) - Both simultaneously This design allows for reliable streaming with automatic reconnection and efficient resource usage.

Troubleshooting

No audio output

bash
Check ALSA devices

aplay -l

Test audio

speaker-test -t wav -c 2

Check volume

alsamixer

Festival TTS not working

bash
Test Festival

echo "Testing Festival" | text2wave -o test.wav
aplay test.wav

Install Festival if needed

sudo apt install festival festvox-us-slt-hts

Streaming connection issues

• Verify Icecast/Shoutcast server is accessible
• Check firewall rules
• Verify credentials (host, port, password, mount point)
• Check logs: sudo journalctl -u ply-radio -f

Performance issues on Raspberry Pi

• Lower bitrate: -b 64k or -b 96k
• Reduce sample rate: -r 22050
• Disable jingles: -t 0
• Use mono audio: -c 1

Dependencies

• mpg123 - MP3 playback
• festival - Text-to-speech engine
• lame - MP3 encoding
• ffmpeg - Audio processing and streaming
• alsa-utils - Audio output (aplay)
• shc - Shell script compiler (build-time only)

License

GNU General Public License v3.0 or later (GPL-3+) See LICENSE file or visit https://www.gnu.org/licenses/gpl-3.0.html

Project History

Ply evolved from "Hand Is Radio," an internet radio automation project. Version 10 represents a complete rewrite with:
• Enhanced command-line interface
• Flexible output options
• Improved error handling
• Professional packaging
• Multi-architecture support

Support

For issues, questions, or contributions:
• Email: jsp@pagetelegram.com
• Website: https://amfile.org

Contributing

Contributions are welcome! Please:
• Fork the repository
• Create a feature branch
• Make your changes
• Submit a pull request

Changelog

Version 10.0 (2025)

• Complete rewrite with enhanced CLI options
• Added local-only playback mode (-l)
• Added streaming-only mode (-n)
• Configurable jingle intervals and messages
• Enhanced Icecast/Shoutcast metadata support
• Improved error handling and reconnection logic
• Debian package creation for x86-64 and ARM64
• Systemd service file examples
• Comprehensive documentation

Version 9.x

• Original "Hand Is Radio" implementation
• Basic streaming and local playback
• TTS announcements

Acknowledgments

• Festival TTS team for the speech synthesis engine
• FFmpeg project for audio processing capabilities
• The Debian/Raspbian communities for packaging tools