Running as a Service

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

Overview

Running BPTimecode 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

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/bptimecode.service:

[Unit]
Description=BPTimecode Server
After=network.target

[Service]
Type=simple
User=bptimecode
Group=bptimecode
WorkingDirectory=/opt/bptimecode
ExecStart=/opt/bptimecode/bptimecode serve --port 5050
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
sudo useradd -r -s /bin/false bptimecode

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

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 bptimecode

# Start the service now
sudo systemctl start bptimecode

# Check status
sudo systemctl status bptimecode

4. View Logs

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

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

5. Managing the Service

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

🍎 macOS (launchd)

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

1. Create the Launch Agent

Create ~/Library/LaunchAgents/com.bpshowtools.bptimecode.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.bptimecode</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/bptimecode</string>
        <string>serve</string>
        <string>--port</string>
        <string>5050</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/bptimecode.log</string>
    
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/bptimecode.error.log</string>
</dict>
</plist>

💡 User vs System Service:

~/Library/LaunchAgents/ — Runs when you log in (user agent)
/Library/LaunchDaemons/ — Runs at boot, even without login (system daemon, requires sudo)

2. Load the Service

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

# Verify it's running
launchctl list | grep bptimecode

3. Managing the Service

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

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

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

🪟 Windows

Windows offers two approaches: Task Scheduler (simpler) or Windows Service (more robust).

Option A: Task Scheduler (Recommended for Most Users)

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: BPTimecode
- Check "Run whether user is logged on or not"
- Check "Run with highest privileges"
Triggers tab:
- Click New → "At startup"
Actions tab:
- Click New → Action: "Start a program"
- Program: C:\Program Files\BPTimecode\bptimecode.exe
- Arguments: serve --port 5050
- Start in: C:\Program Files\BPTimecode
Settings tab:
- Uncheck "Stop the task if it runs longer than"
- Check "If the task fails, restart every" → 1 minute
Click OK and enter your password when prompted

Option B: Windows Service (Using sc.exe)

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

1. Install the Service

Open PowerShell as Administrator:

# Create the service
sc.exe create "BPTimecode" binpath= "C:\Program Files\BPTimecode\bptimecode.exe serve --port 5050" start= auto DisplayName= "BPTimecode Server"

# Set description (optional)
sc.exe description "BPTimecode" "BPTimecode timecode server for broadcast and live production"

# Configure recovery options (restart on failure)
sc.exe failure "BPTimecode" 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 BPTimecode    # Start
sc.exe stop BPTimecode     # Stop
sc.exe query BPTimecode    # Check status
sc.exe delete BPTimecode   # 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.

1. Download WinSW

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

2. Create Configuration File

Create bptimecode-service.xml in the same folder:

<service>
  <id>BPTimecode</id>
  <name>BPTimecode Server</name>
  <description>BPTimecode timecode server for broadcast and live production</description>
  <executable>bptimecode.exe</executable>
  <arguments>serve --port 5050</arguments>
  <log mode="roll"/>
</service>

3. Install and Start

# Install the service
bptimecode-service.exe install

# Start the service
bptimecode-service.exe start

# Check status
bptimecode-service.exe status

🔧 Troubleshooting

Port Already in Use

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

bptimecode serve --port 5060

Permission Denied (Linux/macOS)

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

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

Audio Devices Not Available (LTC)

When running as a system service, audio devices may not be accessible. Options:

Run as a user agent/task instead of system daemon
Use network protocols (Art-Net, sACN) instead of LTC audio
Configure the service to run as your user account