Skip to main content

​
Overview

Musique Agent runs on Raspberry Pi devices to provide reliable, dedicated audio playback for your locations. This guide covers the complete installation and configuration process for Raspberry Pi 4 devices.

​
Requirements

Before you begin, ensure you have:

Hardware

  • Raspberry Pi 4
  • Power supply
  • Audio output (3.5mm jack or HDMI)
  • SD card (16GB+ recommended)

Software

  • Debian-based OS (Ubuntu 24.04.3 LTS recommended)
  • ALSA audio system
  • PulseAudio
  • Docker
This guide assumes you have a fresh installation of Ubuntu 24.04.3 LTS on your Raspberry Pi 4.

​
Installation Process

​
Step 1: Install ALSA

ALSA (Advanced Linux Sound Architecture) is required for audio output.
1

Check if ALSA is installed

Run the following command to verify if ALSA is already present:
dpkg -l | grep alsa
If you see a list of packages, ALSA is already installed.
2

Install ALSA (if needed)

If ALSA is not installed, run:
sudo apt update
sudo apt install -y alsa-utils libasound2-plugins
3

Verify Installation

Check that audio devices are detected:
aplay -l
You should see your audio output device listed.

​
Step 2: Install PulseAudio

PulseAudio manages audio routing for the Musique Agent.
1

Check if PulseAudio is installed

Verify PulseAudio installation:
dpkg -l | grep pulseaudio
2

Install PulseAudio (if needed)

If not installed:
sudo apt update
sudo apt install -y pulseaudio
3

Verify Installation

Start PulseAudio (should produce no output if successful):
pulseaudio --check || pulseaudio --start

​
Step 3: Install Docker

Docker is used to run the Musique Agent container.
1

Check if Docker is installed

Verify Docker installation:
docker --version
If you see a version number, Docker is installed.
2

Install Docker (if needed)

Install Docker and configure permissions:
sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker
3

Verify Installation

Confirm Docker is working:
docker --version

​
Configuration

​
Configure ALSA for PulseAudio

Create an ALSA configuration file to route audio through PulseAudio.
1

Create Configuration File

Open the ALSA configuration file:
nano ~/.asoundrc
2

Add Configuration

Paste the following content:
pcm.!default {
  type pulse
  fallback "sysdefault"
}
ctl.!default {
  type pulse
}
3

Save and Exit

Press Ctrl + X, then Y, then Enter to save and exit.
4

Reboot

Reboot the Raspberry Pi to apply changes:
sudo reboot

​
Install Musique Agent

​
Download Docker Image

1

Authenticate with GitHub Registry

Login to the GitHub Container Registry using your organization token:
echo [YOUR_GITHUB_TOKEN] | docker login ghcr.io -u musique-app --password-stdin
Replace [YOUR_GITHUB_TOKEN] with the read-only token provided by your Musique administrator.
2

Pull the Image

Download the latest Musique Agent image:
docker pull ghcr.io/musique-app/musique-agent:latest

​
Run Musique Agent

1

Get Your User ID

Find your host user ID:
id -u
Note the number (typically 1000).
2

Run the Container

Start the Musique Agent with your credentials:
docker run --rm \
  --device /dev/snd \
  -v /run/user/1000/pulse:/run/pulse \
  -e USERNAME=[your_username] \
  -e PASSWORD=[your_password] \
  -e PULSE_SERVER=unix:/run/pulse/native \
  ghcr.io/musique-app/musique-agent:latest
  • Replace [your_username] and [your_password] with your Musique account credentials
  • Replace 1000 with your actual user ID from the previous step
3

Verify Connection

The agent should connect to Musique servers and appear online in your Analytics dashboard.

​
Enable Auto-Start on Boot

Configure the Musique Agent to start automatically when the Raspberry Pi boots.
1

Create Systemd Service

Run the following command to create a systemd service (replace 1000, [your_username], and [your_password]):
echo "[Unit]
Description=Musique agent
After=network.target

[Service]
Restart=always
ExecStart=/usr/bin/docker run --rm \
  --device /dev/snd \
  -v /run/user/1000/pulse:/run/pulse \
  -e USERNAME=[your_username] \
  -e PASSWORD=[your_password] \
  -e PULSE_SERVER=unix:/run/pulse/native \
  ghcr.io/musique-app/musique-agent:latest
ExecStop=/usr/bin/docker stop ghcr.io/musique-app/musique-agent:latest

[Install]
WantedBy=multi-user.target" | sudo tee /etc/systemd/system/musique-agent.service > /dev/null
2

Enable the Service

Enable and start the service:
sudo systemctl daemon-reload
sudo systemctl enable musique-agent
3

Reboot and Test

Reboot to test auto-start:
sudo reboot
After reboot, the agent should start automatically.

​
Verify Installation

After installation, verify everything is working:
View the service status:
sudo systemctl status musique-agent
Status should show “active (running)”.
Check agent logs for any issues:
sudo journalctl -u musique-agent -f
Press Ctrl + C to exit.
Verify audio output is working:
speaker-test -t wav -c 2
You should hear test sounds. Press Ctrl + C to stop.
  • Log into your Musique dashboard
  • Navigate to Analytics
  • Verify the device appears as online

​
Troubleshooting

Check audio device:
aplay -l
Verify PulseAudio is running:
pulseaudio --check || pulseaudio --start
Test audio directly:
speaker-test -t wav -c 2
Check service status:
sudo systemctl status musique-agent
View error logs:
sudo journalctl -u musique-agent -n 50
Common issues:
  • Incorrect username/password
  • Network connectivity issues
  • Docker not running: sudo systemctl start docker
Add user to docker group:
sudo usermod -aG docker $USER
newgrp docker
Log out and log back in for changes to take effect.
  • Check internet connection
  • Verify credentials are correct
  • Check service is running: sudo systemctl status musique-agent
  • Review logs: sudo journalctl -u musique-agent -f
  • Test network connection: ping google.com

​
Managing the Agent

​
Service Commands

sudo systemctl start musique-agent

​
Update the Agent

To update to the latest version:
1

Stop the Service

sudo systemctl stop musique-agent
2

Pull Latest Image

docker pull ghcr.io/musique-app/musique-agent:latest
3

Restart the Service

sudo systemctl start musique-agent

​
Best Practices

Network Connection

Use wired Ethernet connection for best stability and audio quality.

Power Supply

Use official Raspberry Pi power supply to prevent stability issues.

Audio Output

Test audio output before deploying to ensure proper configuration.

Regular Updates

Keep the agent updated to receive latest features and bug fixes.

Monitor Status

Regularly check device status in Analytics dashboard.

Backup Config

Keep a copy of your systemd service file for easy redeployment.

​
Next Steps

Create Schedules

Set up audio schedules for your new Raspberry Pi device.

Monitor Performance

Track your device status and network quality in Analytics.

Test Network

Use the Speed Test tool to verify connection quality.

FAQ

Find answers to common Raspberry Pi setup questions.