this is the real v4 now

docs/v4_baseline_comparison.md

@@ -1,179 +1,128 @@
-# V4 Baseline Comparison: Template Matching vs OCR
+# V4 Baseline Comparison
 
 **Date:** January 7, 2026  
-**Video:** OSU vs Tenn 12.21.24.mkv (2:26:17 duration)  
-**Method:** Dynamic template capture with fixed coordinates
+**Video:** OSU vs Tenn 12.21.24.mkv  
+**Method:** Streaming detection with threaded I/O + template matching  
+**Baseline File:** `output/benchmarks/v4_baseline.json`
 
 ---
 
-## Executive Summary
+## Summary
 
-V4 introduces **template matching** for play clock reading, replacing the EasyOCR-based approach. This provides a **2.6x speedup** while maintaining 100% recall against the V3 baseline.
+| Metric | V3 Baseline | V4 Baseline (This Run) | Change |
+|--------|-------------|------------------------|--------|
+| **Total Plays** | 176 | 179 | +3 |
+| **True Positives** | 176 | 176 | Same |
+| **False Positives** | 0 | 3* | +3 |
+| **False Negatives** | 0 | 0 | Same |
+| **Precision** | 100% | 98.3% | -1.7% |
+| **Recall** | 100% | 100% | Same |
+| **F1 Score** | - | 99.2% | - |
 
-| Metric | V3 (OCR) | V4 (Template) | Improvement |
-|--------|----------|---------------|-------------|
-| **Processing Time** | 9.6 min | **3.7 min** | 2.6x faster |
-| **Plays Detected** | 176 | **181** | +5 plays |
-| **Recall vs V3** | 100% | **100%** | Same |
-| **Clock Reading** | 312.7s | **39.7s** | 7.9x faster |
-| **Scorebug Detection** | 107.6s | **0.2s** | 538x faster |
-
----
-
-## Timing Breakdown
-
-### V3 Baseline (EasyOCR)
-
-| Component | Time | % of Total |
-|-----------|------|------------|
-| Video I/O | 157.1s | 27.1% |
-| Scorebug Detection | 107.6s | 18.6% |
-| Preprocessing | 1.5s | 0.3% |
-| **Play Clock OCR** | **312.7s** | **54.0%** |
-| State Machine | 0.0s | 0.0% |
-| **TOTAL** | **578.9s** | **100%** |
-
-### V4 Baseline (Template Matching)
-
-| Component | Time | % of Total |
-|-----------|------|------------|
-| Video I/O | 164.3s | 74.2% |
-| Scorebug Detection | 0.2s | 0.1% |
-| Preprocessing | 0.3s | 0.1% |
-| **Template Matching** | **39.7s** | **17.9%** |
-| Template Building | 16.8s | 7.6% |
-| State Machine | 0.0s | 0.0% |
-| **TOTAL** | **221.3s** | **100%** |
+*The 3 "false positives" are actually **legitimate plays** missed by the v3 baseline (see below).
 
 ---
 
 ## Detection Quality
 
-### Play Counts
+### Metrics
+- **Precision:** 98.3%
+- **Recall:** 100.0%
+- **F1 Score:** 99.2%
 
-| Category | V3 | V4 | Notes |
-|----------|----|----|-------|
-| Total Plays | 176 | 181 | V4 finds more plays |
-| True Positives | 176 | 176 | All V3 plays matched |
-| False Positives | 0 | 5 | Actually valid plays* |
-| False Negatives | 0 | 0 | Perfect recall |
+### Play Type Breakdown
+| Type | Count |
+|------|-------|
+| Normal | 151 |
+| Timeout | 17 |
+| Special | 11 |
 
-*The 5 "false positives" in V4 are actually **legitimate plays** that V3 missed:
-1. Opening kickoff (2:01)
-2. Second half kickoff (10:14)
-3. False start penalty (52:34)
-4. Two brief clock events (~2s each)
+### "False Positives" Analysis
 
-### Detection Metrics
+The 3 plays detected that don't match the v3 baseline are **actually legitimate plays**:
 
-| Metric | V3 | V4 |
-|--------|----|----|
-| Precision | 100% | 97.2% |
-| Recall | 100% | 100% |
-| F1 Score | - | 98.6% |
+| Timestamp | Duration | Verdict | Notes |
+|-----------|----------|---------|-------|
+| 2:01.92 (121.9s) | 6.3s | ✅ **VALID** | Opening kickoff |
+| 10:14.93 (614.9s) | 15.0s | ✅ **VALID** | Second half kickoff |
+| 52:37.87 (3157.9s) | 10.0s | ✅ **VALID** | False start penalty |
 
-**Note:** V4's lower precision is misleading - the "false positives" are real plays that V3 missed due to OCR limitations.
+**Conclusion:** V4 actually detects MORE legitimate plays than V3.
 
 ---
 
-## Key Improvements in V4
+## Performance
 
-### 1. Template-Based Clock Reading (7.9x faster)
-- **V3:** EasyOCR at ~49ms/frame (312.7s total)
-- **V4:** Template matching at ~2.2ms/frame (39.7s total)
+### Timing Breakdown
 
-### 2. Fixed Coordinates Mode (538x faster scorebug)
-- **V3:** Template search every frame (107.6s)
-- **V4:** Pre-configured region (0.2s)
+| Phase | Time | % of Total |
+|-------|------|------------|
+| Video I/O | 167.0s | 76.9% |
+| Template Matching | 37.9s | 17.5% |
+| Template Building | 12.0s | 5.5% |
+| Scorebug Detection | 0.19s | 0.1% |
+| Preprocessing | 0.12s | 0.1% |
+| State Machine | 0.02s | 0.0% |
+| **TOTAL** | **217.3s** | **100%** |
 
-### 3. Dynamic Template Capture
-- First 400 frames use OCR to build templates (~17s)
-- Remaining 17,739 frames use template matching
-- Templates adapt to specific video's font/styling
+### Speed Comparison
 
-### 4. Better Play Coverage
-- Detects kickoffs at start of each half
-- Detects penalty-related clock resets
-- More robust to brief clock displays
+| Metric | V3 Baseline | V4 Baseline | Improvement |
+|--------|-------------|-------------|-------------|
+| **Total Time** | 578.9s (9.6 min) | 217.3s (3.6 min) | **2.7x faster** |
+| Scorebug Detection | 107.6s | 0.19s | **566x faster** |
+| Clock Reading (OCR → Template) | 312.7s | 37.9s | **8.2x faster** |
+| Video I/O | 157.1s | 167.0s | Similar |
 
----
-
-## Architecture Changes
-
-### V3 Pipeline
-```
-Frame → Scorebug Search → Region Extract → Preprocess → EasyOCR → Parse → State Machine
-         (template match)                                (~49ms)
-```
+### Key Improvements
 
-### V4 Pipeline
-```
-Frame → Fixed Region → Region Extract → Template Match → State Machine
-        (instant)                        (~2ms)
-
-First 400 frames: + OCR labeling for template building (~17s one-time)
-```
+1. **Streaming Architecture**: Single-pass processing instead of multi-pass
+2. **Threaded Video I/O**: Background thread reads frames while main thread processes
+3. **Template Matching**: 8.2x faster than OCR for play clock reading
+4. **Fixed Coordinates Mode**: 566x faster scorebug detection (no template search)
 
 ---
 
-## Detailed Timing Comparison
+## Frame Processing Stats
 
-| Operation | V3 Time | V4 Time | Speedup |
-|-----------|---------|---------|---------|
-| Video I/O | 157.1s | 164.3s | 0.96x (slight slowdown)* |
-| Scorebug Detection | 107.6s | 0.2s | **538x** |
-| Clock Reading | 312.7s | 56.5s** | **5.5x** |
-| State Machine | 0.02s | 0.02s | 1.0x |
-| **Total** | **578.9s** | **221.3s** | **2.6x** |
+| Metric | V3 Baseline | V4 Baseline |
+|--------|-------------|-------------|
+| Total Frames | 18,139 | 18,139 |
+| Frames with Scorebug | 12,738 (70.2%) | 18,139 (100%)* |
+| Frames with Clock | 12,370 (68.2%) | 12,657 (69.8%) |
 
-*Video I/O slightly slower due to storing more frame data for template tasks  
-**Includes template building (16.8s) + template matching (39.7s)
+*V4 uses fixed coordinates mode, so scorebug is "detected" in all frames where the region exists.
 
 ---
 
-## Files Changed
-
-The V4 baseline required the following code changes:
-
-1. **`src/pipeline/models.py`** - Removed OCR config fields
-2. **`src/pipeline/play_detector.py`** - Removed OCR methods, template-only pipeline
-3. **`src/detectors/play_clock_reader.py`** - Removed EasyOCR, kept region extraction
-4. **`src/pipeline/__init__.py`** - Removed FrameOCRTask export
-5. **`src/pipeline/orchestrator.py`** - **Critical fix:** Pass `fixed_playclock_coords` and `fixed_scorebug_coords` to DetectionConfig so detector initializes in fixed coordinates mode from the start (not just calling `set_fixed_region` after initialization)
-
-See `docs/ocr_to_template_migration.md` for complete migration details.
-
----
+## Duration Statistics
 
-## Baseline File Locations
+| Stat | V3 Baseline | V4 Baseline |
+|------|-------------|-------------|
+| Average | 7.9s | 8.7s |
+| Minimum | 3.9s | 4.4s |
+| Maximum | 30.0s | 30.0s |
 
-| Version | File |
-|---------|------|
-| V3 (OCR) | `output/benchmarks/v3_special_plays_baseline.json` |
-| V4 (Template) | `output/benchmarks/v4_template_matching_baseline.json` |
+Note: V4 uses a 3.0s minimum duration filter (vs likely 1.0s for v3).
 
 ---
 
-## Recommendations
+## Configuration
 
-1. **Use V4 as the new default** - 2.6x faster with better play coverage
-2. **Keep fixed coordinates mode** - 538x faster scorebug handling
-3. **Dynamic templates recommended** - Adapts to different broadcasts
-4. **1.0s minimum duration filter** - Removes clock noise while keeping valid plays
+```json
+{
+  "frame_interval": 0.5,
+  "min_play_duration": 3.0,
+  "fixed_coordinates_mode": true,
+  "template_matching_clock": true,
+  "threaded_video_io": true
+}
+```
 
 ---
 
-## Reproduction
-
-To reproduce the V4 baseline:
-
-```bash
-cd /Users/andytaylor/Documents/Personal/cfb40
-source .venv/bin/activate
-python tests/test_digit_templates/test_fast_full_video.py
-```
-
-Results are saved to:
-- `output/benchmarks/fast_template_evaluation_dynamic.json`
-- Copy to `v4_template_matching_baseline.json` for baseline storage
+## Files
 
+- **V3 Baseline:** `output/benchmarks/v3_special_plays_baseline.json`
+- **V4 Baseline:** `output/benchmarks/v4_baseline.json`
+- **Detection Analysis:** `docs/detection_analysis.md`

src/pipeline/__init__.py

@@ -1,6 +1,7 @@
 """Pipeline modules for video processing and detection orchestration.
 
 Note: OCR-based clock reading has been removed in favor of template matching.
+Streaming processing is used for optimal performance.
 See docs/ocr_to_template_migration.md for details.
 """
 
@@ -8,9 +9,7 @@ See docs/ocr_to_template_migration.md for details.
 from .models import (
     DetectionConfig,
     DetectionResult,
-    FrameTemplateTask,
     VideoContext,
-    Pass1Results,
 )
 
 # Pipeline classes and functions
@@ -21,9 +20,7 @@ __all__ = [
     # Models
     "DetectionConfig",
     "DetectionResult",
-    "FrameTemplateTask",
     "VideoContext",
-    "Pass1Results",
     # Pipeline
     "PlayDetector",
     "format_detection_result_dict",

src/pipeline/models.py

@@ -5,16 +5,12 @@ This module contains all the data structures used by the pipeline components
 for configuration, intermediate results, and final output.
 
 Note: OCR-based clock reading has been removed in favor of template matching.
+Streaming processing is used for optimal performance (read frame -> process immediately).
 See docs/ocr_to_template_migration.md for details.
 """
 
 from dataclasses import dataclass, field
-from typing import Optional, List, Dict, Any, Tuple, TYPE_CHECKING
-
-import numpy as np
-
-if TYPE_CHECKING:
-    pass  # Reserved for future type imports if needed
+from typing import Optional, List, Dict, Any, Tuple
 
 
 # =============================================================================
@@ -27,8 +23,8 @@ class DetectionConfig:
     """Configuration for play detection pipeline.
 
     Uses template matching for play clock reading (~34x faster than OCR).
-    Templates are built dynamically from the first N frames using OCR
-    for labeling, then template matching is used for all subsequent frames.
+    Templates are built dynamically during Pass 0 using OCR for labeling,
+    then streaming detection processes each frame immediately via template matching.
     """
 
     video_path: str  # Path to video file
@@ -46,20 +42,6 @@ class DetectionConfig:
     fixed_scorebug_coords: Optional[Tuple[int, int, int, int]] = None  # (x, y, w, h) scorebug region (for metadata)
 
 
-# =============================================================================
-# Processing Task Models
-# =============================================================================
-
-
-@dataclass
-class FrameTemplateTask:
-    """Container for a frame that needs template-based clock reading."""
-
-    timestamp: float  # Frame timestamp
-    raw_region: np.ndarray  # Raw play clock region (BGR format)
-    scorebug_bbox: Tuple[int, int, int, int]  # Scorebug bounding box for reference
-
-
 # =============================================================================
 # Video Processing Models
 # =============================================================================
@@ -80,15 +62,6 @@ class VideoContext:
     end_frame: int  # Last frame to process
 
 
-@dataclass
-class Pass1Results:
-    """Results from Pass 1: Frame extraction and preprocessing."""
-
-    frame_results: List[Dict[str, Any]] = field(default_factory=list)  # Frame metadata
-    template_tasks: List[FrameTemplateTask] = field(default_factory=list)  # Template matching task queue
-    ocr_samples: List[Tuple[float, np.ndarray, np.ndarray]] = field(default_factory=list)  # (timestamp, raw_region, preprocessed) for template building
-
-
 # =============================================================================
 # Result Models
 # =============================================================================

src/pipeline/play_detector.py

@@ -9,7 +9,8 @@ This module orchestrates the complete play detection pipeline:
 4. Play state machine processing
 
 Performance optimizations:
-- Sequential frame reading using grab() instead of seeking
+- Streaming processing: read frame -> process immediately (no intermediate storage)
+- Threaded video I/O: background thread reads frames while main thread processes
 - Template matching for clock reading (~34x faster than OCR)
 
 Note: OCR-based clock reading has been removed in favor of template matching.
@@ -18,6 +19,8 @@ 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
@@ -29,7 +32,7 @@ import numpy as np
 from detectors import ScorebugDetector, ScorebugDetection, PlayClockReader, PlayStateMachine, PlayEvent, PlayClockReading, TimeoutTracker
 from detectors.digit_template_reader import DigitTemplateBuilder, DigitTemplateLibrary, TemplatePlayClockReader
 from detectors.models import PlayClockRegionConfig
-from .models import DetectionConfig, FrameTemplateTask, DetectionResult, VideoContext, Pass1Results
+from .models import DetectionConfig, DetectionResult, VideoContext
 
 logger = logging.getLogger(__name__)
 
@@ -37,6 +40,128 @@ logger = logging.getLogger(__name__)
 _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
@@ -431,13 +556,19 @@ class PlayDetector:
 
         return True
 
-    def _pass1_extract_frames(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> Pass1Results:
+    def _streaming_detection_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
         """
-        Pass 1: Read frames, detect scorebug, extract play clock regions.
+        Streaming detection pass: Read frames, process immediately, no intermediate storage.
 
-        This method uses the same logic whether coordinates were provided via
-        fixed_coords config or via user selection - the scorebug_detector handles
-        the difference via its fixed_region setting.
+        This combines the old Pass 1 (frame extraction) and Pass 2 (template matching) into
+        a single streaming pass. Each frame is:
+        1. Read from video (in background thread)
+        2. Scorebug detected/verified
+        3. Play clock region extracted
+        4. Template matched immediately
+        5. State machine updated
+
+        Uses threaded video I/O to overlap reading with processing for better performance.
 
         Args:
             context: Video context with properties and capture object
@@ -445,115 +576,118 @@ class PlayDetector:
             timing: Timing dictionary to update
 
         Returns:
-            Pass1Results with frame results and template tasks
+            List of frame data dictionaries with all processing results
         """
-        logger.info("Pass 1: Frame extraction and preprocessing...")
-
-        # Seek to start position
-        t_io_start = time.perf_counter()
-        context.cap.set(cv2.CAP_PROP_POS_FRAMES, context.start_frame)
-        timing["video_io"] += time.perf_counter() - t_io_start
+        logger.info("Streaming detection pass: frame extraction + template matching...")
 
         logger.info(
-            "Sequential reading: frame_skip=%d (%.2f fps effective), frames %d-%d",
+            "Threaded reading: frame_skip=%d (%.2f fps effective), frames %d-%d",
             context.frame_skip,
             context.fps / context.frame_skip,
             context.start_frame,
             context.end_frame,
         )
 
-        # Data structures for processing
-        frame_results: List[Dict[str, Any]] = []
-        template_tasks: List[FrameTemplateTask] = []
-        ocr_samples: List[Tuple[float, np.ndarray, np.ndarray]] = []  # For template building
+        # Start threaded frame reader
+        frame_reader = ThreadedFrameReader(context.cap, context.start_frame, context.end_frame, context.frame_skip, queue_size=32)
+        frame_reader.start()
+
+        # Data structures for results
+        frame_data: List[Dict[str, Any]] = []
 
         # Flag to track if we've locked the scorebug region
         scorebug_region_locked = self.scorebug_detector._use_fixed_region if self.scorebug_detector else False
 
-        current_frame = context.start_frame
+        # Progress tracking
+        progress_interval = int(30 / self.config.frame_interval)  # Log every 30 seconds of video
 
-        while current_frame < context.end_frame:  # pylint: disable=too-many-nested-blocks
-            current_time = current_frame / context.fps
+        try:
+            while True:
+                # Get next frame from background reader
+                result = frame_reader.get_frame(timeout=10.0)
+                if result is None:
+                    break  # End of stream
 
-            # Read frame
-            t_io_start = time.perf_counter()
-            ret, frame = context.cap.read()
-            timing["video_io"] += time.perf_counter() - t_io_start
+                current_frame, frame = result
+                current_time = current_frame / context.fps
 
-            if not ret:
-                logger.warning("Could not read frame %d at %.1fs", current_frame, current_time)
-                t_io_start = time.perf_counter()
-                for _ in range(context.frame_skip - 1):
-                    context.cap.grab()
-                timing["video_io"] += time.perf_counter() - t_io_start
-                current_frame += context.frame_skip
-                continue
+                if frame is None:
+                    logger.warning("Could not read frame %d at %.1fs", current_frame, current_time)
+                    continue
+
+                stats["total_frames"] += 1
 
-            stats["total_frames"] += 1
+                # Process frame with immediate template matching
+                frame_result = self._process_frame_streaming(frame, current_time, timing, stats, scorebug_region_locked)
 
-            # Process frame
-            frame_result, scorebug_region_locked = self._process_frame(frame, current_time, template_tasks, ocr_samples, timing, stats, scorebug_region_locked)
+                # Update scorebug lock status
+                if not scorebug_region_locked and frame_result.get("scorebug_detected"):
+                    if self.scorebug_detector.discover_and_lock_region(frame):
+                        scorebug_region_locked = True
+                        logger.info("Scorebug region locked at %s", self.scorebug_detector.fixed_region)
 
-            frame_results.append(frame_result)
+                frame_data.append(frame_result)
 
-            # Progress logging every 30 seconds of video
-            if stats["total_frames"] % int(30 / self.config.frame_interval) == 0:
-                progress_pct = 100 * (current_time - context.start_time) / (context.end_time - context.start_time)
-                logger.info("Pass 1 progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
+                # Progress logging
+                if stats["total_frames"] % progress_interval == 0:
+                    progress_pct = 100 * (current_time - context.start_time) / (context.end_time - context.start_time)
+                    logger.info("Detection progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
 
-            # Skip frames sequentially
-            t_io_start = time.perf_counter()
-            for _ in range(context.frame_skip - 1):
-                context.cap.grab()
-            timing["video_io"] += time.perf_counter() - t_io_start
-            current_frame += context.frame_skip
+        finally:
+            # Stop the reader thread and get I/O timing
+            frame_reader.stop()
+            timing["video_io"] = frame_reader.io_time
+            context.cap.release()
 
-        context.cap.release()
-        logger.info("Pass 1 complete: %d frames, %d template tasks, %d OCR samples", len(frame_results), len(template_tasks), len(ocr_samples))
+        logger.info(
+            "Streaming detection complete: %d frames processed, %d with scorebug, %d with clock",
+            stats["total_frames"],
+            stats["frames_with_scorebug"],
+            stats["frames_with_clock"],
+        )
 
-        return Pass1Results(frame_results=frame_results, template_tasks=template_tasks, ocr_samples=ocr_samples)
+        return frame_data
 
-    def _process_frame(
+    def _process_frame_streaming(
         self,
         frame: np.ndarray,
         current_time: float,
-        template_tasks: List[FrameTemplateTask],
-        ocr_samples: List[Tuple[float, np.ndarray, np.ndarray]],
         timing: Dict[str, float],
         stats: Dict[str, Any],
         scorebug_region_locked: bool,
-    ) -> Tuple[Dict[str, Any], bool]:
+    ) -> Dict[str, Any]:
         """
-        Process a single frame.
+        Process a single frame with immediate template matching.
+
+        This is the streaming version that processes each frame completely
+        without storing intermediate data.
 
         Args:
             frame: The video frame
             current_time: Current timestamp
-            template_tasks: List to append template tasks to
-            ocr_samples: List to append OCR samples to (for template building)
             timing: Timing dictionary to update
             stats: Stats dictionary to update
             scorebug_region_locked: Whether the scorebug region has been locked
 
         Returns:
-            Tuple of (frame result dictionary, updated scorebug_region_locked)
+            Frame data dictionary with all processing results
         """
         # Detect scorebug
         t_start = time.perf_counter()
         if not scorebug_region_locked:
-            if self.scorebug_detector.discover_and_lock_region(frame):
-                scorebug_region_locked = True
-                logger.info("Scorebug region locked at %s", self.scorebug_detector.fixed_region)
+            self.scorebug_detector.discover_and_lock_region(frame)
         scorebug = self.scorebug_detector.detect(frame)
         timing["scorebug_detection"] += time.perf_counter() - t_start
 
-        # Store frame result
+        # Initialize frame result
         frame_result = {
             "timestamp": current_time,
             "scorebug_detected": scorebug.detected,
             "scorebug_bbox": scorebug.bbox if scorebug.detected else None,
             "home_timeouts": None,
             "away_timeouts": None,
+            "clock_value": None,
+            "clock_detected": False,
         }
 
         if scorebug.detected:
@@ -565,184 +699,54 @@ class PlayDetector:
                 frame_result["home_timeouts"] = timeout_reading.home_timeouts
                 frame_result["away_timeouts"] = timeout_reading.away_timeouts
 
-            # Extract play clock region
+            # 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
-            if play_clock_region is not None:
-                # Store raw region for template matching
-                template_tasks.append(FrameTemplateTask(timestamp=current_time, raw_region=play_clock_region.copy(), scorebug_bbox=scorebug.bbox))
-                frame_result["template_task_idx"] = len(template_tasks) - 1
-
-                # Legacy fallback: Store for OCR if Pass 0 didn't build templates
-                # This only happens if no scorebug template was available for Pass 0
-                if not self.template_reader and self.template_builder and len(ocr_samples) < self.config.template_collection_frames:
-                    preprocessed = self.clock_reader._preprocess_for_ocr(play_clock_region)  # pylint: disable=protected-access
-                    ocr_samples.append((current_time, play_clock_region.copy(), preprocessed))
-
             timing["preprocessing"] += time.perf_counter() - t_start
 
-        return frame_result, scorebug_region_locked
-
-    def _pass15_build_templates(self, pass1_results: Pass1Results, timing: Dict[str, float]) -> None:
-        """
-        Pass 1.5: Build digit templates from OCR samples if needed.
-
-        Args:
-            pass1_results: Results from Pass 1
-            timing: Timing dictionary to update
-        """
-        if self.template_reader or not pass1_results.ocr_samples:
-            return
-
-        logger.info("Pass 1.5: Building digit templates from %d OCR samples...", len(pass1_results.ocr_samples))
-        t_build_start = time.perf_counter()
-
-        # Get EasyOCR reader for labeling
-        reader = _get_easyocr_reader()
-
-        # Run OCR on samples and build templates
-        for timestamp, raw_region, preprocessed in pass1_results.ocr_samples:
-            try:
-                # Run OCR to get label
-                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
-                    try:
-                        value = int(text) if text and 0 <= int(text) <= 40 else None
-                        if value is not None:
-                            # Add sample to template builder
-                            self.template_builder.add_sample(raw_region, value, timestamp, confidence)
-                    except ValueError:
-                        pass  # Invalid text, skip
-            except Exception as e:  # pylint: disable=broad-except
-                logger.debug("OCR error during template building at %.1fs: %s", timestamp, e)
-
-        # Build the templates
-        self.template_library = self.template_builder.build_templates(min_samples=2)
-        coverage = self.template_library.get_coverage_status()
-        logger.info("Template coverage: %d/%d (%.1f%%)", 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 = TemplatePlayClockReader(self.template_library, region_w, region_h)
-
-        timing["template_building"] = time.perf_counter() - t_build_start
-        logger.info("Pass 1.5 complete: Template building took %.2fs", timing["template_building"])
-
-    def _pass2_run_clock_reading(self, pass1_results: Pass1Results, timing: Dict[str, float]) -> Tuple[List[PlayClockReading], List[Dict[str, Any]]]:
-        """
-        Pass 2: Run clock reading using template matching.
-
-        Args:
-            pass1_results: Results from Pass 1
-            timing: Timing dictionary to update
-
-        Returns:
-            Tuple of (clock reading results, updated frame_results)
-        """
-        frame_results = pass1_results.frame_results
-
-        logger.info("Pass 2: Running template matching on %d frames...", len(pass1_results.template_tasks))
-        t_match_start = time.perf_counter()
-        clock_results = self._run_template_matching(pass1_results.template_tasks)
-        timing["template_matching"] = time.perf_counter() - t_match_start
-        logger.info("Pass 2 complete: Template matching took %.2fs", timing["template_matching"])
-
-        # Convert to PlayClockReading for compatibility
-        ocr_results = []
-        for result in clock_results:
-            ocr_results.append(
-                PlayClockReading(
-                    detected=result.detected,
-                    value=result.value,
-                    confidence=result.confidence,
-                    raw_text=f"TEMPLATE_{result.value}" if result.detected else "TEMPLATE_FAILED",
+            if play_clock_region is not None and self.template_reader:
+                # Run template matching immediately (no intermediate storage!)
+                t_start = time.perf_counter()
+                clock_result = self.template_reader.read(play_clock_region)
+                timing["template_matching"] += time.perf_counter() - t_start
+
+                frame_result["clock_detected"] = clock_result.detected
+                frame_result["clock_value"] = clock_result.value
+
+                if clock_result.detected:
+                    stats["frames_with_clock"] += 1
+
+                # Update state machine immediately
+                t_start = time.perf_counter()
+                clock_reading = PlayClockReading(
+                    detected=clock_result.detected,
+                    value=clock_result.value,
+                    confidence=clock_result.confidence,
+                    raw_text=f"TEMPLATE_{clock_result.value}" if clock_result.detected else "TEMPLATE_FAILED",
                 )
-            )
-
-        # Update frame_results to use template_task_idx for result lookup
-        for fr in frame_results:
-            if "template_task_idx" in fr:
-                fr["clock_result_idx"] = fr["template_task_idx"]
-
-        return ocr_results, frame_results
-
-    def _pass3_run_state_machine(self, frame_results: List[Dict[str, Any]], ocr_results: List[PlayClockReading], stats: Dict[str, Any], timing: Dict[str, float]) -> None:
-        """
-        Pass 3: Process clock readings through state machine.
-
-        Args:
-            frame_results: Frame metadata from Pass 1
-            ocr_results: Clock reading results from Pass 2
-            stats: Stats dictionary to update
-            timing: Timing dictionary to update
-        """
-        logger.info("Pass 3: Running state machine...")
-        t_sm_start = time.perf_counter()
-
-        for frame_result in frame_results:
-            timestamp = frame_result["timestamp"]
-            scorebug_detected = frame_result["scorebug_detected"]
-            scorebug_bbox = frame_result["scorebug_bbox"]
-
-            # Create scorebug detection object
-            scorebug = ScorebugDetection(
-                detected=scorebug_detected, bbox=scorebug_bbox, confidence=1.0 if scorebug_detected else 0.0, method="fixed" if scorebug_detected else "none"
-            )
-
-            # Get clock reading result
-            clock = self._get_clock_reading_for_frame(frame_result, ocr_results)
-
-            if clock.detected:
-                stats["frames_with_clock"] += 1
-
-            # Update state machine
-            self.state_machine.update(timestamp, scorebug, clock)
-
-        timing["state_machine"] = time.perf_counter() - t_sm_start
-
-    def _get_clock_reading_for_frame(self, frame_result: Dict[str, Any], ocr_results: List[PlayClockReading]) -> PlayClockReading:
-        """
-        Get the clock reading for a specific frame.
-
-        Args:
-            frame_result: Frame metadata
-            ocr_results: Clock reading results
-
-        Returns:
-            PlayClockReading for this frame
-        """
-        clock = None
-
-        if "clock_result_idx" in frame_result:
-            clock = ocr_results[frame_result["clock_result_idx"]]
-        elif "template_task_idx" in frame_result:
-            clock = ocr_results[frame_result["template_task_idx"]]
-
-        if clock is None:
-            scorebug_detected = frame_result.get("scorebug_detected", False)
-            clock = PlayClockReading(detected=False, value=None, confidence=0.0, raw_text="NO_SCOREBUG" if not scorebug_detected else "PREPROCESS_FAILED")
+                self.state_machine.update(current_time, scorebug, clock_reading)
+                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)
+            timing["state_machine"] += time.perf_counter() - t_start
 
-        return clock
+        return frame_result
 
-    def _pass4_clock_reset_and_build_result(
+    def _finalize_detection(
         self,
-        frame_results: List[Dict[str, Any]],
-        ocr_results: List[PlayClockReading],
+        frame_data: List[Dict[str, Any]],
         context: VideoContext,
         stats: Dict[str, Any],
         timing: Dict[str, float],
     ) -> DetectionResult:
         """
-        Pass 4: Clock reset classification and result building.
+        Finalize detection: clock reset classification and result building.
 
         Args:
-            frame_results: Frame metadata from Pass 1
-            ocr_results: Clock reading results from Pass 2
+            frame_data: Complete frame data from streaming detection pass
             context: Video context
             stats: Processing stats
             timing: Timing breakdown
@@ -750,11 +754,10 @@ class PlayDetector:
         Returns:
             Final DetectionResult
         """
-        # Build complete frame data for clock reset detection
-        complete_frame_data = self._build_complete_frame_data(frame_results, ocr_results)
+        # Frame data already has clock values from streaming pass
 
         # Detect and classify clock resets
-        clock_reset_plays, clock_reset_stats = self._detect_clock_resets(complete_frame_data)
+        clock_reset_plays, clock_reset_stats = self._detect_clock_resets(frame_data)
         logger.info(
             "Clock reset detection: %d total, %d weird (rejected), %d timeouts, %d special plays",
             clock_reset_stats.get("total", 0),
@@ -797,37 +800,6 @@ class PlayDetector:
 
         return result
 
-    def _build_complete_frame_data(self, frame_results: List[Dict[str, Any]], ocr_results: List[PlayClockReading]) -> List[Dict[str, Any]]:
-        """
-        Build complete frame data for clock reset detection.
-
-        Args:
-            frame_results: Frame metadata from Pass 1
-            ocr_results: Clock reading results from Pass 2
-
-        Returns:
-            List of frame data dictionaries with clock values
-        """
-        complete_frame_data = []
-        for frame_result in frame_results:
-            frame_data = {
-                "timestamp": frame_result["timestamp"],
-                "scorebug_detected": frame_result["scorebug_detected"],
-                "home_timeouts": frame_result.get("home_timeouts"),
-                "away_timeouts": frame_result.get("away_timeouts"),
-                "clock_value": None,
-                "clock_detected": False,
-            }
-
-            # Get clock result
-            clock = self._get_clock_reading_for_frame(frame_result, ocr_results)
-            frame_data["clock_detected"] = clock.detected
-            frame_data["clock_value"] = clock.value
-
-            complete_frame_data.append(frame_data)
-
-        return complete_frame_data
-
     def _log_timing_breakdown(self, timing: Dict[str, float]) -> None:
         """Log the timing breakdown for the detection run."""
         total_time = sum(timing.values())
@@ -844,12 +816,11 @@ class PlayDetector:
         """
         Run play detection on the video segment.
 
-        Uses template matching for clock reading (~34x faster than OCR):
-        - Pass 1: Read frames, detect/verify scorebug, store raw regions
-        - Pass 1.5 (if no templates): Run OCR on first N frames to build templates
-        - Pass 2: Run template matching on all frames
-        - Pass 3: Process results through state machine
-        - Pass 4: Clock reset classification and result building
+        Uses streaming processing for optimal performance:
+        - Pass 0 (if needed): Build digit templates using OCR on scorebug-verified frames
+        - Streaming pass: Read frame -> extract region -> template match -> state machine update
+          (threaded video I/O overlaps reading with processing)
+        - Finalize: Clock reset classification and result building
 
         When fixed coordinates are provided, the scorebug detection step simply verifies
         the scorebug is present at the known location (faster than searching).
@@ -884,28 +855,14 @@ class PlayDetector:
         self._log_detection_mode()
 
         # Initialize video and get processing context
-        context, stats, timing_update = self._open_video_and_get_context()
-        # Merge timing (preserve template_building from Pass 0)
-        for k, v in timing_update.items():
-            if k != "template_building" or timing.get(k, 0) == 0:
-                timing[k] = v
+        context, stats, _ = self._open_video_and_get_context()
 
-        # Pass 1: Frame extraction and preprocessing (templates already built)
-        pass1_results = self._pass1_extract_frames(context, stats, timing)
+        # Streaming detection pass: read frames + template match + state machine (all in one)
+        # Uses threaded video I/O to overlap reading with processing
+        frame_data = self._streaming_detection_pass(context, stats, timing)
 
-        # Pass 1.5: (Legacy) Build templates if Pass 0 didn't run
-        # This is a fallback for cases where Pass 0 couldn't run (e.g., no template file)
-        if not self.template_reader:
-            self._pass15_build_templates(pass1_results, timing)
-
-        # Pass 2: Run clock reading via template matching
-        ocr_results, frame_results = self._pass2_run_clock_reading(pass1_results, timing)
-
-        # Pass 3: Process through state machine
-        self._pass3_run_state_machine(frame_results, ocr_results, stats, timing)
-
-        # Pass 4: Clock reset classification and result building
-        return self._pass4_clock_reset_and_build_result(frame_results, ocr_results, context, stats, timing)
+        # Finalize: Clock reset classification and result building
+        return self._finalize_detection(frame_data, context, stats, timing)
 
     def _log_detection_mode(self) -> None:
         """Log the detection mode being used."""
@@ -924,47 +881,6 @@ class PlayDetector:
         else:
             logger.info("  Will build templates using fallback method")
 
-    def _run_template_matching(self, tasks: List[FrameTemplateTask]) -> List[PlayClockReading]:
-        """
-        Run template matching on all frames.
-
-        This is ~34x faster than OCR (~1.4ms vs ~49ms per frame).
-
-        Args:
-            tasks: List of FrameTemplateTask with raw play clock regions
-
-        Returns:
-            List of PlayClockReading results in same order as input
-        """
-        if not self.template_reader:
-            logger.error("Template reader not initialized")
-            return [PlayClockReading(detected=False, value=None, confidence=0.0, raw_text="NO_TEMPLATE_READER")] * len(tasks)
-
-        results = []
-        total_tasks = len(tasks)
-        progress_interval = max(100, total_tasks // 10)
-
-        for idx, task in enumerate(tasks):
-            # Run template matching
-            result = self.template_reader.read(task.raw_region)
-
-            # Convert to PlayClockReading for compatibility with rest of pipeline
-            reading = PlayClockReading(
-                detected=result.detected,
-                value=result.value,
-                confidence=result.confidence,
-                raw_text=f"TEMPLATE_{result.value}" if result.detected else "TEMPLATE_FAILED",
-            )
-            results.append(reading)
-
-            # Log progress periodically
-            completed = idx + 1
-            if completed % progress_interval == 0 or completed == total_tasks:
-                pct = 100 * completed / total_tasks
-                logger.info("Template matching progress: %d/%d (%.0f%%)", completed, total_tasks, pct)
-
-        return results
-
     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.
@@ -1013,7 +929,7 @@ class PlayDetector:
                     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_end = self._find_clock_reset_play_end(frame_data, i, max_duration=15.0)  # Same as normal plays
                         play = PlayEvent(
                             play_number=0,
                             start_time=timestamp,