ohmj2/NAMING.md

NAMING.md - Convention des noms de partitions

Référence du format de fichiers/répertoires des partitions (legacy/Scores/). Cette convention a été normalisée une fois par scripts/convert_final_v2.js (6388 fichiers convertis). Ne pas renommer à la main : le backend (api/lib/ScoreScanner.php) et le frontend en dépendent.

Arborescence

legacy/Scores/<NUM>/<PIECE>/<INSTRUMENT>/<VERSION>/<FICHIER>
legacy/Scores/<NUM>/score.ini

Segment	Rôle	Exemples
NUM	identifiant du morceau, zéro-paddé sur 3 chiffres	102, 390, 072, 098
PIECE	numéro de pièce (mouvement)	1 (morceau simple), 1..5 (medley type 390)
INSTRUMENT	trigramme de l'instrument	cla, sax, sup… (voir table)
VERSION	répertoire de version	1 = version principale, 2, 3… = alternatives
FICHIER	nom du PDF (grammaire ci-dessous)	clarinette-sib-1.pdf

VERSION est un répertoire, pas un token du nom de fichier. Le dossier 1/ est la version principale ; 2/+ sont des versions alternatives du même morceau (ex. score 210 : cla/1/ et cla/2/).

Grammaire du nom de fichier

{instrument}[-{tonalité}][-{variante}]-{partie}[_{partie_combinée}][_{clef}][_alt{N}].pdf

• Séparateur de champs : -
• Séparateur interne aux noms composés et aux suffixes : _
• Multi-instrument (deux instruments sur la même partition) : +

Exemples réels

Fichier	Sens
clarinette-sib-1.pdf	clarinette en Si♭, partie 1
clarinette_alto-mib-1.pdf	clarinette alto en Mi♭, partie 1 (_ = nom composé)
sax_alto-mib-2.pdf	sax alto en Mi♭, partie 2
cor-fa-1_2.pdf	cor en Fa, parties 1 et 2 combinées
baryton-clefa-1.pdf	baryton, clé de fa, partie 1 (pas de tonalité)
euphonium-sib-clesol-1.pdf	euphonium Si♭, clé de sol, partie 1
cornet-sib-solo-1.pdf	variante solo
baryton-sib-default_cor-2.pdf	substitution default_cor
conducteur-1_alt1.pdf	version alternative alt1
basse-sib-1+contrebasse-sib-1.pdf	deux instruments sur la même partition
saxophone-mib-1+baryton-mib-1.pdf	idem (sax + baryton)
glockenspiel-1+xylophone-1.pdf	percussion multiple
percussion-1+gong-1+cymbale-1+triangle-1.pdf	3 + possibles

Ordre réel des champs d'un nom simple : instrument, puis tonalité, variante, clef, et enfin partie (ex. euphonium-sib-clesol-1.pdf, cornet-sib-solo-1.pdf, baryton-clefa-1.pdf).

Parties combinées (sup / par)

Les dossiers sup/ et par/ regroupent des partitions combinées : le nom du fichier reprend les instruments réels reliés par +, pas le code du dossier. Exemples réels : 331/1/sup/1/contrebasse-1+clarinette-1.pdf, 295/1/sup/1/euphonium-sib-clefa-1+baryton-sib-clefa-1.pdf, 346/1/par/1/partie-sib-4.pdf.

À l'upload (admin), un éditeur « Parties combinées » apparaît pour sup/par : on ajoute un ou plusieurs instruments, chacun avec tonalité / clé / partie ; le nom est alors construit automatiquement, relié par + (ex. contrebasse-sib-clefa-1+baryton-sib-clefa-1.pdf).

Percussions (per)

Comme sup/par, le dossier per/ regroupe plusieurs instruments : le nom du fichier précise le(s) instrument(s) de percussion, reliés par + lorsqu'ils partagent la même partition. Noms reconnus : batterie, glockenspiel, xylophone, vibraphone, timbales, grosse_caisse, caisse_claire, cymbale, triangle, tambour, tam_tam, tom, gong, bongos, maracas, tambourine, woodblock, claves.

Exemples : batterie-1.pdf, glockenspiel-1+xylophone-1.pdf, timbales-1+basse-1+batterie-1+triangle-1.pdf, percussion-1+gong-1+cymbalе-1+triangle-1.pdf.

percussion (générique) ne s'utilise que si la partition couvre tout le pupitre. Éviter les noms génériques type percussion_1, percussion_2, … qui ne disent pas quel instrument joue.

Tonalités

sib (Si♭), mib (Mi♭), fa (Fa), ut (Do — do s'écrit ut dans les fichiers), sol, re, mi, si, reb, dob, solb, lab.

Clefs

clesol (clé de sol), clefa (clé de fa).

Variantes / suffixes

• solo : partie solo.
• default_<instr> : instrument de substitution (ex. default_cor).
• _altN : version alternative dans un même dossier (ex. _alt1, _alt2).

Codes instruments

Code	Instrument	Code	Instrument
dir	Direction	trp	Trompette
pic	Piccolo	trb	Trombone
flu	Flûte	tub	Tuba
cla	Clarinette	htb	Hautbois
clb	Clarinette basse	bas	Basson
sax	Saxophone alto	per	Percussions
sat	Saxophone ténor	crn	Cornet
sab	Saxophone baryton	eup	Euphonium
coa	Cor anglais	har	Harpe
cba	Contrebasse	pia	Piano
cor	Cor	sup / par	Parties combinées

score.ini

[info]
name = La part d'Euterpe
compositor = Michaël CUVILLON
ressource = https://...        ; optionnel (lien externe)

[pieces]
count = 1
; pour un medley (count = N) :
; 1 = La Part d Euterpe
; 2 = Calliope s Songs

• [pieces] count = nombre de pièces. Les clés 1..N donnent leur nom.
• ressource : lien externe optionnel (YouTube, éditeur…).

Points d'attention (code)

• + dans les chemins : un + littéral dans une URL est valide en path, mais PHP urldecode() le transforme en espace. Le download doit donc :
  • encoder chaque segment côté frontend (encodePath dans partitions/src/lib/api.ts) ;
  • utiliser rawurldecode() (jamais urldecode()) côté api/index.php. Sinon les 167 fichiers multi-instruments (a+b.pdf) renvoient 403.
• Parsing : ScoreScanner::parseFilename() détecte tonalité, clef, variante et partie. Les motifs doivent être ancrés (_sib(?:_|$)) et du plus long au plus court (sibemol avant sib) pour ne pas mal découper les noms.
• Le matcher multi-instruments utilise + (et non _et_, supprimé par la conversion).

Conversion (one-off)

scripts/convert_final_v2.js est le convertisseur historique utilisé pour normaliser l'ensemble du catalogue. Il ne doit plus être nécessaire pour de nouveaux fichiers (uploader via l'admin respecte la convention).

node scripts/convert_final_v2.js /chemin/vers/Scores confirm