https://github.com/streamndad/streamn-scoreboard
Third-party OBS Studio plugin for tracking youth hockey scoreboard state. Writes game data to text files for use with OBS Text sources.
https://github.com/streamndad/streamn-scoreboard
c clock hockey livestreaming obs-plugin obs-studio obs-studio-plugin scoreboard scorebug scorekeeper sports streamn-dad youth-sports
Last synced: 10 days ago
JSON representation
Third-party OBS Studio plugin for tracking youth hockey scoreboard state. Writes game data to text files for use with OBS Text sources.
- Host: GitHub
- URL: https://github.com/streamndad/streamn-scoreboard
- Owner: StreamnDad
- License: gpl-2.0
- Created: 2026-02-24T04:51:06.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T15:24:42.000Z (11 days ago)
- Last Synced: 2026-04-16T15:30:43.600Z (11 days ago)
- Topics: c, clock, hockey, livestreaming, obs-plugin, obs-studio, obs-studio-plugin, scoreboard, scorebug, scorekeeper, sports, streamn-dad, youth-sports
- Language: C
- Homepage: https://streamn.dad
- Size: 458 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Streamn Scoreboard for OBS Studio
[](https://github.com/StreamnDad/streamn-scoreboard/actions/workflows/build.yml)
[](https://github.com/StreamnDad/streamn-scoreboard/actions/workflows/build.yml)
[](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html)
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.
## Features
- **7 sport presets** — hockey, basketball, soccer, football, lacrosse, rugby, and generic
- **27 text files** updated in real-time: clock, period, scores, shots, team names, penalties, penalty labels, fouls, sport, and more
- **Dock UI** with full scoreboard controls in an OBS dock panel
- **45 OBS hotkeys** for hands-free operation during broadcasts
- **Penalty tracking** with automatic countdown timers, compound penalties (2+2, 2+5, 2+10), edit/clear per slot (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.txt` companion file next to each recording; also embedded directly into Hybrid MP4/MOV recordings on OBS 32+
- **Cumulative game clock** — opt-in clock counting up from 0:00 across all periods, written to `cumulative_clock.txt`, with configurable display format (MM:SS or H:MM:SS)
- **Custom penalty labels** — combined penalty number + time in a single file per team (`home_penalty_labels.txt`, `away_penalty_labels.txt`) with configurable format template and compound penalty support
Build your own scorebug overlay using OBS Text sources pointed at the output files:
## Compatibility
- **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
## Installation
Download the latest release for your platform from the [Releases](https://github.com/StreamnDad/streamn-scoreboard/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](https://obsproject.com/kb/plugins-guide).
### macOS
1. Download `streamn-obs-scoreboard-x.y.z-macos.pkg`
2. **Right-click** (or Control-click) the `.pkg` file 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.
3. Follow the installer prompts
4. Restart OBS Studio
The installer places the plugin in `~/Library/Application Support/obs-studio/plugins/streamn-obs-scoreboard.plugin/`.
### Windows
1. Download `streamn-obs-scoreboard-x.y.z-windows-x64.zip`
2. Extract the `streamn-obs-scoreboard` folder to your OBS plugins directory:
- **Recommended:** `C:\ProgramData\obs-studio\plugins\`
- **Alternative:** Copy just the `.dll` from `bin\64bit\` to `C:\Program Files\obs-studio\obs-plugins\64bit\`
3. Restart OBS Studio
### Linux
1. Download `streamn-obs-scoreboard-x.y.z-linux-x86_64.tar.gz`
2. Extract the `streamn-obs-scoreboard` folder to your OBS plugins directory:
- **Per-user:** `~/.config/obs-studio/plugins/`
- **Alternative:** Copy just the `.so` from `bin/64bit/` to `/usr/lib/obs-plugins/`
3. Restart OBS Studio
### After installation
1. Open OBS Studio — the plugin loads automatically on startup
2. Go to **View > Docks > Streamn Scoreboard** to enable the dock panel
3. Dock it wherever you like in the OBS interface (drag the title bar to snap it into place)
### Uninstalling
**macOS:**
```bash
rm -rf ~/Library/Application\ Support/obs-studio/plugins/streamn-obs-scoreboard.plugin
```
**Windows:** Delete `streamn-obs-scoreboard.dll` from your OBS plugins folder.
**Linux:**
```bash
rm -rf ~/.config/obs-studio/plugins/streamn-obs-scoreboard
# or, if installed system-wide:
sudo rm /usr/lib/obs-plugins/streamn-obs-scoreboard.so
```
Restart OBS after uninstalling.
### Building from source
```bash
# 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 RelWithDebInfo
```
## Text Files
Set 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` |
| `home_penalty_labels.txt` | Combined penalty number + time (one per line) | `#12 1:32` |
| `away_penalty_labels.txt` | Combined penalty number + time (one per line) | `#19 0:22` |
| `home_faceoffs.txt` | Home faceoff wins | `8` |
| `away_faceoffs.txt` | Away faceoff wins | `6` |
| `cumulative_clock.txt` | Cumulative game clock (when enabled) | `32:15` |
| `period_length.txt` | Period length in seconds | `900` |
| `period_labels.txt` | Period display names | `1,2,3,OT` |
| `default_penalty_duration.txt` | Minor penalty duration (seconds) | `120` |
| `default_major_penalty_duration.txt` | Major penalty duration (seconds) | `300` |
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.
## Hotkeys
All 45 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 | Open add-penalty dialog (minor) |
| Home/Away Major Penalty Add | Open add-penalty dialog (major) |
| Home/Away 2+2 Penalty Add | Open add-penalty dialog (compound 2+2) |
| Home/Away 2+5 Penalty Add | Open add-penalty dialog (compound 2+5) |
| Home/Away Penalty Clear 1/2 | Clear or transition penalty slot (4 hotkeys) |
| Home/Away Penalty Edit 1/2 | Open edit dialog for penalty slot (4 hotkeys) |
| Home/Away Faceoff +/- | Adjust faceoff counter (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) |
## Game Event Timestamps & Recording Chapters
The plugin automatically tracks game events (goals, penalties, period changes) with timestamps relative to your stream or recording start time.
### Livestream Timestamps (YouTube Chapters)
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 Penalty: Hawks #12
0:35:10 Period 1 End
```
A `timestamps.txt` file is also written to your output directory after every event.
### Recording Chapters
Enable **"Record chapters in game file"** in Game Settings to track events in your local recordings:
- **Companion file**: A `.chapters.txt` file 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.
### Sport-Aware Score Events
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.
## Development
```bash
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 artifacts
```
### Architecture
Two-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.
## License
This project is licensed under the GNU General Public License v2.0 — see [LICENSE](LICENSE) for details. GPLv2 is required because the plugin links against libobs (GPLv2).