Tennis Training Review Assistant

MVP for turning a long tennis training video into reviewable clips, CSV indexes, and markdown summaries.

What It Does

• Extracts audio from an input .mp4.
• Detects likely hit sounds from audio peaks.
• Groups hits into rally segments.
• Scores and cuts top review clips.
• Adds error-before/end-of-rally clips.
• Detects coach feedback from optional transcript files.
• Generates:
  • output/hit_events.csv
  • output/rally_segments.csv
  • output/review_index.md
  • output/training_summary.md
  • output/clips/*.mp4

Requirements

• Python 3.10+
• FFmpeg available on PATH

No third-party Python packages are required for the MVP.

Quick Start

python src/main.py input/training_001.mp4

Optional transcript input:

python src/main.py input/training_001.mp4 --transcript input/training_001.srt

Custom output directory and clip count:

python src/main.py input/training_001.mp4 --output output/session_001 --top-n 16

Frontend Review Page

Open the static review page:

python -m http.server 8787

Then visit:

http://localhost:8787/web/

The page supports:

• Dragging or manually selecting a training video.
• Dragging or manually selecting hit_events.csv, rally_segments.csv, and review_index.md.
• Drawing hit markers and review segments on the video timeline.
• Clicking markers, review bands, or review cards to jump to the relevant time.

If you open web/index.html directly, the page still works with drag/drop and file picker input. The "读取默认输出" button works best when the page is served through python -m http.server.

Project Layout

config/
  tennis_rules.yaml
input/
  .gitkeep
output/
  .gitkeep
src/
  audio_utils.py
  cut_clips.py
  detect_coach_feedback.py
  detect_hit_sounds.py
  generate_review_index.py
  generate_training_summary.py
  main.py
  models.py
  score_rallies.py
  segment_rallies.py
web/
  index.html
  styles.css
  app.js

MVP Notes

This version intentionally avoids claiming precise technique diagnosis. It gives the learner good clips and structured prompts for manual review: preparation, turn, footwork, contact point, force chain, follow-through, recovery, depth, arc, and stability.