Brown Dust 2 Turn Snapshot Extractor

A helper tool for taking Brown Dust 2 strategy videos and extracting the frames right before the user clicks the TURN button.

If you’ve ever tried copying a clear from YouTube, you probably know the routine: pause the video, switch back to the game, try to match the setup, switch back again, realize you missed a skill order, repeat until your patience bar is empty. I mostly play on my phone, so that constant app switching destroyed any sense of flow. This tool automates the annoying part so you can focus on actually playing and testing the strategy instead of babysitting the video.

Instead of manually scrubbing through a video, it detects when each turn happens and saves snapshots around those moments. The result is a simple visual walkthrough you can follow at your own pace while playing.

What it does

• Extracts frames from a Brown Dust 2 video.
• Detects turn changes using the Turn button in the bottom-right corner.
• Saves snapshots around each detected turn.
• Produces outputs you can use as a step-by-step reference for strategy videos.

What you get

• Turn-by-turn snapshot images.
• Clear references for party setup and skill usage.
• A slower, cleaner way to follow strategy videos without endless scrubbing.

How it works

The pipeline uses ffmpeg to sample frames and Python to detect turn boundaries. Detection focuses on the bottom-right turn button because it is the most reliable on-screen signal; the larger turn text in the middle of the screen is often missing or inconsistent in captured frames, so it is not used.

The detector crops the bottom-right region, runs OCR, applies confirmation rules, and tracks a last-seen state to decide where each turn boundary happens.

Quickstart

Use Make for the easiest run, or call the scripts directly if you want more control.

Run the full YouTube pipeline

make pipeline-youtube YOUTUBE_URL="https://www.youtube.com/watch?v=GViFTckl4fk"

Extract frames only

python3 scripts/bd2_extract_frames.py inputs/GViFTckl4fk.mp4

Detect turns only

python3 scripts/bd2_detect_turns.py --video-id GViFTckl4fk --use-cache

Workflow

You can run the project in two ways:

Option 1: Use Make

This is the simplest option. The pipeline target derives VIDEO_ID and VIDEO_PATH from YOUTUBE_URL, so you can avoid interactive prompts.

make pipeline-youtube YOUTUBE_URL="https://www.youtube.com/watch?v=GViFTckl4fk"

Option 2: Run the scripts manually

1. Download a video or place one in inputs/.
2. Extract frames with scripts/bd2_extract_frames.py.
3. Run detection with scripts/bd2_detect_turns.py.

The detection step expects the frames.csv generated by extraction and requires a --video-id, unless you provide a --frames-csv override.

Requirements

Before running the pipeline, make sure you have the following installed and configured:

• ffmpeg — required for frame extraction.
• yt-dlp — required for downloading YouTube videos.
• Python 3.10+ — required to run the scripts.
• Python packages — google-auth, pillow, and typer; rich is optional.
• Google Cloud SDK (gcloud) — required for authentication setup.
• Cloud Vision API — must be enabled in your GCP project.
• Application Default Credentials — run:

gcloud auth application-default login

Use a Google Cloud project with Vision enabled.

Environment variables

These are optional and only affect region discovery:

• GEMINI_API_KEY or GOOGLE_API_KEY — if set, Gemini is used for region discovery instead of Vision OCR.
• GEMINI_MODEL — overrides the default Gemini model.

Outputs

Detection results are written to:

outputs/<video-id-hash>/

This folder matches the extracted frames directory name, for example:

GViFTckl4fk-<hash>

Inside, you will find:

• detections.jsonl — per-frame OCR results.
• turn_boundaries.csv — detected boundary timestamps.
• found_frames/ — the boundary frame plus nearby snapshots.

Purpose

This project is built around one practical idea: the bottom-right turn button is a more dependable signal than mid-screen text for detecting turn changes in real gameplay footage. The goal is not perfect cinematic analysis; it is making strategy videos easier to use during actual play.

Good fit

This tool is especially useful if you:

• Follow YouTube clear guides.
• Want a visual reference without constantly pausing and rewinding.
• Play on mobile and hate app switching.
• Prefer snapshots over note-taking.

Not magic

This is a helper tool, not a flawless video-understanding engine. If the UI is obscured, the video is heavily edited, or the turn indicator is missing, detection quality may drop. Still, for normal strategy footage, it saves a lot of repetitive manual checking.