WebSocket API

Connection

The WebSocket server runs on ws://localhost:44030/ and accepts connections from the frontend.

const socket = new WebSocket('ws://localhost:44030/');

The backend only allows one active WebSocket connection. New connections automatically close previous ones.

Message Structure

Frontend to Backend

Messages sent via window.external.sendMessage() use this JSON structure:

{
  "Method": "string",
  "Parameters": {
    // Method-specific parameters
  }
}

Backend to Frontend

Messages received via WebSocket use this JSON structure:

{
  "method": "string",
  "content": {
    // Event-specific data
  }
}

Note the casing difference: Method (capitalized) for frontend-to-backend, method (lowercase) for backend-to-frontend due to JSON serialization settings.

Frontend to Backend Methods

These commands can be sent from the frontend to control the backend.

Recording Control

method

Starts a manual recording session.Parameters: NoneExample:

sendMessageToBackend('StartRecording');

method

Stops the current recording.Parameters: NoneExample:

sendMessageToBackend('StopRecording');

Authentication

Authenticates the user with Supabase tokens.Parameters:

string

required

Supabase access token from the session

string

required

Supabase refresh token for token renewal

Example:

sendMessageToBackend('Login', {
  accessToken: session.access_token,
  refreshToken: session.refresh_token,
});

method

Signs out the current user.Parameters: NoneExample:

sendMessageToBackend('Logout');

Clip Creation

method

Creates clips from selected video segments.Parameters:

string

Optional. Set to "separate" to export each segment as its own clip instead of concatenating them.

array

required

Array of segment objects defining clip ranges. Segments no longer duplicate content metadata; the backend resolves game, title, type, IGDB ID, file name, and file path from the referenced content.

number

required

Unique identifier for this segment

string

required

ID of the source content (from Content.id). The backend looks up the source file, type, game, title, and IGDB ID from application state.

number

required

Start timestamp in seconds

number

required

End timestamp in seconds

number[]

Optional array of audio track indexes to mute in the output

object

Optional map of { "<trackIndex>": <volume> } to apply per-track volume adjustments

Example:

sendMessageToBackend('CreateClip', {
  Segments: [{
    id: 1,
    contentId: "9f1c8d0a-...",
    startTime: 30.5,
    endTime: 45.2,
  }]
});

method

Cancels an in-progress clip operation.Parameters:

number

required

The clip operation ID to cancel

Example:

sendMessageToBackend('CancelClip', { id: 123 });

method

Creates AI-generated highlights from a video.Parameters:

string

required

ID of the source content to process (from Content.id).

Example:

sendMessageToBackend('CreateAiClip', {
  Id: "9f1c8d0a-..."
});

Content Management

method

Deletes a single piece of content.Parameters:

string

required

ID of the content to delete (from Content.id). The backend resolves the file path and content type from application state.

Example:

sendMessageToBackend('DeleteContent', {
  Id: "9f1c8d0a-..."
});

method

Deletes multiple content items in a batch operation.Parameters:

string[]

required

Array of content IDs to delete (from Content.id).

Example:

sendMessageToBackend('DeleteMultipleContent', {
  Ids: [
    "9f1c8d0a-...",
    "b2ac7e11-..."
  ]
});

method

Renames a content item’s title.Parameters:

string

required

ID of the content to rename (from Content.id).

string

required

New title for the content.

Example:

sendMessageToBackend('RenameContent', {
  Id: "9f1c8d0a-...",
  Title: "Ace on Ascent"
});

method

Imports an external video file into Segra.Parameters: Handled by ImportService.HandleImportFileExample:

sendMessageToBackend('ImportFile', {
  // Parameters defined in ImportService
});

Upload & Compression

method

Uploads content to Segra.tv. The backend reads Game and IgdbId off the referenced content and uses the current session for authentication (no JWT field is sent).Parameters:

string

required

ID of the content to upload (from Content.id).

string

required

Title to display on Segra.tv.

string

Optional description for the upload.

string

"Public" or "Unlisted".

Example:

sendMessageToBackend('UploadContent', {
  Id: "9f1c8d0a-...",
  Title: "Epic Ace",
  Description: "1v5 clutch on Ascent",
  Visibility: "Public"
});

method

Cancels an in-progress upload.Parameters:

string

required

File name of the upload to cancel

Example:

sendMessageToBackend('CancelUpload', {
  fileName: "clip_001.mp4"
});

method

Compresses a video to reduce file size. The compressed file inherits the source’s name (falling back to " (1)", " (2)", … on collision) and is flagged in metadata via Content.compressed; there is no longer a _compressed filename suffix.Parameters:

string

required

ID of the content to compress (from Content.id).

Example:

sendMessageToBackend('CompressVideo', {
  Id: "9f1c8d0a-..."
});

Bookmarks

method

Adds a bookmark to a piece of content.Parameters:

string

required

ID of the content to bookmark (from Content.id).

number

required

Client-generated bookmark ID.

string

required

Bookmark type (parsed as BookmarkType).

string

required

Timestamp string parsed by the backend (e.g. "00:01:23.500").

Example:

sendMessageToBackend('AddBookmark', {
  ContentId: "9f1c8d0a-...",
  Id: 1,
  Type: "Manual",
  Time: "00:01:23.500"
});

method

Removes a bookmark from a piece of content.Parameters:

string

required

ID of the content the bookmark belongs to (from Content.id).

number

required

Bookmark ID to remove.

Example:

sendMessageToBackend('DeleteBookmark', {
  ContentId: "9f1c8d0a-...",
  Id: 1
});

Settings

method

Updates application settings.Parameters: Handled by SettingsService.HandleUpdateSettingsExample:

sendMessageToBackend('UpdateSettings', {
  // Settings object with changed values
});

method

Opens a folder picker to change the video storage location.Parameters: NoneExample:

sendMessageToBackend('SetVideoLocation');

method

Opens a folder picker to change the cache storage location.Parameters: NoneExample:

sendMessageToBackend('SetCacheLocation');

method

Applies a video quality preset (see PresetsService.ApplyVideoPreset).Parameters:

string

required

Preset name: low, standard, high, or custom

Example:

sendMessageToBackend('ApplyVideoPreset', {
  preset: "high"
});

method

Applies a clip quality preset (see PresetsService.ApplyClipPreset).Parameters:

string

required

Preset name: low, standard, high, or custom

Example:

sendMessageToBackend('ApplyClipPreset', {
  preset: "standard"
});

Game Management

Per-game record/skip preferences live on the unified games array in Settings.Instance (each entry has a record boolean plus optional quality / recording-mode overrides). Update them by sending an UpdateSettings message with the modified games array — there are no dedicated AddToWhitelist / AddToBlacklist / MoveGame methods. The legacy whitelist / blacklist fields are migration-only and may be removed in a future release.

method

Opens a file picker to select a game executable.Parameters: NoneResponse: Backend sends SelectedGameExecutable message with the selected fileExample:

sendMessageToBackend('SelectGameExecutable');

System Actions

method

Opens Windows Explorer to the file location.Parameters:

string

required

Full path to the file

Example:

sendMessageToBackend('OpenFileLocation', {
  FilePath: "C:/Videos/clip.mp4"
});

method

Copies a file to the Windows clipboard so it can be pasted into Explorer, chat clients, or other apps that accept file drops.Parameters:

string

required

Full path to the file to copy

Example:

sendMessageToBackend('CopyFileToClipboard', {
  FilePath: "C:/Videos/clip.mp4"
});

method

Compresses a video down to a target size and copies the result to the Windows clipboard. Powers the “Copy as MB” entries in the video page’s Copy split button.Parameters:

string

required

Full path to the source video file.

number

required

Target maximum size for the compressed copy, in megabytes. Values that are not smaller than the source are rejected by the UI. See copyCompressSizesMb in Settings for the sizes offered by default.

Response: Backend streams ClipboardCompressionProgress events during compression.Example:

sendMessageToBackend('CopyCompressedFileToClipboard', {
  FilePath: "C:/Videos/clip.mp4",
  MaxSizeMb: 50
});

method

Opens a URL in the default browser.Parameters:

string

required

URL to open

Example:

sendMessageToBackend('OpenInBrowser', {
  Url: "https://segra.tv"
});

method

Opens Windows Explorer to the logs folder.Parameters: NoneExample:

sendMessageToBackend('OpenLogsLocation');

method

Toggles fullscreen mode.Parameters:

boolean

required

True to enable fullscreen, false to disable

Example:

sendMessageToBackend('ToggleFullscreen', {
  enabled: true
});

Updates

method

Checks for available application updates.Parameters: NoneExample:

sendMessageToBackend('CheckForUpdates');

method

Applies a downloaded update and restarts the application.Parameters: NoneExample:

sendMessageToBackend('ApplyUpdate');

Connection

method

Signals that a new WebSocket connection has been established. The backend responds with initial state.Parameters: NoneResponse: Backend sends:

Settings with persisted settings
State with runtime application state
GameList with available games
AppVersion with backend version (only when an update manager build is available)
UpdateProgress if an update download/install was in flight when the client (re)connected, replaying the most recent progress payload
ReleaseNotes asynchronously, after fetching from the update channel

Example:

sendMessageToBackend('NewConnection');

Storage & Recovery

method

Confirms or cancels a storage warning action.Parameters: Handled by StorageWarningService.HandleStorageWarningConfirm

method

Confirms recovery of temporary files after a crash.Parameters: Handled by RecoveryService.HandleRecoveryConfirm

method

Triggers migration of existing content into Segra’s canonical folder layout.Parameters: Handled by ContentMigrationService.HandleMigrateContentProgress: The backend streams ContentMigrationProgress events while the migration runs.

Backend to Frontend Events

These messages are sent from the backend to update the frontend state.

State Updates

event

Sends the persisted user settings to the frontend. content is the bare Settings.Instance object (no wrapping settings key).Example:

{
  "method": "Settings",
  "content": {
    "contentFolder": "C:/Videos",
    "cacheFolder": "C:/AppData/Segra",
    "resolution": "1440p",
    "frameRate": 60,
    "recordingMode": "Hybrid",
    "keybindings": [...]
    // ... all persisted settings
  }
}

Runtime state (active recording, content library, detected devices, current folder size, etc.) is no longer nested under settings.state. It is delivered separately via the State message described below.

event

Sends the runtime AppState.Instance object to the frontend. This is non-persisted, in-memory state that mirrors the live application status.Content (selected fields):

object

The active Recording (or null when idle)

object

A PreRecording placeholder while Segra is preparing to record (or null)

array

All known content items (sessions, buffers, clips, highlights)

array

Detected audio input devices

array

Detected audio output devices

array

Detected monitors

array

Available video codecs/encoders

array

OBS versions known to the updater

string

Detected GPU vendor (Nvidia, Amd, Intel, or Unknown)

number

Detected CUDA compute capability for NVIDIA GPUs

number

Maximum height of any connected display (used for resolution clamping)

boolean

True once OBS has been initialized

boolean

True while an update check is in-flight

number

Total size of the content folder in GB

Example:

{
  "method": "State",
  "content": {
    "recording": null,
    "preRecording": null,
    "content": [],
    "gpuVendor": "Nvidia",
    "currentFolderSizeGb": 12.4,
    "hasLoadedObs": true
  }
}

event

Sends the list of detected games.Content: The content field is itself an array of GameEntry objects — there is no wrapping games key.Example:

{
  "method": "GameList",
  "content": [
    {
      "name": "Valorant",
      "executables": ["C:\\Games\\Valorant\\VALORANT.exe"]
    }
  ]
}

Each entry uses the GameEntry shape from Backend/Games/GameUtils.cs — name and executables (back-slashed). It is distinct from the Game shape used for whitelist/blacklist commands, which uses paths.

event

Sends the backend application version for version mismatch detection.Content:

string

Semantic version string (e.g., “1.2.3”)

Example:

{
  "method": "AppVersion",
  "content": {
    "version": "1.2.3"
  }
}

Frontend automatically reloads if this doesn’t match __APP_VERSION__

Progress Events

event

Reports progress of clip creation operations.Content:

number

required

Clip operation ID

number

required

Progress percentage (0-100), or -1 for error

array

required

Array of segments being processed (mirrors what was sent in CreateClip)

string

Error message if progress is -1

Example:

{
  "method": "ClipProgress",
  "content": {
    "id": 123456,
    "progress": 45,
    "segments": [...]
  }
}

event

Reports progress of upload operations.Content:

string

required

File being uploaded

string

required

Title submitted with the upload (mirrored in every progress event)

number

required

Progress percentage (0-100), or -1 for error

string

required

Upload status: “uploading”, “processing”, “done”, or “error”

string

Status message or error description

string

Local file path of the source content’s thumbnail (from FolderNames.GetThumbnailFilePath). Used by upload cards to render a blurred background matching the content’s cover. Omitted when no thumbnail exists.

Example:

{
  "method": "UploadProgress",
  "content": {
    "fileName": "clip_001.mp4",
    "progress": 75,
    "status": "uploading",
    "thumbnailPath": "C:/Users/User/AppData/Roaming/Segra/thumbnails/...jpeg",
    "message": "Uploading to server..."
  }
}

event

Reports progress of file import operations.Content:

number

required

Import operation ID

string

required

Current file being imported

number

required

Progress percentage for current file

string

required

Import status: “importing”, “done”, or “error”

number

required

Total number of files to import

number

required

Index of current file (0-based)

string

Status message

event

Reports progress of video compression.Content:

string

required

File being compressed

number

required

Progress percentage (0-100), or -1 for error

string

required

Status: “compressing”, “done”, “skipped”, or “error”

string

Status message

Example:

{
  "method": "CompressionProgress",
  "content": {
    "filePath": "C:/Videos/large.mp4",
    "progress": 50,
    "status": "compressing"
  }
}

event

Reports progress of a CopyCompressedFileToClipboard operation. The video page uses these events to animate the Copy button while a size-capped copy is being prepared.Content:

string

required

Source file being compressed for the clipboard copy

number

required

Progress percentage (0-100)

string

required

Status: “compressing”, “done”, or “error”

string

Status or error message

event

Reports progress of application updates.Content:

string

required

Version being downloaded

number

required

Download progress (0-100)

string

required

Status: “downloading”, “downloaded”, or “ready”

string

required

Human-readable status message

event

Reports progress of AI highlight generation.Content: Handled by AiService

event

Indicates whether the recording-preview window is currently active (the in-app live preview controlled by the TogglePreview keybind).Content:

boolean

required

Whether preview rendering is active

event

Streams a frame of the live recording preview to the frontend (sent only while the preview is enabled).Content: A frame payload emitted by RecordingPreviewService.

event

Reports status of data migration operations.Content:

boolean

required

Whether migration is currently running

string

Description of current migration

event

Reports progress of a content-folder migration triggered by MigrateContent.Content:

string

required

Migration operation ID

string

required

File currently being moved

number

required

Progress percentage (0-100), or -1 for error

string

required

Migration status (e.g. "migrating", "done", "error")

number

Total number of files in the migration

number

Index of the file currently being moved

string

Status or error message

event

Fired when the user saves the replay buffer (typically via the SaveReplayBuffer keybind). Emitted with an empty content payload — frontends usually surface a toast or sound effect in response.

User Notifications

Displays a modal dialog to the user.Content:

string

required

Modal title

string

Optional subtitle

string

required

Modal body text

string

required

Modal type: “info”, “warning”, or “error”

Example:

{
  "method": "ShowModal",
  "content": {
    "title": "Error",
    "description": "Failed to start recording",
    "type": "error"
  }
}

event

Warns user about storage space issues and requests confirmation.Content:

string

required

Unique ID for this warning

string

required

Warning title

string

required

Warning description

string

required

Text for confirm button

string

required

Text for cancel button

string

required

Action to perform if confirmed

any

required

Data needed to perform the action

event

Prompts user to recover files after a crash.Content:

array

required

Array of recoverable file objects

number

required

Total number of files that can be recovered

event

Notifies that a bookmark was created (typically from a keybind).Content: Empty objectExample:

{
  "method": "BookmarkCreated",
  "content": {}
}

UI Events

event

Returns the game executable selected by the user.Content:

string

required

Game name (derived from executable name)

array

required

Array containing the selected executable path

Example:

{
  "method": "SelectedGameExecutable",
  "content": {
    "name": "MyGame",
    "paths": ["C:/Games/MyGame/game.exe"]
  }
}

event

Sends release notes for available versions.Content:

array

required

Array of release note objects

string

required

Version number

string

required

Release notes in base64-encoded markdown

string

required

ISO 8601 date string

event

Triggers the frontend to display release notes.Content: Version string to show notes for

event

Reports OBS download progress during first-time setup.Content:

number

required

Download progress (0-100)

string

required

Download status: “downloading”

Heartbeat

event

Response to ping heartbeat message.Content: Empty objectExample:

{
  "method": "pong",
  "content": {}
}

Error Handling

Frontend Validation

Always check if the backend connection is available before sending messages:

if ((window as any).external && typeof (window as any).external.sendMessage === 'function') {
  sendMessageToBackend('StartRecording');
} else {
  console.error('Backend connection not available');
}

Backend Error Responses

When operations fail, the backend typically:

Logs the error with Serilog
Sends a progress event with progress: -1 and an error field
Optionally shows a ShowModal message to the user

Example error response:

{
  "method": "ClipProgress",
  "content": {
    "id": 123456,
    "progress": -1,
    "segments": [...],
    "error": "FFmpeg not found. Please reinstall Segra."
  }
}

Connection Failures

The WebSocket automatically reconnects if the connection drops:

Reconnect attempts: Infinite
Reconnect interval: 3 seconds
Heartbeat timeout: 30 seconds

When reconnected, the backend re-sends the full state:

onOpen: () => {
  console.log('WebSocket reconnected - resyncing state');
  sendMessageToBackend('NewConnection');
}

Best Practices

Use TypeScript Types

Import message type definitions from Models/WebSocketMessages.ts for type safety.

Handle All States

Progress events can be: in-progress (0-100), complete (100), or error (-1). Handle all cases.

Listen to Events

Use window.addEventListener('websocket-message') to react to backend events globally.

Graceful Degradation

Always check if window.external.sendMessage exists before calling it.

Never assume the WebSocket is connected. Use the isConnected state from useWebSocketContext() to check connection status.

Example: Complete Clip Workflow

Here’s a complete example showing the clip creation workflow:

import { sendMessageToBackend } from '../Utils/MessageUtils';
import { useEffect, useState } from 'react';

function ClipCreator() {
  const [progress, setProgress] = useState(0);
  const [clipId, setClipId] = useState<number | null>(null);

  // Listen for progress updates
  useEffect(() => {
    const handleMessage = (event: CustomEvent) => {
      const { method, content } = event.detail;
      
      if (method === 'ClipProgress') {
        if (content.id === clipId) {
          if (content.progress === -1) {
            console.error('Clip failed:', content.error);
          } else if (content.progress === 100) {
            console.log('Clip complete!');
          } else {
            setProgress(content.progress);
          }
        }
      }
    };

    window.addEventListener('websocket-message', handleMessage as EventListener);
    return () => window.removeEventListener('websocket-message', handleMessage as EventListener);
  }, [clipId]);

  const createClip = () => {
    const id = Math.floor(Math.random() * 1000000);
    setClipId(id);
    
    sendMessageToBackend('CreateClip', {
      Segments: [{
        id: id,
        contentId: sourceContent.id,
        startTime: 10,
        endTime: 20,
      }]
    });
  };

  const cancelClip = () => {
    if (clipId) {
      sendMessageToBackend('CancelClip', { id: clipId });
    }
  };

  return (
    <div>
      <button onClick={createClip}>Create Clip</button>
      <button onClick={cancelClip}>Cancel</button>
      <progress value={progress} max={100} />
    </div>
  );
}

Overview

Core Services

WebSocket API

Connection

Message Structure

Frontend to Backend

Backend to Frontend

Frontend to Backend Methods

Recording Control

Authentication

Clip Creation

Content Management

Upload & Compression

Bookmarks

Settings

Game Management

System Actions

Updates

Connection

Storage & Recovery

Backend to Frontend Events

State Updates

Progress Events

User Notifications

UI Events

Heartbeat

Error Handling

Frontend Validation

Backend Error Responses

Connection Failures

Best Practices

Use TypeScript Types

Handle All States

Listen to Events

Graceful Degradation

Example: Complete Clip Workflow

Next Steps

API Overview

Core Services

​Connection

​Message Structure

​Frontend to Backend

​Backend to Frontend

​Frontend to Backend Methods

​Recording Control

​Authentication

​Clip Creation

​Content Management

​Upload & Compression

​Bookmarks

​Settings

​Game Management

​System Actions

​Updates

​Connection

​Storage & Recovery

​Backend to Frontend Events

​State Updates

​Progress Events

​User Notifications

​UI Events

​Heartbeat

​Error Handling

​Frontend Validation

​Backend Error Responses

​Connection Failures

​Best Practices

Use TypeScript Types

Handle All States

Listen to Events

Graceful Degradation

​Example: Complete Clip Workflow

​Next Steps

API Overview

Core Services

Connection

Message Structure

Frontend to Backend

Backend to Frontend

Frontend to Backend Methods

Recording Control

Authentication

Clip Creation

Content Management

Upload & Compression

Bookmarks

Settings

Game Management

System Actions

Updates

Connection

Storage & Recovery

Backend to Frontend Events

State Updates

Progress Events

User Notifications

UI Events

Heartbeat

Error Handling

Frontend Validation

Backend Error Responses

Connection Failures

Best Practices

Example: Complete Clip Workflow

Next Steps