Add multi-ball candidate detection and tracking

- detect_all_balls(): Detect multiple balls in first frame with ROI filtering
- _track_single_ball_candidate(): Track each candidate using proximity matching
- _detect_and_track_all_ball_candidates(): Score candidates by kick detection, velocity, position
- _build_multi_ball_chart(): Combined speed chart comparing all candidates
- _apply_selected_ball_to_yolo_state(): Copy selected candidate to main YOLO state
- Updated _auto_detect_ball to detect multiple candidates
- Updated _track_ball_yolo to use multi-ball tracking when multiple candidates found
- Added ball_candidates, selected_ball_idx, ball_selection_confirmed to AppState
- Added multi-ball selection UI components (radio buttons, chart, confirm button)

app.py

@@ -132,6 +132,96 @@ def detect_ball_center(
     )
 
 
+def detect_all_balls(
+    frame: Image.Image,
+    model_filename: str = YOLO_DEFAULT_MODEL,
+    conf_threshold: float = 0.1,  # Lower threshold to catch more candidates
+    iou_threshold: float = YOLO_IOU_THRESHOLD,
+    max_detections: int = 5,
+    roi_x_min: float = 0.20,  # Filter: ball must be within 20-80% horizontal
+    roi_x_max: float = 0.80,
+) -> list[dict]:
+    """
+    Detect all ball candidates in a frame, filtered by ROI.
+    
+    Returns list of dicts with keys:
+        - id: int (candidate index)
+        - center: (x, y) tuple
+        - box: (x_min, y_min, x_max, y_max) tuple
+        - width: float
+        - height: float
+        - conf: float (YOLO confidence)
+        - x_ratio: float (horizontal position as fraction of frame width)
+    """
+    model = get_yolo_model(model_filename)
+    class_ids = [
+        idx for idx, name in model.names.items() if name.lower() == YOLO_TARGET_NAME
+    ]
+    if not class_ids:
+        return []
+
+    results = model.predict(
+        source=frame,
+        conf=conf_threshold,
+        iou=iou_threshold,
+        max_det=max_detections,
+        classes=class_ids,
+        imgsz=640,
+        device="cpu",
+        verbose=False,
+    )
+
+    if not results:
+        return []
+
+    boxes = results[0].boxes
+    if boxes is None or len(boxes) == 0:
+        return []
+
+    frame_width, frame_height = frame.size
+    candidates = []
+
+    for i, box in enumerate(boxes):
+        xywh = box.xywh[0].cpu().tolist()
+        conf = float(box.conf[0].cpu().item()) if box.conf is not None else 0.0
+        x_center, y_center, width, height = xywh
+        
+        # Compute bounding box
+        x_min = int(round(max(0.0, x_center - width / 2.0)))
+        y_min = int(round(max(0.0, y_center - height / 2.0)))
+        x_max = int(round(min(frame_width - 1.0, x_center + width / 2.0)))
+        y_max = int(round(min(frame_height - 1.0, y_center + height / 2.0)))
+        
+        if x_max <= x_min or y_max <= y_min:
+            continue
+        
+        # Compute horizontal position ratio
+        x_ratio = x_center / frame_width
+        
+        # Filter by ROI (horizontal position)
+        if not (roi_x_min <= x_ratio <= roi_x_max):
+            continue
+        
+        candidates.append({
+            "id": len(candidates),
+            "center": (float(x_center), float(y_center)),
+            "box": (x_min, y_min, x_max, y_max),
+            "width": float(width),
+            "height": float(height),
+            "conf": conf,
+            "x_ratio": x_ratio,
+        })
+
+    # Sort by confidence descending
+    candidates.sort(key=lambda c: c["conf"], reverse=True)
+    
+    # Re-assign IDs after sorting
+    for i, c in enumerate(candidates):
+        c["id"] = i
+
+    return candidates
+
+
 def detect_person_box(
     frame: Image.Image,
     model_filename: str = YOLO_DEFAULT_MODEL,
@@ -683,6 +773,347 @@ def _perform_yolo_ball_tracking(state: AppState, progress: gr.Progress | None =
         state.sam_window = None
 
 
+def _track_single_ball_candidate(
+    state: AppState,
+    candidate: dict,
+    progress: gr.Progress | None = None,
+) -> dict:
+    """
+    Track a single ball candidate across all frames using YOLO.
+    Uses proximity matching to follow the same ball.
+    
+    Returns dict with tracking results:
+        - centers: dict[frame_idx, (x, y)]
+        - speeds: dict[frame_idx, speed]
+        - kick_frame: int | None
+        - max_velocity: float
+        - has_kick: bool
+        - coverage: float (fraction of frames with detection)
+    """
+    model = get_yolo_model()
+    class_ids = [
+        idx for idx, name in model.names.items() if name.lower() == YOLO_TARGET_NAME
+    ]
+    
+    frames = state.video_frames
+    total = len(frames)
+    
+    # Initial position from candidate
+    last_center = candidate["center"]
+    max_distance_threshold = 100  # Max pixels to consider same ball
+    
+    centers: dict[int, tuple[float, float]] = {}
+    boxes: dict[int, tuple[int, int, int, int]] = {}
+    confs: dict[int, float] = {}
+    areas: dict[int, float] = {}
+    
+    for idx, frame in enumerate(frames):
+        if progress is not None:
+            progress((idx + 1) / total)
+        
+        results = model.predict(
+            source=frame,
+            conf=0.05,  # Lower threshold to catch more
+            iou=YOLO_IOU_THRESHOLD,
+            max_det=10,  # Allow multiple detections
+            classes=class_ids,
+            imgsz=640,
+            device="cpu",
+            verbose=False,
+        )
+        
+        if not results:
+            continue
+        
+        boxes_result = results[0].boxes
+        if boxes_result is None or len(boxes_result) == 0:
+            continue
+        
+        # Find the detection closest to last known position
+        best_box = None
+        best_distance = float("inf")
+        
+        for box in boxes_result:
+            xywh = box.xywh[0].cpu().tolist()
+            x_center, y_center = xywh[0], xywh[1]
+            dist = math.hypot(x_center - last_center[0], y_center - last_center[1])
+            
+            if dist < best_distance and dist < max_distance_threshold:
+                best_distance = dist
+                best_box = box
+        
+        if best_box is None:
+            continue
+        
+        xywh = best_box.xywh[0].cpu().tolist()
+        conf = float(best_box.conf[0].cpu().item()) if best_box.conf is not None else 0.0
+        x_center, y_center, width, height = xywh
+        x_center = float(x_center)
+        y_center = float(y_center)
+        width = max(1.0, float(width))
+        height = max(1.0, float(height))
+        
+        frame_width, frame_height = frame.size
+        x_min = int(round(max(0.0, x_center - width / 2.0)))
+        y_min = int(round(max(0.0, y_center - height / 2.0)))
+        x_max = int(round(min(frame_width - 1.0, x_center + width / 2.0)))
+        y_max = int(round(min(frame_height - 1.0, y_center + height / 2.0)))
+        
+        if x_max <= x_min or y_max <= y_min:
+            continue
+        
+        centers[idx] = (x_center, y_center)
+        boxes[idx] = (x_min, y_min, x_max, y_max)
+        confs[idx] = conf
+        areas[idx] = float((x_max - x_min) * (y_max - y_min))
+        last_center = (x_center, y_center)
+    
+    # Compute speeds
+    if len(centers) < 3:
+        return {
+            "centers": centers,
+            "boxes": boxes,
+            "confs": confs,
+            "areas": areas,
+            "speeds": {},
+            "smoothed_centers": {},
+            "frames_ordered": [],
+            "speed_series": [],
+            "kick_frame": None,
+            "max_velocity": 0.0,
+            "has_kick": False,
+            "coverage": len(centers) / total if total else 0.0,
+        }
+    
+    items = sorted(centers.items())
+    dt = 1.0 / state.video_fps if state.video_fps and state.video_fps > 1e-3 else 1.0
+    alpha = 0.35
+    
+    smoothed: dict[int, tuple[float, float]] = {}
+    speeds: dict[int, float] = {}
+    
+    prev_frame = None
+    prev_smooth = None
+    for frame_idx, (cx, cy) in items:
+        if prev_smooth is None:
+            smooth_x, smooth_y = float(cx), float(cy)
+        else:
+            smooth_x = prev_smooth[0] + alpha * (cx - prev_smooth[0])
+            smooth_y = prev_smooth[1] + alpha * (cy - prev_smooth[1])
+        smoothed[frame_idx] = (smooth_x, smooth_y)
+        if prev_smooth is None or prev_frame is None:
+            speeds[frame_idx] = 0.0
+        else:
+            frame_delta = max(1, frame_idx - prev_frame)
+            time_delta = frame_delta * dt
+            dist = math.hypot(smooth_x - prev_smooth[0], smooth_y - prev_smooth[1])
+            speed = dist / time_delta if time_delta > 0 else dist
+            speeds[frame_idx] = speed
+        prev_smooth = (smooth_x, smooth_y)
+        prev_frame = frame_idx
+    
+    frames_ordered = [frame_idx for frame_idx, _ in items]
+    speed_series = [speeds.get(f, 0.0) for f in frames_ordered]
+    
+    # Detect kick (velocity spike)
+    baseline_window = min(10, len(frames_ordered) // 3 or 1)
+    baseline_speeds = speed_series[:baseline_window]
+    baseline_speed = statistics.median(baseline_speeds) if baseline_speeds else 0.0
+    speed_std = statistics.pstdev(baseline_speeds) if len(baseline_speeds) > 1 else 0.0
+    base_threshold = baseline_speed + 4.0 * speed_std
+    if base_threshold < baseline_speed * 3.0:
+        base_threshold = baseline_speed * 3.0
+    speed_threshold = max(base_threshold, 15.0)
+    
+    kick_frame: int | None = None
+    max_velocity = max(speed_series) if speed_series else 0.0
+    
+    for idx, frame in enumerate(frames_ordered[baseline_window:], start=baseline_window):
+        speed = speed_series[idx]
+        if speed < speed_threshold:
+            continue
+        # Check sustain
+        sustain_ok = True
+        for j in range(1, 4):
+            if idx + j >= len(frames_ordered):
+                break
+            if speed_series[idx + j] < speed_threshold * 0.7:
+                sustain_ok = False
+                break
+        if sustain_ok:
+            kick_frame = frame
+            break
+    
+    return {
+        "centers": centers,
+        "boxes": boxes,
+        "confs": confs,
+        "areas": areas,
+        "speeds": speeds,
+        "smoothed_centers": smoothed,
+        "frames_ordered": frames_ordered,
+        "speed_series": speed_series,
+        "threshold": speed_threshold,
+        "baseline": baseline_speed,
+        "kick_frame": kick_frame,
+        "max_velocity": max_velocity,
+        "has_kick": kick_frame is not None,
+        "coverage": len(centers) / total if total else 0.0,
+    }
+
+
+def _detect_and_track_all_ball_candidates(
+    state: AppState,
+    progress: gr.Progress | None = None,
+) -> None:
+    """
+    Detect all ball candidates in first frame, track each with YOLO,
+    score them, and auto-select the best candidate.
+    """
+    if state is None or state.num_frames == 0:
+        raise gr.Error("Load a video first.")
+    
+    first_frame = state.video_frames[0]
+    frame_width, frame_height = first_frame.size
+    
+    # Step 1: Detect all balls in first frame
+    candidates = detect_all_balls(first_frame)
+    
+    if not candidates:
+        state.ball_candidates = []
+        state.multi_ball_status = "❌ No ball candidates detected in first frame."
+        return
+    
+    state.multi_ball_status = f"🔍 Found {len(candidates)} ball candidate(s). Tracking..."
+    
+    # Step 2: Track each candidate
+    tracking_results: dict[int, dict] = {}
+    
+    for i, candidate in enumerate(candidates):
+        if progress is not None:
+            progress((i + 1) / len(candidates), desc=f"Tracking ball {i+1}/{len(candidates)}")
+        
+        result = _track_single_ball_candidate(state, candidate, progress=None)
+        tracking_results[candidate["id"]] = result
+        
+        # Add tracking summary to candidate
+        candidate["tracking"] = result
+        candidate["has_kick"] = result["has_kick"]
+        candidate["kick_frame"] = result["kick_frame"]
+        candidate["max_velocity"] = result["max_velocity"]
+        candidate["coverage"] = result["coverage"]
+    
+    # Step 3: Score candidates
+    frame_center_x = frame_width / 2
+    
+    for candidate in candidates:
+        score = 0.0
+        
+        # 1. Has a detected kick (velocity spike) — most important
+        if candidate["has_kick"]:
+            score += 50
+        
+        # 2. Higher max velocity — ball that moves most
+        score += min(30, candidate["max_velocity"] / 10)
+        
+        # 3. Centered horizontally
+        x_offset = abs(candidate["center"][0] - frame_center_x) / frame_center_x
+        score += 20 * (1 - x_offset)
+        
+        # 4. YOLO confidence as tiebreaker
+        score += candidate["conf"] * 10
+        
+        # 5. Better coverage
+        score += candidate["coverage"] * 10
+        
+        candidate["score"] = score
+    
+    # Sort by score descending
+    candidates.sort(key=lambda c: c["score"], reverse=True)
+    
+    # Re-assign IDs after sorting
+    for i, c in enumerate(candidates):
+        c["id"] = i
+    
+    state.ball_candidates = candidates
+    state.ball_candidates_tracking = tracking_results
+    state.selected_ball_idx = 0  # Auto-select best candidate
+    state.ball_selection_confirmed = False
+    
+    # Build status message
+    if len(candidates) == 1:
+        c = candidates[0]
+        kick_info = f"Kick @ frame {c['kick_frame']}" if c["has_kick"] else "No kick detected"
+        state.multi_ball_status = f"✅ 1 ball detected. {kick_info}."
+    else:
+        kicked_count = sum(1 for c in candidates if c["has_kick"])
+        state.multi_ball_status = (
+            f"⚠️ {len(candidates)} balls detected. "
+            f"{kicked_count} show movement. "
+            f"Best candidate auto-selected. Please confirm or change selection."
+        )
+
+
+def _apply_selected_ball_to_yolo_state(state: AppState) -> None:
+    """
+    Copy the selected ball candidate's tracking data to the main YOLO state.
+    This allows the rest of the pipeline to work unchanged.
+    """
+    if not state.ball_candidates:
+        return
+    
+    idx = state.selected_ball_idx
+    if idx < 0 or idx >= len(state.ball_candidates):
+        idx = 0
+    
+    candidate = state.ball_candidates[idx]
+    tracking = candidate.get("tracking", {})
+    
+    # Copy to main YOLO state
+    state.yolo_ball_centers = tracking.get("centers", {})
+    state.yolo_ball_boxes = tracking.get("boxes", {})
+    state.yolo_ball_conf = tracking.get("confs", {})
+    state.yolo_smoothed_centers = tracking.get("smoothed_centers", {})
+    state.yolo_speeds = tracking.get("speeds", {})
+    state.yolo_kick_frames = tracking.get("frames_ordered", [])
+    state.yolo_kick_speeds = tracking.get("speed_series", [])
+    state.yolo_threshold = tracking.get("threshold")
+    state.yolo_baseline_speed = tracking.get("baseline")
+    state.yolo_kick_frame = tracking.get("kick_frame")
+    state.yolo_initial_frame = tracking.get("frames_ordered", [None])[0] if tracking.get("frames_ordered") else None
+    
+    # Compute areas
+    areas = tracking.get("areas", {})
+    frames_ordered = tracking.get("frames_ordered", [])
+    state.yolo_mask_area_proxy = [areas.get(f, 0.0) for f in frames_ordered]
+    
+    # Compute distance from start
+    smoothed = tracking.get("smoothed_centers", {})
+    if smoothed and frames_ordered:
+        origin = smoothed.get(frames_ordered[0], (0, 0))
+        distance_dict = {}
+        for f, (sx, sy) in smoothed.items():
+            distance_dict[f] = math.hypot(sx - origin[0], sy - origin[1])
+        state.yolo_distance_from_start = distance_dict
+        state.yolo_kick_distance = [distance_dict.get(f, 0.0) for f in frames_ordered]
+    
+    # Update kick frame
+    kick_frame = tracking.get("kick_frame")
+    if kick_frame is not None:
+        state.kick_frame = kick_frame
+        _compute_sam_window_from_kick(state, kick_frame)
+    
+    # Mark as tracked
+    state.is_yolo_tracked = True
+    state.ball_selection_confirmed = True
+    
+    coverage = tracking.get("coverage", 0.0)
+    if kick_frame is not None:
+        state.yolo_status = f"✅ Ball {idx+1} tracked. Kick @ frame {kick_frame}."
+    else:
+        state.yolo_status = f"⚠️ Ball {idx+1} tracked ({coverage:.0%} coverage) but no kick detected."
+
+
 def pastel_color_for_object(obj_id: int) -> tuple[int, int, int]:
     """Generate a deterministic pastel RGB color for a given object id.
 
@@ -877,6 +1308,14 @@ class AppState:
         self.is_sam_tracked: bool = False
         self.is_player_detected: bool = False
         self.is_player_propagated: bool = False
+        
+        # Multi-ball candidate tracking
+        self.ball_candidates: list[dict] = []  # All detected ball candidates
+        self.ball_candidates_tracking: dict[int, dict] = {}  # Per-candidate tracking data
+        self.selected_ball_idx: int = 0  # Currently selected candidate index
+        self.ball_selection_confirmed: bool = False  # True after user confirms selection
+        self.multi_ball_status: str = ""  # Status message for multi-ball detection
+        
         self.goal_mode: str = GOAL_MODE_IDLE
         self.goal_points_norm: list[tuple[float, float]] = []
         self.goal_confirmed_points_norm: list[tuple[float, float]] = []
@@ -2225,6 +2664,109 @@ def _build_yolo_plot(state: AppState):
     return fig
 
 
+def _build_multi_ball_chart(state: AppState):
+    """
+    Build a combined speed chart showing all ball candidates.
+    The selected/kicked ball is highlighted in green, others in gray.
+    """
+    fig = go.Figure()
+    
+    if state is None or not state.ball_candidates:
+        fig.update_layout(
+            title="Ball Candidates Speed Comparison",
+            xaxis_title="Frame",
+            yaxis_title="Speed (px/s)",
+        )
+        return fig
+    
+    # Color palette for candidates
+    colors = [
+        "#4caf50",  # Green (selected/kicked)
+        "#9e9e9e",  # Gray
+        "#bdbdbd",  # Light gray
+        "#757575",  # Dark gray
+        "#e0e0e0",  # Very light gray
+    ]
+    
+    selected_idx = state.selected_ball_idx
+    max_speed = 0.0
+    kick_frames_to_mark = []
+    
+    for i, candidate in enumerate(state.ball_candidates):
+        tracking = candidate.get("tracking", {})
+        frames = tracking.get("frames_ordered", [])
+        speeds = tracking.get("speed_series", [])
+        
+        if not frames or not speeds:
+            continue
+        
+        max_speed = max(max_speed, max(speeds) if speeds else 0)
+        
+        is_selected = (i == selected_idx)
+        is_kicked = candidate.get("has_kick", False)
+        
+        # Determine color and style
+        if is_selected:
+            color = "#4caf50"  # Green
+            width = 3
+            opacity = 1.0
+        elif is_kicked:
+            color = "#ff9800"  # Orange for other kicked balls
+            width = 2
+            opacity = 0.7
+        else:
+            color = "#9e9e9e"  # Gray
+            width = 1
+            opacity = 0.5
+        
+        # Build label
+        label_parts = [f"Ball {i+1}"]
+        if is_kicked:
+            label_parts.append("⚽")
+        if is_selected:
+            label_parts.append("✓")
+        label = " ".join(label_parts)
+        
+        fig.add_trace(
+            go.Scatter(
+                x=frames,
+                y=speeds,
+                mode="lines",
+                name=label,
+                line=dict(color=color, width=width),
+                opacity=opacity,
+            )
+        )
+        
+        # Mark kick frame
+        kick_frame = candidate.get("kick_frame")
+        if kick_frame is not None:
+            kick_frames_to_mark.append((kick_frame, i, is_selected))
+    
+    # Add vertical lines for kick frames
+    for kick_frame, ball_idx, is_selected in kick_frames_to_mark:
+        color = "#e91e63" if is_selected else "#ffcdd2"
+        width = 3 if is_selected else 1
+        
+        fig.add_vline(
+            x=kick_frame,
+            line=dict(color=color, width=width, dash="solid" if is_selected else "dot"),
+            annotation_text=f"Ball {ball_idx+1} kick" if is_selected else "",
+            annotation_position="top right" if is_selected else None,
+        )
+    
+    fig.update_layout(
+        title="Ball Candidates Speed Comparison",
+        xaxis=dict(title="Frame"),
+        yaxis=dict(title="Speed (px/s)", range=[0, max_speed * 1.1] if max_speed > 0 else None),
+        legend=dict(orientation="h", yanchor="bottom", y=1.02),
+        margin=dict(t=60, l=40, r=40, b=40),
+        hovermode="x unified",
+    )
+    
+    return fig
+
+
 def _jump_to_frame(state: AppState, target: int | None):
     if state is None or state.num_frames == 0 or target is None:
         return gr.update(), gr.update()
@@ -3680,6 +4222,20 @@ with gr.Blocks(title="SAM2 Video (Transformers) - Interactive Segmentation", the
                         with gr.Row(elem_classes=["model-status"]):
                             yolo_kick_btn = gr.Button("⚽: N/A", interactive=False)
                             yolo_impact_btn = gr.Button("🚩: N/A", interactive=False)
+                    
+                    # Multi-ball candidate selection UI
+                    with gr.Column(visible=False) as multi_ball_selection_col:
+                        multi_ball_status_md = gr.Markdown("", visible=True)
+                        ball_candidate_radio = gr.Radio(
+                            choices=[],
+                            value=None,
+                            label="Select Ball Candidate",
+                            interactive=True,
+                        )
+                        with gr.Row():
+                            confirm_ball_btn = gr.Button("Confirm Selection", variant="primary")
+                        multi_ball_chart = gr.Plot(label="Ball Candidates Speed Comparison", show_label=True)
+                    
                     yolo_plot = gr.Plot(label="YOLO kick diagnostics", show_label=True)
                 with gr.Column(elem_classes=["model-section"]):
                     with gr.Row(elem_classes=["model-row"]):
@@ -4216,25 +4772,45 @@ with gr.Blocks(title="SAM2 Video (Transformers) - Interactive Segmentation", the
         state_in.is_ball_detected = False
         frame_idx = 0
         frame = state_in.video_frames[frame_idx]
-        detection = detect_ball_center(frame)
-        if detection is None:
-            propagate_main_update, detect_btn_update, propagate_player_update = _button_updates(state_in)
-            status_updates = _ui_status_updates(state_in)
-            return (
-                update_frame_display(state_in, frame_idx),
-                gr.update(
-                    value="❌ Unable to auto-detect the ball. Please add a point manually.",
-                    visible=True,
-                ),
-                gr.update(value=frame_idx),
-                _build_kick_plot(state_in),
-                propagate_main_update,
-                detect_btn_update,
-                propagate_player_update,
-                *status_updates,
-            )
+        
+        # First, try multi-ball detection
+        candidates = detect_all_balls(frame)
+        
+        if not candidates:
+            # Fallback to single-ball detection
+            detection = detect_ball_center(frame)
+            if detection is None:
+                propagate_main_update, detect_btn_update, propagate_player_update = _button_updates(state_in)
+                status_updates = _ui_status_updates(state_in)
+                return (
+                    update_frame_display(state_in, frame_idx),
+                    gr.update(
+                        value="❌ Unable to auto-detect the ball. Please add a point manually.",
+                        visible=True,
+                    ),
+                    gr.update(value=frame_idx),
+                    _build_kick_plot(state_in),
+                    propagate_main_update,
+                    detect_btn_update,
+                    propagate_player_update,
+                    *status_updates,
+                )
+            x_center, y_center, _, _, conf = detection
+        else:
+            # Use the best candidate (first one after sorting by confidence)
+            best = candidates[0]
+            x_center, y_center = best["center"]
+            conf = best["conf"]
+            
+            # Store candidates for potential multi-ball workflow
+            state_in.ball_candidates = candidates
+            state_in.selected_ball_idx = 0
+            
+            if len(candidates) > 1:
+                state_in.multi_ball_status = f"⚠️ {len(candidates)} balls detected. Using best candidate. Run 'Track Ball' to analyze all."
+            else:
+                state_in.multi_ball_status = ""
 
-        x_center, y_center, _, _, conf = detection
         frame_width, frame_height = frame.size
         x_center = max(0, min(frame_width - 1, int(x_center)))
         y_center = max(0, min(frame_height - 1, int(y_center)))
@@ -4260,7 +4836,11 @@ with gr.Blocks(title="SAM2 Video (Transformers) - Interactive Segmentation", the
         )
 
         state_in.is_ball_detected = True
-        status_text = f"✅ Auto-detected ball at ({x_center}, {y_center}) (conf={conf:.2f})"
+        num_candidates = len(getattr(state_in, 'ball_candidates', []))
+        if num_candidates > 1:
+            status_text = f"⚠️ {num_candidates} balls found! Best at ({x_center}, {y_center}) (conf={conf:.2f})"
+        else:
+            status_text = f"✅ Auto-detected ball at ({x_center}, {y_center}) (conf={conf:.2f})"
         status_text += f" | {_format_kick_status(state_in)}"
         propagate_main_update, detect_btn_update, propagate_player_update = _button_updates(state_in)
         status_updates = _ui_status_updates(state_in)
@@ -4307,7 +4887,23 @@ with gr.Blocks(title="SAM2 Video (Transformers) - Interactive Segmentation", the
             raise gr.Error("Load a video first, then track the ball with YOLO.")
         progress = gr.Progress(track_tqdm=False)
         state_in.is_yolo_tracked = False
-        _perform_yolo_ball_tracking(state_in, progress=progress)
+        
+        # Check if we have multiple ball candidates
+        num_candidates = len(getattr(state_in, 'ball_candidates', []))
+        
+        if num_candidates > 1:
+            # Multi-ball mode: track all candidates and show comparison
+            _detect_and_track_all_ball_candidates(state_in, progress=progress)
+            
+            # Apply the best candidate to YOLO state
+            _apply_selected_ball_to_yolo_state(state_in)
+            
+            base_msg = state_in.multi_ball_status or state_in.yolo_status or ""
+        else:
+            # Single ball mode: use original tracking
+            _perform_yolo_ball_tracking(state_in, progress=progress)
+            base_msg = state_in.yolo_status or ""
+        
         target_frame = (
             state_in.yolo_kick_frame
             if state_in.yolo_kick_frame is not None
@@ -4319,7 +4915,6 @@ with gr.Blocks(title="SAM2 Video (Transformers) - Interactive Segmentation", the
             target_frame = int(np.clip(target_frame, 0, state_in.num_frames - 1))
         state_in.current_frame_idx = target_frame
         preview_img = update_frame_display(state_in, target_frame)
-        base_msg = state_in.yolo_status or ""
         kick_msg = _format_kick_status(state_in)
         status_text = f"{base_msg} | {kick_msg}" if base_msg else kick_msg
         state_in.is_yolo_tracked = True