OBS Studio plugin that tracks live game scoreboard state and writes it to individual text files. Supports hockey, basketball, soccer, football, lacrosse, rugby, and a generic preset. Users compose their scoreboard overlay in OBS using standard Text (GDI+/FreeType) sources pointed at these files.
- 7 sport presets — hockey, basketball, soccer, football, lacrosse, rugby, and generic
- 17 text files updated in real-time: clock, period, scores, shots, team names, penalties, fouls, and sport
- Dock UI with full scoreboard controls in an OBS dock panel
- 31 OBS hotkeys for hands-free operation during broadcasts
- Penalty tracking with automatic countdown timers (hockey, lacrosse, rugby)
- Foul/card counters for basketball, soccer, and football
- reeln-cli integration for automated highlight generation
- Game event timestamps — YouTube chapter markers copied to clipboard for livestream descriptions
- Recording chapter markers — game events written to a
.chapters.txtcompanion file next to each recording; also embedded directly into Hybrid MP4/MOV recordings on OBS 32+
Build your own scorebug overlay using OBS Text sources pointed at the output files:
- OBS Studio 30.0+ (Qt5/Qt6); embedded recording chapters require OBS 32+ with Hybrid MP4 output
- macOS (Apple Silicon and Intel)
- Windows (x64)
- Linux (x86_64)
- C11 / C++17
Download the latest release for your platform from the Releases page. Each download contains a single plugin file (.so, .dll, or .pkg) that you copy into your OBS plugins folder.
For general information about installing OBS plugins, see the OBS Plugins Guide.
- Download
streamn-obs-scoreboard-x.y.z-macos.pkg - Right-click (or Control-click) the
.pkgfile and choose Open — this is required because the package is not yet notarized with Apple. If you double-click instead, macOS will block it. You can also go to System Settings > Privacy & Security and click Open Anyway after a blocked attempt. - Follow the installer prompts
- Restart OBS Studio
The installer places the plugin in ~/Library/Application Support/obs-studio/plugins/streamn-obs-scoreboard.plugin/.
- Download
streamn-obs-scoreboard-x.y.z-windows-x64.zip - Extract the
streamn-obs-scoreboardfolder to your OBS plugins directory:- Recommended:
C:\ProgramData\obs-studio\plugins\ - Alternative: Copy just the
.dllfrombin\64bit\toC:\Program Files\obs-studio\obs-plugins\64bit\
- Recommended:
- Restart OBS Studio
- Download
streamn-obs-scoreboard-x.y.z-linux-x86_64.tar.gz - Extract the
streamn-obs-scoreboardfolder to your OBS plugins directory:- Per-user:
~/.config/obs-studio/plugins/ - Alternative: Copy just the
.sofrombin/64bit/to/usr/lib/obs-plugins/
- Per-user:
- Restart OBS Studio
- Open OBS Studio — the plugin loads automatically on startup
- Go to View > Docks > Streamn Scoreboard to enable the dock panel
- Dock it wherever you like in the OBS interface (drag the title bar to snap it into place)
macOS:
rm -rf ~/Library/Application\ Support/obs-studio/plugins/streamn-obs-scoreboard.pluginWindows: Delete streamn-obs-scoreboard.dll from your OBS plugins folder.
Linux:
rm -rf ~/.config/obs-studio/plugins/streamn-obs-scoreboard
# or, if installed system-wide:
sudo rm /usr/lib/obs-plugins/streamn-obs-scoreboard.soRestart OBS after uninstalling.
# macOS
make setup # Install prerequisites (requires Homebrew)
make find-obs-dev-paths # Discover local OBS header/lib paths
make dev OBS_INCLUDE_DIR=/path/to/obs/include OBS_LIBRARY=/path/to/libobs
make install
# Linux
sudo apt install libobs-dev qtbase5-dev libsimde-dev ninja-build
cmake --preset linux
cmake --build build
ctest --test-dir build
# Windows (requires Visual Studio 2022, Qt5, OBS SDK)
cmake --preset windows -DOBS_INCLUDE_DIR=... -DOBS_LIBRARY=... -DCMAKE_PREFIX_PATH=...
cmake --build build --config RelWithDebInfo
ctest --test-dir build -C RelWithDebInfoSet an output directory in the dock settings. The plugin writes these files on every tick (~100ms):
| File | Content | Example |
|---|---|---|
clock.txt |
Game clock | 12:45 |
period.txt |
Current period | 2 / OT |
home_name.txt |
Home team name | Eagles |
away_name.txt |
Away team name | Hawks |
home_score.txt |
Home score | 3 |
away_score.txt |
Away score | 1 |
home_shots.txt |
Home shots on goal | 18 |
away_shots.txt |
Away shots on goal | 12 |
home_penalty_numbers.txt |
Home penalty player numbers | #12 #7 |
home_penalty_times.txt |
Home penalty times remaining | 1:32 0:45 |
away_penalty_numbers.txt |
Away penalty player numbers | #19 |
away_penalty_times.txt |
Away penalty times remaining | 0:22 |
home_fouls.txt |
Home fouls/yellow cards/flags | 3 |
away_fouls.txt |
Away fouls/yellow cards/flags | 2 |
home_fouls2.txt |
Home second counter (e.g. red cards) | 0 |
away_fouls2.txt |
Away second counter (e.g. red cards) | 1 |
sport.txt |
Active sport preset | hockey |
Not all files are relevant for every sport — shots are only tracked for hockey and lacrosse, penalties for hockey/lacrosse/rugby, and fouls for basketball/soccer/football. Files for inactive features still exist but won't change.
All 31 hotkeys are prefixed with "Streamn:" in OBS Settings > Hotkeys:
| Hotkey | Action |
|---|---|
| Clock Start/Stop | Toggle game clock |
| Clock Reset | Reset clock to period length |
| Clock +1 Min / -1 Min | Adjust clock by 1 minute |
| Clock +1 Sec / -1 Sec | Adjust clock by 1 second |
| Home/Away Goal +/- | Adjust score (4 hotkeys) |
| Home/Away Shot +/- | Adjust shots (4 hotkeys) |
| Period Advance / Rewind | Change period |
| Home/Away Penalty Add | Add penalty with default duration |
| Home/Away Penalty Clear 1/2 | Clear penalty slot (4 hotkeys) |
| Generate Highlights | Trigger reeln-cli highlight generation |
| Home/Away Foul +/- | Adjust foul counter (4 hotkeys) |
| Home/Away Foul2 +/- | Adjust second foul counter (4 hotkeys) |
The plugin automatically tracks game events (goals, penalties, period changes) with timestamps relative to your stream or recording start time.
When OBS is streaming, events are logged with stream-relative timestamps. Click Copy Timestamps to Clipboard in the dock to paste them into your YouTube video description as chapter markers:
0:00:00 Stream Start
0:12:34 Period 1 Start
0:15:22 Goal: Eagles (1-0)
0:23:45 Power Play: Hawks #12
0:35:10 Period 1 End
A timestamps.txt file is also written to your output directory after every event.
Enable "Record chapters in game file" in Game Settings to track events in your local recordings:
- Companion file: A
.chapters.txtfile is written next to every recording (e.g.,2026-03-12_15-30-00.mp4.chapters.txt). This works with any recording format (MKV, MP4, MOV) and can be used by reeln-cli or with ffmpeg to inject chapters. - Embedded MP4 chapters: On OBS 32+, chapters are also embedded directly into the recording file — but only when using the Hybrid MP4 recording format. Standard (FFmpeg) output and MKV do not support embedded chapters. To enable: OBS Settings > Output > Recording > Recording Format > Hybrid MP4.
Recording chapters are tracked independently of streaming, so they work when you're only recording locally without a livestream.
Score events use sport-specific labels:
| Sport | Label | Logged by default |
|---|---|---|
| Hockey | Goal | Yes |
| Soccer | Goal | Yes |
| Lacrosse | Goal | Yes |
| Rugby | Try | Yes |
| Basketball | Score | No (too frequent) |
| Football | Score | No (too frequent) |
Period, penalty, and game-end events are always logged regardless of sport.
make dev # configure + build + test (full cycle)
make coverage # enforce 100% line coverage on scoreboard-core
make release # build macOS .pkg installer
make clean # remove build artifactsTwo-layer design separating testable core logic from OBS-dependent code:
- scoreboard-core (C static library) — pure game state management, file output, no OBS dependencies
- OBS module (C/C++ shared library) — dock UI, hotkeys, OBS integration
Tests are plain C using assert() with 100% line coverage on the core library.
This project is licensed under the GNU General Public License v2.0 — see LICENSE for details. GPLv2 is required because the plugin links against libobs (GPLv2).
