Linux - Musique App

Overview

Musique Agent runs on Linux devices — including the Raspberry Pi — to provide reliable, dedicated audio playback for your locations. This guide covers three different installation methods to suit your deployment needs.

Choose Your Installation Method

Select the installation method that best fits your use case:

Manual Installation

Best for:

Learning and understanding each component
Custom configurations
Troubleshooting and development
Full control over the process

Automated Script

Best for:

Quick POCs (Proof of Concepts)
Single device deployments
One-by-one installations
Simplified setup

Ansible Deployment

Best for:

Bulk installations (10+ devices)
Fleet management
Standardized configurations
Massive deployments

Method 1: Manual Installation

This method walks through the same steps the automated script performs, one at a time. Choose it when you need full control over the installation process, want to understand each component, or need to customize your setup.

How it works: Musique runs as two parts. The Updater — a small Java application — runs on the host as a systemd service called musique. On startup it downloads, launches, and keeps the Agent (also a Java application) up to date. You install and configure the Updater; the Updater manages the Agent for you, so there is nothing else to run by hand.

Requirements

Before you begin, ensure you have:

Hardware

A Linux device (e.g. Raspberry Pi 4)
Power supply
Audio output (3.5mm jack or HDMI)
Storage (16GB+ recommended)

Software

Debian-based OS (Ubuntu 24.04.3 LTS or Raspberry Pi OS 64-bit)
Java 17 or newer (runs the Updater and Agent)
ALSA audio system
PulseAudio (or PipeWire with Pulse compatibility)

This guide assumes a fresh installation of Ubuntu 24.04.3 LTS or Raspberry Pi OS (64-bit). One installer serves every Linux device — the Updater and Agent are architecture-independent Java, and apt installs the matching native JVM and audio packages for your machine automatically. Run every command as root — either prefix each with sudo, or switch to a root shell first with sudo su -.

Step 1: Update System Packages

Refresh the package index before installing dependencies:

sudo apt update

Step 2: Install CA Certificates

The Updater downloads over HTTPS, so the system needs an up-to-date set of trusted root certificates:

sudo apt install -y ca-certificates
sudo update-ca-certificates

Step 3: Install Java

The Updater and Agent are Java 17 applications and run on any newer JRE.

Check for an existing Java

java -version

If it reports version 17 or newer, skip to the next step.

Install Java 17 (if needed)

sudo apt install -y openjdk-17-jre-headless

If openjdk-17-jre-headless is not available on your distribution, install the default JRE instead (Java 21 on Debian trixie is fine):

sudo apt install -y default-jre-headless

Step 4: Install ALSA

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

Install ALSA

sudo apt install -y alsa-utils libasound2-plugins

Verify Installation

Check that audio devices are detected:

aplay -l

You should see your audio output device listed.

Step 5: Install PulseAudio

PulseAudio manages audio routing for the Agent.

Check for PipeWire first

Newer Raspberry Pi OS images use PipeWire, which already provides the Pulse socket the Agent needs. If the following reports it as installed, skip the PulseAudio install — installing PulseAudio would conflict with and remove PipeWire:

dpkg -s pipewire-pulse

Install PulseAudio (if PipeWire is absent)

sudo apt install -y pulseaudio

Enable session lingering

Lingering keeps the user session — and its PulseAudio socket at /run/user/<uid>/pulse — alive at boot without an interactive login:

sudo loginctl enable-linger $USER

Configuration

Configure ALSA for PulseAudio

Route audio through PulseAudio with a system-wide ALSA configuration. The Agent runs as a child of the root Updater rather than as the desktop user, so the routing must live in /etc/asound.conf (which root also reads), not in a user’s ~/.asoundrc.

Create the configuration file

sudo nano /etc/asound.conf

Add configuration

Paste the following content:

pcm.!default {
    type pulse
    fallback "sysdefault"
}

ctl.!default {
    type pulse
}

Save and exit by pressing Ctrl + X, then Y, then Enter.

Create Directories

Create the Musique install directory and its sub-folders:

sudo mkdir -p /opt/musique/config /opt/musique/logs /opt/musique/musics

Install the Updater

Download the Updater

Download the latest Updater JAR into the install directory (replace the version with the current release if needed):

sudo curl -fL https://musique-portal.s3.us-east-1.amazonaws.com/public/agent/releases/updater-3.0.0.jar -o /opt/musique/updater-3.0.0.jar

Create the Launcher

The Updater renames its own JAR when it self-updates, so the launcher resolves the newest updater-*.jar at each start rather than pinning a filename.

Create the launcher script

sudo nano /opt/musique/run.sh

Add the launcher content

Paste the following:

#!/bin/bash
cd "/opt/musique"
JAR="$(ls -1 updater-*.jar 2>/dev/null | grep -v -- '-download' | sort -V | tail -n 1)"
if [[ -z "$JAR" ]]; then
  echo "No updater JAR found in /opt/musique" >&2
  exit 1
fi
exec /usr/bin/java -jar "$JAR"

Save and exit, then make it executable:

sudo chmod 755 /opt/musique/run.sh

Create the Config File

Only your credentials go here — the Updater fills in every other setting from its bundled defaults on first boot.

Create the config file

sudo nano /opt/musique/config/config.json

Add your credentials

Paste the following, replacing the placeholders with your Musique credentials:

{
  "username": "your_username",
  "password": "your_password"
}

Save and exit, then restrict the file’s permissions since it holds a password:

sudo chmod 600 /opt/musique/config/config.json

Enable Auto-Start on Boot

Create a systemd service so the Updater starts automatically when the device boots. The service runs as root: the Updater manages the Agent process and restarts this unit from its emergency-rollback scripts. The ExecStartPre/ExecStopPost hooks clear any stray Agent JVM so a crashed run can’t leave a second player running.

Create the systemd service

echo "[Unit]
Description=Musique Updater
Wants=network-online.target
After=network-online.target

[Service]
WorkingDirectory=/opt/musique
Environment=LOG_DIR=/opt/musique/logs
ExecStartPre=-/usr/bin/pkill -f agent-.*jar
ExecStart=/opt/musique/run.sh
ExecStopPost=-/usr/bin/pkill -f agent-.*jar
Restart=always
RestartSec=10

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

Enable the service

sudo systemctl daemon-reload
sudo systemctl enable musique

Reboot and test

Reboot to apply all changes:

sudo reboot

After reboot, the Updater starts automatically, downloads and launches the Agent, and the device should appear online in your Analytics dashboard.

Verify Installation

After installation, verify everything is working:

Check Service Status

View the service status:

sudo systemctl status musique

Status should show “active (running)”.

View Logs

Check the Updater logs for any issues:

sudo journalctl -u musique -f

Press Ctrl + C to exit.

Check the Agent Process

Confirm the Updater has launched the Agent:

pgrep -af 'agent-.*jar'

You should see a running java -jar agent-*.jar process.

Test Audio Playback

Verify audio output is working:

speaker-test -t wav -c 2

You should hear test sounds. Press Ctrl + C to stop.

Check Online Status

Log into your Musique dashboard
Navigate to Analytics
Verify the device appears as online

Troubleshooting

No audio output

Check audio device:

aplay -l

Verify PulseAudio is running:

pulseaudio --check || pulseaudio --start

Test audio directly:

speaker-test -t wav -c 2

Service not starting

Check service status:

sudo systemctl status musique

View error logs:

sudo journalctl -u musique -n 50

Common issues:

Incorrect username/password in /opt/musique/config/config.json
No Updater JAR found in /opt/musique
Java not installed or older than 17: java -version
Missing CA certificates blocking the HTTPS download: sudo apt install -y ca-certificates && sudo update-ca-certificates
Network connectivity issues

Device offline in dashboard

Check internet connection
Verify credentials in /opt/musique/config/config.json are correct
Check the service is running: sudo systemctl status musique
Confirm the Agent is up: pgrep -af 'agent-.*jar'
Review logs: sudo journalctl -u musique -f
Test network connection: ping google.com

Managing the Agent

Service Commands

sudo systemctl start musique

sudo systemctl stop musique

sudo systemctl restart musique

sudo systemctl status musique

sudo journalctl -u musique -f

sudo systemctl disable musique

Update the Agent

The Updater checks for and applies new Agent and Updater versions automatically — no manual download is required. To force a fresh check, simply restart the service:

sudo systemctl restart musique

Method 2: Automated Script Installation

The automated installation script provides a quick and easy way to install the Musique Agent on Linux devices. A single script serves every architecture — it detects the machine and installs the right packages. This method is ideal for POCs (Proof of Concepts), single device deployments, and simplified setup.

Prerequisites

Hardware

A Linux device (e.g. Raspberry Pi 4)
Power supply
Audio output (3.5mm jack or HDMI)
Storage (16GB+ recommended)

Software

Debian-based OS (Ubuntu 24.04.3 LTS or Raspberry Pi OS recommended)
Internet connection
Root or sudo access

Installation Steps

Switch to Root User (if needed)

If you’re not logged in as root, switch to superuser mode:

sudo su -

Running the installation script as root ensures all system-level configurations are applied correctly.

Download the Installation Script

Download the automated installation script:

curl -fsSL https://musique-portal.s3.us-east-1.amazonaws.com/public/agent/install-linux.sh > install.sh

Make the Script Executable

Grant execution permissions to the script:

chmod a+x install.sh

Run the Installation Script

Execute the installation script:

./install.sh

You will be prompted for your Musique username and password. The script then automatically handles:

System package updates
CA certificate setup (TLS trust for HTTPS downloads)
Java runtime installation (runs the Updater and Agent)
ALSA installation
PulseAudio installation and configuration
Audio routing configuration (system-wide /etc/asound.conf)
Musique Updater download and setup
Systemd service setup for auto-start

The installation process may take 5-15 minutes depending on your internet connection and system resources. The Updater downloads and launches the Agent on first boot.

Post-Installation

The installation script automatically configures the Musique Agent to start on system boot. Use the same service management commands as described in the manual installation method.

Method 3: Ansible Deployment (Coming Soon)

Ansible deployment provides an automated, scalable solution for installing and managing the Musique Agent across multiple Linux devices simultaneously.

Documentation In Progress: The Ansible playbook and detailed deployment instructions are currently being developed. Check back soon for complete instructions.

Overview

This method will be ideal for:

Fleet Management: Deploy to dozens or hundreds of devices at once
Standardized Configuration: Ensure consistent setup across all devices
Bulk Installations: Rapidly deploy Musique to multiple locations
Infrastructure as Code: Version-controlled, reproducible deployments

Planned Features

The Ansible playbook will automate:

System configuration and package updates
Dependency installation (Java, ALSA, PulseAudio)
Agent deployment with encrypted credential management
Service configuration and verification

Prerequisites (When Available)

Ansible installed on your control machine
SSH access to all target Linux devices
Network connectivity to all devices

Temporary Alternative

While the Ansible playbook is being developed, use the Automated Script method for multiple devices:

# Example: Deploy to multiple devices via SSH
for host in 192.168.1.{101..110}; do
  echo "Deploying to $host..."
  ssh pi@$host "curl -fsSL https://musique-portal.s3.us-east-1.amazonaws.com/public/agent/install-linux.sh > install.sh && chmod +x install.sh && sudo ./install.sh"
done

For enterprise deployment assistance or to request priority access to the Ansible playbook, contact support@musique.app.

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.

​Overview

​Choose Your Installation Method

Manual Installation

Automated Script

Ansible Deployment

​Method 1: Manual Installation

​Requirements

Hardware

Software

​Step 1: Update System Packages

​Step 2: Install CA Certificates

​Step 3: Install Java

​Step 4: Install ALSA

​Step 5: Install PulseAudio

​Configuration

​Configure ALSA for PulseAudio

​Create Directories

​Install the Updater

​Download the Updater

​Create the Launcher

​Create the Config File

​Enable Auto-Start on Boot

​Verify Installation

​Troubleshooting

​Managing the Agent

​Service Commands

​Update the Agent

​Method 2: Automated Script Installation

​Prerequisites

Hardware

Software

​Installation Steps

​Post-Installation

​Method 3: Ansible Deployment (Coming Soon)

​Overview

​Planned Features

​Prerequisites (When Available)

​Temporary Alternative

​Best Practices

Network Connection

Power Supply

Audio Output

Regular Updates

Monitor Status

Backup Config

​Next Steps

Create Schedules

Monitor Performance

Test Network

FAQ

Overview

Choose Your Installation Method

Method 1: Manual Installation

Requirements

Step 1: Update System Packages

Step 2: Install CA Certificates

Step 3: Install Java

Step 4: Install ALSA

Step 5: Install PulseAudio

Configuration

Configure ALSA for PulseAudio

Create Directories

Install the Updater

Download the Updater

Create the Launcher

Create the Config File

Enable Auto-Start on Boot

Verify Installation

Troubleshooting

Managing the Agent

Service Commands

Update the Agent

Method 2: Automated Script Installation

Prerequisites

Installation Steps

Post-Installation

Method 3: Ansible Deployment (Coming Soon)

Overview

Planned Features

Prerequisites (When Available)

Temporary Alternative

Best Practices

Next Steps