OBS Setup - Backups, Color-Coded Scenes, and Animated Overlays

This is the home for my OBS Studio setup across two Macs (MacBook Pro and Mac Mini): secret-scrubbed per-device backups, an import-ready color-coded scene collection, animated stream overlays rendered from code, and a small HTML previewer. It exists so I never lose a scene layout again and can rebuild either Mac from a clean install in minutes.

One command to back up. Separate downloads for overlays and transitions. No lost scenes.

Table of Contents

• Start Here
• How the Pieces Fit
• Features
• Getting Started
• Usage
  • Back up a Mac
  • Get the overlay, scene, and mask files
  • Animated overlays
  • Rounded webcam masks
• Tech Stack
• Development
  • Prerequisites
  • Setup
  • Development Scripts
  • Code Quality
• Project Structure
• License
• Contact

Start Here

If you want to…	Start here
Install and run the obs-backup command	Homebrew install and backup guide · script source · Homebrew formula
Import the ready-made scene collection	Scene and source guide · choose a file in devices/
Preview the color-coded scene collection	Run make preview, then open http://localhost:8000
Download overlays and webcam masks	Latest GitHub Release
Preview, edit, or render the Remotion overlays	remotion/README.md
Change how this repo works	Development guide · project map

How the Pieces Fit

The backup command, OBS scene setup, and Remotion overlays are related tools, but they have separate sources and release paths:

flowchart LR
    Tap["Homebrew Den tap<br/>obs-backup formula"] -->|installs| CLI["scripts/backup.sh<br/>scripts/sanitize.py"]
    CLI --> Raw["Private full backup<br/>configured location"]
    CLI --> Device["Scrubbed OBS files<br/>devices/"]
    Generator[scripts/gen_scene_collection.py] --> Device
    Device --> Preview["index.html<br/>scene preview"]
    Remotion[remotion/src + public] --> Release[release.sh]
    Release --> ScenesZip[OBS-scenes ZIP]
    Release --> StingerZip[OBS-stinger ZIP]
    Release --> MasksZip[OBS-masks ZIP]

Loading

The obs-backup Homebrew formula lives in the separate homebrew-den tap, not in this repository. It packages the two backup scripts as a terminal command; it is not an OBS plugin. The tap update workflow here opens a formula update PR after an obs-setup release.

Features

• Per-device backups. One command reads live macOS OBS settings, saves a full private ZIP, and files a scrubbed copy under the right device.
• Known secrets scrubbed. Source URLs and stream keys are wiped from the Git copy; unsupported files stay in the raw ZIP. Review the staged diff before committing. The full scenes/profiles snapshot goes to Google Drive.
• Import-ready scenes. Generated OBS scene collections for both Macs with every source color-coded, cams pre-pinned to the overlay frames, and per-scene Wolfathon widget wrappers (Mac Mini).
• Consistent color coding. One palette across scenes and sources, so a glance tells you camera vs. alerts vs. screen vs. standby.
• HTML previewer. A color-coded map of every scene that runs locally or on GitHub Pages, no build step.
• Animated overlays. Sixteen preview and release compositions: ten scene/background screens, four transparent widgets, a transparent desk foreground, and the moon-only Stinger. The former paw-swipe is kept as a separate rollback composition. See the remotion/ guide for previews, renders, and OBS setup.
• Branded stinger transition. A 4-second moon iris (Stinger) for OBS scene cuts: the overlay moon leaves its pocket, goes dark-mode steel blue on the way in, and pulls a dark night sky across the screen and back, with no paw mark, logo, or layered paw sweep. The former paw-swipe transition remains available in Remotion as a backup composition. The whoosh is embedded in the video; checks align the measured WAV peak with the covered scene-swap point and prove full-screen coverage across it.
• Organized downloads. make release renders the scenes and stinger with Remotion, encodes the transparent videos, regenerates the webcam masks, then writes four ZIPs to ~/Downloads: the all-in-one OBS-assets, plus OBS-scenes, OBS-stinger, and OBS-masks. The master ZIP separates Scenes/, Extras/, Backgrounds/, Stinger/, and Masks/, with Markdown and styled PDF guides.
• CI-built release assets. GitHub Actions lints and type-checks the Remotion project, smoke-renders and checks the stinger timing, then renders all four downloads on a macOS runner for published GitHub Releases.
• Rounded webcam masks. Ready-made alpha PNGs that clip a live cam to match each overlay's rounded frame.
• OBS JSON reference. What the files contain, how source colors are stored, and exactly which fields are secrets.

Getting Started

Full docs live in docs/:

• Backup guide - configure, back up, and restore.
• ADHD setup guide - the full scene / group / source table with the color for each item.
• Color coding - the palette and what each color means.
• Audio levels - target levels per source.
• Stinger transition setup - configure the branded scene-cut wipe from zero on each Mac.
• OBS JSON reference - file format and the color field.
• Mask install steps - apply the rounded webcam masks in OBS.
• Overlay assets and rendering - asset drop-in and render details.

Quick start:

1. Download OBS-assets-vX.Y.Z.zip from the newest GitHub Release for all assets in one archive. Separate OBS-scenes, OBS-stinger, and OBS-masks ZIPs are also available. (No release yet? Build them locally with make release.)
2. To import the scene layout, clone the repo and in OBS use Scene Collection -> Import -> devices/macbook-pro/scenes/MBP-Streaming.json (MacBook Pro) or devices/mac-mini/scenes/Mini-Streaming.json (Mac Mini).
3. After import, select your camera device and display, and paste your alert and widget URLs (they ship empty on purpose).
4. Run make preview and open http://localhost:8000 to see the color-coded layout map.

Usage

Everything runs through make:

Command	What it does
make backup	Zips live macOS OBS settings, then files a scrubbed copy into the repo for the current device.
make release	Renders and validates scenes, Stinger, and masks, then writes four dated ZIPs to ~/Downloads.
make preview	Serves the color-coded previewer at http://localhost:8000.
make gen	Regenerates both device scene collections (MacBook Pro + Mac Mini).
make masks	Regenerates the rounded webcam masks from the frame geometry.
make	Lists the available commands.

Back up a Mac

1. Install with brew tap mrdemonwolf/den && brew install obs-backup, clone this repo, then run obs-backup setup once to choose the Google Drive folder. Or run bash scripts/backup.sh setup for a local command install.
2. Run obs-backup (or make backup from this repo). It reads OBS's live macOS settings, detects the Mac by its name, writes ~/Library/CloudStorage/GoogleDrive-nathanial.henniges@mrdemonwolf.com/My Drive/Backups/OBS/<LocalHostName>/<Device>-<timestamp>.zip, and copies a scrubbed version into devices/<device>/.
3. Review git status and the staged diff before committing.

The Homebrew formula packages only the backup command and sanitizer. See the backup tool map for the source files and release flow.

Force the device when auto-detect is wrong:

DEVICE=mac-mini make backup

Get the scene, Stinger, and mask files

The easiest path is the release bundle - no local rendering needed:

1. From the Releases page, download OBS-assets-vX.Y.Z.zip for everything, or choose the three split ZIPs for only the assets you need.
2. Unzip the master archive. Scenes/, Extras/, Backgrounds/, Stinger/, and Masks/ each have their own folder. Open the root README.pdf for the formatted guide or README.md for plain text; Stinger and Masks also include their own setup guides.
3. Add the overlay videos in OBS as Media Sources. The Stinger archive contains stinger-hevc.mov, the original stinger.wav, and its own setup guide. Configure the video under Scene Transitions → + → Stinger with Transition Point 2000 ms. Its sound is embedded; do not add the WAV as a second OBS audio source.

To build the same bundle locally:

make release              # reuses the heavy ProRes masters if present
make release FORCE=--force  # re-render everything (after overlay edits)

If all renders are already present and only the ZIP step needs to be retried, run ./release.sh --package-only from the repository root.

All four archives end up in ~/Downloads/. Set OBS_RELEASE_VERSION=v0.1.4 to use a release version in each filename and enclosed folder. Published GitHub releases use their tag automatically. Set OBS_RELEASE_OUTPUT_DIR to choose another output folder. On GitHub, .github/workflows/release.yml attaches all four ZIPs to each published release; a manual workflow run uploads them as separate artifacts instead.

Animated overlays

The animated stream scenes live in remotion/ as a separate Node project:

cd remotion
npm install
npm run obs         # previewer - a button per scene
npm run dev         # Remotion Studio
npm run render:all  # render the standard set into out/

Composition ids: StartingSoon, BRB, JustChatting, JustChattingVtuber, CoworkingSolo, CoworkingDual, EndingStream, Background, CoffeeBackground, CabinBackground (full-frame MP4s), plus four panel-sized transparent overlays: Socials (720x140 badge), Countdown options (5:00 and 10:00, each 820x500 and playing once), and LoadingBarks (1080x420 status panel with wolf-tech jokes), plus the Stinger transition (4s alpha wipe, plays once), and DeskForeground (1920×1080 transparent desk with looping coffee steam). Just Chatting and Co-Working share a moonlit cabin background. The preview shows the desk; the exported desk is a separate foreground video placed above your model in OBS. See the cabin layer setup guide for source order and bounds. The preview's Coffee cabin section offers a complete cabin/desk/steam background and a cabin-only option for stacking the model and transparent desk separately. The cabin artwork was generated with imagegen; animation is implemented in Remotion (lantern flicker, dust motes, drifting valley mist, twinkling window stars, and a breathing window-moon halo, all loop-safe over the 8-second cycle). The heavy Countdown options and LoadingBarks ProRes masters are excluded from render:all; make release (or a manual npx remotion render) handles them and the stinger.

Local exports default to two Remotion workers to leave room for OBS and the preview browser. Set OBS_RENDER_CONCURRENCY=1 on memory-constrained runs; increase it only when the machine has spare resources.

Rounded webcam masks

The Just Chatting and Co-Working overlays draw rounded cam frames. To make a live cam match that rounding, masks/ has a ready-made alpha mask per cam. Apply one to the cam source with an Image Mask/Blend filter (Alpha Mask, Alpha Channel) - see masks/README.md for the size and position of each and the step-by-step. Regenerate with make masks if you retune a frame.

Tech Stack

Layer	Technology
Scripts	Python 3 (standard library) + Bash
Task runner	GNU Make
Previewer	Plain HTML, CSS, and JavaScript
Overlays	Remotion 4 (React 19), Vite previewer with @remotion/player
Transcode	ffmpeg with Apple VideoToolbox (HEVC-alpha)
CI	GitHub Actions (macOS runner) building release bundles
Hosting	GitHub Pages (serves the repo root)
Target	OBS Studio 30+ on macOS

Development

Prerequisites

• macOS with the built-in python3, bash, zip, and make.
• OBS Studio 30 or newer.
• Node.js 18+ (only for the remotion/ overlays).
• ffmpeg (only for make release HEVC-alpha transcodes).
• Pillow (pip install pillow, only for make masks).
• ReportLab (only for release PDFs; install in a Python virtual environment).

Setup

Clone the repo:

git clone git@github.com:MrDemonWolf/obs-setup.git
cd obs-setup

For local release packaging, install the PDF guide dependency in an isolated environment before running make release:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r scripts/requirements-release.txt

The backup, generator, and previewer need no package install - the scripts use macOS tools and the Python standard library. For a global backup command, run bash scripts/backup.sh setup. For the overlays:

cd remotion
npm install

Development Scripts

• scripts/gen_scene_collection.py - builds both device scene collections (MacBook Pro + Mac Mini) from the per-device layouts defined at the top of the file. Run with make gen.
• scripts/sanitize.py - copies live OBS settings into devices/<slug>/, wiping URLs, keys, and tokens. Called by the backup script.
• scripts/backup.sh - detects the device, zips a raw snapshot, runs the sanitizer. Run with obs-backup or make backup.
• release.sh - the Remotion render, audio validation, encoding, and four-ZIP packaging pipeline. Run with make release.
• scripts/render_package_guide.py - makes the styled, accessible PDF guides included alongside Markdown in each asset ZIP.
• scripts/validate_stinger.py - checks the measured WAV-to-cover timing and the rendered PCM track.
• scripts/build_master_package.py - combines split packages into the organized all-in-one archive.
• scripts/validate_release_packages.py - checks the split and master ZIP manifests and their folder contents.
• masks/gen_masks.py - regenerates the webcam masks. Run with make masks.
• In remotion/: npm run obs (previewer), npm run dev (Remotion Studio), npm run lint (eslint + tsc), npm run render:all.

Code Quality

• Standard-library Python only - no dependencies to install or update outside remotion/.
• gen_scene_collection.py runs a self-check (ABGR color math plus every scene item references a real source) before it writes anything.
• remotion/ is linted with eslint and type-checked with tsc (npm run lint).
• Python CI checks verify the checked-in WAV timing, frame delay, and package contents. A macOS job renders the Remotion stinger and confirms its audio is embedded byte-for-byte at the intended frame; release builds repeat the checks after HEVC encoding and before packaging.
• Every overlay loops seamlessly by construction - all motion is periodic over the full composition length.

Project Structure

obs-setup/
├── index.html                # color-coded previewer (also the GitHub Pages site)
├── Makefile                  # backup / release / preview / gen / masks
├── release.sh                # render + transcode + masks + zip, one command
├── assets/                   # repo art (MrDemonWolf logo)
├── .github/workflows/
│   ├── ci.yml                # Python, Remotion, and Stinger checks
│   ├── release.yml           # builds the Scenes, Stinger, and Masks downloads
│   └── update-homebrew.yml   # opens a formula update PR after a release
├── devices/
│   ├── macbook-pro/          # portable rig
│   │   ├── index.json        # which scene files exist (read by the previewer)
│   │   ├── scenes/           # scene collection JSON (secret-free)
│   │   └── profiles/         # profile settings (stream key wiped)
│   └── mac-mini/             # main home rig
│       ├── index.json        # which scene files exist (read by the previewer)
│       └── scenes/           # generated collection + sanitized live backup
├── scripts/
│   ├── README.md             # backup CLI source map and maintenance notes
│   ├── backup.sh             # installed as the `obs-backup` Homebrew command
│   ├── sanitize.py           # scrubs credentials before files enter Git
│   ├── gen_scene_collection.py
│   ├── validate_stinger.py
│   └── validate_release_packages.py
├── docs/
│   ├── adhd-setup-guide.md
│   ├── audio-levels.md
│   ├── backup-guide.md
│   ├── color-coding.md
│   ├── obs-json-reference.md
│   ├── overlay-design-system.md
│   └── stinger-setup.md
├── masks/                    # rounded webcam masks for the cam-frame overlays
│   ├── *.png                 # one alpha mask per cam (named per overlay)
│   ├── gen_masks.py          # regenerate from the frame geometry
│   └── README.md             # OBS Image Mask/Blend steps
├── remotion/                 # animated overlays (separate Node project)
│   ├── README.md             # preview, render, and OBS workflow
│   ├── ASSETS.md             # scene and asset reference
│   ├── src/                  # scenes + layers; scenes.ts is the composition list
│   ├── preview/              # macOS-style previewer (Vite + @remotion/player)
│   ├── public/               # forest, mascot, fonts, and platform marks
│   ├── render-all.mjs        # render the standard set into out/
│   └── to-hevc.sh            # transcode transparent masters to HEVC-alpha
└── tests/                    # Python tests for secret scrubbing and releases

The Homebrew formula itself lives in MrDemonWolf/homebrew-den. This repo keeps the command's source and release automation; the tap owns its Homebrew packaging and catalog.

License

Contact

Questions or ideas:

• Discord: Join my server

---

Made with love by MrDemonWolf, Inc.