DockForLife

Version: 0.001 Beta

Professional OBS Remote Controller with Zero Configuration.

Control your OBS Studio from any device—mobile, tablet, or desktop—without complicated network setup. DockForLife uses a Cloudflare Worker relay to enable seamless remote control from anywhere.

Architecture: The Triad

┌─────────────────────────────────────────────────────────────────────────────┐
│                              WEB APPLICATION                                 │
│                         (Next.js + React + Tailwind)                        │
│                  https://your-domain.com or custom                         │
└─────────────────────────────────────┬───────────────────────────────────────┘
                                      │
                              WebSocket (WSS)
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         CLOUDFLARE WORKER (RELAY)                           │
│                      wss://your-worker.your-subdomain.workers.dev            │
│                         (or your custom worker)                              │
│                                                                             │
│    ┌─────────────────────────────────────────────────────────────────┐    │
│    │                    Durable Object: Session                         │    │
│    │  ┌──────────────┐    ┌──────────────┐                           │    │
│    │  │ Host Socket  │◄──►│ Client Socket │                           │    │
│    │  │   (Agent)    │    │   (Web UI)   │                           │    │
│    │  └──────┬───────┘    └──────┬───────┘                           │    │
│    └─────────┼────────────────────┼───────────────────────────────────┘    │
│              │                    │                                          │
│              │  Broadcasts events │                                          │
│              │  to opposite side │                                          │
│              ▼                    ▼                                          │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                              WebSocket (WSS)
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            LOCAL AGENT (Node.js)                           │
│                         obs-websocket-js → OBS Studio                        │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Event Listeners: SceneChanged, MuteState, Record, Stream, etc.    │   │
│  │  └────► normalizeToAlias() ──► full_sync / obs_event ──► Worker   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Command Handlers: ToggleMute, SetScene, ToggleVisibility, etc.    │   │
│  │  └────► findInputByName() ──► findAudioInputByType() ──► OBS      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘

How the Triad Works

Agent connects to OBS locally and subscribes to all OBS events
Agent normalizes OBS data (e.g., "Audio del escritorio" → "Desktop Audio")
Agent sends full_sync and obs_event messages to Worker
Worker broadcasts events to all connected clients
Web UI receives events and updates React state in real-time
Web UI buttons highlight instantly when OBS state changes

Components

Component	Technology	Purpose
Web UI	Next.js + React + Tailwind	Control interface, runs in browser
Worker	Cloudflare Workers + Durable Objects	WebSocket relay, session management
Agent	Node.js + obs-websocket-js	OBS connection, smart aliasing, event forwarding

Features

Live Bidirectional Sync: Changes in OBS reflect immediately on mobile; mobile commands update OBS in real-time
Smart Audio Mapping: Automatically maps "Desktop Audio" ↔ "Audio del escritorio" ↔ "Speakers" and "Mic/Aux" ↔ "Micrófono"
Import/Export JSON: Backup and restore your button configuration as a JSON file
Universal Access: Control OBS from mobile, tablet, or desktop browsers
Zero Configuration: Connect from any device using a simple pairing code
Customizable Controls: Create buttons for scenes, sources, filters, recording, and streaming
Master Controls: Always-visible buttons for Mic, Desktop Audio, Record, and Stream
Visual Feedback: Active states shown with color changes and glow effects
Mobile Optimized: Haptic feedback and touch-friendly interface
Dark/Light Mode: Automatic theme switching
Drag & Drop: Reorder buttons to match your workflow
Multi-language: English and Spanish support

Smart Audio Mapping

DockForLife uses bidirectional alias normalization to handle OBS in any language:

Supported Aliases

Canonical Name	Spanish Variants	English Variants
Desktop Audio	Audio del escritorio, Audio de escritorio	Desktop Audio, Speakers, Output
Mic/Aux	Micrófono/Auxiliar, Mic	Mic/Aux, Microphone, Input

How It Works

Agent → Web (Events):

OBS: "Audio del escritorio" → normalizeToAlias() → "Desktop Audio" → Web UI ✓

Web → Agent (Commands):

Web: "Desktop Audio" → findInputByName() → "Audio del escritorio" → OBS ✓

This means:

OBS can be in Spanish, English, or any language
Your Web UI buttons always use consistent names ("Desktop Audio", "Mic/Aux")
Buttons highlight correctly regardless of OBS language settings

Worker Configuration

Default Worker

The project uses placeholder Worker URLs by default:

wss://your-worker.your-subdomain.workers.dev/ws

Custom Worker Deployment

To deploy your own Worker:

1. Configure Worker URL

In lib/config.ts:

workerUrl: 'wss://your-worker-name.your-subdomain.workers.dev/ws'

In config.example.json:

{
  "WORKER_URL": "wss://your-worker-name.your-subdomain.workers.dev/ws"
}

2. Deploy with Wrangler

cd worker

# Install dependencies
npm install

# Configure wrangler.toml with your Cloudflare account
# Edit name = "your-worker-name"

# Deploy to production
npx wrangler deploy

# Or deploy to preview
npx wrangler deploy --env preview

3. Update Agent Configuration

Create agent/config.json:

{
  "WORKER_URL": "wss://your-worker-name.your-subdomain.workers.dev/ws",
  "OBS_PORT": 4455,
  "OBS_PASSWORD": "your-obs-password"
}

Setup Guide

1. Web Application (Next.js)

# Clone and install
git clone https://github.com/daurydicaprio/dockforlife.git
cd dockforlife
npm install

# Development with hot reload
npm run dev

# Build for production
npm run build

# Deploy to Vercel (auto-detected)
vercel deploy

# Or deploy static build to any hosting
npx next export -o dist/

2. Cloudflare Worker

cd worker

# Install Wrangler CLI globally if needed
npm install -g wrangler

# Login to Cloudflare
npx wrangler login

# Deploy
npx wrangler deploy

# Check status
npx wrangler deployments

3. Local Agent (Development)

cd agent

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode (with ts-node)
npm run dev

# Or run compiled JavaScript
npm start

Arch Linux / Omarchy Setup

# Install Node.js from official repositories
sudo pacman -S nodejs npm

# Or use nvm for version management
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Proceed with npm install && npm run dev as above

Usage Modes

Local Mode (Desktop)

Connect directly to OBS on the same computer using WebSocket (port 4455). Best for:

Desktop/laptop control
Testing and development
Direct low-latency connection

Remote Mode (Mobile)

Connect through the Cloudflare Worker relay using a pairing code. Best for:

Mobile/tablet control from anywhere
Remote streaming management
Multi-device setups

Creating Custom Buttons

Click the + button to add a new control
Choose an action type:
- Mute: Toggle audio input mute state
- Visibility: Toggle source visibility in current scene
- Filter: Toggle filter on/off
- Scene: Switch to a specific scene
- Record: Start/stop recording
- Stream: Start/stop streaming
Configure the target (scene name, source name, etc.)
Customize colors for idle and active states
Save and rearrange by dragging

Double-tap any button to edit its configuration.

Import / Export Configuration

Export Configuration

Open Settings Modal
Click Export
JSON file downloads automatically with timestamp
File contains all custom buttons (excludes master controls)

Import Configuration

Open Settings Modal
Click Import
Select a valid .json config file
Buttons are merged with master controls

JSON Format

{
  "version": "1.0",
  "deck": [
    {
      "id": "abc123",
      "label": "GAME MIC",
      "type": "Mute",
      "target": "Mic/Aux",
      "color": "#18181b",
      "colorActive": "#3b82f6"
    }
  ]
}

Security

Pairing Codes: Unique 4-12 character codes for each session
No Data Collection: All data stays local, no analytics or tracking
WSS Encryption: All remote connections use secure WebSockets
Local Storage: Settings stored in browser localStorage only

Architecture Details

Web Application

Framework: Next.js 14 with TypeScript
Styling: Tailwind CSS with custom components
State: React hooks with localStorage persistence
Icons: Lucide React
Real-time: WebSocket message handlers for live updates

Cloudflare Worker

Runtime: Cloudflare Workers (edge computing)
Protocol: WebSocket relay for real-time communication
Durable Objects: Session management for pairing codes
CORS: Configured for cross-origin requests

Local Agent

Runtime: Node.js 18+
OBS Connection: obs-websocket-js library
Protocol: WebSocket client to Cloudflare Worker
Smart Features: normalizeToAlias(), findInputByName()
Event Broadcasting: Real-time OBS event relay

Troubleshooting

Connection Failed:

Verify OBS WebSocket is enabled in Tools → WebSocket Server Settings
Check the port (default: 4455) and password match your config
Ensure firewall allows the connection

Agent Not Running:

Check that the agent is still running in the terminal
Verify the Worker URL is accessible
Try regenerating the pairing code

Buttons Not Responding:

Ensure OBS is running and WebSocket server is active
Check browser console for error messages
Refresh the page to reconnect

Mobile Not Syncing:

Check browser console for obs_event or full_sync logs
Verify Agent is sending events (check agent terminal)
Confirm Worker is broadcasting (check Worker logs)

License

This project is licensed under the Sustainable Use License - see LICENSE for details.

Summary

✅ Free for personal use
✅ Free for educational purposes
✅ Free for open-source projects
✅ Free for internal business operations
❌ Cannot be used as a SaaS product
❌ Cannot be used as a hosted/managed service
❌ Cannot be sold or commercially redistributed

For commercial licensing inquiries, contact: hello@daurydicaprio.com

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

Support

Made with ❤️ by Daury DiCaprio

#dockforlife

Name		Name	Last commit message	Last commit date
Latest commit History 109 Commits
.github/workflows		.github/workflows
agent		agent
app		app
components		components
lib		lib
public		public
styles		styles
worker		worker
.gitignore		.gitignore
LICENSE		LICENSE
MANUAL.md		MANUAL.md
README.md		README.md
components.json		components.json
config.example.json		config.example.json
dockforlife.config.json.example		dockforlife.config.json.example
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

DockForLife

Architecture: The Triad

How the Triad Works

Components

Features

Smart Audio Mapping

Supported Aliases

How It Works

Worker Configuration

Default Worker

Custom Worker Deployment

1. Configure Worker URL

2. Deploy with Wrangler

3. Update Agent Configuration

Setup Guide

1. Web Application (Next.js)

2. Cloudflare Worker

3. Local Agent (Development)

Arch Linux / Omarchy Setup

Usage Modes

Local Mode (Desktop)

Remote Mode (Mobile)

Creating Custom Buttons

Import / Export Configuration

Export Configuration

Import Configuration

JSON Format

Security

Architecture Details

Web Application

Cloudflare Worker

Local Agent

Troubleshooting

License

Summary

Contributing

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Contributors

Uh oh!

Languages