The Director Application

The Director is a desktop Electron application that serves as the on-machine broadcast execution engine for Sim RaceCenter. It runs alongside the racing simulator and OBS Studio on the broadcast machine, executing camera commands, managing scene transitions, and coordinating all local integrations in real time.

Purpose

While Race Control (the web interface) handles configuration and monitoring, the Director handles execution. It is the component that actually controls the broadcast -- switching cameras in iRacing, transitioning scenes in OBS, and coordinating the timing of every production decision.

The Director communicates with the Race Control API using a check-in/poll loop:

1. Check-in: At session start, the Director sends its capabilities (which integrations are connected, what intents it can execute) to the API
2. Poll: During the race, it continuously polls for the next broadcast sequence to execute
3. Execute: Each sequence contains a series of steps (camera switches, scene transitions, delays) that the Director executes in order

Extension System

The Director uses a modular extension architecture. Each integration is implemented as an extension that registers its capabilities with the system:

iRacing Extension

Connects to the iRacing simulator via its SDK to:

• Read live telemetry data (positions, lap times, gaps, flags)
• Control the broadcast camera (switch between drivers, change camera groups)
• Monitor session state (practice, qualifying, race, cooldown)
• Detect incidents and flag changes

Registered intents:

• broadcast.showLiveCam -- switch to a driver's live camera feed with a specific camera group

OBS Extension

Connects to OBS Studio via the obs-websocket protocol to:

• Switch between pre-configured scenes
• Trigger scene transitions (cut, fade, stinger)
• Control source visibility for overlays
• Manage recording and streaming state

Registered intents:

• obs.switchScene -- transition to a named scene
• overlay.show -- show an overlay source
• overlay.hide -- hide an overlay source

Discord Extension

Integrates with Discord for communication during broadcasts:

• Text-to-speech announcements during race events
• Channel notifications for session state changes
• Voice channel integration for production team communication

YouTube Extension

Manages YouTube Live streaming:

• Stream health monitoring
• Chat integration for viewer interaction
• Stream metadata updates

Capability Catalog

The Director maintains a CapabilityCatalog that tracks all available intents from all connected extensions. When the Director checks in with the Race Control API, it sends its full capability list so the AI Planner knows what actions are available for template generation.

Each capability includes:

• Intent name (e.g., broadcast.showLiveCam)
• Description of what it does
• Payload schema defining required and optional parameters
• Source extension (which extension provides it)

Sequence Execution

The Director executes sequences as ordered lists of steps. Each step has:

• Intent: The action to perform (e.g., broadcast.showLiveCam)
• Payload: Parameters for the action (e.g., { carNum: "42", camGroup: 3 })
• Metadata: Optional timing and display information (e.g., { label: "Show leader", timeout: 5000 })

Steps are executed sequentially with configurable delays between them. The Director's SequenceExecutor handles:

• Step-by-step execution with error recovery
• Variable resolution (replacing ${driverName} with concrete values)
• Timeout management per step
• Graceful degradation if an extension is disconnected

Sequence Library

The Director includes a three-tier sequence library:

1. Built-in sequences: Pre-packaged sequences shipped with the application (e.g., "Show Leader", "Battle Coverage", "Field Sweep"). Stored on disk in the installation directory.

2. Cloud sequences: AI-generated templates from the session's Planner run, synced from the Race Control API. These are session-specific sequences tailored to the current race configuration and available capabilities.

3. Custom sequences: User-created sequences stored in the application's user data directory. Broadcast Directors can create and save their own sequences for reuse.

The library is accessible through the Director's UI under the Sequences Catalog, organized by category (Built-in, Cloud, Custom). Operators can browse, preview, and manually trigger any sequence from the catalog.

Check-In Flow

When a broadcast session starts, the Director performs a check-in with the Race Control API:

Director                              Race Control API
   |                                        |
   |-- POST /sessions/{id}/checkin -------->|
   |   { capabilities, operatorSequences,   |
   |     connectionHealth }                 |
   |                                        |-- Store CheckinDocument
   |                                        |-- Fire: planSessionSequences()
   |<-------- { sessionConfig, checkinId } -|
   |                                        |
   |-- POST /sessions/{id}/sequences/next ->|  (poll loop starts)
   |   X-Checkin-Id: {checkinId}            |
   |<-------- { PortableSequence }  --------|
   |                                        |
   |-- (execute sequence locally) --------->|
   |                                        |
   |-- POST /sessions/{id}/sequences/next ->|  (next poll)
   ...                                     ...

The check-in triggers the Planner to generate session-specific templates in the background. By the time the first few polls come through, the Planner has typically finished and the Executor can start using the generated templates.

Configuration

The Director is configured through:

• Session selection: Choose which race session to direct (from the list in Race Control)
• Extension settings: Connection details for iRacing, OBS, Discord, YouTube
• Polling interval: How frequently to request new sequences (auto-adjusted based on sequence duration)
• Manual override: Operators can pause AI direction and take manual control at any time

Intents System

Intents are the universal action vocabulary shared between the Director and the AI pipeline. They follow a domain.action naming convention:

The intent system ensures that the AI pipeline generates sequences using only actions the Director can actually execute, based on what was reported during check-in.