# 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`

```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).

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