some large moving

src/pipeline/__init__.py

@@ -15,6 +15,7 @@ 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 .template_builder_pass import TemplateBuildingPass
 
 __all__ = [
     # Models
@@ -26,4 +27,5 @@ __all__ = [
     "format_detection_result_dict",
     "run_detection",
     "print_results_summary",
+    "TemplateBuildingPass",
 ]

src/pipeline/parallel.py

@@ -123,7 +123,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

src/pipeline/play_detector.py

@@ -1,4 +1,3 @@
-# pylint: disable=too-many-lines
 """
 Play detector pipeline module.
 
@@ -19,160 +18,24 @@ 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 detection import DetectScoreBug, ScorebugDetection, DetectTimeouts
-from readers import ReadPlayClock, PlayClockReading, TemplatePlayClockReading
+from readers import ReadPlayClock, PlayClockReading
 from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
-from tracking import TrackPlayState, PlayEvent
+from tracking import TrackPlayState, PlayEvent, PlayMerger, TimeoutInfo
+from video import ThreadedFrameReader
 from .models import DetectionConfig, DetectionResult, 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]:
     """
@@ -376,22 +239,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
@@ -399,164 +247,18 @@ 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 DetectScoreBug for Pass 0 detection
-        # This uses the user-created template + fixed region for fast/accurate detection
-        temp_detector = DetectScoreBug(
-            template_path=str(template_path),
-            fixed_region=(sb_x, sb_y, sb_w, sb_h),
-            use_split_detection=self.config.use_split_detection,
+        # Use the extracted TemplateBuildingPass module
+        template_pass = TemplateBuildingPass(
+            config=self.config,
+            clock_reader=self.clock_reader,
+            template_builder=self.template_builder,
         )
 
-        # Get EasyOCR reader for labeling
-        reader = _get_easyocr_reader()
+        # Run template building
+        self.template_library, self.template_reader, build_time = template_pass.run()
+        timing["template_building"] = build_time
 
-        # 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"],
-        )
-
-        # 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 = ReadPlayClock(self.template_library, region_w, region_h)
-
-        timing["template_building"] = time.perf_counter() - t_build_start
-        logger.info("Pass 0 complete: Template building took %.2fs", timing["template_building"])
-
-        return True
+        return self.template_library is not None
 
     def _streaming_detection_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
         """
@@ -692,6 +394,9 @@ class PlayDetector:
             "clock_detected": False,
         }
 
+        # Initialize timeout_info for state machine
+        timeout_info = None
+
         if scorebug.detected:
             stats["frames_with_scorebug"] += 1
 
@@ -700,10 +405,15 @@ 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
+            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:
@@ -718,7 +428,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,
@@ -726,29 +436,32 @@ 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(
         self,
-        frame_data: List[Dict[str, Any]],
+        frame_data: List[Dict[str, Any]],  # pylint: disable=unused-argument
         context: VideoContext,
         stats: Dict[str, Any],
         timing: Dict[str, float],
     ) -> DetectionResult:
         """
-        Finalize detection: clock reset classification and result building.
+        Finalize detection: apply filtering and build result.
+
+        Clock reset classification is now handled inline by TrackPlayState during
+        the streaming pass, so we just need to merge/filter and build the result.
 
         Args:
-            frame_data: Complete frame data from streaming detection pass
+            frame_data: Complete frame data from streaming detection pass (unused, kept for API compatibility)
             context: Video context
             stats: Processing stats
             timing: Timing breakdown
@@ -756,30 +469,26 @@ class PlayDetector:
         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 (clock reset classification already done inline)
+        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)
+        # Log clock reset stats from state machine
+        clock_reset_stats = play_stats.get("clock_reset_events", {})
         logger.info(
-            "Clock reset detection: %d total, %d weird (rejected), %d timeouts, %d special plays",
+            "Clock reset classification: %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)
-
-        # 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 clock reset stats
-        play_stats["clock_reset_events"] = clock_reset_stats
-
-        # Combine and deduplicate plays
-        plays = self._merge_plays(state_machine_plays, clock_reset_plays)
+        # Use PlayMerger to deduplicate and apply quiet time filter
+        merger = PlayMerger()
+        plays = merger.merge(state_machine_plays)
 
         result = DetectionResult(
             video=Path(self.config.video_path).name,
@@ -983,7 +692,14 @@ 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)
+            # 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_module.perf_counter() - t_sm_start
 
         # Update stats dict
@@ -1013,290 +729,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 {

src/pipeline/template_builder_pass.py

@@ -0,0 +1,279 @@
+"""
+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.
+"""
+
+import logging
+import time
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+import cv2
+import easyocr
+
+from detection import DetectScoreBug
+from readers import ReadPlayClock
+from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionExtractor
+from .models import DetectionConfig
+
+logger = logging.getLogger(__name__)
+
+# Global EasyOCR reader instance for template building (lazy-loaded)
+_easyocr_reader = None  # pylint: disable=invalid-name
+
+
+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
+
+
+class TemplateBuildingPass:
+    """
+    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.
+    """
+
+    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.
+
+        Args:
+            config: Detection configuration
+            clock_reader: Play clock region extractor
+            template_builder: Digit template builder
+            min_samples: Minimum valid OCR samples to collect
+            max_scan_frames: Maximum frames to scan
+            target_coverage: Target template coverage (0.0-1.0)
+        """
+        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.
+
+        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", self.min_samples, self.target_coverage * 100)
+
+        t_build_start = time.perf_counter()
+
+        # Validate configuration
+        if not self._validate_config():
+            return None, None, time.perf_counter() - t_build_start
+
+        # Create temporary scorebug detector for Pass 0
+        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", self.config.template_path)
+
+        temp_detector = DetectScoreBug(
+            template_path=str(self.config.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()
+
+        # Scan video and collect samples
+        valid_samples, frames_scanned, frames_with_scorebug = self._scan_video(temp_detector, reader)
+
+        # 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 = self.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 = 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
+        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
+
+    def _validate_config(self) -> bool:
+        """Validate that required configuration is present."""
+        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
+
+        return True
+
+    def _scan_video(self, temp_detector: DetectScoreBug, reader: easyocr.Reader) -> Tuple[int, int, int]:
+        """
+        Scan video frames and collect OCR samples for template building.
+
+        Args:
+            temp_detector: Scorebug detector to use
+            reader: EasyOCR reader instance
+
+        Returns:
+            Tuple of (valid_samples, frames_scanned, frames_with_scorebug)
+        """
+        # Open video
+        cap = cv2.VideoCapture(self.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(self.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 < self.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
+                    valid_samples += self._process_scorebug_frame(frame, scorebug_result.bbox, current_time, reader)
+
+                # Progress logging every 200 frames
+                if frames_scanned % 200 == 0:
+                    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 >= self.min_samples or coverage >= self.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
+
+    def _process_scorebug_frame(self, frame, scorebug_bbox: Tuple[int, int, int, int], current_time: float, 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
+            reader: EasyOCR reader
+
+        Returns:
+            1 if a valid sample was collected, 0 otherwise
+        """
+        # Extract play clock region
+        play_clock_region = self.clock_reader.extract_region(frame, scorebug_bbox)
+        if play_clock_region is None:
+            return 0
+
+        # Preprocess and run OCR
+        preprocessed = self.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:
+                        self.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

src/tracking/__init__.py

@@ -4,13 +4,20 @@ This package contains components that track state across multiple frames
 to detect play boundaries and other temporal events.
 """
 
-from .models import PlayEvent
-from .play_state import TrackPlayState, PlayState
+from .models import PlayEvent, PlayState, PlayTrackingState, TrackPlayStateConfig, TimeoutInfo, ClockResetStats
+from .play_state import TrackPlayState
+from .play_merger import PlayMerger
 
 __all__ = [
     # Models
     "PlayEvent",
+    "PlayState",
+    "PlayTrackingState",
+    "TrackPlayStateConfig",
+    "TimeoutInfo",
+    "ClockResetStats",
     # State machine
     "TrackPlayState",
-    "PlayState",
+    # Merger
+    "PlayMerger",
 ]

src/tracking/models.py

@@ -1,14 +1,26 @@
 """
 Pydantic models for play tracking.
 
-These models represent detected plays and their temporal boundaries.
+These models represent detected plays, their temporal boundaries,
+and the state machine configuration/state for play detection.
 """
 
-from typing import Optional
+from enum import Enum
+from typing import Optional, List, Tuple
 
 from pydantic import BaseModel, Field
 
 
+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)
+
+
 class PlayEvent(BaseModel):
     """Represents a detected play with start and end times."""
 
@@ -22,3 +34,67 @@ class PlayEvent(BaseModel):
     start_clock_value: Optional[int] = Field(None, description="Clock value at start detection")
     end_clock_value: Optional[int] = Field(None, description="Clock value used for backward calculation")
     play_type: str = Field("normal", description="Type of play: 'normal', 'special' (punt/fg/xp after 25-second reset)")
+
+
+class TrackPlayStateConfig(BaseModel):
+    """Configuration settings for play state tracking.
+
+    These values control the detection thresholds and timing parameters
+    used by the state machine to identify play boundaries.
+    """
+
+    clock_stable_frames: int = Field(3, description="Frames with same clock value to consider it 'stable'")
+    max_play_duration: float = Field(15.0, description="Maximum expected play duration in seconds")
+    scorebug_lost_timeout: float = Field(30.0, description="Seconds before resetting state when scorebug lost")
+    required_countdown_ticks: int = Field(3, description="Number of consecutive descending ticks required to confirm play end")
+    min_clock_jump_for_reset: int = Field(5, description="Minimum jump in clock value to consider it a valid reset (40 from X where X <= 40 - this value)")
+
+
+class TimeoutInfo(BaseModel):
+    """Timeout information for a frame."""
+
+    home_timeouts: Optional[int] = Field(None, description="Number of home team timeouts remaining")
+    away_timeouts: Optional[int] = Field(None, description="Number of away team timeouts remaining")
+
+
+class ClockResetStats(BaseModel):
+    """Statistics about clock reset classifications."""
+
+    total: int = Field(0, description="Total 40→25 resets detected")
+    weird_clock: int = Field(0, description="Class A: 25 counts down immediately (rejected)")
+    timeout: int = Field(0, description="Class B: Timeout indicator changed")
+    special: int = Field(0, description="Class C: Special play (injury/punt/FG/XP)")
+
+
+class PlayTrackingState(BaseModel):
+    """Internal mutable state for play tracking.
+
+    Tracks the current detection state, detected plays, and all intermediate
+    tracking variables used during play boundary detection.
+    """
+
+    # Current detection state
+    state: PlayState = Field(PlayState.IDLE, description="Current state of the play detection state machine")
+    plays: List[PlayEvent] = Field(default_factory=list, description="List of all detected plays")
+
+    # Tracking counters and values
+    play_count: int = Field(0, description="Total number of plays detected so far")
+    last_clock_value: Optional[int] = Field(None, description="Last observed play clock value")
+    last_clock_timestamp: Optional[float] = Field(None, description="Timestamp of last clock reading")
+    clock_stable_count: int = Field(0, description="Number of consecutive frames with same clock value")
+
+    # Current play tracking
+    current_play_start_time: Optional[float] = Field(None, description="Start time of the current play being tracked")
+    current_play_start_method: Optional[str] = Field(None, description="Method used to detect current play start")
+    current_play_start_clock: Optional[int] = Field(None, description="Clock value when current play started")
+    last_scorebug_timestamp: Optional[float] = Field(None, description="Timestamp of last scorebug detection")
+    direct_end_time: Optional[float] = Field(None, description="Direct end time observation (for comparison)")
+    countdown_history: List[Tuple[float, int]] = Field(default_factory=list, description="List of (timestamp, clock_value) for countdown tracking")
+    first_40_timestamp: Optional[float] = Field(None, description="When we first saw 40 in current play (for turnover detection)")
+    current_play_clock_base: int = Field(40, description="Clock base for current play (40 for normal, 25 for special teams)")
+    current_play_type: str = Field("normal", description="Type of current play being tracked: 'normal' or 'special'")
+
+    # Timeout tracking for clock reset classification
+    last_home_timeouts: Optional[int] = Field(None, description="Last observed home team timeouts")
+    last_away_timeouts: Optional[int] = Field(None, description="Last observed away team timeouts")
+    clock_reset_stats: ClockResetStats = Field(default_factory=ClockResetStats, description="Statistics about clock reset classifications")

src/tracking/play_merger.py

@@ -0,0 +1,152 @@
+"""
+Play merger module for combining and filtering detected plays.
+
+This module handles merging plays from multiple sources (state machine, clock reset detection),
+removing duplicates, and applying filters to reduce false positives.
+"""
+
+import logging
+from typing import List
+
+from .models import PlayEvent
+
+logger = logging.getLogger(__name__)
+
+
+class PlayMerger:
+    """
+    Merge plays from multiple sources with deduplication and filtering.
+
+    Handles:
+    - Overlapping plays (start_time < last.end_time)
+    - Close plays (start times within proximity_threshold) representing same event
+    - Quiet time filtering after normal plays
+    """
+
+    def __init__(self, proximity_threshold: float = 5.0, quiet_time: float = 10.0):
+        """
+        Initialize the play merger.
+
+        Args:
+            proximity_threshold: Plays within this time (seconds) are considered the same event
+            quiet_time: Seconds after normal play ends before special/timeout plays are allowed
+        """
+        self.proximity_threshold = proximity_threshold
+        self.quiet_time = quiet_time
+
+    def merge(self, *play_lists: List[PlayEvent]) -> List[PlayEvent]:
+        """
+        Merge multiple lists of plays, removing overlaps and duplicates.
+
+        Args:
+            play_lists: Variable number of play lists to merge
+
+        Returns:
+            Merged list of plays sorted by start time, deduplicated and renumbered
+        """
+        # Combine all play lists
+        all_plays = []
+        for plays in play_lists:
+            all_plays.extend(plays)
+
+        all_plays.sort(key=lambda p: p.start_time)
+
+        if not all_plays:
+            return []
+
+        # Remove overlapping and close plays
+        filtered = self._deduplicate(all_plays)
+
+        # Apply quiet time filter
+        filtered = self._apply_quiet_time_filter(filtered)
+
+        # Renumber plays
+        for i, play in enumerate(filtered, 1):
+            play.play_number = i
+
+        return filtered
+
+    def _deduplicate(self, plays: List[PlayEvent]) -> List[PlayEvent]:
+        """
+        Remove overlapping and close plays, keeping the highest priority one.
+
+        Priority: normal > special > timeout (normal plays are most reliable)
+
+        Args:
+            plays: Sorted list of plays
+
+        Returns:
+            Deduplicated list of plays
+        """
+        if not plays:
+            return []
+
+        filtered = [plays[0]]
+
+        for play in 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) < self.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)
+
+        return filtered
+
+    def _apply_quiet_time_filter(self, plays: List[PlayEvent]) -> 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
+
+        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 + self.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

src/tracking/play_state.py

@@ -5,32 +5,25 @@ 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.
+
+Clock Reset Classification:
+The state machine also classifies 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)
 """
 
 import logging
-from dataclasses import dataclass, field
-from enum import Enum
 from typing import Optional, List
 
 from detection import ScorebugDetection
 from readers import PlayClockReading
-from .models import PlayEvent
+from .models import PlayEvent, PlayState, PlayTrackingState, TrackPlayStateConfig, TimeoutInfo
 
 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 TrackPlayState:  # pylint: disable=too-many-instance-attributes
+class TrackPlayState:  # pylint: disable=too-many-instance-attributes,too-many-public-methods
     """
     State machine for detecting play boundaries using play clock behavior.
 
@@ -46,33 +39,44 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
     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]:
+    def __init__(self, config: Optional[TrackPlayStateConfig] = None):
+        """Initialize the state machine.
+
+        Args:
+            config: Configuration settings. Uses defaults if not provided.
+        """
+        self.config = config or TrackPlayStateConfig()
+        self._state = PlayTrackingState()
+
+    # =========================================================================
+    # Properties for backward compatibility (access state fields directly)
+    # =========================================================================
+
+    @property
+    def state(self) -> PlayState:
+        """Current state of the play detection state machine."""
+        return self._state.state
+
+    @state.setter
+    def state(self, value: PlayState) -> None:
+        self._state.state = value
+
+    @property
+    def plays(self) -> List[PlayEvent]:
+        """List of all detected plays."""
+        return self._state.plays
+
+    # =========================================================================
+    # Main update method
+    # =========================================================================
+
+    def update(
+        self,
+        timestamp: float,
+        scorebug: ScorebugDetection,
+        clock: PlayClockReading,
+        timeout_info: Optional[TimeoutInfo] = None,
+    ) -> Optional[PlayEvent]:
         """
         Update the state machine with new frame data.
 
@@ -80,16 +84,24 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
             timestamp: Current video timestamp in seconds
             scorebug: Scorebug detection result
             clock: Play clock reading result
+            timeout_info: Optional timeout indicator information for clock reset classification
 
         Returns:
             PlayEvent if a play just ended, None otherwise
         """
+        # Update timeout tracking if provided
+        if timeout_info is not None:
+            if timeout_info.home_timeouts is not None:
+                self._state.last_home_timeouts = timeout_info.home_timeouts
+            if timeout_info.away_timeouts is not None:
+                self._state.last_away_timeouts = timeout_info.away_timeouts
+
         # Handle scorebug presence/absence
         if not scorebug.detected:
             return self._handle_no_scorebug(timestamp)
 
         # Update last scorebug timestamp
-        self._last_scorebug_timestamp = timestamp
+        self._state.last_scorebug_timestamp = timestamp
 
         # Handle invalid clock reading
         if not clock.detected or clock.value is None:
@@ -97,30 +109,30 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
             return None
 
         # Process valid clock reading
-        return self._process_clock_value(timestamp, clock.value)
+        return self._process_clock_value(timestamp, clock.value, timeout_info)
 
     def _handle_no_scorebug(self, timestamp: float) -> Optional[PlayEvent]:
         """Handle case when scorebug is not detected."""
-        if self.state == PlayState.IDLE:
+        if self._state.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:
+        if self._state.last_scorebug_timestamp is not None:
+            time_since_scorebug = timestamp - self._state.last_scorebug_timestamp
+            if time_since_scorebug > self.config.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
+        if self._state.state == PlayState.PLAY_IN_PROGRESS and self._state.first_40_timestamp is not None:
+            time_at_40 = (self._state.last_scorebug_timestamp - self._state.first_40_timestamp) if self._state.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
+                play_end_time = self._state.last_scorebug_timestamp if self._state.last_scorebug_timestamp else timestamp
                 logger.info(
                     "Scorebug disappeared during play at %.1fs (%.1fs at 40). Recording play end at %.1fs.",
                     timestamp,
@@ -129,156 +141,238 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
                 )
                 # Record the play before transitioning
                 completed_play = self._end_play_with_backward_calc(timestamp, 40, play_end_time)
-                self.state = PlayState.NO_SCOREBUG
+                self._state.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):
+        if self._state.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
+            self._state.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:
+        if self._state.state == PlayState.PRE_SNAP and self._state.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]:
+    def _process_clock_value(self, timestamp: float, clock_value: int, timeout_info: Optional[TimeoutInfo] = None) -> Optional[PlayEvent]:
         """
         Process a valid clock reading and update state.
 
         Args:
             timestamp: Current timestamp
             clock_value: Detected play clock value (0-40)
+            timeout_info: Optional timeout indicator information
 
         Returns:
             PlayEvent if a play just completed
         """
         completed_play = None
 
-        if self.state == PlayState.IDLE:
+        if self._state.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
+            self._state.state = PlayState.PRE_SNAP
+            self._state.last_clock_value = clock_value
+            self._state.last_clock_timestamp = timestamp
+            self._state.clock_stable_count = 1
 
-        elif self.state == PlayState.PRE_SNAP:
+        elif self._state.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
+            completed_play = self._handle_pre_snap(timestamp, clock_value, timeout_info)
 
-        elif self.state == PlayState.PLAY_IN_PROGRESS:
+        elif self._state.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:
+        elif self._state.state == PlayState.POST_PLAY:
             # Play ended, transitioning back to PRE_SNAP
             self._handle_post_play(timestamp, clock_value)
 
-        elif self.state == PlayState.NO_SCOREBUG:
+        elif self._state.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
+        self._state.last_clock_value = clock_value
+        self._state.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
+    def _handle_pre_snap(self, timestamp: float, clock_value: int, timeout_info: Optional[TimeoutInfo] = None) -> Optional[PlayEvent]:
+        """Handle clock reading during PRE_SNAP state.
+
+        This method also classifies 40→25 clock reset events:
+        - Class A (weird_clock): 25 counts down immediately → rejected
+        - Class B (timeout): Timeout indicator changed → tracked as timeout play
+        - Class C (special): Neither A nor B → special play (punt/FG/XP)
+        """
+        if self._state.last_clock_value is None:
+            self._state.last_clock_value = clock_value
+            self._state.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)
+        max_prev_value = 40 - self.config.min_clock_jump_for_reset  # e.g., 35 if min_jump=5
+        if clock_value == 40 and self._state.last_clock_value <= max_prev_value:
+            logger.info("Play START detected at %.1fs (clock reset to 40 from %d)", timestamp, self._state.last_clock_value)
+            self._state.current_play_clock_base = 40
+            self._state.current_play_type = "normal"
+            self._start_play(timestamp, "clock_reset", self._state.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:
+        if clock_value == 40 and self._state.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,
+                self._state.last_clock_value,
                 max_prev_value,
             )
-            # Don't update _last_clock_value - treat this 40 reading as noise
+            # 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)
+        # Check for 40→25 clock reset - classify and handle appropriately
+        if clock_value == 25 and self._state.last_clock_value == 40:
+            return self._classify_40_to_25_reset(timestamp, timeout_info)
+
+        # Check for other clock resets to 25 (significant jump indicates special teams play)
+        if clock_value == 25 and self._state.last_clock_value is not None:
+            clock_jump = abs(clock_value - self._state.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:
+            # A jump of 5+ indicates a real reset (e.g., 30→25 after brief 40, or 10→25 after play)
+            if clock_jump >= self.config.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,
+                    self._state.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)
+                self._state.current_play_clock_base = 25
+                self._state.current_play_type = "special"
+                self._start_play(timestamp, "clock_reset_25", self._state.last_clock_value)
                 return None
 
         # Track clock stability (for potential future use)
-        if clock_value == self._last_clock_value:
-            self._clock_stable_count += 1
+        if clock_value == self._state.last_clock_value:
+            self._state.clock_stable_count += 1
         else:
-            self._clock_stable_count = 1
+            self._state.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
 
+    def _classify_40_to_25_reset(self, timestamp: float, timeout_info: Optional[TimeoutInfo] = None) -> Optional[PlayEvent]:
+        """
+        Classify a 40→25 clock reset and handle appropriately.
+
+        Classification:
+        - Class A (weird_clock): Will be handled by checking if 25 counts down immediately
+          (detected later in _handle_play_in_progress via abnormal clock drop)
+        - Class B (timeout): Timeout indicator changed → tracked as timeout play
+        - Class C (special): Neither A nor B → special play (punt/FG/XP)
+
+        For now, we check for timeout change. If no timeout, treat as special play.
+        The weird_clock case will naturally be filtered when 25 starts counting down.
+
+        Args:
+            timestamp: Current timestamp
+            timeout_info: Optional timeout indicator information
+
+        Returns:
+            None (play tracking is started, not completed)
+        """
+        self._state.clock_reset_stats.total += 1
+
+        # Check for timeout change (Class B)
+        timeout_team = self._check_timeout_change(timeout_info)
+
+        if timeout_team:
+            # Class B: Team timeout detected
+            self._state.clock_reset_stats.timeout += 1
+            logger.info(
+                "Clock reset 40→25 at %.1fs classified as TIMEOUT (%s team)",
+                timestamp,
+                timeout_team,
+            )
+            self._state.current_play_clock_base = 25
+            self._state.current_play_type = "timeout"
+            self._start_play(timestamp, f"timeout_{timeout_team}", 40)
+        else:
+            # Class C: Special play (punt/FG/XP) - or potentially Class A (will be filtered later)
+            self._state.clock_reset_stats.special += 1
+            logger.info(
+                "Clock reset 40→25 at %.1fs classified as SPECIAL play",
+                timestamp,
+            )
+            self._state.current_play_clock_base = 25
+            self._state.current_play_type = "special"
+            self._start_play(timestamp, "clock_reset_special", 40)
+
+        return None
+
+    def _check_timeout_change(self, timeout_info: Optional[TimeoutInfo] = None) -> Optional[str]:
+        """
+        Check if a timeout indicator changed, indicating a team timeout.
+
+        Args:
+            timeout_info: Current timeout information
+
+        Returns:
+            "home" or "away" if a timeout was used, None otherwise
+        """
+        if timeout_info is None:
+            return None
+
+        # Compare current timeouts with last known values
+        if timeout_info.home_timeouts is not None and self._state.last_home_timeouts is not None:
+            if timeout_info.home_timeouts < self._state.last_home_timeouts:
+                return "home"
+
+        if timeout_info.away_timeouts is not None and self._state.last_away_timeouts is not None:
+            if timeout_info.away_timeouts < self._state.last_away_timeouts:
+                return "away"
+
+        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:
+        if self._state.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:
+        play_duration = timestamp - self._state.current_play_start_time
+        if play_duration > self.config.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
+            capped_end_time = self._state.current_play_start_time + self.config.max_play_duration
             logger.warning(
                 "Play duration (%.1fs) exceeded max (%.1fs), forcing end at %.1fs (capped from %.1fs)",
                 play_duration,
-                self.max_play_duration,
+                self.config.max_play_duration,
                 capped_end_time,
                 timestamp,
             )
-            self._direct_end_time = capped_end_time
-            self._countdown_history = []  # Reset countdown tracking
+            self._state.direct_end_time = capped_end_time
+            self._state.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
+            if self._state.first_40_timestamp is None:
+                self._state.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
+            logger.debug("Play in progress at %.1fs, clock still at 40 (%.1fs at 40)", timestamp, timestamp - self._state.first_40_timestamp)
+            self._state.countdown_history = []  # Reset countdown tracking
             return None
 
         # RAPID 40→25 TRANSITION DETECTION (possession change during play):
@@ -292,12 +386,12 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
         # 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
+        if clock_value == 25 and self._state.first_40_timestamp is not None:
+            time_at_40 = timestamp - self._state.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:
+            if min_time_at_40 <= time_at_40 <= max_time_for_possession_change and len(self._state.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(
@@ -306,10 +400,10 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
                     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
+                self._state.current_play_type = "special"
+                self._state.current_play_clock_base = 25
+                self._state.first_40_timestamp = None  # Reset since we're now tracking at 25
+                self._state.countdown_history = []  # Reset countdown tracking for fresh detection at 25
                 return None  # Continue tracking - DO NOT end the play!
 
         # ABNORMAL CLOCK DROP DETECTION:
@@ -318,13 +412,13 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
         # 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:
+        if len(self._state.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
+                time_at_40 = (timestamp - self._state.first_40_timestamp) if self._state.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:
@@ -349,17 +443,17 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
                     time_at_40,
                 )
                 self._reset_play_tracking()
-                self.state = PlayState.PRE_SNAP
+                self._state.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))
+        self._state.countdown_history.append((timestamp, clock_value))
 
         # Check if we have enough consecutive descending values
-        if len(self._countdown_history) >= self.required_countdown_ticks:
+        if len(self._state.countdown_history) >= self.config.required_countdown_ticks:
             # Get last K readings
-            recent = self._countdown_history[-self.required_countdown_ticks :]
+            recent = self._state.countdown_history[-self.config.required_countdown_ticks :]
             values = [v for _, v in recent]
 
             # Check if values are strictly descending (or stable which means same second)
@@ -374,19 +468,19 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
                 # 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)
+                calculated_end_time = first_timestamp - (self._state.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,
+                    self.config.required_countdown_ticks,
                     calculated_end_time,
                     values[0],
                     values[-1],
-                    self._current_play_clock_base,
+                    self._state.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
+                self._state.direct_end_time = timestamp  # When we confirmed the countdown
+                self._state.countdown_history = []  # Reset for next play
                 return self._end_play_with_backward_calc(timestamp, first_value, calculated_end_time)
 
         return None
@@ -396,22 +490,22 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
         # 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
+        self._state.state = PlayState.PRE_SNAP
+        self._state.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:
+        if self._state.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)
+            calculated_end_time = timestamp - (self._state.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,
+                self._state.current_play_clock_base,
                 calculated_end_time,
             )
             completed_play = self._end_play_with_backward_calc(timestamp, clock_value, calculated_end_time)
@@ -419,39 +513,39 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
             # 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
+        self._state.state = PlayState.PRE_SNAP
+        self._state.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
+        self._state.current_play_start_time = timestamp
+        self._state.current_play_start_method = method
+        self._state.current_play_start_clock = clock_value
+        self._state.countdown_history = []  # Reset countdown tracking for new play
+        self._state.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
+        self._state.play_count += 1
 
         play = PlayEvent(
-            play_number=self._play_count,
-            start_time=self._current_play_start_time or capped_end_time,
+            play_number=self._state.play_count,
+            start_time=self._state.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",
+            start_method=self._state.current_play_start_method or "unknown",
             end_method=method,
-            direct_end_time=self._direct_end_time,
-            start_clock_value=self._current_play_start_clock,
+            direct_end_time=self._state.direct_end_time,
+            start_clock_value=self._state.current_play_start_clock,
             end_clock_value=clock_value,
-            play_type=self._current_play_type,
+            play_type=self._state.current_play_type,
         )
 
-        self.plays.append(play)
+        self._state.plays.append(play)
         self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
+        self._state.state = PlayState.POST_PLAY
 
         logger.info(
             "Play #%d complete (capped, %s): %.1fs - %.1fs (duration: %.1fs)",
@@ -466,27 +560,27 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
 
     def _end_play(self, timestamp: float, clock_value: int, method: str) -> PlayEvent:
         """End the current play and create a PlayEvent."""
-        self._play_count += 1
+        self._state.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,
+            play_number=self._state.play_count,
+            start_time=self._state.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",
+            start_method=self._state.current_play_start_method or "unknown",
             end_method=method,
-            direct_end_time=self._direct_end_time,
-            start_clock_value=self._current_play_start_clock,
+            direct_end_time=self._state.direct_end_time,
+            start_clock_value=self._state.current_play_start_clock,
             end_clock_value=clock_value,
-            play_type=self._current_play_type,
+            play_type=self._state.current_play_type,
         )
 
-        self.plays.append(play)
+        self._state.plays.append(play)
         self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
+        self._state.state = PlayState.POST_PLAY
 
         logger.info(
             "Play #%d complete (%s): %.1fs - %.1fs (duration: %.1fs)",
@@ -501,7 +595,7 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
 
     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
+        start_time = self._state.current_play_start_time or calculated_end_time
 
         # Sanity check: end time must be after start time
         if calculated_end_time < start_time:
@@ -511,40 +605,40 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
                 start_time,
             )
             self._reset_play_tracking()
-            self.state = PlayState.PRE_SNAP
+            self._state.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
+        min_duration = 0.0 if self._state.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
+            self._state.state = PlayState.PRE_SNAP
             return None
 
-        self._play_count += 1
+        self._state.play_count += 1
 
         play = PlayEvent(
-            play_number=self._play_count,
+            play_number=self._state.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",
+            start_method=self._state.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,
+            direct_end_time=self._state.direct_end_time,  # May be None
+            start_clock_value=self._state.current_play_start_clock,
             end_clock_value=clock_value,
-            play_type=self._current_play_type,
+            play_type=self._state.current_play_type,
         )
 
-        self.plays.append(play)
+        self._state.plays.append(play)
         self._reset_play_tracking()
-        self.state = PlayState.POST_PLAY
+        self._state.state = PlayState.POST_PLAY
 
         logger.info(
             "Play #%d complete (backward calc, %s): %.1fs - %.1fs (duration: %.1fs, observed at %.1fs with clock=%d)",
@@ -561,45 +655,46 @@ class TrackPlayState:  # pylint: disable=too-many-instance-attributes
 
     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
+        self._state.current_play_start_time = None
+        self._state.current_play_start_method = None
+        self._state.current_play_start_clock = None
+        self._state.direct_end_time = None
+        self._state.clock_stable_count = 0
+        self._state.countdown_history = []
+        self._state.first_40_timestamp = None
+        self._state.current_play_clock_base = 40  # Reset to default
+        self._state.current_play_type = "normal"  # Reset to default
 
     def _reset_state(self) -> None:
         """Fully reset state machine."""
-        self.state = PlayState.IDLE
+        self._state.state = PlayState.IDLE
         self._reset_play_tracking()
-        self._last_clock_value = None
-        self._last_clock_timestamp = None
-        self._last_scorebug_timestamp = None
+        self._state.last_clock_value = None
+        self._state.last_clock_timestamp = None
+        self._state.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()
+        return self._state.plays.copy()
 
     def get_state(self) -> PlayState:
         """Get current state."""
-        return self.state
+        return self._state.state
 
     def get_stats(self) -> dict:
         """Get statistics about detected plays."""
-        if not self.plays:
-            return {"total_plays": 0}
+        if not self._state.plays:
+            return {"total_plays": 0, "clock_reset_events": self._state.clock_reset_stats.model_dump()}
 
-        durations = [p.end_time - p.start_time for p in self.plays]
+        durations = [p.end_time - p.start_time for p in self._state.plays]
         return {
-            "total_plays": len(self.plays),
+            "total_plays": len(self._state.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)},
+            "start_methods": {m: sum(1 for p in self._state.plays if p.start_method == m) for m in set(p.start_method for p in self._state.plays)},
+            "end_methods": {m: sum(1 for p in self._state.plays if p.end_method == m) for m in set(p.end_method for p in self._state.plays)},
+            "play_types": {t: sum(1 for p in self._state.plays if p.play_type == t) for t in set(p.play_type for p in self._state.plays)},
+            "clock_reset_events": self._state.clock_reset_stats.model_dump(),
         }

src/video/__init__.py

@@ -1,6 +1,7 @@
 """Video processing modules for frame extraction and FFmpeg operations."""
 
 from .frame_extractor import extract_sample_frames, get_video_duration, get_video_fps
+from .frame_reader import ThreadedFrameReader
 from .ffmpeg_ops import (
     extract_clip_stream_copy,
     extract_clip_reencode,
@@ -13,6 +14,7 @@ __all__ = [
     "extract_sample_frames",
     "get_video_duration",
     "get_video_fps",
+    "ThreadedFrameReader",
     "extract_clip_stream_copy",
     "extract_clip_reencode",
     "concatenate_clips",

src/video/frame_reader.py

@@ -0,0 +1,139 @@
+"""
+Threaded frame reader for video processing.
+
+Provides a background thread for reading video frames using a producer-consumer pattern.
+This overlaps video I/O with processing for better performance.
+"""
+
+import logging
+import queue
+import threading
+import time
+from typing import Optional, Tuple
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__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