Soluna — Setup Guide

How It Works

Simply set your Mac's system output to Soluna (virtual device) ↓ Soluna.driver ← CoreAudio HAL plugin ↓ Shared memory Soluna.app —————————————————————┐ │ │ ├—— Audio TX → Stream system audio over network │ ├—— Mic TX → Stream microphone audio │ ├—— RX → Receive from other Mac / iPhone │ ├—— WAN P2P → Share groups over the internet │ └—— CoreAudio → Simultaneous Mac speaker playback │ │ Web UI http://localhost:8400 ←———————┘ * The .pkg installer sets up all components at once

Supported Platforms

💻

Mac

Soluna.app handles TX + RX + WAN P2P in one app. System audio, mic streaming, multi-speaker sync.

TX + RX + WAN

📱

iPhone

Receive with the Soluna Receiver app. Auto-discovery via Bonjour, individual volume and delay controls.

RX Receive

🥬

Raspberry Pi

Just run soluna-rx. High-quality playback with any ALSA-compatible DAC.

RX Receive

🌐

Browser

Listen instantly from the "Browser" tab in the dashboard. No installation required.

RX Receive

Mac Setup

The .pkg installer sets up Soluna.app + virtual audio device + background service all at once.

Download Soluna-mac.pkg

macOS 13 Ventura or later • Apple Silicon + Intel supported

1

Download & Install

Download Soluna-mac.pkg using the button above, then double-click to launch the installer.

2

Set Soluna as Sound Output

Go to System Settings → Sound → Output and select "Soluna".

⚠ If "Soluna" doesn't appear, allow the driver in System Settings → Privacy & Security, then run sudo killall coreaudiod.

3

Start Streaming with Soluna.app

Open /Applications/Soluna.app and turn on Audio TX → streaming starts!

The solunad background service is auto-configured by the installer. Check status with solctl status.

For developers: To build from source, see the GitHub README.

iPhone Setup

1

Install the App

Open apps/ios/SolunaReceiver.xcodeproj in Xcode and build, or distribute via TestFlight.

2

Auto-Connect (Bonjour)

If connected to the same Wi-Fi as your Mac, it auto-discovers on launch.
When the Mac appears in the "Speakers" list, you're good to go.

3

Manual Connection

Tap the "+" button and enter your Mac's IP address (e.g., 192.168.1.10).

Find your Mac's IP at System Settings → Wi-Fi → Details → TCP/IP.

4

Automatic Delay Sync

Latency is automatically measured right after connection, syncing Mac speaker and iPhone audio precisely.
If you notice drift, use the "Global Delay" slider for manual adjustment.

Raspberry Pi Setup

1

One-Command Install

Run on your RPi / Linux machine. Handles everything from build to service registration.

curl -fsSL https://solun.art/install-rx.sh | sudo bash

Automatically installs dependencies, builds, and registers the systemd service.

2

Manual Build (Linux)

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -- soluna-rx
sudo cp build/soluna-rx /usr/local/bin/

3

Launch & Verify

# ALSA default output
soluna-rx --output alsa

# Pipe output to aplay
soluna-rx --output pipe | aplay -f S16_LE -r 48000 -c 2

# Check service status
systemctl status soluna-rx

Listen in Your Browser

1

Dashboard → "Browser" Tab

Select Browser from the bottom navigation in the Dashboard.

Press the ▶ button to start listening instantly. No installation required.

2

Connect from Another Device

Open from any browser on the same network using your Mac's IP address.

http://<Mac's IP address>:8400

⚠ iOS Safari may stop audio in background tabs. Keep the tab visible.

Troubleshooting

"Soluna" doesn't appear in Sound settings

Re-running the .pkg installer and restarting CoreAudio usually fixes this.

# After clicking "Allow" in System Settings → Privacy & Security
sudo killall coreaudiod

No sound (even with Soluna.app running)

Make sure Audio TX is turned ON in Soluna.app. If shared memory doesn't exist, the driver will retry connection every 2-3 seconds.

# Check shared memory
ls -la /private/var/db/soluna/

# Re-download and install the .pkg

Doesn't auto-start after Mac reboot

Check the launchd registration status.

launchctl print gui/$UID/io.soluna.daemon

# If LaunchAgent is missing, reinstall the .pkg

Audio stuttering on iPhone

Increasing the buffer size can help. Go to Settings → Buffer Size in the iPhone app and increase to 60-120ms.
Alternatively, try setting the "Global Delay" slider to 60ms or more.

Dropouts on Raspberry Pi

Granting real-time scheduling permissions significantly improves performance.

sudo setcap cap_sys_nice=ep /usr/local/bin/soluna-rx
echo 'kernel.sched_rt_runtime_us=-1' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Browser audio is delayed or choppy

The browser version uses AudioWorklet for low-latency design, but may stutter under heavy CPU load. If the Buffer value (ms) in Controls is stable, everything is working normally. "Underruns: 0" means no issues.

Mac and iPhone audio are out of sync

The iPhone app automatically measures RTT on connection to align delay. If there's significant drift, adjust manually with the "Global Delay" slider. Typical values: 30-60ms on same Wi-Fi, 80-150ms across routers.

launchd Command Cheatsheet

launchctl print gui/$UID/io.soluna.daemon   # Check status
launchctl stop  gui/$UID/io.soluna.daemon   # Stop
launchctl start gui/$UID/io.soluna.daemon   # Start
launchctl bootout gui/$UID/io.soluna.daemon # Uninstall

tail -f /tmp/solunad.log                    # View logs

WebSocket Command Reference

Connect to ws://localhost:8400/ws and send JSON commands.

# Set monitor volume to 80%
{"id":1,"command":"monitor.set_volume","volume":0.8}

# Set buffer to 40ms
{"id":2,"command":"monitor.set_buffer","ms":40}

# Set delay to 50ms
{"id":3,"command":"monitor.set_delay","ms":50}

# Get receiver statistics
{"id":4,"command":"rx.stats"}

# Start browser audio
{"id":5,"command":"audio.subscribe"}

# Ping / RTT measurement
{"id":6,"command":"time.ping"}