TK Dynamic Delay
TK Dynamic Delay

Architecture Overview

TK Dynamic Delay uses HLS (HTTP Live Streaming) segment-based buffering with playlist manipulation to achieve an adjustable delay from 0 to 180 seconds.

High-Level Data Flow

┌──────────────────────────────────────────────────────────────┐
│                        OBS Studio                            │
│  Settings → Stream: Twitch (Primary Output to Viewers)       │
│  Tools → Multiple output: SRT to localhost:9000 (Buffer)     │
└──────────────────────────────────────────────────────────────┘
                            │ Port 9000 (SRT)
                            ▼
                    MediaMTX Server
                            │ HLS Segments (2s)
                            ▼
            Buffer Storage (C:\ProgramData\StreamDelay\hls)
                            │ Playlist Manipulation
                            ▼
                    Controller Service
                            │ Port 8080 (HTTP)
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                 OBS Studio — Scene Switching                 │
│  → Live Scene: Immediate (viewers see this on Twitch)        │
│  → Delayed Scene: Media Source (delayed.m3u8) — past moments │
└──────────────────────────────────────────────────────────────┘

Components

1. Input Receiver Service

Purpose: Manages the MediaMTX process lifecycle and monitors stream health.

DetailValue
Implementationservices/input-receiver-mediamtx/main.go
Service NameStreamDelayInput
Display NameStream Delay Input Receiver
Start TypeAutomatic (Delayed Start)

Key Responsibilities:

  • Generate MediaMTX configuration from .env file
  • Start and supervise MediaMTX process
  • Monitor stream via MediaMTX API
  • Handle process crashes with automatic restart
  • Clean up HLS files on service start and stop
  • Log to Windows Event Log and file

2. Controller Service

Purpose: REST API server, web dashboard host, and HLS playlist manipulator.

DetailValue
Implementationcontroller/main.go (~921 lines)
Service NameStreamDelayController
Display NameStream Delay Controller
Start TypeAutomatic

Key Responsibilities:

  • Generate delayed.m3u8 from live.m3u8 every 2 seconds
  • Serve REST API endpoints for delay control
  • Host embedded web dashboard
  • Persist state to JSON file
  • Clean up HLS files on service start and stop

Playlist Manipulation Algorithm:

  1. Read live.m3u8
  2. Calculate skip count = delaySeconds / segmentDuration
  3. Take older segments (segments[:len-skipCount])
  4. Write new delayed.m3u8

3. Web Dashboard

Purpose: User-friendly browser interface for delay control.

DetailValue
Implementationcontroller/dashboard.html (embedded via //go:embed)
URLhttp://localhost:8080

Features:

  • Responsive CSS Grid layout
  • Real-time status updates (2-second polling)
  • Delay slider (0–180 seconds)
  • Quick preset buttons (30s, 60s, 90s, 120s, 180s)
  • Buffer visualization

4. MediaMTX Server

Purpose: Convert SRT input to HLS segments.

DetailValue
Binarymediamtx.exe v1.8.5
SRT Port9000
HLS Port8888
API Port9997
Segment Duration2 seconds
Buffer Size100 segments

5. Bootstrapper

Purpose: Elevated setup utility run during MSI installation.

Functions:

  • Create directory structure
  • Download MediaMTX binary
  • Install Windows services
  • Create default configuration
  • Register Event Log sources
  • Start services

Design Decisions

DecisionRationale
HLS over Direct BufferingSegments naturally support variable delay; disk-based = no memory pressure; standard format supported by OBS
Two Separate ServicesSeparation of concerns; can restart independently
No AuthenticationLocalhost-only reduces risk; simpler OBS configuration
Native Go Windows ServicesNo external dependencies; proper event logging; graceful shutdown
Embedded DashboardZero external files; atomic deployment

Performance Characteristics

MetricValue
CPU (idle)< 1%
CPU (streaming)15–30% total
Memory (Controller)~50 MB
Memory (Input Receiver)~30 MB
Memory (MediaMTX)~80 MB
Total system latency (0s delay)~4–5 seconds minimum
Delay adjustment latency~4–6 seconds

File System Layout

PathContents
C:\Program Files\StreamDelay\Executables
C:\ProgramData\StreamDelay\.envConfiguration
C:\ProgramData\StreamDelay\hls\HLS segments & playlists
C:\ProgramData\StreamDelay\logs\Service log files

Project Structure

TKDynamicDelay/
├── controller/                       # Controller service (Go)
│   ├── main.go                       # REST API, HLS manipulation
│   ├── dashboard.html                # Embedded web UI
│   └── build.ps1, go.mod
├── services/
│   └── input-receiver-mediamtx/      # Input service (Go)
│       ├── main.go                   # MediaMTX wrapper
│       └── build.ps1, go.mod
├── bootstrapper/                     # MSI bootstrapper (Go)
│   └── main.go, build.ps1, go.mod
├── msi/                              # MSI installer (WiX)
│   └── Product.wxs
├── DOC/                              # Documentation
├── build-all.ps1                     # Full build script
├── build-msi.ps1                     # MSI-only build
├── install-prerequisites.ps1         # Dev environment setup
└── README.md
Prev
Quick Start
Next
Settings Reference