Direct Installation

SnapDog is distributed as lightweight native binaries. The current release workflow publishes Linux (x86_64, aarch64), macOS (x86_64, aarch64), and Windows (x86_64, aarch64) artifacts.

---

Operating System Requirements

Ensure your target machine meets the following requirements:

• Linux: Kernel 5.4 or higher. ALSA (Advanced Linux Sound Architecture) is required for local audio output interfaces.
• macOS: macOS 12 (Monterey) or higher.
• Windows: Windows 10/11 or Windows Server 2019+ (supported when running as a background service).

---

Package Managers

Arch Linux (AUR)

AUR helper tools can be used to install the latest pre-compiled binary or build SnapDog directly from the Arch User Repository.

# Install the server and audio client
yay -S snapdog snapdog-client

# Enable and start the systemd service
sudo systemctl enable --now snapdog

macOS (Homebrew)

For Apple Silicon or Intel Macs, we maintain a custom Homebrew tap:

# Tap the repository
brew tap snapdogrocks/tap

# Install the server and audio client
brew install snapdog snapdog-client

# Run SnapDog as a macOS background service
brew services start snapdog

Debian/Ubuntu (APT)

We distribute native .deb packages for Debian and Ubuntu architectures (amd64, arm64).

1. Register the trusted APT repository source:

   echo "deb [trusted=yes] https://snapdogrocks.github.io/snapdog/debian stable main" \
     | sudo tee /etc/apt/sources.list.d/snapdog.list

2. Update package lists and install:

   sudo apt update
   sudo apt install snapdog snapdog-client

3. Start the background service:

   sudo systemctl daemon-reload
   sudo systemctl enable --now snapdog

Windows Service

SnapDog compiles to a native Windows binary (x86_64 and arm64) and can run as an NT Service.

1. Download the Windows binary (snapdog.exe) for your architecture and place it in C:\Program Files\SnapDog\.
2. Open a Command Prompt as Administrator and register the service:

   sc create SnapDog binPath= "\"C:\Program Files\SnapDog\snapdog.exe\" --service --config \"C:\ProgramData\snapdog\snapdog.toml\"" start= auto
   sc start SnapDog

---

Direct Binary Download

If you prefer to install the pre-compiled binaries manually:

1. Download the correct archive for your architecture from the GitHub Releases page.
2. Extract the archive and copy the binary to /usr/local/bin:

   tar -xzf snapdog-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
   sudo mv snapdog /usr/local/bin/
   sudo chmod 755 /usr/local/bin/snapdog

---

Compiling from Source

If you want to compile SnapDog with custom target optimizations, you can build it from source using Cargo.

Note

Building from source allows choosing specific Snapcast server backends. See the compilation feature flags described in the Server Mode Selection section below.

Build Dependencies

Ensure your development machine has the required system libraries installed:

• Debian/Ubuntu: sudo apt install build-essential pkg-config clang libasound2-dev libavahi-compat-libdnssd-dev
• macOS: Xcode Command Line Tools are sufficient.

Building

1. Clone the repository:

   git clone https://github.com/SnapDogRocks/snapdog.git
   cd snapdog

2. Build the release binary:

   cargo build --release -p snapdog

3. The compiled binary will be available at target/release/snapdog.

---

Post-Installation Service Scripts

To ensure SnapDog starts automatically on boot and restarts in case of failures, configure a service supervisor.

Linux Systemd Service Unit

Create /etc/systemd/system/snapdog.service:

[Unit]
Description=SnapDog Multi-room Audio Controller
After=network-online.target sound.target
Wants=network-online.target

[Service]
Type=simple
User=snapdog
Group=audio
ExecStart=/usr/local/bin/snapdog --config /etc/snapdog/snapdog.toml
Restart=always
RestartSec=5
LimitRTPRIO=99
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target

macOS Launchd Service Agent

Create ~/Library/LaunchAgents/cc.snapdog.server.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>cc.snapdog.server</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/snapdog</string>
        <string>--config</string>
        <string>/Users/Shared/snapdog.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

---

Server Mode Selection

SnapDog supports two primary Snapcast compilation backends. You can select the backend using Cargo feature flags:

• snapcast-embedded (Default & Recommended): Integrates the Snapcast server directly into the Rust daemon binary (leveraging our native Rust port of the original C++ Snapcast codebase via the snapcast-* crates). This mode is strongly recommended because it manages group synchronization inline, supports proprietary float PCM channels for parametric EQ corrections, and doesn’t require maintaining an external binary.
• snapcast-process: Spawns and manages a standalone C++ snapserver process in the background. Choose this only if you must rely on advanced C++ features or legacy external pipe encoders.

---

Next Steps

Configuration GuideCustomize zone topologies, client speaker volumes, and home automation triggers.

Docker ContainerDeploy SnapDog in a containerized environment.