onair

On Air

Hermes inside your OBS. Ask for a scene and it exists. Ask what the error on screen is and the
answer appears on your stream. Mark the good moments and get the highlight reel, the YouTube
chapters and a title when you stop.

For anyone who records or streams with OBS Studio: demos, tutorials,
coding streams, gameplay, talks.

You:     make me a synthwave "starting soon" scene with a 5 minute countdown
Hermes:  Scene "Starting Soon" is ready. Want it on air?

You:     what's this error?
Hermes:  (card on stream)  Missing import: `requests` is not installed in this venv.

You:     /live stop
Hermes:  Session ended with 6 marks.
         Highlight reel (draft, 6 clips): …/reel-20261111-142210.mp4
         Chapters (paste into YouTube):
         0:00 Intro
         2:14 Null pointer in the upload handler
         5:40 Fixed

What it does

| | |
|---|---|
| Control OBS by asking | Scenes, sources, recording, streaming, replay buffer, virtual camera. "Add my webcam bottom right", "hide the chat", "switch to the camera scene". |
| Design scenes | One request makes a finished animated scene: starting soon (with countdown), be right back, ending, intermission, or any title, in six animated styles (aurora, synthwave, matrix, starfield, confetti, bounce). For anything else Hermes writes the HTML and CSS itself. |
| Scenes from anything Hermes makes | A generated image, a GIF, a video rendered by another tool (for example HyperFrames) or generated by Hermes becomes a full-screen scene; videos loop. Add a voice line from Hermes's text-to-speech and it is spoken each time the scene goes on air, with optional looping music. These use OBS's own image and media sources, not the browser source. |
| Sounds and clips | Play a spoken line, a sound effect or a short video sting once in the scene on air. It ends by itself. |
| GIFs and effects | Pop a GIF on screen for a few seconds, rain confetti, emoji or fireworks. |
| Overlay | One transparent browser source. Hermes shows short answer cards, toasts and chapter titles on it. Everything hides itself on a timer, so nothing can get stuck on screen. |
| Ask about the screen | "What's this error?" takes a screenshot through OBS, reads it with your own model, and shows a two-line answer on the overlay. |
| Marks | /mark, a button, ⌘⇧M, your phone (Telegram), or OBS's own Save Replay hotkey. Each mark saves a clip, a thumbnail, a note and the timestamp. A build or test that fails and then passes is marked automatically, as a pair. |
| Wrap-up | When you stop: a highlight reel of the marked clips with chapter cards, chapter timestamps for the full recording, and a draft title, description and show notes. Always a draft; the recording is never modified. |
| Studio in Hermes Desktop | A live preview of OBS, scene switcher, source toggles, transport buttons, the scene designer and the timeline of marks. Untick the marks you do not want and rebuild the reel. |

Install

Requires Hermes 0.23.1 or newer and OBS Studio 28 or newer (30+ recommended).

hermes plugins install https://github.com/perfect7613/hermes-onair
hermes plugins enable onair

Use the repository URL until a catalog listing is available.

No extra Python packages are installed: the plugin uses websockets and Pillow, which ship
with Hermes. Install FFmpeg (including ffprobe) and make it available on your PATH to
render highlight reels. Marks and OBS control work without FFmpeg.

Set up (about a minute)

In OBS: Tools → WebSocket Server Settings → Enable WebSocket server.
If authentication is on, click Show Connect Info, copy the password, and paste it into
Hermes Settings → Plugins → On Air → OBS password.
In Hermes: /live setup

/live setup adds the overlay to your scenes and enables the replay buffer in your OBS profile.
OBS may require a restart before it can start the newly enabled buffer; follow the returned
message, then run /live setup again.
/live doctor checks the connection, source availability, overlay installation, replay buffer,
recording folder and FFmpeg. A ready setup looks like this:

✓ OBS connection: OBS 33.0.1, obs-websocket 5.7.6
✓ Browser sources: browser source type available
✓ Overlay: in scene 'Main'
✓ Overlay drawing: cards and designed scenes appear on screen
✓ Replay buffer: running, marks will save clips
✓ Recording folder: /Users/you/Movies
✓ FFmpeg: found, highlight reels can be rendered

If a check fails, the report includes a suggested fix. To check visual output, show a card with
/live card Hello from Hermes and look at the OBS preview. When you are not recording or
streaming, doctor also flashes a two-second toast on the overlay and checks that OBS really drew
it.

Use it

Talk to Hermes normally. Some things to try:

"What scenes do I have?" · "Switch to the camera scene"
"Make a be-right-back scene in the matrix style"
"Make a scene with a slowly rotating neon grid and my channel name in the middle" (Hermes writes it)
"Generate a neon city image and make it my intermission scene"
"Make an intro scene from ~/Movies/intro-loop.mp4 and have a voice say welcome back, everyone"
"Say we're back on stream" · "Play ~/Sounds/tada.wav"
"Add ~/Pictures/logo.png to the top-left corner"
"Put this GIF on screen: https://…/party.gif"
"Start a session called Fixing the upload bug and record"
"What's this error?" · "Mark that" · "Confetti!"
"Stop the session"

Or type commands. They work from the terminal, Hermes Desktop and messaging apps:

| Command | |
|---|---|
| /live | What OBS and the session are doing |
| /live setup · /live doctor | Set up · check the setup |
| /live start [title] [--record] · /live stop | Start a session · end it and get the wrap-up |
| /mark [note] | Save this moment |
| /live scene [name] | List scenes, or switch (partial names work) |
| /live record start\|stop\|pause\|resume | Recording |
| /live stream start\|stop | Go live · end the stream |
| /live replay start\|stop\|save | Replay buffer |
| /live design <kind> [style] [title] | Create an animated scene |
| /live media <file> [scene name] | Make a scene from an image, GIF or video file |
| /live play <file> | Play a sound or a video clip once |
| /live card <text> · /live chapter <title> · /live hide | Overlay |
| /live celebrate [fireworks\|<emoji>] · /live gif <link or path> | Effects and stickers |
| /live ask <question> · /live shot | Ask about the screen · save a screenshot |
| /live reel | Rebuild the highlight reel |
| /live pause · /live resume | Stop / allow Hermes looking at the screen |

In Hermes Desktop, open On Air in the sidebar (or ⌘K → On Air: Open studio).

Marking with an OBS hotkey

In OBS Settings → Hotkeys, bind Save Replay. While a session is running, every press
becomes a mark, even when Hermes is not in focus.

Safety

Hermes asks before anything your audience would see or that cannot be resumed: going live,
ending a stream, stopping a recording, deleting a scene or source, and any scene or source
change, sound or clip while you are streaming. This uses Hermes's own approval prompt. Commands you type
yourself act immediately. You can turn the prompts off in the plugin settings.
Hermes always asks before running a page of its own in OBS's browser. A scene built from
HTML the model wrote, or a browser source pointed at a local file, runs script inside OBS with
access to local files and the network, so each one needs your approval, on air or not. The
built-in scene designs, media scenes and the overlay are the plugin's own pages and do not ask.
Raw OBS requests that change something also always ask, and the prompt shows the request's data.
This setting cannot be switched off.
Web links must be public. A browser source, a GIF link or a scene image the model picks has
to be an http or https address that resolves to a public host. Addresses on this machine or
a private network (localhost, 192.168.x.x, 169.254.169.254 and the like) and file://
links are refused. To show a local page, add it in OBS yourself.
/live stream alone never goes live. It needs start.
Screen capture is yours to control. /live pause (or the checkbox in the studio page)
stops Hermes taking screenshots. Sources Hermes may look at in the settings restricts
capture to the scenes or sources you name.
Marks are saved first. If OBS is closed, the replay buffer is off or FFmpeg is missing, the
mark is still recorded and can be cut from the recording later.

What this plugin does on your machine

Disclosure, as the catalog requires:

Network: connects to OBS's WebSocket server on your machine (127.0.0.1:4455 by default,
configurable). Nothing connects until you first use the plugin. No other network calls, no
telemetry, no update checks. Web links you give it (a GIF, a page) are loaded by OBS's browser
source, not by the plugin; before handing one over, the plugin looks up the host name (a DNS
query) to refuse private addresses.
Model calls: live_ask and /live ask send a screenshot and your question to the model
configured in Hermes, through Hermes. Capture is blocked while paused. Wrap-up generation
sends session and mark text to that model, without screenshots. Mark thumbnails and the
studio preview stay on your machine.
Credentials: the OBS password is stored by Hermes as a secret (ONAIR_OBS_PASSWORD) and
read through Hermes's secret store. The plugin does not read OBS's configuration files.
Changes to OBS: creates scenes and sources you ask for (media scenes add sources named
On Air Image/Video/Title/Voice/Music · <scene>; one-shots reuse On Air Sound and
On Air Clip), an On Air Overlay browser source, and, on /live setup, enables the replay buffer in your current OBS profile.
Files written: only under <HERMES_HOME>/plugin-data/onair/: a SQLite database of
sessions and marks, thumbnails, screenshots, overlay and scene HTML, copies of the media
files you build scenes from, highlight reels and wrapup.md. Replay clips and recordings are written by OBS to its own folder; the plugin
reads them and never modifies or deletes them.
Subprocesses: runs ffmpeg and ffprobe from your PATH with fixed argument lists (no
shell) and a minimal environment (PATH, HOME, LANG) to render highlight reels.
Background work: while a session is running, one connection to OBS stays open and
reconnects if OBS restarts. It closes when the session stops or the plugin unloads.
Hooks: post_tool_call reads the exit code of terminal commands during a session, for
automatic marks. pre_tool_call asks for approval on the plugin's own public-facing tools.

Settings

Hermes Desktop → Settings → Plugins → On Air, or hermes config:

| Setting | Default | |
|---|---|---|
| OBS password | | From OBS → Tools → WebSocket Server Settings |
| OBS host / port | 127.0.0.1 / 4455 | |
| Ask before public actions | on | The approval prompts described above |
| Automatic marks | on | Mark failing and then passing build/test commands |
| Clip length | 20 s | How much of each mark goes into the reel |
| Replay buffer length | 30 s | Used when setup switches the buffer on |
| Sources Hermes may look at | scene on air | Restrict screenshots to named scenes or sources |
| Accent colour | #ffb000 | Overlay and chapter cards |

Tools

Twelve tools, in the onair toolset: live_status, live_scene, live_source,
live_design_scene, live_output, live_overlay, live_screenshot, live_ask, live_mark,
live_session, live_reel, and live_obs_request (any obs-websocket request, for filters,
transitions, audio and whatever else you need). A bundled skill, onair:director, teaches the
agent when to mark and how to write cards.

Not included, on purpose

Viewer chat and co-hosting. Reading and answering live chat is a different product with
different risks.
A video editor. The reel is a first cut: clips and chapter cards, joined. For real editing,
take the clips into an editor; the catalog has plugins for that.
Starting OBS for you, and changing your stream key or service.

Limitations

Media scenes and one-shot sounds take files on your computer, not web links. Sounds go to
the recording and the stream; to hear them yourself, set the source's Audio Monitoring in
OBS's Advanced Audio Properties.
The overlay is updated through obs-browser's event channel, which needs OBS's bundled browser
source (included in the official builds for macOS, Windows and Linux).
OBS's browser engine can stop drawing during a long OBS session (seen on macOS with OBS 33):
browser sources are still listed, but cards and designed scenes are blank. /live doctor
detects this ("Overlay drawing") and restarting OBS fixes it. Media scenes and sounds use
OBS's own image and media sources and are not affected.
Chapter markers inside the recording file need OBS 30.2+ and the Hybrid MP4/MOV format. The
chapter list in the wrap-up works with any format.
Enabling the replay buffer from /live setup is done through the OBS profile and may need
outputs to be idle; if OBS refuses, the doctor says where to tick the box.
Windows and Linux use the same protocol and the plugin picks platform-specific source types
at run time, but they are not yet tested by hand.

Tested on macOS

Verified with OBS Studio 33.0.1 and obs-websocket 5.7.6:

Scene and source control, text and colour sources, previews and screenshots.
Media scenes from a video (looping, with title and a voice line that plays once) and from a GIF;
one-shot sounds and clips that end by themselves. Voice restarts on scene re-entry, looping
music stops off-scene, and speech was verified in the recorded audio.
HTTPS browser sources, built-in and custom HTML scenes, restyling a scene, overlay cards,
stickers and effects, in a freshly started OBS; and the doctor's "Overlay drawing" check.
Recording start/stop and pause/resume, replay-buffer clips, marks and thumbnails.
A highlight reel rendered from real OBS footage, with audio/video streams and chapter cards.
A real Hermes chat created a video scene with title, voiceover and music from prepared local
files and listed the resulting sources. Generation through a third-party voice API is not
part of that test.

The automated suite passes all 132 tests, including real FFmpeg rendering and regressions for
media replacement, scene-name collisions, source ordering, file persistence, live approvals, private-address refusal and the always-ask rules. Hermes plugin doctor
and validation also pass, registering all 12 tools and both hooks.

Development

git clone https://github.com/perfect7613/hermes-onair && cd hermes-onair
ln -s "$PWD" ~/.hermes/plugins/onair          # live-linked: Desktop hot-reloads desktop/plugin.js
python -m unittest discover -s tests -t .      # needs websockets and Pillow; ffmpeg for the render test
hermes plugins doctor . --ci
hermes plugins validate . --install-deps

After changing Python tools or their parameters in a linked plugin, restart the running Hermes
gateway with hermes gateway restart --detach and start a new chat. Desktop JavaScript hot reload
does not refresh the gateway's Python tool schemas. The restart command checks for active work;
allow ongoing sessions to finish before restarting.

The tests run the whole plugin (application, tools, commands, Desktop RPC) against an in-memory
OBS that speaks the real protocol, and render a real reel with FFmpeg. See
docs/architecture.md for how the code is laid out.

Licence

MIT

README from the reviewed commit 34f2750; it updates when the author re-pins.

About