Qiushuii/score-sync-guide

Seguir la partitura mientras se escucha (score-sync-guide)

Convierte una partitura MusicXML + una grabación en un video: a la izquierda, una partitura de una sola línea que se desplaza horizontalmente, con el cursor de reproducción fijo, las notas que suenan resaltadas en rojo y mostrando solo el instrumento que está sonando; a la derecha, tarjetas de análisis guiado y la estructura formal del movimiento. Todo el proceso se ejecuta de forma nativa en Windows, sin necesidad de WSL, Node.js o Playwright.

Este enfoque proviene de la producción real del primer movimiento de la Sinfonía n.º 6 de Mahler (cuatro movimientos, 83 minutos). El algoritmo de alineación nota a nota está adaptado de tofucurd/score-sync-video (MIT), y varios diseños del reproductor (cursor fijo, conjunto de voces estable, estructura formal de dos niveles, renderizado por bloques reanudable) también están inspirados en él; este skill es la localización y extensión de ese proyecto para Windows (tarjetas de análisis, flujo de alineación de grabación, herramientas de verificación cruzada).

Lee estas reglas primero

1. Los archivos originales no se modifican. La partitura y la grabación se colocan en la raíz del proyecto, solo lectura; cualquier cambio en la partitura se escribe en scores_fixed/corrections.json, se genera una copia con tools/fix_mxl.py y se registra la justificación (página original de la partitura, captura de pantalla).
2. Pregunta al usuario antes de cambiar notas. Las MusicXML de la comunidad y la partitura impresa suelen ser versiones diferentes; la "inconsistencia" no es necesariamente un error. Solo corrige errores evidentes de importación.
3. Las grabaciones comerciales no se suben a ningún servicio de terceros ni se almacenan en el repositorio.
4. Los paquetes nuevos de Python los instala el usuario: enumera el nombre del paquete y el comando; no ejecutes pip install por tu cuenta.
5. Cada afirmación factual en las tarjetas de análisis debe tener una base: datos de la partitura (indicando el número de compás) o fuentes verificables (references.json + superíndice). Si no se puede verificar, no se escribe, o se etiqueta como "sin verificar". El análisis armónico automático no es fiable para orquestaciones grandes, solo se usa como pista.
6. Si el usuario no sabe leer partituras, la validación se hace escuchando: escuchar la partitura (colección de fragmentos conflictivos) es más fiable que escuchar pitidos.
7. Primero ejecuta la alineación fina nota a nota, luego pide al usuario que escuche y luego añade anclajes. Hacerlo al revés (hacer que el usuario reporte marcas de tiempo una por una) desperdicia mucho tiempo en desplazamientos dentro del compás que la alineación fina ya resuelve automáticamente.
8. Las opiniones personales del usuario son solo adornos; no inventes ni exageres los puntos de vista del usuario.

Resumen del flujo de trabajo

Paso	Qué hacer	Archivos principales	Más detalles
0	Crear proyecto: copiar template/ a la raíz del proyecto, escribir manifest.json	template/, examples/mahler6/manifest.json	flujo de trabajo
1	Inspeccionar partitura: voces, repeticiones, tempo, marcas de ensayo, texto reservado	analyze.py, check_all.py	flujo de trabajo
2	Editar copia, nombres chinos de voces y fusiones	tools/fix_mxl.py, tools/build_labels.py, labels.json	flujo de trabajo
3	DTW por compás → inmediatamente alineación fina nota a nota	align/align.py, align/ssv_align.py	alineación
4	Verificación auditiva: colección de fragmentos conflictivos; solo añadir anclajes y recalibración local en lugares que sigan siendo incorrectos después de la alineación fina, luego volver a ejecutar la alineación fina	demo/make_disputes.py, align/manual_regions.json, align/refine_local.py	alineación
5	Forma, motivos, tarjetas de análisis	form/, motifs.json, cards/	tarjetas
6	Verificación cruzada de tarjetas con la partitura, revisión de duración de visualización	tools/cards_xcheck.py, tools/cards_review.py	tarjetas
7	Composición de partitura, página de reproducción, prueba de video	demo/build_score.py, demo/player.html, demo/render_frames.py	renderizado
8	Renderizado y ensamblaje completo del video	demo/render_film.py	renderizado

Los problemas encontrados en Windows (codificación, procesos, puertos, saltos de línea en PowerShell, frecuencias de muestreo en ffmpeg, etc.) se recogen en windows-notes; revísalo antes de empezar.

Ruta más corta (un movimiento)

# Python del sistema (con verovio, music21, librosa, numba instalados)
$py = "python"
& $py -X utf8 analyze.py                                   # Inspección: out/<nombre_partitura>_structure.json, report.txt
& $py -X utf8 align/align.py --movement 1                  # ① DTW por compás → align/m1_measures.json (ancla inicial en align/anchors.json)
& $py -X utf8 align/ssv_align.py 1                         # ② Inmediatamente alineación fina nota a nota → align/m1_ssv_chain.json
& $py -X utf8 align/make_checklist.py                      # Lista de verificación auditiva
& $py -X utf8 demo/make_disputes.py                        # ③ Colección de fragmentos conflictivos: escuchar la partitura
# ④ Solo en lugares que sigan siendo incorrectos, añadir pins/beats a align/manual_regions.json, y si es necesario:
& $py -X utf8 align/refine_local.py --movement 1
& $py -X utf8 align/ssv_align.py 1                         # ⑤ Si se modificaron anclajes o la tabla de compases, volver a ejecutar la alineación fina
& $py -X utf8 demo/build_score.py --movement 1 --range 1-40 --out demo/build   # Composición de partitura (posición desde 1)
& $py -X utf8 demo/render_frames.py --data build/data.js --out demo/test.mp4  # Prueba de video

Video completo:

& $py -X utf8 demo/render_film.py plan --res 1920x1080 --fps 60 --name Muestra --single 4
& $py -X utf8 demo/render_film.py worker 1 --only 4        # Se pueden ejecutar varios workers simultáneamente (el número determina el puerto de depuración)
& $py -X utf8 demo/render_film.py worker 2
& $py -X utf8 demo/render_film.py status
& $py -X utf8 demo/render_film.py assemble

Para renderizados largos, inicia el proceso desvinculado de la terminal actual (consulta la sección WMI de windows-notes), de lo contrario, cerrar la terminal o la sesión lo interrumpirá.

Autoverificación antes de la entrega

• La línea de tiempo es estrictamente creciente, sin compases faltantes; el número de compases después de expandir repeticiones coincide con play_order.
• Todos los nombres de voces están en chino, sin "sin clasificar".
• Se han revisado uno por uno los elementos sospechosos de cards_xcheck.py; cards_review.py se ha superado por completo; después de modificar tarjetas, volver a ejecutar build_refs.py.
• Después de cambiar la tabla de compases o los anclajes, volver a ejecutar ssv_align.py (build_score.py usará huellas dactilares para detectar alineaciones finas obsoletas).
• Verificar los fotogramas del video final segmento por segmento; inspección visual por muestreo.