Qiushuii/score-sync-guide

跟谱听（score-sync-guide）

Transformez une partition MusicXML + un enregistrement audio en une vidéo : à gauche, la partition réduite à une seule portée défilant horizontalement, avec un curseur fixe, les notes en cours colorées en rouge et uniquement la partie jouée affichée ; à droite, des fiches d'analyse et la structure formelle du mouvement. L'ensemble du processus s'exécute sur Windows natif, sans WSL, Node ou Playwright.

Cette méthode est issue de la réalisation d'une Symphonie n°6 de Gustav Mahler (quatre mouvements, 83 minutes). L'algorithme d'alignement note-à-note est adapté de tofucurd/score-sync-video (MIT). Les choix de conception du lecteur (curseur fixe, ensembles de parties stables, structure formelle à deux niveaux, rendu par blocs) en sont également inspirés. Ce skill en est une adaptation et une extension pour Windows (fiches d'analyse, flux d'alignement de l'enregistrement, outils de vérification croisée).

Règles à lire d'abord

1. Ne pas toucher aux fichiers originaux. La partition et l'enregistrement restent à la racine du projet en lecture seule ; toute correction de partition est écrite dans scores_fixed/corrections.json, un exemplaire modifié est généré par tools/fix_mxl.py avec justification (page de la partition originale, capture d'écran).
2. Demander à l'utilisateur avant de modifier des notes. Les MusicXML de la communauté et les partitions imprimées sont souvent de versions différentes ; une "incohérence" n'est pas forcément une erreur. Ne corriger que les erreurs d'import évidentes.
3. Ne pas télécharger l'enregistrement commercial vers un service tiers et ne pas l'inclure dans le dépôt.
4. Les nouveaux paquets Python sont installés par l'utilisateur : lister le nom du paquet et la commande, ne pas exécuter pip install soi-même.
5. Chaque affirmation factuelle dans une fiche d'analyse doit avoir une source : données de la partition (indiquer le numéro de mesure) ou documentation vérifiable (references.json + notes de bas de page). Si l'information n'est pas trouvable, ne pas l'écrire ou la marquer comme "non vérifiée". L'analyse harmonique automatique n'est pas fiable pour les grands orchestres, ne l'utiliser qu'à titre indicatif.
6. Lorsque l'utilisateur ne lit pas la musique, la validation se fait à l'oreille : écouter en suivant la partition (extraits de passages contestés) est plus fiable qu'écouter un bip.
7. D'abord faire l'alignement fin note-à-note, puis demander à l'utilisateur d'écouter et d'ajouter des points d'ancrage. Faire l'inverse (demander à l'utilisateur de donner des horaires un par un) gaspille beaucoup d'efforts sur des décalages intra-mesure que l'alignement fin résout automatiquement.
8. Les avis personnels de l'utilisateur ne servent qu'à agrémenter ; ne pas inventer ou exagérer les opinions à sa place.

Vue d'ensemble du flux de travail

Étape	Action	Fichiers principaux	Détails
0	Créer le projet : copier template/ à la racine du projet, écrire manifest.json	template/, examples/mahler6/manifest.json	workflow
1	Analyser la partition : parties, reprises, tempos, repères de répétition, caractères réservés	analyze.py, check_all.py	workflow
2	Correction de l'exemplaire, noms chinois des parties et fusion	tools/fix_mxl.py, tools/build_labels.py, labels.json	workflow
3	DTW mesure par mesure → immédiatement faire l'alignement fin note-à-note	align/align.py, align/ssv_align.py	alignment
4	Vérification auditive : compilation des passages contestés ; n'ajouter des points d'ancrage et des corrections locales que là où l'alignement fin reste erroné, puis relancer l'alignement fin	demo/make_disputes.py, align/manual_regions.json, align/refine_local.py	alignment
5	Structure formelle, motifs, fiches d'analyse	form/, motifs.json, cards/	cards
6	Vérification croisée des fiches avec la partition, révision du temps d'affichage	tools/cards_xcheck.py, tools/cards_review.py	cards
7	Mise en page de la partition, page de lecture, test de la vidéo	demo/build_score.py, demo/player.html, demo/render_frames.py	rendering
8	Rendu et assemblage de la vidéo complète	demo/render_film.py	rendering

Les difficultés rencontrées sur Windows (encodage, processus, ports, sauts de ligne dans les scripts batch, fréquence d'échantillonnage ffmpeg, etc.) sont regroupées dans windows-notes ; à parcourir avant de commencer.

Chemin le plus court (un mouvement)

# Python système (avec verovio, music21, librosa, numba installés)
$py = "python"
& $py -X utf8 analyze.py                                   # Analyse : out/<nom partition>_structure.json, report.txt
& $py -X utf8 align/align.py --movement 1                  # ① DTW mesure par mesure → align/m1_measures.json (ancres de début dans align/anchors.json)
& $py -X utf8 align/ssv_align.py 1                         # ② Immédiatement après, alignement fin note-à-note → align/m1_ssv_chain.json
& $py -X utf8 align/make_checklist.py                      # Liste de vérification auditive
& $py -X utf8 demo/make_disputes.py                        # ③ Compilation des passages contestés : écouter en suivant la partition
# ④ Là où ce n'est toujours pas correct, ajouter des pins/beats dans align/manual_regions.json, si nécessaire :
& $py -X utf8 align/refine_local.py --movement 1
& $py -X utf8 align/ssv_align.py 1                         # ⑤ Si des points d'ancrage ou la table des mesures ont changé, relancer l'alignement fin
& $py -X utf8 demo/build_score.py --movement 1 --range 1-40 --out demo/build   # Mise en page de la partition (positions à partir de 1)
& $py -X utf8 demo/render_frames.py --data build/data.js --out demo/test.mp4  # Test de la vidéo

Vidéo complète :

& $py -X utf8 demo/render_film.py plan --res 1920x1080 --fps 60 --name "Échantillon" --single 4
& $py -X utf8 demo/render_film.py worker 1 --only 4        # Plusieurs workers peuvent être lancés en parallèle (le numéro détermine le port de débogage)
& $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

Pour les longs rendus, lancer le processus détaché du terminal (voir section WMI dans windows-notes), sinon la fermeture du terminal ou de la session interrompt le rendu.

Auto-vérification avant remise

• La chronologie est strictement croissante, aucune mesure manquante ; le nombre de mesures après les reprises correspond à play_order.
• Tous les noms de parties sont en chinois, aucun "non classé".
• Les éléments suspects de cards_xcheck.py ont été examinés un par un ; cards_review.py est entièrement passé ; après avoir modifié les fiches, relancer build_refs.py.
• Après avoir modifié la table des mesures ou les points d'ancrage, relancer ssv_align.py (build_score.py utilise une empreinte pour détecter un alignement fin obsolète).
• Vérifier image par image les séquences de la vidéo finale ; inspection visuelle par échantillonnage.