Skip to content

Development

Everything in the Docs and the Tutorials works from CroStream's own screens. This section is for when you want to go further with code: write your own overlay elements, restyle any element with CSS, run CroStream on a machine with no screen, drive it from scripts and Stream Deck, or edit its settings by hand. It's written for people comfortable with HTML, CSS, JavaScript, JSON and a terminal, and it documents everything precisely enough that you never need to read CroStream's source.

Customizing overlays

  • Write your own widgets

    Overlay elements in HTML, CSS and JavaScript, with live data, settings and the sandbox they run in. A code editor that checks your code as you type, a full tutorial and a cookbook of working widgets.

    Widgets

  • Custom CSS

    Restyle any element through its named parts and CSS variables, or the whole overlay at once.

    Custom CSS

  • Overlay data reference

    Every live data key (chat, events, counters, timers, leaderboards, hype train, polls) with its exact JSON shape and when it updates.

    Overlay data

Running headless

  • Browser mode

    crostream serve: the full UI in any browser, its options, and how to keep it safe on your network.

    Browser mode

  • Headless setup

    A streaming PC or server with no screen, step by step: login over SSH, OBS, running as a service, and reverse proxies.

    Headless setup

Reference

  • HTTP API

    Run macros and actions, read the activity log and watch live events from scripts, Stream Deck or Companion.

    HTTP API

  • The settings file

    config.json section by section, and how to edit it by hand safely.

    The settings file

  • Command line

    crostream serve and crostreamctl: every command, option and exit code.

    Command line

At a glance

Names in code. The app says Trigger, Macro and Event; the settings file and the API use CroStream's internal names:

In the app In the settings file and API
Macro sequence (sequences, seq-…, RunSequence)
Trigger binding (bindings, bind-…, TestBinding)
A trigger's event source
Queue queue (queue-…)
Overlay element node (element-…)
Custom widget widget (widget-…)

Addresses.

Address What
http://127.0.0.1:62689 The desktop app's local server: the Twitch login and the overlay pages OBS loads (/overlay/<id>). This computer only.
http://<listen address> Browser mode: the UI, the HTTP API and overlay pages. Default 127.0.0.1:8080.

Files. Your setup lives in the config folder (config.json, overlays/, widgets/, backups/, secrets/) and what CroStream records in the state folder (history.db, viewers.db, library/). See Where files are kept and Other files.

Code you paste is code you run

Custom widgets run in a sandbox that can't reach your accounts, and custom CSS can't load anything from the internet, so pasting a widget or a stylesheet is safe. Scripts that call the HTTP API have no such limits: they can do anything you can. Only run ones you understand.