FRAME

FRAME is a modular, Docker-based streaming appliance for IRL and live production workflows. F.R.A.M.E. is an acronym for "Federated Relay and Automation of Media and Experiences".

This repository is the platform stack: a shared portal, routing edge, video relay, Belabox remote management, OBS overlays, photo upload and gallery tools, Photo Stage controls, and Audio Monitor. Each service has its own README under services/ for deeper setup and operating details.

Current release target: v1.0.0-release.

Audio Bridge is maintained independently in Syronius_FRAME_Audio_Bridge. Existing users should follow the extraction guide before upgrading FRAME.

Online Installer

Download the Windows x64 .exe or Linux x64 .AppImage from the v1.0.0-release downloads. Install and start Docker first, then run FRAME Setup. The installer checks configuration and host ports before downloading and starting the matching prebuilt service images. Internet access is required; the single-file download contains the installer runtime, not the Docker images.

The installers are unsigned. On Linux, make the AppImage executable before opening it. See FRAME Setup for prerequisites and installation details.

The development desktop app now includes FRAME Launcher: installed-stack status, everyday start/stop controls, tray access, and saved setup progress. It also includes macOS support for Intel and Apple Silicon, with separate .dmg/.zip build targets, a menu-bar icon, and native Docker image selection. These changes require a new matching source/image/installer release before distribution; the historical download above does not include them. Mac packaging and native smoke checks are configured in CI; signed installation and complete media workflows still need testing on real Macs. See launcher behavior and storage for the current implementation.

Get The Code

From GitHub, open Code and choose Download ZIP, or use this direct link:

https://github.com/gall-levi-code/Syronius_FRAME/archive/refs/heads/main.zip

Extract the ZIP somewhere with a simple path, for example:

C:\FRAME\Syronius_FRAME

Requirements

FRAME runs through Docker Compose.

• Install Docker Desktop for Windows: https://www.docker.com/get-started/
• Docker Compose v2 is included with Docker Desktop.
• Docker's Compose install notes are here: https://docs.docker.com/compose/install/

After installing Docker Desktop, open PowerShell and check:

docker --version
docker compose version

Linux and macOS use the same command center through ./stack.sh; the walkthrough below is Windows-first because double-clicking stack.cmd is the easiest path for most FRAME users.

Quick Start On Windows

Open the extracted FRAME folder in File Explorer, then double-click:

stack.cmd

FRAME opens a Command Prompt menu with numbered options.

For a first install:

1. Choose Guided setup.
2. Use the default LAN/local settings unless you already know you need something else.
3. When asked which services to enable, turn on:
   • Video Relay
   • Overlays
   • Browser Photo Upload
   • Photo Gallery
   • Photo Stage
4. Leave the other optional services disabled for now.
5. Set the required Portal username, password, and shared login session length when prompted.
6. Let the installer validate and verify the setup.
7. When it offers to reconcile the Docker Compose stack, choose yes.

If you return to the main menu before starting containers, choose Start or update stack.

Open the Portal:

http://localhost/dashboard

If you configured a different Edge port, include it, for example http://localhost:8088/dashboard. From another device on the same LAN, use the FRAME host's LAN IP address and configured port:

http://<FRAME-host-LAN-IP>:<configured-port>/dashboard

Omit :<configured-port> when the port is 80. You can also use a DNS name that you configure and maintain on your network. FRAME does not publish a LAN hostname or run a discovery watchdog. The localhost addresses below refer to the computer running FRAME; use the LAN address and configured port when opening the same pages from another device.

Useful first pages:

• Portal: http://localhost/dashboard
• Stream Management: http://localhost/slsui
• Stream Statistics: http://localhost/stats/<stream-id>
• Overlay Wizard: http://localhost/overlays/setup
• Browser Photo Upload: http://localhost/photos/upload
• Photo Gallery: http://localhost/today/gallery
• OBS Photo Stage Viewer: http://localhost/today/viewer
• Phone Photo Stage Remote: http://localhost/today/remote
• Belabox Manager: http://localhost/belabox

Check status or logs:

• Choose Status and logs from the menu.

Stop the stack:

• Choose Stop stack from the menu.

Update An Existing Install

The installer includes an explicit alpha/development refresh command:

.\stack.cmd update

On Linux or macOS, run ./stack.sh update. In the interactive command center, choose Download and update FRAME (option 12). Start or update stack (option 7) remains the offline choice: it rebuilds from the FRAME files already present and does not download anything.

The update command resolves the official GitHub main branch to an immutable commit, downloads and validates that exact source archive in a temporary staging area, then overlays FRAME-managed source files. It leaves .env, the generated docker-compose.yml, and the configured FRAME_DATA_ROOT untouched during the overlay before running the normal installer and Docker Compose reconciliation.

This is deliberately a manual alpha update path, not a stable release channel, semantic-version comparison, background updater, or full automatic rollback system. Existing installations need one final manual ZIP overlay to receive the updater-capable installer; later updates can use stack update directly.

Administrator elevation is not normally required. The current user needs write access to the FRAME installation folder and ordinary access to Docker. Keep FRAME in a user-writable location such as C:\FRAME\Syronius_FRAME instead of Program Files or another protected system folder.

On Linux/macOS, run chmod +x stack.sh once, then run ./stack.sh without arguments to open the same menu.

Optional Setup

Change the shared Portal login later:

• Open stack.cmd.
• Choose Credentials and security.
• Update the Portal username, password, or session length.

Choose where FRAME stores generated data and expose that same path to StreamerBot .ready watchers:

• Open stack.cmd.
• Choose Configure network/storage.
• Set the FRAME data folder to the storage location you want, such as E:\FRAME_DATA.

Then watch:

<FRAME_DATA_ROOT>\galleries

Include subfolders and process only files whose names end exactly in .ready.

Photo Upload defaults to 10 selected files and 10 concurrent upload sessions. Tune PHOTO_UPLOAD_MAX_FILES and PHOTO_UPLOAD_MAX_SESSIONS from Advanced setup or .env. Photo FTP passwords default to a 5-character minimum through PHOTO_FTP_MIN_PASSWORD_LENGTH. Original backup archives expire 14 days after creation by default. Owners can change Original backup retention (days) in Portal's Photo Pipeline settings, or set the installation default with PHOTO_ARCHIVE_RETENTION_DAYS; 0 keeps originals indefinitely. Galleries and trash are deleted only through owner actions. FRAME pauses new photo processing at the same disk error and minimum-free-space thresholds shown by Portal.

Connect a Belabox to FRAME:

1. Open stack.cmd or stack.sh and choose Configure network/storage.
2. Select HYBRID mode.
3. Enter the browser-facing public hostname and the public SRTLA relay hostname or IPv4 address.
4. Enable Video Relay and Stream Management and Belabox Manager.
5. Start or update the stack.
6. Open http://localhost/belabox and follow the Add device wizard while the Belabox is on the same LAN and reachable through SSH.

Belabox agent installation and repair are intentionally Hybrid-only: the agent must receive a public wss://.../belabox/control endpoint even though the initial SSH hop occurs on the LAN.

The SRTLA address is stored as PUBLIC_RELAY_HOST. It may differ from the Cloudflare/browser hostname when web traffic and SRTLA traffic use different public endpoints.

Run verification:

• Choose Validate and verify from the menu.

Native Setup App

FRAME Setup is the Electron online installer. Its runtime ships as one Windows .exe installer or Linux .AppImage; the development version also targets macOS Intel and Apple Silicon .dmg/.zip packages. Docker remains a prerequisite. It retains the FRAME setup screens, validates the selected TCP/UDP ports on the host, and downloads an official release's prebuilt images before starting the stack. Node and Python do not need to be installed. See release publishing for the required architecture-specific image manifests and the remaining Mac release checks.

For development:

npm run setup:dev

What Is Included

Start with the service README when you want to understand, operate, or customize a part of FRAME.

Area	Service
Online setup app	apps/frame-setup/
Routing	services/frame-edge/
Shared login	services/frame-auth/
Portal and status	services/frame-portal/
Hybrid tunnel notes	services/frame-tunnel/
Video relay wrapper	services/frame-ingest-video/
Stream management	services/frame-streams/
OBS overlays	services/frame-overlays/
Browser photo upload	services/frame-photo-upload/
Camera FTP upload	services/frame-photo-ftp/
Photo processing	services/frame-pipeline-photos/
Gallery	services/frame-gallery/
Photo Stage viewer and remote	services/frame-today/
Audio monitor	services/frame-audio/
Belabox Manager	services/frame-belabox-manager/

Container Breakdown

FRAME separates the platform containers that make the stack work from the service containers that provide optional tools. The installer turns service containers on and off from your selected capabilities; core containers stay in place so routing, login, status, and shared storage keep working.

flowchart TD
  operator["Browser / OBS / phone"] --> edge["frame-edge"]
  edge --> auth["frame-auth"]
  edge --> portal["frame-portal"]
  portal --> dockerProxy["frame-docker-proxy"]

  tunnel["frame-tunnel"] --> publicGateway["frame-public-gateway"]
  publicGateway --> edge

  edge --> streams["frame-streams"]
  streams --> ingestVideo["frame-ingest-video"]
  edge --> overlays["frame-overlays"]

  belabox["Belabox agent"] -->|"authenticated WSS control"| publicGateway
  edge --> belaboxManager["frame-belabox-manager"]
  streams --> belaboxManager

  edge --> audio["frame-audio"]

  edge --> photoUpload["frame-photo-upload"]
  camera["Camera FTP"] --> photoFtp["frame-photo-ftp"]
  photoUpload --> photoPipeline["frame-pipeline-photos"]
  photoFtp --> photoPipeline
  photoPipeline --> gallery["frame-gallery"]
  photoPipeline --> today["frame-today"]
  edge --> gallery
  edge --> today

Loading

Core containers

Container	When It Runs	What It Does
frame-edge	Always	Main local web entry point for FRAME pages.
frame-auth	Always	Shared login screen and protected-page session checks.
frame-portal	Always	Dashboard, navigation, status, and logs.
frame-docker-proxy	Always	Restricted Docker status access for Portal and Edge.
frame-public-gateway	Hybrid only	Filters which HTTP routes are allowed through the public tunnel.
frame-tunnel	Hybrid only	Cloudflare Tunnel connection for approved public web routes.

Service containers

Container	Enabled By	What It Does
frame-ingest-video	Video Relay	SRTLA/SRT ingest and stream statistics.
frame-streams	Video Relay or Overlays	Stream profile management and /stats routing.
frame-overlays	Overlays	OBS overlay sources and the Overlay Wizard.
frame-audio	Audio Monitor	Browser capture, audio relay, listen pages, and HLS output.
frame-belabox-manager	Belabox Manager	Authenticated device WSS control, agent installation, FRAME Remote belaUI and Mixer access, relay selection, photo controls, diagnostics, and maintenance.
frame-photo-upload	Browser Photo Upload	Protected browser/phone upload page.
frame-photo-ftp	Photo FTP Ingest	Camera FTP upload intake.
frame-pipeline-photos	Any photo feature	Photo validation, conversion, sidecars, .ready files, and archive output.
frame-gallery	Photo Gallery	Gallery pages and thumbnail cache.
frame-today	Photo Stage	Current-day viewer, remote, and dashboard controls.

The canonical spec is docs/spec/v1.1.md. Installer details live in installer/README.md.

Current TODO

The public-facing backlog for the alpha release line:

Overlay System

• Add latest-photo overlay and Photo Stage integration.

Belabox Manager

• Add BCRPT-compatible UDP and MTU relay probing beyond the current TCP RTT indicator.
• Add the planned stream-safe bitrate governor and recovery controls.

Audio Monitor

• Add relay retention controls and long-session soak tests.
• Remember recently seen browser audio devices so users do not have to refresh or reselect as often.

Installer / Platform

• Add host-port conflict preflight detection.
• Add optional Cloudflare Access policy automation.

Photo Workflow

• Build the Discord delivery outbox.
• Add camera and long-running FTP soak tests.

The fuller engineering backlog remains in docs/TODO.md.

License

FRAME is released under the MIT License. See LICENSE.