clarifying detect meaning

main.py

@@ -58,7 +58,7 @@ from ui import (
 )
 from ui.api import extract_sample_frames_for_selection
 from video import generate_clips
-from pipeline import run_detection, print_results_summary
+from pipeline import run_extraction, print_results_summary
 
 logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -368,19 +368,19 @@ def _print_region_summary(config: SessionConfig) -> None:
 # =============================================================================
 
 
-def _phase3_detection(session_config: SessionConfig, num_workers: int) -> Dict[str, Any]:
+def _phase3_extraction(session_config: SessionConfig, num_workers: int) -> Dict[str, Any]:
     """
-    Phase 3: Run play detection on the video.
+    Phase 3: Run play extraction on the video.
 
     Args:
         session_config: Configuration with video path and regions.
         num_workers: Number of parallel workers.
 
     Returns:
-        Detection results dictionary.
+        Extraction results dictionary.
     """
     print("\n" + "=" * 60)
-    return run_detection(session_config, OUTPUT_DIR, num_workers=num_workers)
+    return run_extraction(session_config, OUTPUT_DIR, num_workers=num_workers)
 
 
 # =============================================================================
@@ -492,8 +492,8 @@ def main() -> int:
     if session_config is None:
         return 1
 
-    # Phase 3: Detection
-    results = _phase3_detection(session_config, args.parallel)
+    # Phase 3: Extraction
+    results = _phase3_extraction(session_config, args.parallel)
 
     # Phase 4: Clip Generation
     clip_timing = {}

src/pipeline/__init__.py

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

src/pipeline/orchestrator.py

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

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

@@ -1,11 +1,12 @@
 """
-Play detector pipeline module.
+Play extractor pipeline module.
 
-This module orchestrates the complete play detection pipeline:
+This module orchestrates the complete play extraction pipeline:
 1. Video frame extraction
 2. Scorebug detection
 3. Play clock reading via template matching
 4. Play state machine processing
+5. Post-hoc clock reset identification (timeout/special plays)
 
 Performance optimizations:
 - Streaming processing: read frame -> process immediately (no intermediate storage)
@@ -28,7 +29,7 @@ import numpy as np
 from detection import DetectScoreBug, ScorebugDetection, DetectTimeouts
 from readers import ReadPlayClock, PlayClockReading
 from setup import DigitTemplateBuilder, DigitTemplateLibrary, PlayClockRegionConfig, PlayClockRegionExtractor
-from tracking import TrackPlayState, PlayEvent, PlayMerger, TimeoutInfo
+from tracking import TrackPlayState, PlayEvent, PlayMerger, TimeoutInfo, ClockResetIdentifier
 from utils import create_frame_result
 from video import ThreadedFrameReader
 from .models import DetectionConfig, DetectionResult, ParallelProcessingConfig, VideoContext
@@ -38,7 +39,7 @@ from .template_builder_pass import TemplateBuildingPass
 logger = logging.getLogger(__name__)
 
 
-def format_detection_result_dict(result: DetectionResult) -> Dict[str, Any]:
+def format_extraction_result_dict(result: DetectionResult) -> Dict[str, Any]:
     """
     Format a DetectionResult into a dictionary for JSON serialization or API return.
 
@@ -62,20 +63,21 @@ def format_detection_result_dict(result: DetectionResult) -> Dict[str, Any]:
     }
 
 
-class PlayDetector:
+class PlayExtractor:
     """
-    Main pipeline for detecting plays in video.
+    Main pipeline for extracting plays from video.
 
-    This class orchestrates all detection components:
+    This class orchestrates all extraction components:
     - DetectScoreBug: Locates scorebug in frames
     - ReadPlayClock: Reads play clock digits via template matching
     - TrackPlayState: Determines play boundaries
     - DetectTimeouts: Tracks timeout indicators for 3-class clock reset classification
+    - ClockResetIdentifier: Post-hoc identification of timeout/special plays
     """
 
     def __init__(self, config: DetectionConfig, timeout_tracker: Optional[DetectTimeouts] = None):
         """
-        Initialize the play detector pipeline.
+        Initialize the play extractor pipeline.
 
         Args:
             config: Detection configuration
@@ -111,11 +113,11 @@ class PlayDetector:
                 raise FileNotFoundError(f"Clock region config not found: {self.config.clock_region_config_path}")
 
     def _initialize_components(self) -> None:
-        """Initialize detection components."""
-        logger.info("Initializing play detector components...")
+        """Initialize extraction components."""
+        logger.info("Initializing play extractor components...")
 
         # Determine if we're using fixed coordinates mode
-        # In this mode, we still use the same detection logic but with pre-set regions
+        # In this mode, we still use the same logic but with pre-set regions
         use_fixed_coords = self.config.fixed_playclock_coords is not None
 
         if use_fixed_coords:
@@ -176,7 +178,7 @@ class PlayDetector:
                 self.template_reader = ReadPlayClock(self.template_library, region_w, region_h)
             else:
                 self.template_library = None
-                logger.info("Could not load templates, will build during detection")
+                logger.info("Could not load templates, will build during extraction")
 
         # Initialize template builder for collection phase if no templates loaded
         if self.template_library is None:
@@ -262,9 +264,9 @@ class PlayDetector:
 
         return self.template_library is not None
 
-    def _streaming_detection_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
+    def _streaming_extraction_pass(self, context: VideoContext, stats: Dict[str, Any], timing: Dict[str, float]) -> List[Dict[str, Any]]:
         """
-        Streaming detection pass: Read frames, process immediately, no intermediate storage.
+        Streaming extraction pass: Read frames, process immediately, no intermediate storage.
 
         This combines the old Pass 1 (frame extraction) and Pass 2 (template matching) into
         a single streaming pass. Each frame is:
@@ -284,7 +286,7 @@ class PlayDetector:
         Returns:
             List of frame data dictionaries with all processing results
         """
-        logger.info("Streaming detection pass: frame extraction + template matching...")
+        logger.info("Streaming extraction pass: frame extraction + template matching...")
 
         logger.info(
             "Threaded reading: frame_skip=%d (%.2f fps effective), frames %d-%d",
@@ -337,7 +339,7 @@ class PlayDetector:
                 # Progress logging
                 if stats["total_frames"] % progress_interval == 0:
                     progress_pct = 100 * (current_time - context.start_time) / (context.end_time - context.start_time)
-                    logger.info("Detection progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
+                    logger.info("Extraction progress: %.1fs / %.1fs (%.0f%%)", current_time, context.end_time, progress_pct)
 
         finally:
             # Stop the reader thread and get I/O timing
@@ -346,7 +348,7 @@ class PlayDetector:
             context.cap.release()
 
         logger.info(
-            "Streaming detection complete: %d frames processed, %d with scorebug, %d with clock",
+            "Streaming extraction complete: %d frames processed, %d with scorebug, %d with clock",
             stats["total_frames"],
             stats["frames_with_scorebug"],
             stats["frames_with_clock"],
@@ -446,7 +448,7 @@ class PlayDetector:
 
         return frame_result
 
-    def _finalize_detection(
+    def _finalize_extraction(
         self,
         context: VideoContext,
         stats: Dict[str, Any],
@@ -454,9 +456,9 @@ class PlayDetector:
         frame_data: List[Dict[str, Any]],
     ) -> DetectionResult:
         """
-        Finalize detection: run post-hoc clock reset detection and build result.
+        Finalize extraction: run post-hoc clock reset identification and build result.
 
-        Performs 3-class classification for 40→25 clock reset events:
+        Uses ClockResetIdentifier for 3-class classification of 40→25 clock reset events:
         - Class A (weird_clock): 25 counts down immediately → rejected
         - Class B (timeout): Timeout indicator changed → tracked as timeout
         - Class C (special): Neither A nor B → special play (punt/FG/XP)
@@ -477,10 +479,11 @@ class PlayDetector:
         state_machine_plays = self.state_machine.get_plays()
         play_stats = self.state_machine.get_stats()
 
-        # Run post-hoc clock reset detection (40→25 transitions)
-        clock_reset_plays, clock_reset_stats = self._detect_clock_resets(frame_data)
+        # Run post-hoc clock reset identification (40→25 transitions)
+        clock_reset_identifier = ClockResetIdentifier()
+        clock_reset_plays, clock_reset_stats = clock_reset_identifier.identify(frame_data)
         logger.info(
-            "Clock reset detection: %d total, %d weird (rejected), %d timeouts, %d special plays",
+            "Clock reset identification: %d total, %d weird (rejected), %d timeouts, %d special plays",
             clock_reset_stats.get("total", 0),
             clock_reset_stats.get("weird_clock", 0),
             clock_reset_stats.get("timeout", 0),
@@ -490,8 +493,9 @@ class PlayDetector:
         # Merge clock reset stats into play stats
         play_stats["clock_reset_events"] = clock_reset_stats
 
-        # Merge state machine plays with clock reset plays (handles deduplication)
-        plays = self._merge_plays(state_machine_plays, clock_reset_plays)
+        # Merge state machine plays with clock reset plays using PlayMerger
+        merger = PlayMerger()
+        plays = merger.merge(state_machine_plays, clock_reset_plays)
 
         # Recalculate stats from merged plays
         start_methods: Dict[str, int] = {}
@@ -520,16 +524,16 @@ class PlayDetector:
         )
 
         # Log final summary
-        logger.info("Detection complete!")
+        logger.info("Extraction complete!")
         logger.info("Processed %d frames", stats["total_frames"])
         logger.info("Frames with scorebug: %d (%.1f%%)", stats["frames_with_scorebug"], 100 * stats["frames_with_scorebug"] / max(1, stats["total_frames"]))
         logger.info("Frames with clock: %d (%.1f%%)", stats["frames_with_clock"], 100 * stats["frames_with_clock"] / max(1, stats["total_frames"]))
-        logger.info("Plays detected: %d", len(plays))
+        logger.info("Plays extracted: %d", len(plays))
 
         return result
 
     def _log_timing_breakdown(self, timing: Dict[str, float]) -> None:
-        """Log the timing breakdown for the detection run."""
+        """Log the timing breakdown for the extraction run."""
         total_time = sum(timing.values())
         logger.info("=" * 50)
         logger.info("TIMING BREAKDOWN")
@@ -540,304 +544,23 @@ class PlayDetector:
         logger.info("  TOTAL: %.2fs", total_time)
         logger.info("=" * 50)
 
-    # =========================================================================
-    # Clock Reset Detection (Post-hoc 40→25 analysis)
-    # =========================================================================
-
-    def _detect_clock_resets(self, frame_data: List[Dict[str, Any]]) -> Tuple[List[PlayEvent], Dict[str, int]]:
-        """
-        Detect and classify 40 -> 25 clock reset events.
-
-        Classification:
-        - Class A (weird_clock): 25 counts down immediately -> rejected
-        - Class B (timeout): Timeout indicator changed -> tracked as timeout
-        - Class C (special): Neither A nor B -> special play with extension
-
-        Args:
-            frame_data: List of frame data with clock values and timeout counts
-
-        Returns:
-            Tuple of (list of PlayEvent for valid clock resets, stats dict)
-        """
-        plays = []
-        stats = {"total": 0, "weird_clock": 0, "timeout": 0, "special": 0}
-
-        # Parameters
-        immediate_countdown_window = 2.0  # Seconds to check if 25 counts down
-        special_play_extension = 10.0  # Extension for Class C plays
-
-        prev_clock = None
-        saw_40_at = None
-
-        for i, frame in enumerate(frame_data):
-            clock_value = frame.get("clock_value")
-            timestamp = frame["timestamp"]
-
-            if clock_value is not None:
-                # Detect 40 -> 25 transition
-                if prev_clock == 40 and clock_value == 25:
-                    stats["total"] += 1
-
-                    # Check if 25 immediately counts down (Class A: weird clock)
-                    is_immediate_countdown = self._check_immediate_countdown(frame_data, i, immediate_countdown_window)
-
-                    # Check if timeout changed (Class B: team timeout)
-                    timeout_team = self._check_timeout_change(frame_data, i)
-
-                    if is_immediate_countdown:
-                        # Class A: Weird clock behavior - reject
-                        stats["weird_clock"] += 1
-                        logger.debug("Clock reset at %.1fs: weird_clock (25 counts down immediately)", timestamp)
-                    elif timeout_team:
-                        # Class B: Team timeout - record but mark as timeout
-                        stats["timeout"] += 1
-                        play_end = self._find_clock_reset_play_end(frame_data, i, max_duration=15.0)
-                        play = PlayEvent(
-                            play_number=0,
-                            start_time=timestamp,
-                            end_time=play_end,
-                            confidence=0.8,
-                            start_method=f"timeout_{timeout_team}",
-                            end_method="timeout_end",
-                            direct_end_time=play_end,
-                            start_clock_value=prev_clock,
-                            end_clock_value=25,
-                            play_type="timeout",
-                        )
-                        plays.append(play)
-                        logger.debug("Clock reset at %.1fs: timeout (%s team)", timestamp, timeout_team)
-                    else:
-                        # Class C: Special play (injury/punt/FG/XP)
-                        stats["special"] += 1
-                        play_end = self._find_clock_reset_play_end(frame_data, i, max_duration=special_play_extension)
-                        play_duration = play_end - timestamp
-                        end_method = "max_duration" if play_duration >= special_play_extension - 0.1 else "scorebug_disappeared"
-                        play = PlayEvent(
-                            play_number=0,
-                            start_time=timestamp,
-                            end_time=play_end,
-                            confidence=0.8,
-                            start_method="clock_reset_special",
-                            end_method=end_method,
-                            direct_end_time=play_end,
-                            start_clock_value=prev_clock,
-                            end_clock_value=25,
-                            play_type="special",
-                        )
-                        plays.append(play)
-                        logger.debug("Clock reset at %.1fs: special play (%.1fs duration)", timestamp, play_end - timestamp)
-
-                # Track when 40 first appeared
-                if clock_value == 40 and prev_clock != 40:
-                    saw_40_at = timestamp
-
-                prev_clock = clock_value
-
-        return plays, stats
-
-    def _check_immediate_countdown(self, frame_data: List[Dict[str, Any]], frame_idx: int, window: float) -> bool:
-        """Check if 25 immediately starts counting down (indicates weird clock behavior)."""
-        reset_timestamp = frame_data[frame_idx]["timestamp"]
-
-        for j in range(frame_idx + 1, len(frame_data)):
-            frame = frame_data[j]
-            elapsed = frame["timestamp"] - reset_timestamp
-            if elapsed > window:
-                break
-            clock_value = frame.get("clock_value")
-            if clock_value is not None and clock_value < 25:
-                return True  # 25 counted down - weird clock
-
-        return False
-
-    def _check_timeout_change(self, frame_data: List[Dict[str, Any]], frame_idx: int) -> Optional[str]:
-        """Check if a timeout indicator changed around the reset."""
-        # Get timeout counts before reset
-        before_home = None
-        before_away = None
-
-        for j in range(frame_idx - 1, max(0, frame_idx - 20), -1):
-            frame = frame_data[j]
-            if frame.get("home_timeouts") is not None:
-                before_home = frame.get("home_timeouts", 3)
-                before_away = frame.get("away_timeouts", 3)
-                break
-
-        if before_home is None:
-            return None
-
-        # Look forward for timeout change (up to 15 seconds)
-        frame_interval = frame_data[1]["timestamp"] - frame_data[0]["timestamp"] if len(frame_data) > 1 else 0.5
-        max_frames_forward = int(15.0 / frame_interval) if frame_interval > 0 else 30
-
-        for j in range(frame_idx, min(len(frame_data), frame_idx + max_frames_forward)):
-            frame = frame_data[j]
-            if frame.get("home_timeouts") is not None:
-                after_home = frame.get("home_timeouts", 3)
-                after_away = frame.get("away_timeouts", 3)
-
-                if after_home < before_home:
-                    return "home"
-                if after_away < before_away:
-                    return "away"
-
-        return None
-
-    def _find_clock_reset_play_end(self, frame_data: List[Dict[str, Any]], frame_idx: int, max_duration: float) -> float:
-        """
-        Find the end time for a clock reset play (Class C special play).
-
-        The play ends when EITHER:
-        - Scorebug disappears (cut to commercial/replay)
-        - max_duration seconds have elapsed since play START
-
-        Args:
-            frame_data: Frame data list
-            frame_idx: Index of the frame where 40->25 reset occurred
-            max_duration: Maximum play duration from start
-
-        Returns:
-            Play end timestamp
-        """
-        start_timestamp: float = frame_data[frame_idx]["timestamp"]
-        max_end_time = start_timestamp + max_duration
-
-        # Look for scorebug disappearance (but cap at max_duration from start)
-        for j in range(frame_idx + 1, len(frame_data)):
-            frame = frame_data[j]
-            timestamp: float = frame["timestamp"]
-
-            # If we've exceeded max_duration, end the play at max_duration
-            if timestamp >= max_end_time:
-                return max_end_time
-
-            # Check for play clock disappearance
-            clock_available = frame.get("clock_detected", frame.get("scorebug_detected", False))
-            if not clock_available:
-                return timestamp
-
-        # Default: end at max_duration (or end of data if shorter)
-        return min(max_end_time, float(frame_data[-1]["timestamp"]) if frame_data else max_end_time)
-
-    def _merge_plays(self, state_machine_plays: List[PlayEvent], clock_reset_plays: List[PlayEvent]) -> List[PlayEvent]:
-        """
-        Merge plays from state machine and clock reset detection, removing overlaps and duplicates.
-
-        Handles two types of duplicates:
-        1. Overlapping plays (start_time < last.end_time)
-        2. Close plays (start times within proximity_threshold) representing the same event
-
-        Args:
-            state_machine_plays: Plays from the state machine
-            clock_reset_plays: Plays from clock reset detection
-
-        Returns:
-            Merged list of plays sorted by start time
-        """
-        all_plays = list(state_machine_plays) + list(clock_reset_plays)
-        all_plays.sort(key=lambda p: p.start_time)
-
-        if not all_plays:
-            return []
-
-        # Proximity threshold: plays within this time are considered the same event
-        proximity_threshold = 5.0  # seconds
-
-        # Remove overlapping and close plays (keep state machine plays over clock reset plays)
-        filtered = [all_plays[0]]
-        for play in all_plays[1:]:
-            last = filtered[-1]
-
-            # Check for overlap OR proximity (both indicate same event)
-            is_overlapping = play.start_time < last.end_time
-            is_close = abs(play.start_time - last.start_time) < proximity_threshold
-
-            if is_overlapping or is_close:
-                # Same event detected twice - keep the better one
-                # Priority: normal > special > timeout (normal plays are most reliable)
-                type_priority = {"normal": 3, "special": 2, "timeout": 1}
-                last_priority = type_priority.get(last.play_type, 0)
-                play_priority = type_priority.get(play.play_type, 0)
-
-                if play_priority > last_priority:
-                    filtered[-1] = play  # Replace with higher priority play
-                elif play_priority == last_priority and play.confidence > last.confidence:
-                    filtered[-1] = play  # Same priority, but higher confidence
-                # else: keep existing
-            else:
-                filtered.append(play)
-
-        # Apply quiet time filter to remove false positives after normal plays
-        filtered = self._apply_quiet_time_filter(filtered)
-
-        # Renumber plays
-        for i, play in enumerate(filtered, 1):
-            play.play_number = i
-
-        return filtered
-
-    def _apply_quiet_time_filter(self, plays: List[PlayEvent], quiet_time: float = 10.0) -> List[PlayEvent]:
-        """
-        Apply quiet time filter after normal plays.
-
-        After a normal play ends, no new special/timeout plays can start for quiet_time seconds.
-        This filters out false positives from penalties during plays.
-
-        Args:
-            plays: List of plays sorted by start time
-            quiet_time: Seconds of quiet time after normal plays
-
-        Returns:
-            Filtered list of plays
-        """
-        if not plays:
-            return []
-
-        filtered = []
-        last_normal_end = -999.0  # Track when last normal play ended
-
-        for play in plays:
-            # Check if this play starts during quiet time after a normal play
-            if play.start_time < last_normal_end + quiet_time and play.play_type != "normal":
-                # This non-normal play starts during quiet time - filter it out
-                time_since_normal = play.start_time - last_normal_end
-                logger.debug(
-                    "Quiet time filter: Removing %s play at %.1fs (%.1fs after normal play ended)",
-                    play.play_type,
-                    play.start_time,
-                    time_since_normal,
-                )
-                continue
-
-            filtered.append(play)
-
-            # Update last normal play end time
-            if play.play_type == "normal":
-                last_normal_end = play.end_time
-
-        removed_count = len(plays) - len(filtered)
-        if removed_count > 0:
-            logger.info("Quiet time filter removed %d plays", removed_count)
-
-        return filtered
-
-    def detect(self) -> DetectionResult:
+    def extract(self) -> DetectionResult:
         """
-        Run play detection on the video segment.
+        Run play extraction on the video segment.
 
         Uses streaming processing for optimal performance:
         - Pass 0 (if needed): Build digit templates using OCR on scorebug-verified frames
         - Streaming pass: Read frame -> extract region -> template match -> state machine update
           (threaded video I/O overlaps reading with processing)
-        - Finalize: Clock reset classification and result building
+        - Finalize: Clock reset identification and result building
 
         When fixed coordinates are provided, the scorebug detection step simply verifies
         the scorebug is present at the known location (faster than searching).
 
         Returns:
-            DetectionResult with all detected plays
+            DetectionResult with all extracted plays
         """
-        logger.info("Starting play detection...")
+        logger.info("Starting play extraction...")
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
 
@@ -858,26 +581,26 @@ class PlayDetector:
         if not self.template_reader and self.template_builder:
             success = self._pass0_build_templates_with_real_detection(timing)
             if not success:
-                logger.warning("Pass 0 failed to build templates, detection may fail or be inaccurate")
+                logger.warning("Pass 0 failed to build templates, extraction may fail or be inaccurate")
 
         # Log mode info (after Pass 0 so we can show if templates were built)
-        self._log_detection_mode()
+        self._log_extraction_mode()
 
         # Initialize video and get processing context
         context, stats, _ = self._open_video_and_get_context()
 
-        # Streaming detection pass: read frames + template match + state machine (all in one)
+        # Streaming extraction pass: read frames + template match + state machine (all in one)
         # Uses threaded video I/O to overlap reading with processing
-        # Returns frame_data needed for post-hoc clock reset detection
-        frame_data = self._streaming_detection_pass(context, stats, timing)
+        # Returns frame_data needed for post-hoc clock reset identification
+        frame_data = self._streaming_extraction_pass(context, stats, timing)
 
-        # Finalize: Post-hoc clock reset classification (Class A/B/C) and result building
-        return self._finalize_detection(context, stats, timing, frame_data)
+        # Finalize: Post-hoc clock reset identification (Class A/B/C) and result building
+        return self._finalize_extraction(context, stats, timing, frame_data)
 
     # pylint: disable=too-many-locals
-    def detect_parallel(self, num_workers: int = 2, output_dir: Optional[Path] = None) -> DetectionResult:
+    def extract_parallel(self, num_workers: int = 2, output_dir: Optional[Path] = None) -> DetectionResult:
         """
-        Run play detection using parallel chunk processing.
+        Run play extraction using parallel chunk processing.
 
         This provides ~26% speedup over sequential processing by using multiple
         processes to read and process different segments of the video simultaneously.
@@ -887,16 +610,16 @@ class PlayDetector:
         2. Save templates to disk for worker processes to load
         3. Parallel pass: Each worker processes a video chunk independently
         4. Merge: Combine frame data from all chunks in chronological order
-        5. State machine: Process merged data to detect plays
+        5. State machine: Process merged data to extract plays
 
         Args:
             num_workers: Number of parallel workers (default 2).
             output_dir: Output directory for templates (required).
 
         Returns:
-            DetectionResult with all detected plays
+            DetectionResult with all extracted plays
         """
-        logger.info("Starting parallel play detection (%d workers)...", num_workers)
+        logger.info("Starting parallel play extraction (%d workers)...", num_workers)
         logger.info("Video: %s", self.config.video_path)
         logger.info("Segment: %.1fs to %s", self.config.start_time, self.config.end_time or "end")
 
@@ -914,7 +637,7 @@ class PlayDetector:
         if not self.template_reader and self.template_builder:
             success = self._pass0_build_templates_with_real_detection(timing)
             if not success:
-                logger.warning("Pass 0 failed to build templates, detection may fail or be inaccurate")
+                logger.warning("Pass 0 failed to build templates, extraction may fail or be inaccurate")
 
         # Save templates to disk for worker processes
         template_path = None
@@ -1012,11 +735,11 @@ class PlayDetector:
             "frames_with_clock": stats["frames_with_clock"],
         }
 
-        # Finalize: Post-hoc clock reset classification (Class A/B/C) and result building
-        return self._finalize_detection(context, stats_dict, timing, frame_data)
+        # Finalize: Post-hoc clock reset identification (Class A/B/C) and result building
+        return self._finalize_extraction(context, stats_dict, timing, frame_data)
 
-    def _log_detection_mode(self) -> None:
-        """Log the detection mode being used."""
+    def _log_extraction_mode(self) -> None:
+        """Log the extraction mode being used."""
         use_fixed_region = self.scorebug_detector and self.scorebug_detector.is_fixed_region_mode
 
         if use_fixed_region:
@@ -1050,16 +773,16 @@ class PlayDetector:
 
     def save_results(self, result: DetectionResult, output_path: str) -> None:
         """
-        Save detection results to a JSON file.
+        Save extraction results to a JSON file.
 
         Args:
-            result: Detection results
+            result: Extraction results
             output_path: Path to output file
         """
         output = Path(output_path)
         output.parent.mkdir(parents=True, exist_ok=True)
 
-        data = format_detection_result_dict(result)
+        data = format_extraction_result_dict(result)
 
         # Include configuration if provided (for reproducibility)
         if result.config:

src/tracking/__init__.py

@@ -7,6 +7,7 @@ to detect play boundaries and other temporal events.
 from .models import PlayEvent, PlayState, PlayTrackingState, TrackPlayStateConfig, TimeoutInfo, ClockResetStats
 from .play_state import TrackPlayState
 from .play_merger import PlayMerger
+from .clock_reset_identifier import ClockResetIdentifier
 
 __all__ = [
     # Models
@@ -20,4 +21,6 @@ __all__ = [
     "TrackPlayState",
     # Merger
     "PlayMerger",
+    # Clock reset identification
+    "ClockResetIdentifier",
 ]

src/tracking/clock_reset_identifier.py

@@ -0,0 +1,243 @@
+"""
+Clock reset identifier module for post-hoc 40→25 transition analysis.
+
+This module identifies and classifies 40→25 play clock reset events by analyzing
+frame data after the initial extraction pass. It complements the real-time
+TrackPlayState by catching timeout and special plays that the state machine
+may miss or classify differently.
+
+Classification (Class A/B/C):
+- Class A (weird_clock): 25 counts down immediately → rejected (false positive)
+- Class B (timeout): Timeout indicator changed → tracked as timeout play
+- Class C (special): Neither A nor B → special play (punt/FG/XP/injury)
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+from .models import PlayEvent
+
+logger = logging.getLogger(__name__)
+
+
+class ClockResetIdentifier:
+    """
+    Identifies and classifies 40→25 clock reset events from frame data.
+
+    This performs post-hoc analysis on extracted frame data to find timeout
+    and special plays by looking for 40→25 clock transitions and classifying
+    them based on subsequent behavior and timeout indicator changes.
+    """
+
+    def __init__(
+        self,
+        immediate_countdown_window: float = 2.0,
+        special_play_extension: float = 10.0,
+        timeout_max_duration: float = 15.0,
+    ):
+        """
+        Initialize the clock reset identifier.
+
+        Args:
+            immediate_countdown_window: Seconds to check if 25 counts down (Class A filter)
+            special_play_extension: Max duration for special plays (Class C)
+            timeout_max_duration: Max duration for timeout plays (Class B)
+        """
+        self.immediate_countdown_window = immediate_countdown_window
+        self.special_play_extension = special_play_extension
+        self.timeout_max_duration = timeout_max_duration
+
+    def identify(self, frame_data: List[Dict[str, Any]]) -> Tuple[List[PlayEvent], Dict[str, int]]:
+        """
+        Identify and classify 40→25 clock reset events in frame data.
+
+        Scans through frame_data looking for 40→25 transitions and classifies each:
+        - Class A (weird_clock): 25 counts down immediately → rejected
+        - Class B (timeout): Timeout indicator changed → timeout play
+        - Class C (special): Neither A nor B → special play
+
+        Args:
+            frame_data: List of frame data dicts with clock_value, timestamp,
+                       home_timeouts, away_timeouts, etc.
+
+        Returns:
+            Tuple of (list of PlayEvent for valid clock resets, stats dict)
+        """
+        plays: List[PlayEvent] = []
+        stats = {"total": 0, "weird_clock": 0, "timeout": 0, "special": 0}
+
+        prev_clock: Optional[int] = None
+
+        for i, frame in enumerate(frame_data):
+            clock_value = frame.get("clock_value")
+            timestamp: float = frame["timestamp"]
+
+            if clock_value is not None:
+                # Identify 40 → 25 transition
+                if prev_clock == 40 and clock_value == 25:
+                    stats["total"] += 1
+
+                    # Check Class A: 25 immediately counts down (weird clock behavior)
+                    is_immediate_countdown = self._check_immediate_countdown(frame_data, i)
+
+                    # Check Class B: timeout indicator changed
+                    timeout_team = self._check_timeout_change(frame_data, i)
+
+                    if is_immediate_countdown:
+                        # Class A: Weird clock behavior - reject
+                        stats["weird_clock"] += 1
+                        logger.debug("Clock reset at %.1fs: weird_clock (25 counts down immediately)", timestamp)
+
+                    elif timeout_team:
+                        # Class B: Team timeout
+                        stats["timeout"] += 1
+                        play_end = self._find_play_end(frame_data, i, max_duration=self.timeout_max_duration)
+                        play = PlayEvent(
+                            play_number=0,
+                            start_time=timestamp,
+                            end_time=play_end,
+                            confidence=0.8,
+                            start_method=f"timeout_{timeout_team}",
+                            end_method="timeout_end",
+                            direct_end_time=play_end,
+                            start_clock_value=prev_clock,
+                            end_clock_value=25,
+                            play_type="timeout",
+                        )
+                        plays.append(play)
+                        logger.debug("Clock reset at %.1fs: timeout (%s team)", timestamp, timeout_team)
+
+                    else:
+                        # Class C: Special play (punt/FG/XP/injury)
+                        stats["special"] += 1
+                        play_end = self._find_play_end(frame_data, i, max_duration=self.special_play_extension)
+                        play_duration = play_end - timestamp
+                        end_method = "max_duration" if play_duration >= self.special_play_extension - 0.1 else "scorebug_disappeared"
+                        play = PlayEvent(
+                            play_number=0,
+                            start_time=timestamp,
+                            end_time=play_end,
+                            confidence=0.8,
+                            start_method="clock_reset_special",
+                            end_method=end_method,
+                            direct_end_time=play_end,
+                            start_clock_value=prev_clock,
+                            end_clock_value=25,
+                            play_type="special",
+                        )
+                        plays.append(play)
+                        logger.debug("Clock reset at %.1fs: special play (%.1fs duration)", timestamp, play_end - timestamp)
+
+                prev_clock = clock_value
+
+        return plays, stats
+
+    def _check_immediate_countdown(self, frame_data: List[Dict[str, Any]], frame_idx: int) -> bool:
+        """
+        Check if 25 immediately starts counting down (Class A filter).
+
+        If the clock shows a value < 25 within the countdown window after
+        the reset, this indicates weird clock behavior (false positive).
+
+        Args:
+            frame_data: Frame data list
+            frame_idx: Index of frame where 40→25 reset occurred
+
+        Returns:
+            True if 25 counts down immediately (Class A), False otherwise
+        """
+        reset_timestamp: float = frame_data[frame_idx]["timestamp"]
+
+        for j in range(frame_idx + 1, len(frame_data)):
+            frame = frame_data[j]
+            elapsed = frame["timestamp"] - reset_timestamp
+            if elapsed > self.immediate_countdown_window:
+                break
+            clock_value = frame.get("clock_value")
+            if clock_value is not None and clock_value < 25:
+                return True  # 25 counted down - weird clock
+
+        return False
+
+    def _check_timeout_change(self, frame_data: List[Dict[str, Any]], frame_idx: int) -> Optional[str]:
+        """
+        Check if a timeout indicator changed around the reset (Class B check).
+
+        Compares timeout counts before and after the reset to determine
+        if a team timeout was called.
+
+        Args:
+            frame_data: Frame data list
+            frame_idx: Index of frame where 40→25 reset occurred
+
+        Returns:
+            "home" or "away" if timeout was used, None otherwise
+        """
+        # Get timeout counts before reset (look back up to 20 frames)
+        before_home: Optional[int] = None
+        before_away: Optional[int] = None
+
+        for j in range(frame_idx - 1, max(0, frame_idx - 20), -1):
+            frame = frame_data[j]
+            if frame.get("home_timeouts") is not None:
+                before_home = frame.get("home_timeouts", 3)
+                before_away = frame.get("away_timeouts", 3)
+                break
+
+        if before_home is None:
+            return None
+
+        # Look forward for timeout change (up to 15 seconds)
+        frame_interval = frame_data[1]["timestamp"] - frame_data[0]["timestamp"] if len(frame_data) > 1 else 0.5
+        max_frames_forward = int(15.0 / frame_interval) if frame_interval > 0 else 30
+
+        for j in range(frame_idx, min(len(frame_data), frame_idx + max_frames_forward)):
+            frame = frame_data[j]
+            if frame.get("home_timeouts") is not None:
+                after_home = frame.get("home_timeouts", 3)
+                after_away = frame.get("away_timeouts", 3)
+
+                if after_home < before_home:
+                    return "home"
+                if after_away < before_away:
+                    return "away"
+
+        return None
+
+    def _find_play_end(self, frame_data: List[Dict[str, Any]], frame_idx: int, max_duration: float) -> float:
+        """
+        Find the end time for a clock reset play.
+
+        The play ends when EITHER:
+        - Scorebug/clock disappears (cut to commercial/replay)
+        - max_duration seconds have elapsed since the reset
+
+        Whichever comes first.
+
+        Args:
+            frame_data: Frame data list
+            frame_idx: Index of frame where 40→25 reset occurred
+            max_duration: Maximum play duration from reset
+
+        Returns:
+            Play end timestamp
+        """
+        start_timestamp: float = frame_data[frame_idx]["timestamp"]
+        max_end_time = start_timestamp + max_duration
+
+        # Look for scorebug disappearance (but cap at max_duration)
+        for j in range(frame_idx + 1, len(frame_data)):
+            frame = frame_data[j]
+            timestamp: float = frame["timestamp"]
+
+            # If we've exceeded max_duration, end at max_duration
+            if timestamp >= max_end_time:
+                return max_end_time
+
+            # Check for clock/scorebug disappearance
+            clock_available = frame.get("clock_detected", frame.get("scorebug_detected", False))
+            if not clock_available:
+                return timestamp
+
+        # Default: end at max_duration (or end of data if shorter)
+        return min(max_end_time, float(frame_data[-1]["timestamp"]) if frame_data else max_end_time)