better clock reading, faster

scripts/benchmark_ocr.py

@@ -0,0 +1,540 @@
+#!/usr/bin/env python3
+"""
+Benchmark different OCR methods for play clock reading.
+
+This script compares:
+1. Tesseract (current method)
+2. EasyOCR (deep learning based)
+3. Template matching (custom digit templates)
+
+Usage:
+    python scripts/benchmark_ocr.py
+"""
+
+import logging
+import sys
+import time
+from pathlib import Path
+from typing import List, Tuple, Optional, Dict, Any
+
+import cv2
+import numpy as np
+
+# Add src to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+# pylint: disable=wrong-import-position
+from detectors import ScorebugDetector
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+# Constants
+VIDEO_PATH = Path(__file__).parent.parent / "full_videos" / "OSU vs Tenn 12.21.24.mkv"
+TEMPLATE_PATH = Path(__file__).parent.parent / "data" / "templates" / "scorebug_template_main.png"
+CONFIG_PATH = Path(__file__).parent.parent / "data" / "config" / "play_clock_region.json"
+DIGIT_TEMPLATES_DIR = Path(__file__).parent.parent / "data" / "templates" / "digits"
+
+# Test segment - sample frames with known clock values (30 frames)
+TEST_TIMESTAMPS = [2320.0 + i for i in range(30)]
+# Expected values based on countdown pattern: 18->17->...->12->40->40->40->39->...
+# This is approximate - the real test will use Tesseract as ground truth
+
+
+def load_play_clock_config() -> Tuple[int, int, int, int]:
+    """Load play clock region config."""
+    import json
+
+    with open(CONFIG_PATH, "r") as f:
+        data = json.load(f)
+    return (data["x_offset"], data["y_offset"], data["width"], data["height"])
+
+
+def extract_test_frames(
+    video_path: Path, detector: ScorebugDetector, timestamps: List[float]
+) -> List[Tuple[float, np.ndarray, Tuple[int, int, int, int]]]:
+    """Extract frames with scorebug for testing."""
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise ValueError(f"Could not open video: {video_path}")
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    frames = []
+
+    for ts in timestamps:
+        frame_number = int(ts * fps)
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+        ret, frame = cap.read()
+        if not ret:
+            continue
+
+        detection = detector.detect(frame)
+        if detection.detected and detection.bbox:
+            frames.append((ts, frame, detection.bbox))
+
+    cap.release()
+    return frames
+
+
+def extract_play_clock_region(frame: np.ndarray, scorebug_bbox: Tuple[int, int, int, int], config: Tuple[int, int, int, int]) -> np.ndarray:
+    """Extract play clock region from frame."""
+    sb_x, sb_y, sb_w, sb_h = scorebug_bbox
+    x_offset, y_offset, width, height = config
+
+    pc_x = sb_x + x_offset
+    pc_y = sb_y + y_offset
+
+    return frame[pc_y : pc_y + height, pc_x : pc_x + width].copy()
+
+
+def preprocess_for_ocr(region: np.ndarray) -> np.ndarray:
+    """Standard preprocessing for OCR."""
+    # Convert to grayscale
+    gray = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
+
+    # Scale up
+    scale_factor = 4
+    scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
+
+    # Otsu's threshold
+    _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+    # Invert if needed (dark text on light background)
+    if np.mean(binary) < 128:
+        binary = cv2.bitwise_not(binary)
+
+    return binary
+
+
+# ============================================================
+# OCR Method 1: Tesseract (current baseline)
+# ============================================================
+def ocr_tesseract(region: np.ndarray) -> Tuple[Optional[int], float]:
+    """Read digits using Tesseract."""
+    import pytesseract
+
+    preprocessed = preprocess_for_ocr(region)
+
+    # Add padding
+    padding = 10
+    preprocessed = cv2.copyMakeBorder(preprocessed, padding, padding, padding, padding, cv2.BORDER_CONSTANT, value=255)
+
+    config = "--psm 7 -c tessedit_char_whitelist=0123456789"
+
+    try:
+        data = pytesseract.image_to_data(preprocessed, config=config, output_type=pytesseract.Output.DICT)
+
+        best_text = ""
+        best_conf = 0.0
+
+        for i, text in enumerate(data["text"]):
+            conf = float(data["conf"][i])
+            if conf > best_conf and text.strip():
+                best_text = text.strip()
+                best_conf = conf
+
+        if best_text and best_text.isdigit():
+            value = int(best_text)
+            if 0 <= value <= 40:
+                return value, best_conf / 100.0
+
+    except Exception as e:
+        logger.debug(f"Tesseract error: {e}")
+
+    return None, 0.0
+
+
+# ============================================================
+# OCR Method 2: EasyOCR
+# ============================================================
+_easyocr_reader = None
+
+
+def get_easyocr_reader():
+    """Lazy-load EasyOCR reader."""
+    global _easyocr_reader
+    if _easyocr_reader is None:
+        try:
+            import easyocr
+
+            _easyocr_reader = easyocr.Reader(["en"], gpu=False)  # CPU mode for fair comparison
+            logger.info("EasyOCR reader initialized")
+        except ImportError:
+            logger.warning("EasyOCR not installed. Install with: pip install easyocr")
+            return None
+    return _easyocr_reader
+
+
+def ocr_easyocr(region: np.ndarray) -> Tuple[Optional[int], float]:
+    """Read digits using EasyOCR."""
+    reader = get_easyocr_reader()
+    if reader is None:
+        return None, 0.0
+
+    preprocessed = preprocess_for_ocr(region)
+
+    try:
+        # EasyOCR expects BGR or grayscale
+        results = reader.readtext(preprocessed, allowlist="0123456789", detail=1)
+
+        if results:
+            # Get highest confidence result
+            best_result = max(results, key=lambda x: x[2])
+            text = best_result[1].strip()
+            conf = best_result[2]
+
+            if text.isdigit():
+                value = int(text)
+                if 0 <= value <= 40:
+                    return value, conf
+
+    except Exception as e:
+        logger.debug(f"EasyOCR error: {e}")
+
+    return None, 0.0
+
+
+# ============================================================
+# OCR Method 3: Template Matching for Digits
+# ============================================================
+
+
+class DigitTemplateMatcher:
+    """Fast digit recognition using template matching."""
+
+    def __init__(self):
+        self.digit_templates: Dict[str, np.ndarray] = {}
+        self._calibrated = False
+
+    def calibrate_from_tesseract(self, regions: List[np.ndarray]) -> bool:
+        """
+        Calibrate digit templates using Tesseract as ground truth on first few frames.
+
+        This extracts individual digit images from frames where Tesseract successfully reads values.
+        """
+        logger.info("Calibrating digit templates from Tesseract readings...")
+
+        for region in regions:
+            # Get Tesseract reading as ground truth
+            value, conf = ocr_tesseract(region)
+            if value is None or conf < 0.7:
+                continue
+
+            # Preprocess and extract digit regions
+            preprocessed = preprocess_for_ocr(region)
+            h, w = preprocessed.shape
+
+            # Find digit contours
+            contours, _ = cv2.findContours(cv2.bitwise_not(preprocessed), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+            if not contours:
+                continue
+
+            # Get bounding boxes sorted left-to-right
+            boxes = [cv2.boundingRect(c) for c in contours]
+            boxes = [(x, y, bw, bh) for x, y, bw, bh in boxes if bh > h * 0.3]  # Filter small noise
+            boxes.sort(key=lambda b: b[0])  # Sort by x position
+
+            # Extract digits based on value
+            value_str = str(value)
+            if len(boxes) != len(value_str):
+                continue  # Mismatch, skip
+
+            for i, (x, y, bw, bh) in enumerate(boxes):
+                digit = value_str[i]
+                # Add padding around digit
+                pad = 4
+                x1 = max(0, x - pad)
+                y1 = max(0, y - pad)
+                x2 = min(w, x + bw + pad)
+                y2 = min(h, y + bh + pad)
+
+                digit_img = preprocessed[y1:y2, x1:x2]
+
+                # Store template (keep best quality one per digit)
+                if digit not in self.digit_templates or digit_img.shape[0] * digit_img.shape[1] > self.digit_templates[digit].shape[0] * self.digit_templates[digit].shape[1]:
+                    self.digit_templates[digit] = digit_img.copy()
+
+            # Check if we have all digits we need (0-4 for tens, 0-9 for ones)
+            if all(str(d) in self.digit_templates for d in range(10)):
+                break
+
+        logger.info(f"  Calibrated templates for digits: {sorted(self.digit_templates.keys())}")
+        self._calibrated = len(self.digit_templates) >= 5  # At least 0-4 for play clock
+
+        return self._calibrated
+
+    def read(self, region: np.ndarray) -> Tuple[Optional[int], float]:
+        """Read digits using template matching."""
+        if not self._calibrated:
+            return None, 0.0
+
+        preprocessed = preprocess_for_ocr(region)
+        h, w = preprocessed.shape
+
+        # Find digit contours
+        contours, _ = cv2.findContours(cv2.bitwise_not(preprocessed), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+        if not contours:
+            return None, 0.0
+
+        # Get bounding boxes sorted left-to-right
+        boxes = [cv2.boundingRect(c) for c in contours]
+        boxes = [(x, y, bw, bh) for x, y, bw, bh in boxes if bh > h * 0.3]  # Filter noise
+        boxes.sort(key=lambda b: b[0])
+
+        if not boxes:
+            return None, 0.0
+
+        # Match each digit region to templates
+        digits = []
+        total_conf = 0.0
+
+        for x, y, bw, bh in boxes:
+            # Extract digit with padding
+            pad = 4
+            x1 = max(0, x - pad)
+            y1 = max(0, y - pad)
+            x2 = min(w, x + bw + pad)
+            y2 = min(h, y + bh + pad)
+
+            digit_img = preprocessed[y1:y2, x1:x2]
+
+            # Match against all templates
+            best_digit = None
+            best_conf = 0.0
+
+            for digit, template in self.digit_templates.items():
+                # Resize template to match digit height
+                if template.shape[0] == 0 or digit_img.shape[0] == 0:
+                    continue
+
+                scale = digit_img.shape[0] / template.shape[0]
+                new_w = max(1, int(template.shape[1] * scale))
+                resized = cv2.resize(template, (new_w, digit_img.shape[0]), interpolation=cv2.INTER_LINEAR)
+
+                # Pad smaller image to match sizes for comparison
+                digit_img_padded = digit_img
+                if resized.shape[1] < digit_img.shape[1]:
+                    diff = digit_img.shape[1] - resized.shape[1]
+                    resized = cv2.copyMakeBorder(resized, 0, 0, diff // 2, diff - diff // 2, cv2.BORDER_CONSTANT, value=255)
+                elif digit_img.shape[1] < resized.shape[1]:
+                    diff = resized.shape[1] - digit_img.shape[1]
+                    digit_img_padded = cv2.copyMakeBorder(digit_img, 0, 0, diff // 2, diff - diff // 2, cv2.BORDER_CONSTANT, value=255)
+
+                # Ensure same size
+                min_h = min(resized.shape[0], digit_img_padded.shape[0])
+                min_w = min(resized.shape[1], digit_img_padded.shape[1])
+                resized = resized[:min_h, :min_w]
+                digit_img_padded = digit_img_padded[:min_h, :min_w]
+
+                # Calculate normalized cross-correlation
+                if resized.size == 0 or digit_img_padded.size == 0:
+                    continue
+
+                # Simple pixel difference score
+                diff = np.abs(resized.astype(float) - digit_img_padded.astype(float))
+                score = 1.0 - (np.mean(diff) / 255.0)
+
+                if score > best_conf:
+                    best_conf = score
+                    best_digit = digit
+
+            if best_digit is not None and best_conf > 0.5:
+                digits.append(best_digit)
+                total_conf += best_conf
+
+        if not digits:
+            return None, 0.0
+
+        # Combine digits into number
+        try:
+            value = int("".join(digits))
+            avg_conf = total_conf / len(digits)
+            if 0 <= value <= 40:
+                return value, avg_conf
+        except ValueError:
+            pass
+
+        return None, 0.0
+
+
+_digit_matcher = None
+
+
+def get_digit_matcher() -> DigitTemplateMatcher:
+    """Get or create digit template matcher."""
+    global _digit_matcher
+    if _digit_matcher is None:
+        _digit_matcher = DigitTemplateMatcher()
+    return _digit_matcher
+
+
+def ocr_template_matching(region: np.ndarray) -> Tuple[Optional[int], float]:
+    """Read digits using template matching."""
+    matcher = get_digit_matcher()
+    return matcher.read(region)
+
+
+# ============================================================
+# Benchmark Runner
+# ============================================================
+def run_benchmark(frames: List[Tuple[float, np.ndarray, Tuple[int, int, int, int]]], config: Tuple[int, int, int, int]) -> None:
+    """Run benchmark comparing OCR methods."""
+    logger.info("=" * 60)
+    logger.info("OCR BENCHMARK")
+    logger.info("=" * 60)
+    logger.info(f"Testing {len(frames)} frames")
+
+    # Extract play clock regions
+    regions = []
+    for ts, frame, scorebug_bbox in frames:
+        region = extract_play_clock_region(frame, scorebug_bbox, config)
+        regions.append((ts, region))
+
+    # Method 1: Tesseract (baseline - also used for ground truth)
+    logger.info("")
+    logger.info("-" * 60)
+    logger.info("Method 1: Tesseract (baseline)")
+    logger.info("-" * 60)
+
+    tesseract_results = []
+    t_start = time.perf_counter()
+    for ts, region in regions:
+        value, conf = ocr_tesseract(region)
+        tesseract_results.append((ts, value, conf))
+    tesseract_time = time.perf_counter() - t_start
+
+    tesseract_success = sum(1 for _, v, _ in tesseract_results if v is not None)
+    logger.info(f"  Success rate: {tesseract_success}/{len(regions)} ({100*tesseract_success/len(regions):.1f}%)")
+    logger.info(f"  Total time: {tesseract_time:.3f}s")
+    logger.info(f"  Per-frame: {1000*tesseract_time/len(regions):.1f}ms")
+    logger.info(f"  Values: {[v for _, v, _ in tesseract_results]}")
+
+    # Use Tesseract results as ground truth for accuracy comparison
+    ground_truth = {ts: v for ts, v, _ in tesseract_results if v is not None}
+
+    # Method 2: EasyOCR
+    logger.info("")
+    logger.info("-" * 60)
+    logger.info("Method 2: EasyOCR")
+    logger.info("-" * 60)
+
+    reader = get_easyocr_reader()
+    easyocr_time = 0
+    easyocr_success = 0
+    easyocr_accuracy = 0
+
+    if reader:
+        easyocr_results = []
+        t_start = time.perf_counter()
+        for ts, region in regions:
+            value, conf = ocr_easyocr(region)
+            easyocr_results.append((ts, value, conf))
+        easyocr_time = time.perf_counter() - t_start
+
+        easyocr_success = sum(1 for _, v, _ in easyocr_results if v is not None)
+        # Calculate accuracy vs ground truth
+        easyocr_correct = sum(1 for ts, v, _ in easyocr_results if ts in ground_truth and v == ground_truth[ts])
+        easyocr_accuracy = easyocr_correct / len(ground_truth) * 100 if ground_truth else 0
+
+        logger.info(f"  Success rate: {easyocr_success}/{len(regions)} ({100*easyocr_success/len(regions):.1f}%)")
+        logger.info(f"  Accuracy vs Tesseract: {easyocr_correct}/{len(ground_truth)} ({easyocr_accuracy:.1f}%)")
+        logger.info(f"  Total time: {easyocr_time:.3f}s")
+        logger.info(f"  Per-frame: {1000*easyocr_time/len(regions):.1f}ms")
+        logger.info(f"  Speedup vs Tesseract: {tesseract_time/easyocr_time:.2f}x")
+        logger.info(f"  Values: {[v for _, v, _ in easyocr_results]}")
+    else:
+        logger.info("  SKIPPED (EasyOCR not installed)")
+
+    # Method 3: Template Matching
+    logger.info("")
+    logger.info("-" * 60)
+    logger.info("Method 3: Template Matching")
+    logger.info("-" * 60)
+
+    matcher = get_digit_matcher()
+
+    # Calibrate using first 10 regions (not counted in benchmark time)
+    calibration_regions = [r for _, r in regions[:10]]
+    if matcher.calibrate_from_tesseract(calibration_regions):
+        template_results = []
+        t_start = time.perf_counter()
+        for ts, region in regions:
+            value, conf = ocr_template_matching(region)
+            template_results.append((ts, value, conf))
+        template_time = time.perf_counter() - t_start
+
+        template_success = sum(1 for _, v, _ in template_results if v is not None)
+        template_correct = sum(1 for ts, v, _ in template_results if ts in ground_truth and v == ground_truth[ts])
+        template_accuracy = template_correct / len(ground_truth) * 100 if ground_truth else 0
+
+        logger.info(f"  Success rate: {template_success}/{len(regions)} ({100*template_success/len(regions):.1f}%)")
+        logger.info(f"  Accuracy vs Tesseract: {template_correct}/{len(ground_truth)} ({template_accuracy:.1f}%)")
+        logger.info(f"  Total time: {template_time:.3f}s")
+        logger.info(f"  Per-frame: {1000*template_time/len(regions):.1f}ms")
+        logger.info(f"  Speedup vs Tesseract: {tesseract_time/template_time:.2f}x")
+        logger.info(f"  Values: {[v for _, v, _ in template_results]}")
+    else:
+        logger.info("  SKIPPED (calibration failed)")
+        template_time = 0
+        template_success = 0
+        template_accuracy = 0
+
+    # Summary
+    logger.info("")
+    logger.info("=" * 60)
+    logger.info("SUMMARY")
+    logger.info("=" * 60)
+    logger.info(f"{'Method':<20} {'Time/frame':<12} {'Success':<12} {'Accuracy':<12} {'Speedup':<10}")
+    logger.info("-" * 66)
+    logger.info(f"{'Tesseract':<20} {f'{1000*tesseract_time/len(regions):.1f}ms':<12} {f'{tesseract_success}/{len(regions)}':<12} {'(baseline)':<12} {'1.00x':<10}")
+    if reader and easyocr_time > 0:
+        logger.info(f"{'EasyOCR':<20} {f'{1000*easyocr_time/len(regions):.1f}ms':<12} {f'{easyocr_success}/{len(regions)}':<12} {f'{easyocr_accuracy:.1f}%':<12} {f'{tesseract_time/easyocr_time:.2f}x':<10}")
+    if template_time > 0:
+        logger.info(f"{'Template Matching':<20} {f'{1000*template_time/len(regions):.1f}ms':<12} {f'{template_success}/{len(regions)}':<12} {f'{template_accuracy:.1f}%':<12} {f'{tesseract_time/template_time:.2f}x':<10}")
+
+
+def main():
+    """Main entry point."""
+    logger.info("OCR Benchmark Tool")
+    logger.info("=" * 60)
+
+    # Verify paths
+    if not VIDEO_PATH.exists():
+        logger.error(f"Video not found: {VIDEO_PATH}")
+        return 1
+
+    if not TEMPLATE_PATH.exists():
+        logger.error(f"Template not found: {TEMPLATE_PATH}")
+        return 1
+
+    if not CONFIG_PATH.exists():
+        logger.error(f"Config not found: {CONFIG_PATH}")
+        return 1
+
+    # Load config
+    config = load_play_clock_config()
+    logger.info(f"Play clock config: {config}")
+
+    # Initialize scorebug detector
+    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
+
+    # Extract test frames
+    logger.info(f"Extracting {len(TEST_TIMESTAMPS)} test frames...")
+    frames = extract_test_frames(VIDEO_PATH, detector, TEST_TIMESTAMPS)
+    logger.info(f"Extracted {len(frames)} frames with scorebug")
+
+    if not frames:
+        logger.error("No frames with scorebug found!")
+        return 1
+
+    # Run benchmark
+    run_benchmark(frames, config)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+

scripts/detect_plays.py

@@ -95,7 +95,8 @@ def main():
     parser.add_argument("--output", type=str, help="Output JSON file path")
 
     # Processing options
-    parser.add_argument("--interval", type=float, default=0.1, help="Frame sampling interval in seconds (default: 0.1)")
+    # Play clock only changes once per second, so 0.5s (2 fps) is sufficient and much faster
+    parser.add_argument("--interval", type=float, default=0.5, help="Frame sampling interval in seconds (default: 0.5)")
     parser.add_argument("--verbose", "-v", action="store_true", help="Enable verbose logging")
 
     args = parser.parse_args()

scripts/diagnose_play_clock.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+Diagnostic script to visualize play clock region extraction and preprocessing.
+
+This script extracts a few frames and saves debug images showing:
+1. The full frame with scorebug and play clock region highlighted
+2. The extracted play clock region (raw)
+3. The preprocessed play clock region (what OCR sees)
+
+Usage:
+    python scripts/diagnose_play_clock.py
+"""
+
+import logging
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+# Add src to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+# pylint: disable=wrong-import-position
+from detectors import ScorebugDetector, PlayClockReader
+
+logging.basicConfig(level=logging.DEBUG, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+# Constants
+VIDEO_PATH = Path(__file__).parent.parent / "full_videos" / "OSU vs Tenn 12.21.24.mkv"
+TEMPLATE_PATH = Path(__file__).parent.parent / "data" / "templates" / "scorebug_template_main.png"
+CONFIG_PATH = Path(__file__).parent.parent / "data" / "config" / "play_clock_region.json"
+OUTPUT_DIR = Path(__file__).parent.parent / "output" / "debug"
+
+# Test at 38:40 - a known segment with plays
+TEST_TIMESTAMPS = [2320.0, 2321.0, 2322.0, 2325.0, 2328.0]  # Sample timestamps in seconds
+
+
+def extract_debug_info(video_path: Path, detector: ScorebugDetector, reader: PlayClockReader, timestamps: list) -> None:
+    """
+    Extract frames and save debug visualizations.
+
+    Args:
+        video_path: Path to video file
+        detector: ScorebugDetector instance
+        reader: PlayClockReader instance
+        timestamps: List of timestamps to analyze
+    """
+    cap = cv2.VideoCapture(str(video_path))
+    if not cap.isOpened():
+        raise ValueError("Could not open video: %s" % video_path)
+
+    fps = cap.get(cv2.CAP_PROP_FPS)
+    logger.info("Video FPS: %.2f", fps)
+
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    for timestamp in timestamps:
+        # Seek to timestamp
+        frame_number = int(timestamp * fps)
+        cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
+
+        ret, frame = cap.read()
+        if not ret:
+            logger.warning("Could not read frame at %.1fs", timestamp)
+            continue
+
+        # Detect scorebug
+        detection = detector.detect(frame)
+        if not detection.detected or not detection.bbox:
+            logger.warning("No scorebug at %.1fs", timestamp)
+            continue
+
+        sb_x, sb_y, sb_w, sb_h = detection.bbox
+        logger.info("Frame %.1fs: Scorebug at (%d, %d, %d, %d) conf=%.2f", timestamp, sb_x, sb_y, sb_w, sb_h, detection.confidence)
+
+        # Get play clock config
+        config = reader.config
+        if config is None:
+            logger.error("No play clock config loaded")
+            continue
+
+        # Calculate play clock region in absolute coordinates
+        pc_x = sb_x + config.x_offset
+        pc_y = sb_y + config.y_offset
+        pc_w = config.width
+        pc_h = config.height
+        logger.info("Play clock region: (%d, %d, %d, %d)", pc_x, pc_y, pc_w, pc_h)
+
+        # Extract play clock region
+        play_clock_region = frame[pc_y : pc_y + pc_h, pc_x : pc_x + pc_w].copy()
+
+        # Preprocess for OCR (same as PlayClockReader)
+        preprocessed = preprocess_for_debug(play_clock_region)
+
+        # Run OCR and get result
+        reading = reader.read(frame, detection.bbox)
+
+        # Create debug visualization
+        debug_frame = frame.copy()
+
+        # Draw scorebug bbox (blue)
+        cv2.rectangle(debug_frame, (sb_x, sb_y), (sb_x + sb_w, sb_y + sb_h), (255, 0, 0), 2)
+        cv2.putText(debug_frame, "Scorebug", (sb_x, sb_y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 0, 0), 2)
+
+        # Draw play clock region (green if detected, red otherwise)
+        pc_color = (0, 255, 0) if reading.detected else (0, 0, 255)
+        cv2.rectangle(debug_frame, (pc_x, pc_y), (pc_x + pc_w, pc_y + pc_h), pc_color, 2)
+
+        # Add text showing OCR result
+        if reading.detected:
+            text = "Clock: %d (%.0f%%)" % (reading.value, reading.confidence * 100)
+        else:
+            text = "FAILED: '%s'" % reading.raw_text
+        cv2.putText(debug_frame, text, (pc_x, pc_y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.7, pc_color, 2)
+
+        # Save outputs
+        ts_str = "%.0f" % timestamp
+
+        # Save full debug frame
+        cv2.imwrite(str(OUTPUT_DIR / ("frame_%s_full.png" % ts_str)), debug_frame)
+
+        # Save cropped scorebug region
+        scorebug_crop = frame[sb_y : sb_y + sb_h, sb_x : sb_x + sb_w].copy()
+        cv2.imwrite(str(OUTPUT_DIR / ("frame_%s_scorebug.png" % ts_str)), scorebug_crop)
+
+        # Save play clock region (raw and scaled)
+        cv2.imwrite(str(OUTPUT_DIR / ("frame_%s_playclock_raw.png" % ts_str)), play_clock_region)
+
+        # Scale up raw for easier viewing
+        scaled_raw = cv2.resize(play_clock_region, None, fx=4, fy=4, interpolation=cv2.INTER_NEAREST)
+        cv2.imwrite(str(OUTPUT_DIR / ("frame_%s_playclock_scaled.png" % ts_str)), scaled_raw)
+
+        # Save preprocessed (what OCR sees)
+        cv2.imwrite(str(OUTPUT_DIR / ("frame_%s_playclock_preprocessed.png" % ts_str)), preprocessed)
+
+        logger.info("Saved debug images for frame %.1fs", timestamp)
+        logger.info("  OCR Result: detected=%s, value=%s, conf=%.2f, raw='%s'", reading.detected, reading.value, reading.confidence, reading.raw_text)
+
+    cap.release()
+
+
+def preprocess_for_debug(region: np.ndarray) -> np.ndarray:
+    """
+    Preprocess the play clock region for OCR (same as PlayClockReader).
+    Returns the preprocessed image for debugging.
+    """
+    # Convert to grayscale
+    gray = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
+
+    # Scale up by 4x for better OCR accuracy on small digits
+    scale_factor = 4
+    scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
+
+    # Use Otsu's thresholding - works better for high-contrast scorebug displays
+    _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+    # Determine if we need to invert (Tesseract prefers dark text on light background)
+    mean_intensity = np.mean(binary)
+    if mean_intensity < 128:
+        # Image is mostly dark (light digits on dark background) - invert for Tesseract
+        binary = cv2.bitwise_not(binary)
+
+    # Apply morphological operations to clean up noise
+    kernel = np.ones((2, 2), np.uint8)
+    binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
+    binary = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)
+
+    # Add padding
+    padding = 10
+    binary = cv2.copyMakeBorder(binary, padding, padding, padding, padding, cv2.BORDER_CONSTANT, value=255)
+
+    return binary
+
+
+def main():
+    """Main entry point for play clock diagnostic."""
+    logger.info("Play Clock Diagnostic Tool")
+    logger.info("=" * 50)
+
+    # Verify paths
+    if not VIDEO_PATH.exists():
+        logger.error("Video not found: %s", VIDEO_PATH)
+        return 1
+
+    if not TEMPLATE_PATH.exists():
+        logger.error("Template not found: %s", TEMPLATE_PATH)
+        return 1
+
+    if not CONFIG_PATH.exists():
+        logger.error("Config not found: %s", CONFIG_PATH)
+        return 1
+
+    # Initialize
+    logger.info("Initializing detectors...")
+    detector = ScorebugDetector(template_path=str(TEMPLATE_PATH))
+    reader = PlayClockReader(region_config_path=str(CONFIG_PATH))
+
+    # Run diagnostic
+    logger.info("Extracting debug info for %d timestamps...", len(TEST_TIMESTAMPS))
+    extract_debug_info(VIDEO_PATH, detector, reader, TEST_TIMESTAMPS)
+
+    logger.info("Debug images saved to: %s", OUTPUT_DIR)
+    logger.info("Diagnostic complete!")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/visualize_detections.py

@@ -271,9 +271,130 @@ def create_timeline_image(plays: List[Dict], segment_start: float, segment_end:
     logger.info("Timeline saved to: %s", output_path)
 
 
+def generate_play_clips_ffmpeg(results: Dict[str, Any], video_path: str, output_dir: str, padding: float = 2.0) -> Dict[str, float]:
+    """
+    Generate video clips for each detected play using ffmpeg (much faster than OpenCV).
+
+    Args:
+        results: Detection results
+        video_path: Path to source video
+        output_dir: Directory to save clips
+        padding: Seconds of padding before/after play
+
+    Returns:
+        Dictionary with timing information
+    """
+    import subprocess
+    import time
+
+    timing = {"clip_extraction": 0.0, "concatenation": 0.0}
+
+    plays = results.get("plays", [])
+    if not plays:
+        logger.warning("No plays to generate clips for")
+        return timing
+
+    # Create output directory
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    logger.info("Generating %d play clips with ffmpeg...", len(plays))
+    clip_paths = []
+
+    t_start = time.perf_counter()
+
+    for play in plays:
+        play_num = play.get("play_number", 0)
+        start_time = max(0, play.get("start_time", 0) - padding)
+        end_time = play.get("end_time", 0) + padding
+        duration = end_time - start_time
+
+        # Create output file
+        clip_path = output_path / ("play_%02d.mp4" % play_num)
+        clip_paths.append(clip_path)
+
+        # Use ffmpeg for fast extraction
+        # -ss before -i for fast seeking, -t for duration
+        cmd = [
+            "ffmpeg",
+            "-y",  # Overwrite output
+            "-ss",
+            str(start_time),
+            "-i",
+            video_path,
+            "-t",
+            str(duration),
+            "-c:v",
+            "libx264",  # Re-encode for compatibility
+            "-preset",
+            "fast",
+            "-crf",
+            "23",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "128k",
+            "-loglevel",
+            "error",
+            str(clip_path),
+        ]
+
+        try:
+            subprocess.run(cmd, check=True, capture_output=True)
+            logger.info("  Created: %s (%.1fs - %.1fs, duration: %.1fs)", clip_path.name, start_time, end_time, duration)
+        except subprocess.CalledProcessError as e:
+            logger.error("  Failed to create %s: %s", clip_path.name, e.stderr.decode() if e.stderr else str(e))
+
+    timing["clip_extraction"] = time.perf_counter() - t_start
+    logger.info("Clip extraction complete! (%.2fs)", timing["clip_extraction"])
+
+    # Concatenate all clips into a single highlight video
+    if len(clip_paths) > 1:
+        t_start = time.perf_counter()
+        concat_path = output_path / "all_plays.mp4"
+        logger.info("Concatenating %d clips into %s...", len(clip_paths), concat_path.name)
+
+        # Create concat file list
+        concat_list_path = output_path / "concat_list.txt"
+        with open(concat_list_path, "w") as f:
+            for clip_path in clip_paths:
+                f.write("file '%s'\n" % clip_path.name)
+
+        # Use ffmpeg concat demuxer
+        cmd = [
+            "ffmpeg",
+            "-y",
+            "-f",
+            "concat",
+            "-safe",
+            "0",
+            "-i",
+            str(concat_list_path),
+            "-c",
+            "copy",  # No re-encoding needed
+            "-loglevel",
+            "error",
+            str(concat_path),
+        ]
+
+        try:
+            subprocess.run(cmd, check=True, capture_output=True, cwd=str(output_path))
+            logger.info("  Created: %s", concat_path.name)
+        except subprocess.CalledProcessError as e:
+            logger.error("  Failed to concatenate: %s", e.stderr.decode() if e.stderr else str(e))
+
+        # Clean up concat list
+        concat_list_path.unlink(missing_ok=True)
+
+        timing["concatenation"] = time.perf_counter() - t_start
+        logger.info("Concatenation complete! (%.2fs)", timing["concatenation"])
+
+    return timing
+
+
 def generate_play_clips(results: Dict[str, Any], video_path: str, output_dir: str, padding: float = 2.0) -> None:
     """
-    Generate video clips for each detected play.
+    Generate video clips for each detected play (legacy OpenCV version - slow).
 
     Args:
         results: Detection results
@@ -351,6 +472,37 @@ def generate_play_clips(results: Dict[str, Any], video_path: str, output_dir: st
     logger.info("Clip generation complete!")
 
 
+def print_timing_summary(results: Dict[str, Any], clip_timing: Optional[Dict[str, float]] = None) -> None:
+    """Print timing breakdown from detection and clip generation."""
+    timing = results.get("timing", {})
+
+    if not timing and not clip_timing:
+        return
+
+    logger.info("")
+    logger.info("=" * 60)
+    logger.info("TIMING BREAKDOWN")
+    logger.info("=" * 60)
+
+    total_detection = 0.0
+    if timing:
+        logger.info("Detection Phase:")
+        for section, duration in timing.items():
+            logger.info("  %s: %.2fs", section, duration)
+            total_detection += duration
+        logger.info("  DETECTION TOTAL: %.2fs", total_detection)
+
+    if clip_timing:
+        logger.info("Clip Generation Phase:")
+        total_clips = 0.0
+        for section, duration in clip_timing.items():
+            logger.info("  %s: %.2fs", section, duration)
+            total_clips += duration
+        logger.info("  CLIP TOTAL: %.2fs", total_clips)
+
+    logger.info("=" * 60)
+
+
 def main():
     """Main entry point."""
     parser = argparse.ArgumentParser(description="Visualize play detection results")
@@ -359,6 +511,8 @@ def main():
     parser.add_argument("--ground-truth", type=str, help="Path to ground truth JSON file")
     parser.add_argument("--video", type=str, help="Path to video file (for clip generation)")
     parser.add_argument("--generate-clips", action="store_true", help="Generate video clips for each play")
+    parser.add_argument("--use-opencv", action="store_true", help="Use OpenCV instead of ffmpeg for clip generation (slower)")
+    parser.add_argument("--padding", type=float, default=2.0, help="Seconds of padding before/after each play (default: 2.0)")
     parser.add_argument("--output-dir", type=str, help="Output directory for visualizations")
 
     args = parser.parse_args()
@@ -396,6 +550,7 @@ def main():
     create_timeline_image(results.get("plays", []), segment.get("start", 0), segment.get("end", 0), timeline_path)
 
     # Generate clips if requested
+    clip_timing = None
     if args.generate_clips:
         video_path = args.video or str(DEFAULT_VIDEO_PATH)
         if not Path(video_path).exists():
@@ -403,7 +558,14 @@ def main():
             return 1
 
         clips_dir = str(Path(output_dir) / "clips")
-        generate_play_clips(results, video_path, clips_dir)
+
+        if args.use_opencv:
+            generate_play_clips(results, video_path, clips_dir, padding=args.padding)
+        else:
+            clip_timing = generate_play_clips_ffmpeg(results, video_path, clips_dir, padding=args.padding)
+
+    # Print timing summary
+    print_timing_summary(results, clip_timing)
 
     return 0
 

src/detectors/play_clock_reader.py

@@ -184,8 +184,9 @@ class PlayClockReader:
         Preprocessing steps:
         1. Convert to grayscale
         2. Scale up for better digit recognition
-        3. Apply adaptive thresholding
-        4. Invert if needed (Tesseract prefers dark text on light background)
+        3. Apply Otsu's thresholding (better for high-contrast scorebug displays)
+        4. Invert to get dark text on light background (Tesseract preference)
+        5. Apply morphological operations to clean up noise
 
         Args:
             region: Play clock region (BGR format)
@@ -196,23 +197,31 @@ class PlayClockReader:
         # Convert to grayscale
         gray = cv2.cvtColor(region, cv2.COLOR_BGR2GRAY)
 
-        # Scale up by 3x for better OCR accuracy on small digits
-        scale_factor = 3
-        scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_CUBIC)
+        # Scale up by 4x for better OCR accuracy on small digits
+        scale_factor = 4
+        scaled = cv2.resize(gray, None, fx=scale_factor, fy=scale_factor, interpolation=cv2.INTER_LINEAR)
 
-        # Apply Gaussian blur to reduce noise
-        blurred = cv2.GaussianBlur(scaled, (3, 3), 0)
-
-        # Apply adaptive thresholding for better handling of varying lighting
-        binary = cv2.adaptiveThreshold(blurred, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 11, 2)
+        # Use Otsu's thresholding - works better for high-contrast scorebug displays
+        # The play clock has white digits on a dark background with good contrast
+        _, binary = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
 
         # Determine if we need to invert (Tesseract prefers dark text on light background)
         # Check if the image is predominantly dark (likely light digits on dark background)
         mean_intensity = np.mean(binary)
         if mean_intensity < 128:
-            # Invert so we have dark text on light background
+            # Image is mostly dark (light digits on dark background) - invert for Tesseract
             binary = cv2.bitwise_not(binary)
 
+        # Apply morphological operations to clean up noise
+        # Use a small kernel to remove small noise while preserving digit shapes
+        kernel = np.ones((2, 2), np.uint8)
+        binary = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)  # Fill small holes
+        binary = cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel)  # Remove small noise
+
+        # Add padding around the image - helps Tesseract with edge detection
+        padding = 10
+        binary = cv2.copyMakeBorder(binary, padding, padding, padding, padding, cv2.BORDER_CONSTANT, value=255)
+
         return binary
 
     def _run_ocr(self, image: np.ndarray) -> Tuple[str, float]:

src/detectors/play_state_machine.py

@@ -50,6 +50,7 @@ class PlayStateMachine:
     Detection Strategy:
     - Play START: Detected when play clock resets to 40 (or potentially freezes - needs validation)
     - Play END: **Always use backward counting** - calculate from next observed clock value after play
+              Requires K consecutive descending clock ticks to confirm (avoids false positives)
 
     Backward Counting:
     When the play clock reappears showing value X (where X < 40), the play end time is:
@@ -62,6 +63,7 @@ class PlayStateMachine:
     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
 
     # Internal state
     state: PlayState = field(default=PlayState.IDLE)
@@ -77,6 +79,7 @@ class PlayStateMachine:
     _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
 
     def update(self, timestamp: float, scorebug: ScorebugDetection, clock: PlayClockReading) -> Optional[PlayEvent]:
         """
@@ -188,20 +191,14 @@ class PlayStateMachine:
             self._start_play(timestamp, "clock_reset", self._last_clock_value)
             return None
 
-        # Check if clock is stable (same value for multiple frames)
+        # Track clock stability (for potential future use)
         if clock_value == self._last_clock_value:
             self._clock_stable_count += 1
-            # If clock has been stable for a while and value is low, might be a freeze
-            if self._clock_stable_count >= self.clock_stable_frames and clock_value <= 5:
-                # Calculate time the clock has been at this value
-                time_at_value = timestamp - (self._last_clock_timestamp or timestamp)
-                if time_at_value > 1.0:  # More than 1 second at same low value
-                    logger.info("Play START detected at %.1fs (clock frozen at %d for %.1fs)", timestamp, clock_value, time_at_value)
-                    self._start_play(timestamp - time_at_value, "clock_freeze", clock_value)
-                    return None
         else:
             self._clock_stable_count = 1
 
+        # Note: "clock_freeze" detection disabled - was causing false positives
+        # The clock_reset detection (going to 40) is the reliable method
         return None
 
     def _handle_play_in_progress(self, timestamp: float, clock_value: int) -> Optional[PlayEvent]:
@@ -213,30 +210,52 @@ class PlayStateMachine:
         play_duration = timestamp - self._current_play_start_time
         if play_duration > self.max_play_duration:
             logger.warning("Play duration (%.1fs) exceeded max (%.1fs), forcing end", play_duration, self.max_play_duration)
-            # Use current timestamp as direct end, but will recalculate with backward counting
             self._direct_end_time = timestamp
+            self._countdown_history = []  # Reset countdown tracking
             return self._end_play(timestamp, clock_value, "direct_detect")
 
-        # If we see clock at 40, play has definitely ended
+        # 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:
-            logger.info("Play END detected at %.1fs (clock at 40)", timestamp)
-            self._direct_end_time = timestamp
-            # Calculate backward: play ended at this time since clock just reset
-            return self._end_play(timestamp, clock_value, "direct_detect")
+            # Clock is still at 40 after reset - waiting for countdown to begin
+            logger.debug("Play in progress at %.1fs, clock still at 40", timestamp)
+            self._countdown_history = []  # Reset countdown tracking
+            return None
 
-        # If we see clock ticking down normally, play has ended and we can backward calculate
-        if self._last_clock_value is not None and clock_value < self._last_clock_value:
-            # Clock is counting down - play must have ended, calculate backwards
-            # End time = current_time - (40 - clock_value)
-            calculated_end_time = timestamp - (40 - clock_value)
-            logger.info(
-                "Play END calculated via backward counting: %.1fs (clock=%d at %.1fs)",
-                calculated_end_time,
-                clock_value,
-                timestamp,
-            )
-            self._direct_end_time = None  # No direct detection
-            return self._end_play_with_backward_calc(timestamp, clock_value, calculated_end_time)
+        # Track countdown history for confirming play end
+        # We require K consecutive descending ticks to confirm
+        self._countdown_history.append((timestamp, clock_value))
+
+        # Check if we have enough consecutive descending values
+        if len(self._countdown_history) >= self.required_countdown_ticks:
+            # Get last K readings
+            recent = self._countdown_history[-self.required_countdown_ticks :]
+            values = [v for _, v in recent]
+
+            # Check if values are strictly descending (or stable which means same second)
+            is_valid_countdown = True
+            for i in range(1, len(values)):
+                # Allow same value (within same second) or descending
+                if values[i] > values[i - 1]:
+                    is_valid_countdown = False
+                    break
+
+            if is_valid_countdown:
+                # Use the first reading in our confirmed sequence for backward calculation
+                first_timestamp, first_value = recent[0]
+                calculated_end_time = first_timestamp - (40 - first_value)
+                logger.info(
+                    "Play END confirmed via %d-tick countdown: %.1fs (clock=%d→%d, observed %.1fs-%.1fs)",
+                    self.required_countdown_ticks,
+                    calculated_end_time,
+                    values[0],
+                    values[-1],
+                    recent[0][0],
+                    recent[-1][0],
+                )
+                self._direct_end_time = timestamp  # When we confirmed the countdown
+                self._countdown_history = []  # Reset for next play
+                return self._end_play_with_backward_calc(timestamp, first_value, calculated_end_time)
 
         return None
 
@@ -276,6 +295,7 @@ class PlayStateMachine:
         self._current_play_start_time = timestamp
         self._current_play_start_method = method
         self._current_play_start_clock = clock_value
+        self._countdown_history = []  # Reset countdown tracking for new play
         self.state = PlayState.PLAY_IN_PROGRESS
         logger.debug("Play started: time=%.1fs, method=%s, clock=%s", timestamp, method, clock_value)
 
@@ -351,6 +371,7 @@ class PlayStateMachine:
         self._current_play_start_clock = None
         self._direct_end_time = None
         self._clock_stable_count = 0
+        self._countdown_history = []
 
     def _reset_state(self) -> None:
         """Fully reset state machine."""

src/detectors/scorebug_detector.py

@@ -5,9 +5,11 @@ This module provides functions to detect the presence and location of the scoreb
 (score overlay) in video frames.
 """
 
+import json
 import cv2
 import numpy as np
 import logging
+from pathlib import Path
 from typing import Optional, Tuple, Dict
 from dataclasses import dataclass
 
@@ -28,28 +30,59 @@ class ScorebugDetector:
     """
     Detects the scorebug in video frames.
 
-    The detector uses multiple strategies to identify the scorebug:
-    1. Template matching
-    2. Color-based detection
-    3. Position-based heuristics
+    The detector supports two modes:
+    1. Full-frame search: Template matching across entire frame (slower, use for initial detection)
+    2. Fixed-region check: Only check known location for presence (much faster)
+
+    For optimal performance, use fixed_region mode after determining scorebug location once.
     """
 
-    def __init__(self, template_path: Optional[str] = None, expected_region: Optional[Tuple[int, int, int, int]] = None):
+    def __init__(
+        self,
+        template_path: Optional[str] = None,
+        fixed_region: Optional[Tuple[int, int, int, int]] = None,
+        fixed_region_config_path: Optional[str] = None,
+    ):
         """
         Initialize the scorebug detector.
 
         Args:
             template_path: Path to a template image of the scorebug (optional)
-            expected_region: Expected region where scorebug appears (x, y, w, h) (optional)
+            fixed_region: Fixed region where scorebug appears (x, y, w, h) - enables fast mode
+            fixed_region_config_path: Path to JSON config with fixed region (alternative to fixed_region)
         """
         self.template = None
         self.template_path = template_path
-        self.expected_region = expected_region
+        self.fixed_region = fixed_region
+        self._use_fixed_region = fixed_region is not None
 
         if template_path:
             self.load_template(template_path)
 
-        logger.info(f"ScorebugDetector initialized (template: {template_path is not None}, region: {expected_region is not None})")
+        # Load fixed region from config file if provided
+        if fixed_region_config_path and not fixed_region:
+            self._load_fixed_region_config(fixed_region_config_path)
+
+        mode = "fixed_region" if self._use_fixed_region else "full_search"
+        logger.info("ScorebugDetector initialized (template: %s, mode: %s)", template_path is not None, mode)
+        if self._use_fixed_region:
+            logger.info("  Fixed region: %s", self.fixed_region)
+
+    def _load_fixed_region_config(self, config_path: str) -> None:
+        """Load fixed region from a JSON config file."""
+        path = Path(config_path)
+        if not path.exists():
+            logger.warning("Fixed region config not found: %s", config_path)
+            return
+
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        if "scorebug_region" in data:
+            region = data["scorebug_region"]
+            self.fixed_region = (region["x"], region["y"], region["width"], region["height"])
+            self._use_fixed_region = True
+            logger.info("Loaded fixed region from config: %s", self.fixed_region)
 
     def load_template(self, template_path: str) -> None:
         """
@@ -69,29 +102,75 @@ class ScorebugDetector:
         """
         Detect scorebug in a frame.
 
+        Uses fixed-region mode if configured (much faster), otherwise searches entire frame.
+
         Args:
             frame: Input frame (BGR format)
 
         Returns:
             ScorebugDetection object with detection results
         """
-        # Only use template matching - position alone is not sufficient
-        # The scorebug is NOT present during replays/timeouts even though
-        # the position may have other graphics
+        if self.template is None:
+            logger.debug("No template loaded, cannot detect scorebug")
+            return ScorebugDetection(detected=False, confidence=0.0, method="none")
+
+        # Use fixed-region mode if configured (much faster - only checks known location)
+        if self._use_fixed_region and self.fixed_region is not None:
+            detection = self._detect_in_fixed_region(frame)
+        else:
+            # Full-frame template matching (slower, searches entire frame)
+            detection = self._detect_by_template_fullsearch(frame)
+
+        if detection.detected:
+            logger.debug("Scorebug detected with confidence %.2f using %s", detection.confidence, detection.method)
+        else:
+            logger.debug("No scorebug detected (confidence: %.2f)", detection.confidence)
+
+        return detection
+
+    def _detect_in_fixed_region(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug by checking only the fixed known location.
 
-        if self.template is not None:
-            detection = self._detect_by_template(frame)
-            if detection.detected:
-                logger.debug(f"Scorebug detected with confidence {detection.confidence:.2f} using {detection.method}")
-                return detection
+        This is MUCH faster than full-frame search since we only compare
+        the template against a single position.
 
-        # If template matching fails, scorebug is NOT present
-        logger.debug("No scorebug detected")
-        return ScorebugDetection(detected=False, confidence=0.0, method="none")
+        Args:
+            frame: Input frame
 
-    def _detect_by_template(self, frame: np.ndarray) -> ScorebugDetection:
+        Returns:
+            Detection result
         """
-        Detect scorebug using template matching.
+        x, y, w, h = self.fixed_region
+        th, tw = self.template.shape[:2]
+
+        # Validate region bounds
+        frame_h, frame_w = frame.shape[:2]
+        if x < 0 or y < 0 or x + tw > frame_w or y + th > frame_h:
+            logger.warning("Fixed region out of frame bounds")
+            return ScorebugDetection(detected=False, confidence=0.0, bbox=self.fixed_region, method="fixed_region")
+
+        # Extract the region where scorebug should be
+        region = frame[y : y + th, x : x + tw]
+
+        # Compare template to region using normalized cross-correlation
+        # This is much faster than matchTemplate on full frame since we're only comparing one location
+        result = cv2.matchTemplate(region, self.template, cv2.TM_CCOEFF_NORMED)
+        confidence = float(result[0, 0])  # Single value since region matches template size
+
+        # Use threshold to determine if scorebug is present
+        threshold = 0.8
+        if confidence >= threshold:
+            return ScorebugDetection(detected=True, confidence=confidence, bbox=(x, y, tw, th), method="fixed_region")
+        else:
+            return ScorebugDetection(detected=False, confidence=confidence, bbox=(x, y, tw, th), method="fixed_region")
+
+    def _detect_by_template_fullsearch(self, frame: np.ndarray) -> ScorebugDetection:
+        """
+        Detect scorebug using full-frame template matching.
+
+        This searches the entire frame for the template - slower but works
+        when scorebug position is unknown.
 
         Args:
             frame: Input frame
@@ -100,9 +179,9 @@ class ScorebugDetector:
             Detection result
         """
         if self.template is None:
-            return ScorebugDetection(detected=False, confidence=0.0, method="template")
+            return ScorebugDetection(detected=False, confidence=0.0, method="full_search")
 
-        # Perform template matching
+        # Perform template matching across entire frame
         result = cv2.matchTemplate(frame, self.template, cv2.TM_CCOEFF_NORMED)
         min_val, max_val, min_loc, max_loc = cv2.minMaxLoc(result)
 
@@ -115,9 +194,64 @@ class ScorebugDetector:
             h, w = self.template.shape[:2]
             bbox = (max_loc[0], max_loc[1], w, h)
 
-            return ScorebugDetection(detected=True, confidence=float(max_val), bbox=bbox, method="template")
+            return ScorebugDetection(detected=True, confidence=float(max_val), bbox=bbox, method="full_search")
+        else:
+            return ScorebugDetection(detected=False, confidence=float(max_val), method="full_search")
+
+    def set_fixed_region(self, region: Tuple[int, int, int, int]) -> None:
+        """
+        Set a fixed region for fast detection mode.
+
+        Call this after discovering the scorebug location to switch to fast mode.
+
+        Args:
+            region: (x, y, width, height) of the scorebug location
+        """
+        self.fixed_region = region
+        self._use_fixed_region = True
+        logger.info("Fixed region set: %s - now using fast detection mode", region)
+
+    def save_fixed_region_config(self, config_path: str) -> None:
+        """Save the fixed region to a config file for reuse."""
+        if self.fixed_region is None:
+            logger.warning("No fixed region to save")
+            return
+
+        x, y, w, h = self.fixed_region
+        data = {"scorebug_region": {"x": x, "y": y, "width": w, "height": h}}
+
+        path = Path(config_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        logger.info("Saved fixed region config to: %s", config_path)
+
+    def discover_and_lock_region(self, frame: np.ndarray) -> bool:
+        """
+        Discover scorebug location using full search, then lock to fixed region mode.
+
+        This is useful for the first frame - find the scorebug once, then use
+        fast fixed-region mode for all subsequent frames.
+
+        Args:
+            frame: Frame to search
+
+        Returns:
+            True if scorebug was found and region was locked, False otherwise
+        """
+        # Temporarily disable fixed region to do full search
+        old_use_fixed = self._use_fixed_region
+        self._use_fixed_region = False
+
+        detection = self._detect_by_template_fullsearch(frame)
+
+        if detection.detected and detection.bbox:
+            self.set_fixed_region(detection.bbox)
+            return True
         else:
-            return ScorebugDetection(detected=False, confidence=float(max_val), method="template")
+            self._use_fixed_region = old_use_fixed
+            return False
 
     def _detect_by_position(self, frame: np.ndarray) -> ScorebugDetection:
         """

src/pipeline/play_detector.py

@@ -10,13 +10,14 @@ This module orchestrates the complete play detection pipeline:
 
 import json
 import logging
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Optional, List, Dict, Any
 
 import cv2
 
-from ..detectors import ScorebugDetector, PlayClockReader, PlayStateMachine, PlayEvent
+from detectors import ScorebugDetector, PlayClockReader, PlayStateMachine, PlayEvent
 
 logger = logging.getLogger(__name__)
 
@@ -30,7 +31,7 @@ class DetectionConfig:
     clock_region_config_path: str  # Path to play clock region config
     start_time: float = 0.0  # Start time in seconds
     end_time: Optional[float] = None  # End time in seconds (None = full video)
-    frame_interval: float = 0.1  # Interval between frame samples (seconds)
+    frame_interval: float = 0.5  # Interval between frame samples (seconds) - 2 fps is sufficient since play clock changes once/sec
 
 
 @dataclass
@@ -45,6 +46,7 @@ class DetectionResult:
     frames_with_clock: int  # Frames where clock was read successfully
     plays: List[Dict[str, Any]] = field(default_factory=list)  # Detected plays as dicts
     stats: Dict[str, Any] = field(default_factory=dict)  # Summary statistics
+    timing: Dict[str, float] = field(default_factory=dict)  # Timing breakdown by section
 
 
 class PlayDetector:
@@ -128,16 +130,23 @@ class PlayDetector:
         start_time = self.config.start_time
         end_time = self.config.end_time if self.config.end_time else duration
 
-        # Process frames
+        # Process frames with timing tracking
         stats = {"total_frames": 0, "frames_with_scorebug": 0, "frames_with_clock": 0}
+        timing = {"scorebug_detection": 0.0, "playclock_ocr": 0.0, "state_machine": 0.0, "video_io": 0.0}
+
+        # Flag to track if we've locked the scorebug region
+        scorebug_region_locked = False
 
         current_time = start_time
         while current_time < end_time:
-            # Seek to current time
+            # Seek to current time (video I/O)
+            t_io_start = time.perf_counter()
             frame_number = int(current_time * fps)
             cap.set(cv2.CAP_PROP_POS_FRAMES, frame_number)
 
             ret, frame = cap.read()
+            timing["video_io"] += time.perf_counter() - t_io_start
+
             if not ret:
                 logger.warning("Could not read frame at %.1fs", current_time)
                 current_time += self.config.frame_interval
@@ -145,17 +154,44 @@ class PlayDetector:
 
             stats["total_frames"] += 1
 
-            # Run detection pipeline
-            self._process_frame(frame, current_time, stats)
+            # On first successful scorebug detection, lock to fixed region for speed
+            if not scorebug_region_locked:
+                t_start = time.perf_counter()
+                if self.scorebug_detector.discover_and_lock_region(frame):
+                    scorebug_region_locked = True
+                    logger.info("Scorebug region locked at %s - using fast detection mode", self.scorebug_detector.fixed_region)
+                timing["scorebug_detection"] += time.perf_counter() - t_start
+                # Still process this frame normally
+                self._process_frame(frame, current_time, stats, timing, skip_scorebug_timing=True)
+            else:
+                # Run detection pipeline with timing
+                self._process_frame(frame, current_time, stats, timing)
 
             # Progress logging every 30 seconds
             if stats["total_frames"] % int(30 / self.config.frame_interval) == 0:
-                logger.info("Progress: %.1fs / %.1fs (%.0f%%), %d plays detected", current_time, end_time, 100 * (current_time - start_time) / (end_time - start_time), len(self.state_machine.get_plays()))
+                logger.info(
+                    "Progress: %.1fs / %.1fs (%.0f%%), %d plays detected",
+                    current_time,
+                    end_time,
+                    100 * (current_time - start_time) / (end_time - start_time),
+                    len(self.state_machine.get_plays()),
+                )
 
             current_time += self.config.frame_interval
 
         cap.release()
 
+        # Log timing breakdown
+        total_time = sum(timing.values())
+        logger.info("=" * 50)
+        logger.info("TIMING BREAKDOWN")
+        logger.info("=" * 50)
+        for section, duration in timing.items():
+            pct = 100 * duration / total_time if total_time > 0 else 0
+            logger.info("  %s: %.2fs (%.1f%%)", section, duration, pct)
+        logger.info("  TOTAL: %.2fs", total_time)
+        logger.info("=" * 50)
+
         # Build result
         plays = self.state_machine.get_plays()
         play_stats = self.state_machine.get_stats()
@@ -169,6 +205,7 @@ class PlayDetector:
             frames_with_clock=stats["frames_with_clock"],
             plays=[self._play_to_dict(p) for p in plays],
             stats=play_stats,
+            timing=timing,
         )
 
         logger.info("Detection complete!")
@@ -179,7 +216,7 @@ class PlayDetector:
 
         return result
 
-    def _process_frame(self, frame, timestamp: float, stats: Dict[str, int]) -> None:
+    def _process_frame(self, frame, timestamp: float, stats: Dict[str, int], timing: Dict[str, float], skip_scorebug_timing: bool = False) -> None:
         """
         Process a single frame through the detection pipeline.
 
@@ -187,24 +224,35 @@ class PlayDetector:
             frame: Video frame (BGR)
             timestamp: Current timestamp in seconds
             stats: Statistics dictionary to update
+            timing: Timing dictionary to update
+            skip_scorebug_timing: If True, don't add to scorebug timing (already counted in region discovery)
         """
         # Detect scorebug
+        t_start = time.perf_counter()
         scorebug = self.scorebug_detector.detect(frame)
+        if not skip_scorebug_timing:
+            timing["scorebug_detection"] += time.perf_counter() - t_start
 
         if scorebug.detected:
             stats["frames_with_scorebug"] += 1
 
-            # Read play clock
+            # Read play clock (OCR - most expensive operation)
+            t_start = time.perf_counter()
             clock = self.clock_reader.read(frame, scorebug.bbox)
+            timing["playclock_ocr"] += time.perf_counter() - t_start
 
             if clock.detected:
                 stats["frames_with_clock"] += 1
         else:
-            # No scorebug - create empty clock reading
-            clock = self.clock_reader.read(frame, (0, 0, 0, 0))  # Will fail gracefully
+            # No scorebug - create empty clock reading (no OCR needed)
+            from detectors import PlayClockReading
+
+            clock = PlayClockReading(detected=False, value=None, confidence=0.0, raw_text="NO_SCOREBUG")
 
         # Update state machine
+        t_start = time.perf_counter()
         self.state_machine.update(timestamp, scorebug, clock)
+        timing["state_machine"] += time.perf_counter() - t_start
 
     def _play_to_dict(self, play: PlayEvent) -> Dict[str, Any]:
         """Convert PlayEvent to dictionary for JSON serialization."""
@@ -240,6 +288,7 @@ class PlayDetector:
                 "frames_with_scorebug": result.frames_with_scorebug,
                 "frames_with_clock": result.frames_with_clock,
             },
+            "timing": result.timing,
             "plays": result.plays,
             "stats": result.stats,
         }