Merge pull request #6 from andytaylor-smg/code-quality

README.md

@@ -4,14 +4,20 @@ Automatically detect and extract live plays from college football game videos us
 
 ## Project Status
 
-**Status:** V3 Baseline - Production-ready with special play detection
+**Status:** V4 - Production-ready with template-based detection
+
+### Key Features
+- ✅ **Template-based clock reading** - 34x faster than OCR (~0.3ms vs ~49ms per frame)
+- ✅ **Streaming processing** - Read frame → process immediately (no intermediate storage)
+- ✅ **Parallel processing** - ~26% speedup with 2 workers
+- ✅ **Threaded video I/O** - Background reading overlaps with processing
 
 ### Detection Capabilities
 - ✅ **Normal plays** - Regular offensive plays (149+ per game)
 - ✅ **Extra points (XPs)** - 100% detection rate
 - ✅ **Field goals (FGs)** - 50% detection rate
 - ✅ **Punts** - 90% detection rate
-- ✅ **Timeout tracking** - Team timeout detection
+- ✅ **Timeout tracking** - Team timeout detection via indicator analysis
 - ⚠️ **Opening kickoffs** - Not yet supported
 
 ## Overview
@@ -34,196 +40,231 @@ python main.py --video "full_videos/OSU vs Tenn 12.21.24.mkv"
 
 # Testing mode (uses 10-minute segment at 38:40-48:40)
 python main.py --testing
+
+# Parallel processing (faster)
+python main.py --testing --workers 2
 ```
 
 ## Project Structure
 
 ```
 cfb40/
-├── main.py                           # Minimal pipeline entry point
+├── main.py                           # Pipeline entry point
 ├── src/
-│   ├── ui/                           # User interface modules
-│   │   ├── models.py                 # Pydantic models (BBox, SelectionState, etc.)
-│   │   ├── selector.py               # RegionSelector class for mouse callbacks
-│   │   ├── sessions.py               # Interactive selection session classes
-│   │   ├── api.py                    # Public API functions
+│   ├── config/                       # Configuration management
+│   │   ├── models.py                 # SessionConfig Pydantic model
+│   │   ├── session.py                # Save/load config, project constants
 │   │   └── __init__.py
-│   ├── video/                        # Video processing modules
-│   │   ├── ffmpeg_ops.py             # FFmpeg clip extraction/concatenation
-│   │   ├── frame_extractor.py        # Frame extraction utilities
+│   ├── detection/                    # Per-frame detection components
+│   │   ├── models.py                 # ScorebugDetection, TimeoutReading models
+│   │   ├── scorebug.py               # DetectScoreBug (template matching)
+│   │   ├── timeouts.py               # DetectTimeouts (oval brightness analysis)
 │   │   └── __init__.py
-│   ├── config/                       # Configuration management
-│   │   ├── session.py                # SessionConfig, project constants
+│   ├── pipeline/                     # Video processing orchestration
+│   │   ├── models.py                 # DetectionConfig, DetectionResult, etc.
+│   │   ├── orchestrator.py           # run_extraction(), print_results_summary()
+│   │   ├── parallel.py               # Parallel chunk processing
+│   │   ├── play_extractor.py         # PlayExtractor main pipeline class
+│   │   ├── template_builder_pass.py  # Pass 0: OCR-based template building
+│   │   └── __init__.py
+│   ├── readers/                      # Value reading from detected regions
+│   │   ├── models.py                 # PlayClockReading, TemplateMatchResult
+│   │   ├── playclock.py              # ReadPlayClock (template matching)
+│   │   └── __init__.py
+│   ├── setup/                        # One-time preparation before processing
+│   │   ├── models.py                 # DigitSample, DigitTemplate, PlayClockRegionConfig
+│   │   ├── coverage.py               # Template coverage calculation utilities
+│   │   ├── playclock_region.py       # PlayClockRegionExtractor
+│   │   ├── template_builder.py       # DigitTemplateBuilder
+│   │   ├── template_library.py       # DigitTemplateLibrary
+│   │   └── __init__.py
+│   ├── tracking/                     # Cross-frame state management
+│   │   ├── models.py                 # PlayEvent, PlayState, PlayTrackingState
+│   │   ├── play_state.py             # TrackPlayState (main state machine facade)
+│   │   ├── play_lifecycle.py         # PlayLifecycle (start/end/reset plays)
+│   │   ├── play_identification_checks.py  # Clock analysis for play boundaries
+│   │   ├── state_handlers.py         # State machine transition handlers
+│   │   ├── play_merger.py            # PlayMerger (deduplicate/filter plays)
+│   │   ├── clock_reset_identifier.py # Post-hoc 40→25 transition analysis
 │   │   └── __init__.py
-│   ├── detectors/                    # Detection components
-│   │   ├── scorebug_detector.py      # Scorebug detection via template matching
-│   │   ├── play_clock_reader.py      # Play clock OCR using EasyOCR
-│   │   ├── play_state_machine.py     # Play boundary detection logic
-│   │   ├── timeout_tracker.py        # Timeout indicator tracking
+│   ├── ui/                           # Interactive region selection
+│   │   ├── models.py                 # BBox, SelectionState, SelectionViewConfig
+│   │   ├── selector.py               # RegionSelector (mouse callbacks)
+│   │   ├── sessions.py               # Selection session classes
+│   │   ├── api.py                    # Public API functions
+│   │   └── __init__.py
+│   ├── utils/                        # Shared utilities
+│   │   ├── color.py                  # Red digit detection, color normalization
+│   │   ├── frame_result.py           # Standardized frame result factory
+│   │   ├── regions.py                # Digit region extraction utilities
 │   │   └── __init__.py
-│   └── pipeline/                     # Pipeline orchestration
-│       ├── play_detector.py          # Detection pipeline
-│       ├── orchestrator.py           # High-level pipeline orchestration
+│   └── video/                        # Video I/O and FFmpeg operations
+│       ├── ffmpeg_ops.py             # Clip extraction/concatenation
+│       ├── frame_extractor.py        # Frame extraction utilities
+│       ├── frame_reader.py           # ThreadedFrameReader
 │       └── __init__.py
-├── scripts/                          # Active utility scripts
-│   ├── configure_timeout_tracker.py  # Interactive timeout region selection
-│   ├── cache_detections.py           # Cache OCR results for fast iteration
-│   ├── replay_state_machine.py       # Replay cached detections
-│   ├── diagnose_special_plays.py     # Analyze special play detection
-│   ├── diagnose_red_play_clock.py    # Debug red play clock OCR
-│   └── debug_red_preprocessing.py    # Debug red digit preprocessing
-├── scripts/archive/                  # Archived/legacy scripts
-│   ├── identify_play_clock_region.py # Interactive tool to locate play clock
-│   ├── detect_plays.py               # CLI for running detection
-│   ├── visualize_detections.py       # Visualize and validate results
-│   ├── test_play_clock_reader.py     # Test OCR accuracy
-│   ├── test_state_machine.py         # Test state machine logic
-│   ├── diagnose_play_clock.py        # Debug play clock detection
-│   ├── diagnose_missed_plays.py      # Analyze missed play detection
-│   ├── diagnose_scorebug_threshold.py # Debug scorebug detection
-│   ├── diagnose_confidence_distribution.py # Analyze confidence distribution
-│   ├── benchmark_ffmpeg_concat.py    # Benchmark clip concatenation methods
-│   ├── benchmark_ocr.py              # Benchmark OCR performance
-│   └── benchmark_ocr_batching.py     # Benchmark OCR batching strategies
+├── scripts/                          # Utility scripts
+│   ├── test_full_segment.py          # Test on video segment
+│   ├── test_full_video_evaluation.py # Full video evaluation
+│   ├── test_template_accuracy.py     # Template matching accuracy test
+│   └── archive/                      # Archived scripts (v2, v3)
 ├── data/
-│   ├── config/
-│   │   └── play_clock_region.json    # Play clock location config
+│   ├── config/                       # Region configuration files
 │   └── templates/                    # Scorebug template images
 ├── output/                           # Detection results and clips
 │   ├── clips/                        # Generated video clips
-│   ├── benchmarks/                   # Benchmark results (v1, v2, v3 baselines)
+│   ├── benchmarks/                   # Benchmark results (v1-v4 baselines)
 │   ├── cache/                        # Detection cache files
-│   └── archive/                      # Historical runs
+│   └── debug/                        # Debug output (digit templates, etc.)
 ├── full_videos/                      # Source video files (gitignored)
 ├── docs/                             # Documentation
-│   ├── v3_baseline_analysis.md       # V3 special play detection analysis
-│   ├── special_plays_ground_truth.md # Ground truth for XPs/FGs/punts
-│   ├── ffmpeg_clip_methods.md
-│   ├── missed_plays_analysis.md
-│   └── play_detection_improvements.md
-├── tests/
-│   └── test_data/
-│       └── ground_truth_plays.json   # Ground truth for validation
+│   ├── ocr_to_template_migration.md  # Template matching migration details
+│   ├── ocr_benchmark.md              # OCR vs template performance comparison
+│   ├── video_processing_speedup.md   # Streaming/parallel optimization docs
+│   └── ...
 ├── pyproject.toml
 ├── AGENTS.md                         # AI assistant guidelines
 └── README.md
 ```
 
-## Setup
+## Module Architecture
 
-### Prerequisites
-- Python 3.13+
-- ffmpeg installed (`brew install ffmpeg` on macOS)
-- Virtual environment (`.venv`)
+The codebase is organized into specialized modules under `src/`:
 
-### Installation
+### `src/config/` - Configuration Management
 
-1. Clone the repository
+Session configuration and project constants for the detection pipeline.
 
-2. Create and activate virtual environment:
-```bash
-python -m venv .venv
-source .venv/bin/activate
-```
+| Component | Description |
+|-----------|-------------|
+| `SessionConfig` | Pydantic model with video path, region coordinates, generated paths |
+| `save_session_config()` | Saves config JSON, template image, playclock/timeout configs |
+| `load_session_config()` | Loads session from JSON file |
+| Project constants | `PROJECT_ROOT`, `OUTPUT_DIR`, test segment bounds |
 
-3. Install dependencies:
-```bash
-pip install -e .
-# Or manually:
-pip install opencv-python numpy pillow easyocr torch
-```
+### `src/detection/` - Per-Frame Detection
 
-## Usage
+Components that process individual video frames to detect visual elements.
 
-### Main Pipeline
+| Component | Description |
+|-----------|-------------|
+| `DetectScoreBug` | Template matching with split-detection for partial overlays |
+| `DetectTimeouts` | Reads timeout indicators via oval brightness analysis |
+| `ScorebugDetection` | Detection result model (detected, confidence, bbox) |
+| `TimeoutReading` | Timeout reading result (home/away counts, oval states) |
 
-The main entry point `main.py` provides an end-to-end pipeline:
+**Detection Modes:**
+- **Full-frame search**: Template matching across entire frame (initial detection)
+- **Fixed-region check**: Fast verification at known location (subsequent frames)
+- **Split detection**: Left/right half matching for robustness to overlays
 
-```bash
-# Interactive mode - select video from list
-python main.py
+### `src/pipeline/` - Video Processing Orchestration
 
-# Specify video directly
-python main.py --video "full_videos/OSU vs ND 01.20.25.mp4"
+Orchestrates the complete play extraction pipeline with streaming processing.
 
-# Process specific segment
-python main.py --video "full_videos/game.mp4" --start 30:00 --end 60:00
+| Component | Description |
+|-----------|-------------|
+| `PlayExtractor` | Main pipeline class coordinating all extraction components |
+| `run_extraction()` | High-level extraction function with filtering |
+| `TemplateBuildingPass` | Pass 0: Builds digit templates using OCR on scorebug-verified frames |
+| `process_video_parallel()` | Parallel chunk processing for speedup |
 
-# Testing mode (10-minute segment from test video)
-python main.py --testing
+**Pipeline Stages:**
+1. **Pass 0** (if needed): Build digit templates using OCR
+2. **Streaming pass**: Read frame → detect scorebug → extract region → template match → state machine
+3. **Finalize**: Post-hoc clock reset identification, play merging, result building
 
-# Skip clip generation (detection only)
-python main.py --testing --skip-clips
+### `src/readers/` - Value Reading
 
-# Generate individual play clips (in addition to combined video)
-python main.py --testing --all-plays-debug
-```
+Reads values from detected regions using template matching.
 
-The pipeline guides you through:
-1. **Video selection** - Choose video file to process
-2. **Scorebug region selection** - Click to define scorebug location
-3. **Play clock region selection** - Click to define play clock within scorebug
-4. **Timeout region selection** - Click to define timeout indicators for each team
-5. **Play detection** - Automatic detection using state machine
-6. **Clip extraction** - Generate video clips for each play
+| Component | Description |
+|-----------|-------------|
+| `ReadPlayClock` | Template-based clock reading with dual-mode detection |
+| `backfill_missing_readings()` | Gap interpolation for missing readings |
+| `PlayClockReading` | Reading result (detected, value, confidence) |
+| `TemplatePlayClockReading` | Detailed result with per-digit match info |
 
-### Clip Generation Methods
+**Dual-Mode Detection:**
+- **Single-digit (0-9)**: Digit is CENTER-aligned
+- **Double-digit (10-40)**: Tens on LEFT, ones on RIGHT
 
-Three methods are available via `--clip-method`:
+### `src/setup/` - One-Time Preparation
 
-| Method | Speed | File Size | Accuracy |
-|--------|-------|-----------|----------|
-| `stream_copy` (default) | Fastest | Same as source | Keyframe-aligned |
-| `ultrafast` | Fast | Larger | Frame-accurate |
-| `reencode` | Slowest | Smaller | Frame-accurate |
+Components for building digit templates before video processing.
 
-```bash
-# Use frame-accurate encoding
-python main.py --testing --clip-method reencode
-```
+| Component | Description |
+|-----------|-------------|
+| `DigitTemplateBuilder` | Collects OCR samples, extracts digits, builds averaged templates |
+| `DigitTemplateLibrary` | Stores/loads templates (25 total for full coverage) |
+| `PlayClockRegionExtractor` | Extracts play clock region, preprocesses for OCR |
+| `DigitSample` / `DigitTemplate` | Data models for samples and templates |
 
-### Diagnostic Scripts
+**Template Coverage (25 templates needed):**
+- 10 ones-center templates (single-digit: 0-9)
+- 10 ones-right templates (double-digit: 0-9)
+- 4 tens-left templates (1, 2, 3, 4)
+- 1 blank template (tens position for single digits)
 
-For debugging and analysis:
+### `src/tracking/` - Cross-Frame State Management
 
-```bash
-# Analyze special play detection
-python scripts/diagnose_special_plays.py
+Tracks state across frames to identify play boundaries.
 
-# Debug red play clock OCR (low values 0-5)
-python scripts/diagnose_red_play_clock.py
+| Component | Description |
+|-----------|-------------|
+| `TrackPlayState` | Main state machine facade (delegates to helpers) |
+| `PlayLifecycle` | Manages play start, end, and state reset |
+| `PlayIdentificationChecks` | Clock analysis for play boundary detection |
+| `StateHandlers` | State machine transition handlers |
+| `PlayMerger` | Merges plays from multiple sources, deduplicates |
+| `ClockResetIdentifier` | Post-hoc 40→25 transition analysis |
 
-# Cache detections for fast iteration
-python scripts/cache_detections.py
+**State Machine States:**
+1. **IDLE** - Waiting for scorebug
+2. **PRE_SNAP** - Clock ticking down before snap
+3. **PLAY_IN_PROGRESS** - Ball snapped, play is live
+4. **POST_PLAY** - Play ended, transitioning
+5. **NO_SCOREBUG** - Scorebug lost (e.g., during replay)
 
-# Replay cached detections through state machine
-python scripts/replay_state_machine.py
-```
+### `src/ui/` - Interactive Region Selection
 
-Archived scripts (in `scripts/archive/`) include:
-- `visualize_detections.py` - Visualize detection results
-- `diagnose_play_clock.py` - Debug play clock reading
-- `benchmark_*.py` - Various benchmarking scripts
+Tools for interactively selecting regions in video frames.
 
-## Module Architecture
+| Component | Description |
+|-----------|-------------|
+| `RegionSelector` | Mouse callback handler (two-click or drag modes) |
+| `ScorebugSelectionSession` | Full-frame scorebug selection with frame navigation |
+| `PlayClockSelectionSession` | Zoomed scorebug view for precise clock selection |
+| `TimeoutSelectionSession` | Padded view for timeout indicator selection |
+| `BBox` | Bounding box model with scaling/offset utilities |
+
+### `src/utils/` - Shared Utilities
+
+Utilities shared across modules to avoid code duplication.
+
+| Component | Description |
+|-----------|-------------|
+| `detect_red_digits()` | Detects red digits (clock ≤ 5 seconds) |
+| `normalize_to_grayscale()` | Converts red digits to white for uniform templates |
+| `preprocess_playclock_region()` | Full preprocessing pipeline for clock regions |
+| `extract_*_region()` | Digit region extraction (left, right, center, far-left) |
+| `create_frame_result()` | Standardized frame result dictionary factory |
 
-The codebase is organized into modular components under `src/`:
+### `src/video/` - Video I/O and FFmpeg Operations
 
-| Module | Purpose |
-|--------|---------|
-| `src/ui/` | Interactive user interface components (OpenCV-based region selection) |
-| `src/video/` | Video processing (FFmpeg operations, frame extraction) |
-| `src/config/` | Configuration management (SessionConfig, project constants) |
-| `src/detectors/` | Detection components (scorebug, play clock, timeout tracking) |
-| `src/pipeline/` | Pipeline orchestration (detection flow, result handling) |
+Video processing, frame extraction, and clip generation.
 
-### Key Classes
+| Component | Description |
+|-----------|-------------|
+| `ThreadedFrameReader` | Background thread for overlapped video I/O |
+| `extract_sample_frames()` | Extract frames at intervals for selection |
+| `generate_clips()` | Generate play clips with configurable method |
+| `concatenate_clips()` | Combine clips into highlight video |
 
-- **`RegionSelector`** (`ui/selector.py`) - Interactive region selection with two-click or drag modes
-- **`BBox`** (`ui/models.py`) - Pydantic model for bounding box coordinates
-- **`SessionConfig`** (`config/session.py`) - Dataclass holding all session configuration
-- **`PlayDetector`** (`pipeline/play_detector.py`) - Main detection pipeline
-- **`PlayStateMachine`** (`detectors/play_state_machine.py`) - Play boundary detection logic
+**Clip Methods:**
+- `stream_copy`: Fastest, keyframe-aligned cuts
+- `reencode`: Frame-accurate, best compression
+- `ultrafast`: Frame-accurate, faster encoding
 
 ## Detection Algorithm
 
@@ -235,20 +276,11 @@ The codebase is organized into modular components under `src/`:
 | **Special** | 40→25 transition | XPs, FGs, punts, injury stoppages |
 | **Timeout** | Timeout indicator change | Team-called timeouts |
 
-### Play Clock State Machine
-
-The system tracks the play clock through these states:
-1. **IDLE** - Waiting for scorebug
-2. **PRE_SNAP** - Clock ticking down before snap
-3. **PLAY_IN_PROGRESS** - Ball snapped, play is live
-4. **POST_PLAY** - Play ended, transitioning
-5. **NO_SCOREBUG** - Scorebug lost (e.g., during replay)
-
 ### Backward Counting (Primary Method for Play End)
 
 When the play clock reappears showing value X (where X < 40):
 ```
-play_end_time = current_time - (40 - X)
+play_end_time = current_time - (clock_base - X)
 ```
 
 Example: If at timestamp 100.0s we see play clock at 35, play ended at:
@@ -256,15 +288,6 @@ Example: If at timestamp 100.0s we see play clock at 35, play ended at:
 100.0 - (40 - 35) = 95.0s
 ```
 
-This method is reliable even when broadcasts cut to replays.
-
-### Special Play Detection (40→25 Clock Reset)
-
-After possession-changing plays (XPs, FGs, punts), the clock resets to 25 instead of 40:
-1. Clock shows 40 briefly after the snap
-2. Clock quickly transitions to 25 (possession change)
-3. Play classified as "special" with 10-second max duration
-
 ### 3-Class Clock Reset Classification
 
 When a 40→25 transition is detected:
@@ -274,13 +297,50 @@ When a 40→25 transition is detected:
 
 ### Quiet Time Filter
 
-A 10-second quiet time is enforced after normal plays end. During this window, special/timeout plays are rejected. This filters false positives from:
-- Penalties during plays (false starts, delay of game)
-- Clock resets from ongoing play situations
+A 10-second quiet time is enforced after normal plays end. During this window, special/timeout plays are rejected to filter false positives from penalties.
 
 ### Play Filtering
 
-Plays shorter than 3 seconds are automatically filtered out (typically clock operator errors or false positives).
+Plays shorter than 3 seconds are automatically filtered out (typically clock operator errors).
+
+## Usage
+
+### Main Pipeline
+
+```bash
+# Interactive mode - select video from list
+python main.py
+
+# Specify video directly
+python main.py --video "full_videos/OSU vs ND 01.20.25.mp4"
+
+# Process specific segment
+python main.py --video "full_videos/game.mp4" --start 30:00 --end 60:00
+
+# Testing mode (10-minute segment from test video)
+python main.py --testing
+
+# Parallel processing (faster)
+python main.py --testing --workers 2
+
+# Skip clip generation (detection only)
+python main.py --testing --skip-clips
+
+# Generate individual play clips
+python main.py --testing --all-plays-debug
+
+# Use frame-accurate encoding
+python main.py --testing --clip-method reencode
+```
+
+### Pipeline Phases
+
+1. **Video selection** - Choose video file to process
+2. **Scorebug region selection** - Click to define scorebug location
+3. **Play clock region selection** - Click to define play clock within scorebug
+4. **Timeout region selection** - Click to define timeout indicators for each team
+5. **Play detection** - Template building + streaming extraction
+6. **Clip extraction** - Generate video clips for each play
 
 ## Output Files
 
@@ -291,12 +351,12 @@ For a video named `OSU vs Tenn 12.21.24.mkv`:
 | `output/OSU_vs_Tenn_12_21_24_config.json` | Session configuration |
 | `output/OSU_vs_Tenn_12_21_24_plays.json` | Detected plays with timestamps |
 | `output/OSU_vs_Tenn_12_21_24_template.png` | Scorebug template image |
-| `output/OSU_vs_Tenn_12_21_24_timeout_config.json` | Timeout tracker configuration |
+| `output/OSU_vs_Tenn_12_21_24_playclock_config.json` | Play clock region config |
+| `output/OSU_vs_Tenn_12_21_24_timeout_config.json` | Timeout tracker config |
 | `output/clips/OSU_vs_Tenn_12_21_24_all_plays.mp4` | Concatenated highlight video |
 
 ### Play JSON Format
 
-Each play includes:
 ```json
 {
   "play_number": 1,
@@ -312,75 +372,69 @@ Each play includes:
 
 Play types: `normal`, `special`, `timeout`
 
-## Benchmarks
+## Performance
+
+### Template Matching vs OCR
+
+| Metric | EasyOCR | Template Matching |
+|--------|---------|-------------------|
+| Time per frame | 48.9ms | 0.3ms |
+| Speedup | 1x | **163x** |
 
-| Version | Total Plays | Normal | Special | Timeout | Ground Truth (Special) |
-|---------|-------------|--------|---------|---------|------------------------|
-| V1 (Baseline) | ~130 | ~130 | 0 | 0 | 0% |
-| V2 (Split Detection) | 149 | 149 | 0 | 0 | 0% |
-| V3 (Special Plays) | 176 | 150 | 22 | 4 | 85% (17/20) |
+### Processing Modes
 
-Baseline files stored in `output/benchmarks/`.
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| Sequential | Single-threaded streaming | Default, simpler |
+| Parallel (2 workers) | Multi-process chunks | ~26% faster |
 
-## Test Data
+## Setup
+
+### Prerequisites
+- Python 3.13+
+- ffmpeg installed (`brew install ffmpeg` on macOS)
 
-### Video Reference
-- **File**: `full_videos/OSU vs Tenn 12.21.24.mkv`
-- **Resolution**: 1920×1080 @ 59.94fps
-- **Final Score**: Ohio State 42, Tennessee 17
+### Installation
 
-### Test Segments
-- **Quick test**: 38:40 - 41:40 (3 minutes, ~5 plays)
-- **Extended test**: 38:40 - 48:40 (10 minutes, ~12 plays)
+```bash
+# Create and activate virtual environment
+python -m venv .venv
+source .venv/bin/activate
 
-### Ground Truth Special Plays
-- 7 XPs, 2 FGs, 10 punts, 1 opening kickoff (20 total)
-- See `docs/special_plays_ground_truth.md` for details
+# Install dependencies
+pip install -e .
+```
 
 ## Development
 
 ### Code Style
-- Use Black formatter with `line-length=180`
-- Add descriptive inline comments
-- Include logging for debugging
 
 ```bash
+# Format with Black (line-length=180)
 python -m black src/ scripts/ main.py --line-length=180
-```
 
-### Running Linter
-```bash
-# Lint main modules
+# Lint
 pylint src/ main.py
-
-# Lint active scripts
-pylint scripts/*.py
-
-# Lint archived scripts (from archive directory)
-cd scripts/archive && pylint *.py
 ```
 
-### Running Tests
+### Testing
+
 ```bash
-# State machine tests (archived)
-python scripts/archive/test_state_machine.py
+# Quick test (3 minutes, ~5 plays)
+python main.py --testing --start 38:40 --end 41:40
 
-# Play clock reader tests (archived, requires video)
-python scripts/archive/test_play_clock_reader.py
+# Extended test (10 minutes, ~12 plays)
+python main.py --testing
 ```
 
 ## Dependencies
 
 - `opencv-python>=4.8.0` - Video processing
 - `numpy>=1.24.0` - Array operations
-- `pillow>=10.0.0` - Image handling
-- `easyocr>=1.7.0` - OCR for play clock reading
+- `pydantic>=2.0.0` - Data validation
+- `easyocr>=1.7.0` - OCR for template building (Pass 0 only)
 - `torch>=2.0.0` - Required by EasyOCR
 
-### Development Dependencies
-- `black>=24.0.0` - Code formatting
-- `pylint>=3.0.0` - Linting
-
 ## License
 
 Private project - All rights reserved

main.py

@@ -36,10 +36,6 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent / "src"))
-
-# pylint: disable=wrong-import-position
 from config import (
     SessionConfig,
     save_session_config,
@@ -62,7 +58,7 @@ from ui import (
 )
 from ui.api import extract_sample_frames_for_selection
 from video import generate_clips
-from pipeline import run_detection, print_results_summary
+from pipeline import run_extraction, print_results_summary
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -372,19 +368,19 @@ def _print_region_summary(config: SessionConfig) -> None:
 # =============================================================================
 
 
-def _phase3_detection(session_config: SessionConfig, num_workers: int) -> Dict[str, Any]:
+def _phase3_extraction(session_config: SessionConfig, num_workers: int) -> Dict[str, Any]:
     """
-    Phase 3: Run play detection on the video.
+    Phase 3: Run play extraction on the video.
 
     Args:
         session_config: Configuration with video path and regions.
         num_workers: Number of parallel workers.
 
     Returns:
-        Detection results dictionary.
+        Extraction results dictionary.
     """
     print("\n" + "=" * 60)
-    return run_detection(session_config, OUTPUT_DIR, num_workers=num_workers)
+    return run_extraction(session_config, OUTPUT_DIR, num_workers=num_workers)
 
 
 # =============================================================================
@@ -496,8 +492,8 @@ def main() -> int:
     if session_config is None:
         return 1
 
-    # Phase 3: Detection
-    results = _phase3_detection(session_config, args.parallel)
+    # Phase 3: Extraction
+    results = _phase3_extraction(session_config, args.parallel)
 
     # Phase 4: Clip Generation
     clip_timing = {}

pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "opencv-python>=4.8.0",
     "numpy>=1.24.0",
     "pillow>=10.0.0",
+    "pydantic>=2.0.0",
     "pytesseract>=0.3.10",
 ]
 
@@ -18,17 +19,30 @@ dev = [
     "black>=24.0.0",
     "pylint>=3.0.0",
     "pylint-pydantic>=0.3.0",
+    "mypy>=1.0.0",
 ]
 
 [build-system]
 requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
 [tool.mypy]
 python_version = "3.13"
 strict = true
 ignore_missing_imports = true
 exclude = ["tests", "scripts", "examples", "static"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
 
 [tool.black]
 line-length = 180

scripts/archive/v2/benchmark_ocr.py

@@ -20,12 +20,10 @@ from typing import List, Tuple, Optional, Dict
 import cv2
 import numpy as np
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
+from detection import DetectScoreBug
 
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -51,7 +49,7 @@ def load_play_clock_config() -> Tuple[int, int, int, int]:
     return (data["x_offset"], data["y_offset"], data["width"], data["height"])
 
 
-def extract_test_frames(video_path: Path, detector: ScorebugDetector, timestamps: List[float]) -> List[Tuple[float, np.ndarray, Tuple[int, int, int, int]]]:
+def extract_test_frames(video_path: Path, detector: DetectScoreBug, timestamps: List[float]) -> List[Tuple[float, np.ndarray, Tuple[int, int, int, int]]]:
     """Extract frames with scorebug for testing."""
     cap = cv2.VideoCapture(str(video_path))
     if not cap.isOpened():
@@ -521,7 +519,7 @@ def main():
     logger.info(f"Play clock config: {config}")
 
     # Initialize scorebug detector
-    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
+    detector = DetectScoreBug(template_path=str(TEMPLATE_PATH))
 
     # Extract test frames
     logger.info(f"Extracting {len(TEST_TIMESTAMPS)} test frames...")

scripts/archive/v2/benchmark_ocr_batching.py

@@ -25,12 +25,13 @@ from typing import List, Tuple, Optional
 import cv2
 import numpy as np
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
+from detection import DetectScoreBug
+from readers import PlayClockReading
+from setup import PlayClockRegionExtractor
 
-from detectors import ScorebugDetector, PlayClockReader  # noqa: E402
-from detectors.play_clock_reader import PlayClockReading, _get_easyocr_reader  # noqa: E402
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
+# Note: _get_easyocr_reader was removed during migration to template matching
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -57,8 +58,8 @@ def extract_frames_sequential(
     start_time: float,
     end_time: float,
     frame_interval: float,
-    scorebug_detector: ScorebugDetector,
-    clock_reader: PlayClockReader,
+    scorebug_detector: DetectScoreBug,
+    clock_reader: PlayClockRegionExtractor,
 ) -> Tuple[List[FrameData], dict]:
     """
     Extract and preprocess frames using sequential reading (new optimized approach).
@@ -293,11 +294,11 @@ def main():
         config = json.load(f)
 
     # Initialize detectors
-    scorebug_detector = ScorebugDetector(template_path=str(template_path))
+    scorebug_detector = DetectScoreBug(template_path=str(template_path))
     fixed_region = (config["scorebug_x"], config["scorebug_y"], config["scorebug_width"], config["scorebug_height"])
     scorebug_detector.set_fixed_region(fixed_region)
 
-    clock_reader = PlayClockReader(region_config_path=str(playclock_config_path))
+    clock_reader = PlayClockRegionExtractor(region_config_path=str(playclock_config_path))
 
     # Extract and preprocess all frames
     logger.info("\n--- Frame Extraction Phase ---")

scripts/archive/v2/detect_plays.py

@@ -24,12 +24,10 @@ import logging
 import sys
 from pathlib import Path
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
-
-# pylint: disable=wrong-import-position
 from pipeline import PlayDetector
+
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
 from pipeline.play_detector import DetectionConfig
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

scripts/archive/v2/diagnose_play_clock.py

@@ -18,12 +18,11 @@ from pathlib import Path
 import cv2
 import numpy as np
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
+from detection import DetectScoreBug
+from setup import PlayClockRegionExtractor
 
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector, PlayClockReader
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
 
 logging.basicConfig(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -38,14 +37,14 @@ OUTPUT_DIR = PROJECT_ROOT / "output" / "debug"
 TEST_TIMESTAMPS = [2320.0, 2321.0, 2322.0, 2325.0, 2328.0]  # Sample timestamps in seconds
 
 
-def extract_debug_info(video_path: Path, detector: ScorebugDetector, reader: PlayClockReader, timestamps: list) -> None:
+def extract_debug_info(video_path: Path, detector: DetectScoreBug, reader: PlayClockRegionExtractor, timestamps: list) -> None:
     """
     Extract frames and save debug visualizations.
 
     Args:
         video_path: Path to video file
-        detector: ScorebugDetector instance
-        reader: PlayClockReader instance
+        detector: DetectScoreBug instance
+        reader: PlayClockRegionExtractor instance
         timestamps: List of timestamps to analyze
     """
     cap = cv2.VideoCapture(str(video_path))
@@ -92,7 +91,7 @@ def extract_debug_info(video_path: Path, detector: ScorebugDetector, reader: Pla
         # Extract play clock region
         play_clock_region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
 
-        # Preprocess for OCR (same as PlayClockReader)
+        # Preprocess for OCR (same as PlayClockRegionExtractor)
         preprocessed = preprocess_for_debug(play_clock_region)
 
         # Run OCR and get result
@@ -144,7 +143,7 @@ def extract_debug_info(video_path: Path, detector: ScorebugDetector, reader: Pla
 
 def preprocess_for_debug(region: np.ndarray) -> np.ndarray:
     """
-    Preprocess the play clock region for OCR (same as PlayClockReader).
+    Preprocess the play clock region for OCR (same as PlayClockRegionExtractor).
     Returns the preprocessed image for debugging.
     """
     # Convert to grayscale
@@ -195,8 +194,8 @@ def main():
 
     # Initialize
     logger.info("Initializing detectors...")
-    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
-    reader = PlayClockReader(region_config_path=str(CONFIG_PATH))
+    detector = DetectScoreBug(template_path=str(TEMPLATE_PATH))
+    reader = PlayClockRegionExtractor(region_config_path=str(CONFIG_PATH))
 
     # Run diagnostic
     logger.info("Extracting debug info for %d timestamps...", len(TEST_TIMESTAMPS))

scripts/archive/v2/diagnose_scorebug_threshold.py

@@ -17,9 +17,8 @@ from typing import List, Tuple, Dict
 import cv2
 import numpy as np
 
-# Add src to path for imports (scripts/archive/ -> project root)
+# Path reference for constants
 PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)

scripts/archive/v2/identify_play_clock_region.py

@@ -26,12 +26,10 @@ from typing import Optional, Tuple, List, Any
 
 import cv2
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
+from detection import DetectScoreBug
 
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -118,14 +116,14 @@ class RegionSelector:
 
 
 def extract_frames_with_scorebug(
-    video_path: Path, detector: ScorebugDetector, start_time: float, end_time: float, interval: float
+    video_path: Path, detector: DetectScoreBug, start_time: float, end_time: float, interval: float
 ) -> List[Tuple[float, Any, Tuple[int, int, int, int]]]:
     """
     Extract frames from video where scorebug is detected.
 
     Args:
         video_path: Path to video file
-        detector: ScorebugDetector instance
+        detector: DetectScoreBug instance
         start_time: Start time in seconds
         end_time: End time in seconds
         interval: Sampling interval in seconds
@@ -327,7 +325,7 @@ def main():
 
     # Initialize scorebug detector
     logger.info("Loading scorebug template: %s", TEMPLATE_PATH)
-    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
+    detector = DetectScoreBug(template_path=str(TEMPLATE_PATH))
 
     # Extract frames with scorebug
     logger.info("Extracting frames from %ds to %ds...", START_TIME_SECONDS, END_TIME_SECONDS)

scripts/archive/v2/test_play_clock_reader.py

@@ -21,12 +21,12 @@ from typing import List, Tuple, Any
 import cv2
 import numpy as np
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
+from detection import DetectScoreBug
+from readers import PlayClockReading
+from setup import PlayClockRegionExtractor
 
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector, PlayClockReader, PlayClockReading
+# Path reference for constants
+PROJECT_ROOT = Path(__file__).parent.parent.parent
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -44,14 +44,14 @@ SAMPLE_INTERVAL_SECONDS = 0.5  # Sample every 0.5 seconds for detailed analysis
 
 
 def extract_test_frames(
-    video_path: Path, detector: ScorebugDetector, start_time: float, end_time: float, interval: float, max_frames: int = 50
+    video_path: Path, detector: DetectScoreBug, start_time: float, end_time: float, interval: float, max_frames: int = 50
 ) -> List[Tuple[float, Any, Tuple[int, int, int, int]]]:
     """
     Extract frames from video where scorebug is detected for testing.
 
     Args:
         video_path: Path to video file
-        detector: ScorebugDetector instance
+        detector: DetectScoreBug instance
         start_time: Start time in seconds
         end_time: End time in seconds
         interval: Sampling interval in seconds
@@ -92,13 +92,13 @@ def extract_test_frames(
     return frames
 
 
-def run_reading_tests(frames: List[Tuple[float, Any, Tuple[int, int, int, int]]], reader: PlayClockReader) -> List[Tuple[float, PlayClockReading, Any]]:
+def run_reading_tests(frames: List[Tuple[float, Any, Tuple[int, int, int, int]]], reader: PlayClockRegionExtractor) -> List[Tuple[float, PlayClockReading, Any]]:
     """
     Run play clock reader on all extracted frames.
 
     Args:
         frames: List of (timestamp, frame, scorebug_bbox) tuples
-        reader: PlayClockReader instance
+        reader: PlayClockRegionExtractor instance
 
     Returns:
         List of (timestamp, reading, frame) tuples
@@ -119,7 +119,7 @@ def run_reading_tests(frames: List[Tuple[float, Any, Tuple[int, int, int, int]]]
 
 def create_visualization_grid(
     results: List[Tuple[float, PlayClockReading, Any]],
-    reader: PlayClockReader,
+    reader: PlayClockRegionExtractor,
     scorebug_bboxes: List[Tuple[int, int, int, int]],
     output_path: Path,
     grid_cols: int = 5,
@@ -129,7 +129,7 @@ def create_visualization_grid(
 
     Args:
         results: List of (timestamp, reading, frame) tuples
-        reader: PlayClockReader for visualization
+        reader: PlayClockRegionExtractor for visualization
         scorebug_bboxes: List of scorebug bounding boxes
         output_path: Path to save the visualization
         grid_cols: Number of columns in the grid
@@ -243,8 +243,8 @@ def main():
 
     # Initialize detectors
     logger.info("Initializing detectors...")
-    scorebug_detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
-    play_clock_reader = PlayClockReader(region_config_path=str(CONFIG_PATH))
+    scorebug_detector = DetectScoreBug(template_path=str(TEMPLATE_PATH))
+    play_clock_reader = PlayClockRegionExtractor(region_config_path=str(CONFIG_PATH))
 
     # Extract test frames
     logger.info("Extracting test frames from %.1fs to %.1fs...", START_TIME_SECONDS, END_TIME_SECONDS)

scripts/archive/v2/test_state_machine.py

@@ -23,14 +23,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Tuple, Optional
 
-# Add src to path for imports (scripts/archive/ -> project root)
-PROJECT_ROOT = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(PROJECT_ROOT / "src"))
-
-# pylint: disable=wrong-import-position
-from detectors import PlayStateMachine, PlayEvent
-from detectors.scorebug_detector import ScorebugDetection
-from detectors.play_clock_reader import PlayClockReading
+from tracking import TrackPlayState, PlayEvent
+from detection import ScorebugDetection
+from readers import PlayClockReading
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -74,7 +69,7 @@ def run_test_sequence(name: str, frames: List[TestFrame], expected_plays: int) -
     logger.info("TEST: %s", name)
     logger.info("=" * 60)
 
-    state_machine = PlayStateMachine()
+    state_machine = TrackPlayState()
     detected_plays = []
 
     for frame in frames:
@@ -299,7 +294,7 @@ def test_direct_vs_backward_comparison() -> bool:
 
 def main():
     """Run all state machine tests."""
-    logger.info("PlayStateMachine Test Suite")
+    logger.info("TrackPlayState Test Suite")
     logger.info("=" * 60)
 
     tests = [

scripts/archive/v3/cache_detections.py

@@ -28,12 +28,9 @@ from typing import List, Dict, Any, Optional, Tuple
 import cv2
 import numpy as np
 
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector, PlayClockReader, TimeoutTracker
-from detectors.play_clock_reader import _get_easyocr_reader
+from detection import DetectScoreBug, TrackTimeouts
+from setup import PlayClockRegionExtractor
+# Note: _get_easyocr_reader was removed during migration to template matching
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -85,13 +82,13 @@ def cache_detections(
 
     # Initialize detectors
     logger.info("Initializing detectors...")
-    scorebug_detector = ScorebugDetector(template_path=str(template_path), use_split_detection=True)
-    clock_reader = PlayClockReader(region_config_path=str(clock_config_path))
+    scorebug_detector = DetectScoreBug(template_path=str(template_path), use_split_detection=True)
+    clock_reader = PlayClockRegionExtractor(region_config_path=str(clock_config_path))
 
     # Initialize timeout tracker if config provided
-    timeout_tracker: Optional[TimeoutTracker] = None
+    timeout_tracker: Optional[TrackTimeouts] = None
     if timeout_config_path and timeout_config_path.exists():
-        timeout_tracker = TimeoutTracker(config_path=str(timeout_config_path))
+        timeout_tracker = TrackTimeouts(config_path=str(timeout_config_path))
         logger.info("Timeout tracker initialized from: %s", timeout_config_path)
     else:
         logger.info("Timeout tracker not configured (no config or file not found)")

scripts/archive/v3/configure_timeout_tracker.py

@@ -30,12 +30,7 @@ from typing import Optional, Tuple, List, Any
 import cv2
 import numpy as np
 
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-# pylint: disable=wrong-import-position
-from detectors import ScorebugDetector
-from detectors.timeout_tracker import TimeoutTracker, TimeoutRegionConfig
+from detection import DetectScoreBug, TrackTimeouts, TimeoutRegionConfig
 from ui import RegionSelector
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
@@ -54,14 +49,14 @@ SAMPLE_INTERVAL_SECONDS = 3  # Sample every 3 seconds
 
 
 def extract_frames_with_scorebug(
-    video_path: Path, detector: ScorebugDetector, start_time: float, end_time: float, interval: float
+    video_path: Path, detector: DetectScoreBug, start_time: float, end_time: float, interval: float
 ) -> List[Tuple[float, Any, Tuple[int, int, int, int]]]:
     """
     Extract frames from video where scorebug is detected.
 
     Args:
         video_path: Path to video file
-        detector: ScorebugDetector instance
+        detector: DetectScoreBug instance
         start_time: Start time in seconds
         end_time: End time in seconds
         interval: Sampling interval in seconds
@@ -122,7 +117,7 @@ def convert_to_absolute_bbox(relative_bbox: Tuple[int, int, int, int], scorebug_
     return (abs_x, abs_y, original_rel_w, original_rel_h)
 
 
-def test_timeout_detection(frame: np.ndarray, tracker: TimeoutTracker) -> None:
+def test_timeout_detection(frame: np.ndarray, tracker: TrackTimeouts) -> None:
     """Test and display timeout detection on a frame."""
     if not tracker.is_configured():
         logger.warning("Tracker not fully configured yet")
@@ -167,7 +162,7 @@ def run_region_selection(frames_with_scorebug: List[Tuple[float, Any, Tuple[int,
     away_region: Optional[TimeoutRegionConfig] = None
 
     # Create tracker for testing
-    tracker = TimeoutTracker()
+    tracker = TrackTimeouts()
 
     frame_idx = 0
     scale_factor = 2  # Scale up for easier selection
@@ -313,7 +308,7 @@ def main():
 
     # Initialize scorebug detector
     logger.info("Loading scorebug template: %s", TEMPLATE_PATH)
-    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
+    detector = DetectScoreBug(template_path=str(TEMPLATE_PATH))
 
     # Extract frames with scorebug
     logger.info("Extracting frames from %ds to %ds...", START_TIME_SECONDS, END_TIME_SECONDS)

scripts/archive/v3/debug_red_preprocessing.py

@@ -2,15 +2,11 @@
 Debug script to visualize each preprocessing step for red play clock digits.
 """
 
-import sys
 from pathlib import Path
 
 import cv2
 import numpy as np
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
 
 def main():
     # Load the red play clock region (frame 472849, which shows "5")

scripts/archive/v3/diagnose_red_play_clock.py

@@ -8,18 +8,15 @@ Test case: 2:11:20 for 15 seconds in OSU vs Tenn 12.21.24.mkv
 Expected: Play clock should tick down to 0 and stay at 0 for a few seconds.
 """
 
-import sys
 import logging
 from pathlib import Path
 
 import cv2
 import numpy as np
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-from detectors.play_clock_reader import PlayClockReader, backfill_missing_readings
-from detectors.scorebug_detector import ScorebugDetector
+from detection import DetectScoreBug
+from readers import backfill_missing_readings
+from setup import PlayClockRegionExtractor
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -84,8 +81,8 @@ def main():
     logger.info(f"Start time: {start_seconds:.2f}s")
 
     # Initialize detectors
-    scorebug_detector = ScorebugDetector(str(template_path))
-    play_clock_reader = PlayClockReader(str(play_clock_config_path))
+    scorebug_detector = DetectScoreBug(str(template_path))
+    play_clock_reader = PlayClockRegionExtractor(str(play_clock_config_path))
 
     # Open video
     cap = cv2.VideoCapture(str(video_path))
@@ -209,7 +206,7 @@ def main():
     # Collect all readings for backfill test
     all_readings = []
     for r in results:
-        from detectors.play_clock_reader import PlayClockReading
+        from detection import PlayClockReading
 
         all_readings.append(
             PlayClockReading(

scripts/archive/v3/replay_state_machine.py

@@ -30,11 +30,9 @@ from datetime import datetime
 from pathlib import Path
 from typing import Dict, Any, List, Optional
 
-# Add src to path for imports
-sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
-
-# pylint: disable=wrong-import-position
-from detectors import PlayStateMachine, ScorebugDetection, PlayClockReading, PlayEvent
+from detection import ScorebugDetection
+from readers import PlayClockReading
+from tracking import TrackPlayState, PlayEvent
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -479,7 +477,7 @@ def replay_state_machine(
         logger.info("  Special plays: %d", special_count)
 
     # Initialize state machine for regular play detection
-    state_machine = PlayStateMachine()
+    state_machine = TrackPlayState()
 
     t_start = time.perf_counter()
 

scripts/investigate_missed_plays.py

@@ -20,16 +20,13 @@ Usage:
 
 import json
 import logging
-import sys
 from pathlib import Path
 from typing import List, Dict, Tuple, Optional
 
 import cv2
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
-from detectors.digit_template_reader import DigitTemplateLibrary, TemplatePlayClockReader
+from setup import DigitTemplateLibrary
+from readers import ReadPlayClock
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -88,7 +85,7 @@ def find_missed_plays(baseline: List[Dict], detected: List[Dict], tolerance: flo
 
 def collect_clock_readings(
     video_path: str,
-    template_reader: TemplatePlayClockReader,
+    template_reader: ReadPlayClock,
     playclock_coords: Tuple[int, int, int, int],
     start_time: float,
     end_time: float,
@@ -138,7 +135,7 @@ def format_readings(readings: List[Tuple[float, Optional[int], float]]) -> str:
 
 def analyze_missed_play(
     play: Dict,
-    template_reader: TemplatePlayClockReader,
+    template_reader: ReadPlayClock,
     playclock_coords: Tuple[int, int, int, int],
     video_path: str,
 ) -> Dict:
@@ -318,7 +315,7 @@ def main():
 
     playclock_coords = get_absolute_playclock_coords()
     pc_w, pc_h = playclock_coords[2], playclock_coords[3]
-    template_reader = TemplatePlayClockReader(template_library, region_width=pc_w, region_height=pc_h)
+    template_reader = ReadPlayClock(template_library, region_width=pc_w, region_height=pc_h)
 
     # Analyze first 10 missed plays
     logger.info("\n[Step 3] Analyzing first 10 missed plays...")

scripts/test_digit_extraction.py

@@ -19,11 +19,9 @@ from pathlib import Path
 
 import cv2
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
-from detectors import PlayClockReader, ScorebugDetector
-from detectors.digit_template_reader import DigitTemplateBuilder, normalize_to_grayscale, detect_red_digits
+from detection import DetectScoreBug
+from readers import normalize_to_grayscale, detect_red_digits
+from setup import DigitTemplateBuilder, PlayClockRegionExtractor
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -46,8 +44,8 @@ def extract_samples_with_ocr(video_path: str, start_time: float, end_time: float
     Returns list of (timestamp, clock_value, region_image, confidence)
     """
     # Initialize components
-    scorebug_detector = ScorebugDetector(template_path=TEMPLATE_PATH)
-    clock_reader = PlayClockReader(region_config_path=PLAYCLOCK_CONFIG_PATH)
+    scorebug_detector = DetectScoreBug(template_path=TEMPLATE_PATH)
+    clock_reader = PlayClockRegionExtractor(region_config_path=PLAYCLOCK_CONFIG_PATH)
 
     # Open video
     cap = cv2.VideoCapture(video_path)

scripts/test_fast_full_video.py

@@ -30,9 +30,6 @@ import time
 from pathlib import Path
 from typing import List, Dict, Any, Optional
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
 from pipeline.play_detector import PlayDetector, DetectionConfig
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

scripts/test_full_segment.py

@@ -17,9 +17,6 @@ import logging
 import sys
 from pathlib import Path
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
 from pipeline.play_detector import PlayDetector, DetectionConfig
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

scripts/test_full_video_evaluation.py

@@ -23,12 +23,9 @@ import sys
 import time
 from pathlib import Path
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
 from pipeline.play_detector import DetectionConfig, PlayDetector
-from detectors.digit_template_reader import DigitTemplateLibrary
-from detectors.timeout_tracker import TimeoutTracker
+from setup import DigitTemplateLibrary
+from detection import TrackTimeouts
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -182,7 +179,7 @@ def run_full_video_evaluation():
     # Initialize timeout tracker if config exists
     timeout_tracker = None
     if Path(TIMEOUT_CONFIG_PATH).exists():
-        timeout_tracker = TimeoutTracker(config_path=TIMEOUT_CONFIG_PATH)
+        timeout_tracker = TrackTimeouts(config_path=TIMEOUT_CONFIG_PATH)
         logger.info("Timeout tracker initialized")
 
     # Initialize detector

scripts/test_missed_play.py

@@ -17,9 +17,6 @@ import logging
 import sys
 from pathlib import Path
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
 from pipeline.play_detector import PlayDetector, DetectionConfig
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")

scripts/test_template_accuracy.py

@@ -27,11 +27,9 @@ from typing import List
 import cv2
 import numpy as np
 
-# Add src to path
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
-
-from detectors import PlayClockReader, ScorebugDetector
-from detectors.digit_template_reader import DigitTemplateBuilder, TemplatePlayClockReader
+from detection import DetectScoreBug
+from readers import ReadPlayClock
+from setup import DigitTemplateBuilder, PlayClockRegionExtractor
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -57,8 +55,8 @@ def collect_all_samples(video_path: str, start_time: float, end_time: float, sam
 
     Returns list of (timestamp, clock_value, region_image, confidence)
     """
-    scorebug_detector = ScorebugDetector(template_path=TEMPLATE_PATH)
-    clock_reader = PlayClockReader(region_config_path=PLAYCLOCK_CONFIG_PATH)
+    scorebug_detector = DetectScoreBug(template_path=TEMPLATE_PATH)
+    clock_reader = PlayClockRegionExtractor(region_config_path=PLAYCLOCK_CONFIG_PATH)
 
     cap = cv2.VideoCapture(video_path)
     if not cap.isOpened():
@@ -234,7 +232,7 @@ def test_template_accuracy():
 
     # Test template matching on test set
     logger.info("\n[Step 4] Testing template matching accuracy...")
-    template_reader = TemplatePlayClockReader(library)
+    template_reader = ReadPlayClock(library)
 
     correct = 0
     wrong = 0

src/config/__init__.py

@@ -1,7 +1,7 @@
 """Configuration modules for session management and project settings."""
 
+from .models import SessionConfig
 from .session import (
-    SessionConfig,
     save_session_config,
     load_session_config,
     get_video_basename,

src/config/models.py

@@ -0,0 +1,55 @@
+"""
+Pydantic models for CFB40 configuration.
+
+This module contains validated configuration models using Pydantic BaseModel.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel
+
+
+class SessionConfig(BaseModel):
+    """
+    Configuration for a detection session, including user-specified regions.
+
+    This model contains all the information needed to run play detection
+    on a video, including the selected scorebug, play clock, and timeout regions.
+    """
+
+    # Video settings
+    video_path: str
+    start_time: float
+    end_time: Optional[float]
+
+    # Scorebug region (absolute coordinates in frame)
+    scorebug_x: int
+    scorebug_y: int
+    scorebug_width: int
+    scorebug_height: int
+
+    # Play clock region (relative to scorebug)
+    playclock_x_offset: int
+    playclock_y_offset: int
+    playclock_width: int
+    playclock_height: int
+
+    # Timeout tracker regions (absolute coordinates in frame)
+    # Home team timeout indicators (3 ovals stacked vertically)
+    home_timeout_x: int = 0
+    home_timeout_y: int = 0
+    home_timeout_width: int = 0
+    home_timeout_height: int = 0
+
+    # Away team timeout indicators (3 ovals stacked vertically)
+    away_timeout_x: int = 0
+    away_timeout_y: int = 0
+    away_timeout_width: int = 0
+    away_timeout_height: int = 0
+
+    # Generated paths
+    template_path: str = ""
+    config_path: str = ""
+
+    # Video identifier for output naming
+    video_basename: str = ""

src/config/session.py

@@ -1,19 +1,20 @@
 """
 Session configuration management for CFB40.
 
-This module provides dataclasses and functions for managing session configuration,
+This module provides functions for managing session configuration,
 including region selections, video paths, and project constants.
 """
 
 import json
 import logging
-from dataclasses import asdict, dataclass
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
 
+from config.models import SessionConfig
+
 logger = logging.getLogger(__name__)
 
 # =============================================================================
@@ -34,58 +35,6 @@ EXPECTED_PLAYS_TESTING = 12
 MIN_PLAY_DURATION = 3.0  # seconds
 
 
-# =============================================================================
-# Session Configuration Dataclass
-# =============================================================================
-
-
-@dataclass
-class SessionConfig:  # pylint: disable=too-many-instance-attributes
-    """
-    Configuration for a detection session, including user-specified regions.
-
-    This dataclass contains all the information needed to run play detection
-    on a video, including the selected scorebug, play clock, and timeout regions.
-    """
-
-    # Video settings
-    video_path: str
-    start_time: float
-    end_time: Optional[float]
-
-    # Scorebug region (absolute coordinates in frame)
-    scorebug_x: int
-    scorebug_y: int
-    scorebug_width: int
-    scorebug_height: int
-
-    # Play clock region (relative to scorebug)
-    playclock_x_offset: int
-    playclock_y_offset: int
-    playclock_width: int
-    playclock_height: int
-
-    # Timeout tracker regions (absolute coordinates in frame)
-    # Home team timeout indicators (3 ovals stacked vertically)
-    home_timeout_x: int = 0
-    home_timeout_y: int = 0
-    home_timeout_width: int = 0
-    home_timeout_height: int = 0
-
-    # Away team timeout indicators (3 ovals stacked vertically)
-    away_timeout_x: int = 0
-    away_timeout_y: int = 0
-    away_timeout_width: int = 0
-    away_timeout_height: int = 0
-
-    # Generated paths
-    template_path: str = ""
-    config_path: str = ""
-
-    # Video identifier for output naming
-    video_basename: str = ""
-
-
 # =============================================================================
 # Utility Functions
 # =============================================================================
@@ -154,67 +103,88 @@ def format_time(seconds: float) -> str:
 
 
 # =============================================================================
-# Save/Load Functions
+# Save/Load Helper Functions
 # =============================================================================
 
 
-# pylint: disable=too-many-locals
-def save_session_config(
-    config: SessionConfig,
-    output_dir: Path,
-    selected_frame: Tuple[float, np.ndarray] = None,
-) -> Tuple[str, str]:
+def _save_config_json(config: SessionConfig, output_dir: Path, basename: str) -> Path:
     """
-    Save session configuration and generate template image.
+    Save the main session configuration as JSON.
 
     Args:
         config: Session configuration to save.
         output_dir: Output directory.
-        selected_frame: The specific (timestamp, frame) tuple selected during
-                       region selection. Used to generate template image.
+        basename: Base name for the output file.
 
     Returns:
-        Tuple of (config_path, template_path).
+        Path to the saved config file.
     """
-    output_dir.mkdir(parents=True, exist_ok=True)
-    basename = config.video_basename
-
-    # Save config JSON with video-specific name
     config_path = output_dir / f"{basename}_config.json"
-    config_dict = asdict(config)
+    config_dict = config.model_dump()
     with open(config_path, "w", encoding="utf-8") as f:
         json.dump(config_dict, f, indent=2)
     logger.info("Config saved to: %s", config_path)
+    return config_path
 
-    # Generate template from selected frame (if provided) or from video
-    template_path = output_dir / f"{basename}_template.png"
+
+def _extract_frame_from_video(video_path: str, timestamp: float) -> np.ndarray[Any, Any] | None:
+    """
+    Extract a single frame from a video at the given timestamp.
+
+    Args:
+        video_path: Path to the video file.
+        timestamp: Time in seconds to extract the frame.
+
+    Returns:
+        The extracted frame as a numpy array, or None if extraction failed.
+    """
+    cap = cv2.VideoCapture(video_path)
     frame = None
+    if cap.isOpened():
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        frame_number = int(timestamp * fps)
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+        ret, frame = cap.read()
+        if not ret:
+            frame = None
+        cap.release()
+    return frame
+
+
+def _save_template_image(config: SessionConfig, output_dir: Path, basename: str, frame: np.ndarray[Any, Any]) -> Path:
+    """
+    Extract the scorebug region from a frame and save it as the template image.
 
-    if selected_frame is not None:
-        # Use the specific frame that was selected during scorebug selection
-        timestamp, frame = selected_frame
-        logger.info("Using selected frame @ %.1fs for template generation", timestamp)
-    else:
-        # Fallback: extract from video at start_time
-        cap = cv2.VideoCapture(config.video_path)
-        if cap.isOpened():
-            fps = cap.get(cv2.CAP_PROP_FPS)
-            frame_number = int(config.start_time * fps)
-            cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
-            ret, frame = cap.read()
-            if not ret:
-                frame = None
-            cap.release()
+    Args:
+        config: Session configuration with scorebug coordinates.
+        output_dir: Output directory.
+        basename: Base name for the output file.
+        frame: The frame to extract the template from.
 
-    if frame is not None:
-        # Extract scorebug region as template
-        sb_x, sb_y = config.scorebug_x, config.scorebug_y
-        sb_w, sb_h = config.scorebug_width, config.scorebug_height
-        template = frame[sb_y : sb_y + sb_h, sb_x : sb_x + sb_w]
-        cv2.imwrite(str(template_path), template)
-        logger.info("Template saved to: %s", template_path)
-
-    # Also save play clock region config in the format expected by PlayClockReader
+    Returns:
+        Path to the saved template image.
+    """
+    template_path = output_dir / f"{basename}_template.png"
+    sb_x, sb_y = config.scorebug_x, config.scorebug_y
+    sb_w, sb_h = config.scorebug_width, config.scorebug_height
+    template = frame[sb_y : sb_y + sb_h, sb_x : sb_x + sb_w]
+    cv2.imwrite(str(template_path), template)
+    logger.info("Template saved to: %s", template_path)
+    return template_path
+
+
+def _save_playclock_config(config: SessionConfig, output_dir: Path, basename: str) -> Path:
+    """
+    Save the play clock region configuration in the format expected by ReadPlayClock.
+
+    Args:
+        config: Session configuration with play clock coordinates.
+        output_dir: Output directory.
+        basename: Base name for the output file.
+
+    Returns:
+        Path to the saved playclock config file.
+    """
     playclock_config_path = output_dir / f"{basename}_playclock_config.json"
     playclock_config = {
         "x_offset": config.playclock_x_offset,
@@ -227,34 +197,101 @@ def save_session_config(
     }
     with open(playclock_config_path, "w", encoding="utf-8") as f:
         json.dump(playclock_config, f, indent=2)
+    logger.info("Playclock config saved to: %s", playclock_config_path)
+    return playclock_config_path
+
 
-    # Save timeout tracker config in the format expected by TimeoutTracker
-    if config.home_timeout_width > 0 and config.away_timeout_width > 0:
-        timeout_config_path = output_dir / f"{basename}_timeout_config.json"
-        timeout_config = {
-            "home_timeout_region": {
-                "team_name": "home",
-                "bbox": {
-                    "x": config.home_timeout_x,
-                    "y": config.home_timeout_y,
-                    "width": config.home_timeout_width,
-                    "height": config.home_timeout_height,
-                },
+def _save_timeout_config(config: SessionConfig, output_dir: Path, basename: str) -> Path | None:
+    """
+    Save the timeout tracker configuration in the format expected by DetectTimeouts.
+
+    Only saves if both home and away timeout regions are configured.
+
+    Args:
+        config: Session configuration with timeout region coordinates.
+        output_dir: Output directory.
+        basename: Base name for the output file.
+
+    Returns:
+        Path to the saved timeout config file, or None if not configured.
+    """
+    # Only save if timeout regions are configured
+    if config.home_timeout_width <= 0 or config.away_timeout_width <= 0:
+        return None
+
+    timeout_config_path = output_dir / f"{basename}_timeout_config.json"
+    timeout_config = {
+        "home_timeout_region": {
+            "team_name": "home",
+            "bbox": {
+                "x": config.home_timeout_x,
+                "y": config.home_timeout_y,
+                "width": config.home_timeout_width,
+                "height": config.home_timeout_height,
             },
-            "away_timeout_region": {
-                "team_name": "away",
-                "bbox": {
-                    "x": config.away_timeout_x,
-                    "y": config.away_timeout_y,
-                    "width": config.away_timeout_width,
-                    "height": config.away_timeout_height,
-                },
+        },
+        "away_timeout_region": {
+            "team_name": "away",
+            "bbox": {
+                "x": config.away_timeout_x,
+                "y": config.away_timeout_y,
+                "width": config.away_timeout_width,
+                "height": config.away_timeout_height,
             },
-            "source_video": Path(config.video_path).name,
-        }
-        with open(timeout_config_path, "w", encoding="utf-8") as f:
-            json.dump(timeout_config, f, indent=2)
-        logger.info("Timeout tracker config saved to: %s", timeout_config_path)
+        },
+        "source_video": Path(config.video_path).name,
+    }
+    with open(timeout_config_path, "w", encoding="utf-8") as f:
+        json.dump(timeout_config, f, indent=2)
+    logger.info("Timeout tracker config saved to: %s", timeout_config_path)
+    return timeout_config_path
+
+
+# =============================================================================
+# Save/Load Functions
+# =============================================================================
+
+
+def save_session_config(
+    config: SessionConfig,
+    output_dir: Path,
+    selected_frame: Tuple[float, np.ndarray[Any, Any]] | None = None,
+) -> Tuple[str, str]:
+    """
+    Save session configuration and generate template image.
+
+    Args:
+        config: Session configuration to save.
+        output_dir: Output directory.
+        selected_frame: The specific (timestamp, frame) tuple selected during
+                       region selection. Used to generate template image.
+
+    Returns:
+        Tuple of (config_path, template_path).
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    basename = config.video_basename
+
+    # Save the main session config JSON
+    config_path = _save_config_json(config, output_dir, basename)
+
+    # Get frame for template generation
+    frame: Optional[np.ndarray[Any, Any]] = None
+    if selected_frame is not None:
+        timestamp, frame = selected_frame
+        logger.info("Using selected frame @ %.1fs for template generation", timestamp)
+    else:
+        # Fallback: extract from video at start_time
+        frame = _extract_frame_from_video(config.video_path, config.start_time)
+
+    # Save template image from the frame
+    template_path = output_dir / f"{basename}_template.png"
+    if frame is not None:
+        template_path = _save_template_image(config, output_dir, basename, frame)
+
+    # Save auxiliary config files
+    _save_playclock_config(config, output_dir, basename)
+    _save_timeout_config(config, output_dir, basename)
 
     return str(config_path), str(template_path)
 

src/detection/__init__.py

@@ -0,0 +1,26 @@
+"""Detection modules for per-frame analysis during video scanning.
+
+This package contains components that process individual video frames to detect:
+- Scorebug presence and location
+- Timeout indicator states
+"""
+
+from .models import (
+    ScorebugDetection,
+    TimeoutRegionConfig,
+    TimeoutReading,
+)
+from .scorebug import DetectScoreBug, create_template_from_frame
+from .timeouts import DetectTimeouts
+
+__all__ = [
+    # Models
+    "ScorebugDetection",
+    "TimeoutRegionConfig",
+    "TimeoutReading",
+    # Scorebug detection
+    "DetectScoreBug",
+    "create_template_from_frame",
+    # Timeout tracking
+    "DetectTimeouts",
+]

src/detection/models.py

@@ -0,0 +1,51 @@
+"""
+Pydantic models for per-frame detection.
+
+These models represent the results of detecting various elements in video frames:
+scorebug presence and timeout indicators.
+"""
+
+from typing import Any, Optional, Tuple, List
+
+from pydantic import BaseModel, Field
+
+
+class ScorebugDetection(BaseModel):
+    """Results from scorebug detection."""
+
+    detected: bool = Field(..., description="Whether scorebug was detected")
+    confidence: float = Field(..., description="Confidence score (0.0 to 1.0)")
+    bbox: Optional[Tuple[int, int, int, int]] = Field(None, description="Bounding box (x, y, width, height)")
+    method: str = Field("unknown", description="Detection method used")
+    left_confidence: Optional[float] = Field(None, description="Left half confidence (when split detection enabled)")
+    right_confidence: Optional[float] = Field(None, description="Right half confidence (when split detection enabled)")
+
+
+class TimeoutRegionConfig(BaseModel):
+    """Configuration for a team's timeout indicator region."""
+
+    team_name: str = Field(..., description="'home' or 'away'")
+    bbox: Tuple[int, int, int, int] = Field(..., description="x, y, width, height for the 3-oval group")
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "team_name": self.team_name,
+            "bbox": {"x": self.bbox[0], "y": self.bbox[1], "width": self.bbox[2], "height": self.bbox[3]},
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "TimeoutRegionConfig":
+        """Create from dictionary."""
+        bbox = (data["bbox"]["x"], data["bbox"]["y"], data["bbox"]["width"], data["bbox"]["height"])
+        return cls(team_name=data["team_name"], bbox=bbox)
+
+
+class TimeoutReading(BaseModel):
+    """Results from timeout indicator reading."""
+
+    home_timeouts: int = Field(..., description="0-3 timeouts remaining")
+    away_timeouts: int = Field(..., description="0-3 timeouts remaining")
+    confidence: float = Field(..., description="Overall confidence in reading")
+    home_oval_states: Optional[List[bool]] = Field(None, description="True = white (available), False = dark (used)")
+    away_oval_states: Optional[List[bool]] = Field(None, description="True = white (available), False = dark (used)")

src/{detectors/scorebug_detector.py → detection/scorebug.py}

@@ -8,7 +8,7 @@ This module provides functions to detect the presence and location of the scoreb
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
@@ -18,7 +18,7 @@ from .models import ScorebugDetection
 logger = logging.getLogger(__name__)
 
 
-class ScorebugDetector:
+class DetectScoreBug:
     """
     Detects the scorebug in video frames.
 
@@ -55,15 +55,15 @@ class ScorebugDetector:
             fixed_region_config_path: Path to JSON config with fixed region (alternative to fixed_region)
             use_split_detection: Enable split-half detection for robustness to partial overlays (default: True)
         """
-        self.template = None
+        self.template: Optional[np.ndarray[Any, Any]] = None
         self.template_path = template_path
         self.fixed_region = fixed_region
         self._use_fixed_region = fixed_region is not None
         self.use_split_detection = use_split_detection
 
         # Pre-computed template halves for split detection (populated when template is loaded)
-        self._template_left = None
-        self._template_right = None
+        self._template_left: Optional[np.ndarray[Any, Any]] = None
+        self._template_right: Optional[np.ndarray[Any, Any]] = None
 
         if template_path:
             self.load_template(template_path)
@@ -74,10 +74,15 @@ class ScorebugDetector:
 
         mode = "fixed_region" if self._use_fixed_region else "full_search"
         split_mode = "split_detection" if use_split_detection else "full_only"
-        logger.info("ScorebugDetector initialized (template: %s, mode: %s, split: %s)", template_path is not None, mode, split_mode)
+        logger.info("DetectScoreBug initialized (template: %s, mode: %s, split: %s)", template_path is not None, mode, split_mode)
         if self._use_fixed_region:
             logger.info("  Fixed region: %s", self.fixed_region)
 
+    @property
+    def is_fixed_region_mode(self) -> bool:
+        """Check if detector is using fixed region mode for faster detection."""
+        return self._use_fixed_region
+
     def _load_fixed_region_config(self, config_path: str) -> None:
         """Load fixed region from a JSON config file."""
         path = Path(config_path)
@@ -121,7 +126,7 @@ class ScorebugDetector:
                 self._template_right.shape[0],
             )
 
-    def detect(self, frame: np.ndarray) -> ScorebugDetection:
+    def detect(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug in a frame.
 
@@ -162,7 +167,7 @@ class ScorebugDetector:
         return detection
 
     # pylint: disable=too-many-locals
-    def _detect_in_fixed_region(self, frame: np.ndarray) -> ScorebugDetection:
+    def _detect_in_fixed_region(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug by checking only the fixed known location.
 
@@ -180,6 +185,10 @@ class ScorebugDetector:
         Returns:
             Detection result
         """
+        # Asserts: this method should only be called when fixed_region and template are set
+        assert self.fixed_region is not None
+        assert self.template is not None
+
         x, y, _, _ = self.fixed_region
         th, tw = self.template.shape[:2]
 
@@ -239,7 +248,7 @@ class ScorebugDetector:
         return ScorebugDetection(detected=False, confidence=full_confidence, bbox=(x, y, tw, th), method="fixed_region")
 
     # pylint: disable=too-many-locals
-    def _detect_by_template_fullsearch(self, frame: np.ndarray) -> ScorebugDetection:
+    def _detect_by_template_fullsearch(self, frame: np.ndarray[Any, Any]) -> ScorebugDetection:
         """
         Detect scorebug using full-frame template matching.
 
@@ -346,7 +355,7 @@ class ScorebugDetector:
 
         logger.info("Saved fixed region config to: %s", config_path)
 
-    def discover_and_lock_region(self, frame: np.ndarray) -> bool:
+    def discover_and_lock_region(self, frame: np.ndarray[Any, Any]) -> bool:
         """
         Discover scorebug location using full search, then lock to fixed region mode.
 
@@ -371,7 +380,7 @@ class ScorebugDetector:
         self._use_fixed_region = old_use_fixed
         return False
 
-    def visualize_detection(self, frame: np.ndarray, detection: ScorebugDetection) -> np.ndarray:
+    def visualize_detection(self, frame: np.ndarray[Any, Any], detection: ScorebugDetection) -> np.ndarray[Any, Any]:
         """
         Draw detection results on frame for visualization.
 
@@ -398,7 +407,7 @@ class ScorebugDetector:
         return vis_frame
 
 
-def create_template_from_frame(frame: np.ndarray, bbox: Tuple[int, int, int, int], output_path: str) -> None:
+def create_template_from_frame(frame: np.ndarray[Any, Any], bbox: Tuple[int, int, int, int], output_path: str) -> None:
     """
     Extract a region from a frame to use as a template.
 

src/{detectors/timeout_tracker.py → detection/timeouts.py}

@@ -9,7 +9,7 @@ Detecting when an oval changes from white to dark indicates a timeout was called
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple, List
+from typing import Any, Optional, Tuple, List
 
 import cv2
 import numpy as np
@@ -19,7 +19,7 @@ from .models import TimeoutRegionConfig, TimeoutReading
 logger = logging.getLogger(__name__)
 
 
-class TimeoutTracker:
+class DetectTimeouts:
     """
     Tracks timeout indicators on the scorebug.
 
@@ -67,11 +67,11 @@ class TimeoutTracker:
             self._load_config(config_path)
 
         if self._configured:
-            logger.info("TimeoutTracker initialized with regions")
+            logger.info("DetectTimeouts initialized with regions")
             logger.info("  Home region: %s", self.home_region.bbox if self.home_region else None)
             logger.info("  Away region: %s", self.away_region.bbox if self.away_region else None)
         else:
-            logger.info("TimeoutTracker initialized (not configured - call configure_regions first)")
+            logger.info("DetectTimeouts initialized (not configured - call configure_regions first)")
 
     def _load_config(self, config_path: str) -> None:
         """Load timeout regions from a JSON config file."""
@@ -128,7 +128,7 @@ class TimeoutTracker:
         self._configured = True
         logger.info("Timeout regions set: home=%s, away=%s", home_region.bbox, away_region.bbox)
 
-    def _extract_oval_bright_ratios(self, frame: np.ndarray, region: TimeoutRegionConfig) -> List[float]:
+    def _extract_oval_bright_ratios(self, frame: np.ndarray[Any, Any], region: TimeoutRegionConfig) -> List[float]:
         """
         Extract the ratio of bright pixels for each oval in a region.
 
@@ -194,7 +194,7 @@ class TimeoutTracker:
         """Count how many timeouts are available (white ovals)."""
         return sum(1 for state in oval_states if state)
 
-    def read_timeouts(self, frame: np.ndarray) -> TimeoutReading:
+    def read_timeouts(self, frame: np.ndarray[Any, Any]) -> TimeoutReading:
         """
         Read the current timeout count for each team.
 
@@ -208,6 +208,10 @@ class TimeoutTracker:
             logger.warning("Timeout tracker not configured")
             return TimeoutReading(home_timeouts=3, away_timeouts=3, confidence=0.0)
 
+        # Asserts: _configured guarantees regions are set
+        assert self.home_region is not None
+        assert self.away_region is not None
+
         # Read home team timeouts using bright pixel ratio
         home_bright_ratios = self._extract_oval_bright_ratios(frame, self.home_region)
         home_states = self._classify_ovals(home_bright_ratios)
@@ -291,7 +295,7 @@ class TimeoutTracker:
         self._prev_reading = curr_reading
         return result
 
-    def update(self, frame: np.ndarray) -> Tuple[TimeoutReading, Optional[str]]:
+    def update(self, frame: np.ndarray[Any, Any]) -> Tuple[TimeoutReading, Optional[str]]:
         """
         Read timeouts and detect any change in one call.
 
@@ -310,7 +314,7 @@ class TimeoutTracker:
         self._prev_reading = None
         logger.debug("Timeout tracking reset")
 
-    def visualize(self, frame: np.ndarray, reading: Optional[TimeoutReading] = None) -> np.ndarray:
+    def visualize(self, frame: np.ndarray[Any, Any], reading: Optional[TimeoutReading] = None) -> np.ndarray[Any, Any]:
         """
         Draw timeout regions and states on frame for visualization.
 

src/detectors/__init__.py

@@ -1,55 +0,0 @@
-"""Detector modules for identifying game elements."""
-
-# Models (dataclasses)
-from .models import (
-    ScorebugDetection,
-    PlayClockReading,
-    PlayClockRegionConfig,
-    TimeoutRegionConfig,
-    TimeoutReading,
-    PlayEvent,
-    DigitSample,
-    DigitTemplate,
-    TemplateMatchResult,
-    TemplatePlayClockReading,
-)
-
-# Detector classes
-from .scorebug_detector import ScorebugDetector, create_template_from_frame
-from .play_clock_reader import PlayClockReader
-from .play_state_machine import PlayStateMachine, PlayState
-from .timeout_tracker import TimeoutTracker
-from .digit_template_reader import (
-    DigitTemplateLibrary,
-    DigitTemplateBuilder,
-    TemplatePlayClockReader,
-    normalize_to_grayscale,
-    detect_red_digits,
-)
-
-__all__ = [
-    # Models
-    "ScorebugDetection",
-    "PlayClockReading",
-    "PlayClockRegionConfig",
-    "TimeoutRegionConfig",
-    "TimeoutReading",
-    "PlayEvent",
-    "DigitSample",
-    "DigitTemplate",
-    "TemplateMatchResult",
-    "TemplatePlayClockReading",
-    # Detectors
-    "ScorebugDetector",
-    "create_template_from_frame",
-    "PlayClockReader",
-    "PlayStateMachine",
-    "PlayState",
-    "TimeoutTracker",
-    # Template-based play clock reader
-    "DigitTemplateLibrary",
-    "DigitTemplateBuilder",
-    "TemplatePlayClockReader",
-    "normalize_to_grayscale",
-    "detect_red_digits",
-]

src/detectors/digit_template_reader.py

@@ -1,1113 +0,0 @@
-# pylint: disable=too-many-lines
-"""
-Template-based play clock reader using digit template matching.
-
-This module provides fast play clock reading using template matching instead of OCR.
-Templates are built from OCR-labeled samples during an initial collection phase,
-then used for lightning-fast digit recognition on all subsequent frames.
-
-Performance comparison (from ocr_benchmark.md):
-- EasyOCR: 48.9ms/frame
-- Template Matching: 0.3ms/frame (163x faster)
-
-The play clock displays values 0-40 and turns RED when <= 5 seconds remain.
-A color normalization step converts red digits to white-like appearance.
-
-Implements dual-mode matching to handle both display layouts:
-- Single-digit (0-9): Digit is CENTER-aligned (10 templates: ones_center)
-- Double-digit (10-40): Tens on LEFT, ones on RIGHT (14 templates: ones_right + tens)
-- Plus 1 blank template for detecting empty tens position
-Total: 25 templates needed for full coverage.
-"""
-
-import json
-import logging
-from pathlib import Path
-from typing import Dict, List, Optional, Tuple
-
-import cv2
-import numpy as np
-
-from .models import DigitSample, DigitTemplate, TemplateMatchResult, TemplatePlayClockReading
-
-logger = logging.getLogger(__name__)
-
-
-def detect_red_digits(region: np.ndarray) -> bool:
-    """
-    Detect if the play clock digits are red.
-
-    Red digits appear when the play clock has 5 seconds or less remaining.
-    Red digits have high red channel values with very low green and blue.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        True if red digits detected, False otherwise
-    """
-    # Split into BGR channels
-    b, g, r = cv2.split(region)
-
-    # Calculate mean values for each channel
-    r_mean = np.mean(r)
-    g_mean = np.mean(g)
-    b_mean = np.mean(b)
-
-    # Red digits: high red channel, very low green/blue, red > 2x green
-    # pylint: disable=chained-comparison
-    is_red = r_mean > 15 and max(g_mean, b_mean) < 15 and r_mean > (g_mean * 2)
-
-    if is_red:
-        logger.debug("Red digits detected: R=%.1f, G=%.1f, B=%.1f", r_mean, g_mean, b_mean)
-
-    return is_red
-
-
-def normalize_to_grayscale(region: np.ndarray) -> np.ndarray:
-    """
-    Normalize a play clock region to grayscale, handling both red and white digits.
-
-    Red digits (displayed when clock <= 5) are converted to white-like grayscale
-    by extracting the red channel. White digits use standard grayscale conversion.
-    This allows a single set of templates to match both color variants.
-
-    Args:
-        region: Play clock region (BGR format)
-
-    Returns:
-        Grayscale image where digits appear as bright pixels on dark background
-    """
-    is_red = detect_red_digits(region)
-
-    if is_red:
-        # For red digits, use the red channel directly as grayscale
-        # This converts red digits to white-like appearance
-        _, _, r = cv2.split(region)
-        return r
-
-    # Standard grayscale conversion for white digits
-    return cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
-
-
-class DigitTemplateLibrary:
-    """
-    Stores and manages digit templates for play clock reading.
-
-    Uses color normalization to handle both red and white digits with a single
-    template set. Now supports position-aware templates to handle both single-digit
-    (centered) and double-digit (left/right split) layouts:
-    - Ones digits (center): 0-9 from single-digit displays (10 templates)
-    - Ones digits (right): 0-9 from double-digit displays (10 templates)
-    - Tens digits (left): 1, 2, 3, 4 from double-digit displays (4 templates)
-    - Blank (left): Empty tens position from single-digit displays (1 template)
-    Total: 25 templates needed for full coverage
-    """
-
-    # Template coverage requirements
-    ONES_DIGITS = list(range(10))  # 0-9
-    TENS_DIGITS = [-1, 1, 2, 3, 4]  # -1 = blank, 1-4 for 10-40
-    POSITIONS = ["left", "center", "right"]
-
-    def __init__(self):
-        """Initialize empty template library."""
-        # Templates: {(is_tens, digit_value, position): DigitTemplate}
-        self.templates: Dict[Tuple[bool, int, str], DigitTemplate] = {}
-        logger.info("DigitTemplateLibrary initialized (empty)")
-
-    def add_template(self, template: DigitTemplate) -> None:
-        """
-        Add a template to the library.
-
-        Args:
-            template: DigitTemplate to add
-        """
-        key = (template.is_tens_digit, template.digit_value, template.position)
-        self.templates[key] = template
-        digit_display = "blank" if template.digit_value == -1 else str(template.digit_value)
-        logger.debug(
-            "Added template: tens=%s, digit=%s, position=%s",
-            template.is_tens_digit,
-            digit_display,
-            template.position,
-        )
-
-    def get_template(self, is_tens: bool, digit_value: int, position: str) -> Optional[DigitTemplate]:
-        """
-        Get a template from the library.
-
-        Args:
-            is_tens: Whether this is a tens digit
-            digit_value: The digit value (-1 for blank, 0-9 for digits)
-            position: Template position ("left", "center", or "right")
-
-        Returns:
-            DigitTemplate if found, None otherwise
-        """
-        key = (is_tens, digit_value, position)
-        return self.templates.get(key)
-
-    def get_all_templates(self, is_tens: bool, position: Optional[str] = None) -> List[DigitTemplate]:
-        """
-        Get all templates for a specific digit position.
-
-        Args:
-            is_tens: Whether to get tens digit templates
-            position: Optional position filter ("left", "center", or "right")
-
-        Returns:
-            List of matching DigitTemplate objects
-        """
-        templates = []
-        for (tens, _, pos), template in self.templates.items():
-            if tens == is_tens:
-                if position is None or pos == position:
-                    templates.append(template)
-        return templates
-
-    def get_coverage_status(self) -> Dict[str, any]:
-        """
-        Get the current template coverage status.
-
-        Returns:
-            Dictionary with coverage information
-        """
-        ones_center_have = set()
-        ones_right_have = set()
-        tens_have = set()
-        has_blank = False
-
-        for (is_tens, digit, position), _ in self.templates.items():
-            if is_tens:
-                if digit == -1:
-                    has_blank = True
-                else:
-                    tens_have.add(digit)
-            else:
-                if position == "center":
-                    ones_center_have.add(digit)
-                elif position == "right":
-                    ones_right_have.add(digit)
-
-        ones_center_missing = set(self.ONES_DIGITS) - ones_center_have
-        ones_right_missing = set(self.ONES_DIGITS) - ones_right_have
-        tens_missing = set([1, 2, 3, 4]) - tens_have
-
-        # Calculate totals
-        # ones_center (10) + ones_right (10) + tens (4) + blank (1) = 25
-        total_needed = 25
-        total_have = len(self.templates)
-
-        # Convert -1 to "blank" for display
-        def format_tens(digits):
-            return sorted(["blank" if d == -1 else d for d in digits], key=lambda x: (isinstance(x, str), x))
-
-        return {
-            "total_needed": total_needed,
-            "total_have": total_have,
-            "is_complete": total_have >= total_needed,
-            "ones_center_have": sorted(ones_center_have),
-            "ones_center_missing": sorted(ones_center_missing),
-            "ones_right_have": sorted(ones_right_have),
-            "ones_right_missing": sorted(ones_right_missing),
-            "tens_have": sorted(tens_have),
-            "tens_missing": sorted(tens_missing),
-            "has_blank": has_blank,
-            # Legacy fields for backward compatibility
-            "ones_have": sorted(ones_center_have | ones_right_have),
-            "ones_missing": sorted(ones_center_missing & ones_right_missing),
-            "tens_have_formatted": format_tens(tens_have | ({-1} if has_blank else set())),
-            "tens_missing_formatted": format_tens(tens_missing | (set() if has_blank else {-1})),
-        }
-
-    def is_complete(self) -> bool:
-        """Check if all required templates are present."""
-        return self.get_coverage_status()["is_complete"]
-
-    def save(self, output_path: str) -> None:
-        """
-        Save templates to disk.
-
-        Args:
-            output_path: Path to save directory
-        """
-        output_dir = Path(output_path)
-        output_dir.mkdir(parents=True, exist_ok=True)
-
-        metadata = {"templates": [], "version": 2}  # Version 2 includes position
-
-        for (is_tens, digit, position), template in self.templates.items():
-            # Use "blank" instead of -1 for the empty tens digit in filenames
-            digit_str = "blank" if digit == -1 else str(digit)
-            position_suffix = f"_{position}" if position != "left" or not is_tens else ""
-            filename = f"{'tens' if is_tens else 'ones'}_{digit_str}{position_suffix}.png"
-            cv2.imwrite(str(output_dir / filename), template.template)
-            metadata["templates"].append(
-                {
-                    "filename": filename,
-                    "digit_value": digit_str,  # Use "blank" for display
-                    "is_tens_digit": template.is_tens_digit,
-                    "position": position,
-                    "sample_count": template.sample_count,
-                    "avg_confidence": template.avg_confidence,
-                }
-            )
-
-        with open(output_dir / "templates_metadata.json", "w", encoding="utf-8") as f:
-            json.dump(metadata, f, indent=2)
-
-        logger.info("Saved %d templates to %s", len(self.templates), output_path)
-
-    def load(self, input_path: str) -> bool:
-        """
-        Load templates from disk.
-
-        Args:
-            input_path: Path to templates directory
-
-        Returns:
-            True if loaded successfully, False otherwise
-        """
-        input_dir = Path(input_path)
-        metadata_path = input_dir / "templates_metadata.json"
-
-        if not metadata_path.exists():
-            logger.warning("No templates metadata found at %s", metadata_path)
-            return False
-
-        with open(metadata_path, "r", encoding="utf-8") as f:
-            metadata = json.load(f)
-
-        version = metadata.get("version", 1)
-
-        for entry in metadata.get("templates", []):
-            img_path = input_dir / entry["filename"]
-            if img_path.exists():
-                template_img = cv2.imread(str(img_path), cv2.IMREAD_GRAYSCALE)
-                if template_img is not None:
-                    # Convert "blank" back to -1 for internal use
-                    digit_value = entry["digit_value"]
-                    if digit_value == "blank":
-                        digit_value = -1
-                    elif isinstance(digit_value, str):
-                        digit_value = int(digit_value)
-
-                    # Handle position (v2) or infer from old format (v1)
-                    is_tens = entry["is_tens_digit"]
-                    if version >= 2:
-                        position = entry.get("position", "left" if is_tens else "right")
-                    else:
-                        # V1 format: tens → left, ones → right (old behavior)
-                        position = "left" if is_tens else "right"
-
-                    template = DigitTemplate(
-                        digit_value=digit_value,
-                        is_tens_digit=is_tens,
-                        position=position,
-                        template=template_img,
-                        sample_count=entry.get("sample_count", 1),
-                        avg_confidence=entry.get("avg_confidence", 1.0),
-                    )
-                    self.add_template(template)
-
-        logger.info("Loaded %d templates from %s (v%d format)", len(self.templates), input_path, version)
-        return True
-
-
-class DigitTemplateBuilder:
-    """
-    Builds digit templates from OCR-labeled play clock samples.
-
-    Collects samples from the play clock region, extracts individual digits,
-    and builds averaged templates for each unique digit value.
-
-    Uses color normalization so red and white digits produce the same template.
-    """
-
-    # Play clock region dimensions (from config)
-    DEFAULT_REGION_WIDTH = 50
-    DEFAULT_REGION_HEIGHT = 28
-
-    def __init__(self, region_width: int = DEFAULT_REGION_WIDTH, region_height: int = DEFAULT_REGION_HEIGHT):
-        """
-        Initialize the template builder.
-
-        Args:
-            region_width: Width of play clock region in pixels
-            region_height: Height of play clock region in pixels
-        """
-        self.region_width = region_width
-        self.region_height = region_height
-
-        # Collected samples: {(is_tens, digit_value): [DigitSample, ...]}
-        self.samples: Dict[Tuple[bool, int], List[DigitSample]] = {}
-
-        # Track raw clock region images for potential reprocessing
-        self.raw_regions: List[Tuple[float, int, np.ndarray]] = []  # (timestamp, clock_value, region)
-
-        logger.info("DigitTemplateBuilder initialized (region: %dx%d)", region_width, region_height)
-
-    def preprocess_region(self, region: np.ndarray) -> np.ndarray:
-        """
-        Preprocess play clock region for template extraction.
-
-        Uses color normalization to handle both red and white digits uniformly.
-
-        Args:
-            region: Play clock region (BGR format)
-
-        Returns:
-            Preprocessed binary image (white digits on black background)
-        """
-        # Normalize color (red → white conversion happens here)
-        gray = normalize_to_grayscale(region)
-
-        # Scale up for better template quality
-        scale_factor = 4
-        scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
-
-        # Use Otsu's thresholding
-        _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-
-        # Ensure white digits on black background (digits should be bright)
-        mean_intensity = np.mean(binary)
-        if mean_intensity > 128:
-            binary = cv2.bitwise_not(binary)
-
-        return binary
-
-    def extract_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the left (tens digit) region from preprocessed play clock.
-
-        Used for tens digits in double-digit displays (10-40).
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Left region image for tens digit
-        """
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, : mid_x - 2]  # Small gap in middle
-
-    def extract_far_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the far left region from preprocessed play clock.
-
-        Used for blank detection in single-digit displays (0-9). This narrow
-        region (0%-20% of width) doesn't overlap with a centered digit,
-        so it should be truly empty when the clock shows a single digit.
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Far left region image (should be mostly black for single digits)
-        """
-        _, w = preprocessed.shape[:2]
-        # Far left: 0% to 20% of width - avoids overlap with centered digit
-        far_left_end = int(w * 0.20)
-        return preprocessed[:, :far_left_end]
-
-    def extract_right_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the right (ones digit) region from preprocessed play clock.
-
-        Used for ones digits in double-digit displays (10-40).
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Right region image for ones digit
-        """
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, mid_x + 2 :]
-
-    def extract_center_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """
-        Extract the center region from preprocessed play clock.
-
-        Used for ones digits in single-digit displays (0-9) where the
-        digit is center-aligned rather than right-aligned.
-
-        The center region spans approximately 60% of the width, centered.
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-
-        Returns:
-            Center region image for centered single digit
-        """
-        _, w = preprocessed.shape[:2]
-
-        # Center region: ~20% padding on each side, capturing middle 60%
-        # This encompasses where a centered single digit would appear
-        center_start = int(w * 0.20)
-        center_end = int(w * 0.80)
-
-        return preprocessed[:, center_start:center_end]
-
-    def extract_digits(self, preprocessed: np.ndarray, clock_value: int) -> Tuple[np.ndarray, np.ndarray, Optional[np.ndarray], Optional[np.ndarray]]:
-        """
-        Extract individual digit images from preprocessed play clock region.
-
-        For double-digit values (10-40): extracts left (tens) and right (ones)
-        For single-digit values (0-9): extracts far-left (blank) and center (ones)
-
-        Args:
-            preprocessed: Preprocessed play clock image (scaled 4x)
-            clock_value: The known clock value (0-40)
-
-        Returns:
-            Tuple of (tens_digit_image, ones_right_image, ones_center_image, blank_image)
-            - For double-digit: tens=left, ones_right=right, ones_center=None, blank=None
-            - For single-digit: tens=None, ones_right=None, ones_center=center, blank=far_left
-        """
-        if clock_value >= 10:
-            # Double-digit: standard left/right split
-            return self.extract_left_region(preprocessed), self.extract_right_region(preprocessed), None, None
-        # Single-digit: far-left is blank (truly empty), ones is centered
-        return None, None, self.extract_center_region(preprocessed), self.extract_far_left_region(preprocessed)
-
-    def add_sample(self, region: np.ndarray, clock_value: int, timestamp: float, confidence: float = 1.0) -> None:
-        """
-        Add a play clock sample for template building.
-
-        Routes samples based on display layout:
-        - Single-digit (0-9): Digit is CENTER-aligned, tens position is blank
-        - Double-digit (10-40): Tens on LEFT, ones on RIGHT
-
-        Args:
-            region: Play clock region (BGR format, original size)
-            clock_value: OCR-determined clock value (0-40)
-            timestamp: Video timestamp
-            confidence: OCR confidence score
-        """
-        if clock_value < 0 or clock_value > 40:
-            logger.warning("Invalid clock value %d, skipping sample", clock_value)
-            return
-
-        # Store raw region for potential reprocessing
-        self.raw_regions.append((timestamp, clock_value, region.copy()))
-
-        # Preprocess (handles red-to-white conversion automatically)
-        preprocessed = self.preprocess_region(region)
-
-        # Extract digits based on single vs double digit display
-        tens_img, ones_right_img, ones_center_img, blank_img = self.extract_digits(preprocessed, clock_value)
-
-        # Determine digit values
-        ones_digit = clock_value % 10
-        tens_digit = clock_value // 10 if clock_value >= 10 else -1  # -1 = blank
-
-        if clock_value >= 10:
-            # Double-digit display (10-40): tens on left, ones on right
-            # Store tens sample (left position)
-            tens_sample = DigitSample(
-                digit_value=tens_digit,
-                is_tens_digit=True,
-                position="left",
-                image=tens_img,
-                source_clock_value=clock_value,
-                timestamp=timestamp,
-                confidence=confidence,
-            )
-            tens_key = (True, tens_digit, "left")
-            if tens_key not in self.samples:
-                self.samples[tens_key] = []
-            self.samples[tens_key].append(tens_sample)
-
-            # Store ones sample (right position)
-            ones_sample = DigitSample(
-                digit_value=ones_digit,
-                is_tens_digit=False,
-                position="right",
-                image=ones_right_img,
-                source_clock_value=clock_value,
-                timestamp=timestamp,
-                confidence=confidence,
-            )
-            ones_key = (False, ones_digit, "right")
-            if ones_key not in self.samples:
-                self.samples[ones_key] = []
-            self.samples[ones_key].append(ones_sample)
-
-            logger.debug(
-                "Added double-digit sample: clock=%d, tens=%d (left), ones=%d (right), t=%.1f",
-                clock_value,
-                tens_digit,
-                ones_digit,
-                timestamp,
-            )
-        else:
-            # Single-digit display (0-9): digit is centered, tens position is blank
-            # Store blank sample (far-left position - should be truly empty)
-            blank_sample = DigitSample(
-                digit_value=-1,  # blank
-                is_tens_digit=True,
-                position="left",  # Still use "left" as the position key for compatibility
-                image=blank_img,  # Now using far-left region that's truly empty
-                source_clock_value=clock_value,
-                timestamp=timestamp,
-                confidence=confidence,
-            )
-            blank_key = (True, -1, "left")
-            if blank_key not in self.samples:
-                self.samples[blank_key] = []
-            self.samples[blank_key].append(blank_sample)
-
-            # Store ones sample (center position)
-            ones_sample = DigitSample(
-                digit_value=ones_digit,
-                is_tens_digit=False,
-                position="center",
-                image=ones_center_img,
-                source_clock_value=clock_value,
-                timestamp=timestamp,
-                confidence=confidence,
-            )
-            ones_key = (False, ones_digit, "center")
-            if ones_key not in self.samples:
-                self.samples[ones_key] = []
-            self.samples[ones_key].append(ones_sample)
-
-            logger.debug(
-                "Added single-digit sample: clock=%d, ones=%d (center), blank (far-left), t=%.1f",
-                clock_value,
-                ones_digit,
-                timestamp,
-            )
-
-    def get_sample_count(self) -> Dict[str, int]:
-        """Get count of samples collected for each digit and position."""
-        counts = {}
-        for (is_tens, digit, position), samples in self.samples.items():
-            type_str = "tens" if is_tens else "ones"
-            digit_str = "blank" if digit == -1 else str(digit)
-            key = f"{type_str}_{digit_str}_{position}"
-            counts[key] = len(samples)
-        return counts
-
-    def build_templates(self, min_samples: int = 3) -> DigitTemplateLibrary:
-        """
-        Build templates from collected samples.
-
-        For each digit/position combination, averages multiple samples
-        to create a robust template.
-
-        Args:
-            min_samples: Minimum samples required to build a template (default: 3)
-
-        Returns:
-            DigitTemplateLibrary with built templates
-        """
-        library = DigitTemplateLibrary()
-
-        for (is_tens, digit, position), samples in self.samples.items():
-            if len(samples) < min_samples:
-                digit_display = "blank" if digit == -1 else str(digit)
-                logger.warning(
-                    "Insufficient samples for %s digit %s (%s): %d < %d",
-                    "tens" if is_tens else "ones",
-                    digit_display,
-                    position,
-                    len(samples),
-                    min_samples,
-                )
-                continue
-
-            # Resize all samples to match dimensions of first sample
-            target_shape = samples[0].image.shape
-
-            # Average the samples (with resizing if needed)
-            sum_image = np.zeros(target_shape, dtype=np.float32)
-            valid_count = 0
-            total_confidence = 0.0
-
-            for sample in samples:
-                img = sample.image
-                if img.shape != target_shape:
-                    img = cv2.resize(img, (target_shape[1], target_shape[0]))
-                sum_image += img.astype(np.float32)
-                valid_count += 1
-                total_confidence += sample.confidence
-
-            if valid_count > 0:
-                avg_image = (sum_image / valid_count).astype(np.uint8)
-
-                # Threshold the averaged image to clean it up
-                _, template_img = cv2.threshold(avg_image, 127, 255, cv2.THRESH_BINARY)
-
-                template = DigitTemplate(
-                    digit_value=digit,
-                    is_tens_digit=is_tens,
-                    position=position,
-                    template=template_img,
-                    sample_count=valid_count,
-                    avg_confidence=total_confidence / valid_count,
-                )
-
-                library.add_template(template)
-                digit_display = "blank" if digit == -1 else str(digit)
-                logger.info(
-                    "Built template: %s digit %s (%s) from %d samples",
-                    "tens" if is_tens else "ones",
-                    digit_display,
-                    position,
-                    valid_count,
-                )
-
-        # Log coverage status
-        coverage = library.get_coverage_status()
-        logger.info(
-            "Template coverage: %d/%d (%.1f%%)",
-            coverage["total_have"],
-            coverage["total_needed"],
-            100 * coverage["total_have"] / coverage["total_needed"],
-        )
-
-        return library
-
-    def get_coverage_status(self) -> Dict[str, any]:
-        """Get current sample coverage status."""
-        ones_center_have = set()
-        ones_right_have = set()
-        tens_have = set()
-        has_blank = False
-
-        for (is_tens, digit, position), samples in self.samples.items():
-            if len(samples) >= 1:  # At least one sample
-                if is_tens:
-                    if digit == -1:
-                        has_blank = True
-                    else:
-                        tens_have.add(digit)
-                else:
-                    if position == "center":
-                        ones_center_have.add(digit)
-                    elif position == "right":
-                        ones_right_have.add(digit)
-
-        return {
-            "ones_center": sorted(ones_center_have),
-            "ones_right": sorted(ones_right_have),
-            "tens": sorted(tens_have),
-            "has_blank": has_blank,
-            "ones_center_missing": sorted(set(DigitTemplateLibrary.ONES_DIGITS) - ones_center_have),
-            "ones_right_missing": sorted(set(DigitTemplateLibrary.ONES_DIGITS) - ones_right_have),
-            "tens_missing": sorted(set([1, 2, 3, 4]) - tens_have),
-        }
-
-    def get_coverage_estimate(self) -> float:
-        """
-        Get a simple coverage estimate as a float (0.0-1.0).
-
-        Returns:
-            Coverage estimate where 1.0 = all templates have samples
-        """
-        status = self.get_coverage_status()
-
-        # Count what we have (with at least 1 sample each)
-        total_have = len(status["ones_center"]) + len(status["ones_right"]) + len(status["tens"])
-        if status["has_blank"]:
-            total_have += 1
-
-        # Total needed: 10 ones_center + 10 ones_right + 4 tens + 1 blank = 25
-        total_needed = 25
-
-        return total_have / total_needed
-
-
-class TemplatePlayClockReader:
-    """
-    Reads play clock values using template matching with dual-mode detection.
-
-    Uses digit templates built from OCR-labeled samples to achieve
-    lightning-fast digit recognition (~0.3ms/frame vs ~49ms for OCR).
-
-    Implements dual-mode matching to handle both display layouts:
-    - Single-digit (0-9): Digit is CENTER-aligned
-    - Double-digit (10-40): Tens on LEFT, ones on RIGHT
-
-    The reader tries both interpretations and picks the best match.
-
-    Handles slight translational shifts via template matching search window.
-    """
-
-    # Confidence thresholds
-    MIN_DIGIT_CONFIDENCE = 0.6  # Minimum confidence to accept a digit match
-    MIN_CLOCK_CONFIDENCE = 0.5  # Minimum overall confidence to return a reading
-
-    def __init__(self, template_library: DigitTemplateLibrary, region_width: int = 50, region_height: int = 28):
-        """
-        Initialize the template-based clock reader.
-
-        Args:
-            template_library: Pre-built digit template library
-            region_width: Play clock region width
-            region_height: Play clock region height
-        """
-        self.library = template_library
-        self.region_width = region_width
-        self.region_height = region_height
-        self.scale_factor = 4  # Must match the scale used in template building
-
-        logger.info("TemplatePlayClockReader initialized")
-
-    def preprocess_region(self, region: np.ndarray) -> np.ndarray:
-        """
-        Preprocess play clock region for template matching.
-
-        Uses color normalization to handle both red and white digits uniformly.
-
-        Args:
-            region: Play clock region (BGR format)
-
-        Returns:
-            Preprocessed binary image (scaled up)
-        """
-        # Normalize color (red → white conversion)
-        gray = normalize_to_grayscale(region)
-
-        # Scale up to match template resolution
-        scaled = cv2.resize(gray, None, fx=self.scale_factor, fy=self.scale_factor, interpolation=cv2.INTER_LINEAR)
-
-        # Use Otsu's thresholding
-        _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-
-        # Ensure white digits on black background
-        mean_intensity = np.mean(binary)
-        if mean_intensity > 128:
-            binary = cv2.bitwise_not(binary)
-
-        return binary
-
-    def _extract_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract left region for tens digit."""
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, : mid_x - 2]
-
-    def _extract_right_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract right region for ones digit in double-digit displays."""
-        _, w = preprocessed.shape[:2]
-        mid_x = w // 2
-        return preprocessed[:, mid_x + 2 :]
-
-    def _extract_center_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract center region for ones digit in single-digit displays."""
-        _, w = preprocessed.shape[:2]
-        center_start = int(w * 0.20)
-        center_end = int(w * 0.80)
-        return preprocessed[:, center_start:center_end]
-
-    def _extract_far_left_region(self, preprocessed: np.ndarray) -> np.ndarray:
-        """Extract far left region for blank detection in single-digit displays."""
-        _, w = preprocessed.shape[:2]
-        far_left_end = int(w * 0.20)
-        return preprocessed[:, :far_left_end]
-
-    def match_digit(self, region: np.ndarray, templates: List[DigitTemplate]) -> TemplateMatchResult:
-        """
-        Match a region against a set of digit templates.
-
-        Uses template matching with a small search window for robustness
-        to slight translational shifts.
-
-        Args:
-            region: Preprocessed digit region
-            templates: List of templates to match against
-
-        Returns:
-            TemplateMatchResult with best match
-        """
-        if not templates:
-            return TemplateMatchResult(digit_value=-1, confidence=0.0, is_valid=False)
-
-        best_digit = -1
-        best_confidence = -1.0
-
-        for template in templates:
-            tmpl = template.template
-
-            # Ensure template fits within region (with search window)
-            if tmpl.shape[0] > region.shape[0] or tmpl.shape[1] > region.shape[1]:
-                # Resize template to fit
-                scale = min(region.shape[0] / tmpl.shape[0], region.shape[1] / tmpl.shape[1]) * 0.9
-                new_h = int(tmpl.shape[0] * scale)
-                new_w = int(tmpl.shape[1] * scale)
-                tmpl = cv2.resize(tmpl, (new_w, new_h))
-
-            # Template matching with search window
-            result = cv2.matchTemplate(region, tmpl, cv2.TM_CCOEFF_NORMED)
-            _, max_val, _, _ = cv2.minMaxLoc(result)
-
-            if max_val > best_confidence:
-                best_confidence = max_val
-                best_digit = template.digit_value
-
-        is_valid = best_confidence >= self.MIN_DIGIT_CONFIDENCE
-
-        return TemplateMatchResult(digit_value=best_digit, confidence=best_confidence, is_valid=is_valid)
-
-    def _try_double_digit(self, preprocessed: np.ndarray) -> TemplatePlayClockReading:
-        """
-        Try to read as double-digit display (10-40): tens on left, ones on right.
-
-        Args:
-            preprocessed: Preprocessed play clock region
-
-        Returns:
-            TemplatePlayClockReading with result of double-digit interpretation
-        """
-        # Get templates for double-digit positions
-        # Filter out blank (-1) since it was built from far-left region (different size)
-        tens_templates = [t for t in self.library.get_all_templates(is_tens=True, position="left") if t.digit_value != -1]
-        ones_templates = self.library.get_all_templates(is_tens=False, position="right")
-
-        if not ones_templates or not tens_templates:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=None,
-                ones_match=None,
-                method="template_double",
-            )
-
-        # Extract regions
-        tens_region = self._extract_left_region(preprocessed)
-        ones_region = self._extract_right_region(preprocessed)
-
-        # Match digits
-        tens_match = self.match_digit(tens_region, tens_templates)
-        ones_match = self.match_digit(ones_region, ones_templates)
-
-        # Require valid ones match and tens match
-        if not ones_match.is_valid or not tens_match.is_valid:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=min(tens_match.confidence, ones_match.confidence),
-                tens_match=tens_match,
-                ones_match=ones_match,
-                method="template_double",
-            )
-
-        # Calculate clock value
-        clock_value = tens_match.digit_value * 10 + ones_match.digit_value
-
-        # Validate range (10-40)
-        if clock_value < 10 or clock_value > 40:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=tens_match,
-                ones_match=ones_match,
-                method="template_double",
-            )
-
-        overall_confidence = (tens_match.confidence + ones_match.confidence) / 2
-        detected = overall_confidence >= self.MIN_CLOCK_CONFIDENCE
-
-        return TemplatePlayClockReading(
-            detected=detected,
-            value=clock_value if detected else None,
-            confidence=overall_confidence,
-            tens_match=tens_match,
-            ones_match=ones_match,
-            method="template_double",
-        )
-
-    def _try_single_digit(self, preprocessed: np.ndarray) -> TemplatePlayClockReading:
-        """
-        Try to read as single-digit display (0-9): digit is centered.
-
-        Args:
-            preprocessed: Preprocessed play clock region
-
-        Returns:
-            TemplatePlayClockReading with result of single-digit interpretation
-        """
-        # Get templates for single-digit (centered) position
-        ones_templates = self.library.get_all_templates(is_tens=False, position="center")
-        blank_templates = [t for t in self.library.get_all_templates(is_tens=True, position="left") if t.digit_value == -1]
-
-        if not ones_templates:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=None,
-                ones_match=None,
-                method="template_single",
-            )
-
-        # Extract regions
-        center_region = self._extract_center_region(preprocessed)
-        far_left_region = self._extract_far_left_region(preprocessed)
-
-        # Match center digit (ones)
-        ones_match = self.match_digit(center_region, ones_templates)
-
-        # Optionally check that far-left region looks blank
-        blank_match = None
-        if blank_templates:
-            blank_match = self.match_digit(far_left_region, blank_templates)
-
-        # Require valid ones match
-        if not ones_match.is_valid:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=ones_match.confidence,
-                tens_match=blank_match,
-                ones_match=ones_match,
-                method="template_single",
-            )
-
-        # Clock value is just the ones digit (0-9)
-        clock_value = ones_match.digit_value
-
-        # Validate range (0-9)
-        if clock_value < 0 or clock_value > 9:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=blank_match,
-                ones_match=ones_match,
-                method="template_single",
-            )
-
-        # Use only ones confidence for single-digit
-        overall_confidence = ones_match.confidence
-        detected = overall_confidence >= self.MIN_CLOCK_CONFIDENCE
-
-        return TemplatePlayClockReading(
-            detected=detected,
-            value=clock_value if detected else None,
-            confidence=overall_confidence,
-            tens_match=blank_match,
-            ones_match=ones_match,
-            method="template_single",
-        )
-
-    def read(self, region: np.ndarray) -> TemplatePlayClockReading:
-        """
-        Read the play clock value from a region using dual-mode template matching.
-
-        Tries both single-digit (centered) and double-digit (left/right) interpretations
-        and returns the result with higher confidence.
-
-        Args:
-            region: Play clock region (BGR format, original size ~50x28)
-
-        Returns:
-            TemplatePlayClockReading with detected value or error state
-        """
-        # Preprocess the region (handles red-to-white conversion)
-        preprocessed = self.preprocess_region(region)
-
-        # Try both interpretations
-        double_result = self._try_double_digit(preprocessed)
-        single_result = self._try_single_digit(preprocessed)
-
-        # Pick the best result
-        # Priority: detected result with higher confidence
-        if single_result.detected and double_result.detected:
-            # Both detected - pick higher confidence
-            if single_result.confidence > double_result.confidence:
-                return single_result
-            return double_result
-        if single_result.detected:
-            return single_result
-        if double_result.detected:
-            return double_result
-        # Neither detected - return the one with higher confidence for debugging
-        if single_result.confidence > double_result.confidence:
-            return single_result
-        return double_result
-
-    def read_from_frame(
-        self,
-        frame: np.ndarray,
-        scorebug_bbox: Tuple[int, int, int, int],
-        clock_region_offset: Tuple[int, int, int, int],
-    ) -> TemplatePlayClockReading:
-        """
-        Read play clock from a full frame.
-
-        Args:
-            frame: Full video frame (BGR)
-            scorebug_bbox: Scorebug bounding box (x, y, w, h)
-            clock_region_offset: Play clock region offset from scorebug (x_off, y_off, w, h)
-
-        Returns:
-            TemplatePlayClockReading with detected value
-        """
-        sb_x, sb_y, _, _ = scorebug_bbox
-        pc_x_off, pc_y_off, pc_w, pc_h = clock_region_offset
-
-        # Calculate absolute coordinates
-        pc_x = sb_x + pc_x_off
-        pc_y = sb_y + pc_y_off
-
-        # Validate bounds
-        frame_h, frame_w = frame.shape[:2]
-        if pc_x < 0 or pc_y < 0 or pc_x + pc_w > frame_w or pc_y + pc_h > frame_h:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=None,
-                ones_match=None,
-                method="template",
-            )
-
-        # Extract region
-        region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
-
-        return self.read(region)
-
-    def read_from_fixed_location(
-        self,
-        frame: np.ndarray,
-        absolute_coords: Tuple[int, int, int, int],
-    ) -> TemplatePlayClockReading:
-        """
-        Read play clock from a fixed absolute location in the frame.
-
-        This bypasses scorebug detection entirely - useful when templates
-        are built and we know exactly where the play clock should be.
-
-        Args:
-            frame: Full video frame (BGR)
-            absolute_coords: Absolute play clock location (x, y, w, h)
-
-        Returns:
-            TemplatePlayClockReading with detected value
-        """
-        x, y, w, h = absolute_coords
-
-        # Validate bounds
-        frame_h, frame_w = frame.shape[:2]
-        if x < 0 or y < 0 or x + w > frame_w or y + h > frame_h:
-            return TemplatePlayClockReading(
-                detected=False,
-                value=None,
-                confidence=0.0,
-                tens_match=None,
-                ones_match=None,
-                method="template",
-            )
-
-        # Extract region
-        region = frame[y : y + h, x : x + w].copy()
-
-        return self.read(region)

src/detectors/models.py

@@ -1,165 +0,0 @@
-"""
-Dataclass models for the detectors module.
-
-This module contains all the data structures used by the detector components
-for passing information between pipeline stages.
-"""
-
-from dataclasses import dataclass
-from typing import Optional, Tuple, List
-
-import numpy as np
-
-
-# =============================================================================
-# Scorebug Detection Models
-# =============================================================================
-
-
-@dataclass
-class ScorebugDetection:
-    """Results from scorebug detection."""
-
-    detected: bool  # Whether scorebug was detected
-    confidence: float  # Confidence score (0.0 to 1.0)
-    bbox: Optional[Tuple[int, int, int, int]] = None  # Bounding box (x, y, width, height)
-    method: str = "unknown"  # Detection method used
-    left_confidence: Optional[float] = None  # Left half confidence (when split detection enabled)
-    right_confidence: Optional[float] = None  # Right half confidence (when split detection enabled)
-
-
-# =============================================================================
-# Play Clock Reading Models
-# =============================================================================
-
-
-@dataclass
-class PlayClockReading:
-    """Result from play clock OCR reading."""
-
-    detected: bool  # Whether a valid play clock value was detected
-    value: Optional[int]  # Play clock value (0-40 seconds), None if unreadable
-    confidence: float  # Confidence score (0.0 to 1.0)
-    raw_text: str  # Raw OCR output for debugging
-
-
-@dataclass
-class PlayClockRegionConfig:
-    """Configuration for the play clock region relative to the scorebug bounding box."""
-
-    x_offset: int  # X offset from scorebug left edge
-    y_offset: int  # Y offset from scorebug top edge
-    width: int  # Width of play clock region
-    height: int  # Height of play clock region
-    source_video: str  # Video used to identify region
-    scorebug_template: str  # Template used for scorebug detection
-    samples_used: int  # Number of frames used to verify region
-
-
-# =============================================================================
-# Timeout Tracking Models
-# =============================================================================
-
-
-@dataclass
-class TimeoutRegionConfig:
-    """Configuration for a team's timeout indicator region."""
-
-    team_name: str  # "home" or "away"
-    bbox: Tuple[int, int, int, int]  # x, y, width, height for the 3-oval group
-
-    def to_dict(self) -> dict:
-        """Convert to dictionary for JSON serialization."""
-        return {
-            "team_name": self.team_name,
-            "bbox": {"x": self.bbox[0], "y": self.bbox[1], "width": self.bbox[2], "height": self.bbox[3]},
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "TimeoutRegionConfig":
-        """Create from dictionary."""
-        bbox = (data["bbox"]["x"], data["bbox"]["y"], data["bbox"]["width"], data["bbox"]["height"])
-        return cls(team_name=data["team_name"], bbox=bbox)
-
-
-@dataclass
-class TimeoutReading:
-    """Results from timeout indicator reading."""
-
-    home_timeouts: int  # 0-3 timeouts remaining
-    away_timeouts: int  # 0-3 timeouts remaining
-    confidence: float  # Overall confidence in reading
-    home_oval_states: Optional[List[bool]] = None  # True = white (available), False = dark (used)
-    away_oval_states: Optional[List[bool]] = None  # True = white (available), False = dark (used)
-
-
-# =============================================================================
-# Play State Machine Models
-# =============================================================================
-
-
-@dataclass
-class PlayEvent:
-    """Represents a detected play with start and end times."""
-
-    play_number: int  # Sequential play number
-    start_time: float  # Video timestamp (seconds) when play started
-    end_time: float  # Video timestamp (seconds) when play ended - from backward counting
-    confidence: float  # Overall confidence score
-    start_method: str  # How start was detected: "clock_reset", "clock_reset_25", "clock_freeze"
-    end_method: str  # How end was detected: "backward_calc" (primary), "direct_detect" (secondary)
-    direct_end_time: Optional[float] = None  # End time from direct detection (for comparison)
-    start_clock_value: Optional[int] = None  # Clock value at start detection
-    end_clock_value: Optional[int] = None  # Clock value used for backward calculation
-    play_type: str = "normal"  # Type of play: "normal", "special" (punt/fg/xp after 25-second reset)
-
-
-# =============================================================================
-# Digit Template Matching Models
-# =============================================================================
-
-
-@dataclass
-class DigitSample:
-    """A single digit sample extracted from a play clock region."""
-
-    digit_value: int  # 0-9 for ones digit, 0-4 for tens digit, -1 for blank
-    is_tens_digit: bool  # True if this is the tens place digit
-    position: str  # "left", "center", or "right" - where digit appears in region
-    image: np.ndarray  # The digit image (grayscale, preprocessed)
-    source_clock_value: int  # The full clock value this was extracted from
-    timestamp: float  # Video timestamp where this was captured
-    confidence: float  # OCR confidence for this sample
-
-
-@dataclass
-class DigitTemplate:
-    """A template for matching a specific digit."""
-
-    digit_value: int  # 0-9 for ones, 0-4 for tens, -1 for blank
-    is_tens_digit: bool  # True if this is a tens place template
-    position: str  # "left", "center", or "right" - where digit appears in region
-    template: np.ndarray  # The template image (grayscale)
-    sample_count: int  # Number of samples used to build this template
-    avg_confidence: float  # Average OCR confidence of source samples
-
-
-@dataclass
-class TemplateMatchResult:
-    """Result from template matching for a single digit."""
-
-    digit_value: int  # Matched digit value (-1 for blank, 0-9 for digits)
-    confidence: float  # Match confidence (0.0 to 1.0)
-    is_valid: bool  # Whether match confidence exceeds threshold
-
-
-@dataclass
-class TemplatePlayClockReading:
-    """Result from template-based play clock reading."""
-
-    detected: bool  # Whether a valid clock value was read
-    value: Optional[int]  # Clock value (0-40), None if unreadable
-    confidence: float  # Overall confidence score
-    tens_match: Optional[TemplateMatchResult]  # Tens digit match result
-    ones_match: Optional[TemplateMatchResult]  # Ones digit match result
-    method: str  # "template" or "ocr_fallback"

src/detectors/play_state_machine.py

@@ -1,602 +0,0 @@
-"""
-Play state machine module for detecting play start and end times.
-
-This module tracks play clock state changes to determine when plays begin and end.
-The primary method for determining play end time is backward counting from the
-next observed play clock value after the play.
-"""
-
-import logging
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Optional, List
-
-from .models import ScorebugDetection, PlayClockReading, PlayEvent
-
-logger = logging.getLogger(__name__)
-
-
-class PlayState(Enum):
-    """Current state of play detection."""
-
-    IDLE = "idle"  # No scorebug detected, waiting
-    PRE_SNAP = "pre_snap"  # Scorebug visible, clock ticking down before snap
-    PLAY_IN_PROGRESS = "play_in_progress"  # Ball snapped, play is live
-    POST_PLAY = "post_play"  # Play ended, waiting for next play setup
-    NO_SCOREBUG = "no_scorebug"  # Scorebug lost during/after play (e.g., replay)
-
-
-@dataclass
-class PlayStateMachine:  # pylint: disable=too-many-instance-attributes
-    """
-    State machine for detecting play boundaries using play clock behavior.
-
-    Detection Strategy:
-    - Play START: Detected when play clock resets to 40 (or potentially freezes - needs validation)
-    - Play END: **Always use backward counting** - calculate from next observed clock value after play
-              Requires K consecutive descending clock ticks to confirm (avoids false positives)
-
-    Backward Counting:
-    When the play clock reappears showing value X (where X < 40), the play end time is:
-        play_end_time = current_time - (40 - X)
-
-    This method is reliable even when the broadcast cuts to replays.
-    """
-
-    # Configuration
-    clock_stable_frames: int = 3  # Frames with same clock value to consider it "stable"
-    max_play_duration: float = 15.0  # Maximum expected play duration in seconds
-    scorebug_lost_timeout: float = 30.0  # Seconds before resetting state when scorebug lost
-    required_countdown_ticks: int = 3  # Number of consecutive descending ticks required to confirm play end
-    min_clock_jump_for_reset: int = 5  # Minimum jump in clock value to consider it a valid reset (40 from X where X <= 40 - this value)
-
-    # Internal state
-    state: PlayState = field(default=PlayState.IDLE)
-    plays: List[PlayEvent] = field(default_factory=list)
-
-    # Tracking variables
-    _play_count: int = field(default=0)
-    _last_clock_value: Optional[int] = field(default=None)
-    _last_clock_timestamp: Optional[float] = field(default=None)
-    _clock_stable_count: int = field(default=0)
-    _current_play_start_time: Optional[float] = field(default=None)
-    _current_play_start_method: Optional[str] = field(default=None)
-    _current_play_start_clock: Optional[int] = field(default=None)
-    _last_scorebug_timestamp: Optional[float] = field(default=None)
-    _direct_end_time: Optional[float] = field(default=None)
-    _countdown_history: List[tuple] = field(default_factory=list)  # List of (timestamp, clock_value) for countdown tracking
-    _first_40_timestamp: Optional[float] = field(default=None)  # When we first saw 40 in current play (for turnover detection)
-    _current_play_clock_base: int = field(default=40)  # Clock base for current play (40 for normal, 25 for special teams)
-    _current_play_type: str = field(default="normal")  # Type of current play being tracked
-
-    def update(self, timestamp: float, scorebug: ScorebugDetection, clock: PlayClockReading) -> Optional[PlayEvent]:
-        """
-        Update the state machine with new frame data.
-
-        Args:
-            timestamp: Current video timestamp in seconds
-            scorebug: Scorebug detection result
-            clock: Play clock reading result
-
-        Returns:
-            PlayEvent if a play just ended, None otherwise
-        """
-        # Handle scorebug presence/absence
-        if not scorebug.detected:
-            return self._handle_no_scorebug(timestamp)
-
-        # Update last scorebug timestamp
-        self._last_scorebug_timestamp = timestamp
-
-        # Handle invalid clock reading
-        if not clock.detected or clock.value is None:
-            self._handle_invalid_clock(timestamp)
-            return None
-
-        # Process valid clock reading
-        return self._process_clock_value(timestamp, clock.value)
-
-    def _handle_no_scorebug(self, timestamp: float) -> Optional[PlayEvent]:
-        """Handle case when scorebug is not detected."""
-        if self.state == PlayState.IDLE:
-            return None
-
-        # Check if we've lost scorebug for too long
-        if self._last_scorebug_timestamp is not None:
-            time_since_scorebug = timestamp - self._last_scorebug_timestamp
-            if time_since_scorebug > self.scorebug_lost_timeout:
-                logger.warning("Scorebug lost for %.1fs, resetting to IDLE", time_since_scorebug)
-                self._reset_state()
-                return None
-
-        # TURNOVER DETECTION: If we were in PLAY_IN_PROGRESS with significant time at 40,
-        # and scorebug disappears (likely for replay/review), record the play.
-        if self.state == PlayState.PLAY_IN_PROGRESS and self._first_40_timestamp is not None:
-            time_at_40 = (self._last_scorebug_timestamp - self._first_40_timestamp) if self._last_scorebug_timestamp else 0
-            min_time_for_play = 2.0
-
-            if time_at_40 > min_time_for_play:
-                # Play happened, scorebug disappeared (likely for replay/review)
-                play_end_time = self._last_scorebug_timestamp if self._last_scorebug_timestamp else timestamp
-                logger.info(
-                    "Scorebug disappeared during play at %.1fs (%.1fs at 40). Recording play end at %.1fs.",
-                    timestamp,
-                    time_at_40,
-                    play_end_time,
-                )
-                # Record the play before transitioning
-                completed_play = self._end_play_with_backward_calc(timestamp, 40, play_end_time)
-                self.state = PlayState.NO_SCOREBUG
-                return completed_play
-
-        # Transition to NO_SCOREBUG state if we were in a play
-        if self.state in (PlayState.PRE_SNAP, PlayState.PLAY_IN_PROGRESS, PlayState.POST_PLAY):
-            logger.debug("Scorebug lost at %.1fs, entering NO_SCOREBUG state", timestamp)
-            self.state = PlayState.NO_SCOREBUG
-
-        return None
-
-    def _handle_invalid_clock(self, timestamp: float) -> None:
-        """Handle case when clock reading is invalid but scorebug is present."""
-        # If we're in pre-snap and clock becomes unreadable, might indicate play started
-        if self.state == PlayState.PRE_SNAP and self._last_clock_value is not None:
-            # Clock became unreadable - could be play in progress
-            logger.debug("Clock unreadable at %.1fs in PRE_SNAP state", timestamp)
-
-    def _process_clock_value(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
-        """
-        Process a valid clock reading and update state.
-
-        Args:
-            timestamp: Current timestamp
-            clock_value: Detected play clock value (0-40)
-
-        Returns:
-            PlayEvent if a play just completed
-        """
-        completed_play = None
-
-        if self.state == PlayState.IDLE:
-            # First clock reading - transition to PRE_SNAP
-            logger.debug("First clock reading (%d) at %.1fs, entering PRE_SNAP", clock_value, timestamp)
-            self.state = PlayState.PRE_SNAP
-            self._last_clock_value = clock_value
-            self._last_clock_timestamp = timestamp
-            self._clock_stable_count = 1
-
-        elif self.state == PlayState.PRE_SNAP:
-            # Watching for play to start (clock reset to 40 or freeze)
-            completed_play = self._handle_pre_snap(timestamp, clock_value)  # pylint: disable=assignment-from-none
-
-        elif self.state == PlayState.PLAY_IN_PROGRESS:
-            # Play is live, watching for it to end (clock restarts)
-            completed_play = self._handle_play_in_progress(timestamp, clock_value)
-
-        elif self.state == PlayState.POST_PLAY:
-            # Play ended, transitioning back to PRE_SNAP
-            self._handle_post_play(timestamp, clock_value)
-
-        elif self.state == PlayState.NO_SCOREBUG:
-            # Scorebug returned after being lost
-            completed_play = self._handle_scorebug_returned(timestamp, clock_value)
-
-        # Update tracking
-        self._last_clock_value = clock_value
-        self._last_clock_timestamp = timestamp
-
-        return completed_play
-
-    def _handle_pre_snap(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
-        """Handle clock reading during PRE_SNAP state."""
-        if self._last_clock_value is None:
-            self._last_clock_value = clock_value
-            self._clock_stable_count = 1
-            return None
-
-        # Check for clock reset to 40 (indicates ball was snapped for normal play)
-        # Require a significant jump in clock value to avoid false positives from OCR noise
-        # e.g., "40 from 39" is likely OCR noise, but "40 from 25" is a real reset
-        max_prev_value = 40 - self.min_clock_jump_for_reset  # e.g., 35 if min_jump=5
-        if clock_value == 40 and self._last_clock_value <= max_prev_value:
-            logger.info("Play START detected at %.1fs (clock reset to 40 from %d)", timestamp, self._last_clock_value)
-            self._current_play_clock_base = 40
-            self._current_play_type = "normal"
-            self._start_play(timestamp, "clock_reset", self._last_clock_value)
-            return None
-
-        # Reject suspicious clock resets that look like OCR noise
-        if clock_value == 40 and self._last_clock_value > max_prev_value:
-            logger.debug(
-                "Ignoring suspicious clock reset at %.1fs (40 from %d, requires prev <= %d)",
-                timestamp,
-                self._last_clock_value,
-                max_prev_value,
-            )
-            # Don't update _last_clock_value - treat this 40 reading as noise
-            return None
-
-        # NEW: Check for clock reset to 25 (indicates special teams play - punt return, kickoff return, post-FG/XP)
-        # This happens after possession-changing plays like punts, FGs, XPs
-        # The clock resets to 25 instead of 40 for these plays
-        if clock_value == 25 and self._last_clock_value is not None:
-            clock_jump = abs(clock_value - self._last_clock_value)
-            # Require significant jump to avoid false positives from normal countdown through 25
-            # A jump of 5+ indicates a real reset (e.g., 40→25, 30→25 after brief 40, or 10→25 after play)
-            if clock_jump >= self.min_clock_jump_for_reset:
-                logger.info(
-                    "Special teams play START detected at %.1fs (clock reset to 25 from %d, jump of %d)",
-                    timestamp,
-                    self._last_clock_value,
-                    clock_jump,
-                )
-                self._current_play_clock_base = 25
-                self._current_play_type = "special"
-                self._start_play(timestamp, "clock_reset_25", self._last_clock_value)
-                return None
-
-        # Track clock stability (for potential future use)
-        if clock_value == self._last_clock_value:
-            self._clock_stable_count += 1
-        else:
-            self._clock_stable_count = 1
-
-        # Note: "clock_freeze" detection disabled - was causing false positives
-        # The clock_reset detection (going to 40 or 25) is the reliable method
-        return None
-
-    # pylint: disable=too-many-return-statements,too-many-branches
-    def _handle_play_in_progress(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
-        """Handle clock reading during PLAY_IN_PROGRESS state."""
-        if self._current_play_start_time is None:
-            return None
-
-        # Check for play duration timeout
-        play_duration = timestamp - self._current_play_start_time
-        if play_duration > self.max_play_duration:
-            # Cap the end time at start + max_duration to avoid inflated durations
-            # This prevents long gaps (commercials, etc.) from extending play end times
-            capped_end_time = self._current_play_start_time + self.max_play_duration
-            logger.warning(
-                "Play duration (%.1fs) exceeded max (%.1fs), forcing end at %.1fs (capped from %.1fs)",
-                play_duration,
-                self.max_play_duration,
-                capped_end_time,
-                timestamp,
-            )
-            self._direct_end_time = capped_end_time
-            self._countdown_history = []  # Reset countdown tracking
-            return self._end_play_capped(capped_end_time, clock_value, "max_duration")
-
-        # If clock is still at 40, the play just started and clock hasn't begun countdown yet
-        # We need to wait for the clock to drop below 40 before we can detect play end
-        if clock_value == 40:
-            # Track when we first saw 40 (for turnover detection)
-            if self._first_40_timestamp is None:
-                self._first_40_timestamp = timestamp
-            # Clock is still at 40 after reset - waiting for countdown to begin
-            logger.debug("Play in progress at %.1fs, clock still at 40 (%.1fs at 40)", timestamp, timestamp - self._first_40_timestamp)
-            self._countdown_history = []  # Reset countdown tracking
-            return None
-
-        # RAPID 40→25 TRANSITION DETECTION (possession change during play):
-        # This happens during punts, kickoffs, and after XPs/FGs:
-        # - Punt: Ball punted, receiving team catches it → clock resets to 25
-        # - Kickoff: Similar to punt
-        # - XP/FG: After kick, clock resets to 25 for next team's possession
-        #
-        # IMPORTANT: We should NOT end the play here! For punts/kickoffs, the return
-        # is still in progress. We need to:
-        # 1. Mark this as a special play
-        # 2. Update the clock base to 25
-        # 3. Continue tracking until proper end detection (countdown confirmed, scorebug lost, or max duration)
-        if clock_value == 25 and self._first_40_timestamp is not None:
-            time_at_40 = timestamp - self._first_40_timestamp
-            max_time_for_possession_change = 5.0  # 40→25 within 5 seconds indicates possession change
-            min_time_at_40 = 0.5  # Must be at 40 briefly to avoid OCR noise (lowered from 1.0 for timing precision)
-
-            if min_time_at_40 <= time_at_40 <= max_time_for_possession_change and len(self._countdown_history) == 0:
-                # Possession change detected - play continues (e.g., punt return in progress)
-                # DO NOT end the play here - let it continue until proper end detection
-                logger.info(
-                    "Possession change detected at %.1fs: 40 → 25 after %.1fs. Play continues (return may be in progress).",
-                    timestamp,
-                    time_at_40,
-                )
-                # Mark as special play and update clock base for proper end detection
-                self._current_play_type = "special"
-                self._current_play_clock_base = 25
-                self._first_40_timestamp = None  # Reset since we're now tracking at 25
-                self._countdown_history = []  # Reset countdown tracking for fresh detection at 25
-                return None  # Continue tracking - DO NOT end the play!
-
-        # ABNORMAL CLOCK DROP DETECTION:
-        # If the first reading after seeing 40 drops by more than 5 seconds (e.g., 40 → 25),
-        # this could be either:
-        # 1. A timeout/injury reset (no play happened) - clock was at 40 briefly
-        # 2. A turnover/possession change (play DID happen) - clock was at 40 for several seconds during play
-        # We distinguish by checking how long the clock was at 40.
-        if len(self._countdown_history) == 0:
-            # This is the first reading after 40
-            clock_drop = 40 - clock_value
-            max_normal_drop = 5  # Allow up to 5 second drop on first reading (accounts for timing/OCR variance)
-            if clock_drop > max_normal_drop:
-                # Check how long clock was at 40 to distinguish turnover from timeout
-                time_at_40 = (timestamp - self._first_40_timestamp) if self._first_40_timestamp else 0
-                min_time_for_play = 2.0  # If clock was at 40 for > 2 seconds, a play likely happened
-
-                if time_at_40 > min_time_for_play:
-                    # Ball was snapped, play happened - this is likely a turnover/possession change
-                    # Estimate play ended shortly before we saw the abnormal reading
-                    play_end_time = timestamp - 1.0
-                    logger.info(
-                        "Turnover/possession change detected at %.1fs: 40 → %d after %.1fs at 40. Recording play end at %.1fs.",
-                        timestamp,
-                        clock_value,
-                        time_at_40,
-                        play_end_time,
-                    )
-                    return self._end_play_with_backward_calc(timestamp, clock_value, play_end_time)
-                # Brief time at 40, likely timeout/reset, not a real play
-                logger.warning(
-                    "Abnormal clock drop detected at %.1fs: 40 → %d (drop of %d seconds, only %.1fs at 40). "
-                    "Likely timeout/injury reset, not a real play. Resetting to PRE_SNAP.",
-                    timestamp,
-                    clock_value,
-                    clock_drop,
-                    time_at_40,
-                )
-                self._reset_play_tracking()
-                self.state = PlayState.PRE_SNAP
-                return None
-
-        # Track countdown history for confirming play end
-        # We require K consecutive descending ticks to confirm
-        self._countdown_history.append((timestamp, clock_value))
-
-        # Check if we have enough consecutive descending values
-        if len(self._countdown_history) >= self.required_countdown_ticks:
-            # Get last K readings
-            recent = self._countdown_history[-self.required_countdown_ticks :]
-            values = [v for _, v in recent]
-
-            # Check if values are strictly descending (or stable which means same second)
-            is_valid_countdown = True
-            for i in range(1, len(values)):
-                # Allow same value (within same second) or descending
-                if values[i] > values[i - 1]:
-                    is_valid_countdown = False
-                    break
-
-            if is_valid_countdown:
-                # Use the first reading in our confirmed sequence for backward calculation
-                first_timestamp, first_value = recent[0]
-                # Use the correct clock base (40 for normal plays, 25 for special teams)
-                calculated_end_time = first_timestamp - (self._current_play_clock_base - first_value)
-                logger.info(
-                    "Play END confirmed via %d-tick countdown: %.1fs (clock=%d→%d, base=%d, observed %.1fs-%.1fs)",
-                    self.required_countdown_ticks,
-                    calculated_end_time,
-                    values[0],
-                    values[-1],
-                    self._current_play_clock_base,
-                    recent[0][0],
-                    recent[-1][0],
-                )
-                self._direct_end_time = timestamp  # When we confirmed the countdown
-                self._countdown_history = []  # Reset for next play
-                return self._end_play_with_backward_calc(timestamp, first_value, calculated_end_time)
-
-        return None
-
-    def _handle_post_play(self, timestamp: float, clock_value: int) -> None:  # pylint: disable=unused-argument
-        """Handle clock reading during POST_PLAY state."""
-        # Note: clock_value unused for now, but kept for potential future use
-        # Transition back to PRE_SNAP
-        logger.debug("Transitioning from POST_PLAY to PRE_SNAP at %.1fs", timestamp)
-        self.state = PlayState.PRE_SNAP
-        self._clock_stable_count = 1
-
-    def _handle_scorebug_returned(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
-        """Handle scorebug returning after being lost."""
-        completed_play = None
-
-        # If we were tracking a play, use backward counting to determine when it ended
-        if self._current_play_start_time is not None:
-            # Calculate when play ended using backward counting with correct clock base
-            calculated_end_time = timestamp - (self._current_play_clock_base - clock_value)
-            logger.info(
-                "Scorebug returned at %.1fs (clock=%d, base=%d), backward calc play end: %.1fs",
-                timestamp,
-                clock_value,
-                self._current_play_clock_base,
-                calculated_end_time,
-            )
-            completed_play = self._end_play_with_backward_calc(timestamp, clock_value, calculated_end_time)
-        else:
-            # No play was in progress, just return to PRE_SNAP
-            logger.debug("Scorebug returned at %.1fs, no play in progress", timestamp)
-
-        self.state = PlayState.PRE_SNAP
-        self._clock_stable_count = 1
-        return completed_play
-
-    def _start_play(self, timestamp: float, method: str, clock_value: Optional[int]) -> None:
-        """Record the start of a new play."""
-        self._current_play_start_time = timestamp
-        self._current_play_start_method = method
-        self._current_play_start_clock = clock_value
-        self._countdown_history = []  # Reset countdown tracking for new play
-        self.state = PlayState.PLAY_IN_PROGRESS
-        logger.debug("Play started: time=%.1fs, method=%s, clock=%s", timestamp, method, clock_value)
-
-    def _end_play_capped(self, capped_end_time: float, clock_value: int, method: str) -> PlayEvent:
-        """End the current play with a capped end time (for max duration exceeded)."""
-        self._play_count += 1
-
-        play = PlayEvent(
-            play_number=self._play_count,
-            start_time=self._current_play_start_time or capped_end_time,
-            end_time=capped_end_time,
-            confidence=0.7,  # Lower confidence for capped plays
-            start_method=self._current_play_start_method or "unknown",
-            end_method=method,
-            direct_end_time=self._direct_end_time,
-            start_clock_value=self._current_play_start_clock,
-            end_clock_value=clock_value,
-            play_type=self._current_play_type,
-        )
-
-        self.plays.append(play)
-        self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
-
-        logger.info(
-            "Play #%d complete (capped, %s): %.1fs - %.1fs (duration: %.1fs)",
-            play.play_number,
-            play.play_type,
-            play.start_time,
-            play.end_time,
-            play.end_time - play.start_time,
-        )
-
-        return play
-
-    def _end_play(self, timestamp: float, clock_value: int, method: str) -> PlayEvent:
-        """End the current play and create a PlayEvent."""
-        self._play_count += 1
-
-        # For direct detection, end time is the current timestamp
-        end_time = timestamp
-
-        play = PlayEvent(
-            play_number=self._play_count,
-            start_time=self._current_play_start_time or timestamp,
-            end_time=end_time,
-            confidence=0.8,  # Base confidence for direct detection
-            start_method=self._current_play_start_method or "unknown",
-            end_method=method,
-            direct_end_time=self._direct_end_time,
-            start_clock_value=self._current_play_start_clock,
-            end_clock_value=clock_value,
-            play_type=self._current_play_type,
-        )
-
-        self.plays.append(play)
-        self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
-
-        logger.info(
-            "Play #%d complete (%s): %.1fs - %.1fs (duration: %.1fs)",
-            play.play_number,
-            play.play_type,
-            play.start_time,
-            play.end_time,
-            play.end_time - play.start_time,
-        )
-
-        return play
-
-    def _end_play_with_backward_calc(self, observation_time: float, clock_value: int, calculated_end_time: float) -> Optional[PlayEvent]:
-        """End the current play using backward calculation for end time."""
-        start_time = self._current_play_start_time or calculated_end_time
-
-        # Sanity check: end time must be after start time
-        if calculated_end_time < start_time:
-            logger.warning(
-                "Rejecting invalid play: calculated end time (%.1fs) is before start time (%.1fs). This likely indicates OCR noise or false play detection. Resetting state.",
-                calculated_end_time,
-                start_time,
-            )
-            self._reset_play_tracking()
-            self.state = PlayState.PRE_SNAP
-            return None
-
-        # Sanity check: play duration should be reasonable
-        # Special plays (XP/FG completions) can have very short durations due to sampling interval
-        duration = calculated_end_time - start_time
-        min_duration = 0.0 if self._current_play_type == "special" else 0.5
-        if duration < min_duration:
-            logger.warning(
-                "Rejecting invalid play: duration (%.1fs) is too short. This likely indicates OCR noise. Resetting state.",
-                duration,
-            )
-            self._reset_play_tracking()
-            self.state = PlayState.PRE_SNAP
-            return None
-
-        self._play_count += 1
-
-        play = PlayEvent(
-            play_number=self._play_count,
-            start_time=start_time,
-            end_time=calculated_end_time,  # Use backward-calculated time
-            confidence=0.9,  # Higher confidence for backward calculation
-            start_method=self._current_play_start_method or "unknown",
-            end_method="backward_calc",
-            direct_end_time=self._direct_end_time,  # May be None
-            start_clock_value=self._current_play_start_clock,
-            end_clock_value=clock_value,
-            play_type=self._current_play_type,
-        )
-
-        self.plays.append(play)
-        self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
-
-        logger.info(
-            "Play #%d complete (backward calc, %s): %.1fs - %.1fs (duration: %.1fs, observed at %.1fs with clock=%d)",
-            play.play_number,
-            play.play_type,
-            play.start_time,
-            play.end_time,
-            play.end_time - play.start_time,
-            observation_time,
-            clock_value,
-        )
-
-        return play
-
-    def _reset_play_tracking(self) -> None:
-        """Reset tracking variables for next play."""
-        self._current_play_start_time = None
-        self._current_play_start_method = None
-        self._current_play_start_clock = None
-        self._direct_end_time = None
-        self._clock_stable_count = 0
-        self._countdown_history = []
-        self._first_40_timestamp = None
-        self._current_play_clock_base = 40  # Reset to default
-        self._current_play_type = "normal"  # Reset to default
-
-    def _reset_state(self) -> None:
-        """Fully reset state machine."""
-        self.state = PlayState.IDLE
-        self._reset_play_tracking()
-        self._last_clock_value = None
-        self._last_clock_timestamp = None
-        self._last_scorebug_timestamp = None
-        logger.debug("State machine reset to IDLE")
-
-    def get_plays(self) -> List[PlayEvent]:
-        """Get all detected plays."""
-        return self.plays.copy()
-
-    def get_state(self) -> PlayState:
-        """Get current state."""
-        return self.state
-
-    def get_stats(self) -> dict:
-        """Get statistics about detected plays."""
-        if not self.plays:
-            return {"total_plays": 0}
-
-        durations = [p.end_time - p.start_time for p in self.plays]
-        return {
-            "total_plays": len(self.plays),
-            "avg_duration": sum(durations) / len(durations),
-            "min_duration": min(durations),
-            "max_duration": max(durations),
-            "start_methods": {m: sum(1 for p in self.plays if p.start_method == m) for m in set(p.start_method for p in self.plays)},
-            "end_methods": {m: sum(1 for p in self.plays if p.end_method == m) for m in set(p.end_method for p in self.plays)},
-            "play_types": {t: sum(1 for p in self.plays if p.play_type == t) for t in set(p.play_type for p in self.plays)},
-        }

src/pipeline/__init__.py

@@ -1,4 +1,4 @@
-"""Pipeline modules for video processing and detection orchestration.
+"""Pipeline modules for video processing and play extraction orchestration.
 
 Note: OCR-based clock reading has been removed in favor of template matching.
 Streaming processing is used for optimal performance.
@@ -13,8 +13,9 @@ from .models import (
 )
 
 # Pipeline classes and functions
-from .play_detector import PlayDetector, format_detection_result_dict
-from .orchestrator import run_detection, print_results_summary
+from .play_extractor import PlayExtractor, format_extraction_result_dict
+from .orchestrator import run_extraction, print_results_summary
+from .template_builder_pass import TemplateBuildingPass
 
 __all__ = [
     # Models
@@ -22,8 +23,9 @@ __all__ = [
     "DetectionResult",
     "VideoContext",
     # Pipeline
-    "PlayDetector",
-    "format_detection_result_dict",
-    "run_detection",
+    "PlayExtractor",
+    "format_extraction_result_dict",
+    "run_extraction",
     "print_results_summary",
+    "TemplateBuildingPass",
 ]

src/pipeline/models.py

@@ -1,5 +1,5 @@
 """
-Dataclass models for the pipeline module.
+Pydantic models for the pipeline module.
 
 This module contains all the data structures used by the pipeline components
 for configuration, intermediate results, and final output.
@@ -9,10 +9,9 @@ Streaming processing is used for optimal performance (read frame -> process imme
 See docs/ocr_to_template_migration.md for details.
 """
 
-from dataclasses import dataclass, field
 from typing import Optional, List, Dict, Any, Tuple
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict, Field
 
 
 # =============================================================================
@@ -20,8 +19,7 @@ from pydantic import BaseModel
 # =============================================================================
 
 
-@dataclass
-class DetectionConfig:
+class DetectionConfig(BaseModel):
     """Configuration for play detection pipeline.
 
     Uses template matching for play clock reading (~34x faster than OCR).
@@ -29,19 +27,19 @@ class DetectionConfig:
     then streaming detection processes each frame immediately via template matching.
     """
 
-    video_path: str  # Path to video file
-    template_path: str  # Path to scorebug template
-    clock_region_config_path: str  # Path to play clock region config
-    start_time: float = 0.0  # Start time in seconds
-    end_time: Optional[float] = None  # End time in seconds (None = full video)
-    frame_interval: float = 0.5  # Interval between frame samples (seconds)
-    use_split_detection: bool = True  # Enable split-half scorebug detection for robustness to partial overlays
+    video_path: str = Field(..., description="Path to video file")
+    template_path: str = Field(..., description="Path to scorebug template")
+    clock_region_config_path: str = Field(..., description="Path to play clock region config")
+    start_time: float = Field(0.0, description="Start time in seconds")
+    end_time: Optional[float] = Field(None, description="End time in seconds (None = full video)")
+    frame_interval: float = Field(0.5, description="Interval between frame samples (seconds)")
+    use_split_detection: bool = Field(True, description="Enable split-half scorebug detection for robustness to partial overlays")
     # Template matching configuration
-    template_collection_frames: int = 400  # Number of frames to use for building digit templates via OCR
-    digit_template_path: Optional[str] = None  # Path to pre-built digit templates (skip collection phase if provided)
+    template_collection_frames: int = Field(400, description="Number of frames to use for building digit templates via OCR")
+    digit_template_path: Optional[str] = Field(None, description="Path to pre-built digit templates (skip collection phase if provided)")
     # Fixed coordinates mode - skip scorebug detection entirely for maximum speed
-    fixed_playclock_coords: Optional[Tuple[int, int, int, int]] = None  # (x, y, w, h) absolute play clock coords
-    fixed_scorebug_coords: Optional[Tuple[int, int, int, int]] = None  # (x, y, w, h) scorebug region (for metadata)
+    fixed_playclock_coords: Optional[Tuple[int, int, int, int]] = Field(None, description="(x, y, w, h) absolute play clock coords")
+    fixed_scorebug_coords: Optional[Tuple[int, int, int, int]] = Field(None, description="(x, y, w, h) scorebug region (for metadata)")
 
 
 # =============================================================================
@@ -49,19 +47,20 @@ class DetectionConfig:
 # =============================================================================
 
 
-@dataclass
-class VideoContext:
+class VideoContext(BaseModel):
     """Container for video properties and processing state."""
 
-    cap: Any  # cv2.VideoCapture (using Any to avoid cv2 typing issues)
-    fps: float  # Frames per second
-    total_frames: int  # Total frame count
-    duration: float  # Video duration in seconds
-    start_time: float  # Segment start time
-    end_time: float  # Segment end time
-    frame_skip: int  # Frames to skip between samples
-    start_frame: int  # First frame to process
-    end_frame: int  # Last frame to process
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    cap: Any = Field(..., description="cv2.VideoCapture (using Any to avoid cv2 typing issues)")
+    fps: float = Field(..., description="Frames per second")
+    total_frames: int = Field(..., description="Total frame count")
+    duration: float = Field(..., description="Video duration in seconds")
+    start_time: float = Field(..., description="Segment start time")
+    end_time: float = Field(..., description="Segment end time")
+    frame_skip: int = Field(..., description="Frames to skip between samples")
+    start_frame: int = Field(..., description="First frame to process")
+    end_frame: int = Field(..., description="Last frame to process")
 
 
 # =============================================================================
@@ -69,20 +68,19 @@ class VideoContext:
 # =============================================================================
 
 
-@dataclass
-class DetectionResult:
+class DetectionResult(BaseModel):
     """Results from play detection pipeline."""
 
-    video: str  # Video filename
-    segment_start: float  # Segment start time
-    segment_end: float  # Segment end time
-    total_frames_processed: int  # Number of frames analyzed
-    frames_with_scorebug: int  # Frames where scorebug was detected
-    frames_with_clock: int  # Frames where clock was read successfully
-    plays: List[Dict[str, Any]] = field(default_factory=list)  # Detected plays as dicts
-    stats: Dict[str, Any] = field(default_factory=dict)  # Summary statistics
-    timing: Dict[str, float] = field(default_factory=dict)  # Timing breakdown by section
-    config: Dict[str, Any] = field(default_factory=dict)  # Configuration used for this run (regions, thresholds, etc.)
+    video: str = Field(..., description="Video filename")
+    segment_start: float = Field(..., description="Segment start time")
+    segment_end: float = Field(..., description="Segment end time")
+    total_frames_processed: int = Field(..., description="Number of frames analyzed")
+    frames_with_scorebug: int = Field(..., description="Frames where scorebug was detected")
+    frames_with_clock: int = Field(..., description="Frames where clock was read successfully")
+    plays: List[Dict[str, Any]] = Field(default_factory=list, description="Detected plays as dicts")
+    stats: Dict[str, Any] = Field(default_factory=dict, description="Summary statistics")
+    timing: Dict[str, float] = Field(default_factory=dict, description="Timing breakdown by section")
+    config: Dict[str, Any] = Field(default_factory=dict, description="Configuration used for this run (regions, thresholds, etc.)")
 
 
 # =============================================================================
@@ -90,6 +88,23 @@ class DetectionResult:
 # =============================================================================
 
 
+class ParallelProcessingConfig(BaseModel):
+    """Configuration for parallel video chunk processing.
+
+    This model groups the configuration parameters needed by parallel processing
+    functions, reducing the number of individual arguments.
+    """
+
+    video_path: str = Field(..., description="Path to video file")
+    start_time: float = Field(..., description="Start time in seconds")
+    end_time: float = Field(..., description="End time in seconds")
+    frame_interval: float = Field(..., description="Time interval between frames")
+    fixed_playclock_coords: Tuple[int, int, int, int] = Field(..., description="(x, y, w, h) for play clock region")
+    fixed_scorebug_coords: Tuple[int, int, int, int] = Field(..., description="(x, y, w, h) for scorebug region")
+    template_library_path: Optional[str] = Field(None, description="Path to template library directory")
+    timeout_config_path: Optional[str] = Field(None, description="Path to timeout tracker config")
+
+
 class ChunkResult(BaseModel):
     """Result from processing a single video chunk in parallel processing.
 
@@ -97,12 +112,12 @@ class ChunkResult(BaseModel):
     when passing data between worker processes.
     """
 
-    chunk_id: int  # Identifier for this chunk
-    start_time: float  # Chunk start time in seconds
-    end_time: float  # Chunk end time in seconds
-    frames_processed: int  # Total frames processed in this chunk
-    frames_with_scorebug: int  # Frames where scorebug was detected
-    frames_with_clock: int  # Frames where clock was successfully read
-    frame_data: List[Dict[str, Any]]  # Per-frame detection results
-    io_time: float  # Time spent on video I/O operations
-    processing_time: float  # Total processing time for this chunk
+    chunk_id: int = Field(..., description="Identifier for this chunk")
+    start_time: float = Field(..., description="Chunk start time in seconds")
+    end_time: float = Field(..., description="Chunk end time in seconds")
+    frames_processed: int = Field(..., description="Total frames processed in this chunk")
+    frames_with_scorebug: int = Field(..., description="Frames where scorebug was detected")
+    frames_with_clock: int = Field(..., description="Frames where clock was successfully read")
+    frame_data: List[Dict[str, Any]] = Field(..., description="Per-frame detection results")
+    io_time: float = Field(..., description="Time spent on video I/O operations")
+    processing_time: float = Field(..., description="Total processing time for this chunk")

src/pipeline/orchestrator.py

@@ -1,7 +1,7 @@
 """
-Pipeline orchestration for play detection.
+Pipeline orchestration for play extraction.
 
-This module provides the high-level functions for running play detection,
+This module provides the high-level functions for running play extraction,
 including result filtering and summary printing.
 
 Supports both sequential and parallel processing modes:
@@ -10,26 +10,20 @@ Supports both sequential and parallel processing modes:
 """
 
 import logging
-import sys
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
-# Add src to path for imports if running standalone
-_SRC_PATH = str(Path(__file__).parent.parent)
-if _SRC_PATH not in sys.path:
-    sys.path.insert(0, _SRC_PATH)
-
-# pylint: disable=wrong-import-position
-from config.session import SessionConfig, MIN_PLAY_DURATION
-from detectors.timeout_tracker import TimeoutTracker
-from pipeline.play_detector import DetectionConfig, PlayDetector, format_detection_result_dict
+from config import SessionConfig, MIN_PLAY_DURATION
+from detection import DetectTimeouts
+from .models import DetectionConfig
+from .play_extractor import PlayExtractor, format_extraction_result_dict
 
 logger = logging.getLogger(__name__)
 
 
-def run_detection(config: SessionConfig, output_dir: Path, num_workers: int = 1) -> Dict[str, Any]:
+def run_extraction(config: SessionConfig, output_dir: Path, num_workers: int = 1) -> Dict[str, Any]:
     """
-    Run play detection using the configured regions.
+    Run play extraction using the configured regions.
 
     Uses 3-class classification for 40->25 clock resets:
     - Class A (weird_clock): 25 counts down immediately -> rejected
@@ -42,18 +36,18 @@ def run_detection(config: SessionConfig, output_dir: Path, num_workers: int = 1)
         num_workers: Number of parallel workers (1=sequential, 2+=parallel).
 
     Returns:
-        Detection results dictionary with keys:
+        Extraction results dictionary with keys:
         - video: Video path
         - segment: Start/end times
         - processing: Frame processing stats
         - timing: Timing breakdown
-        - plays: List of detected plays
+        - plays: List of extracted plays
         - stats: Play statistics
     """
     if num_workers > 1:
-        print(f"\n[Phase 3] Running Detection (parallel: {num_workers} workers)...")
+        print(f"\n[Phase 3] Running Extraction (parallel: {num_workers} workers)...")
     else:
-        print("\n[Phase 3] Running Detection...")
+        print("\n[Phase 3] Running Extraction...")
     print("-" * 50)
 
     basename = config.video_basename
@@ -88,19 +82,19 @@ def run_detection(config: SessionConfig, output_dir: Path, num_workers: int = 1)
     # Initialize timeout tracker if config exists
     timeout_tracker = None
     if timeout_config_path.exists():
-        timeout_tracker = TimeoutTracker(config_path=str(timeout_config_path))
+        timeout_tracker = DetectTimeouts(config_path=str(timeout_config_path))
         logger.info("Timeout tracker initialized from: %s", timeout_config_path)
     else:
         logger.info("No timeout tracker config found - clock reset classification will be limited")
 
-    # Initialize detector - fixed coordinates mode is configured via DetectionConfig
-    detector = PlayDetector(detection_config, timeout_tracker=timeout_tracker)
+    # Initialize extractor - fixed coordinates mode is configured via DetectionConfig
+    extractor = PlayExtractor(detection_config, timeout_tracker=timeout_tracker)
 
-    # Run detection - parallel or sequential based on num_workers
+    # Run extraction - parallel or sequential based on num_workers
     if num_workers > 1:
-        result = detector.detect_parallel(num_workers=num_workers, output_dir=output_dir)
+        result = extractor.extract_parallel(num_workers=num_workers, output_dir=output_dir)
     else:
-        result = detector.detect()
+        result = extractor.extract()
 
     # Filter out plays shorter than minimum duration (e.g., clock operator errors)
     original_play_count = len(result.plays)
@@ -159,10 +153,10 @@ def run_detection(config: SessionConfig, output_dir: Path, num_workers: int = 1)
 
     # Save results with video-specific name
     results_path = output_dir / f"{basename}_plays.json"
-    detector.save_results(result, str(results_path))
+    extractor.save_results(result, str(results_path))
 
     # Convert to dictionary for return
-    return format_detection_result_dict(result)
+    return format_extraction_result_dict(result)
 
 
 def print_results_summary(
@@ -172,12 +166,12 @@ def print_results_summary(
     video_basename: str,
     generate_individual: bool,
     expected_plays: int = 12,
-):
+) -> None:
     """
     Print the final results summary.
 
     Args:
-        results: Detection results dictionary from run_detection().
+        results: Extraction results dictionary from run_extraction().
         testing_mode: Whether running in testing mode.
         clip_timing: Timing information from clip generation.
         video_basename: Base name for output files.

src/pipeline/parallel.py

@@ -13,9 +13,10 @@ import time
 from concurrent.futures import Future, ProcessPoolExecutor, as_completed
 from multiprocessing import Manager
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Dict, List, MutableMapping, Optional, Tuple
 
-from .models import ChunkResult
+from utils import create_frame_result
+from .models import ChunkResult, ParallelProcessingConfig
 
 logger = logging.getLogger(__name__)
 
@@ -25,53 +26,58 @@ logger = logging.getLogger(__name__)
 # =============================================================================
 
 
-def _init_chunk_detectors(
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
-) -> Tuple[Any, Any, Any, Any]:
+def _init_chunk_detectors(config: ParallelProcessingConfig) -> Tuple[Any, Any, Any, Any]:
     """
     Initialize all detection components for a chunk worker.
 
     Must be called within the subprocess since these objects can't be pickled.
 
+    Note: Imports are inside this function because multiprocessing requires
+    fresh imports in each worker process. Moving these to module level would
+    cause pickling errors when spawning workers.
+
     Args:
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory.
-        timeout_config_path: Path to timeout tracker config.
+        config: Parallel processing configuration.
 
     Returns:
         Tuple of (scorebug_detector, clock_reader, template_reader, timeout_tracker).
     """
-    from detectors import PlayClockReader, ScorebugDetector, TimeoutTracker
-    from detectors.digit_template_reader import DigitTemplateLibrary, TemplatePlayClockReader
-    from detectors.models import PlayClockRegionConfig
+    # pylint: disable=import-outside-toplevel
+    # Imports must be inside function for multiprocessing - each subprocess
+    # needs its own fresh imports of these modules to avoid pickling errors
+    from detection import DetectScoreBug, DetectTimeouts
+    from readers import ReadPlayClock
+    from setup import DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
 
     # Create scorebug detector with fixed region
-    scorebug_detector = ScorebugDetector(template_path=None, use_split_detection=True)
-    scorebug_detector.set_fixed_region(fixed_scorebug_coords)
-
-    # Create play clock reader
-    pc_x, pc_y, pc_w, pc_h = fixed_playclock_coords
-    sb_x, sb_y, _, _ = fixed_scorebug_coords
-    x_offset = pc_x - sb_x
-    y_offset = pc_y - sb_y
-    playclock_config = PlayClockRegionConfig(x_offset=x_offset, y_offset=y_offset, width=pc_w, height=pc_h, source_video="", scorebug_template="", samples_used=0)
-    clock_reader = PlayClockReader(region_config=playclock_config)
+    scorebug_detector = DetectScoreBug(template_path=None, use_split_detection=True)
+    scorebug_detector.set_fixed_region(config.fixed_scorebug_coords)
+
+    # Create play clock region extractor
+    pc_x, pc_y, pc_w, pc_h = config.fixed_playclock_coords
+    sb_x, sb_y, _, _ = config.fixed_scorebug_coords
+    playclock_config = PlayClockRegionConfig(
+        x_offset=pc_x - sb_x,
+        y_offset=pc_y - sb_y,
+        width=pc_w,
+        height=pc_h,
+        source_video="",
+        scorebug_template="",
+        samples_used=0,
+    )
+    clock_reader = PlayClockRegionExtractor(region_config=playclock_config)
 
     # Create template reader if template path provided
     template_reader = None
-    if template_library_path and Path(template_library_path).exists():
+    if config.template_library_path and Path(config.template_library_path).exists():
         template_library = DigitTemplateLibrary()
-        if template_library.load(template_library_path):
-            template_reader = TemplatePlayClockReader(template_library, pc_w, pc_h)
+        if template_library.load(config.template_library_path):
+            template_reader = ReadPlayClock(template_library, pc_w, pc_h)
 
     # Initialize timeout tracker if config provided
     timeout_tracker = None
-    if timeout_config_path and Path(timeout_config_path).exists():
-        timeout_tracker = TimeoutTracker(config_path=timeout_config_path)
+    if config.timeout_config_path and Path(config.timeout_config_path).exists():
+        timeout_tracker = DetectTimeouts(config_path=config.timeout_config_path)
 
     return scorebug_detector, clock_reader, template_reader, timeout_tracker
 
@@ -91,10 +97,10 @@ def _process_frame(
     Args:
         img: OpenCV image (numpy array).
         timestamp: Frame timestamp in seconds.
-        scorebug_detector: Initialized ScorebugDetector.
-        clock_reader: Initialized PlayClockReader.
-        template_reader: Initialized TemplatePlayClockReader (or None).
-        timeout_tracker: Initialized TimeoutTracker (or None).
+        scorebug_detector: Initialized DetectScoreBug.
+        clock_reader: Initialized PlayClockRegionExtractor.
+        template_reader: Initialized ReadPlayClock (or None).
+        timeout_tracker: Initialized DetectTimeouts (or None).
         stats: Mutable dict to update with detection statistics.
 
     Returns:
@@ -103,15 +109,12 @@ def _process_frame(
     # Detect scorebug (fast path with fixed region)
     scorebug = scorebug_detector.detect(img)
 
-    frame_result = {
-        "timestamp": timestamp,
-        "scorebug_detected": scorebug.detected,
-        "scorebug_bbox": scorebug.bbox if scorebug.detected else None,
-        "home_timeouts": None,
-        "away_timeouts": None,
-        "clock_value": None,
-        "clock_detected": False,
-    }
+    # Initialize frame result using shared factory
+    frame_result = create_frame_result(
+        timestamp=timestamp,
+        scorebug_detected=scorebug.detected,
+        scorebug_bbox=scorebug.bbox if scorebug.detected else None,
+    )
 
     if scorebug.detected:
         stats["frames_with_scorebug"] += 1
@@ -123,7 +126,7 @@ def _process_frame(
             frame_result["away_timeouts"] = timeout_reading.away_timeouts
 
         # Extract play clock region and template match
-        play_clock_region = clock_reader._extract_region(img, scorebug.bbox)  # pylint: disable=protected-access
+        play_clock_region = clock_reader.extract_region(img, scorebug.bbox)
         if play_clock_region is not None and template_reader:
             clock_result = template_reader.read(play_clock_region)
             frame_result["clock_detected"] = clock_result.detected
@@ -134,17 +137,52 @@ def _process_frame(
     return frame_result
 
 
+def _read_video_frames(cap: Any, start_frame: int, end_frame: int, frame_skip: int, fps: float) -> Tuple[List[Tuple[float, Any]], float]:
+    """
+    Read frames from video capture within the given range.
+
+    Args:
+        cap: OpenCV VideoCapture object.
+        start_frame: First frame to read.
+        end_frame: Last frame to read.
+        frame_skip: Number of frames to skip between samples.
+        fps: Video frames per second.
+
+    Returns:
+        Tuple of (list of (timestamp, frame) tuples, total_io_time).
+    """
+    frames = []
+    io_time = 0.0
+    current_frame = start_frame
+
+    while current_frame < end_frame:
+        t_io_start = time.perf_counter()
+        ret, img = cap.read()
+        io_time += time.perf_counter() - t_io_start
+
+        if not ret:
+            break
+
+        timestamp = current_frame / fps
+        frames.append((timestamp, img))
+
+        # Skip to next sample frame
+        t_io_start = time.perf_counter()
+        for _ in range(frame_skip - 1):
+            cap.grab()
+        io_time += time.perf_counter() - t_io_start
+        current_frame += frame_skip
+
+    return frames, io_time
+
+
+# pylint: disable=too-many-locals
 def _process_chunk(
     chunk_id: int,
-    video_path: str,
-    start_time: float,
-    end_time: float,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
-    progress_dict: Optional[Dict] = None,
+    config: ParallelProcessingConfig,
+    chunk_start: float,
+    chunk_end: float,
+    progress_dict: Optional[MutableMapping[int, Any]] = None,
 ) -> ChunkResult:
     """
     Process a single video chunk using OpenCV.
@@ -154,47 +192,41 @@ def _process_chunk(
 
     Args:
         chunk_id: Identifier for this chunk (for logging).
-        video_path: Path to video file.
-        start_time: Chunk start time in seconds.
-        end_time: Chunk end time in seconds.
-        frame_interval: Time interval between frames.
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory (or None).
-        timeout_config_path: Path to timeout tracker config (or None).
+        config: Parallel processing configuration.
+        chunk_start: Chunk start time in seconds.
+        chunk_end: Chunk end time in seconds.
         progress_dict: Shared dictionary for progress updates.
 
     Returns:
         ChunkResult with processing results.
     """
-    # Import cv2 here to avoid issues with multiprocessing
+    # pylint: disable=import-outside-toplevel
+    # cv2 import must be inside function for multiprocessing - each subprocess
+    # needs its own fresh import to avoid issues with OpenCV's internal state
     import cv2
 
     t_start = time.perf_counter()
-    io_time = 0.0
 
     # Initialize all detection components
-    scorebug_detector, clock_reader, template_reader, timeout_tracker = _init_chunk_detectors(
-        fixed_playclock_coords, fixed_scorebug_coords, template_library_path, timeout_config_path
-    )
+    scorebug_detector, clock_reader, template_reader, timeout_tracker = _init_chunk_detectors(config)
 
     # Open video and seek to start
     t_io_start = time.perf_counter()
-    cap = cv2.VideoCapture(video_path)
+    cap = cv2.VideoCapture(config.video_path)
     if not cap.isOpened():
-        raise RuntimeError(f"Could not open video: {video_path}")
+        raise RuntimeError(f"Could not open video: {config.video_path}")
 
     fps = cap.get(cv2.CAP_PROP_FPS)
-    frame_skip = int(frame_interval * fps)
-    start_frame = int(start_time * fps)
-    end_frame = int(end_time * fps)
+    frame_skip = int(config.frame_interval * fps)
+    start_frame = int(chunk_start * fps)
+    end_frame = int(chunk_end * fps)
     cap.set(cv2.CAP_PROP_POS_FRAMES, start_frame)
-    io_time += time.perf_counter() - t_io_start
+    io_time = time.perf_counter() - t_io_start
 
     # Initialize processing state
     frame_data: List[Dict[str, Any]] = []
     stats = {"total_frames": 0, "frames_with_scorebug": 0, "frames_with_clock": 0}
-    total_expected_frames = max(1, int((end_time - start_time) / frame_interval))
+    total_expected_frames = max(1, int((chunk_end - chunk_start) / config.frame_interval))
 
     # Initialize progress
     if progress_dict is not None:
@@ -236,8 +268,8 @@ def _process_chunk(
 
     return ChunkResult(
         chunk_id=chunk_id,
-        start_time=start_time,
-        end_time=end_time,
+        start_time=chunk_start,
+        end_time=chunk_end,
         frames_processed=stats["total_frames"],
         frames_with_scorebug=stats["frames_with_scorebug"],
         frames_with_clock=stats["frames_with_clock"],
@@ -278,7 +310,7 @@ def _calculate_chunk_boundaries(start_time: float, end_time: float, num_workers:
     return chunks
 
 
-def _create_progress_monitor(progress_dict: Dict, num_workers: int) -> Tuple[threading.Thread, threading.Event]:
+def _create_progress_monitor(progress_dict: MutableMapping[int, Any], num_workers: int) -> Tuple[threading.Thread, threading.Event]:
     """
     Create a progress monitoring thread.
 
@@ -291,7 +323,7 @@ def _create_progress_monitor(progress_dict: Dict, num_workers: int) -> Tuple[thr
     """
     stop_monitor = threading.Event()
 
-    def monitor_progress():
+    def monitor_progress() -> None:
         """Monitor and display progress from workers."""
         while not stop_monitor.is_set():
             _display_progress(progress_dict, num_workers)
@@ -301,7 +333,7 @@ def _create_progress_monitor(progress_dict: Dict, num_workers: int) -> Tuple[thr
     return monitor_thread, stop_monitor
 
 
-def _display_progress(progress_dict: Dict, num_workers: int) -> None:
+def _display_progress(progress_dict: MutableMapping[int, Any], num_workers: int) -> None:
     """
     Build and display current progress string.
 
@@ -337,7 +369,8 @@ def _display_progress(progress_dict: Dict, num_workers: int) -> None:
     overall_pct = min(100, int(100 * total_frames_done / total_frames_expected)) if total_frames_expected > 0 else 0
     progress_str = " | ".join(parts)
 
-    if completed_workers > 0 and completed_workers < num_workers:
+    # Use chained comparison for cleaner code
+    if 0 < completed_workers < num_workers:
         remaining = num_workers - completed_workers
         status_msg = f"  [{overall_pct:3d}%] {progress_str} — waiting for {remaining} worker{'s' if remaining > 1 else ''}..."
     elif completed_workers == num_workers:
@@ -352,26 +385,16 @@ def _display_progress(progress_dict: Dict, num_workers: int) -> None:
 def _submit_chunk_jobs(
     executor: ProcessPoolExecutor,
     chunks: List[Tuple[int, float, float]],
-    video_path: str,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
-    progress_dict: Dict,
-) -> Dict[Future, int]:
+    config: ParallelProcessingConfig,
+    progress_dict: MutableMapping[int, Any],
+) -> Dict[Future[ChunkResult], int]:
     """
     Submit all chunk processing jobs to the executor.
 
     Args:
         executor: ProcessPoolExecutor instance.
         chunks: List of (chunk_id, start_time, end_time) tuples.
-        video_path: Path to video file.
-        frame_interval: Time between frame samples.
-        fixed_playclock_coords: Play clock region coordinates.
-        fixed_scorebug_coords: Scorebug region coordinates.
-        template_library_path: Path to template library.
-        timeout_config_path: Path to timeout config.
+        config: Parallel processing configuration.
         progress_dict: Shared progress dictionary.
 
     Returns:
@@ -382,21 +405,16 @@ def _submit_chunk_jobs(
         future = executor.submit(
             _process_chunk,
             chunk_id,
-            video_path,
+            config,
             chunk_start,
             chunk_end,
-            frame_interval,
-            fixed_playclock_coords,
-            fixed_scorebug_coords,
-            template_library_path,
-            timeout_config_path,
             progress_dict,
         )
         futures[future] = chunk_id
     return futures
 
 
-def _collect_chunk_results(futures: Dict[Future, int]) -> Dict[int, Optional[ChunkResult]]:
+def _collect_chunk_results(futures: Dict[Future[ChunkResult], int]) -> Dict[int, Optional[ChunkResult]]:
     """
     Collect results from all chunk futures as they complete.
 
@@ -458,14 +476,7 @@ def _merge_chunk_results(results: Dict[int, Optional[ChunkResult]], num_workers:
 
 
 def process_video_parallel(
-    video_path: str,
-    start_time: float,
-    end_time: float,
-    frame_interval: float,
-    fixed_playclock_coords: Tuple[int, int, int, int],
-    fixed_scorebug_coords: Tuple[int, int, int, int],
-    template_library_path: Optional[str],
-    timeout_config_path: Optional[str],
+    config: ParallelProcessingConfig,
     num_workers: int = 2,
 ) -> Tuple[List[Dict[str, Any]], Dict[str, int], float]:
     """
@@ -475,22 +486,16 @@ def process_video_parallel(
     Results are merged in chronological order.
 
     Args:
-        video_path: Path to video file.
-        start_time: Start time in seconds.
-        end_time: End time in seconds.
-        frame_interval: Time interval between frames.
-        fixed_playclock_coords: (x, y, w, h) for play clock region.
-        fixed_scorebug_coords: (x, y, w, h) for scorebug region.
-        template_library_path: Path to template library directory.
-        timeout_config_path: Path to timeout tracker config.
+        config: Parallel processing configuration containing video path,
+                time bounds, frame interval, and region coordinates.
         num_workers: Number of parallel workers (default 2).
 
     Returns:
         Tuple of (frame_data_list, stats_dict, total_io_time).
     """
     # Calculate chunk boundaries
-    chunks = _calculate_chunk_boundaries(start_time, end_time, num_workers)
-    chunk_duration = (end_time - start_time) / num_workers
+    chunks = _calculate_chunk_boundaries(config.start_time, config.end_time, num_workers)
+    chunk_duration = (config.end_time - config.start_time) / num_workers
 
     logger.info("Parallel processing: %d workers, %.1fs per chunk", num_workers, chunk_duration)
     for chunk_id, chunk_start, chunk_end in chunks:
@@ -508,9 +513,7 @@ def process_video_parallel(
 
     # Execute chunks in parallel
     with ProcessPoolExecutor(max_workers=num_workers) as executor:
-        futures = _submit_chunk_jobs(
-            executor, chunks, video_path, frame_interval, fixed_playclock_coords, fixed_scorebug_coords, template_library_path, timeout_config_path, progress_dict
-        )
+        futures = _submit_chunk_jobs(executor, chunks, config, progress_dict)
         results = _collect_chunk_results(futures)
 
     # Stop progress monitor and show completion

src/pipeline/{play_detector.py → play_extractor.py}

@@ -1,12 +1,12 @@
-# pylint: disable=too-many-lines
 """
-Play detector pipeline module.
+Play extractor pipeline module.
 
-This module orchestrates the complete play detection pipeline:
+This module orchestrates the complete play extraction pipeline:
 1. Video frame extraction
 2. Scorebug detection
 3. Play clock reading via template matching
 4. Play state machine processing
+5. Post-hoc clock reset identification (timeout/special plays)
 
 Performance optimizations:
 - Streaming processing: read frame -> process immediately (no intermediate storage)
@@ -19,161 +19,27 @@ See docs/ocr_to_template_migration.md for details.
 
 import json
 import logging
-import queue
-import threading
 import time
 from pathlib import Path
 from typing import Optional, List, Dict, Any, Tuple
 
 import cv2
-import easyocr
 import numpy as np
 
-from detectors import ScorebugDetector, ScorebugDetection, PlayClockReader, PlayStateMachine, PlayEvent, PlayClockReading, TimeoutTracker
-from detectors.digit_template_reader import DigitTemplateBuilder, DigitTemplateLibrary, TemplatePlayClockReader
-from detectors.models import PlayClockRegionConfig
-from .models import DetectionConfig, DetectionResult, VideoContext
+from detection import DetectScoreBug, ScorebugDetection, DetectTimeouts
+from readers import ReadPlayClock, PlayClockReading
+from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
+from tracking import TrackPlayState, PlayEvent, PlayMerger, TimeoutInfo, ClockResetIdentifier
+from utils import create_frame_result
+from video import ThreadedFrameReader
+from .models import DetectionConfig, DetectionResult, ParallelProcessingConfig, VideoContext
 from .parallel import process_video_parallel
+from .template_builder_pass import TemplateBuildingPass
 
 logger = logging.getLogger(__name__)
 
-# Global EasyOCR reader instance for template building (lazy-loaded)
-_easyocr_reader = None  # pylint: disable=invalid-name
 
-
-class ThreadedFrameReader:
-    """
-    Background thread for reading video frames.
-
-    Uses a producer-consumer pattern to overlap video I/O with processing.
-    The reader thread reads frames ahead into a queue while the main thread
-    processes frames from the queue.
-
-    This provides significant speedup by hiding video decode latency.
-    """
-
-    def __init__(self, cap: cv2.VideoCapture, start_frame: int, end_frame: int, frame_skip: int, queue_size: int = 32):
-        """
-        Initialize the threaded frame reader.
-
-        Args:
-            cap: OpenCV VideoCapture object
-            start_frame: First frame to read
-            end_frame: Last frame to read
-            frame_skip: Number of frames to skip between reads
-            queue_size: Maximum frames to buffer (default 32)
-        """
-        self.cap = cap
-        self.start_frame = start_frame
-        self.end_frame = end_frame
-        self.frame_skip = frame_skip
-        self.queue_size = queue_size
-
-        # Frame queue: (frame_number, frame_data) or (frame_number, None) for read failures
-        self.frame_queue: queue.Queue = queue.Queue(maxsize=queue_size)
-
-        # Control flags
-        self.stop_flag = threading.Event()
-        self.reader_thread: Optional[threading.Thread] = None
-
-        # Timing stats
-        self.io_time = 0.0
-        self.frames_read = 0
-
-    def start(self) -> None:
-        """Start the background reader thread."""
-        self.stop_flag.clear()
-        self.reader_thread = threading.Thread(target=self._reader_loop, daemon=True)
-        self.reader_thread.start()
-        logger.debug("Threaded frame reader started")
-
-    def stop(self) -> None:
-        """Stop the background reader thread."""
-        self.stop_flag.set()
-        if self.reader_thread and self.reader_thread.is_alive():
-            # Drain the queue to unblock the reader thread
-            try:
-                while True:
-                    self.frame_queue.get_nowait()
-            except queue.Empty:
-                pass
-            self.reader_thread.join(timeout=2.0)
-        logger.debug("Threaded frame reader stopped (read %d frames, %.2fs I/O)", self.frames_read, self.io_time)
-
-    def get_frame(self, timeout: float = 5.0) -> Optional[Tuple[int, Optional[np.ndarray]]]:
-        """
-        Get the next frame from the queue.
-
-        Args:
-            timeout: Maximum time to wait for a frame
-
-        Returns:
-            Tuple of (frame_number, frame_data) or None if queue is empty and reader is done
-        """
-        try:
-            return self.frame_queue.get(timeout=timeout)
-        except queue.Empty:
-            return None
-
-    def _reader_loop(self) -> None:
-        """Background thread that reads frames into the queue."""
-        # Seek to start position
-        t_start = time.perf_counter()
-        self.cap.set(cv2.CAP_PROP_POS_FRAMES, self.start_frame)
-        self.io_time += time.perf_counter() - t_start
-
-        current_frame = self.start_frame
-
-        while current_frame < self.end_frame and not self.stop_flag.is_set():
-            # Read frame
-            t_start = time.perf_counter()
-            ret, frame = self.cap.read()
-            self.io_time += time.perf_counter() - t_start
-
-            if ret:
-                self.frames_read += 1
-                # Put frame in queue (blocks if queue is full)
-                try:
-                    self.frame_queue.put((current_frame, frame), timeout=5.0)
-                except queue.Full:
-                    if self.stop_flag.is_set():
-                        break
-                    logger.warning("Frame queue full, dropping frame %d", current_frame)
-            else:
-                # Signal read failure
-                try:
-                    self.frame_queue.put((current_frame, None), timeout=1.0)
-                except queue.Full:
-                    pass
-
-            # Skip frames
-            t_start = time.perf_counter()
-            for _ in range(self.frame_skip - 1):
-                if self.stop_flag.is_set():
-                    break
-                self.cap.grab()
-            self.io_time += time.perf_counter() - t_start
-
-            current_frame += self.frame_skip
-
-        # Signal end of stream
-        try:
-            self.frame_queue.put(None, timeout=1.0)
-        except queue.Full:
-            pass
-
-
-def _get_easyocr_reader() -> easyocr.Reader:
-    """Get or create the global EasyOCR reader instance for template building."""
-    global _easyocr_reader  # pylint: disable=global-statement
-    if _easyocr_reader is None:
-        logger.info("Initializing EasyOCR reader for template building...")
-        _easyocr_reader = easyocr.Reader(["en"], gpu=False, verbose=False)
-        logger.info("EasyOCR reader initialized")
-    return _easyocr_reader
-
-
-def format_detection_result_dict(result: DetectionResult) -> Dict[str, Any]:
+def format_extraction_result_dict(result: DetectionResult) -> Dict[str, Any]:
     """
     Format a DetectionResult into a dictionary for JSON serialization or API return.
 
@@ -197,37 +63,36 @@ def format_detection_result_dict(result: DetectionResult) -> Dict[str, Any]:
     }
 
 
-class PlayDetector:
+class PlayExtractor:
     """
-    Main pipeline for detecting plays in video.
-
-    This class orchestrates all detection components:
-    - ScorebugDetector: Locates scorebug in frames
-    - TemplatePlayClockReader: Reads play clock digits via template matching
-    - PlayStateMachine: Determines play boundaries
-    - TimeoutTracker: Tracks timeout indicators for 3-class clock reset classification
+    Main pipeline for extracting plays from video.
+
+    This class orchestrates all extraction components:
+    - DetectScoreBug: Locates scorebug in frames
+    - ReadPlayClock: Reads play clock digits via template matching
+    - TrackPlayState: Determines play boundaries
+    - DetectTimeouts: Tracks timeout indicators for 3-class clock reset classification
+    - ClockResetIdentifier: Post-hoc identification of timeout/special plays
     """
 
-    def __init__(self, config: DetectionConfig, timeout_tracker: Optional[TimeoutTracker] = None):
+    def __init__(self, config: DetectionConfig, timeout_tracker: Optional[DetectTimeouts] = None):
         """
-        Initialize the play detector pipeline.
+        Initialize the play extractor pipeline.
 
         Args:
             config: Detection configuration
             timeout_tracker: Optional timeout tracker for clock reset classification
         """
         self.config = config
-        self.scorebug_detector: Optional[ScorebugDetector] = None
-        self.clock_reader: Optional[PlayClockReader] = None
-        self.state_machine: Optional[PlayStateMachine] = None
         self.timeout_tracker = timeout_tracker
 
-        # Template-based clock reading components
+        # Template-based clock reading components (conditionally initialized)
         self.template_builder: Optional[DigitTemplateBuilder] = None
         self.template_library: Optional[DigitTemplateLibrary] = None
-        self.template_reader: Optional[TemplatePlayClockReader] = None
+        self.template_reader: Optional[ReadPlayClock] = None
 
         self._validate_config()
+        # Core components are initialized here (scorebug_detector, clock_reader, state_machine)
         self._initialize_components()
 
     def _validate_config(self) -> None:
@@ -248,11 +113,11 @@ class PlayDetector:
                 raise FileNotFoundError(f"Clock region config not found: {self.config.clock_region_config_path}")
 
     def _initialize_components(self) -> None:
-        """Initialize detection components."""
-        logger.info("Initializing play detector components...")
+        """Initialize extraction components."""
+        logger.info("Initializing play extractor components...")
 
         # Determine if we're using fixed coordinates mode
-        # In this mode, we still use the same detection logic but with pre-set regions
+        # In this mode, we still use the same logic but with pre-set regions
         use_fixed_coords = self.config.fixed_playclock_coords is not None
 
         if use_fixed_coords:
@@ -260,6 +125,7 @@ class PlayDetector:
             logger.info("Fixed coordinates mode - regions pre-configured")
 
             # Compute play clock offset relative to scorebug from absolute coordinates
+            assert self.config.fixed_playclock_coords is not None  # Already checked above, helps mypy
             pc_x, pc_y, pc_w, pc_h = self.config.fixed_playclock_coords
             if self.config.fixed_scorebug_coords:
                 sb_x, sb_y, _, _ = self.config.fixed_scorebug_coords
@@ -273,27 +139,27 @@ class PlayDetector:
             playclock_config = PlayClockRegionConfig(x_offset=x_offset, y_offset=y_offset, width=pc_w, height=pc_h, source_video="", scorebug_template="", samples_used=0)
 
             # Initialize scorebug detector (will set fixed region below)
-            self.scorebug_detector = ScorebugDetector(template_path=None, use_split_detection=self.config.use_split_detection)
+            self.scorebug_detector: DetectScoreBug = DetectScoreBug(template_path=None, use_split_detection=self.config.use_split_detection)
 
             # Set the fixed region immediately so no template matching is needed
             if self.config.fixed_scorebug_coords:
                 self.scorebug_detector.set_fixed_region(self.config.fixed_scorebug_coords)
                 logger.info("Scorebug fixed region set: %s", self.config.fixed_scorebug_coords)
 
-            # Initialize play clock reader with the derived config (for region extraction only)
-            self.clock_reader = PlayClockReader(region_config=playclock_config)
-            logger.info("Play clock reader initialized with offset=(%d, %d), size=(%d, %d)", x_offset, y_offset, pc_w, pc_h)
+            # Initialize play clock region extractor with the derived config
+            self.clock_reader: PlayClockRegionExtractor = PlayClockRegionExtractor(region_config=playclock_config)
+            logger.info("Play clock region extractor initialized with offset=(%d, %d), size=(%d, %d)", x_offset, y_offset, pc_w, pc_h)
         else:
             # Standard mode: use template and config files
-            self.scorebug_detector = ScorebugDetector(template_path=self.config.template_path, use_split_detection=self.config.use_split_detection)
+            self.scorebug_detector = DetectScoreBug(template_path=self.config.template_path, use_split_detection=self.config.use_split_detection)
             logger.info("Scorebug detector initialized (split_detection=%s)", self.config.use_split_detection)
 
-            # Initialize play clock reader from config file (for region extraction only)
-            self.clock_reader = PlayClockReader(region_config_path=self.config.clock_region_config_path)
-            logger.info("Play clock reader initialized")
+            # Initialize play clock region extractor from config file
+            self.clock_reader = PlayClockRegionExtractor(region_config_path=self.config.clock_region_config_path)
+            logger.info("Play clock region extractor initialized")
 
         # Initialize state machine
-        self.state_machine = PlayStateMachine()
+        self.state_machine: TrackPlayState = TrackPlayState()
         logger.info("State machine initialized")
 
         # Initialize template matching components
@@ -309,10 +175,10 @@ class PlayDetector:
             self.template_library = DigitTemplateLibrary()
             if self.template_library.load(self.config.digit_template_path):
                 logger.info("Loaded pre-built digit templates from %s", self.config.digit_template_path)
-                self.template_reader = TemplatePlayClockReader(self.template_library, region_w, region_h)
+                self.template_reader = ReadPlayClock(self.template_library, region_w, region_h)
             else:
                 self.template_library = None
-                logger.info("Could not load templates, will build during detection")
+                logger.info("Could not load templates, will build during extraction")
 
         # Initialize template builder for collection phase if no templates loaded
         if self.template_library is None:
@@ -375,22 +241,7 @@ class PlayDetector:
         """
         Pass 0: Build digit templates by scanning video using TEMPLATE-BASED scorebug detection.
 
-        This pass runs BEFORE the main detection loop. It:
-        1. Uses the scorebug template (created during user setup) for detection
-        2. Scans through video until finding frames with actual scorebugs
-        3. Runs OCR on ONLY frames where scorebug is detected
-        4. Builds templates from samples with high-confidence OCR results
-
-        This solves the problem of building templates from pre-game content that
-        has no scorebug, which causes all subsequent template matching to fail.
-
-        The scorebug is verified using template matching (same as main detection),
-        not just brightness/contrast heuristics.
-
-        Completion criteria:
-        - At least min_samples valid OCR samples collected
-        - OR template coverage >= 70%
-        - OR scanned max_scan_frames frames
+        Delegates to TemplateBuildingPass which handles the actual scanning and OCR.
 
         Args:
             timing: Timing dictionary to update
@@ -398,168 +249,24 @@ class PlayDetector:
         Returns:
             True if templates were built successfully, False otherwise
         """
-        # Configuration for template building scan
-        min_samples = 200  # Minimum valid OCR samples to collect
-        max_scan_frames = 2000  # Maximum frames to scan (about 16 minutes at 0.5s interval)
-        target_coverage = 0.70  # Target template coverage (70%)
-
-        logger.info("Pass 0: Building templates using scorebug template detection...")
-        logger.info("  Target: %d samples OR %.0f%% template coverage", min_samples, target_coverage * 100)
-
-        t_build_start = time.perf_counter()
-
-        # Need both template and fixed coordinates for Pass 0
-        if not self.config.template_path:
-            logger.warning("Pass 0: No scorebug template path provided, cannot detect scorebugs")
-            return False
-
-        template_path = Path(self.config.template_path)
-        if not template_path.exists():
-            logger.warning("Pass 0: Scorebug template not found at %s", template_path)
-            return False
-
-        if not self.config.fixed_scorebug_coords:
-            logger.warning("Pass 0: No fixed scorebug coordinates provided")
-            return False
-
-        sb_x, sb_y, sb_w, sb_h = self.config.fixed_scorebug_coords
-        logger.info("  Scorebug region: (%d, %d, %d, %d)", sb_x, sb_y, sb_w, sb_h)
-        logger.info("  Scorebug template: %s", template_path)
-
-        # Create a temporary ScorebugDetector for Pass 0 detection
-        # This uses the user-created template + fixed region for fast/accurate detection
-        temp_detector = ScorebugDetector(
-            template_path=str(template_path),
-            fixed_region=(sb_x, sb_y, sb_w, sb_h),
-            use_split_detection=self.config.use_split_detection,
-        )
-
-        # Get EasyOCR reader for labeling
-        reader = _get_easyocr_reader()
-
-        # Open video for scanning
-        cap = cv2.VideoCapture(self.config.video_path)
-        if not cap.isOpened():
-            logger.error("Pass 0: Could not open video")
-            return False
-
-        fps = cap.get(cv2.CAP_PROP_FPS)
-        frame_skip = int(self.config.frame_interval * fps)
-
-        # Scan from start of video to find where game content starts
-        scan_start_frame = 0
-
-        cap.set(cv2.CAP_PROP_POS_FRAMES, scan_start_frame)
-
-        valid_samples = 0
-        frames_scanned = 0
-        frames_with_scorebug = 0
-        current_frame = scan_start_frame
-
-        logger.info("  Scanning from frame %d (%.1fs)...", scan_start_frame, scan_start_frame / fps)
-
-        while frames_scanned < max_scan_frames:
-            ret, frame = cap.read()
-            if not ret:
-                break
-
-            current_time = current_frame / fps
-            frames_scanned += 1
-
-            # Use REAL scorebug detection (template matching)
-            scorebug_result = temp_detector.detect(frame)
-
-            if scorebug_result.detected:
-                frames_with_scorebug += 1
-
-                # Extract play clock region using the detected scorebug bbox
-                scorebug_bbox = scorebug_result.bbox
-                play_clock_region = self.clock_reader._extract_region(frame, scorebug_bbox)  # pylint: disable=protected-access
-
-                if play_clock_region is not None:
-                    # Preprocess and run OCR
-                    preprocessed = self.clock_reader._preprocess_for_ocr(play_clock_region)  # pylint: disable=protected-access
-
-                    try:
-                        ocr_results = reader.readtext(preprocessed, allowlist="0123456789", detail=1)
-                        if ocr_results:
-                            best = max(ocr_results, key=lambda x: x[2])
-                            text, confidence = best[1].strip(), best[2]
-
-                            # Parse and validate
-                            if text and confidence >= 0.5:
-                                try:
-                                    value = int(text)
-                                    if 0 <= value <= 40:
-                                        # Add sample to template builder
-                                        self.template_builder.add_sample(play_clock_region, value, current_time, confidence)
-                                        valid_samples += 1
-                                except ValueError:
-                                    pass  # Invalid text, skip
-                    except Exception as e:  # pylint: disable=broad-except
-                        logger.debug("Pass 0: OCR error at %.1fs: %s", current_time, e)
-
-            # Progress logging every 200 frames
-            if frames_scanned % 200 == 0:
-                # Check current template coverage
-                coverage = self.template_builder.get_coverage_estimate()
-                logger.info(
-                    "  Pass 0 progress: %d frames scanned, %d with scorebug, %d valid samples, ~%.0f%% coverage",
-                    frames_scanned,
-                    frames_with_scorebug,
-                    valid_samples,
-                    coverage * 100,
-                )
-
-                # Check completion criteria
-                if valid_samples >= min_samples or coverage >= target_coverage:
-                    logger.info("  Completion criteria met!")
-                    break
-
-            # Skip frames
-            for _ in range(frame_skip - 1):
-                cap.grab()
-            current_frame += frame_skip
-
-        cap.release()
-
-        logger.info(
-            "Pass 0 scan complete: %d frames, %d with scorebug (%.1f%%), %d valid samples",
-            frames_scanned,
-            frames_with_scorebug,
-            100 * frames_with_scorebug / max(1, frames_scanned),
-            valid_samples,
-        )
-
-        if valid_samples < 50:  # Need at least 50 samples to build useful templates
-            logger.warning("Pass 0: Insufficient samples (%d < 50), template building may fail", valid_samples)
-            if frames_with_scorebug == 0:
-                logger.error("Pass 0: No scorebugs detected! Check that the scorebug template matches the video.")
-                return False
-
-        # Build the templates
-        self.template_library = self.template_builder.build_templates(min_samples=2)
-        coverage = self.template_library.get_coverage_status()
-        logger.info(
-            "Pass 0 templates built: %d/%d (%.1f%%) coverage",
-            coverage["total_have"],
-            coverage["total_needed"],
-            100 * coverage["total_have"] / coverage["total_needed"],
+        # Use the extracted TemplateBuildingPass module
+        # Assert: template_builder is initialized when this method is called
+        assert self.template_builder is not None
+        template_pass = TemplateBuildingPass(
+            config=self.config,
+            clock_reader=self.clock_reader,
+            template_builder=self.template_builder,
         )
 
-        # Create template reader
-        region_w = self.clock_reader.config.width if self.clock_reader.config else 50
-        region_h = self.clock_reader.config.height if self.clock_reader.config else 28
-        self.template_reader = TemplatePlayClockReader(self.template_library, region_w, region_h)
+        # Run template building
+        self.template_library, self.template_reader, build_time = template_pass.run()
+        timing["template_building"] = build_time
 
-        timing["template_building"] = time.perf_counter() - t_build_start
-        logger.info("Pass 0 complete: Template building took %.2fs", timing["template_building"])
+        return self.template_library is not None
 
-        return True
-
-    def _streaming_detection_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
+    def _streaming_extraction_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
         """
-        Streaming detection pass: Read frames, process immediately, no intermediate storage.
+        Streaming extraction pass: Read frames, process immediately, no intermediate storage.
 
         This combines the old Pass 1 (frame extraction) and Pass 2 (template matching) into
         a single streaming pass. Each frame is:
@@ -579,7 +286,7 @@ class PlayDetector:
         Returns:
             List of frame data dictionaries with all processing results
         """
-        logger.info("Streaming detection pass: frame extraction + template matching...")
+        logger.info("Streaming extraction pass: frame extraction + template matching...")
 
         logger.info(
             "Threaded reading: frame_skip=%d (%.2f fps effective), frames %d-%d",
@@ -597,7 +304,7 @@ class PlayDetector:
         frame_data: List[Dict[str, Any]] = []
 
         # Flag to track if we've locked the scorebug region
-        scorebug_region_locked = self.scorebug_detector._use_fixed_region if self.scorebug_detector else False
+        scorebug_region_locked = self.scorebug_detector.is_fixed_region_mode if self.scorebug_detector else False
 
         # Progress tracking
         progress_interval = int(30 / self.config.frame_interval)  # Log every 30 seconds of video
@@ -632,7 +339,7 @@ class PlayDetector:
                 # Progress logging
                 if stats["total_frames"] % progress_interval == 0:
                     progress_pct = 100 * (current_time - context.start_time) / (context.end_time - context.start_time)
-                    logger.info("Detection progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
+                    logger.info("Extraction progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
 
         finally:
             # Stop the reader thread and get I/O timing
@@ -641,7 +348,7 @@ class PlayDetector:
             context.cap.release()
 
         logger.info(
-            "Streaming detection complete: %d frames processed, %d with scorebug, %d with clock",
+            "Streaming extraction complete: %d frames processed, %d with scorebug, %d with clock",
             stats["total_frames"],
             stats["frames_with_scorebug"],
             stats["frames_with_clock"],
@@ -651,7 +358,7 @@ class PlayDetector:
 
     def _process_frame_streaming(
         self,
-        frame: np.ndarray,
+        frame: np.ndarray[Any, Any],
         current_time: float,
         timing: Dict[str, float],
         stats: Dict[str, Any],
@@ -680,16 +387,15 @@ class PlayDetector:
         scorebug = self.scorebug_detector.detect(frame)
         timing["scorebug_detection"] += time.perf_counter() - t_start
 
-        # Initialize frame result
-        frame_result = {
-            "timestamp": current_time,
-            "scorebug_detected": scorebug.detected,
-            "scorebug_bbox": scorebug.bbox if scorebug.detected else None,
-            "home_timeouts": None,
-            "away_timeouts": None,
-            "clock_value": None,
-            "clock_detected": False,
-        }
+        # Initialize frame result using shared factory
+        frame_result = create_frame_result(
+            timestamp=current_time,
+            scorebug_detected=scorebug.detected,
+            scorebug_bbox=scorebug.bbox if scorebug.detected else None,
+        )
+
+        # Initialize timeout_info for state machine
+        timeout_info = None
 
         if scorebug.detected:
             stats["frames_with_scorebug"] += 1
@@ -699,10 +405,16 @@ class PlayDetector:
                 timeout_reading = self.timeout_tracker.read_timeouts(frame)
                 frame_result["home_timeouts"] = timeout_reading.home_timeouts
                 frame_result["away_timeouts"] = timeout_reading.away_timeouts
+                # Create TimeoutInfo for state machine clock reset classification
+                timeout_info = TimeoutInfo(
+                    home_timeouts=timeout_reading.home_timeouts,
+                    away_timeouts=timeout_reading.away_timeouts,
+                )
 
             # Extract play clock region and run template matching immediately
             t_start = time.perf_counter()
-            play_clock_region = self.clock_reader._extract_region(frame, scorebug.bbox)  # pylint: disable=protected-access
+            assert scorebug.bbox is not None  # scorebug.detected implies bbox is set
+            play_clock_region = self.clock_reader.extract_region(frame, scorebug.bbox)
             timing["preprocessing"] += time.perf_counter() - t_start
 
             if play_clock_region is not None and self.template_reader:
@@ -717,7 +429,7 @@ class PlayDetector:
                 if clock_result.detected:
                     stats["frames_with_clock"] += 1
 
-                # Update state machine immediately
+                # Update state machine immediately with timeout info for clock reset classification
                 t_start = time.perf_counter()
                 clock_reading = PlayClockReading(
                     detected=clock_result.detected,
@@ -725,60 +437,79 @@ class PlayDetector:
                     confidence=clock_result.confidence,
                     raw_text=f"TEMPLATE_{clock_result.value}" if clock_result.detected else "TEMPLATE_FAILED",
                 )
-                self.state_machine.update(current_time, scorebug, clock_reading)
+                self.state_machine.update(current_time, scorebug, clock_reading, timeout_info)
                 timing["state_machine"] += time.perf_counter() - t_start
         else:
             # No scorebug - still update state machine
             t_start = time.perf_counter()
             clock_reading = PlayClockReading(detected=False, value=None, confidence=0.0, raw_text="NO_SCOREBUG")
-            self.state_machine.update(current_time, scorebug, clock_reading)
+            self.state_machine.update(current_time, scorebug, clock_reading, timeout_info)
             timing["state_machine"] += time.perf_counter() - t_start
 
         return frame_result
 
-    def _finalize_detection(
+    def _finalize_extraction(
         self,
-        frame_data: List[Dict[str, Any]],
         context: VideoContext,
         stats: Dict[str, Any],
         timing: Dict[str, float],
+        frame_data: List[Dict[str, Any]],
     ) -> DetectionResult:
         """
-        Finalize detection: clock reset classification and result building.
+        Finalize extraction: run post-hoc clock reset identification and build result.
+
+        Uses ClockResetIdentifier for 3-class classification of 40→25 clock reset events:
+        - Class A (weird_clock): 25 counts down immediately → rejected
+        - Class B (timeout): Timeout indicator changed → tracked as timeout
+        - Class C (special): Neither A nor B → special play (punt/FG/XP)
 
         Args:
-            frame_data: Complete frame data from streaming detection pass
             context: Video context
             stats: Processing stats
             timing: Timing breakdown
+            frame_data: List of frame data dicts with clock values and timeout counts
 
         Returns:
             Final DetectionResult
         """
-        # Frame data already has clock values from streaming pass
+        # Log timing breakdown
+        self._log_timing_breakdown(timing)
+
+        # Get plays from state machine (normal 40-second plays)
+        state_machine_plays = self.state_machine.get_plays()
+        play_stats = self.state_machine.get_stats()
 
-        # Detect and classify clock resets
-        clock_reset_plays, clock_reset_stats = self._detect_clock_resets(frame_data)
+        # Run post-hoc clock reset identification (40→25 transitions)
+        clock_reset_identifier = ClockResetIdentifier()
+        clock_reset_plays, clock_reset_stats = clock_reset_identifier.identify(frame_data)
         logger.info(
-            "Clock reset detection: %d total, %d weird (rejected), %d timeouts, %d special plays",
+            "Clock reset identification: %d total, %d weird (rejected), %d timeouts, %d special plays",
             clock_reset_stats.get("total", 0),
             clock_reset_stats.get("weird_clock", 0),
             clock_reset_stats.get("timeout", 0),
             clock_reset_stats.get("special", 0),
         )
 
-        # Log timing breakdown
-        self._log_timing_breakdown(timing)
+        # Merge clock reset stats into play stats
+        play_stats["clock_reset_events"] = clock_reset_stats
 
-        # Build result - combine state machine plays with clock reset plays
-        state_machine_plays = self.state_machine.get_plays()
-        play_stats = self.state_machine.get_stats()
+        # Merge state machine plays with clock reset plays using PlayMerger
+        merger = PlayMerger()
+        plays = merger.merge(state_machine_plays, clock_reset_plays)
 
-        # Merge clock reset stats
-        play_stats["clock_reset_events"] = clock_reset_stats
+        # Recalculate stats from merged plays
+        start_methods: Dict[str, int] = {}
+        end_methods: Dict[str, int] = {}
+        play_types: Dict[str, int] = {}
+        for play in plays:
+            start_methods[play.start_method] = start_methods.get(play.start_method, 0) + 1
+            end_methods[play.end_method] = end_methods.get(play.end_method, 0) + 1
+            play_types[play.play_type] = play_types.get(play.play_type, 0) + 1
 
-        # Combine and deduplicate plays
-        plays = self._merge_plays(state_machine_plays, clock_reset_plays)
+        play_stats["total_plays"] = len(plays)
+        play_stats["start_methods"] = start_methods
+        play_stats["end_methods"] = end_methods
+        play_stats["play_types"] = play_types
 
         result = DetectionResult(
             video=Path(self.config.video_path).name,
@@ -793,16 +524,16 @@ class PlayDetector:
         )
 
         # Log final summary
-        logger.info("Detection complete!")
+        logger.info("Extraction complete!")
         logger.info("Processed %d frames", stats["total_frames"])
         logger.info("Frames with scorebug: %d (%.1f%%)", stats["frames_with_scorebug"], 100 * stats["frames_with_scorebug"] / max(1, stats["total_frames"]))
         logger.info("Frames with clock: %d (%.1f%%)", stats["frames_with_clock"], 100 * stats["frames_with_clock"] / max(1, stats["total_frames"]))
-        logger.info("Plays detected: %d", len(plays))
+        logger.info("Plays extracted: %d", len(plays))
 
         return result
 
     def _log_timing_breakdown(self, timing: Dict[str, float]) -> None:
-        """Log the timing breakdown for the detection run."""
+        """Log the timing breakdown for the extraction run."""
         total_time = sum(timing.values())
         logger.info("=" * 50)
         logger.info("TIMING BREAKDOWN")
@@ -813,23 +544,23 @@ class PlayDetector:
         logger.info("  TOTAL: %.2fs", total_time)
         logger.info("=" * 50)
 
-    def detect(self) -> DetectionResult:
+    def extract(self) -> DetectionResult:
         """
-        Run play detection on the video segment.
+        Run play extraction on the video segment.
 
         Uses streaming processing for optimal performance:
         - Pass 0 (if needed): Build digit templates using OCR on scorebug-verified frames
         - Streaming pass: Read frame -> extract region -> template match -> state machine update
           (threaded video I/O overlaps reading with processing)
-        - Finalize: Clock reset classification and result building
+        - Finalize: Clock reset identification and result building
 
         When fixed coordinates are provided, the scorebug detection step simply verifies
         the scorebug is present at the known location (faster than searching).
 
         Returns:
-            DetectionResult with all detected plays
+            DetectionResult with all extracted plays
         """
-        logger.info("Starting play detection...")
+        logger.info("Starting play extraction...")
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
 
@@ -850,24 +581,26 @@ class PlayDetector:
         if not self.template_reader and self.template_builder:
             success = self._pass0_build_templates_with_real_detection(timing)
             if not success:
-                logger.warning("Pass 0 failed to build templates, detection may fail or be inaccurate")
+                logger.warning("Pass 0 failed to build templates, extraction may fail or be inaccurate")
 
         # Log mode info (after Pass 0 so we can show if templates were built)
-        self._log_detection_mode()
+        self._log_extraction_mode()
 
         # Initialize video and get processing context
         context, stats, _ = self._open_video_and_get_context()
 
-        # Streaming detection pass: read frames + template match + state machine (all in one)
+        # Streaming extraction pass: read frames + template match + state machine (all in one)
         # Uses threaded video I/O to overlap reading with processing
-        frame_data = self._streaming_detection_pass(context, stats, timing)
+        # Returns frame_data needed for post-hoc clock reset identification
+        frame_data = self._streaming_extraction_pass(context, stats, timing)
 
-        # Finalize: Clock reset classification and result building
-        return self._finalize_detection(frame_data, context, stats, timing)
+        # Finalize: Post-hoc clock reset identification (Class A/B/C) and result building
+        return self._finalize_extraction(context, stats, timing, frame_data)
 
-    def detect_parallel(self, num_workers: int = 2, output_dir: Optional[Path] = None) -> DetectionResult:
+    # pylint: disable=too-many-locals
+    def extract_parallel(self, num_workers: int = 2, output_dir: Optional[Path] = None) -> DetectionResult:
         """
-        Run play detection using parallel chunk processing.
+        Run play extraction using parallel chunk processing.
 
         This provides ~26% speedup over sequential processing by using multiple
         processes to read and process different segments of the video simultaneously.
@@ -877,18 +610,16 @@ class PlayDetector:
         2. Save templates to disk for worker processes to load
         3. Parallel pass: Each worker processes a video chunk independently
         4. Merge: Combine frame data from all chunks in chronological order
-        5. State machine: Process merged data to detect plays
+        5. State machine: Process merged data to extract plays
 
         Args:
             num_workers: Number of parallel workers (default 2).
             output_dir: Output directory for templates (required).
 
         Returns:
-            DetectionResult with all detected plays
+            DetectionResult with all extracted plays
         """
-        import time as time_module
-
-        logger.info("Starting parallel play detection (%d workers)...", num_workers)
+        logger.info("Starting parallel play extraction (%d workers)...", num_workers)
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
 
@@ -906,7 +637,7 @@ class PlayDetector:
         if not self.template_reader and self.template_builder:
             success = self._pass0_build_templates_with_real_detection(timing)
             if not success:
-                logger.warning("Pass 0 failed to build templates, detection may fail or be inaccurate")
+                logger.warning("Pass 0 failed to build templates, extraction may fail or be inaccurate")
 
         # Save templates to disk for worker processes
         template_path = None
@@ -933,9 +664,13 @@ class PlayDetector:
 
         # Run parallel processing
         logger.info("Starting parallel frame extraction...")
-        t_parallel_start = time_module.perf_counter()
+        t_parallel_start = time.perf_counter()
 
-        frame_data, stats, io_time = process_video_parallel(
+        # Create parallel processing config
+        # Asserts: validated by _validate_config, parallel mode requires fixed coords
+        assert self.config.fixed_playclock_coords is not None
+        assert self.config.fixed_scorebug_coords is not None
+        parallel_config = ParallelProcessingConfig(
             video_path=self.config.video_path,
             start_time=self.config.start_time,
             end_time=end_time,
@@ -944,12 +679,13 @@ class PlayDetector:
             fixed_scorebug_coords=self.config.fixed_scorebug_coords,
             template_library_path=str(template_path) if template_path else None,
             timeout_config_path=timeout_config_path,
-            num_workers=num_workers,
         )
 
+        frame_data, stats, io_time = process_video_parallel(parallel_config, num_workers=num_workers)
+
         timing["video_io"] = io_time
         # Estimate template matching time from parallel processing
-        parallel_time = time_module.perf_counter() - t_parallel_start
+        parallel_time = time.perf_counter() - t_parallel_start
         timing["template_matching"] = max(0, parallel_time - io_time - timing["template_building"])
 
         logger.info("Parallel processing complete: %d frames", stats["total_frames"])
@@ -968,7 +704,7 @@ class PlayDetector:
         )
 
         # Run state machine on merged frame data
-        t_sm_start = time_module.perf_counter()
+        t_sm_start = time.perf_counter()
         for frame in frame_data:
             # Create proper objects for state machine
             scorebug = ScorebugDetection(
@@ -982,8 +718,15 @@ class PlayDetector:
                 confidence=1.0 if frame.get("clock_detected") else 0.0,
                 raw_text=f"PARALLEL_{frame.get('clock_value')}" if frame.get("clock_detected") else "PARALLEL_FAILED",
             )
-            self.state_machine.update(frame["timestamp"], scorebug, clock_reading)
-        timing["state_machine"] = time_module.perf_counter() - t_sm_start
+            # Create timeout info for clock reset classification
+            timeout_info = None
+            if frame.get("home_timeouts") is not None or frame.get("away_timeouts") is not None:
+                timeout_info = TimeoutInfo(
+                    home_timeouts=frame.get("home_timeouts"),
+                    away_timeouts=frame.get("away_timeouts"),
+                )
+            self.state_machine.update(frame["timestamp"], scorebug, clock_reading, timeout_info)
+        timing["state_machine"] = time.perf_counter() - t_sm_start
 
         # Update stats dict
         stats_dict = {
@@ -992,12 +735,12 @@ class PlayDetector:
             "frames_with_clock": stats["frames_with_clock"],
         }
 
-        # Finalize: Clock reset classification and result building
-        return self._finalize_detection(frame_data, context, stats_dict, timing)
+        # Finalize: Post-hoc clock reset identification (Class A/B/C) and result building
+        return self._finalize_extraction(context, stats_dict, timing, frame_data)
 
-    def _log_detection_mode(self) -> None:
-        """Log the detection mode being used."""
-        use_fixed_region = self.scorebug_detector and self.scorebug_detector._use_fixed_region
+    def _log_extraction_mode(self) -> None:
+        """Log the extraction mode being used."""
+        use_fixed_region = self.scorebug_detector and self.scorebug_detector.is_fixed_region_mode
 
         if use_fixed_region:
             logger.info("Mode: Fixed region (scorebug location pre-configured)")
@@ -1012,290 +755,6 @@ class PlayDetector:
         else:
             logger.info("  Will build templates using fallback method")
 
-    def _detect_clock_resets(self, frame_data: List[Dict[str, Any]]) -> Tuple[List[PlayEvent], Dict[str, int]]:
-        """
-        Detect and classify 40 -> 25 clock reset events.
-
-        Classification:
-        - Class A (weird_clock): 25 counts down immediately -> rejected
-        - Class B (timeout): Timeout indicator changed -> tracked as timeout
-        - Class C (special): Neither A nor B -> special play with extension
-
-        Args:
-            frame_data: List of frame data with clock values and timeout counts
-
-        Returns:
-            Tuple of (list of PlayEvent for valid clock resets, stats dict)
-        """
-        plays = []
-        stats = {"total": 0, "weird_clock": 0, "timeout": 0, "special": 0}
-
-        # Parameters
-        immediate_countdown_window = 2.0  # Seconds to check if 25 counts down
-        special_play_extension = 10.0  # Extension for Class C plays
-
-        prev_clock = None
-        saw_40_at = None
-
-        for i, frame in enumerate(frame_data):
-            clock_value = frame.get("clock_value")
-            timestamp = frame["timestamp"]
-
-            if clock_value is not None:
-                # Detect 40 -> 25 transition
-                if prev_clock == 40 and clock_value == 25:
-                    stats["total"] += 1
-                    _ = timestamp - saw_40_at if saw_40_at else 0.0  # time_at_40 for potential future use
-
-                    # Check if 25 immediately counts down (Class A: weird clock)
-                    is_immediate_countdown = self._check_immediate_countdown(frame_data, i, immediate_countdown_window)
-
-                    # Check if timeout changed (Class B: team timeout)
-                    timeout_team = self._check_timeout_change(frame_data, i)
-
-                    if is_immediate_countdown:
-                        # Class A: Weird clock behavior - reject
-                        stats["weird_clock"] += 1
-                        logger.debug("Clock reset at %.1fs: weird_clock (25 counts down immediately)", timestamp)
-                    elif timeout_team:
-                        # Class B: Team timeout - record but mark as timeout
-                        stats["timeout"] += 1
-                        play_end = self._find_clock_reset_play_end(frame_data, i, max_duration=30.0)  # Timeouts can last longer
-                        play = PlayEvent(
-                            play_number=0,
-                            start_time=timestamp,
-                            end_time=play_end,
-                            confidence=0.8,
-                            start_method=f"timeout_{timeout_team}",
-                            end_method="timeout_end",
-                            direct_end_time=play_end,
-                            start_clock_value=prev_clock,
-                            end_clock_value=25,
-                            play_type="timeout",
-                        )
-                        plays.append(play)
-                        logger.debug("Clock reset at %.1fs: timeout (%s team)", timestamp, timeout_team)
-                    else:
-                        # Class C: Special play (injury/punt/FG/XP) - end at scorebug disappear OR max_duration from start
-                        stats["special"] += 1
-                        play_end = self._find_clock_reset_play_end(frame_data, i, max_duration=special_play_extension)
-                        # Determine end method based on whether we hit max duration or scorebug disappeared first
-                        play_duration = play_end - timestamp
-                        if play_duration >= special_play_extension - 0.1:  # Close to max duration (within tolerance)
-                            end_method = "max_duration"
-                        else:
-                            end_method = "scorebug_disappeared"
-                        play = PlayEvent(
-                            play_number=0,
-                            start_time=timestamp,
-                            end_time=play_end,
-                            confidence=0.8,
-                            start_method="clock_reset_special",
-                            end_method=end_method,
-                            direct_end_time=play_end,
-                            start_clock_value=prev_clock,
-                            end_clock_value=25,
-                            play_type="special",
-                        )
-                        plays.append(play)
-                        logger.debug("Clock reset at %.1fs: special play (%.1fs duration)", timestamp, play_end - timestamp)
-
-                # Track when 40 first appeared
-                if clock_value == 40 and prev_clock != 40:
-                    saw_40_at = timestamp
-
-                prev_clock = clock_value
-
-        return plays, stats
-
-    def _check_immediate_countdown(self, frame_data: List[Dict[str, Any]], frame_idx: int, window: float) -> bool:
-        """Check if 25 immediately starts counting down (indicates weird clock behavior)."""
-        reset_timestamp = frame_data[frame_idx]["timestamp"]
-
-        for j in range(frame_idx + 1, len(frame_data)):
-            frame = frame_data[j]
-            elapsed = frame["timestamp"] - reset_timestamp
-            if elapsed > window:
-                break
-            clock_value = frame.get("clock_value")
-            if clock_value is not None and clock_value < 25:
-                return True  # 25 counted down - weird clock
-
-        return False
-
-    def _check_timeout_change(self, frame_data: List[Dict[str, Any]], frame_idx: int) -> Optional[str]:
-        """Check if a timeout indicator changed around the reset."""
-        # Get timeout counts before reset
-        before_home = None
-        before_away = None
-
-        for j in range(frame_idx - 1, max(0, frame_idx - 20), -1):
-            frame = frame_data[j]
-            if frame.get("home_timeouts") is not None:
-                before_home = frame.get("home_timeouts", 3)
-                before_away = frame.get("away_timeouts", 3)
-                break
-
-        if before_home is None:
-            return None
-
-        # Look forward for timeout change (up to 15 seconds)
-        frame_interval = frame_data[1]["timestamp"] - frame_data[0]["timestamp"] if len(frame_data) > 1 else 0.5
-        max_frames_forward = int(15.0 / frame_interval) if frame_interval > 0 else 30
-
-        for j in range(frame_idx, min(len(frame_data), frame_idx + max_frames_forward)):
-            frame = frame_data[j]
-            if frame.get("home_timeouts") is not None:
-                after_home = frame.get("home_timeouts", 3)
-                after_away = frame.get("away_timeouts", 3)
-
-                if after_home < before_home:
-                    return "home"
-                if after_away < before_away:
-                    return "away"
-
-        return None
-
-    def _find_clock_reset_play_end(self, frame_data: List[Dict[str, Any]], frame_idx: int, max_duration: float) -> float:
-        """
-        Find the end time for a clock reset play (Class C special play).
-
-        The play ends when EITHER:
-        - Scorebug disappears (cut to commercial/replay)
-        - max_duration seconds have elapsed since play START
-
-        Whichever comes FIRST.
-
-        Args:
-            frame_data: Frame data list
-            frame_idx: Index of the frame where 40->25 reset occurred
-            max_duration: Maximum play duration from start (e.g., 10 seconds)
-
-        Returns:
-            Play end timestamp
-        """
-        start_timestamp = frame_data[frame_idx]["timestamp"]
-        max_end_time = start_timestamp + max_duration
-
-        # Look for scorebug disappearance (but cap at max_duration from start)
-        for j in range(frame_idx + 1, len(frame_data)):
-            frame = frame_data[j]
-            timestamp = frame["timestamp"]
-
-            # If we've exceeded max_duration, end the play at max_duration
-            if timestamp >= max_end_time:
-                return max_end_time
-
-            # Check for play clock disappearance (works for both fixed coords and standard mode)
-            clock_available = frame.get("clock_detected", frame.get("scorebug_detected", False))
-            if not clock_available:
-                return timestamp
-
-        # Default: end at max_duration (or end of data if shorter)
-        return min(max_end_time, frame_data[-1]["timestamp"] if frame_data else max_end_time)
-
-    def _merge_plays(self, state_machine_plays: List[PlayEvent], clock_reset_plays: List[PlayEvent]) -> List[PlayEvent]:
-        """
-        Merge plays from state machine and clock reset detection, removing overlaps and duplicates.
-
-        Handles two types of duplicates:
-        1. Overlapping plays (start_time < last.end_time)
-        2. Close plays (start times within proximity_threshold) representing the same event
-
-        Args:
-            state_machine_plays: Plays from the state machine
-            clock_reset_plays: Plays from clock reset detection
-
-        Returns:
-            Merged list of plays sorted by start time
-        """
-        all_plays = list(state_machine_plays) + list(clock_reset_plays)
-        all_plays.sort(key=lambda p: p.start_time)
-
-        if not all_plays:
-            return []
-
-        # Proximity threshold: plays within this time are considered the same event
-        proximity_threshold = 5.0  # seconds
-
-        # Remove overlapping and close plays (keep state machine plays over clock reset plays)
-        filtered = [all_plays[0]]
-        for play in all_plays[1:]:
-            last = filtered[-1]
-
-            # Check for overlap OR proximity (both indicate same event)
-            is_overlapping = play.start_time < last.end_time
-            is_close = abs(play.start_time - last.start_time) < proximity_threshold
-
-            if is_overlapping or is_close:
-                # Same event detected twice - keep the better one
-                # Priority: normal > special > timeout (normal plays are most reliable)
-                type_priority = {"normal": 3, "special": 2, "timeout": 1}
-                last_priority = type_priority.get(last.play_type, 0)
-                play_priority = type_priority.get(play.play_type, 0)
-
-                if play_priority > last_priority:
-                    filtered[-1] = play  # Replace with higher priority play
-                elif play_priority == last_priority and play.confidence > last.confidence:
-                    filtered[-1] = play  # Same priority, but higher confidence
-                # else: keep existing
-            else:
-                filtered.append(play)
-
-        # Apply quiet time filter to remove false positives after normal plays
-        filtered = self._apply_quiet_time_filter(filtered)
-
-        # Renumber plays
-        for i, play in enumerate(filtered, 1):
-            play.play_number = i
-
-        return filtered
-
-    def _apply_quiet_time_filter(self, plays: List[PlayEvent], quiet_time: float = 10.0) -> List[PlayEvent]:
-        """
-        Apply quiet time filter after normal plays.
-
-        After a normal play ends, no new special/timeout plays can start for quiet_time seconds.
-        This filters out false positives from penalties during plays (false starts, delay of game, etc.).
-
-        Args:
-            plays: List of plays sorted by start time
-            quiet_time: Seconds of quiet time after normal plays (default 10.0)
-
-        Returns:
-            Filtered list of plays
-        """
-        if not plays:
-            return []
-
-        filtered = []
-        last_normal_end = -999.0  # Track when last normal play ended
-
-        for play in plays:
-            # Check if this play starts during quiet time after a normal play
-            if play.start_time < last_normal_end + quiet_time and play.play_type != "normal":
-                # This non-normal play starts during quiet time - filter it out
-                time_since_normal = play.start_time - last_normal_end
-                logger.debug(
-                    "Quiet time filter: Removing %s play at %.1fs (%.1fs after normal play ended)",
-                    play.play_type,
-                    play.start_time,
-                    time_since_normal,
-                )
-                continue
-
-            filtered.append(play)
-
-            # Update last normal play end time
-            if play.play_type == "normal":
-                last_normal_end = play.end_time
-
-        removed_count = len(plays) - len(filtered)
-        if removed_count > 0:
-            logger.info("Quiet time filter removed %d plays", removed_count)
-
-        return filtered
-
     def _play_to_dict(self, play: PlayEvent) -> Dict[str, Any]:
         """Convert PlayEvent to dictionary for JSON serialization."""
         return {
@@ -1314,16 +773,16 @@ class PlayDetector:
 
     def save_results(self, result: DetectionResult, output_path: str) -> None:
         """
-        Save detection results to a JSON file.
+        Save extraction results to a JSON file.
 
         Args:
-            result: Detection results
+            result: Extraction results
             output_path: Path to output file
         """
         output = Path(output_path)
         output.parent.mkdir(parents=True, exist_ok=True)
 
-        data = format_detection_result_dict(result)
+        data = format_extraction_result_dict(result)
 
         # Include configuration if provided (for reproducibility)
         if result.config:

src/pipeline/template_builder_pass.py

@@ -0,0 +1,334 @@
+"""
+Template building pass (Pass 0) for the play detection pipeline.
+
+This module handles the initial phase of building digit templates by scanning
+the video for frames with scorebugs and running OCR on the play clock region.
+These templates are then used for fast template matching in subsequent passes.
+
+Note: This module uses functions instead of a class because there is only one
+public entry point (run_template_building_pass). The class pattern was causing
+"too few public methods" warnings.
+"""
+
+import logging
+import time
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+import cv2
+import easyocr
+import numpy as np
+
+from detection import DetectScoreBug
+from readers import ReadPlayClock
+from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionExtractor
+from .models import DetectionConfig
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=1)
+def get_easyocr_reader() -> easyocr.Reader:
+    """Get or create the EasyOCR reader instance (lazily loaded, cached)."""
+    logger.info("Initializing EasyOCR reader for template building...")
+    reader = easyocr.Reader(["en"], gpu=False, verbose=False)
+    logger.info("EasyOCR reader initialized")
+    return reader
+
+
+def _validate_config(config: DetectionConfig) -> bool:
+    """Validate that required configuration is present for template building."""
+    if not config.template_path:
+        logger.warning("Pass 0: No scorebug template path provided, cannot detect scorebugs")
+        return False
+
+    template_path = Path(config.template_path)
+    if not template_path.exists():
+        logger.warning("Pass 0: Scorebug template not found at %s", template_path)
+        return False
+
+    if not config.fixed_scorebug_coords:
+        logger.warning("Pass 0: No fixed scorebug coordinates provided")
+        return False
+
+    return True
+
+
+def _process_scorebug_frame(
+    frame: np.ndarray[Any, Any],
+    scorebug_bbox: Tuple[int, int, int, int],
+    current_time: float,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    reader: easyocr.Reader,
+) -> int:
+    """
+    Process a frame with detected scorebug and extract play clock via OCR.
+
+    Args:
+        frame: Video frame
+        scorebug_bbox: Scorebug bounding box (x, y, w, h)
+        current_time: Current timestamp
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        reader: EasyOCR reader
+
+    Returns:
+        1 if a valid sample was collected, 0 otherwise
+    """
+    # Extract play clock region
+    play_clock_region = clock_reader.extract_region(frame, scorebug_bbox)
+    if play_clock_region is None:
+        return 0
+
+    # Preprocess and run OCR
+    preprocessed = clock_reader.preprocess_for_ocr(play_clock_region)
+
+    try:
+        ocr_results = reader.readtext(preprocessed, allowlist="0123456789", detail=1)
+        if not ocr_results:
+            return 0
+
+        best = max(ocr_results, key=lambda x: x[2])
+        text, confidence = best[1].strip(), best[2]
+
+        # Parse and validate
+        if text and confidence >= 0.5:
+            try:
+                value = int(text)
+                if 0 <= value <= 40:
+                    template_builder.add_sample(play_clock_region, value, current_time, confidence)
+                    return 1
+            except ValueError:
+                pass  # Invalid text, skip
+
+    except Exception as e:  # pylint: disable=broad-except
+        logger.debug("Pass 0: OCR error at %.1fs: %s", current_time, e)
+
+    return 0
+
+
+def _scan_video(
+    config: DetectionConfig,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    temp_detector: DetectScoreBug,
+    reader: easyocr.Reader,
+    min_samples: int,
+    max_scan_frames: int,
+    target_coverage: float,
+) -> Tuple[int, int, int]:
+    """
+    Scan video frames and collect OCR samples for template building.
+
+    Args:
+        config: Detection configuration
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        temp_detector: Scorebug detector to use
+        reader: EasyOCR reader instance
+        min_samples: Minimum valid OCR samples to collect
+        max_scan_frames: Maximum frames to scan
+        target_coverage: Target template coverage (0.0-1.0)
+
+    Returns:
+        Tuple of (valid_samples, frames_scanned, frames_with_scorebug)
+    """
+    # Open video
+    cap = cv2.VideoCapture(config.video_path)
+    if not cap.isOpened():
+        logger.error("Pass 0: Could not open video")
+        return 0, 0, 0
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frame_skip = int(config.frame_interval * fps)
+
+    # Initialize counters
+    valid_samples = 0
+    frames_scanned = 0
+    frames_with_scorebug = 0
+    current_frame = 0
+
+    cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
+    logger.info("  Scanning from frame 0 (0.0s)...")
+
+    try:
+        while frames_scanned < max_scan_frames:
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            current_time = current_frame / fps
+            frames_scanned += 1
+
+            # Detect scorebug using template matching
+            scorebug_result = temp_detector.detect(frame)
+
+            if scorebug_result.detected:
+                frames_with_scorebug += 1
+                assert scorebug_result.bbox is not None  # detected implies bbox is set
+                valid_samples += _process_scorebug_frame(frame, scorebug_result.bbox, current_time, clock_reader, template_builder, reader)
+
+            # Progress logging every 200 frames
+            if frames_scanned % 200 == 0:
+                coverage = template_builder.get_coverage_estimate()
+                logger.info(
+                    "  Pass 0 progress: %d frames scanned, %d with scorebug, %d valid samples, ~%.0f%% coverage",
+                    frames_scanned,
+                    frames_with_scorebug,
+                    valid_samples,
+                    coverage * 100,
+                )
+
+                # Check completion criteria
+                if valid_samples >= min_samples or coverage >= target_coverage:
+                    logger.info("  Completion criteria met!")
+                    break
+
+            # Skip frames
+            for _ in range(frame_skip - 1):
+                cap.grab()
+            current_frame += frame_skip
+
+    finally:
+        cap.release()
+
+    return valid_samples, frames_scanned, frames_with_scorebug
+
+
+# pylint: disable=too-many-locals
+def run_template_building_pass(
+    config: DetectionConfig,
+    clock_reader: PlayClockRegionExtractor,
+    template_builder: DigitTemplateBuilder,
+    min_samples: int = 200,
+    max_scan_frames: int = 2000,
+    target_coverage: float = 0.70,
+) -> Tuple[Optional[DigitTemplateLibrary], Optional[ReadPlayClock], float]:
+    """
+    Run the template building pass (Pass 0).
+
+    This pass runs BEFORE the main detection loop. It:
+    1. Uses the scorebug template (created during user setup) for detection
+    2. Scans through video until finding frames with actual scorebugs
+    3. Runs OCR on ONLY frames where scorebug is detected
+    4. Builds templates from samples with high-confidence OCR results
+
+    This solves the problem of building templates from pre-game content that
+    has no scorebug, which causes all subsequent template matching to fail.
+
+    Args:
+        config: Detection configuration
+        clock_reader: Play clock region extractor
+        template_builder: Digit template builder
+        min_samples: Minimum valid OCR samples to collect (default: 200)
+        max_scan_frames: Maximum frames to scan (default: 2000)
+        target_coverage: Target template coverage 0.0-1.0 (default: 0.70)
+
+    Returns:
+        Tuple of (template_library, template_reader, build_time).
+        template_library and template_reader may be None if building failed.
+    """
+    logger.info("Pass 0: Building templates using scorebug template detection...")
+    logger.info("  Target: %d samples OR %.0f%% template coverage", min_samples, target_coverage * 100)
+
+    t_build_start = time.perf_counter()
+
+    # Validate configuration
+    if not _validate_config(config):
+        return None, None, time.perf_counter() - t_build_start
+
+    # Assert: _validate_config guarantees fixed_scorebug_coords is set
+    assert config.fixed_scorebug_coords is not None
+
+    # Create temporary scorebug detector for Pass 0
+    sb_x, sb_y, sb_w, sb_h = config.fixed_scorebug_coords
+    logger.info("  Scorebug region: (%d, %d, %d, %d)", sb_x, sb_y, sb_w, sb_h)
+    logger.info("  Scorebug template: %s", config.template_path)
+
+    temp_detector = DetectScoreBug(
+        template_path=str(config.template_path),
+        fixed_region=(sb_x, sb_y, sb_w, sb_h),
+        use_split_detection=config.use_split_detection,
+    )
+
+    # Get EasyOCR reader for labeling
+    reader = get_easyocr_reader()
+
+    # Scan video and collect samples
+    valid_samples, frames_scanned, frames_with_scorebug = _scan_video(config, clock_reader, template_builder, temp_detector, reader, min_samples, max_scan_frames, target_coverage)
+
+    # Log scan results
+    logger.info(
+        "Pass 0 scan complete: %d frames, %d with scorebug (%.1f%%), %d valid samples",
+        frames_scanned,
+        frames_with_scorebug,
+        100 * frames_with_scorebug / max(1, frames_scanned),
+        valid_samples,
+    )
+
+    # Check if we have enough samples
+    if valid_samples < 50:
+        logger.warning("Pass 0: Insufficient samples (%d < 50), template building may fail", valid_samples)
+        if frames_with_scorebug == 0:
+            logger.error("Pass 0: No scorebugs detected! Check that the scorebug template matches the video.")
+            return None, None, time.perf_counter() - t_build_start
+
+    # Build templates
+    template_library = template_builder.build_templates(min_samples=2)
+    coverage = template_library.get_coverage_status()
+    logger.info(
+        "Pass 0 templates built: %d/%d (%.1f%%) coverage",
+        coverage["total_have"],
+        coverage["total_needed"],
+        100 * coverage["total_have"] / coverage["total_needed"],
+    )
+
+    # Create template reader
+    region_w = clock_reader.config.width if clock_reader.config else 50
+    region_h = clock_reader.config.height if clock_reader.config else 28
+    template_reader = ReadPlayClock(template_library, region_w, region_h)
+
+    build_time = time.perf_counter() - t_build_start
+    logger.info("Pass 0 complete: Template building took %.2fs", build_time)
+
+    return template_library, template_reader, build_time
+
+
+# Keep the class for backward compatibility, but it now delegates to the function
+class TemplateBuildingPass:  # pylint: disable=too-few-public-methods
+    """
+    Backward-compatible class wrapper for run_template_building_pass.
+
+    Deprecated: Use run_template_building_pass() function directly instead.
+    This class exists only for backward compatibility with existing code.
+    """
+
+    def __init__(
+        self,
+        config: DetectionConfig,
+        clock_reader: PlayClockRegionExtractor,
+        template_builder: DigitTemplateBuilder,
+        min_samples: int = 200,
+        max_scan_frames: int = 2000,
+        target_coverage: float = 0.70,
+    ):
+        """Initialize the template building pass."""
+        self.config = config
+        self.clock_reader = clock_reader
+        self.template_builder = template_builder
+        self.min_samples = min_samples
+        self.max_scan_frames = max_scan_frames
+        self.target_coverage = target_coverage
+
+    def run(self) -> Tuple[Optional[DigitTemplateLibrary], Optional[ReadPlayClock], float]:
+        """Run the template building pass by delegating to the function."""
+        return run_template_building_pass(
+            self.config,
+            self.clock_reader,
+            self.template_builder,
+            self.min_samples,
+            self.max_scan_frames,
+            self.target_coverage,
+        )

src/readers/__init__.py

@@ -0,0 +1,28 @@
+"""Reader modules for extracting values from video frame regions.
+
+This package contains components that read values from detected regions:
+- Play clock digit values (via template matching)
+- Future: expanded timeout value reading
+
+Note: detect_red_digits and normalize_to_grayscale are now in utils.color
+"""
+
+from .models import (
+    PlayClockReading,
+    TemplateMatchResult,
+    TemplatePlayClockReading,
+)
+from .playclock import (
+    ReadPlayClock,
+    backfill_missing_readings,
+)
+
+__all__ = [
+    # Models
+    "PlayClockReading",
+    "TemplateMatchResult",
+    "TemplatePlayClockReading",
+    # Play clock reading
+    "ReadPlayClock",
+    "backfill_missing_readings",
+]

src/readers/models.py

@@ -0,0 +1,38 @@
+"""
+Pydantic models for value reading results.
+
+These models represent the outputs of reading values from detected regions:
+play clock readings, template match results, etc.
+"""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class PlayClockReading(BaseModel):
+    """Result from play clock reading (used by both OCR and template-based methods)."""
+
+    detected: bool = Field(..., description="Whether a valid play clock value was detected")
+    value: Optional[int] = Field(..., description="Play clock value (0-40 seconds), None if unreadable")
+    confidence: float = Field(..., description="Confidence score (0.0 to 1.0)")
+    raw_text: str = Field(..., description="Source identifier for debugging (e.g., 'TEMPLATE_40', 'BACKFILLED_25', 'NO_SCOREBUG')")
+
+
+class TemplateMatchResult(BaseModel):
+    """Result from template matching for a single digit."""
+
+    digit_value: int = Field(..., description="Matched digit value (-1 for blank, 0-9 for digits)")
+    confidence: float = Field(..., description="Match confidence (0.0 to 1.0)")
+    is_valid: bool = Field(..., description="Whether match confidence exceeds threshold")
+
+
+class TemplatePlayClockReading(BaseModel):
+    """Result from template-based play clock reading."""
+
+    detected: bool = Field(..., description="Whether a valid clock value was read")
+    value: Optional[int] = Field(..., description="Clock value (0-40), None if unreadable")
+    confidence: float = Field(..., description="Overall confidence score")
+    tens_match: Optional[TemplateMatchResult] = Field(..., description="Tens digit match result")
+    ones_match: Optional[TemplateMatchResult] = Field(..., description="Ones digit match result")
+    method: str = Field(..., description="'template_single', 'template_double', or 'template'")

src/readers/playclock.py

@@ -0,0 +1,543 @@
+"""
+Play clock reading via template matching.
+
+This module provides:
+- ReadPlayClock: Fast template-based clock value reading
+- backfill_missing_readings for gap interpolation
+
+Color normalization utilities (detect_red_digits, normalize_to_grayscale) are
+now shared from utils.color to eliminate code duplication.
+
+Performance comparison (from ocr_benchmark.md):
+- EasyOCR: 48.9ms/frame
+- Template Matching: 0.3ms/frame (163x faster)
+"""
+
+import logging
+from typing import Any, List, Tuple
+
+import cv2
+import numpy as np
+
+from setup import DigitTemplate, DigitTemplateLibrary
+from utils import extract_center_region, extract_far_left_region, extract_left_region, extract_right_region, preprocess_playclock_region
+from .models import PlayClockReading, TemplateMatchResult, TemplatePlayClockReading
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Template-Based Play Clock Reader
+# =============================================================================
+
+
+class ReadPlayClock:
+    """
+    Reads play clock values using template matching with dual-mode detection.
+
+    Uses digit templates built from OCR-labeled samples to achieve
+    lightning-fast digit recognition (~0.3ms/frame vs ~49ms for OCR).
+
+    Implements dual-mode matching to handle both display layouts:
+    - Single-digit (0-9): Digit is CENTER-aligned
+    - Double-digit (10-40): Tens on LEFT, ones on RIGHT
+
+    The reader tries both interpretations and picks the best match.
+
+    Handles slight translational shifts via template matching search window.
+    """
+
+    # Confidence thresholds
+    MIN_DIGIT_CONFIDENCE = 0.6  # Minimum confidence to accept a digit match
+    MIN_CLOCK_CONFIDENCE = 0.5  # Minimum overall confidence to return a reading
+
+    def __init__(self, template_library: DigitTemplateLibrary, region_width: int = 50, region_height: int = 28):
+        """
+        Initialize the template-based clock reader.
+
+        Args:
+            template_library: Pre-built digit template library
+            region_width: Play clock region width
+            region_height: Play clock region height
+        """
+        self.library = template_library
+        self.region_width = region_width
+        self.region_height = region_height
+        self.scale_factor = 4  # Must match the scale used in template building
+
+        logger.info("ReadPlayClock initialized")
+
+    def preprocess_region(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
+        """
+        Preprocess play clock region for template matching.
+
+        Delegates to shared utility function in utils.regions.
+
+        Args:
+            region: Play clock region (BGR format)
+
+        Returns:
+            Preprocessed binary image (scaled up)
+        """
+        return preprocess_playclock_region(region, self.scale_factor)
+
+    def match_digit(self, region: np.ndarray[Any, Any], templates: List[DigitTemplate]) -> TemplateMatchResult:
+        """
+        Match a region against a set of digit templates.
+
+        Uses template matching with a small search window for robustness
+        to slight translational shifts.
+
+        Args:
+            region: Preprocessed digit region
+            templates: List of templates to match against
+
+        Returns:
+            TemplateMatchResult with best match
+        """
+        if not templates:
+            return TemplateMatchResult(digit_value=-1, confidence=0.0, is_valid=False)
+
+        best_digit = -1
+        best_confidence = -1.0
+
+        for template in templates:
+            tmpl = template.template
+
+            # Ensure template fits within region (with search window)
+            if tmpl.shape[0] > region.shape[0] or tmpl.shape[1] > region.shape[1]:
+                # Resize template to fit
+                scale = min(region.shape[0] / tmpl.shape[0], region.shape[1] / tmpl.shape[1]) * 0.9
+                new_h = int(tmpl.shape[0] * scale)
+                new_w = int(tmpl.shape[1] * scale)
+                tmpl = cv2.resize(tmpl, (new_w, new_h))
+
+            # Template matching with search window
+            result = cv2.matchTemplate(region, tmpl, cv2.TM_CCOEFF_NORMED)
+            _, max_val, _, _ = cv2.minMaxLoc(result)
+
+            if max_val > best_confidence:
+                best_confidence = max_val
+                best_digit = template.digit_value
+
+        is_valid = best_confidence >= self.MIN_DIGIT_CONFIDENCE
+
+        return TemplateMatchResult(digit_value=best_digit, confidence=best_confidence, is_valid=is_valid)
+
+    def _try_double_digit(self, preprocessed: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
+        """
+        Try to read as double-digit display (10-40): tens on left, ones on right.
+
+        Args:
+            preprocessed: Preprocessed play clock region
+
+        Returns:
+            TemplatePlayClockReading with result of double-digit interpretation
+        """
+        # Get templates for double-digit positions
+        # Filter out blank (-1) since it was built from far-left region (different size)
+        tens_templates = [t for t in self.library.get_all_templates(is_tens=True, position="left") if t.digit_value != -1]
+        ones_templates = self.library.get_all_templates(is_tens=False, position="right")
+
+        if not ones_templates or not tens_templates:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=None,
+                ones_match=None,
+                method="template_double",
+            )
+
+        # Extract regions using shared utility functions
+        tens_region = extract_left_region(preprocessed)
+        ones_region = extract_right_region(preprocessed)
+
+        # Match digits
+        tens_match = self.match_digit(tens_region, tens_templates)
+        ones_match = self.match_digit(ones_region, ones_templates)
+
+        # Require valid ones match and tens match
+        if not ones_match.is_valid or not tens_match.is_valid:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=min(tens_match.confidence, ones_match.confidence),
+                tens_match=tens_match,
+                ones_match=ones_match,
+                method="template_double",
+            )
+
+        # Calculate clock value
+        clock_value = tens_match.digit_value * 10 + ones_match.digit_value
+
+        # Validate range (10-40)
+        if clock_value < 10 or clock_value > 40:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=tens_match,
+                ones_match=ones_match,
+                method="template_double",
+            )
+
+        overall_confidence = (tens_match.confidence + ones_match.confidence) / 2
+        detected = overall_confidence >= self.MIN_CLOCK_CONFIDENCE
+
+        return TemplatePlayClockReading(
+            detected=detected,
+            value=clock_value if detected else None,
+            confidence=overall_confidence,
+            tens_match=tens_match,
+            ones_match=ones_match,
+            method="template_double",
+        )
+
+    def _try_single_digit(self, preprocessed: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
+        """
+        Try to read as single-digit display (0-9): digit is centered.
+
+        Args:
+            preprocessed: Preprocessed play clock region
+
+        Returns:
+            TemplatePlayClockReading with result of single-digit interpretation
+        """
+        # Get templates for single-digit (centered) position
+        ones_templates = self.library.get_all_templates(is_tens=False, position="center")
+        blank_templates = [t for t in self.library.get_all_templates(is_tens=True, position="left") if t.digit_value == -1]
+
+        if not ones_templates:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=None,
+                ones_match=None,
+                method="template_single",
+            )
+
+        # Extract regions using shared utility functions
+        center_region = extract_center_region(preprocessed)
+        far_left_region = extract_far_left_region(preprocessed)
+
+        # Match center digit (ones)
+        ones_match = self.match_digit(center_region, ones_templates)
+
+        # Optionally check that far-left region looks blank
+        blank_match = None
+        if blank_templates:
+            blank_match = self.match_digit(far_left_region, blank_templates)
+
+        # Require valid ones match
+        if not ones_match.is_valid:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=ones_match.confidence,
+                tens_match=blank_match,
+                ones_match=ones_match,
+                method="template_single",
+            )
+
+        # Clock value is just the ones digit (0-9)
+        clock_value = ones_match.digit_value
+
+        # Validate range (0-9)
+        if clock_value < 0 or clock_value > 9:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=blank_match,
+                ones_match=ones_match,
+                method="template_single",
+            )
+
+        # Use only ones confidence for single-digit
+        overall_confidence = ones_match.confidence
+        detected = overall_confidence >= self.MIN_CLOCK_CONFIDENCE
+
+        return TemplatePlayClockReading(
+            detected=detected,
+            value=clock_value if detected else None,
+            confidence=overall_confidence,
+            tens_match=blank_match,
+            ones_match=ones_match,
+            method="template_single",
+        )
+
+    def read(self, region: np.ndarray[Any, Any]) -> TemplatePlayClockReading:
+        """
+        Read the play clock value from a region using dual-mode template matching.
+
+        Tries both single-digit (centered) and double-digit (left/right) interpretations
+        and returns the result with higher confidence.
+
+        Args:
+            region: Play clock region (BGR format, original size ~50x28)
+
+        Returns:
+            TemplatePlayClockReading with detected value or error state
+        """
+        # Preprocess the region (handles red-to-white conversion)
+        preprocessed = self.preprocess_region(region)
+
+        # Try both interpretations
+        double_result = self._try_double_digit(preprocessed)
+        single_result = self._try_single_digit(preprocessed)
+
+        # Pick the best result
+        # Priority: detected result with higher confidence
+        if single_result.detected and double_result.detected:
+            # Both detected - pick higher confidence
+            if single_result.confidence > double_result.confidence:
+                return single_result
+            return double_result
+        if single_result.detected:
+            return single_result
+        if double_result.detected:
+            return double_result
+        # Neither detected - return the one with higher confidence for debugging
+        if single_result.confidence > double_result.confidence:
+            return single_result
+        return double_result
+
+    def read_from_frame(
+        self,
+        frame: np.ndarray[Any, Any],
+        scorebug_bbox: Tuple[int, int, int, int],
+        clock_region_offset: Tuple[int, int, int, int],
+    ) -> TemplatePlayClockReading:
+        """
+        Read play clock from a full frame.
+
+        Args:
+            frame: Full video frame (BGR)
+            scorebug_bbox: Scorebug bounding box (x, y, w, h)
+            clock_region_offset: Play clock region offset from scorebug (x_off, y_off, w, h)
+
+        Returns:
+            TemplatePlayClockReading with detected value
+        """
+        sb_x, sb_y, _, _ = scorebug_bbox
+        pc_x_off, pc_y_off, pc_w, pc_h = clock_region_offset
+
+        # Calculate absolute coordinates
+        pc_x = sb_x + pc_x_off
+        pc_y = sb_y + pc_y_off
+
+        # Validate bounds
+        frame_h, frame_w = frame.shape[:2]
+        if pc_x < 0 or pc_y < 0 or pc_x + pc_w > frame_w or pc_y + pc_h > frame_h:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=None,
+                ones_match=None,
+                method="template",
+            )
+
+        # Extract region
+        region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
+
+        return self.read(region)
+
+    def read_from_fixed_location(
+        self,
+        frame: np.ndarray[Any, Any],
+        absolute_coords: Tuple[int, int, int, int],
+    ) -> TemplatePlayClockReading:
+        """
+        Read play clock from a fixed absolute location in the frame.
+
+        This bypasses scorebug detection entirely - useful when templates
+        are built and we know exactly where the play clock should be.
+
+        Args:
+            frame: Full video frame (BGR)
+            absolute_coords: Absolute play clock location (x, y, w, h)
+
+        Returns:
+            TemplatePlayClockReading with detected value
+        """
+        x, y, w, h = absolute_coords
+
+        # Validate bounds
+        frame_h, frame_w = frame.shape[:2]
+        if x < 0 or y < 0 or x + w > frame_w or y + h > frame_h:
+            return TemplatePlayClockReading(
+                detected=False,
+                value=None,
+                confidence=0.0,
+                tens_match=None,
+                ones_match=None,
+                method="template",
+            )
+
+        # Extract region
+        region = frame[y : y + h, x : x + w].copy()
+
+        return self.read(region)
+
+
+# =============================================================================
+# Gap Interpolation
+# =============================================================================
+
+
+def _find_gap_extent(readings: List[PlayClockReading], start_idx: int) -> int:
+    """Find the end index of a gap starting at start_idx."""
+    gap_end = start_idx
+    while gap_end < len(readings) and (not readings[gap_end].detected or readings[gap_end].value is None):
+        gap_end += 1
+    return gap_end
+
+
+def _validate_gap_boundaries(readings: List[PlayClockReading], gap_start: int, gap_end: int, max_gap_seconds: int) -> Tuple[bool, int, int, int]:
+    """
+    Validate that a gap can be backfilled.
+
+    Returns:
+        Tuple of (is_valid, left_value, right_value, seconds_gap).
+        is_valid is False if gap cannot be backfilled.
+    """
+    # Check if we have valid readings on both sides
+    if gap_start == 0:
+        logger.debug("Gap at start of sequence (index 0), no left side for backfill")
+        return False, 0, 0, 0
+
+    if gap_end >= len(readings):
+        logger.debug("Gap at end of sequence (index %d), no right side for backfill", gap_start)
+        return False, 0, 0, 0
+
+    # Get the clock values on either side
+    left_value = readings[gap_start - 1].value
+    right_value = readings[gap_end].value
+
+    if left_value is None or right_value is None:
+        logger.debug("Adjacent values are None, cannot backfill")
+        return False, 0, 0, 0
+
+    # Left should be higher than right in a countdown
+    if left_value <= right_value:
+        logger.debug("Invalid countdown: left=%d not greater than right=%d", left_value, right_value)
+        return False, 0, 0, 0
+
+    seconds_gap = left_value - right_value - 1
+
+    # Check if gap in seconds is within our limit
+    if seconds_gap > max_gap_seconds:
+        logger.debug(
+            "Gap of %d seconds (left=%d, right=%d) exceeds max_gap_seconds=%d, skipping backfill",
+            seconds_gap,
+            left_value,
+            right_value,
+            max_gap_seconds,
+        )
+        return False, 0, 0, 0
+
+    return True, left_value, right_value, seconds_gap
+
+
+def _backfill_interpolate(result: List[PlayClockReading], gap_start: int, gap_frame_count: int, left_value: int, right_value: int) -> None:
+    """Backfill a gap using nearest value interpolation (no missing clock values)."""
+    logger.debug("No missing clock values between %d and %d, using nearest value interpolation", left_value, right_value)
+    for j in range(gap_frame_count):
+        # Use left value for first half, right value for second half
+        backfill_value = left_value if j < gap_frame_count / 2 else right_value
+        result[gap_start + j] = PlayClockReading(
+            detected=True,
+            value=backfill_value,
+            confidence=0.0,
+            raw_text=f"BACKFILLED_{backfill_value}",
+        )
+
+
+def _backfill_with_missing_values(result: List[PlayClockReading], gap_start: int, gap_end: int, left_value: int, right_value: int) -> None:
+    """Backfill a gap by distributing missing clock values across frames."""
+    gap_frame_count = gap_end - gap_start
+    missing_values = list(range(left_value - 1, right_value, -1))
+
+    logger.info(
+        "Backfilling gap: frames %d-%d, clock values %d to %d, missing values: %s",
+        gap_start,
+        gap_end - 1,
+        left_value,
+        right_value,
+        missing_values,
+    )
+
+    for j in range(gap_frame_count):
+        # Calculate which missing value this frame should have
+        position = j / gap_frame_count
+        value_index = min(int(position * len(missing_values)), len(missing_values) - 1)
+        backfill_value = missing_values[value_index]
+
+        result[gap_start + j] = PlayClockReading(
+            detected=True,
+            value=backfill_value,
+            confidence=0.0,
+            raw_text=f"BACKFILLED_{backfill_value}",
+        )
+        logger.debug("  Backfilled index %d with value %d", gap_start + j, backfill_value)
+
+
+def backfill_missing_readings(readings: List[PlayClockReading], max_gap_seconds: int = 3) -> List[PlayClockReading]:
+    """
+    Backfill missing play clock readings when there's a clear countdown sequence with gaps.
+
+    This function fills in missing readings when:
+    1. The gap in clock VALUES is 1-3 seconds (configurable via max_gap_seconds)
+    2. There's at least one valid reading on EACH side of the gap
+    3. The readings form a valid countdown sequence
+
+    Since the video may be sampled at higher than 1fps, each clock value may appear
+    multiple times. This function looks at the actual clock values, not frame indices.
+
+    Examples (showing clock values, with ? for undetected):
+        - [6, 6, 5, 5, ?, ?, 3, 3] → missing value is 4, backfill the gaps
+        - [10, 9, ?, ?, ?] → no backfill (no right side continuation)
+        - [6, 6, ?, ?, ?, ?, ?, 0, 0] → no backfill if gap > max_gap_seconds
+
+    Args:
+        readings: List of PlayClockReading objects (in chronological order)
+        max_gap_seconds: Maximum number of missing SECONDS to backfill (default: 3)
+
+    Returns:
+        New list with backfilled readings (original list is not modified)
+    """
+    if not readings:
+        return readings
+
+    result = list(readings)
+    i = 0
+
+    while i < len(result):
+        # Skip if this reading is valid
+        if result[i].detected and result[i].value is not None:
+            i += 1
+            continue
+
+        # Found a missing reading - find the extent of the gap
+        gap_start = i
+        gap_end = _find_gap_extent(result, i)
+        gap_frame_count = gap_end - gap_start
+
+        # Validate that we can backfill this gap
+        is_valid, left_value, right_value, seconds_gap = _validate_gap_boundaries(result, gap_start, gap_end, max_gap_seconds)
+        if not is_valid:
+            i = gap_end
+            continue
+
+        # Perform the backfill
+        if seconds_gap <= 0:
+            _backfill_interpolate(result, gap_start, gap_frame_count, left_value, right_value)
+        else:
+            _backfill_with_missing_values(result, gap_start, gap_end, left_value, right_value)
+
+        i = gap_end
+
+    return result

src/setup/__init__.py

@@ -0,0 +1,25 @@
+"""Setup modules for one-time preparation before video processing.
+
+This package contains components for:
+- Building digit templates from OCR-labeled samples
+- Extracting and preprocessing play clock regions for OCR
+
+Templates are built once during an initial collection phase, then used for fast
+digit recognition during video processing.
+"""
+
+from .models import DigitSample, DigitTemplate, PlayClockRegionConfig
+from .template_library import DigitTemplateLibrary
+from .template_builder import DigitTemplateBuilder
+from .playclock_region import PlayClockRegionExtractor
+
+__all__ = [
+    # Models
+    "DigitSample",
+    "DigitTemplate",
+    "PlayClockRegionConfig",
+    # Classes
+    "DigitTemplateLibrary",
+    "DigitTemplateBuilder",
+    "PlayClockRegionExtractor",
+]

src/setup/coverage.py

@@ -0,0 +1,84 @@
+"""
+Shared coverage calculation utilities for digit templates.
+
+This module provides utilities for calculating template coverage status,
+shared between DigitTemplateBuilder and DigitTemplateLibrary.
+"""
+
+from typing import Any, Dict, Iterable, Set, Tuple
+
+
+# Standard digit sets for play clock displays
+ONES_DIGITS = set(range(10))  # 0-9
+TENS_DIGITS = {1, 2, 3, 4}  # 10, 20, 30, 40
+
+
+def categorize_template_keys(keys: Iterable[Tuple[bool, int, str]]) -> Tuple[Set[int], Set[int], Set[int], bool]:
+    """
+    Categorize template keys into digit sets.
+
+    Args:
+        keys: Iterable of (is_tens, digit, position) tuples
+
+    Returns:
+        Tuple of (ones_center_have, ones_right_have, tens_have, has_blank)
+    """
+    ones_center_have: Set[int] = set()
+    ones_right_have: Set[int] = set()
+    tens_have: Set[int] = set()
+    has_blank = False
+
+    for is_tens, digit, position in keys:
+        if is_tens:
+            if digit == -1:
+                has_blank = True
+            else:
+                tens_have.add(digit)
+        else:
+            if position == "center":
+                ones_center_have.add(digit)
+            elif position == "right":
+                ones_right_have.add(digit)
+
+    return ones_center_have, ones_right_have, tens_have, has_blank
+
+
+def calculate_coverage_status(
+    ones_center_have: Set[int],
+    ones_right_have: Set[int],
+    tens_have: Set[int],
+    has_blank: bool,
+    total_items: int = 0,
+) -> Dict[str, Any]:
+    """
+    Calculate coverage status from digit sets.
+
+    Args:
+        ones_center_have: Set of ones digits that have center templates
+        ones_right_have: Set of ones digits that have right templates
+        tens_have: Set of tens digits that have templates
+        has_blank: Whether blank template exists
+        total_items: Total number of items (templates or samples)
+
+    Returns:
+        Dictionary with coverage information
+    """
+    ones_center_missing = ONES_DIGITS - ones_center_have
+    ones_right_missing = ONES_DIGITS - ones_right_have
+    tens_missing = TENS_DIGITS - tens_have
+
+    # Total needed: 10 ones_center + 10 ones_right + 4 tens + 1 blank = 25
+    total_needed = 25
+
+    return {
+        "total_needed": total_needed,
+        "total_have": total_items,
+        "is_complete": total_items >= total_needed,
+        "ones_center_have": sorted(ones_center_have),
+        "ones_center_missing": sorted(ones_center_missing),
+        "ones_right_have": sorted(ones_right_have),
+        "ones_right_missing": sorted(ones_right_missing),
+        "tens_have": sorted(tens_have),
+        "tens_missing": sorted(tens_missing),
+        "has_blank": has_blank,
+    }

src/setup/models.py

@@ -0,0 +1,51 @@
+"""
+Pydantic models for the setup/template building phase.
+
+These models are used during the initial template collection phase where
+OCR-labeled samples are collected and averaged into digit templates.
+Also includes region configuration models for setup.
+"""
+
+from typing import Any
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DigitSample(BaseModel):
+    """A single digit sample extracted from a play clock region."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    digit_value: int = Field(..., description="0-9 for ones digit, 0-4 for tens digit, -1 for blank")
+    is_tens_digit: bool = Field(..., description="True if this is the tens place digit")
+    position: str = Field(..., description="'left', 'center', or 'right' - where digit appears in region")
+    image: np.ndarray[Any, Any] = Field(..., description="The digit image (grayscale, preprocessed)")
+    source_clock_value: int = Field(..., description="The full clock value this was extracted from")
+    timestamp: float = Field(..., description="Video timestamp where this was captured")
+    confidence: float = Field(..., description="OCR confidence for this sample")
+
+
+class DigitTemplate(BaseModel):
+    """A template for matching a specific digit."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    digit_value: int = Field(..., description="0-9 for ones, 0-4 for tens, -1 for blank")
+    is_tens_digit: bool = Field(..., description="True if this is a tens place template")
+    position: str = Field(..., description="'left', 'center', or 'right' - where digit appears in region")
+    template: np.ndarray[Any, Any] = Field(..., description="The template image (grayscale)")
+    sample_count: int = Field(..., description="Number of samples used to build this template")
+    avg_confidence: float = Field(..., description="Average OCR confidence of source samples")
+
+
+class PlayClockRegionConfig(BaseModel):
+    """Configuration for the play clock region relative to the scorebug bounding box."""
+
+    x_offset: int = Field(..., description="X offset from scorebug left edge")
+    y_offset: int = Field(..., description="Y offset from scorebug top edge")
+    width: int = Field(..., description="Width of play clock region")
+    height: int = Field(..., description="Height of play clock region")
+    source_video: str = Field(..., description="Video used to identify region")
+    scorebug_template: str = Field(..., description="Template used for scorebug detection")
+    samples_used: int = Field(..., description="Number of frames used to verify region")

src/{detectors/play_clock_reader.py → setup/playclock_region.py}

@@ -1,43 +1,49 @@
 """
-Play clock reader module for region extraction and preprocessing.
+Play clock region extraction and OCR preprocessing for template building.
 
-This module provides functionality to extract and preprocess the play clock region
-from video frames. The actual digit recognition is performed by the template
-matching system (see digit_template_reader.py).
+This module provides:
+- PlayClockRegionExtractor: Extracts and preprocesses play clock regions
+- OCR preprocessing for initial digit labeling during template building
 
-Note: OCR-based clock reading has been removed in favor of template matching.
-See docs/ocr_to_template_migration.md for details.
+The region extraction logic determines WHERE to look in the frame,
+while the OCR preprocessing prepares images for EasyOCR labeling.
+
+Color detection utilities are shared from utils.color to eliminate code duplication.
 """
 
 import json
 import logging
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Any, Optional, Tuple
 
 import cv2
 import numpy as np
 
-from detectors.digit_template_reader import detect_red_digits as _detect_red_shared
-from .models import PlayClockReading, PlayClockRegionConfig
+from utils import detect_red_digits
+from .models import PlayClockRegionConfig
 
 logger = logging.getLogger(__name__)
 
 
-class PlayClockReader:
+# =============================================================================
+# Play Clock Region Extractor
+# =============================================================================
+
+
+class PlayClockRegionExtractor:
     """
     Extracts and preprocesses play clock regions from video frames.
 
-    The reader extracts a sub-region from the scorebug where the play clock
-    is displayed and preprocesses the image for template matching or
-    template building (via OCR labeling).
+    The extractor locates the play clock sub-region within the scorebug
+    and preprocesses it for OCR during template building. This class
+    handles the geometry of WHERE to look in the frame.
 
-    Note: This class no longer performs OCR - see TemplatePlayClockReader
-    in digit_template_reader.py for the actual clock value reading.
+    Note: For reading actual clock values, use ReadPlayClock from readers.playclock.
     """
 
     def __init__(self, region_config_path: Optional[str] = None, region_config: Optional[PlayClockRegionConfig] = None):
         """
-        Initialize the play clock reader.
+        Initialize the play clock region extractor.
 
         Args:
             region_config_path: Path to JSON config file with play clock region coordinates
@@ -47,11 +53,11 @@ class PlayClockReader:
 
         if region_config:
             self.config = region_config
-            logger.info("PlayClockReader initialized with direct config")
+            logger.info("PlayClockRegionExtractor initialized with direct config")
         elif region_config_path:
             self.load_config(region_config_path)
         else:
-            logger.warning("PlayClockReader initialized without region config - call load_config() before use")
+            logger.warning("PlayClockRegionExtractor initialized without region config - call load_config() before use")
 
     def load_config(self, config_path: str) -> None:
         """
@@ -84,7 +90,7 @@ class PlayClockReader:
             self.config.height,
         )
 
-    def _extract_region(self, frame: np.ndarray, scorebug_bbox: Tuple[int, int, int, int]) -> Optional[np.ndarray]:
+    def extract_region(self, frame: np.ndarray[Any, Any], scorebug_bbox: Tuple[int, int, int, int]) -> Optional[np.ndarray[Any, Any]]:
         """
         Extract the play clock region from the frame.
 
@@ -125,21 +131,7 @@ class PlayClockReader:
         region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
         return region
 
-    def _detect_red_digits(self, region: np.ndarray) -> bool:
-        """
-        Detect if the play clock digits are red (displayed when clock is at 5 seconds or less).
-
-        Delegates to shared detect_red_digits function from digit_template_reader.
-
-        Args:
-            region: Play clock region (BGR format)
-
-        Returns:
-            True if red digits detected, False otherwise
-        """
-        return _detect_red_shared(region)
-
-    def _preprocess_for_ocr(self, region: np.ndarray) -> np.ndarray:
+    def preprocess_for_ocr(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
         """
         Preprocess the play clock region for OCR (used during template building).
 
@@ -158,7 +150,7 @@ class PlayClockReader:
             Preprocessed image ready for OCR
         """
         # Check if digits are red (play clock at 5 seconds or less)
-        is_red = self._detect_red_digits(region)
+        is_red = detect_red_digits(region)
 
         if is_red:
             # For red digits, use the red channel directly
@@ -175,7 +167,7 @@ class PlayClockReader:
 
         if is_red:
             # For red digits, use percentile-based threshold on the red channel
-            threshold_value = np.percentile(scaled, 90)
+            threshold_value = float(np.percentile(np.asarray(scaled), 90))
             _, binary = cv2.threshold(scaled, threshold_value, 255, cv2.THRESH_BINARY)
             logger.debug("Red digit threshold (90th percentile): %.1f", threshold_value)
 
@@ -190,7 +182,7 @@ class PlayClockReader:
             _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
 
             # Determine if we need to invert
-            mean_intensity = np.mean(binary)
+            mean_intensity = np.mean(np.asarray(binary))
             if mean_intensity < 128:
                 binary = cv2.bitwise_not(binary)
 
@@ -205,142 +197,23 @@ class PlayClockReader:
 
         return binary
 
+    def get_absolute_coords(self, scorebug_bbox: Tuple[int, int, int, int]) -> Optional[Tuple[int, int, int, int]]:
+        """
+        Get absolute coordinates of the play clock region given scorebug position.
 
-# pylint: disable=too-many-branches,too-many-statements
-def backfill_missing_readings(readings: list[PlayClockReading], max_gap_seconds: int = 3) -> list[PlayClockReading]:
-    """
-    Backfill missing play clock readings when there's a clear countdown sequence with gaps.
-
-    This function fills in missing readings when:
-    1. The gap in clock VALUES is 1-3 seconds (configurable via max_gap_seconds)
-    2. There's at least one valid reading on EACH side of the gap
-    3. The readings form a valid countdown sequence
-
-    Since the video may be sampled at higher than 1fps, each clock value may appear
-    multiple times. This function looks at the actual clock values, not frame indices.
-
-    Examples (showing clock values, with ? for undetected):
-        - [6, 6, 5, 5, ?, ?, 3, 3] → missing value is 4, backfill the gaps
-        - [10, 9, ?, ?, ?] → no backfill (no right side continuation)
-        - [6, 6, ?, ?, ?, ?, ?, 0, 0] → no backfill if gap > max_gap_seconds
-
-    Args:
-        readings: List of PlayClockReading objects (in chronological order)
-        max_gap_seconds: Maximum number of missing SECONDS to backfill (default: 3)
+        Args:
+            scorebug_bbox: Scorebug bounding box (x, y, w, h)
 
-    Returns:
-        New list with backfilled readings (original list is not modified)
-    """
-    if not readings:
-        return readings
-
-    # Create a copy to avoid modifying the original
-    result = list(readings)
-
-    # Find gaps and try to backfill
-    i = 0
-    while i < len(result):
-        # Skip if this reading is valid
-        if result[i].detected and result[i].value is not None:
-            i += 1
-            continue
-
-        # Found a missing reading - find the extent of the gap (in frames)
-        gap_start = i
-        gap_end = i
-        while gap_end < len(result) and (not result[gap_end].detected or result[gap_end].value is None):
-            gap_end += 1
-
-        gap_frame_count = gap_end - gap_start
-
-        # Check if we have valid readings on both sides
-        if gap_start == 0:
-            logger.debug("Gap at start of sequence (index 0), no left side for backfill")
-            i = gap_end
-            continue
-
-        if gap_end >= len(result):
-            logger.debug("Gap at end of sequence (index %d), no right side for backfill", gap_start)
-            i = gap_end
-            continue
-
-        # Get the clock values on either side
-        left_value = result[gap_start - 1].value
-        right_value = result[gap_end].value
-
-        if left_value is None or right_value is None:
-            logger.debug("Adjacent values are None, cannot backfill")
-            i = gap_end
-            continue
-
-        # Calculate the gap in seconds (clock values)
-        # Left should be higher than right in a countdown
-        if left_value <= right_value:
-            logger.debug("Invalid countdown: left=%d not greater than right=%d", left_value, right_value)
-            i = gap_end
-            continue
-
-        seconds_gap = left_value - right_value - 1  # Number of missing clock values
-
-        # Check if gap in seconds is within our limit
-        if seconds_gap > max_gap_seconds:
-            logger.debug(
-                "Gap of %d seconds (left=%d, right=%d) exceeds max_gap_seconds=%d, skipping backfill",
-                seconds_gap,
-                left_value,
-                right_value,
-                max_gap_seconds,
-            )
-            i = gap_end
-            continue
-
-        if seconds_gap <= 0:
-            # No missing values (e.g., left=5, right=4 means we just missed some frames of 5 or 4)
-            # Still backfill with a reasonable value (closer to left or right based on position)
-            logger.debug("No missing clock values between %d and %d, using nearest value interpolation", left_value, right_value)
-            for j in range(gap_frame_count):
-                # Use left value for first half, right value for second half
-                if j < gap_frame_count / 2:
-                    backfill_value = left_value
-                else:
-                    backfill_value = right_value
-                result[gap_start + j] = PlayClockReading(
-                    detected=True,
-                    value=backfill_value,
-                    confidence=0.0,
-                    raw_text=f"BACKFILLED_{backfill_value}",
-                )
-            i = gap_end
-            continue
-
-        # Calculate the missing clock values
-        missing_values = list(range(left_value - 1, right_value, -1))
+        Returns:
+            Play clock absolute coordinates (x, y, w, h) or None if no config
+        """
+        if self.config is None:
+            return None
 
-        logger.info(
-            "Backfilling gap: frames %d-%d, clock values %d to %d, missing values: %s",
-            gap_start,
-            gap_end - 1,
-            left_value,
-            right_value,
-            missing_values,
+        sb_x, sb_y, _, _ = scorebug_bbox
+        return (
+            sb_x + self.config.x_offset,
+            sb_y + self.config.y_offset,
+            self.config.width,
+            self.config.height,
         )
-
-        # Distribute missing values across the gap frames
-        for j in range(gap_frame_count):
-            # Calculate which missing value this frame should have
-            position = j / gap_frame_count
-            value_index = int(position * len(missing_values))
-            value_index = min(value_index, len(missing_values) - 1)
-            backfill_value = missing_values[value_index]
-
-            result[gap_start + j] = PlayClockReading(
-                detected=True,
-                value=backfill_value,
-                confidence=0.0,
-                raw_text=f"BACKFILLED_{backfill_value}",
-            )
-            logger.debug("  Backfilled index %d with value %d", gap_start + j, backfill_value)
-
-        i = gap_end
-
-    return result

src/setup/template_builder.py

@@ -0,0 +1,340 @@
+"""
+Digit template builder for creating play clock digit templates from OCR samples.
+
+This module provides the DigitTemplateBuilder class which collects samples from
+the play clock region, extracts individual digits, and builds averaged templates
+for each unique digit value.
+
+Region extraction and preprocessing utilities are shared from utils to eliminate code duplication.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+import cv2
+import numpy as np
+
+from utils import (
+    extract_center_region,
+    extract_far_left_region,
+    extract_left_region,
+    extract_right_region,
+    preprocess_playclock_region,
+)
+from .coverage import ONES_DIGITS, categorize_template_keys
+from .models import DigitSample, DigitTemplate
+from .template_library import DigitTemplateLibrary
+
+logger = logging.getLogger(__name__)
+
+
+class DigitTemplateBuilder:
+    """
+    Builds digit templates from OCR-labeled play clock samples.
+
+    Collects samples from the play clock region, extracts individual digits,
+    and builds averaged templates for each unique digit value.
+
+    Uses color normalization so red and white digits produce the same template.
+    """
+
+    # Play clock region dimensions (from config)
+    DEFAULT_REGION_WIDTH = 50
+    DEFAULT_REGION_HEIGHT = 28
+
+    def __init__(self, region_width: int = DEFAULT_REGION_WIDTH, region_height: int = DEFAULT_REGION_HEIGHT):
+        """
+        Initialize the template builder.
+
+        Args:
+            region_width: Width of play clock region in pixels
+            region_height: Height of play clock region in pixels
+        """
+        self.region_width = region_width
+        self.region_height = region_height
+
+        # Collected samples: {(is_tens, digit_value, position): [DigitSample, ...]}
+        self.samples: Dict[Tuple[bool, int, str], List[DigitSample]] = {}
+
+        # Track raw clock region images for potential reprocessing
+        self.raw_regions: List[Tuple[float, int, np.ndarray[Any, Any]]] = []  # (timestamp, clock_value, region)
+
+        logger.info("DigitTemplateBuilder initialized (region: %dx%d)", region_width, region_height)
+
+    def preprocess_region(self, region: np.ndarray[Any, Any]) -> np.ndarray[Any, Any]:
+        """
+        Preprocess play clock region for template extraction.
+
+        Delegates to shared utility function in utils.regions.
+
+        Args:
+            region: Play clock region (BGR format)
+
+        Returns:
+            Preprocessed binary image (white digits on black background)
+        """
+        return preprocess_playclock_region(region, scale_factor=4)
+
+    def extract_digits(
+        self, preprocessed: np.ndarray[Any, Any], clock_value: int
+    ) -> Tuple[Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]], Optional[np.ndarray[Any, Any]]]:
+        """
+        Extract individual digit images from preprocessed play clock region.
+
+        For double-digit values (10-40): extracts left (tens) and right (ones)
+        For single-digit values (0-9): extracts far-left (blank) and center (ones)
+
+        Args:
+            preprocessed: Preprocessed play clock image (scaled 4x)
+            clock_value: The known clock value (0-40)
+
+        Returns:
+            Tuple of (tens_digit_image, ones_right_image, ones_center_image, blank_image)
+            - For double-digit: tens=left, ones_right=right, ones_center=None, blank=None
+            - For single-digit: tens=None, ones_right=None, ones_center=center, blank=far_left
+        """
+        if clock_value >= 10:
+            # Double-digit: standard left/right split
+            return extract_left_region(preprocessed), extract_right_region(preprocessed), None, None
+        # Single-digit: far-left is blank (truly empty), ones is centered
+        return None, None, extract_center_region(preprocessed), extract_far_left_region(preprocessed)
+
+    def add_sample(self, region: np.ndarray[Any, Any], clock_value: int, timestamp: float, confidence: float = 1.0) -> None:
+        """
+        Add a play clock sample for template building.
+
+        Routes samples based on display layout:
+        - Single-digit (0-9): Digit is CENTER-aligned, tens position is blank
+        - Double-digit (10-40): Tens on LEFT, ones on RIGHT
+
+        Args:
+            region: Play clock region (BGR format, original size)
+            clock_value: OCR-determined clock value (0-40)
+            timestamp: Video timestamp
+            confidence: OCR confidence score
+        """
+        if clock_value < 0 or clock_value > 40:
+            logger.warning("Invalid clock value %d, skipping sample", clock_value)
+            return
+
+        # Store raw region for potential reprocessing
+        self.raw_regions.append((timestamp, clock_value, region.copy()))
+
+        # Preprocess (handles red-to-white conversion automatically)
+        preprocessed = self.preprocess_region(region)
+
+        # Extract digits based on single vs double digit display
+        tens_img, ones_right_img, ones_center_img, blank_img = self.extract_digits(preprocessed, clock_value)
+
+        # Determine digit values
+        ones_digit = clock_value % 10
+        tens_digit = clock_value // 10 if clock_value >= 10 else -1  # -1 = blank
+
+        if clock_value >= 10:
+            # Double-digit display (10-40): tens on left, ones on right
+            assert tens_img is not None  # Asserts: validated by extract_digits
+            # Store tens sample (left position)
+            tens_sample = DigitSample(
+                digit_value=tens_digit,
+                is_tens_digit=True,
+                position="left",
+                image=tens_img,
+                source_clock_value=clock_value,
+                timestamp=timestamp,
+                confidence=confidence,
+            )
+            tens_key = (True, tens_digit, "left")
+            if tens_key not in self.samples:
+                self.samples[tens_key] = []
+            self.samples[tens_key].append(tens_sample)
+
+            # Store ones sample (right position)
+            assert ones_right_img is not None  # Asserts: validated by extract_digits
+            ones_sample = DigitSample(
+                digit_value=ones_digit,
+                is_tens_digit=False,
+                position="right",
+                image=ones_right_img,
+                source_clock_value=clock_value,
+                timestamp=timestamp,
+                confidence=confidence,
+            )
+            ones_key = (False, ones_digit, "right")
+            if ones_key not in self.samples:
+                self.samples[ones_key] = []
+            self.samples[ones_key].append(ones_sample)
+
+            logger.debug(
+                "Added double-digit sample: clock=%d, tens=%d (left), ones=%d (right), t=%.1f",
+                clock_value,
+                tens_digit,
+                ones_digit,
+                timestamp,
+            )
+        else:
+            # Single-digit display (0-9): digit is centered, tens position is blank
+            # Store blank sample (far-left position - should be truly empty)
+            assert blank_img is not None  # Asserts: validated by extract_digits
+            blank_sample = DigitSample(
+                digit_value=-1,  # blank
+                is_tens_digit=True,
+                position="left",  # Still use "left" as the position key for compatibility
+                image=blank_img,  # Now using far-left region that's truly empty
+                source_clock_value=clock_value,
+                timestamp=timestamp,
+                confidence=confidence,
+            )
+            blank_key = (True, -1, "left")
+            if blank_key not in self.samples:
+                self.samples[blank_key] = []
+            self.samples[blank_key].append(blank_sample)
+
+            # Store ones sample (center position)
+            assert ones_center_img is not None  # Asserts: validated by extract_digits
+            ones_sample = DigitSample(
+                digit_value=ones_digit,
+                is_tens_digit=False,
+                position="center",
+                image=ones_center_img,
+                source_clock_value=clock_value,
+                timestamp=timestamp,
+                confidence=confidence,
+            )
+            ones_key = (False, ones_digit, "center")
+            if ones_key not in self.samples:
+                self.samples[ones_key] = []
+            self.samples[ones_key].append(ones_sample)
+
+            logger.debug(
+                "Added single-digit sample: clock=%d, ones=%d (center), blank (far-left), t=%.1f",
+                clock_value,
+                ones_digit,
+                timestamp,
+            )
+
+    def get_sample_count(self) -> Dict[str, int]:
+        """Get count of samples collected for each digit and position."""
+        counts = {}
+        for (is_tens, digit, position), samples in self.samples.items():
+            type_str = "tens" if is_tens else "ones"
+            digit_str = "blank" if digit == -1 else str(digit)
+            key = f"{type_str}_{digit_str}_{position}"
+            counts[key] = len(samples)
+        return counts
+
+    def build_templates(self, min_samples: int = 3) -> DigitTemplateLibrary:
+        """
+        Build templates from collected samples.
+
+        For each digit/position combination, averages multiple samples
+        to create a robust template.
+
+        Args:
+            min_samples: Minimum samples required to build a template (default: 3)
+
+        Returns:
+            DigitTemplateLibrary with built templates
+        """
+        library = DigitTemplateLibrary()
+
+        for (is_tens, digit, position), samples in self.samples.items():
+            if len(samples) < min_samples:
+                digit_display = "blank" if digit == -1 else str(digit)
+                logger.warning(
+                    "Insufficient samples for %s digit %s (%s): %d < %d",
+                    "tens" if is_tens else "ones",
+                    digit_display,
+                    position,
+                    len(samples),
+                    min_samples,
+                )
+                continue
+
+            # Resize all samples to match dimensions of first sample
+            target_shape = samples[0].image.shape
+
+            # Average the samples (with resizing if needed)
+            sum_image = np.zeros(target_shape, dtype=np.float32)
+            valid_count = 0
+            total_confidence = 0.0
+
+            for sample in samples:
+                img = sample.image
+                if img.shape != target_shape:
+                    img = cv2.resize(img, (target_shape[1], target_shape[0]))
+                sum_image += img.astype(np.float32)
+                valid_count += 1
+                total_confidence += sample.confidence
+
+            if valid_count > 0:
+                avg_image = (sum_image / valid_count).astype(np.uint8)
+
+                # Threshold the averaged image to clean it up
+                _, template_img = cv2.threshold(avg_image, 127, 255, cv2.THRESH_BINARY)
+
+                template = DigitTemplate(
+                    digit_value=digit,
+                    is_tens_digit=is_tens,
+                    position=position,
+                    template=template_img,
+                    sample_count=valid_count,
+                    avg_confidence=total_confidence / valid_count,
+                )
+
+                library.add_template(template)
+                digit_display = "blank" if digit == -1 else str(digit)
+                logger.info(
+                    "Built template: %s digit %s (%s) from %d samples",
+                    "tens" if is_tens else "ones",
+                    digit_display,
+                    position,
+                    valid_count,
+                )
+
+        # Log coverage status
+        coverage = library.get_coverage_status()
+        logger.info(
+            "Template coverage: %d/%d (%.1f%%)",
+            coverage["total_have"],
+            coverage["total_needed"],
+            100 * coverage["total_have"] / coverage["total_needed"],
+        )
+
+        return library
+
+    def get_coverage_status(self) -> Dict[str, Any]:
+        """Get current sample coverage status."""
+        # Get keys for samples that have at least one entry
+        keys_with_samples = [key for key, samples in self.samples.items() if len(samples) >= 1]
+
+        # Use shared utility to categorize
+        ones_center_have, ones_right_have, tens_have, has_blank = categorize_template_keys(keys_with_samples)
+
+        return {
+            "ones_center": sorted(ones_center_have),
+            "ones_right": sorted(ones_right_have),
+            "tens": sorted(tens_have),
+            "has_blank": has_blank,
+            "ones_center_missing": sorted(ONES_DIGITS - ones_center_have),
+            "ones_right_missing": sorted(ONES_DIGITS - ones_right_have),
+            "tens_missing": sorted({1, 2, 3, 4} - tens_have),
+        }
+
+    def get_coverage_estimate(self) -> float:
+        """
+        Get a simple coverage estimate as a float (0.0-1.0).
+
+        Returns:
+            Coverage estimate where 1.0 = all templates have samples
+        """
+        status = self.get_coverage_status()
+
+        # Count what we have (with at least 1 sample each)
+        total_have = len(status["ones_center"]) + len(status["ones_right"]) + len(status["tens"])
+        if status["has_blank"]:
+            total_have += 1
+
+        # Total needed: 10 ones_center + 10 ones_right + 4 tens + 1 blank = 25
+        total_needed = 25
+
+        return total_have / total_needed

src/setup/template_library.py

@@ -0,0 +1,214 @@
+"""
+Digit template library for storing and managing play clock digit templates.
+
+This module provides the DigitTemplateLibrary class for saving, loading, and
+managing digit templates used for play clock reading.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import cv2
+
+from .coverage import ONES_DIGITS, calculate_coverage_status, categorize_template_keys
+from .models import DigitTemplate
+
+logger = logging.getLogger(__name__)
+
+
+class DigitTemplateLibrary:
+    """
+    Stores and manages digit templates for play clock reading.
+
+    Uses color normalization to handle both red and white digits with a single
+    template set. Now supports position-aware templates to handle both single-digit
+    (centered) and double-digit (left/right split) layouts:
+    - Ones digits (center): 0-9 from single-digit displays (10 templates)
+    - Ones digits (right): 0-9 from double-digit displays (10 templates)
+    - Tens digits (left): 1, 2, 3, 4 from double-digit displays (4 templates)
+    - Blank (left): Empty tens position from single-digit displays (1 template)
+    Total: 25 templates needed for full coverage
+    """
+
+    # Template coverage requirements
+    ONES_DIGITS = list(range(10))  # 0-9
+    TENS_DIGITS = [-1, 1, 2, 3, 4]  # -1 = blank, 1-4 for 10-40
+    POSITIONS = ["left", "center", "right"]
+
+    def __init__(self) -> None:
+        """Initialize empty template library."""
+        # Templates: {(is_tens, digit_value, position): DigitTemplate}
+        self.templates: Dict[Tuple[bool, int, str], DigitTemplate] = {}
+        logger.info("DigitTemplateLibrary initialized (empty)")
+
+    def add_template(self, template: DigitTemplate) -> None:
+        """
+        Add a template to the library.
+
+        Args:
+            template: DigitTemplate to add
+        """
+        key = (template.is_tens_digit, template.digit_value, template.position)
+        self.templates[key] = template
+        digit_display = "blank" if template.digit_value == -1 else str(template.digit_value)
+        logger.debug(
+            "Added template: tens=%s, digit=%s, position=%s",
+            template.is_tens_digit,
+            digit_display,
+            template.position,
+        )
+
+    def get_template(self, is_tens: bool, digit_value: int, position: str) -> Optional[DigitTemplate]:
+        """
+        Get a template from the library.
+
+        Args:
+            is_tens: Whether this is a tens digit
+            digit_value: The digit value (-1 for blank, 0-9 for digits)
+            position: Template position ("left", "center", or "right")
+
+        Returns:
+            DigitTemplate if found, None otherwise
+        """
+        key = (is_tens, digit_value, position)
+        return self.templates.get(key)
+
+    def get_all_templates(self, is_tens: bool, position: Optional[str] = None) -> List[DigitTemplate]:
+        """
+        Get all templates for a specific digit position.
+
+        Args:
+            is_tens: Whether to get tens digit templates
+            position: Optional position filter ("left", "center", or "right")
+
+        Returns:
+            List of matching DigitTemplate objects
+        """
+        templates = []
+        for (tens, _, pos), template in self.templates.items():
+            if tens == is_tens:
+                if position is None or pos == position:
+                    templates.append(template)
+        return templates
+
+    def get_coverage_status(self) -> Dict[str, Any]:
+        """
+        Get the current template coverage status.
+
+        Returns:
+            Dictionary with coverage information
+        """
+        # Use shared utility to categorize template keys
+        ones_center_have, ones_right_have, tens_have, has_blank = categorize_template_keys(self.templates.keys())
+
+        # Get base coverage status from shared utility
+        status = calculate_coverage_status(ones_center_have, ones_right_have, tens_have, has_blank, total_items=len(self.templates))
+
+        # Convert -1 to "blank" for display
+        def format_tens(digits: set[int]) -> list[str | int]:
+            return sorted(["blank" if d == -1 else d for d in digits], key=lambda x: (isinstance(x, str), x))
+
+        # Add legacy fields for backward compatibility
+        status["ones_have"] = sorted(ones_center_have | ones_right_have)
+        status["ones_missing"] = sorted((ONES_DIGITS - ones_center_have) & (ONES_DIGITS - ones_right_have))
+        status["tens_have_formatted"] = format_tens(tens_have | ({-1} if has_blank else set()))
+        status["tens_missing_formatted"] = format_tens(set(status["tens_missing"]) | (set() if has_blank else {-1}))
+
+        return status
+
+    def is_complete(self) -> bool:
+        """Check if all required templates are present."""
+        return bool(self.get_coverage_status()["is_complete"])
+
+    def save(self, output_path: str) -> None:
+        """
+        Save templates to disk.
+
+        Args:
+            output_path: Path to save directory
+        """
+        output_dir = Path(output_path)
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        templates_list: list[dict[str, object]] = []
+
+        for (is_tens, digit, position), template in self.templates.items():
+            # Use "blank" instead of -1 for the empty tens digit in filenames
+            digit_str = "blank" if digit == -1 else str(digit)
+            position_suffix = f"_{position}" if position != "left" or not is_tens else ""
+            filename = f"{'tens' if is_tens else 'ones'}_{digit_str}{position_suffix}.png"
+            cv2.imwrite(str(output_dir / filename), template.template)
+            templates_list.append(
+                {
+                    "filename": filename,
+                    "digit_value": digit_str,  # Use "blank" for display
+                    "is_tens_digit": template.is_tens_digit,
+                    "position": position,
+                    "sample_count": template.sample_count,
+                    "avg_confidence": template.avg_confidence,
+                }
+            )
+
+        metadata = {"templates": templates_list, "version": 2}  # Version 2 includes position
+
+        with open(output_dir / "templates_metadata.json", "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2)
+
+        logger.info("Saved %d templates to %s", len(self.templates), output_path)
+
+    def load(self, input_path: str) -> bool:
+        """
+        Load templates from disk.
+
+        Args:
+            input_path: Path to templates directory
+
+        Returns:
+            True if loaded successfully, False otherwise
+        """
+        input_dir = Path(input_path)
+        metadata_path = input_dir / "templates_metadata.json"
+
+        if not metadata_path.exists():
+            logger.warning("No templates metadata found at %s", metadata_path)
+            return False
+
+        with open(metadata_path, "r", encoding="utf-8") as f:
+            metadata = json.load(f)
+
+        version = metadata.get("version", 1)
+
+        for entry in metadata.get("templates", []):
+            img_path = input_dir / entry["filename"]
+            if img_path.exists():
+                template_img = cv2.imread(str(img_path), cv2.IMREAD_GRAYSCALE)
+                if template_img is not None:
+                    # Convert "blank" back to -1 for internal use
+                    digit_value = entry["digit_value"]
+                    if digit_value == "blank":
+                        digit_value = -1
+                    elif isinstance(digit_value, str):
+                        digit_value = int(digit_value)
+
+                    # Handle position (v2) or infer from old format (v1)
+                    is_tens = entry["is_tens_digit"]
+                    if version >= 2:
+                        position = entry.get("position", "left" if is_tens else "right")
+                    else:
+                        # V1 format: tens → left, ones → right (old behavior)
+                        position = "left" if is_tens else "right"
+
+                    template = DigitTemplate(
+                        digit_value=digit_value,
+                        is_tens_digit=is_tens,
+                        position=position,
+                        template=template_img,
+                        sample_count=entry.get("sample_count", 1),
+                        avg_confidence=entry.get("avg_confidence", 1.0),
+                    )
+                    self.add_template(template)
+
+        logger.info("Loaded %d templates from %s (v%d format)", len(self.templates), input_path, version)
+        return True

src/tracking/__init__.py

@@ -0,0 +1,37 @@
+"""Tracking modules for cross-frame state management.
+
+This package contains components that track state across multiple frames
+to identify play boundaries and other temporal events.
+
+Public API:
+- TrackPlayState: Main state machine for play tracking (facade over internal modules)
+- PlayMerger: Merges overlapping plays
+- ClockResetIdentifier: Post-hoc analysis of 40→25 clock resets
+- Models: PlayEvent, PlayState, PlayTrackingState, etc.
+
+Internal modules (not exported):
+- play_lifecycle: Play start/end/reset operations
+- play_identification_checks: Clock analysis for play boundary identification
+- state_handlers: State machine transition logic
+"""
+
+from .models import PlayEvent, PlayState, PlayTrackingState, TrackPlayStateConfig, TimeoutInfo, ClockResetStats
+from .play_state import TrackPlayState
+from .play_merger import PlayMerger
+from .clock_reset_identifier import ClockResetIdentifier
+
+__all__ = [
+    # Models
+    "PlayEvent",
+    "PlayState",
+    "PlayTrackingState",
+    "TrackPlayStateConfig",
+    "TimeoutInfo",
+    "ClockResetStats",
+    # State machine
+    "TrackPlayState",
+    # Merger
+    "PlayMerger",
+    # Clock reset identification
+    "ClockResetIdentifier",
+]