documenting texas

docs/texas_ground_truth.md

@@ -0,0 +1,80 @@
+# OSU vs Texas Ground Truth - Play Detection Analysis
+
+This document tracks observations, issues, and ground truth for the Texas video analysis.
+
+## Video Details
+- **Video**: OSU vs Texas 01.10.25.mkv
+- **Note**: This video has Variable Frame Rate (VFR) encoding - see [texas_video_vfr_issue.md](texas_video_vfr_issue.md) for details
+
+---
+
+## Known Issues
+
+### 1. Opening Kickoff False Positive ⚠️
+| Issue | Details |
+|-------|---------|
+| **Real kickoff starts** | ~7:21 in video |
+| **Problem** | Strange detection of play clock before 7:21 causing false positive reading |
+| **Status** | Left unfixed - couldn't resolve without causing regression on other videos |
+| **Priority** | Low - edge case, revisit later |
+
+### 2. Variable Frame Rate Timing Issues ⚠️
+| Issue | Details |
+|-------|---------|
+| **Problem** | VFR video caused timing/padding issues |
+| **Symptom** | Padding 2 seconds before was sometimes actually 4 seconds or 6 seconds before |
+| **Impact** | Play clipping ffmpeg logic not well set up for VFR videos |
+| **Note** | 4 seconds padding before may actually be preferable to 2 seconds |
+| **TODO** | Consider changing main logic to use 4 second pre-padding instead of 2 |
+| **Documentation** | See [texas_video_vfr_issue.md](texas_video_vfr_issue.md) for technical details |
+
+### 3. FLAG Play Merge Duplication ❌
+| Issue | Details |
+|-------|---------|
+| **Problem** | Flag plays overlap with regular plays before them |
+| **Symptom** | Video shows end of regular play, then flag for a few seconds, then skips BACK in time to where FLAG first appeared |
+| **Result** | Duplicated video time present in every FLAG event |
+| **Suspected cause** | Buffer handling or merge logic issue, possibly VFR-related |
+| **Severity** | High - very bad user experience, needs investigation |
+
+### 4. Special Play Max Duration Too Long ⚠️
+| Issue | Details |
+|-------|---------|
+| **Current value** | 10 seconds max for special plays (when clock reset happens) |
+| **Recommended** | Reduce to 8 seconds |
+| **Rationale** | 10 seconds is too long for most special plays |
+
+---
+
+## Positive Results ✅
+
+- **No significant missed plays detected** - core play detection appears to be working well for this video
+
+---
+
+## TODO Items
+
+1. [ ] Investigate FLAG merge duplication issue (high priority)
+2. [ ] Reduce special play max duration from 10s to 8s
+3. [ ] Consider increasing pre-play buffer from 2s to 4s
+4. [ ] Investigate VFR handling in ffmpeg clip extraction logic
+5. [ ] Investigate opening kickoff false positive (low priority)
+
+---
+
+## Comparison with Other Videos
+
+| Metric | Tennessee | Oregon | Texas |
+|--------|-----------|--------|-------|
+| Opening kickoff | ✅ Clean | ✅ Clean | ⚠️ False positive |
+| FLAG merge | ✅ Working | ✅ Working | ❌ Duplicating |
+| VFR issues | N/A | N/A | ⚠️ Present |
+| Missed plays | ~1 acceptable | 3 missing | ✅ None significant |
+
+---
+
+## Notes for Future Analysis
+
+- This video is a good test case for VFR handling improvements
+- FLAG merge logic needs to be more robust against timestamp inconsistencies
+- The opening kickoff issue suggests the detection may be sensitive to pre-game content

scripts/test_opening_kickoff_fix.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+Test script to verify the opening kickoff detection fix.
+
+Tests:
+1. Tennessee: Opening kickoff should be detected around 117s
+2. Oregon: Opening kickoff should be detected around 332s
+3. Texas: Should REJECT the fake kickoff at 20.5s and detect real game start around 444s
+
+The fix requires:
+- k=3 consecutive clock readings to confirm kickoff start
+- Maximum kickoff duration of 90s (rejects if too long)
+"""
+
+import sys
+import logging
+from pathlib import Path
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from config import SessionConfig, load_session_config, get_video_basename, OUTPUT_DIR
+from pipeline import run_extraction
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+
+def test_video(video_name: str, video_path: str, start_time: float, end_time: float, expected_kickoff_start: float, expected_kickoff_tolerance: float = 30.0):
+    """
+    Test opening kickoff detection on a video segment.
+
+    Args:
+        video_name: Name for display
+        video_path: Path to video file
+        start_time: Start time in seconds
+        end_time: End time in seconds
+        expected_kickoff_start: Expected kickoff start time (within video segment)
+        expected_kickoff_tolerance: Tolerance for kickoff timing match
+    """
+    print(f"\n{'=' * 60}")
+    print(f"Testing: {video_name}")
+    print(f"Video: {video_path}")
+    print(f"Time range: {start_time}s - {end_time}s")
+    print(f"Expected kickoff around: {expected_kickoff_start}s (±{expected_kickoff_tolerance}s)")
+    print("=" * 60)
+
+    try:
+        # Load existing session config for this video
+        video_basename = get_video_basename(video_path, testing_mode=False)
+        config_path = OUTPUT_DIR / f"{video_basename}_config.json"
+
+        if not config_path.exists():
+            logger.error(f"Config not found: {config_path}")
+            logger.error("Run main.py with --use-saved-regions first")
+            return False
+
+        # Load config and update time bounds
+        session_config = load_session_config(str(config_path))
+        session_config.video_path = video_path
+        session_config.start_time = start_time
+        session_config.end_time = end_time
+        session_config.video_basename = video_basename
+
+        # Run extraction
+        results = run_extraction(session_config, OUTPUT_DIR, num_workers=1)
+
+        # Analyze results - plays are dicts, not objects
+        plays = results.get("plays", [])
+        kickoff_plays = [p for p in plays if p.get("play_type") == "kickoff"]
+
+        print(f"\nResults:")
+        print(f"  Total plays detected: {len(plays)}")
+        print(f"  Kickoff plays: {len(kickoff_plays)}")
+
+        success = True
+        if kickoff_plays:
+            for kp in kickoff_plays:
+                start = kp.get("start_time", 0)
+                end = kp.get("end_time", 0)
+                print(f"\n  Kickoff found:")
+                print(f"    Start: {start:.1f}s")
+                print(f"    End: {end:.1f}s")
+                print(f"    Duration: {end - start:.1f}s")
+
+                # Check if within expected range
+                diff = abs(start - expected_kickoff_start)
+                if diff <= expected_kickoff_tolerance:
+                    print(f"    ✅ PASS: Within expected range ({diff:.1f}s from expected)")
+                else:
+                    print(f"    ❌ FAIL: Outside expected range ({diff:.1f}s from expected)")
+                    success = False
+        else:
+            print(f"\n  ❌ No kickoff detected!")
+            success = False
+
+        # Show first few plays for context
+        print(f"\nFirst 5 plays:")
+        for p in plays[:5]:
+            pnum = p.get("play_number", "?")
+            pstart = p.get("start_time", 0)
+            pend = p.get("end_time", 0)
+            ptype = p.get("play_type", "?")
+            pmethod = p.get("start_method", "?")
+            print(f"  Play #{pnum}: {pstart:.1f}s - {pend:.1f}s ({ptype}, {pmethod})")
+
+        return success
+
+    except Exception as e:
+        logger.error(f"Error testing {video_name}: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def main():
+    """Run all tests."""
+    base_path = Path("/Users/andytaylor/Documents/Personal/cfb40/full_videos")
+
+    # Test configurations
+    tests = [
+        {
+            "video_name": "Tennessee (baseline - should pass)",
+            "video_path": str(base_path / "OSU vs Tenn 12.21.24.mkv"),
+            "start_time": 0,
+            "end_time": 300,  # First 5 minutes
+            "expected_kickoff_start": 117,  # ~1:57 video time
+            "expected_kickoff_tolerance": 30,
+        },
+        {
+            "video_name": "Oregon (baseline - should pass)",
+            "video_path": str(base_path / "OSU vs Oregon 01.01.25.mkv"),
+            "start_time": 200,
+            "end_time": 500,  # Around kickoff time
+            "expected_kickoff_start": 332,  # ~5:32 video time
+            "expected_kickoff_tolerance": 30,
+        },
+        {
+            "video_name": "Texas (fix test - should reject fake kickoff at 20s)",
+            "video_path": str(base_path / "OSU vs Texas 01.10.25.mkv"),
+            "start_time": 0,
+            "end_time": 600,  # First 10 minutes
+            "expected_kickoff_start": 444,  # Real game starts ~7:24
+            "expected_kickoff_tolerance": 30,
+        },
+    ]
+
+    print("\n" + "=" * 60)
+    print("OPENING KICKOFF DETECTION FIX TEST")
+    print("=" * 60)
+
+    results = []
+    for test_config in tests:
+        success = test_video(**test_config)
+        results.append((test_config["video_name"], success))
+
+    # Summary
+    print("\n" + "=" * 60)
+    print("TEST SUMMARY")
+    print("=" * 60)
+    for name, success in results:
+        status = "✅ PASS" if success else "❌ FAIL"
+        print(f"  {status}: {name}")
+
+
+if __name__ == "__main__":
+    main()

src/tracking/models.py

@@ -113,6 +113,10 @@ class TrackPlayStateConfig(BaseModel):
     flag_extension_timeout: float = Field(15.0, description="Max seconds to extend play capture after FLAG first detected")
     capture_flag_plays: bool = Field(True, description="Whether to capture plays with FLAGS (bypasses quiet time filter)")
 
+    # Opening kickoff detection settings
+    opening_kickoff_min_consecutive_frames: int = Field(3, description="Required consecutive frames with valid clock readings to confirm kickoff start")
+    max_opening_kickoff_duration: float = Field(90.0, description="Maximum valid kickoff duration (seconds). If exceeded, reject and keep searching.")
+
 
 class TimeoutInfo(BaseModel):
     """Timeout information for a frame."""
@@ -214,10 +218,13 @@ class NormalTrackerState(BaseModel):
     # Opening kickoff tracking
     # The opening kickoff is special because the scorebug appears mid-play
     # We detect it when scorebug first appears and end it on first clock reset to 40
+    # Requires k consecutive valid clock readings to confirm kickoff (filters out pre-game noise)
     opening_kickoff_active: bool = Field(False, description="Whether we're currently tracking the opening kickoff")
     opening_kickoff_complete: bool = Field(False, description="Whether opening kickoff has been recorded (only happens once)")
     first_scorebug_timestamp: Optional[float] = Field(None, description="When scorebug first appeared in the video (verified by template matching)")
     first_clock_reading_timestamp: Optional[float] = Field(None, description="When we first got a valid clock reading")
+    opening_kickoff_consecutive_readings: int = Field(0, description="Count of consecutive frames with valid clock readings for kickoff detection")
+    opening_kickoff_candidate_timestamp: Optional[float] = Field(None, description="Timestamp when consecutive clock readings started (candidate kickoff start)")
 
 
 class SpecialTrackerState(BaseModel):

src/tracking/normal_play_tracker.py

@@ -127,18 +127,16 @@ class NormalPlayTracker:
         completed_play = None
 
         if self._state.state == PlayState.IDLE:
-            # First clock reading - this is likely the opening kickoff
-            logger.info("First clock reading (%d) at %.1fs, entering PRE_SNAP", clock_value, timestamp)
+            # First clock reading - track consecutive readings before confirming kickoff
+            # This filters out isolated clock readings during pre-game content
             self._state.state = PlayState.PRE_SNAP
             self._state.last_clock_value = clock_value
             self._state.last_clock_timestamp = timestamp
             self._state.clock_stable_count = 1
-            self._state.first_clock_reading_timestamp = timestamp
 
-            # Start the opening kickoff if not already complete
-            # The opening kickoff starts when we first see the scorebug with a clock reading
+            # Track consecutive readings for opening kickoff detection
             if not self._state.opening_kickoff_complete:
-                self._start_opening_kickoff(timestamp)
+                self._track_opening_kickoff_reading(timestamp, clock_value)
 
         elif self._state.state == PlayState.PRE_SNAP:
             # Watching for play to start (may return completed opening kickoff play)
@@ -171,6 +169,14 @@ class NormalPlayTracker:
         if self._state.state == PlayState.IDLE:
             return None
 
+        # Reset consecutive reading count for opening kickoff detection
+        # No scorebug means no clock reading - breaks the chain
+        if not self._state.opening_kickoff_complete and not self._state.opening_kickoff_active:
+            if self._state.opening_kickoff_consecutive_readings > 0:
+                logger.debug("Opening kickoff: consecutive clock readings reset (no scorebug at %.1fs)", timestamp)
+                self._state.opening_kickoff_consecutive_readings = 0
+                self._state.opening_kickoff_candidate_timestamp = None
+
         # Check if we've lost scorebug for too long
         if self._state.last_scorebug_timestamp is not None:
             time_since_scorebug = timestamp - self._state.last_scorebug_timestamp
@@ -208,8 +214,20 @@ class NormalPlayTracker:
         if self._state.state == PlayState.PRE_SNAP and self._state.last_clock_value is not None:
             logger.debug("Clock unreadable at %.1fs in PRE_SNAP state", timestamp)
 
+        # Reset consecutive reading count for opening kickoff detection
+        # Invalid clock breaks the chain of valid readings
+        if not self._state.opening_kickoff_complete and not self._state.opening_kickoff_active:
+            if self._state.opening_kickoff_consecutive_readings > 0:
+                logger.debug("Opening kickoff: consecutive clock readings reset (invalid clock at %.1fs)", timestamp)
+                self._state.opening_kickoff_consecutive_readings = 0
+                self._state.opening_kickoff_candidate_timestamp = None
+
     def _handle_pre_snap(self, timestamp: float, clock_value: int, timeout_info: Optional[TimeoutInfo] = None) -> Optional[PlayEvent]:
         """Handle clock reading during PRE_SNAP state. May return completed opening kickoff play."""
+        # Track consecutive clock readings for opening kickoff detection
+        if not self._state.opening_kickoff_complete and not self._state.opening_kickoff_active:
+            self._track_opening_kickoff_reading(timestamp, clock_value)
+
         if self._state.last_clock_value is None:
             self._state.last_clock_value = clock_value
             self._state.clock_stable_count = 1
@@ -690,6 +708,15 @@ class NormalPlayTracker:
             self._state.state = PlayState.PRE_SNAP
             return None
 
+        # Mark opening kickoff as complete when first play finishes
+        # This prevents detecting a "kickoff" after the game has started
+        if not self._state.opening_kickoff_complete:
+            logger.debug("First play completed - marking opening kickoff tracking as complete")
+            self._state.opening_kickoff_complete = True
+            self._state.opening_kickoff_active = False
+            self._state.opening_kickoff_consecutive_readings = 0
+            self._state.opening_kickoff_candidate_timestamp = None
+
         self._play_count += 1
 
         play = PlayEvent(
@@ -718,6 +745,15 @@ class NormalPlayTracker:
 
     def _end_play_capped(self, capped_end_time: float, clock_value: int, method: str) -> PlayEvent:
         """End the current play with a capped end time."""
+        # Mark opening kickoff as complete when first play finishes
+        # This prevents detecting a "kickoff" after the game has started
+        if not self._state.opening_kickoff_complete:
+            logger.debug("First play completed (capped) - marking opening kickoff tracking as complete")
+            self._state.opening_kickoff_complete = True
+            self._state.opening_kickoff_active = False
+            self._state.opening_kickoff_consecutive_readings = 0
+            self._state.opening_kickoff_candidate_timestamp = None
+
         self._play_count += 1
 
         play = PlayEvent(
@@ -762,52 +798,85 @@ class NormalPlayTracker:
     # Opening kickoff handling
     # =========================================================================
 
+    def _track_opening_kickoff_reading(self, timestamp: float, clock_value: int) -> None:
+        """
+        Track consecutive clock readings to confirm opening kickoff start.
+
+        Requires k consecutive valid clock readings before starting kickoff tracking.
+        This filters out isolated/sporadic clock readings during pre-game content.
+
+        Args:
+            timestamp: Current video timestamp
+            clock_value: Current play clock value
+        """
+        # Increment consecutive reading count
+        self._state.opening_kickoff_consecutive_readings += 1
+
+        # Record candidate start timestamp on first reading
+        if self._state.opening_kickoff_candidate_timestamp is None:
+            self._state.opening_kickoff_candidate_timestamp = timestamp
+            logger.debug("Opening kickoff: candidate start at %.1fs (clock=%d), tracking consecutive readings...", timestamp, clock_value)
+
+        # Check if we have enough consecutive readings to confirm kickoff
+        required_frames = self.config.opening_kickoff_min_consecutive_frames
+        if self._state.opening_kickoff_consecutive_readings >= required_frames:
+            logger.info(
+                "Opening kickoff: %d consecutive clock readings confirmed (started at %.1fs)",
+                self._state.opening_kickoff_consecutive_readings,
+                self._state.opening_kickoff_candidate_timestamp,
+            )
+            # Start tracking the opening kickoff using the candidate timestamp
+            self._start_opening_kickoff(self._state.opening_kickoff_candidate_timestamp)
+        else:
+            logger.debug(
+                "Opening kickoff: %d/%d consecutive readings (started at %.1fs)",
+                self._state.opening_kickoff_consecutive_readings,
+                required_frames,
+                self._state.opening_kickoff_candidate_timestamp,
+            )
+
     def _start_opening_kickoff(self, timestamp: float) -> None:
         """
         Start tracking the opening kickoff.
 
-        Called when we get the first clock reading in the video. The opening kickoff
-        is special because the scorebug appears mid-play (during the kickoff).
-
-        The opening kickoff ends when we see the first clock reset to 40 from a lower
-        value, OR when the first countdown confirmation happens. This handles both:
-        - Tennessee: Clock shows 40, stays at 40, then counts down (no reset before first play)
-        - Oregon: Clock counts down during kickoff, resets to 25, then 40
+        Called when we get k consecutive valid clock readings (confirmed kickoff).
+        The opening kickoff is special because the scorebug appears mid-play.
 
         Args:
-            timestamp: When first clock reading was seen
+            timestamp: When kickoff tracking should start (first of k consecutive readings)
         """
         self._state.opening_kickoff_active = True
-        # Don't set current_play_start_time yet - we'll use a different mechanism
-        # The kickoff tracking is separate from normal play tracking
-        logger.info("Opening kickoff tracking started at %.1fs (first clock reading)", timestamp)
+        self._state.first_clock_reading_timestamp = timestamp
+        logger.info("Opening kickoff tracking started at %.1fs (%d consecutive clock readings)", timestamp, self.config.opening_kickoff_min_consecutive_frames)
 
-    def _end_opening_kickoff(self, timestamp: float) -> PlayEvent:
+    def _end_opening_kickoff(self, timestamp: float) -> Optional[PlayEvent]:
         """
         End the opening kickoff and create the play event.
 
         Called when the first normal play starts (clock reset to 40 or countdown from 40).
         The kickoff spans from when we first got a clock reading until this moment.
 
+        Note: Kickoff plays that are too long will be filtered out by PlayMerger
+        using max_kickoff_duration filter.
+
         Args:
             timestamp: When the first normal play is starting
 
         Returns:
             PlayEvent for the opening kickoff
         """
-        self._play_count += 1
-
         # Kickoff starts when we first got a clock reading
         start_time = self._state.first_clock_reading_timestamp or timestamp
 
         # Kickoff ends just before the first normal play starts
-        # Use a small buffer to avoid overlap
         kickoff_end_time = timestamp - 0.5
 
         # Ensure end time is after start time with reasonable duration
         if kickoff_end_time <= start_time:
             kickoff_end_time = start_time + 2.0  # Minimum 2 second duration for kickoffs
 
+        self._play_count += 1
+
         play = PlayEvent(
             play_number=self._play_count,
             start_time=start_time,
@@ -934,6 +1003,9 @@ class NormalPlayTracker:
         self._reset_freeze_tracking()
         # Reset opening kickoff active flag (but NOT complete - that's permanent)
         self._state.opening_kickoff_active = False
+        # Reset consecutive reading tracking (but NOT complete)
+        self._state.opening_kickoff_consecutive_readings = 0
+        self._state.opening_kickoff_candidate_timestamp = None
         logger.debug("State machine reset to IDLE")
 
     # =========================================================================

src/tracking/play_merger.py

@@ -37,16 +37,19 @@ class PlayMerger:  # pylint: disable=too-few-public-methods
     - Adjusted to avoid overlap with previous play's end time (prevents duplicate footage)
     """
 
-    def __init__(self, proximity_threshold: float = 5.0, quiet_time: float = 10.0):
+    def __init__(self, proximity_threshold: float = 5.0, quiet_time: float = 10.0, max_kickoff_duration: float = 60.0):
         """
         Initialize the play merger.
 
         Args:
             proximity_threshold: Plays within this time (seconds) are considered the same event
             quiet_time: Seconds after normal play ends before special/timeout plays are allowed
+            max_kickoff_duration: Maximum duration (seconds) for kickoff plays. Longer ones are
+                                  filtered as false positives (e.g., pre-game content)
         """
         self.proximity_threshold = proximity_threshold
         self.quiet_time = quiet_time
+        self.max_kickoff_duration = max_kickoff_duration
 
     def merge(self, *play_lists: List[PlayEvent]) -> List[PlayEvent]:
         """
@@ -74,6 +77,7 @@ class PlayMerger:  # pylint: disable=too-few-public-methods
         # Process non-FLAG plays (deduplicate and filter)
         other_plays.sort(key=lambda p: p.start_time)
         if other_plays:
+            other_plays = self._filter_invalid_kickoffs(other_plays)
             other_plays = self._deduplicate(other_plays)
             other_plays = self._apply_quiet_time_filter(other_plays)
 
@@ -95,6 +99,42 @@ class PlayMerger:  # pylint: disable=too-few-public-methods
 
         return all_plays
 
+    def _filter_invalid_kickoffs(self, plays: List[PlayEvent]) -> List[PlayEvent]:
+        """
+        Filter out kickoff plays that exceed max_kickoff_duration.
+
+        Kickoff plays that are too long are likely false positives from pre-game
+        content where the scorebug is visible but actual gameplay hasn't started.
+
+        Args:
+            plays: List of plays sorted by start time
+
+        Returns:
+            Filtered list with invalid kickoffs removed
+        """
+        filtered = []
+        removed_count = 0
+
+        for play in plays:
+            if play.play_type == "kickoff":
+                duration = play.end_time - play.start_time
+                if duration > self.max_kickoff_duration:
+                    logger.warning(
+                        "Filtering invalid kickoff: %.1fs - %.1fs (duration %.1fs exceeds max %.1fs)",
+                        play.start_time,
+                        play.end_time,
+                        duration,
+                        self.max_kickoff_duration,
+                    )
+                    removed_count += 1
+                    continue
+            filtered.append(play)
+
+        if removed_count > 0:
+            logger.info("Kickoff filter removed %d plays exceeding %.1fs duration", removed_count, self.max_kickoff_duration)
+
+        return filtered
+
     def _deduplicate(self, plays: List[PlayEvent]) -> List[PlayEvent]:
         """
         Remove overlapping and close plays, keeping the highest priority one.

src/tracking/play_tracker.py

@@ -294,6 +294,9 @@ class PlayTracker:
         is completed, ensuring the opening kickoff is captured even if special plays
         are created before normal play detection kicks in.
 
+        Note: Kickoff plays that are too long will be filtered out by PlayMerger
+        using max_kickoff_duration filter.
+
         Args:
             first_play_start: Start time of the first detected play