zakezhang/tennis-video-private-coach

Entrenador Privado de Video de Tenis

Convierte el video de práctica de un jugador amateur en una revisión que puedan poner en práctica: qué parte del golpe falla, qué tiros lo demuestran y exactamente qué practicar a continuación. Diseñado para jugadores principiantes e intermedios que golpean contra una pared, una máquina de bolas, un entrenador o un compañero de práctica.

Requisitos: un entorno que pueda ejecutar Python 3 y ffmpeg e instalar paquetes pip (ultralytics, opencv-python, numpy, scipy, Pillow). Una GPU ayuda pero no es necesaria.

0. Preguntar primero (solo lo que no sepas ya)

1. Qué persona en el cuadro es el jugador: colores de ropa, cabello, posición. Los entrenadores, compañeros y personas en la cancha de al lado suelen aparecer en el cuadro.
2. Mano dominante, y si el revés es a una mano o a dos manos (o ambas, mientras aprende).
3. Nivel y objetivo: cuánto tiempo ha jugado y qué quiere alcanzar (por ejemplo, "intercambiar y jugar un set para fin de año").
4. Lugar: pared de práctica / máquina de bolas / entrenador alimentando / intercambio; interior o exterior.
5. Cámara: detrás, lateral o frontal; altura del teléfono; velocidad de fotogramas.
6. Lesiones: dolor reciente en rodillas, hombro, codo o espalda. Si es así, el juego de pies y los aterrizajes recibirán atención adicional.
7. El único problema que más quieren resolver (por ejemplo, "muchas bolas se van largas" o "mi punto de contacto es inconsistente"). El informe debe responderlo al principio.
8. Informes anteriores, si los hay, para comparar.

1. Lo que el informe debe hacer

• Comenzar con la conclusión. Una frase sobre el mayor problema y la mayor mejora, luego el detalle. Sé específico y respalda cada crítica con evidencia; no solo elogies. Si una revisión anterior se equivocó en algo, dilo explícitamente.
• Respaldar cada afirmación con video. Cada caso obtiene un clip anotado en cámara lenta, dibujado sobre el metraje real del jugador, no una animación de figura de palo.
• Por defecto, 4 categorías × 3 tiros: mejores derechas, peores derechas, mejores reveses, peores reveses (12 clips). Cada categoría obtiene una tabla de comparación de 3 columnas y una frase sobre lo que los tres tiros tienen en común. Si una categoría tiene menos de 3 tiros utilizables, indica cuántos se encontraron.
• Mantener separados los reveses a una mano y a dos manos. Si el jugador practica ambos, los de una mano tienen su propia sección y se excluyen de las estadísticas de dos manos.
• Nombrar la fase defectuosa: preparación / caída de la raqueta / punto de contacto / dirección del seguimiento / juego de pies / tiempo de preparación / manejo de bolas altas / decisión entre derecha y revés.
• Revisar siempre rodillas y juego de pies: golpear en el aire, aterrizar en una pierna, pivotar sobre una pierna recta bloqueada.
• Declarar los límites de los datos: tamaño de la muestra, cuántos tiros fueron ilegibles, sesgo del ángulo de la cámara. Si algo no puede verse, dilo en lugar de adivinar un número.
• Terminar con un plan que puedan seguir: 2–4 ejercicios con repeticiones o minutos, más la condición para pasar a la siguiente etapa.

2. Pipeline

2.1 Transcodificar y extraer audio

• El metraje de 4K HEVC del teléfono es pesado. Haz una copia de análisis H.264 de 960 de ancho: ffmpeg -i IN.MOV -vf scale=960:-2 -r 30 -an -c:v libx264 -preset veryfast -crf 24 p.mp4 (Algunos teléfonos graban a 29.97 fps; forzar 30 mantiene las conversiones de tiempo simples).
• Extraer el audio por separado para localizar el contacto: ffmpeg -i IN.MOV -vn -ac 1 -ar 22050 a.wav
• Procesar videos largos en fragmentos de 4–5 minutos para evitar tiempos de espera. Para muchos clips cortos, toma primero un fotograma de cada uno en una hoja de resumen y decide qué clips son ángulos utilizables desde atrás del jugador y cuáles están demasiado lejos (usa solo estos para observar la técnica).
• Para sesiones de pared de práctica, también recorta una copia "pared" ampliada alrededor de la línea de la red para juzgar red/fuera.

2.2 Estimación de pose

• Usa un modelo de pose YOLO de Ultralytics (yolo11n-pose.pt; yolo11m-pose.pt para mayor precisión). En interiores, cada 4 fotogramas a imgsz 640, conf 0.3 es suficiente. En exteriores, donde las personas son más pequeñas y numerosas, usa cada 2 fotogramas, imgsz 960, conf 0.25.
• Rastrear a la persona correcta. Con una persona en el cuadro, toma el cuadro delimitador más grande. Con entrenadores u otros alrededor, puntúa cada detección por la ropa: brillo y saturación HSV medianos dentro del polígono del torso (hombros + caderas), y el color de la región cadera-rodilla para pantalones cortos. Agrega una penalización por saltar lejos del fotograma anterior para que el rastreo no cambie de persona.
• Decidir izquierda y derecha por la coordenada x de la imagen, no por las etiquetas de izquierda/derecha del modelo. Desde atrás, el lado derecho del jugador es el lado derecho de la imagen.

2.3 Encontrar cada golpe

• Un golpe es un pico en la velocidad de la muñeca: desplazamiento fotograma a fotograma de la muñeca que más se mueve, dividido por la altura del cuadro delimitador, suavizado sobre 2 muestras, umbral de aproximadamente 0.16 (para muestreo de cada 4 fotogramas; escala hacia abajo para muestreo más denso).
• Requerir al menos 1.6 s entre picos. Un espacio de 1.0 s cuenta la recuperación después del seguimiento como un segundo golpe. El ritmo normal es un golpe cada 3–4 s.
• Derecha o revés: en la ventana de 1.1 s a 0.25 s antes del pico, de qué lado de la línea media de la cadera está el punto medio de ambas manos. El lado de la mano dominante significa derecha. Algunos estarán equivocados; confirma fotograma a fotograma para cualquier tiro que destaques.
• Anclar cada métrica a continuación al pico de velocidad de la muñeca (llámalo tp) para que las sesiones sigan siendo comparables.

2.4 Localizar el contacto por sonido

• Pasa alto a 1500 Hz; calcula una envolvente de energía sobre ventanas de 110 muestras; encuentra picos al menos 10 dB por encima de la mediana de las 401 ventanas circundantes y al menos 50 ventanas separadas.
• Convertir a segundos con window_index × 110 / 22050. Multiplicar por 0.005 como atajo se desvía aproximadamente medio segundo cada 4 minutos y arruina la segunda mitad de videos largos.
• Pared de práctica: toma el pico más fuerte al menos 15 dB por encima del fondo dentro de [tp−0.1, tp+0.55] s, generalmente 0.2–0.35 s después de tp. La pelota golpeando la pared aproximadamente 0.45 s después del contacto también es fuerte; no lo elijas.
• Exteriores: los tiros del entrenador y otras canchas añaden ruido. Busca [tp−0.45, tp+0.25] s; si nada califica, usa tp.
• Para cada tiro que termine en un clip, confirma el fotograma de contacto real mirando los fotogramas.

2.5 Detectar reveses a una mano (si el jugador está aprendiendo uno)

• Entre los reveses, toma la distancia máxima muñeca a muñeca (dividida por la longitud del torso) dentro de 0.7 s después de tp. Los de dos manos mantienen ambas manos juntas durante el final (generalmente por debajo de 1.5); los de una mano abren el brazo que no golpea hacia atrás (generalmente 2.0–2.5). La brecha es clara; un umbral alrededor de 1.95 funciona.
• Los ángulos de cámara cercanos producen falsos positivos; confirma cada candidato visualmente.
• Para cada revés a una mano, registra: si la mano va por encima de la cabeza en la preparación, si la preparación es tardía (preparado como un revés a dos manos, luego levantado en el último momento), si el brazo está recto en el contacto, altura del seguimiento y el resultado.
• Lista de verificación de revés a una mano (para cada elemento: cómo se ve lo correcto / esta sesión / veredicto): giro de unidad con la mano de apoyo en la garganta, altura de preparación entre el pecho y el hombro con la cabeza de la raqueta apuntando hacia atrás, la raqueta cae baja luego golpea de abajo a arriba, contacto adelante con el brazo recto, la mano de apoyo se abre hacia atrás, termina alto y sostenido sin que el pecho se gire temprano, rodillas flexionadas y pisando hacia adelante. El agarre no puede verse desde atrás; sugiere que el jugador lo confirme con un entrenador.

2.6 Conteo de red / fuera (solo cuando la pelota es visible)

• Pared de práctica: marca la línea de la red en el video ampliado de la pared. Para cada tiro, haz un mosaico: manchas amarillas en movimiento sobre los 30 fotogramas después del contacto, trazadas de rojo a verde por tiempo, más el movimiento de la cortina por encima de la línea de la red en un segundo color. Juzga cada mosaico a simple vista: la cortina se mueve o la pelota golpea por encima de la línea = dentro; la pelota golpea el tablero y la cortina no se mueve = red; bloqueado por el jugador = ilegible. El juicio completamente automático coincide con un humano solo aproximadamente el 60% del tiempo, así que úsalo solo como una pista.
• Muestreo: juzga 100 tiros distribuidos uniformemente a lo largo de la sesión, excluye los ilegibles e informa por separado para derechas / reveses a dos manos / reveses a una mano. Luego revisa los 20 tiros más sospechosos restantes para ver si los errores se agrupan en un período (generalmente después de que aparece la fatiga).
• Exteriores: con árboles moviéndose en el fondo o muchos jugadores alrededor, la detección de pelota por color y movimiento falla principalmente. No informes un porcentaje. Di por qué en el informe, elige los mejores/peores por técnica en su lugar y da consejos de cámara que harían posible el conteo.

2.7 Métricas de técnica (medidas en cada golpe)

Métrica	Cómo	Qué revela
Mano de derecha por encima de la nariz	Proporción de fotogramas en [tp−1.1, tp−0.25] con la muñeca que golpea por encima de la nariz	Preparación demasiado alta, golpe con bucle
Ambas manos por encima de los hombros	Proporción de la misma ventana con ambas muñecas por encima del centro del hombro	Raqueta de revés sostenida demasiado alta
Flexión máxima de rodilla	Ángulo mínimo cadera-rodilla-tobillo de la pierna delantera en [tp−0.6, tp+0.3], mediana a través de los golpes	Piernas demasiado rectas (una cámara detrás subestima la flexión hacia adelante; compara solo contigo mismo)
Anchura de postura	Distancia horizontal del tobillo en tp ÷ longitud del torso	Postura estrecha a menudo va con saltar
Plantado y recto	Un tobillo se mueve menos de 0.4 longitudes de torso dentro de 0.7 s después de tp, y esa rodilla está más recta que 155°	Carga de torsión en la rodilla (común al pivotar en los reveses)
Altura de contacto	Posición de la mano que golpea entre cadera (0) y hombro (1), 0.07–0.2 s antes de tp	Cuántas bolas son altas y si el jugador ajusta la posición
Saltar / aterrizar en una pierna	Contado a simple vista en los tiros que revisas fotograma a fotograma	Aún no hay métrica automática confiable

• Para sesiones largas, informa la primera y la segunda mitad por separado para ver qué se descompone con la fatiga.
• Si la cámara, el lugar o el método cambian, vuelve a medir los videos antiguos con el nuevo método o di claramente que los números no son comparables.

2.8 Elegir 3 mejores y 3 peores

• Mejores: buen resultado (supera la red cómodamente, cae profundo) y un golpe completo (preparación en posición, cabeza de la raqueta cae por debajo de la pelota, final completo, ambos pies en el suelo). Distribúyelos a lo largo de la sesión.
• Peores: red, bolas al cielo o errores claros; si no hay suficientes, toma los tiros donde el defecto técnico sea más claro. Prefiere tiros que muestren diferentes causas, o que juntos demuestren una causa común.
• Preselecciona a partir de los mosaicos de resultados, luego confirma la causa a partir de hojas de jugador por fotograma (0.9 s antes hasta 0.5 s después del contacto). Al elegir los peores reveses, asegúrate de que no sean de una mano.

2.9 Renderizar clips anotados en cámara lenta

• Corta aproximadamente 3 s del original (comenzando 1.1–1.5 s antes del contacto), recorta alrededor del jugador a aproximadamente 16:10 con el jugador alrededor del 60% de la altura del fotograma y escala a 1280 de ancho.
• Ejecuta la pose en cada fotograma. Elige cuatro fotogramas a mano: parte superior de la preparación, contacto, e inicio y final de la trayectoria dibujada (excluyendo la posición de espera y la recuperación). Los fotogramas de contacto automáticos suelen ser incorrectos; revisa siempre visualmente.
• Estructura del clip:
  1. Velocidad real una vez.
  2. Velocidad reducida a la cuarta parte, dibujando la trayectoria de la mano que golpea fotograma a fotograma (derecha = muñeca que golpea; dos manos = punto medio de ambas muñecas; una mano = punto medio antes del contacto, muñeca que golpea después), degradado naranja a cian, con leyendas para cada fase en la parte inferior.
  3. Congelar en la parte superior de la preparación durante aproximadamente 3 s, rodéalo (verde = correcto, rojo = problema) con un titular breve.
  4. Congelar en el contacto durante aproximadamente 3 s: círculo blanco en el punto de contacto (la posición automática a menudo falla la pelota, así que ajústala a mano), círculo amarillo en la rodilla delantera con su ángulo (omite para los reveses a una mano, donde las piernas se superponen de lado).
  5. Congelar en la trayectoria completa. En los clips peores, superpone el mejor tiro de la sesión del mismo tipo, desde el inicio de la trayectoria hasta el contacto, escalado por la longitud del torso y alineado en el centro del hombro, como una línea discontinua verde animada con un contorno negro, más una frase sobre la corrección.
• Codifica H.264, yuv420p, faststart, 960 de ancho, aproximadamente 1–2.5 MB por clip. Hoja de contacto de 4 fotogramas de cada clip para verificar que las leyendas no cubran nada y los círculos caigan en el lugar correcto.
• Evita ✓ y ✗ en las leyendas; muchas fuentes CJK carecen de ellos y muestran cuadros.

3. Estructura del informe

Produce una página HTML (o el formato que el usuario solicite), en este orden:

1. Veredicto: responde la pregunta del jugador directamente; mejora más grande, problema más grande, números clave; correcciones a la revisión anterior. Debajo, una tira de estadísticas (golpes por tipo de golpe, tasa de red muestreada o "no contada" con la razón, una o dos métricas clave).
2. Causas: agrupa los problemas en 2–3 causas, cada una con un ejemplo con marca de tiempo.
3. Mejores vs peores: 4 grupos, cada uno con 3 clips, una tabla de 3 columnas (preparación, caída, contacto, final, pies, ángulo de rodilla) y una frase sobre el patrón.
4. Comparado con la última vez: qué cambió en el mejor y el peor tiro, como tabla más clips lado a lado.
5. Revés a una mano (si lo practica): estadísticas, lista de verificación, 3 clips buenos y 3 malos, lista tiro por tiro y consejo sobre si seguir entrenándolo ahora.
6. Rodillas y juego de pies: tabla de métricas y riesgos ordenados en "prioridad / vigilancia / mejorando", cada uno con una corrección. Declara claramente que esto no es consejo médico y sugiere ver a un médico de medicina deportiva por hinchazón, bloqueo, ceder o dolor que dure más de una semana.
7. Qué practicar a continuación: ver sección 5.
8. Consejos de cámara (si el metraje tuvo lagunas).
9. Pie de página: fuente de datos, tamaño de la muestra, definiciones de medición, limitaciones de la cámara.

Dirección de diseño opcional: una paleta de tenis, con azul de cancha dura como color principal, amarillo de pelota solo para números clave y aspectos destacados, verde de césped para "bueno" y rojo de arcilla para "problema". Números condensados para una sensación de marcador. Hazlo legible tanto en modo claro como oscuro, sin desplazamiento horizontal en un teléfono.

4. Fallos comunes y correcciones

Clasifica lo que ves con esta tabla primero, luego pruébalo con tiros específicos.

Síntoma	Causa habitual	Cómo se muestra en el video	Corrección
Derecha a la red, golpe hacia abajo	Preparación por encima de la cabeza, gran bucle, la raqueta no puede caer a tiempo	Mano que golpea por encima de la cabeza...	...

[Nota: El contenido original se truncó; se ha traducido el texto disponible. Para completar, se deben traducir las secciones faltantes del original manteniendo la estructura de la tabla y el contenido técnico.]