Headless and unattended OBS: what already works in the fork

[vpacher]

Why headless. My use case is remote pair programming. IDE, OBS, a video meeting and compile runs all on one laptop means load, heat and fan noise, even on a well-specced machine. So OBS moved to a headless box: no monitor, started and stopped by automation, controlled over obs-websocket (Companion), output over NDI. Judging by obsproject/obs-studio#12650 (64 comments before it was locked), quite a few people run OBS like this: streaming boxes, kiosks, rack machines, CI.

Headless OBS has one simple requirement: it has to come back on its own, with no dialog that nobody can click and no state that is lost because nobody pressed save.

What the fork already fixes for this:

• frontend: Restore --disable-shutdown-check #810 (bug: frontend: unattended start blocks forever on the "Crash Detected" dialog after an unclean shutdown (upstream #12650) #809): --disable-shutdown-check is back. After an unclean stop (power loss, OOM killer, a hard stop of the VM or container), OBS starts without the hidden "Crash Detected" prompt, and the unclean shutdown is logged as a warning on line 1. A normal stop request (SIGTERM, SIGINT, SIGQUIT) already exits and saves cleanly in the fork.
• frontend: Migrate pre-31 settings that lack LastVersion #816 (bug: frontend: a pre-31 config without LastVersion is not migrated; the hidden first-run wizard disables all outputs #815): settings from before 31.0 without LastVersion are migrated. Before this, the first-run wizard opened hidden on a headless display and disabled all outputs.
• frontend: Log output starts refused while outputs are disabled #818 (bug: frontend: a start refused while outputs are disabled leaves no trace (no log, no event) #817): a start of streaming, recording, the replay buffer or the virtual camera that is refused while outputs are disabled is now logged. Before this, obs-websocket replied "success" and nothing happened, without a trace.
• frontend: Build with Qt 6.8 (QString::arg) #1017 (bug: frontend: does not build with Qt 6.8 (Debian 13): QString::arg(std::string_view) #1015): the frontend builds against distribution Qt 6.8 (Debian 13), which is what many headless boxes run.

In progress:

• requesthandler: Save the collection after changes obs-websocket#12 + obs-websocket: Save the scene collection after changes #812 (bug: obs-websocket: requests that change the scene collection do not save it, so a crash or hard stop loses them #811): websocket requests that change the scene collection (volume, mute, input settings, transforms, ...) now save it. Before this, every change made from Companion or a script was only in memory until a clean exit, and a crash or hard stop lost it.

Next on my list: the ALSA input opens USB audio interfaces at 16 bit even when they offer 24 bit (it tries S16_LE first). Small fix, measurable difference.

This lines up nicely with #96 (an agent-friendly CLI / MCP): a machine that drives OBS needs the same guarantees as a box that nobody looks at. No dialogs, every action leaves a trace, and state survives.

All of these run in production on a Debian 13 LXC with an RTX 3060 (NVENC, NDI via DistroAV, Companion over the websocket), and each one was verified end to end on that box.

So, if you came here from #12650: the flag is back, your old settings survive the update, and saving websocket changes is on its way. Pull up a chair. 🙂

@zackees, I'll leave it to you whether and how to tell the headless crowd. The upstream thread is locked, so this Discussion is the place to point people to.

[zackees]

We need a readme section pointing to a features ledger and updates to agent documentation on how to update.

We also need to scan all PRs published in this fork for backfilling the new features.

We can organize it and make it look stunning later. Right now these awesome features are announced via PR, and then get crowded out and eventually disappear, like tears in rain.

Ledger is > selective announcement and are also non exclusive to it.

[zackees]

promoting to issue

#1250