DeckPilot

A professional shot/take name management application for Blackmagic HyperDeck recorders with OSC integration for Bitfocus Companion and cmnd integration for distributed system management.

Features

Core Functionality

Multi-Recorder Management - Add and manage multiple HyperDeck recorders simultaneously
Flexible Take Naming - Three template modes:
- Show Template: Simple show name format
- Take Template: Structured format with shot and take numbers (e.g., ShowName_S01_T01)
- Custom Template: Freeform text input
Shot/Take Counters - Independent shot and take numbering per recorder with auto-increment
Date Format Options - 9 different date format options for take names
Take History - Automatic history tracking with dropdown access to previous takes
Real-time Status - Live connection status monitoring for all recorders

OSC Integration

Bitfocus Companion Support - Bidirectional OSC communication with custom DeckPilot module
Unified Port Architecture - All recorders share ports 8012 (incoming) and 8014 (outgoing)
Per-Recorder Variables - Automatic variable creation for each recorder's take data
Stream Deck Ready - Full integration with Stream Deck buttons and triggers
Configurable Settings - Adjustable OSC host, ports, and listener options

cmnd Integration

Distributed System Support - Integrate with cmndHub for centralized monitoring and control
Remote Command Execution - Control DeckPilot remotely from cmndHub dashboard
Real-time Metrics - Report recorder status, disk space, and recording state to cmndHub
Multi-Site Coordination - Manage multiple DeckPilot instances across distributed locations
Fleet Management - Centralized control of all HyperDeck recorders via cmndHub

User Interface

Clean Dark Theme - Professional, easy-to-read interface
Floating Window - Always-on-top option for quick access
Settings Access - Click the AE logo to access OSC configuration
Persistent State - All settings and history saved automatically

Installation

Download Pre-built

Download the latest release from the releases page
Install the DMG (macOS) or installer for your platform
Launch DeckPilot

Build from Source

Quick Start - Interactive Build Menu

macOS / Linux:

./build.sh

Windows:

build.bat

The interactive menu offers:

Build Electron App
Build Companion Module
Build Both
Install Companion Module
Build Companion + Install
Build All + Install Companion

Note: Version numbers auto-increment on each build (0.0.12 → 0.0.13, etc.)

What Gets Built

After running the build script, you'll find in ./release/:

DeckPilot Application:

macOS: DeckPilot-0.0.2-arm64.dmg (installer), DeckPilot-0.0.2-arm64-mac.zip (portable)
Windows: DeckPilot-Setup-0.0.2.exe (installer), DeckPilot-0.0.2-win.zip (portable)

Companion Module:

companion-module-svndco-deckpilot-0.0.2.tgz - Ready to install in Companion

Manual Build Steps

If you prefer to build components separately:

DeckPilot App Only:

npm install
npm run build

Companion Module Only:

cd companion-module-svndco-deckpilot
npm install --legacy-peer-deps
npm run build
npx companion-module-build

Development Mode:

npm run electron:dev  # Hot reload development

Build Requirements

All Platforms:

Node.js 18+ or 22+
npm

macOS:

Xcode Command Line Tools

Windows:

Visual Studio Build Tools
Windows SDK

Installing the Companion Module

Option 1: Automatic (Recommended) Use the build menu:

./build.sh  # Select option 5: Build Companion + Install

This automatically installs the module to the correct Companion directory.

Option 2: Manual

macOS:

mkdir -p ~/Library/Application\ Support/companion/modules/svndco-deckpilot
tar -xzf companion-module-svndco-deckpilot/svndco-deckpilot-*.tgz -C ~/Library/Application\ Support/companion/modules/svndco-deckpilot --strip-components=1

Windows:

mkdir %APPDATA%\companion\modules\svndco-deckpilot
tar -xzf companion-module-svndco-deckpilot\svndco-deckpilot-*.tgz -C %APPDATA%\companion\modules\svndco-deckpilot --strip-components=1

Important:

Restart Companion completely after installing the module
To update: If you already have a DeckPilot connection, open its settings and select the new version from the dropdown

Version Management

Versions auto-increment with each build. The build script updates:

Main app package.json
Companion module package.json and manifest.json
README.md version badge

All builds output to ./release/ directory.

Usage

Adding Recorders

Click "+ Add Recorder" button
Enter recorder name (e.g., "HYPER-41")
Enter IP address (e.g., "192.168.1.100")
Select format template (Show, Take, or Custom)
Click "Add"

Setting Take Names

Select a recorder from the list
Choose template (Show/Take/Custom)
For Take template:
- Set shot number (increments automatically or manually)
- Set take number (increments with each take)
Enter or select take name
Take name is automatically sent to the recorder and via OSC

OSC Configuration

Click the Settings button in the top-right corner
Configure settings:
- Enable OSC: Toggle OSC functionality
- OSC Host: Companion IP address (default: 127.0.0.1)
- OSC Port: Companion module port (default: 8014)
- OSC Listener Port: Incoming command port (default: 8012)
Click "Save"

Companion Integration

DeckPilot includes a custom Companion module that automatically handles OSC communication and creates variables for each recorder.

Quick Setup

Install the DeckPilot Companion Module (see installation instructions above)
Add DeckPilot connection in Companion:
- Module: DeckPilot (by svndco)
- OSC Listener Port: 8014
Use variables in your Stream Deck buttons:
- $(deckpilot:HYPER_41_take) - Full take name
- $(deckpilot:HYPER_41_shot_num) - Shot number
- $(deckpilot:HYPER_41_take_num) - Take number

OSC Ports

Port 8012: Incoming commands (Companion → DeckPilot)
Port 8014: Outgoing feedback (DeckPilot → Companion module)
All recorders share the same ports; individual recorders are identified by name in OSC paths

For detailed setup instructions, see:

OSC_CONFIGURATION.md - Start here! Network setup and module installation
OSC_COMMANDS.md - Complete OSC protocol reference and command formats
STREAMDECK_SETUP.md - Stream Deck button examples and workflows

cmnd Integration

DeckPilot can integrate with cmndHub for centralized monitoring and control across distributed production environments.

What is cmnd?

cmnd is a distributed command & control system for monitoring and managing servers across virtual production sites. When integrated with cmndHub, DeckPilot becomes a managed node that reports status and accepts remote commands.

Setup

Enable cmnd in DeckPilot Settings:
- Click the Settings icon (gear) in DeckPilot
- Scroll to "cmnd Integration" section
- Check "Enable cmnd Integration"
- Configure Hub URL (default: ws://localhost:5000/ws)
- Optionally set Node ID and Show ID
- Click "Save Settings"
Verify Connection:
- DeckPilot will connect to cmndHub via WebSocket
- Check cmndHub logs for authentication message
- DeckPilot appears as a node in cmndHub dashboard

What DeckPilot Reports to cmndHub

Authentication (on connect):

Node ID (auto-generated UUID)
Hostname and platform
DeckPilot version
Node type: "deckpilot"

Metrics (every 30 seconds):

recorders_total - Total number of recorders configured
recorders_online - Number of online/connected recorders
recorders_recording - Number of recorders currently recording
total_disk_space_gb - Combined disk space across all HyperDecks

Heartbeat (every 30 seconds):

Keeps connection alive
Updates last-seen timestamp in cmndHub

Remote Commands from cmndHub

DeckPilot accepts these commands from cmndHub:

Command	Parameters	Description
`set_take_name`	`recorderId`, `takeName`	Update take name for specific recorder
`start_recording`	`recorderId`	Start recording on recorder
`stop_recording`	`recorderId`	Stop recording on recorder
`increment_take`	`recorderId`	Increment take number
`increment_shot`	`recorderId`	Increment shot number (resets take to 1)
`get_recorders`	none	Get list of all recorders with status
`get_status`	none	Get DeckPilot overall status

Example command execution from cmndHub:

// Send command to DeckPilot node
{
  "type": "command",
  "command_id": "cmd-123",
  "node_id": "deckpilot-uuid",
  "command": "set_take_name",
  "params": {
    "recorderId": "recorder-1",
    "takeName": "ShowName_S01_T05"
  }
}

Use Cases

Multi-Site Production:

Monitor all DeckPilot instances from central cmndHub
Coordinate take names across distributed locations
Synchronized recording triggers across sites

Fleet Management:

Centralized view of all HyperDeck recorders
Remote take name updates without local access
Disk space monitoring and alerts

Automation:

Script complex recording workflows via cmndHub API
Integrate with other production tools through cmndHub
Create custom dashboards and monitoring

Architecture

cmndHub (Central Server)
    ↕ WebSocket (port 5000)
DeckPilot Node 1 (Site A)
    ↕ HyperDeck Protocol (port 9993)
HyperDeck Recorders (Site A)

DeckPilot Node 2 (Site B)
    ↕ HyperDeck Protocol (port 9993)
HyperDeck Recorders (Site B)

Configuration Files

Configuration is stored in:

macOS: ~/Library/Application Support/deckpilot/config.json
Windows: %APPDATA%/deckpilot/config.json
Linux: ~/.config/deckpilot/config.json

Project Structure

deckpilot/
├── electron/           # Electron main process
│   ├── main.ts        # Main process, OSC/cmnd handling, IPC
│   ├── cmnd-client.ts # cmnd WebSocket client
│   ├── preload.ts     # Preload script for IPC bridge
│   └── build.js       # Build script
├── src/               # React application
│   ├── components/    # React components
│   │   ├── RecorderList.tsx
│   │   ├── TakeInput.tsx
│   │   └── Settings.tsx
│   ├── App.tsx        # Main App component
│   ├── App.css        # Styles
│   └── main.tsx       # React entry point
├── shared/            # Shared TypeScript types
│   └── types.ts       # Type definitions
└── public/            # Static assets

Development

Available Scripts

npm run dev - Start Vite dev server
npm run electron:dev - Run Electron app in development mode
npm run build - Build production app (DMG/installer)
npm run build:electron - Build Electron main process only

Tech Stack

Electron - Desktop application framework
React - UI framework
TypeScript - Type-safe development
Vite - Fast build tool
OSC - Open Sound Control for Companion integration

Documentation

For detailed information, see:

OSC_COMMANDS.md - Complete OSC protocol reference, command formats, and examples
STREAMDECK_SETUP.md - Stream Deck button configuration and workflows
OSC_CONFIGURATION.md - Network configuration and setup guide
WARP.md - Development guide for AI assistants (architecture, patterns, build commands)

Troubleshooting

OSC Messages Not Sending

Check OSC is enabled in Settings
Verify DeckPilot Companion module is installed and connection shows green
Check OSC port is set to 8014 in both DeckPilot settings and Companion module config
Check firewall settings aren't blocking UDP ports 8012 and 8014
Review Companion logs for incoming OSC messages

Recorders Not Connecting

Verify IP addresses are correct
Ensure recorders are on the same network
Check recorder status indicators (green = online)
HyperDeck control port 9993 must be accessible

Settings Not Saving

Restart the application
Check file permissions in application support directory
Review console logs for errors (View > Toggle Developer Tools)

Roadmap

HyperDeck protocol integration for direct recorder control
Timecode display and sync
Multi-camera take synchronization
Export take logs to CSV/Excel
Custom keyboard shortcuts
Predefined take lists

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues.

License

MIT

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
companion-module-svndco-deckpilot		companion-module-svndco-deckpilot
electron		electron
scripts		scripts
shared		shared
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
OSC_COMMANDS.md		OSC_COMMANDS.md
OSC_CONFIGURATION.md		OSC_CONFIGURATION.md
README.md		README.md
STREAMDECK_SETUP.md		STREAMDECK_SETUP.md
WARP.md		WARP.md
build.bat		build.bat
build.sh		build.sh
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
test-osc.js		test-osc.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

DeckPilot

Features

Core Functionality

OSC Integration

cmnd Integration

User Interface

Installation

Download Pre-built

Build from Source

Quick Start - Interactive Build Menu

What Gets Built

Manual Build Steps

Build Requirements

Installing the Companion Module

Version Management

Usage

Adding Recorders

Setting Take Names

OSC Configuration

Companion Integration

Quick Setup

OSC Ports

cmnd Integration

What is cmnd?

Setup

What DeckPilot Reports to cmndHub

Remote Commands from cmndHub

Use Cases

Architecture

Configuration Files

Project Structure

Development

Available Scripts

Tech Stack

Documentation

Troubleshooting

OSC Messages Not Sending

Recorders Not Connecting

Settings Not Saving

Roadmap

Contributing

License

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages