tennis-clip-coach

name	tennis-clip-coach
description	Tennis Clip Coach — technical stroke analysis from training video clips. Use when the user asks to analyze tennis mechanics, diagnose forehand/backhand/serve/volley movement, extract video frames with ffmpeg, annotate key sequence frames, or produce an HTML/PDF tennis technique report with root-cause coaching advice.

Tennis Clip Coach

Drop a practice clip. Get an evidence-backed coaching report with selected frame sequences, visual annotations, and a small number of root-cause priorities.

Default output is HTML. Prefer HTML first because it handles many annotated frames, side-by-side comparisons, and dense coaching notes better than PDF. Create PDF only after the HTML is approved or when the user explicitly needs a fixed archive/share format.

Workflow

Prerequisite: ffmpeg and ffprobe must be available on PATH. If either is missing, stop before analysis and tell the user to install ffmpeg or provide an environment that has it.

1. Resolve the input video path and create an analysis directory.
   • Default to ./analyses/<YYYY-MM-DD>-<video-stem>/ relative to the working directory (or a user-specified output folder).
   • Store raw extracts under frames/, intermediate notes under notes/, and the final report as report.html.
2. Run coarse frame extraction:

python3 scripts/extract_frames.py <video> --out <analysis-dir>/frames

3. Inspect frames/coarse/ and frames/manifest.json to identify likely stroke windows. Use coarse frames only to find candidates; do not write final diagnosis from 2-second samples.
4. Classify before diagnosing. Read references/stroke_classification.md. For each candidate window, confirm:
   • player handedness (never assume right-handed; use user input + grip checks across 2+ frames)
   • stroke type (groundstroke / volley / serve / overhead / recovery — do not call volleys or ready positions groundstrokes)
   • stroke side (forehand vs backhand from the player's body, not the camera edge)
   • frame phase (prep / contact / follow-through / recovery — single frames often mislead)
   • ball ownership (inbound to subject vs outbound after subject hit — do not call recovery "late prep") If labels are uncertain, mark 待确认 and do not hard-write.
5. Extract fine sequences around key actions. Use at least 1.0-1.5 seconds around each key stroke when possible, with a 0.25-second interval. If a moment is ambiguous, widen the window to ~2 seconds each side (4–8 frames at 0.25s):

python3 scripts/extract_frames.py <video> --out <analysis-dir>/frames --fine-window 12.0-14.0 --fine-window 28.5-30.0

6. Verify true state with trajectory. For each candidate key frame, read the context window (default ±2 frames; expand to ±4–8 if unclear). Track ball path, subject phase, and opponent action across frames. Assign phase and stroke labels only after the trajectory story is coherent. See Step 5 in stroke_classification.md.
7. Read references/diagnostic_framework.md before writing conclusions. Diagnose the movement system, not isolated cosmetic details.
8. Select evidence frames and define annotations. Prefer before → key → after sequences. Keep annotations sparse: 2-4 marks per frame. 待确认 frames go to uncertainties, not root-cause evidence.
9. Read references/report_data_schema.md, then create <analysis-dir>/report_data.json.
10. Build the report:

python3 scripts/build_report.py <analysis-dir>/report_data.json --out <analysis-dir>/report.html

11. Deliver the HTML path. If PDF is needed, render the approved HTML to PDF using an available browser or PDF tool and verify the visual layout.

Classification Reminder

Mislabeling is the fastest way to ruin an otherwise good report. Typical mistakes: assuming right-handed, calling a volley a groundstroke, calling follow-through "preparation", swapping forehand and backhand on the same clip, treating an outgoing ball as an incoming one (subject just hit a lob and is recovering, but the report says "late prep for opponent's high ball"). When the user corrects handedness or stroke type, update the report and note the correction.

Diagnosis Standard

Always produce a prioritized diagnosis:

• Name 1-3 root causes, ordered by impact.
• Tie each root cause to timestamped frame evidence.
• Explain the causal chain: setup/read -> spacing/timing -> loading/kinetic chain -> racket path/contact -> recovery/result.
• Separate confirmed visual evidence from plausible inference.
• Give a concrete correction plan: cue, drill, dosage, and success metric.

Avoid shallow advice such as "bend knees more" unless it is linked to a deeper constraint such as late spacing, unstable base, missing hip-shoulder separation, or poor contact geometry.

Stroke Windows

For groundstrokes, capture:

• opponent impact or incoming-ball read if visible
• split step / first move
• unit turn and spacing adjustment
• loading position
• forward swing start
• contact
• first follow-through frame
• recovery

For serves, capture:

• setup
• ball release
• trophy / loading
• racket drop
• upward drive
• contact
• pronation/follow-through
• landing and recovery

Report Shape

Use this structure unless the user asks otherwise:

1. Executive diagnosis: the main limiting pattern in 3-6 sentences.
2. Evidence map: timestamped key frames and what each proves.
3. Root-cause chain: why the problem happens, not only what looks wrong.
4. Annotated sequences: frame cards with overlays and concise observations.
5. Intervention plan: 2-4 drills, each with cue, dosage, and pass/fail metric.
6. Uncertainty and next capture request: what the video cannot prove and what angle/frame rate would improve confidence.

Resources

• scripts/extract_frames.py: extract coarse 2-second frames and fine 0.25-second stroke windows with ffmpeg/ffprobe.
• scripts/build_report.py: generate a static HTML report from structured report JSON and overlay annotations on sequence frames.
• references/stroke_classification.md: handedness, stroke-type, and frame-phase checks before labeling.
• references/diagnostic_framework.md: tennis-specific root-cause diagnostic framework.
• references/report_data_schema.md: JSON schema and annotation coordinate conventions for the HTML report builder.