Scaffold local OBS streaming bridge

This commit is contained in:
Meta Vens 2026-05-18 10:56:01 +01:00
commit beac84ae23
18 changed files with 1159 additions and 0 deletions

48
docs/architecture.md Normal file
View file

@ -0,0 +1,48 @@
# Architecture
## Objective
Make one local Windows computer available as OBS sources on another computer, with sender-side NVENC video encoding and independently mixable audio sources.
## Current Mechanism
The repo owns configuration and scripts. FFmpeg owns capture, encoding, and SRT transport. OBS owns scene composition.
Inputs become outputs like this:
1. `config/localcast.json` declares the receiver IP, SRT ports, video capture shape, and named audio devices.
2. `scripts/sender-discover.ps1` asks FFmpeg what Windows capture devices and encoders exist.
3. `scripts/sender-start.ps1` validates the config and launches one FFmpeg process per source.
4. The video process captures the desktop and encodes H.264 using `h264_nvenc`.
5. Each audio process captures one DirectShow audio device and encodes Opus.
6. Each process sends MPEG-TS over SRT to a stable receiver URL.
7. OBS adds each URL as a Media Source.
## Invariants
- Video encoding happens on the sender.
- OBS receives ordinary media-source URLs; it does not need a plugin for v1.
- Audio remains separately mixable in OBS.
- Ports are stable and derived from one base port plus explicit offsets.
- Secrets, if used, stay in local config and are not committed.
## Intended Change
The first implementation creates the repeatable operating spine. Future native code is only justified if the SRT Media Source path fails one of the invariants above.
## Cut Line
The following do not currently earn their keep:
- OBS fork
- OBS plugin
- custom receiver daemon
- synchronized multi-track container that hides audio sources from OBS mixing
- homegrown capture stack over Windows APIs
## Source Notes
- OBS SRT guide: `https://obsproject.com/kb/srt-protocol-streaming-guide`
- FFmpeg devices docs: `https://www.ffmpeg.org/ffmpeg-devices.html`
- FFmpeg protocols docs: `https://ffmpeg.org/ffmpeg-protocols.html`

View file

@ -0,0 +1,26 @@
# Implementation Plan
## Implemented
- Repo-local persistence machinery.
- First architecture map.
- Example config for one video source plus two audio sources.
- Sender device discovery script.
- Sender launch script with dry-run mode and per-source FFmpeg commands.
- OBS receiver setup notes.
## Temporary
- Audio and video are separate SRT endpoints. This preserves OBS mixing authority but may need latency tuning.
- Audio defaults to AAC inside MPEG-TS for compatibility; test Opus later only if there is a concrete reason.
- Desktop capture uses `gdigrab` first because it is broadly available. `ddagrab` is a candidate once the installed FFmpeg build is confirmed.
- The scripts assume Windows sender and OBS receiver on the same LAN.
## Next
1. Run `scripts/sender-discover.ps1` on the sender and record the actual device names.
2. Smoke-test one video stream into OBS.
3. Smoke-test each audio source independently.
4. Tune SRT latency and FFmpeg buffering for the local network.
5. Decide whether a small OBS scene/source generator is worth adding.
6. Reconsider plugin/fork only if standard OBS Media Source cannot preserve the required behavior.

View file

@ -0,0 +1,42 @@
# OBS Receiver Setup
Add each stream as a separate OBS Media Source.
For every source:
1. Add `Sources > + > Media Source`.
2. Uncheck `Local File`.
3. Set `Input` to the relevant SRT URL.
4. Set `Input Format` to `mpegts`.
5. Enable `Restart playback when source becomes active`.
## Default URLs
These match `config/localcast.example.json` when the receiver is listening locally:
```text
video: srt://0.0.0.0:5100?mode=listener&latency=120000&timeout=5000000
desktop: srt://0.0.0.0:5101?mode=listener&latency=120000&timeout=5000000
voice: srt://0.0.0.0:5102?mode=listener&latency=120000&timeout=5000000
```
If using a passphrase, append:
```text
&passphrase=YOUR_SECRET&pbkeylen=16
```
OBS should be open before the sender starts if OBS is the SRT listener. If a source gets wedged, deactivate and reactivate the Media Source before changing ports; port churn is a symptom, not a configuration strategy.
## Source Layout
Recommended OBS scene:
```text
Husband PC - Video Media Source, monitor off
Husband PC - Desktop Media Source, audio only, monitor as needed
Husband PC - Voice Media Source, audio only, monitor as needed
```
Mute the video source if it carries no audio. Keep audio filters on the separate audio sources.