Automation Settings - TCP Streamer

Overview

Automation settings allow TCP Streamer to run unattended, making it ideal for headless setups, background audio distribution, and always-on streaming scenarios.

Auto-Start on Boot

Launch TCP Streamer automatically when your system starts.

auto_start

boolean

default:"false"

Enable automatic launch on system startup

How It Works

TCP Streamer integrates with your operating system’s autostart mechanism:

Windows: Adds registry entry to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run
macOS: Creates launch agent in ~/Library/LaunchAgents
Linux: Adds .desktop file to ~/.config/autostart/

Behavior

When auto-start is enabled:

Application launches on system boot
Window opens minimized to system tray
No user interaction required
Waits for user to start streaming OR auto-stream triggers

Enable Auto-Start

Check the “Auto-start on launch” checkbox in Settings tab

Restart System

Restart your computer to test (optional)

Verify

Check system tray for TCP Streamer icon after boot

Use Cases

Home audio server: Always available for streaming
Headless systems: No manual launch required
Multi-room audio: Ensures continuous availability
Background monitoring: Audio capture without user interaction

On some systems, auto-start may require administrator/root privileges during initial setup.

Auto-Stream

Begin streaming immediately after application starts.

auto_stream

boolean

default:"false"

Automatically start streaming on application launch

How It Works

When auto-stream is enabled:

Application loads saved configuration from current profile
Waits 500ms for device initialization
Automatically clicks “Start Streaming” button
Begins streaming to configured IP:Port

Requirements

For auto-stream to work, you must have:

✅ Valid input device selected
✅ IP address configured
✅ Port number configured
✅ TCP server running and accessible

If any required setting is missing, auto-stream will fail silently and the application will remain in “Ready” state.

Behavior

if (autostreamCheck.checked && deviceSelect.value && ipInput.value) {
  setTimeout(() => {
    toggleStream();
  }, 500);
}

Combined with Auto-Start

For fully automated operation, enable both:

{
  "auto_start": true,
  "auto_stream": true
}

Result: System boots → TCP Streamer launches → Streaming begins automatically

Test your configuration manually before enabling auto-stream to ensure all settings are correct.

Auto-Reconnect

Automatically retry connection when network errors occur.

auto_reconnect

boolean

default:"false"

Enable automatic reconnection on connection failure

How It Works

When auto-reconnect is enabled:

Detects connection failures (write errors, timeouts, socket closure)
Closes TCP connection gracefully (sends FIN packet)
Waits with exponential backoff
Attempts to reconnect to the same IP:Port
Resumes streaming if successful

Reconnection Strategy

Exponential Backoff with Jitter:

Initial delay: 2 seconds (minimum)
Max delay: 60 seconds
Jitter: ±500ms (prevents thundering herd)

Retry 1: 2s ± 500ms
Retry 2: 4s ± 500ms
Retry 3: 8s ± 500ms
Retry 4: 16s ± 500ms
Retry 5: 32s ± 500ms
Retry 6+: 60s ± 500ms

Behavior During Reconnection

Audio buffer:

Continues capturing audio during reconnection
Drains stale audio (100ms chunks) to prevent sending old data
Sends fresh audio once reconnected

User interface:

Status shows: “Reconnecting to [IP] (retry in Xs)…”
“Stop Streaming” button remains active
Statistics continue updating

Network thread:

Remains running (does not exit)
Uses strict pacing during disconnect to prevent CPU spin
Clears buffer gradually to avoid blocking

Graceful Shutdown

When connection fails, TCP Streamer:

// Send TCP FIN to server
stream.shutdown(Shutdown::Both);

// Wait 100ms for kernel to process FIN
thread::sleep(Duration::from_millis(100));

// Attempt reconnection

This prevents zombie connections where the server thinks the client is still connected.

Use Cases

Network Interruptions

WiFi signal drops temporarily
Router restarts
Ethernet cable briefly unplugged

Server Restarts

Snapcast server updates
Server maintenance windows
Temporary server crashes

Development

Testing connection resilience
Server debugging sessions
Integration testing

Auto-reconnect will retry indefinitely until you manually stop streaming or close the application.

Deep Sleep Mode

Automatic disconnection during prolonged silence to prevent zombie connections.

deep_sleep

boolean

default:"true"

Automatically disconnect after prolonged silence (always enabled)

How It Works

Introduced in v1.6.0, Deep Sleep prevents “zombie” connections:

Monitors audio RMS (Root Mean Square) levels
Detects prolonged silence (no audio above threshold)
Automatically disconnects after timeout period
Reconnects when audio resumes (if auto-reconnect enabled)

Behavior

Silence detection:

Threshold: RMS < 50.0
Timeout: Configurable (default: 60 seconds)

On timeout:

Gracefully closes TCP connection
Logs: “Deep sleep activated (no audio)”
Stops sending data

On audio resume:

Automatically reconnects if auto-reconnect enabled
Logs: “Audio detected, reconnecting…”
Resumes streaming

Deep Sleep is always active and cannot be disabled. It’s a core reliability feature introduced in v1.6.0.

Configuration Profiles

Save different automation configurations for various scenarios.

Creating Automation Profiles

Create Profile

Click ➕ New, enter profile name (e.g., “Auto-Streaming”), click ✓ Create

Configure Settings

Set IP address and port
Select input device
Enable auto-stream and auto-reconnect

Save Profile

Click 💾 Save to store configuration

Example Profiles

Always-On Home Server

{
  "name": "Home-Server",
  "ip": "192.168.1.100",
  "port": 4953,
  "device": "[Loopback] Speakers",
  "auto_start": true,
  "auto_stream": true,
  "auto_reconnect": true,
  "ring_buffer_duration": 8000
}

Use case: Unattended home audio server that streams system audio 24/7

Development Testing

{
  "name": "Testing",
  "ip": "localhost",
  "port": 9999,
  "device": "Microphone",
  "auto_start": false,
  "auto_stream": false,
  "auto_reconnect": true,
  "ring_buffer_duration": 2000
}

Use case: Manual testing with automatic reconnection for debugging

Studio Monitor

{
  "name": "Studio",
  "ip": "10.0.0.50",
  "port": 8000,
  "device": "Audio Interface",
  "auto_start": true,
  "auto_stream": false,
  "auto_reconnect": true,
  "ring_buffer_duration": 4000
}

Use case: Studio monitoring system, launches on boot but waits for manual streaming start

System Tray Integration

TCP Streamer always runs in the system tray, never fully quits.

Behavior

Window closing:

Clicking ❌ minimizes to tray (does not quit)
Application continues running in background
Streaming continues uninterrupted

Tray menu:

Right-click tray icon for options
“Show” - Restore window
“Quit” - Fully exit application

Streaming state:

Tray icon changes color when streaming
Hover tooltip shows connection status

To fully quit TCP Streamer, you must use the “Quit” option in the system tray menu. Closing the window only minimizes it.

Unattended Operation

Complete setup guide for headless/unattended streaming.

Setup Checklist

Configure Connection

Set IP address and port for your TCP server (e.g., Snapcast)

Select Device

Choose audio input device (or enable loopback on Windows)

Optimize Settings

Sample Rate: 48000 Hz
Buffer Size: 1024
Ring Buffer: 4000-8000ms (WiFi) or 2000ms (wired)

Enable Automation

✅ Auto-start on launch
✅ Auto-stream
✅ Auto-reconnect

Test Configuration

Manually test streaming to verify all settings work correctly

Save Profile

Save configuration to a named profile (e.g., “Production”)

Reboot Test

Restart system and verify automatic streaming begins

Monitoring Unattended Systems

Check logs remotely to verify operation:

[14:32:01] INFO: Starting stream to 192.168.1.100:4953
[14:32:01] SUCCESS: Stream started successfully
[14:32:02] SUCCESS: Connected successfully!
[14:32:02] SUCCESS: Buffer prefilled! Starting transmission.

For production deployments, consider setting up remote monitoring or logging to track uptime and connection health.

Troubleshooting

Auto-Start Not Working

Solutions:

Verify auto-start is enabled in settings
Check system startup applications list
Windows: Check registry entry exists
macOS: Check Launch Agent is loaded (launchctl list)
Linux: Check ~/.config/autostart/ for .desktop file
Grant necessary permissions (may require admin/root)

Auto-Stream Fails Silently

Solutions:

Verify device is selected
Verify IP and port are configured
Check TCP server is running before launching app
Look for errors in logs after 500ms delay
Test manual streaming first

Auto-Reconnect Not Retrying

Solutions:

Verify auto-reconnect is enabled
Check logs for reconnection attempts
Ensure network is accessible
Verify firewall allows outbound connections
Check if “Stop Streaming” was clicked (disables auto-reconnect)

Connection Storms (Too Many Retries)

Symptoms: Excessive connection attempts overwhelming server Explanation: Exponential backoff with jitter prevents this. If you’re seeing connection storms:

Verify you’re running v1.9.0 or later (minimum 2s delay)
Check that multiple instances aren’t running
Verify jitter is working (retry delays should vary by ±500ms)

Audio Settings - Configure input devices
Network Settings - Optimize connection reliability
Advanced Settings - Enable adaptive buffer for unattended operation

Getting Started

Core Features

Configuration

Platform Guides

Use Cases

Troubleshooting

​Overview

​Auto-Start on Boot

​How It Works

​Behavior

​Use Cases

​Auto-Stream

​How It Works

​Requirements

​Behavior

​Combined with Auto-Start

​Auto-Reconnect

​How It Works

​Reconnection Strategy

​Behavior During Reconnection

​Graceful Shutdown

​Use Cases

​Network Interruptions

​Server Restarts

​Development

​Deep Sleep Mode

​How It Works

​Behavior

​Configuration Profiles

​Creating Automation Profiles

​Example Profiles

​Always-On Home Server

​Development Testing

​Studio Monitor

​System Tray Integration

​Behavior

​Unattended Operation

​Setup Checklist

​Monitoring Unattended Systems

​Troubleshooting

​Auto-Start Not Working

​Auto-Stream Fails Silently

​Auto-Reconnect Not Retrying

​Connection Storms (Too Many Retries)

​Related Settings

Build docs developers (and LLMs) love

Overview

Auto-Start on Boot

How It Works

Behavior

Use Cases

Auto-Stream

How It Works

Requirements

Behavior

Combined with Auto-Start

Auto-Reconnect

How It Works

Reconnection Strategy

Behavior During Reconnection

Graceful Shutdown

Use Cases

Network Interruptions

Server Restarts

Development

Deep Sleep Mode

How It Works

Behavior

Configuration Profiles

Creating Automation Profiles

Example Profiles

Always-On Home Server

Development Testing

Studio Monitor

System Tray Integration

Behavior

Unattended Operation

Setup Checklist

Monitoring Unattended Systems

Troubleshooting

Auto-Start Not Working

Auto-Stream Fails Silently

Auto-Reconnect Not Retrying

Connection Storms (Too Many Retries)

Related Settings