Running as a Service

Configure BPSoundscape to start automatically and run in the background on your production systems.

Overview

Running BPSoundscape as a service ensures it:

Starts automatically when the system boots
Restarts automatically if it crashes
Runs in the background without requiring a logged-in user
Can be managed via standard system tools

⚠️ Audio Output Considerations:

BPSoundscape plays audio, which may require a logged-in user session on some systems. See the Troubleshooting section for platform-specific guidance.

Choose the section below for your operating system.

🐧 Linux (systemd)

Most modern Linux distributions use systemd for service management.

1. Create the Service File

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

[Unit]
Description=BPSoundscape Server
After=network.target sound.target

[Service]
Type=simple
User=bpsoundscape
Group=bpsoundscape
WorkingDirectory=/opt/bpsoundscape
ExecStart=/opt/bpsoundscape/bpsoundscape serve --port 8513 --library /opt/bpsoundscape/library
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Optional: Set environment variables
# Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

2. Create a Service User (Recommended)

# Create a dedicated user for the service (add to audio group for sound access)
sudo useradd -r -s /bin/false -G audio bpsoundscape

# Set ownership of the installation directory
sudo chown -R bpsoundscape:bpsoundscape /opt/bpsoundscape

3. Enable and Start the Service

# Reload systemd to pick up the new service
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable bpsoundscape

# Start the service now
sudo systemctl start bpsoundscape

# Check status
sudo systemctl status bpsoundscape

4. View Logs

# View recent logs
sudo journalctl -u bpsoundscape -n 50

# Follow logs in real-time
sudo journalctl -u bpsoundscape -f

5. Managing the Service

sudo systemctl start bpsoundscape    # Start
sudo systemctl stop bpsoundscape     # Stop
sudo systemctl restart bpsoundscape  # Restart
sudo systemctl status bpsoundscape   # Check status

🍎 macOS (launchd)

macOS uses launchd for managing services (called "launch agents" or "launch daemons").

💡 For Audio Playback: Use a Launch Agent (runs when you log in) rather than a Launch Daemon. This ensures audio output works correctly.

1. Create the Launch Agent

Create ~/Library/LaunchAgents/com.bpshowtools.bpsoundscape.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>com.bpshowtools.bpsoundscape</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/bpsoundscape</string>
        <string>serve</string>
        <string>--port</string>
        <string>8513</string>
        <string>--library</string>
        <string>/Users/Shared/BPSoundscape/library</string>
    </array>
    
    <key>RunAtLoad</key>
    <true/>
    
    <key>KeepAlive</key>
    <true/>
    
    <key>WorkingDirectory</key>
    <string>/usr/local/bin</string>
    
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/bpsoundscape.log</string>
    
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/bpsoundscape.error.log</string>
</dict>
</plist>

2. Load the Service

# Load and start the service
launchctl load ~/Library/LaunchAgents/com.bpshowtools.bpsoundscape.plist

# Verify it's running
launchctl list | grep bpsoundscape

3. Managing the Service

# Stop the service
launchctl unload ~/Library/LaunchAgents/com.bpshowtools.bpsoundscape.plist

# Start the service
launchctl load ~/Library/LaunchAgents/com.bpshowtools.bpsoundscape.plist

# View logs
tail -f /usr/local/var/log/bpsoundscape.log

🪟 Windows

Windows offers two approaches: Task Scheduler (simpler, better for audio) or Windows Service (more robust).

💡 For Audio Playback: Task Scheduler is recommended because it runs in your user session, ensuring audio output works correctly.

Option A: Task Scheduler (Recommended)

1. Open Task Scheduler

Press Win + R, type taskschd.msc, and press Enter.

2. Create a New Task

Click Create Task (not "Create Basic Task")
General tab:
- Name: BPSoundscape
- Check "Run only when user is logged on" (required for audio)
Triggers tab:
- Click New → "At log on" → Specific user (your account)
Actions tab:
- Click New → Action: "Start a program"
- Program: C:\Program Files\BPSoundscape\bpsoundscape.exe
- Arguments: serve --port 8513 --library "C:\BPSoundscape\library"
- Start in: C:\Program Files\BPSoundscape
Settings tab:
- Uncheck "Stop the task if it runs longer than"
- Check "If the task fails, restart every" → 1 minute
Click OK

Option B: Windows Service (Using sc.exe)

Windows includes sc.exe (Service Control) for creating native Windows Services. This requires no third-party tools.

⚠️ Audio Limitation: Windows Services run in Session 0 and cannot access audio devices directly. Use Task Scheduler if you need audio output.

1. Install the Service

Open PowerShell as Administrator:

# Create the service
sc.exe create "BPSoundscape" binpath= "C:\Program Files\BPSoundscape\bpsoundscape.exe serve --port 8513 --library C:\BPSoundscape\library" start= auto DisplayName= "BPSoundscape Server"

# Set description (optional)
sc.exe description "BPSoundscape" "BPSoundscape audio playback server"

# Configure recovery options (restart on failure)
sc.exe failure "BPSoundscape" reset= 86400 actions= restart/60000/restart/60000/restart/60000

💡 Note: The spaces after = in sc.exe commands are required (e.g., binpath= "..." not binpath="...").

2. Managing the Service

sc.exe start BPSoundscape    # Start
sc.exe stop BPSoundscape     # Stop
sc.exe query BPSoundscape    # Check status
sc.exe delete BPSoundscape   # Remove service

You can also manage it via services.msc (Windows Services GUI).

Option C: Windows Service (Using WinSW)

WinSW is an actively maintained service wrapper with XML configuration and built-in logging.

⚠️ Audio Limitation: Windows Services run in Session 0 and cannot access audio devices directly. Use Task Scheduler if you need audio output.

1. Download WinSW

Download WinSW-x64.exe from GitHub Releases and place it in your BPSoundscape folder as bpsoundscape-service.exe.

2. Create Configuration File

Create bpsoundscape-service.xml in the same folder:

<service>
  <id>BPSoundscape</id>
  <name>BPSoundscape Server</name>
  <description>BPSoundscape audio playback server</description>
  <executable>bpsoundscape.exe</executable>
  <arguments>serve --port 8513 --library C:\BPSoundscape\library</arguments>
  <log mode="roll"/>
</service>

3. Install and Start

# Install the service
bpsoundscape-service.exe install

# Start the service
bpsoundscape-service.exe start

# Check status
bpsoundscape-service.exe status

🔧 Troubleshooting

No Audio Output

Audio playback requires access to audio devices, which may not be available to system services:

Linux: Ensure the service user is in the audio group. For PulseAudio, you may need to run as a user service.
macOS: Use a Launch Agent (not Daemon) so it runs in your user session.
Windows: Use Task Scheduler with "Run only when user is logged on" instead of a Windows Service.

Port Already in Use

If port 8513 is already in use, specify a different port:

bpsoundscape serve --port 8520

Library Not Found

Ensure the library path exists and is accessible to the service user:

# Linux/macOS
sudo mkdir -p /opt/bpsoundscape/library
sudo chown -R bpsoundscape:bpsoundscape /opt/bpsoundscape/library

# Windows (PowerShell as Admin)
New-Item -ItemType Directory -Path "C:\BPSoundscape\library" -Force

Service Won't Start

Check the logs for error messages
Verify the executable path is correct
Ensure the service user has read/execute permissions
Try running the command manually first to test

Permission Denied (Linux/macOS)

Ports below 1024 require root privileges. Use a higher port number, or set up a reverse proxy.