Qiushuii/score-sync-guide

Mit der Partitur hören (score-sync-guide)

Aus einer MusicXML-Partitur + einer Aufnahme ein Video erstellen: Links die horizontal scrollende Einzelstimmen-Partitur mit fixiertem Cursor, aktuell klingende Noten in Rot, nur die gerade aktive Stimme sichtbar; rechts Analyse-Karten und die Formstruktur des Satzes. Der gesamte Ablauf läuft unter nativen Windows – kein WSL, Node oder Playwright nötig.

Dieser Ansatz stammt aus der praktischen Produktion von Mahlers 6. Sinfonie (vier Sätze, 83 Minuten). Der note-by-note-Alignment-Algorithmus wurde von tofucurd/score-sync-video (MIT) portiert, ebenso mehrere Design-Ideen des Players (fixierter Cursor, stabile Stimmenaggregation, zweistufige Formstruktur, blockweise Fortsetzung); dieses Skill ist die lokalisierte und erweiterte Windows-Version (Analysekarten, Aufnahme-Alignment, Querverweis-Werkzeuge).

Diese Regeln zuerst lesen

1. Originaldateien bleiben unberührt. Partitur und Aufnahme liegen schreibgeschützt im Projektstamm; Änderungen an der Partitur werden ausschließlich in scores_fixed/corrections.json festgehalten, von tools/fix_mxl.py als Kopie umgesetzt, mit Begründung (Seitenzahl in der Originalpartitur, Screenshot).
2. Vor dem Ändern von Noten den Benutzer fragen. Community-MusicXML und gedruckte Partitur sind oft unterschiedliche Versionen – "Inkonsistenz" bedeutet nicht zwingend einen Fehler. Es werden nur offensichtliche Importfehler korrigiert.
3. Kommerzielle Aufnahmen werden nicht auf Dienste Dritter hochgeladen und kommen nicht ins Repository.
4. Neue Python-Pakete installiert der Benutzer selbst: Paketnamen und Befehl angeben, nicht selbst pip install ausführen.
5. Jede faktische Behauptung in einer Karte benötigt eine Quelle: Partiturdaten (mit Takzahl) oder überprüfbare Literatur (references.json + Fußnote). Wenn nicht auffindbar, weglassen oder als "nicht verifiziert" kennzeichnen. Automatische harmonische Analyse ist bei großen Orchesterbesetzungen unzuverlässig – nur als Hinweis verwenden.
6. Wenn der Benutzer keine Noten lesen kann, erfolgt die Abnahme durch Hören gegen die Partitur (Sammlung strittiger Stellen) – zuverlässiger als das Hören von "Tick"-Geräuschen.
7. Zuerst das note-by-note-Feinalignment durchführen, dann den Benutzer hören lassen, dann Pins setzen. Der umgekehrte Weg (Benutzer gibt nacheinander Zeitpunkte an) würde viel Aufwand in taktinterne Abweichungen stecken, die das Feinalignment ohnehin automatisch löst.
8. Persönliche Meinungen des Benutzers dienen als Beiwerk – keine erfundenen oder übertriebenen Aussagen.

Ablaufübersicht

Schritt	Was wird gemacht	Hauptdateien	Details
0	Projekt anlegen: template/ in das Projektstammverzeichnis kopieren, manifest.json schreiben	template/, examples/mahler6/manifest.json	workflow
1	Partitur-Check: Stimmen, Wiederholungen, Tempo, Probeziffern, Platzhalter	analyze.py, check_all.py	workflow
2	Korrigierte Kopie, chinesische Stimmennamen und Zusammenführung	tools/fix_mxl.py, tools/build_labels.py, labels.json	workflow
3	Taktweises DTW → sofort note-by-note-Feinalignment	align/align.py, align/ssv_align.py	alignment
4	Hörtest: Sammlung strittiger Stellen; nur bei Fehlern nach dem Feinalignment Pins setzen, lokal neu ausrichten, dann Feinalignment erneut ausführen	demo/make_disputes.py, align/manual_regions.json, align/refine_local.py	alignment
5	Form, Motive, Analyse-Karten	form/, motifs.json, cards/	cards
6	Querverweis zwischen Karten und Partitur, Prüfung der Verweildauer	tools/cards_xcheck.py, tools/cards_review.py	cards
7	Partitur-Setup, Player-Seite, Testclip	demo/build_score.py, demo/player.html, demo/render_frames.py	rendering
8	Vollständiges Rendern und Zusammenfügen	demo/render_film.py	rendering

Stolperfallen unter Windows (Kodierung, Prozesse, Ports, Batch-Umbruch, ffmpeg-Samplerate usw.) sind in windows-notes zusammengefasst – vor dem Start durchlesen.

Kürzester Pfad (ein Satz)

# System-Python (mit verovio, music21, librosa, numba)
$py = "python"
& $py -X utf8 analyze.py                                   # Check: out/<Partitur>_structure.json, report.txt
& $py -X utf8 align/align.py --movement 1                  # ① Taktweises DTW → align/m1_measures.json (Anfangsanker in align/anchors.json)
& $py -X utf8 align/ssv_align.py 1                         # ② Direkt danach note-by-note-Feinalignment → align/m1_ssv_chain.json
& $py -X utf8 align/make_checklist.py                      # Hörtest-Checkliste
& $py -X utf8 demo/make_disputes.py                        # ③ Sammlung strittiger Stellen: gegen die Partitur hören
# ④ Nur an noch falschen Stellen Pins/Beats in align/manual_regions.json eintragen, falls nötig:
& $py -X utf8 align/refine_local.py --movement 1
& $py -X utf8 align/ssv_align.py 1                         # ⑤ Nach Änderungen an Pins oder Taktliste Feinalignment erneut ausführen
& $py -X utf8 demo/build_score.py --movement 1 --range 1-40 --out demo/build   # Partitur-Setup (Positionen ab 1)
& $py -X utf8 demo/render_frames.py --data build/data.js --out demo/test.mp4  # Testclip

Gesamtes Video:

& $py -X utf8 demo/render_film.py plan --res 1920x1080 --fps 60 --name 样片 --single 4
& $py -X utf8 demo/render_film.py worker 1 --only 4        # Mehrere Worker gleichzeitig startbar (Nummer bestimmt Debug-Port)
& $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

Für lange Renderings den Prozess vom aktuellen Terminal entkoppelt starten (siehe WMI-Abschnitt in windows-notes), sonst wird er beim Schließen des Terminals oder der Sitzung abgebrochen.

Selbstprüfung vor Abgabe

• Zeitachse strikt aufsteigend, keine fehlenden Takte; Anzahl Takte nach Wiederholungen deckt sich mit play_order.
• Alle Stimmennamen sind chinesisch, kein "nicht kategorisiert".
• Verdachtsfälle aus cards_xcheck.py wurden einzeln bewertet; cards_review.py vollständig bestanden; nach Änderungen an Karten build_refs.py erneut ausführen.
• Nach Änderungen an der Taktliste oder Pins ssv_align.py erneut ausführen (build_score.py blockt veraltetes Feinalignment per Fingerprint).
• Fertiges Video abschnittsweise auf korrekte Frames prüfen; stichprobenartige Sichtkontrolle.