From 67aa5da5d2d90013ea5ae622716f5b965a506e71 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?F=C3=A9lix=20Lavi=C3=A9ville?= <lavieville.felix@gmail.com>
Date: Fri, 17 Jul 2026 19:40:39 +0200
Subject: [PATCH] feat: migrating instrument factory for maximal compatibility
 with future tier plugin

---
 webapp/src/components/app/CLAUDE.md           |  82 +++--
 .../app/instruments/InstrumentParamField.vue  | 125 +++++++
 .../app/instruments/InstrumentParamsModal.vue | 105 ++++++
 .../app/instruments/InstrumentSettings.vue    | 333 ++----------------
 .../app/timeline/AddTrackButton.vue           |  36 +-
 webapp/src/composables/useOnboardingTour.ts   |  26 +-
 .../engines/audio-clip/AudioClipEngine.ts     |   4 +-
 .../audio/engines/audio-clip/definition.ts    |  17 +
 .../src/lib/audio/engines/audio-clip/index.ts |   1 +
 .../engines/basic-synth/BasicSynthEngine.ts   |   8 +-
 .../audio/engines/basic-synth/definition.ts   |  34 ++
 .../lib/audio/engines/basic-synth/index.ts    |   1 +
 .../lib/audio/engines/smplr/SmplrEngine.ts    |   9 +-
 .../src/lib/audio/engines/smplr/definition.ts |  30 ++
 webapp/src/lib/audio/engines/smplr/index.ts   |   1 +
 webapp/src/lib/audio/engines/types.ts         |  14 +-
 .../engines/undertale/UndertaleEngine.ts      |  23 +-
 .../lib/audio/engines/undertale/definition.ts |  70 ++++
 .../src/lib/audio/engines/undertale/index.ts  |   1 +
 webapp/src/lib/audio/instrumentFactory.ts     | 106 ++----
 webapp/src/lib/audio/instruments/index.ts     |  29 ++
 webapp/src/lib/audio/instruments/registry.ts  |  51 +++
 webapp/src/lib/audio/instruments/types.ts     |  38 ++
 webapp/src/lib/onboarding/CLAUDE.md           |   6 +-
 webapp/src/lib/onboarding/steps.ts            |  23 +-
 webapp/src/lib/utils/types.ts                 |  40 ++-
 webapp/src/stores/timelineStore.ts            |   4 +-
 27 files changed, 730 insertions(+), 487 deletions(-)
 create mode 100644 webapp/src/components/app/instruments/InstrumentParamField.vue
 create mode 100644 webapp/src/components/app/instruments/InstrumentParamsModal.vue
 create mode 100644 webapp/src/lib/audio/engines/audio-clip/definition.ts
 create mode 100644 webapp/src/lib/audio/engines/basic-synth/definition.ts
 create mode 100644 webapp/src/lib/audio/engines/smplr/definition.ts
 create mode 100644 webapp/src/lib/audio/engines/undertale/definition.ts
 create mode 100644 webapp/src/lib/audio/instruments/index.ts
 create mode 100644 webapp/src/lib/audio/instruments/registry.ts
 create mode 100644 webapp/src/lib/audio/instruments/types.ts

diff --git a/webapp/src/components/app/CLAUDE.md b/webapp/src/components/app/CLAUDE.md
index 009f1d8..8aeb2f4 100644
--- a/webapp/src/components/app/CLAUDE.md
+++ b/webapp/src/components/app/CLAUDE.md
@@ -74,18 +74,28 @@ setAutomationPoints(trackId, laneId, points): boolean
 ### Types clés (`lib/utils/types.ts`)
 
 ```typescript
-InstrumentType = "basicSynth" | "elementarySynth" | "smplr" | "undertale" | "audioTrack"
-
-// Discriminated unions pour type safety
+// InstrumentType = clé du registre d'instruments (lib/audio/instruments/registry.ts),
+// forme ouverte (string) — plus une union fermée. Un nouvel instrument
+// s'ajoute en s'enregistrant, sans modifier ce fichier.
+InstrumentType = string
+
+// InstrumentConfig = forme ouverte, à l'image d'EffectInstanceConfig : le
+// `type` est une clé du registre, les champs spécifiques (oscillatorType,
+// soundfont, attack...) vivent à plat pour rester compatibles avec les
+// projets déjà sauvegardés.
+InstrumentConfig { type: string, gain?: number, [key: string]: unknown }
+
+// Types internes documentaires par engine (utilisés par chaque `definition.ts`
+// et le constructeur de l'engine concerné, ne composent plus l'union
+// InstrumentConfig) :
 BasicSynthConfig { type: "basicSynth", oscillatorType: OscillatorType, gain? }
 SmplrConfig { type: "smplr", soundfont: string, gain? }
-ElementarySynthConfig { type: "elementarySynth", preset?, gain? }
+ElementarySynthConfig { type: "elementarySynth", preset?, gain? } // legacy, voir plus bas
 UndertaleConfig { type: "undertale", instrument: string, gain?, attack?, decay?, sustain?, release? }
 AudioTrackConfig { type: "audioTrack", gain? }
-InstrumentConfig = BasicSynthConfig | SmplrConfig | ElementarySynthConfig | UndertaleConfig | AudioTrackConfig
 
-// Pour les updates partiels (sans discriminant)
-InstrumentConfigUpdate { oscillatorType?, soundfont?, preset?, gain? }
+// Pour les updates partiels : Partial<InstrumentConfig> (plus d'interface
+// InstrumentConfigUpdate séparée à faire grossir à chaque nouveau type)
 
 EQBand {
   id: string          // "sub", "bass", "mid", "presence", "brilliance"
@@ -169,29 +179,53 @@ existantes. Les anciens projets (positions en "colonnes", 1 colonne = 1
 double-croche) sont migrés automatiquement au chargement (`timelineStore.ts`,
 `migrateLegacyProject`).
 
+### Registre d'instruments (`lib/audio/instruments/`)
+
+Registre extensible façon plugin, sur le modèle du [système d'effets](#système-deffets-libaudioeffects) (même esprit "proche de WAM dans la forme") — remplace l'ancien switch fermé. Contrairement aux effets (paramètres strictement numériques), les instruments ont aussi des réglages à choix fermé (waveform, soundfont, preset), d'où un discriminant `kind` sur les métadonnées :
+
+```
+lib/audio/instruments/
+  types.ts     # InstrumentParamMeta = NumericInstrumentParamMeta ("number") | EnumInstrumentParamMeta ("enum")
+               # EnumInstrumentParamMeta.options: Option[] | "dynamic" (liste connue seulement après
+               # chargement d'une ressource par l'engine, ex: presets Undertale — résolue via
+               # InstrumentEngine.getParamOptions(paramId))
+  registry.ts  # InstrumentDefinition { type, label, icon?, params, createDefaultConfig(), engine }
+               # registerInstrument/getInstrumentDefinition/listInstrumentDefinitions/createInstrumentEngine
+  index.ts     # Enregistre les 4 instruments intégrés au chargement du module
+```
+
+Chaque `InstrumentDefinition` concrète est colocalisée avec son engine (`engines/basic-synth/definition.ts`, etc.) plutôt que regroupée ici — le registre reste générique, les détails (bornes ADSR, liste de soundfonts) sont propres à chaque engine.
+
+`lib/audio/instrumentFactory.ts` reste le point d'entrée utilisé par les stores (signature stable) : adaptateur fin qui délègue au registre pour tout type connu, et garde en dur le seul cas legacy `elementarySynth → BasicSynthEngine` (jamais eu de vrai moteur, plus proposé à la création — voir plus bas).
+
 ### Engines Audio (`lib/audio/engines/`)
 
 Architecture modulaire avec classe de base abstraite :
 
 ```
 engines/
-  types.ts              # InstrumentEngine, EngineState, EngineStateCallback
+  types.ts              # InstrumentEngine, EngineState, EngineStateCallback, getParamOptions?()
   BaseEngine.ts         # Classe abstraite avec state management
   noteUtils.ts          # noteNameToFrequency() partagé
   index.ts              # Re-exports publics
 
   basic-synth/
     BasicSynthEngine.ts # Oscillateurs Web Audio (toujours ready)
+    definition.ts        # InstrumentDefinition (enum oscillatorType)
 
   smplr/
     SmplrEngine.ts      # Soundfonts via `smplr` (128+ instruments)
     soundfonts.ts       # SOUNDFONT_LIST + SoundfontName
+    definition.ts        # InstrumentDefinition (enum soundfont, options dérivées de SOUNDFONT_LIST)
 
   undertale/
-    UndertaleEngine.ts  # Soundfont custom Undertale avec ADSR
-```
+    UndertaleEngine.ts  # Soundfont custom Undertale avec ADSR, getParamOptions("instrument")
+    definition.ts        # InstrumentDefinition (enum instrument "dynamic" + 4 params ADSR numériques)
 
-Factory : `lib/audio/instrumentFactory.ts` - Crée les instances d'engines selon le type.
+  audio-clip/
+    AudioClipEngine.ts  # Lecture de clips audio (pas de synthèse)
+    definition.ts        # InstrumentDefinition (params: [])
+```
 
 ### Bibliothèque de samples (Audiothèque)
 
@@ -318,10 +352,12 @@ Le playback engine, l'export et l'enregistrement voix dépendent l'un de l'autre
 
 #### Instruments (`components/app/instruments/`)
 
-| Composant                | Rôle                                                    |
-| ------------------------ | ------------------------------------------------------- |
-| `InstrumentSettings.vue` | Panneau latéral : volume, pile d'effets (`EffectRack`), options instrument |
-| `TrackEqualizer.vue`     | Canvas EQ 5 bandes interactif (drag points), réutilisé par `EffectSlot.vue` |
+| Composant                    | Rôle                                                    |
+| ----------------------------- | ------------------------------------------------------- |
+| `InstrumentSettings.vue`      | Panneau latéral : volume, pile d'effets (`EffectRack`), bouton d'ouverture des réglages instrument |
+| `InstrumentParamsModal.vue`   | Modale (`BaseModal`) : rendu générique des `params` de l'`InstrumentDefinition` (via `InstrumentParamField`) |
+| `InstrumentParamField.vue`    | Un champ de réglage instrument, `RangeSlider` (number) ou `<select>` (enum, options statiques ou dynamiques) |
+| `TrackEqualizer.vue`         | Canvas EQ 5 bandes interactif (drag points), réutilisé par `EffectSlot.vue` |
 
 #### Effets (`components/app/effects/`)
 
@@ -389,7 +425,7 @@ cloneEQBands()                // Clone profond des bandes EQ
 - [ ] Synchronisation audio multi-pistes (timing précis)
 - [x] Gestion mémoire des engines (dispose correct)
 - [ ] Persistance localStorage avec le nouveau format v5.0 (grille en ticks)
-- [ ] ElementarySynth non implémenté (fallback sur BasicSynth)
+- [x] ElementarySynth non implémenté — retiré du catalogue "Ajouter une piste" (non enregistré dans le registre), fallback legacy sur BasicSynth conservé dans `instrumentFactory.ts` pour les pistes déjà sauvegardées avec ce type
 
 ### Bugs résolus
 
@@ -409,7 +445,6 @@ cloneEQBands()                // Clone profond des bandes EQ
 - [ ] Export audio (WAV/MP3)
 - [x] Pile d'effets réordonnable (EQ/Reverb/Compressor/Limiter/Overdrive) par piste et master
 - [ ] Zoom timeline
-- [ ] ADSR pour ElementarySynth
 - [x] Undertale soundfont engine avec ADSR
 - [ ] Audio tracks (pistes samples) - en cours
 - [x] Bibliothèque de samples connectée à R2/CDN
@@ -422,14 +457,15 @@ cloneEQBands()                // Clone profond des bandes EQ
 - **Audio** : Classes TypeScript pures (pas de dépendance Vue)
 - **Styling** : SCSS scoped avec variables CSS (`--color-*`)
 
-### Pour ajouter un nouvel Engine
+### Pour ajouter un nouvel Engine (instrument)
 
 1. Créer un dossier `engines/mon-engine/`
-2. Créer `MonEngine.ts` qui `extends BaseEngine`
-3. Implémenter les méthodes abstraites : `preload()`, `playNote()`, `stopNote()`, `stopAllNotes()`, `updateConfig()`, `dispose()`
-4. Créer `index.ts` pour re-exporter
-5. Ajouter les re-exports dans `engines/index.ts`
-6. Ajouter le case dans `instrumentFactory.ts`
+2. Créer `MonEngine.ts` qui `extends BaseEngine` — constructeur typé `config: InstrumentConfig` (narrower en interne via cast, ex. `config as MonConfig`), implémenter les méthodes abstraites : `preload()`, `playNote()`, `stopNote()`, `stopAllNotes()`, `updateConfig()`, `dispose()` (+ `getParamOptions()` si un param a des options dynamiques)
+3. Créer `definition.ts` exportant un `InstrumentDefinition` (type, label, icon?, params: `InstrumentParamMeta[]`, createDefaultConfig(), engine — caster `engine: MonEngine as unknown as InstrumentEngineConstructor`, nécessaire car le constructeur concret prend un type plus étroit que `InstrumentConfig`)
+4. Créer `index.ts` pour re-exporter la classe + la définition
+5. Enregistrer la définition dans `lib/audio/instruments/index.ts` via `registerInstrument(...)`
+
+Aucune modification requise dans `instrumentFactory.ts`, `AddTrackButton.vue` ni `InstrumentSettings.vue` — tous dérivent génériquement du registre (`listInstrumentDefinitions()` / `getInstrumentDefinition()`).
 
 ## Commandes utiles
 
diff --git a/webapp/src/components/app/instruments/InstrumentParamField.vue b/webapp/src/components/app/instruments/InstrumentParamField.vue
new file mode 100644
index 0000000..043a607
--- /dev/null
+++ b/webapp/src/components/app/instruments/InstrumentParamField.vue
@@ -0,0 +1,125 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { InstrumentParamMeta } from "../../../lib/audio/instruments";
+import RangeSlider from "../../ui/RangeSlider.vue";
+
+const props = defineProps<{
+  meta: InstrumentParamMeta;
+  modelValue: number | string;
+  dynamicOptions?: { value: string; label: string }[];
+  loading?: boolean;
+}>();
+
+const emit = defineEmits<{
+  (e: "update:modelValue", value: number | string): void;
+}>();
+
+const options = computed(() => {
+  if (props.meta.kind !== "enum") return [];
+  return props.meta.options === "dynamic"
+    ? (props.dynamicOptions ?? [])
+    : props.meta.options;
+});
+
+const displayValue = computed(() => {
+  if (props.meta.kind !== "number") return "";
+  const value = Number(props.modelValue);
+  return props.meta.toDisplay
+    ? props.meta.toDisplay(value)
+    : `${value}${props.meta.unit ?? ""}`;
+});
+
+const onNumberChange = (value: number) => emit("update:modelValue", value);
+const onEnumChange = (event: Event) => {
+  emit("update:modelValue", (event.target as HTMLSelectElement).value);
+};
+</script>
+
+<template>
+  <div class="param-field">
+    <label class="param-label">{{ meta.label }}</label>
+
+    <RangeSlider
+      v-if="meta.kind === 'number'"
+      :model-value="Number(modelValue)"
+      :min="meta.min"
+      :max="meta.max"
+      :step="meta.step"
+      thumb-size="small"
+      :display-value="displayValue"
+      @update:model-value="onNumberChange"
+    />
+
+    <template v-else>
+      <p v-if="meta.options === 'dynamic' && loading" class="loading-text">
+        Chargement...
+      </p>
+      <p v-else-if="options.length === 0" class="coming-soon">
+        Aucune option disponible
+      </p>
+      <select
+        v-else
+        class="param-select"
+        :value="modelValue"
+        @change="onEnumChange"
+      >
+        <option v-for="opt in options" :key="opt.value" :value="opt.value">
+          {{ opt.label }}
+        </option>
+      </select>
+    </template>
+  </div>
+</template>
+
+<style scoped lang="scss">
+.param-field {
+  margin-bottom: 20px;
+
+  &:last-child {
+    margin-bottom: 0;
+  }
+}
+
+.param-label {
+  display: block;
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: rgba(255, 255, 255, 0.6);
+  margin-bottom: 8px;
+}
+
+.param-select {
+  width: 100%;
+  padding: 10px 12px;
+  border: 1px solid var(--color-border-secondary);
+  border-radius: 6px;
+  background: var(--color-bg-primary-dark);
+  color: var(--color-white);
+  font-size: 13px;
+  cursor: pointer;
+  color-scheme: dark;
+
+  &:focus {
+    outline: none;
+    border-color: var(--color-accent2);
+  }
+
+  option {
+    background: var(--color-bg-secondary-dark);
+    text-transform: capitalize;
+  }
+}
+
+.coming-soon,
+.loading-text {
+  font-size: 13px;
+  font-style: italic;
+  color: rgba(255, 255, 255, 0.6);
+}
+
+.loading-text {
+  color: var(--color-accent2);
+}
+</style>
diff --git a/webapp/src/components/app/instruments/InstrumentParamsModal.vue b/webapp/src/components/app/instruments/InstrumentParamsModal.vue
new file mode 100644
index 0000000..5430b04
--- /dev/null
+++ b/webapp/src/components/app/instruments/InstrumentParamsModal.vue
@@ -0,0 +1,105 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import type { Track } from "../../../lib/utils/types";
+import { useTimelineStore } from "../../../stores/timelineStore";
+import { useTrackAudioStore } from "../../../stores/trackAudioStore";
+import { getInstrumentDefinition } from "../../../lib/audio/instruments";
+import BaseModal from "../../ui/BaseModal.vue";
+import BaseButton from "../../ui/BaseButton.vue";
+import InstrumentParamField from "./InstrumentParamField.vue";
+
+const props = defineProps<{
+  track: Track;
+  modelValue: boolean;
+}>();
+
+const emit = defineEmits<{
+  "update:modelValue": [value: boolean];
+}>();
+
+const timelineStore = useTimelineStore();
+const trackAudioStore = useTrackAudioStore();
+
+const definition = computed(() =>
+  getInstrumentDefinition(props.track.instrument.type),
+);
+
+const engineState = computed(() =>
+  trackAudioStore.getTrackEngineState(props.track.id),
+);
+
+const getParamValue = (paramId: string, fallback: number | string) => {
+  const value = props.track.instrument[paramId];
+  return typeof value === "number" || typeof value === "string"
+    ? value
+    : fallback;
+};
+
+const getDynamicOptions = (paramId: string) => {
+  return trackAudioStore.getEngine(props.track.id)?.getParamOptions?.(paramId);
+};
+
+const handleParamChange = (paramId: string, value: number | string) => {
+  timelineStore.updateTrackInstrument(props.track.id, { [paramId]: value });
+  trackAudioStore.updateTrackInstrument(props.track.id, { [paramId]: value });
+};
+
+const handleClose = () => emit("update:modelValue", false);
+</script>
+
+<template>
+  <BaseModal
+    :model-value="modelValue"
+    size="large"
+    modal-class="instrument-params-modal"
+    @update:model-value="(v) => emit('update:modelValue', v)"
+  >
+    <template #header>
+      <h3>
+        <span v-if="definition?.icon">{{ definition.icon }}</span>
+        {{ definition?.label ?? "Instrument" }}
+      </h3>
+    </template>
+
+    <div v-if="definition && definition.params.length > 0" class="params-list">
+      <InstrumentParamField
+        v-for="meta in definition.params"
+        :key="meta.id"
+        :meta="meta"
+        :model-value="getParamValue(meta.id, meta.defaultValue)"
+        :dynamic-options="
+          meta.kind === 'enum' && meta.options === 'dynamic'
+            ? getDynamicOptions(meta.id)
+            : undefined
+        "
+        :loading="
+          meta.kind === 'enum' &&
+          meta.options === 'dynamic' &&
+          engineState === 'loading'
+        "
+        @update:model-value="(value) => handleParamChange(meta.id, value)"
+      />
+    </div>
+    <p v-else class="coming-soon">
+      Paramètres non disponibles pour cet instrument.
+    </p>
+
+    <template #footer>
+      <BaseButton
+        class="close-instrument-params-btn"
+        variant="secondary"
+        @click="handleClose"
+      >
+        Fermer
+      </BaseButton>
+    </template>
+  </BaseModal>
+</template>
+
+<style scoped>
+.coming-soon {
+  font-size: 13px;
+  font-style: italic;
+  color: rgba(255, 255, 255, 0.6);
+}
+</style>
diff --git a/webapp/src/components/app/instruments/InstrumentSettings.vue b/webapp/src/components/app/instruments/InstrumentSettings.vue
index 204a8de..3bb2b71 100644
--- a/webapp/src/components/app/instruments/InstrumentSettings.vue
+++ b/webapp/src/components/app/instruments/InstrumentSettings.vue
@@ -1,12 +1,11 @@
 <script setup lang="ts">
-import { computed } from "vue";
-import type { Track, OscillatorType } from "../../../lib/utils/types";
+import { computed, ref } from "vue";
+import type { Track } from "../../../lib/utils/types";
 import { useTimelineStore } from "../../../stores/timelineStore";
-import { useTrackAudioStore } from "../../../stores/trackAudioStore";
-import { SOUNDFONT_LIST, UndertaleEngine } from "../../../lib/audio/engines";
-import RangeSlider from "../../ui/RangeSlider.vue";
+import { getInstrumentDefinition } from "../../../lib/audio/instruments";
 import EffectParamRow from "../effects/EffectParamRow.vue";
 import EffectRack from "../effects/EffectRack.vue";
+import InstrumentParamsModal from "./InstrumentParamsModal.vue";
 
 const props = defineProps<{
   track: Track;
@@ -18,107 +17,12 @@ const emit = defineEmits<{
 }>();
 
 const timelineStore = useTimelineStore();
-const trackAudioStore = useTrackAudioStore();
 
-const instrumentType = computed(() => props.track.instrument.type);
+const definition = computed(() =>
+  getInstrumentDefinition(props.track.instrument.type),
+);
 
-const currentOscillatorType = computed(() => {
-  if (props.track.instrument.type === "basicSynth") {
-    return props.track.instrument.oscillatorType;
-  }
-  return "sine";
-});
-
-const currentSoundfont = computed(() => {
-  if (props.track.instrument.type === "smplr") {
-    return props.track.instrument.soundfont;
-  }
-  return "";
-});
-
-const undertaleEngine = computed(() => {
-  if (props.track.instrument.type !== "undertale") return null;
-  const engine = trackAudioStore.getEngine(props.track.id);
-  if (engine && engine instanceof UndertaleEngine) {
-    return engine;
-  }
-  return null;
-});
-
-const undertaleInstruments = computed(() => {
-  return undertaleEngine.value?.instrumentNames ?? [];
-});
-
-const currentUndertaleInstrument = computed(() => {
-  if (props.track.instrument.type === "undertale") {
-    return props.track.instrument.instrument;
-  }
-  return "";
-});
-
-const undertaleEngineState = computed(() => {
-  return trackAudioStore.getTrackEngineState(props.track.id);
-});
-
-const undertaleAttack = computed(() => {
-  if (props.track.instrument.type === "undertale") {
-    return props.track.instrument.attack ?? 0;
-  }
-  return 0;
-});
-
-const undertaleDecay = computed(() => {
-  if (props.track.instrument.type === "undertale") {
-    return props.track.instrument.decay ?? 0;
-  }
-  return 0;
-});
-
-const undertaleSustain = computed(() => {
-  if (props.track.instrument.type === "undertale") {
-    return props.track.instrument.sustain ?? 1;
-  }
-  return 1;
-});
-
-const undertaleRelease = computed(() => {
-  if (props.track.instrument.type === "undertale") {
-    return props.track.instrument.release ?? 0.3;
-  }
-  return 0.3;
-});
-
-const oscillatorTypes: OscillatorType[] = [
-  "sine",
-  "square",
-  "sawtooth",
-  "triangle",
-];
-
-const handleOscillatorChange = (type: OscillatorType) => {
-  timelineStore.updateTrackInstrument(props.track.id, { oscillatorType: type });
-  trackAudioStore.updateTrackInstrument(props.track.id, {
-    oscillatorType: type,
-  });
-};
-
-const handleSoundfontChange = (soundfont: string) => {
-  timelineStore.updateTrackInstrument(props.track.id, { soundfont });
-  trackAudioStore.updateTrackInstrument(props.track.id, { soundfont });
-};
-
-const handleUndertaleInstrumentChange = (instrument: string) => {
-  timelineStore.updateTrackInstrument(props.track.id, { instrument });
-  trackAudioStore.updateTrackInstrument(props.track.id, { instrument });
-};
-
-const handleADSRChange = (
-  param: "attack" | "decay" | "sustain" | "release",
-  value: number,
-) => {
-  timelineStore.updateTrackInstrument(props.track.id, { [param]: value });
-  trackAudioStore.updateTrackInstrument(props.track.id, { [param]: value });
-};
+const showInstrumentModal = ref(false);
 
 const handleVolumeChange = (volume: number) => {
   timelineStore.setTrackVolume(props.track.id, volume);
@@ -161,147 +65,22 @@ const handleClose = () => {
               <EffectRack :track-id="track.id" :effects="track.effects" />
             </div>
 
-            <template v-if="instrumentType === 'basicSynth'">
-              <div class="setting-group">
-                <label class="setting-label">Forme d'onde</label>
-                <div class="waveform-selector">
-                  <button
-                    v-for="waveform in oscillatorTypes"
-                    :key="waveform"
-                    class="waveform-btn"
-                    :class="{
-                      active: currentOscillatorType === waveform,
-                    }"
-                    @click="handleOscillatorChange(waveform)"
-                  >
-                    {{ waveform }}
-                  </button>
-                </div>
-              </div>
-            </template>
-
-            <template v-else-if="instrumentType === 'smplr'">
-              <div class="setting-group">
-                <label class="setting-label">Instrument</label>
-                <select
-                  class="soundfont-select instrument-select"
-                  :value="currentSoundfont"
-                  @change="
-                    handleSoundfontChange(
-                      ($event.target as HTMLSelectElement).value,
-                    )
-                  "
-                >
-                  <option v-for="sf in SOUNDFONT_LIST" :key="sf" :value="sf">
-                    {{ sf.replace(/_/g, " ") }}
-                  </option>
-                </select>
-              </div>
-            </template>
-
-            <template v-else-if="instrumentType === 'undertale'">
-              <div class="setting-group">
-                <label class="setting-label">Preset Undertale</label>
-                <template v-if="undertaleEngineState === 'loading'">
-                  <p class="loading-text">Chargement du soundfont...</p>
-                </template>
-                <template v-else-if="undertaleInstruments.length > 0">
-                  <select
-                    class="soundfont-select instrument-select"
-                    :value="currentUndertaleInstrument"
-                    @change="
-                      handleUndertaleInstrumentChange(
-                        ($event.target as HTMLSelectElement).value,
-                      )
-                    "
-                  >
-                    <option
-                      v-for="inst in undertaleInstruments"
-                      :key="inst"
-                      :value="inst"
-                    >
-                      {{ inst }}
-                    </option>
-                  </select>
-                </template>
-                <template v-else>
-                  <p class="coming-soon">Aucun preset disponible</p>
-                </template>
-              </div>
-
-              <div class="setting-group">
-                <label class="setting-label">Enveloppe ADSR</label>
-                <div class="adsr-controls">
-                  <div class="adsr-slider">
-                    <span class="adsr-label">A</span>
-                    <RangeSlider
-                      :model-value="undertaleAttack"
-                      :min="0"
-                      :max="2"
-                      :step="0.01"
-                      thumb-size="small"
-                      :display-value="`${undertaleAttack.toFixed(2)}s`"
-                      @update:model-value="
-                        (value) => handleADSRChange('attack', value)
-                      "
-                    />
-                  </div>
-                  <div class="adsr-slider">
-                    <span class="adsr-label">D</span>
-                    <RangeSlider
-                      :model-value="undertaleDecay"
-                      :min="0"
-                      :max="2"
-                      :step="0.01"
-                      thumb-size="small"
-                      :display-value="`${undertaleDecay.toFixed(2)}s`"
-                      @update:model-value="
-                        (value) => handleADSRChange('decay', value)
-                      "
-                    />
-                  </div>
-                  <div class="adsr-slider">
-                    <span class="adsr-label">S</span>
-                    <RangeSlider
-                      :model-value="undertaleSustain"
-                      :min="0"
-                      :max="1"
-                      :step="0.01"
-                      thumb-size="small"
-                      :display-value="`${(undertaleSustain * 100).toFixed(0)}%`"
-                      @update:model-value="
-                        (value) => handleADSRChange('sustain', value)
-                      "
-                    />
-                  </div>
-                  <div class="adsr-slider">
-                    <span class="adsr-label">R</span>
-                    <RangeSlider
-                      :model-value="undertaleRelease"
-                      :min="0"
-                      :max="3"
-                      :step="0.01"
-                      thumb-size="small"
-                      :display-value="`${undertaleRelease.toFixed(2)}s`"
-                      @update:model-value="
-                        (value) => handleADSRChange('release', value)
-                      "
-                    />
-                  </div>
-                </div>
-              </div>
-            </template>
-
-            <template v-else-if="instrumentType === 'elementarySynth'">
-              <div class="setting-group">
-                <p class="coming-soon">Paramètres ADSR à venir...</p>
-              </div>
-            </template>
+            <div class="setting-group">
+              <button
+                class="instrument-params-btn"
+                @click="showInstrumentModal = true"
+              >
+                <span v-if="definition?.icon">{{ definition.icon }}</span>
+                Régler {{ definition?.label ?? "l'instrument" }}
+              </button>
+            </div>
           </div>
         </div>
       </div>
     </Transition>
   </Teleport>
+
+  <InstrumentParamsModal v-model="showInstrumentModal" :track="track" />
 </template>
 
 <style scoped lang="scss">
@@ -376,20 +155,18 @@ const handleClose = () => {
   margin-bottom: 8px;
 }
 
-.waveform-selector {
-  display: grid;
-  grid-template-columns: repeat(2, 1fr);
+.instrument-params-btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
   gap: 8px;
-}
-
-.waveform-btn {
-  padding: 10px;
+  padding: 10px 12px;
   border: 1px solid var(--color-border-secondary);
   border-radius: 6px;
   background: var(--color-bg-primary-dark);
   color: var(--color-white);
   font-size: 13px;
-  text-transform: capitalize;
   cursor: pointer;
   transition: all 0.15s ease;
 
@@ -397,66 +174,6 @@ const handleClose = () => {
     background: var(--color-bg-daw-active);
     border-color: rgba(var(--color-accent3-rgb), 0.7);
   }
-
-  &.active {
-    background: var(--color-accent2);
-    border-color: var(--color-accent2);
-    color: var(--color-bg-primary-dark);
-  }
-}
-
-.soundfont-select {
-  width: 100%;
-  padding: 10px 12px;
-  border: 1px solid var(--color-border-secondary);
-  border-radius: 6px;
-  background: var(--color-bg-primary-dark);
-  color: var(--color-white);
-  font-size: 13px;
-  cursor: pointer;
-  color-scheme: dark;
-
-  &:focus {
-    outline: none;
-    border-color: var(--color-accent2);
-  }
-
-  option {
-    background: var(--color-bg-secondary-dark);
-    text-transform: capitalize;
-  }
-}
-
-.coming-soon {
-  font-size: 13px;
-  color: rgba(255, 255, 255, 0.6);
-  font-style: italic;
-}
-
-.loading-text {
-  font-size: 13px;
-  color: var(--color-accent2);
-  font-style: italic;
-}
-
-.adsr-controls {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-
-.adsr-slider {
-  display: flex;
-  align-items: center;
-  gap: 10px;
-
-  .adsr-label {
-    width: 16px;
-    font-size: 12px;
-    font-weight: 700;
-    color: var(--color-accent2);
-    text-align: center;
-  }
 }
 
 .slide-enter-active,
diff --git a/webapp/src/components/app/timeline/AddTrackButton.vue b/webapp/src/components/app/timeline/AddTrackButton.vue
index 9b7701d..5df9639 100644
--- a/webapp/src/components/app/timeline/AddTrackButton.vue
+++ b/webapp/src/components/app/timeline/AddTrackButton.vue
@@ -3,6 +3,7 @@ import { vOnClickOutside } from "@vueuse/components";
 import type { InstrumentType } from "../../../lib/utils/types";
 import BaseButton from "../../ui/BaseButton.vue";
 import { useDropdown } from "../../../composables/useDropdown";
+import { listInstrumentDefinitions } from "../../../lib/audio/instruments";
 
 const emit = defineEmits<{
   (e: "add-track", type: InstrumentType): void;
@@ -14,38 +15,7 @@ const {
   close: closeMenu,
 } = useDropdown();
 
-const instruments = [
-  {
-    type: "audioTrack" as InstrumentType,
-    name: "Audio",
-    icon: "🔊",
-    description: "Piste audio pour samples et boucles",
-  },
-  {
-    type: "basicSynth" as InstrumentType,
-    name: "Synth",
-    icon: "🎹",
-    description: "Oscillateur simple (sine, square, saw, triangle)",
-  },
-  {
-    type: "elementarySynth" as InstrumentType,
-    name: "Elementary",
-    icon: "🎛️",
-    description: "Synthétiseur avancé avec ADSR",
-  },
-  {
-    type: "smplr" as InstrumentType,
-    name: "Sampler",
-    icon: "🎸",
-    description: "Instruments réalistes (piano, guitare, etc.)",
-  },
-  {
-    type: "undertale" as InstrumentType,
-    name: "Undertale",
-    icon: "💀",
-    description: "Soundfont Undertale (plusieurs presets)",
-  },
-];
+const instruments = listInstrumentDefinitions();
 
 const handleSelect = (type: InstrumentType) => {
   emit("add-track", type);
@@ -76,7 +46,7 @@ const handleSelect = (type: InstrumentType) => {
         >
           <span class="inst-icon">{{ inst.icon }}</span>
           <div class="inst-info">
-            <span class="inst-name">{{ inst.name }}</span>
+            <span class="inst-name">{{ inst.label }}</span>
             <span class="inst-desc">{{ inst.description }}</span>
           </div>
         </button>
diff --git a/webapp/src/composables/useOnboardingTour.ts b/webapp/src/composables/useOnboardingTour.ts
index 654caa9..0bd19fe 100644
--- a/webapp/src/composables/useOnboardingTour.ts
+++ b/webapp/src/composables/useOnboardingTour.ts
@@ -129,6 +129,8 @@ export function useOnboardingTour() {
     });
     if (step.id === "add-track") waitForInstrumentMenu();
     if (step.id === "open-settings") waitForSettingsOpen();
+    if (step.id === "open-instrument-params") waitForInstrumentParamsOpen();
+    if (step.id === "close-instrument-params") waitForInstrumentParamsClose();
     if (step.id === "close-settings") waitForSettingsClose();
     if (step.id === "play") waitForPlayed();
     if (step.id === "rename-project") waitForRenameInput();
@@ -152,7 +154,7 @@ export function useOnboardingTour() {
   };
 
   const waitForSettingsOpen = async () => {
-    await waitForElement(".instrument-select");
+    await waitForElement(".instrument-params-btn");
     if (
       !onboardingStore.isActive ||
       onboardingStore.currentStepIndex !== stepIndex("open-settings")
@@ -161,6 +163,26 @@ export function useOnboardingTour() {
     onboardingStore.advance();
   };
 
+  const waitForInstrumentParamsOpen = async () => {
+    await waitForElement(".instrument-params-modal .param-select");
+    if (
+      !onboardingStore.isActive ||
+      onboardingStore.currentStepIndex !== stepIndex("open-instrument-params")
+    )
+      return;
+    onboardingStore.advance();
+  };
+
+  const waitForInstrumentParamsClose = async () => {
+    await waitForElementGone(".instrument-params-modal");
+    if (
+      !onboardingStore.isActive ||
+      onboardingStore.currentStepIndex !== stepIndex("close-instrument-params")
+    )
+      return;
+    onboardingStore.advance();
+  };
+
   const waitForSettingsClose = async () => {
     await waitForElementGone(".settings-overlay");
     if (
@@ -358,7 +380,7 @@ export function useOnboardingTour() {
           (t) => t.id === onboardingStore.targetTrackId,
         );
         return track?.instrument.type === "smplr"
-          ? track.instrument.soundfont
+          ? (track.instrument as { soundfont?: string }).soundfont
           : null;
       },
       (soundfont) => {
diff --git a/webapp/src/lib/audio/engines/audio-clip/AudioClipEngine.ts b/webapp/src/lib/audio/engines/audio-clip/AudioClipEngine.ts
index 7d6d7ee..284e6da 100644
--- a/webapp/src/lib/audio/engines/audio-clip/AudioClipEngine.ts
+++ b/webapp/src/lib/audio/engines/audio-clip/AudioClipEngine.ts
@@ -1,6 +1,6 @@
 import type {
   AudioTrackConfig,
-  InstrumentConfigUpdate,
+  InstrumentConfig,
   NoteName,
 } from "../../../utils/types";
 import { BaseEngine } from "../BaseEngine";
@@ -117,7 +117,7 @@ export class AudioClipEngine extends BaseEngine {
     }
   }
 
-  updateConfig(config: InstrumentConfigUpdate): void {
+  updateConfig(config: Partial<InstrumentConfig>): void {
     if (config.gain !== undefined) {
       this.gain = config.gain;
     }
diff --git a/webapp/src/lib/audio/engines/audio-clip/definition.ts b/webapp/src/lib/audio/engines/audio-clip/definition.ts
new file mode 100644
index 0000000..03d2095
--- /dev/null
+++ b/webapp/src/lib/audio/engines/audio-clip/definition.ts
@@ -0,0 +1,17 @@
+import type { InstrumentDefinition } from "../../instruments/registry";
+import type { InstrumentEngineConstructor } from "../types";
+import type { AudioTrackConfig } from "../../../utils/types";
+import { AudioClipEngine } from "./AudioClipEngine";
+
+export const audioClipDefinition: InstrumentDefinition = {
+  type: "audioTrack",
+  label: "Audio",
+  icon: "🔊",
+  description: "Piste audio pour samples et boucles",
+  params: [],
+  createDefaultConfig: (): AudioTrackConfig => ({
+    type: "audioTrack",
+    gain: 1,
+  }),
+  engine: AudioClipEngine as unknown as InstrumentEngineConstructor,
+};
diff --git a/webapp/src/lib/audio/engines/audio-clip/index.ts b/webapp/src/lib/audio/engines/audio-clip/index.ts
index 3a445c6..58557a8 100644
--- a/webapp/src/lib/audio/engines/audio-clip/index.ts
+++ b/webapp/src/lib/audio/engines/audio-clip/index.ts
@@ -1 +1,2 @@
 export { AudioClipEngine } from "./AudioClipEngine";
+export { audioClipDefinition } from "./definition";
diff --git a/webapp/src/lib/audio/engines/basic-synth/BasicSynthEngine.ts b/webapp/src/lib/audio/engines/basic-synth/BasicSynthEngine.ts
index d003530..e72b4a3 100644
--- a/webapp/src/lib/audio/engines/basic-synth/BasicSynthEngine.ts
+++ b/webapp/src/lib/audio/engines/basic-synth/BasicSynthEngine.ts
@@ -1,6 +1,6 @@
 import type {
   BasicSynthConfig,
-  InstrumentConfigUpdate,
+  InstrumentConfig,
   NoteName,
   OscillatorType,
 } from "../../../utils/types";
@@ -95,9 +95,9 @@ export class BasicSynthEngine extends BaseEngine {
     }
   }
 
-  updateConfig(config: InstrumentConfigUpdate): void {
-    if (config.oscillatorType) {
-      this.oscillatorType = config.oscillatorType;
+  updateConfig(config: Partial<InstrumentConfig>): void {
+    if (typeof config.oscillatorType === "string") {
+      this.oscillatorType = config.oscillatorType as OscillatorType;
     }
     if (config.gain !== undefined) {
       this.gain = config.gain;
diff --git a/webapp/src/lib/audio/engines/basic-synth/definition.ts b/webapp/src/lib/audio/engines/basic-synth/definition.ts
new file mode 100644
index 0000000..7a5a44e
--- /dev/null
+++ b/webapp/src/lib/audio/engines/basic-synth/definition.ts
@@ -0,0 +1,34 @@
+import type { InstrumentDefinition } from "../../instruments/registry";
+import type { InstrumentEngineConstructor } from "../types";
+import type { BasicSynthConfig } from "../../../utils/types";
+import { BasicSynthEngine } from "./BasicSynthEngine";
+
+export const basicSynthDefinition: InstrumentDefinition = {
+  type: "basicSynth",
+  label: "Synth",
+  icon: "🎹",
+  description: "Oscillateur simple (sine, square, saw, triangle)",
+  params: [
+    {
+      kind: "enum",
+      id: "oscillatorType",
+      label: "Forme d'onde",
+      defaultValue: "sine",
+      options: [
+        { value: "sine", label: "sine" },
+        { value: "square", label: "square" },
+        { value: "sawtooth", label: "sawtooth" },
+        { value: "triangle", label: "triangle" },
+      ],
+    },
+  ],
+  createDefaultConfig: (): BasicSynthConfig => ({
+    type: "basicSynth",
+    oscillatorType: "sine",
+    gain: 1,
+  }),
+  // Le constructeur concret prend un BasicSynthConfig (plus étroit que
+  // InstrumentConfig) — cast nécessaire, chaque engine narrowe lui-même sa
+  // config en interne (voir BasicSynthEngine).
+  engine: BasicSynthEngine as unknown as InstrumentEngineConstructor,
+};
diff --git a/webapp/src/lib/audio/engines/basic-synth/index.ts b/webapp/src/lib/audio/engines/basic-synth/index.ts
index 382a674..33ee328 100644
--- a/webapp/src/lib/audio/engines/basic-synth/index.ts
+++ b/webapp/src/lib/audio/engines/basic-synth/index.ts
@@ -1 +1,2 @@
 export { BasicSynthEngine } from "./BasicSynthEngine";
+export { basicSynthDefinition } from "./definition";
diff --git a/webapp/src/lib/audio/engines/smplr/SmplrEngine.ts b/webapp/src/lib/audio/engines/smplr/SmplrEngine.ts
index 2372ad9..fb540ad 100644
--- a/webapp/src/lib/audio/engines/smplr/SmplrEngine.ts
+++ b/webapp/src/lib/audio/engines/smplr/SmplrEngine.ts
@@ -1,6 +1,6 @@
 import type {
   SmplrConfig,
-  InstrumentConfigUpdate,
+  InstrumentConfig,
   NoteName,
 } from "../../../utils/types";
 import { Soundfont } from "smplr";
@@ -114,8 +114,11 @@ export class SmplrEngine extends BaseEngine {
     }
   }
 
-  updateConfig(config: InstrumentConfigUpdate): void {
-    if (config.soundfont && config.soundfont !== this.currentSoundfontName) {
+  updateConfig(config: Partial<InstrumentConfig>): void {
+    if (
+      typeof config.soundfont === "string" &&
+      config.soundfont !== this.currentSoundfontName
+    ) {
       this.stopAllNotes();
       this.soundfont = null;
       this.loadPromise = null;
diff --git a/webapp/src/lib/audio/engines/smplr/definition.ts b/webapp/src/lib/audio/engines/smplr/definition.ts
new file mode 100644
index 0000000..db93118
--- /dev/null
+++ b/webapp/src/lib/audio/engines/smplr/definition.ts
@@ -0,0 +1,30 @@
+import type { InstrumentDefinition } from "../../instruments/registry";
+import type { InstrumentEngineConstructor } from "../types";
+import type { SmplrConfig } from "../../../utils/types";
+import { SmplrEngine } from "./SmplrEngine";
+import { SOUNDFONT_LIST } from "./soundfonts";
+
+export const smplrDefinition: InstrumentDefinition = {
+  type: "smplr",
+  label: "Sampler",
+  icon: "🎸",
+  description: "Instruments réalistes (piano, guitare, etc.)",
+  params: [
+    {
+      kind: "enum",
+      id: "soundfont",
+      label: "Instrument",
+      defaultValue: "acoustic_grand_piano",
+      options: SOUNDFONT_LIST.map((sf) => ({
+        value: sf,
+        label: sf.replace(/_/g, " "),
+      })),
+    },
+  ],
+  createDefaultConfig: (): SmplrConfig => ({
+    type: "smplr",
+    soundfont: "acoustic_grand_piano",
+    gain: 1,
+  }),
+  engine: SmplrEngine as unknown as InstrumentEngineConstructor,
+};
diff --git a/webapp/src/lib/audio/engines/smplr/index.ts b/webapp/src/lib/audio/engines/smplr/index.ts
index aa9e69f..ab415de 100644
--- a/webapp/src/lib/audio/engines/smplr/index.ts
+++ b/webapp/src/lib/audio/engines/smplr/index.ts
@@ -1,2 +1,3 @@
 export { SmplrEngine } from "./SmplrEngine";
 export { SOUNDFONT_LIST, type SoundfontName } from "./soundfonts";
+export { smplrDefinition } from "./definition";
diff --git a/webapp/src/lib/audio/engines/types.ts b/webapp/src/lib/audio/engines/types.ts
index 2ae854e..280f924 100644
--- a/webapp/src/lib/audio/engines/types.ts
+++ b/webapp/src/lib/audio/engines/types.ts
@@ -1,8 +1,5 @@
-import type {
-  InstrumentConfig,
-  InstrumentConfigUpdate,
-  NoteName,
-} from "../../utils/types";
+import type { InstrumentConfig, NoteName } from "../../utils/types";
+import type { EnumInstrumentParamOption } from "../instruments/types";
 
 export type EngineState = "idle" | "loading" | "ready" | "error";
 
@@ -34,7 +31,12 @@ export interface InstrumentEngine {
   stopNote(noteId: string): void;
   stopAllNotes(): void;
 
-  updateConfig(config: InstrumentConfigUpdate): void;
+  updateConfig(config: Partial<InstrumentConfig>): void;
+
+  /** Résout les options d'un param enum "dynamic" contre l'état vivant de
+   *  cette instance (ex: presets du soundfont chargé). Absent = pas de
+   *  param dynamique pour cet engine. */
+  getParamOptions?(paramId: string): EnumInstrumentParamOption[];
 
   dispose(): void;
 }
diff --git a/webapp/src/lib/audio/engines/undertale/UndertaleEngine.ts b/webapp/src/lib/audio/engines/undertale/UndertaleEngine.ts
index aa2f484..8df0559 100644
--- a/webapp/src/lib/audio/engines/undertale/UndertaleEngine.ts
+++ b/webapp/src/lib/audio/engines/undertale/UndertaleEngine.ts
@@ -1,8 +1,9 @@
 import type {
   UndertaleConfig,
-  InstrumentConfigUpdate,
+  InstrumentConfig,
   NoteName,
 } from "../../../utils/types";
+import type { EnumInstrumentParamOption } from "../../instruments/types";
 import { Soundfont2Sampler } from "smplr";
 import { SoundFont2 } from "soundfont2";
 import { BaseEngine } from "../BaseEngine";
@@ -52,6 +53,11 @@ export class UndertaleEngine extends BaseEngine {
     return this._instrumentNames;
   }
 
+  getParamOptions(paramId: string): EnumInstrumentParamOption[] {
+    if (paramId !== "instrument") return [];
+    return this._instrumentNames.map((name) => ({ value: name, label: name }));
+  }
+
   async preload(): Promise<void> {
     if (this._state === "ready") return;
     if (this._state === "loading" && this.loadPromise) {
@@ -191,14 +197,17 @@ export class UndertaleEngine extends BaseEngine {
     }
   }
 
-  updateConfig(config: InstrumentConfigUpdate): void {
-    if (config.instrument && config.instrument !== this.currentInstrument) {
+  updateConfig(config: Partial<InstrumentConfig>): void {
+    if (
+      typeof config.instrument === "string" &&
+      config.instrument !== this.currentInstrument
+    ) {
       this.loadInstrument(config.instrument);
     }
-    if (config.attack !== undefined) this.attack = config.attack;
-    if (config.decay !== undefined) this.decay = config.decay;
-    if (config.sustain !== undefined) this.sustain = config.sustain;
-    if (config.release !== undefined) this.release = config.release;
+    if (typeof config.attack === "number") this.attack = config.attack;
+    if (typeof config.decay === "number") this.decay = config.decay;
+    if (typeof config.sustain === "number") this.sustain = config.sustain;
+    if (typeof config.release === "number") this.release = config.release;
 
     this.config = { ...this.config, ...config } as UndertaleConfig;
   }
diff --git a/webapp/src/lib/audio/engines/undertale/definition.ts b/webapp/src/lib/audio/engines/undertale/definition.ts
new file mode 100644
index 0000000..b1afb35
--- /dev/null
+++ b/webapp/src/lib/audio/engines/undertale/definition.ts
@@ -0,0 +1,70 @@
+import type { InstrumentDefinition } from "../../instruments/registry";
+import type { InstrumentEngineConstructor } from "../types";
+import type { UndertaleConfig } from "../../../utils/types";
+import { UndertaleEngine } from "./UndertaleEngine";
+
+export const undertaleDefinition: InstrumentDefinition = {
+  type: "undertale",
+  label: "Undertale",
+  icon: "💀",
+  description: "Soundfont Undertale (plusieurs presets)",
+  params: [
+    {
+      kind: "enum",
+      id: "instrument",
+      label: "Preset Undertale",
+      defaultValue: "",
+      options: "dynamic",
+    },
+    {
+      kind: "number",
+      id: "attack",
+      label: "A",
+      min: 0,
+      max: 2,
+      step: 0.01,
+      defaultValue: 0,
+      toDisplay: (value) => `${value.toFixed(2)}s`,
+    },
+    {
+      kind: "number",
+      id: "decay",
+      label: "D",
+      min: 0,
+      max: 2,
+      step: 0.01,
+      defaultValue: 0,
+      toDisplay: (value) => `${value.toFixed(2)}s`,
+    },
+    {
+      kind: "number",
+      id: "sustain",
+      label: "S",
+      min: 0,
+      max: 1,
+      step: 0.01,
+      defaultValue: 1,
+      toDisplay: (value) => `${(value * 100).toFixed(0)}%`,
+    },
+    {
+      kind: "number",
+      id: "release",
+      label: "R",
+      min: 0,
+      max: 3,
+      step: 0.01,
+      defaultValue: 0.3,
+      toDisplay: (value) => `${value.toFixed(2)}s`,
+    },
+  ],
+  createDefaultConfig: (): UndertaleConfig => ({
+    type: "undertale",
+    instrument: "",
+    gain: 1,
+    attack: 0,
+    decay: 0,
+    sustain: 1,
+    release: 0.3,
+  }),
+  engine: UndertaleEngine as unknown as InstrumentEngineConstructor,
+};
diff --git a/webapp/src/lib/audio/engines/undertale/index.ts b/webapp/src/lib/audio/engines/undertale/index.ts
index 1e27298..60bb966 100644
--- a/webapp/src/lib/audio/engines/undertale/index.ts
+++ b/webapp/src/lib/audio/engines/undertale/index.ts
@@ -1 +1,2 @@
 export { UndertaleEngine } from "./UndertaleEngine";
+export { undertaleDefinition } from "./definition";
diff --git a/webapp/src/lib/audio/instrumentFactory.ts b/webapp/src/lib/audio/instrumentFactory.ts
index e4bba09..b9f14de 100644
--- a/webapp/src/lib/audio/instrumentFactory.ts
+++ b/webapp/src/lib/audio/instrumentFactory.ts
@@ -1,88 +1,44 @@
 import type { InstrumentConfig } from "../utils/types";
+import type { InstrumentEngine } from "./engines/types";
+import { BasicSynthEngine } from "./engines";
 import {
-  AudioClipEngine,
-  BasicSynthEngine,
-  SmplrEngine,
-  UndertaleEngine,
-  type InstrumentEngine,
-} from "./engines";
+  createInstrumentEngine as createRegisteredInstrumentEngine,
+  getDefaultConfigForType as getRegisteredDefaultConfigForType,
+} from "./instruments";
+
+/**
+ * `elementarySynth` n'a jamais eu de moteur réel : fallback historique vers
+ * BasicSynth, conservé hors registre uniquement pour les pistes déjà
+ * sauvegardées avec ce type (plus proposé à la création, voir
+ * AddTrackButton.vue / listInstrumentDefinitions()).
+ */
+function createElementarySynthFallback(
+  audioContext: AudioContext,
+  destination: AudioNode,
+  config: InstrumentConfig,
+): InstrumentEngine {
+  console.warn("ElementarySynth not yet implemented, using BasicSynth");
+  return new BasicSynthEngine(audioContext, destination, {
+    type: "basicSynth",
+    oscillatorType: "sine",
+    gain: config.gain,
+  });
+}
 
 export function createInstrumentEngine(
   audioContext: AudioContext,
   destination: AudioNode,
   config: InstrumentConfig,
 ): InstrumentEngine {
-  switch (config.type) {
-    case "basicSynth":
-      return new BasicSynthEngine(audioContext, destination, config);
-
-    case "smplr":
-      return new SmplrEngine(audioContext, destination, config);
-
-    case "elementarySynth":
-      // Pour l'instant, fallback sur BasicSynth
-      // TODO: Implémenter ElementarySynthEngine
-      console.warn("ElementarySynth not yet implemented, using BasicSynth");
-      return new BasicSynthEngine(audioContext, destination, {
-        type: "basicSynth",
-        oscillatorType: "sine",
-        gain: config.gain,
-      });
-
-    case "undertale":
-      return new UndertaleEngine(audioContext, destination, config);
-
-    case "audioTrack":
-      return new AudioClipEngine(audioContext, destination, config);
-
-    default:
-      throw new Error(`Unknown instrument type: ${(config as any).type}`);
+  if (config.type === "elementarySynth") {
+    return createElementarySynthFallback(audioContext, destination, config);
   }
+  return createRegisteredInstrumentEngine(audioContext, destination, config);
 }
 
-export function getDefaultConfigForType(
-  type: InstrumentConfig["type"],
-): InstrumentConfig {
-  switch (type) {
-    case "basicSynth":
-      return {
-        type: "basicSynth",
-        oscillatorType: "sine",
-        gain: 1,
-      };
-
-    case "smplr":
-      return {
-        type: "smplr",
-        soundfont: "acoustic_grand_piano",
-        gain: 1,
-      };
-
-    case "elementarySynth":
-      return {
-        type: "elementarySynth",
-        preset: "default",
-        gain: 1,
-      };
-
-    case "undertale":
-      return {
-        type: "undertale",
-        instrument: "",
-        gain: 1,
-        attack: 0,
-        decay: 0,
-        sustain: 1,
-        release: 0.3,
-      };
-
-    case "audioTrack":
-      return {
-        type: "audioTrack",
-        gain: 1,
-      };
-
-    default:
-      throw new Error(`Unknown instrument type: ${type}`);
+export function getDefaultConfigForType(type: string): InstrumentConfig {
+  if (type === "elementarySynth") {
+    return { type: "elementarySynth", preset: "default", gain: 1 };
   }
+  return getRegisteredDefaultConfigForType(type);
 }
diff --git a/webapp/src/lib/audio/instruments/index.ts b/webapp/src/lib/audio/instruments/index.ts
new file mode 100644
index 0000000..c5311f1
--- /dev/null
+++ b/webapp/src/lib/audio/instruments/index.ts
@@ -0,0 +1,29 @@
+// Types
+export type {
+  NumericInstrumentParamMeta,
+  EnumInstrumentParamMeta,
+  EnumInstrumentParamOption,
+  InstrumentParamMeta,
+} from "./types";
+export type { InstrumentDefinition } from "./registry";
+
+// Registry
+export {
+  registerInstrument,
+  getInstrumentDefinition,
+  listInstrumentDefinitions,
+  createInstrumentEngine,
+  getDefaultConfigForType,
+} from "./registry";
+
+// Enregistrement des instruments intégrés au chargement du module
+import { registerInstrument } from "./registry";
+import { basicSynthDefinition } from "../engines/basic-synth";
+import { smplrDefinition } from "../engines/smplr";
+import { undertaleDefinition } from "../engines/undertale";
+import { audioClipDefinition } from "../engines/audio-clip";
+
+registerInstrument(basicSynthDefinition);
+registerInstrument(smplrDefinition);
+registerInstrument(undertaleDefinition);
+registerInstrument(audioClipDefinition);
diff --git a/webapp/src/lib/audio/instruments/registry.ts b/webapp/src/lib/audio/instruments/registry.ts
new file mode 100644
index 0000000..e705e14
--- /dev/null
+++ b/webapp/src/lib/audio/instruments/registry.ts
@@ -0,0 +1,51 @@
+import type {
+  InstrumentEngine,
+  InstrumentEngineConstructor,
+} from "../engines/types";
+import type { InstrumentConfig } from "../../utils/types";
+import type { InstrumentParamMeta } from "./types";
+
+export interface InstrumentDefinition {
+  type: string;
+  label: string;
+  icon?: string;
+  description?: string;
+  /** Absent du catalogue "ajouter une piste" / réglages génériques, sans être
+   *  retiré du registre (résolution createInstrumentEngine reste possible). */
+  hidden?: boolean;
+  params: InstrumentParamMeta[];
+  createDefaultConfig(): InstrumentConfig;
+  engine: InstrumentEngineConstructor;
+}
+
+const registry = new Map<string, InstrumentDefinition>();
+
+export function registerInstrument(def: InstrumentDefinition): void {
+  registry.set(def.type, def);
+}
+
+export function getInstrumentDefinition(
+  type: string,
+): InstrumentDefinition | undefined {
+  return registry.get(type);
+}
+
+export function listInstrumentDefinitions(): InstrumentDefinition[] {
+  return [...registry.values()].filter((def) => !def.hidden);
+}
+
+export function createInstrumentEngine(
+  audioContext: AudioContext,
+  destination: AudioNode,
+  config: InstrumentConfig,
+): InstrumentEngine {
+  const def = registry.get(config.type);
+  if (!def) throw new Error(`Unknown instrument type: ${config.type}`);
+  return new def.engine(audioContext, destination, config);
+}
+
+export function getDefaultConfigForType(type: string): InstrumentConfig {
+  const def = registry.get(type);
+  if (!def) throw new Error(`Unknown instrument type: ${type}`);
+  return def.createDefaultConfig();
+}
diff --git a/webapp/src/lib/audio/instruments/types.ts b/webapp/src/lib/audio/instruments/types.ts
new file mode 100644
index 0000000..46169c3
--- /dev/null
+++ b/webapp/src/lib/audio/instruments/types.ts
@@ -0,0 +1,38 @@
+// Même esprit que effects/types.ts (proche de WAM 2.0 dans la FORME, pas le
+// protocole). Contrairement aux effets (paramètres strictement numériques),
+// les instruments ont des réglages à choix fermé (waveform, soundfont,
+// preset) — d'où un discriminant `kind` sur les métadonnées.
+
+export interface NumericInstrumentParamMeta {
+  kind: "number";
+  id: string; // ex: "attack", "gain"
+  label: string;
+  unit?: string;
+  min: number;
+  max: number;
+  step?: number;
+  defaultValue: number;
+  toDisplay?: (value: number) => string;
+}
+
+export interface EnumInstrumentParamOption {
+  value: string;
+  label: string;
+}
+
+export interface EnumInstrumentParamMeta {
+  kind: "enum";
+  id: string; // ex: "oscillatorType", "soundfont", "instrument"
+  label: string;
+  defaultValue: string;
+  /**
+   * Liste statique connue à froid (waveform, soundfont) OU "dynamic" quand la
+   * liste ne peut être connue qu'après chargement d'une ressource par une
+   * instance d'engine (ex: presets d'un .sf2 chargé) — dans ce cas l'UI doit
+   * appeler InstrumentEngine.getParamOptions(paramId) sur l'instance vivante.
+   */
+  options: EnumInstrumentParamOption[] | "dynamic";
+}
+
+export type InstrumentParamMeta =
+  NumericInstrumentParamMeta | EnumInstrumentParamMeta;
diff --git a/webapp/src/lib/onboarding/CLAUDE.md b/webapp/src/lib/onboarding/CLAUDE.md
index 9d73b22..683c16f 100644
--- a/webapp/src/lib/onboarding/CLAUDE.md
+++ b/webapp/src/lib/onboarding/CLAUDE.md
@@ -15,9 +15,11 @@ styles/onboarding.css              # thème driver.js + overrides de comportemen
 - **`useOnboardingTour()`** : instancié une seule fois dans `App.vue` (survit à la navigation `/app` <-> `/app/sequencer`). Contient tous les `watch()` sur le state réel (`timelineStore`, `projectStore`) qui appellent `advance()`, plus des helpers de polling DOM (`waitForElement`, `waitForElementGone`, `waitForPositionSettle`) pour les cas où l'état pertinent n'est pas dans un store.
 - **`steps.ts`** : uniquement des données. Le champ optionnel `expandedSelector` sert quand l'élément réellement highlighté n'existe qu'après une interaction dynamique (ex: le piano roll n'apparaît qu'après double-clic sur la piste).
 
-## Les 12 étapes
+## Les 14 étapes
 
-`create-project` → `add-track` → `add-instrument` (Sampler uniquement) → `open-settings` → `select-instrument` (flûte) → `close-settings` → `add-notes` (3 notes) → `rename-project` → `play` → `save` → `export` → `confirm-export`.
+`create-project` → `add-track` → `add-instrument` (Sampler uniquement) → `open-settings` (ouvre le tiroir de piste) → `open-instrument-params` (ouvre la modale de réglages instrument, `InstrumentParamsModal.vue`) → `select-instrument` (flûte) → `close-instrument-params` (ferme la modale) → `close-settings` (ferme le tiroir) → `add-notes` (3 notes) → `rename-project` → `play` → `save` → `export` → `confirm-export`.
+
+Les étapes `open-instrument-params`/`select-instrument`/`close-instrument-params` existent car les réglages propres à l'instrument (ex: le choix du soundfont) vivent dans une modale dédiée ouverte depuis le tiroir de piste (`InstrumentSettings.vue` → bouton `.instrument-params-btn`), pas inline dans le tiroir lui-même — d'où l'étape intermédiaire d'ouverture/fermeture en plus de `open-settings`/`close-settings`. Le sélecteur cible de `select-instrument` (`.instrument-params-modal .param-select`) s'appuie sur `modal-class="instrument-params-modal"` posé explicitement sur le `BaseModal` (voir gotcha ci-dessous sur le fallthrough d'attrs) plutôt que sur la seule classe de style `.param-select`, potentiellement ambiguë si un futur instrument expose plusieurs champs enum.
 
 `export` highlight le bouton header (`.export-audio-btn`) qui ouvre la modale de choix de format ; `confirm-export` highlight la modale elle-même (`.export-format-modal`, tous ses enfants restent cliquables puisqu'ils sont dans l'élément actif de driver.js) et avance via le même watcher `lastExportedAt` qu'avant. Si l'utilisateur clique "Annuler", `waitForExportModalClose` redétecte l'absence d'overlay de progression et revient à l'étape `export` plutôt que de rester bloqué.
 
diff --git a/webapp/src/lib/onboarding/steps.ts b/webapp/src/lib/onboarding/steps.ts
index 0f882a6..81d75f5 100644
--- a/webapp/src/lib/onboarding/steps.ts
+++ b/webapp/src/lib/onboarding/steps.ts
@@ -3,7 +3,9 @@ export type OnboardingStepId =
   | "add-track"
   | "add-instrument"
   | "open-settings"
+  | "open-instrument-params"
   | "select-instrument"
+  | "close-instrument-params"
   | "close-settings"
   | "add-notes"
   | "rename-project"
@@ -57,14 +59,31 @@ export const ONBOARDING_STEPS: OnboardingStep[] = [
     description: "Cliquez sur l'icône ⚙️ de la piste pour ouvrir ses réglages.",
     side: "top",
   },
+  {
+    id: "open-instrument-params",
+    route: "app-sequencer",
+    selector: ".instrument-params-btn",
+    title: "Configurez le son",
+    description:
+      "Cliquez sur « Régler » pour ouvrir les réglages de l'instrument.",
+    side: "left",
+  },
   {
     id: "select-instrument",
     route: "app-sequencer",
-    selector: ".instrument-select",
+    selector: ".instrument-params-modal .param-select",
     title: "Choisissez la flûte",
     description:
       "Sélectionnez « flute » dans la liste pour changer le son de la piste.",
-    side: "left",
+    side: "bottom",
+  },
+  {
+    id: "close-instrument-params",
+    route: "app-sequencer",
+    selector: ".close-instrument-params-btn",
+    title: "Validez votre choix",
+    description: "Cliquez sur Fermer pour revenir à votre piste.",
+    side: "top",
   },
   {
     id: "close-settings",
diff --git a/webapp/src/lib/utils/types.ts b/webapp/src/lib/utils/types.ts
index 09d66b8..1d517d4 100644
--- a/webapp/src/lib/utils/types.ts
+++ b/webapp/src/lib/utils/types.ts
@@ -106,27 +106,38 @@ export interface LegacySequenceData {
 // Types pour le système multi-pistes (Timeline GarageBand-style)
 // ============================================
 
-export type InstrumentType =
-  "basicSynth" | "elementarySynth" | "smplr" | "undertale" | "audioTrack";
+// Clé du registre d'instruments (lib/audio/instruments/registry.ts) — plus
+// une union fermée : un futur moteur externe peut s'enregistrer sans
+// modifier ce fichier.
+export type InstrumentType = string;
 
 export type OscillatorType = "sine" | "square" | "sawtooth" | "triangle";
 
+// Types internes documentaires par engine — ne composent plus l'union
+// InstrumentConfig exportée (voir plus bas), gardés pour typer les
+// constructeurs des engines concrets et leurs `definition.ts`. L'index
+// signature est nécessaire pour rester structurellement assignable à
+// InstrumentConfig (qui en a une) — sans elle, TS refuse l'assignation d'un
+// type nommé (par opposition à un littéral) vers un type indexé.
 export interface BasicSynthConfig {
   type: "basicSynth";
   oscillatorType: OscillatorType;
   gain?: number;
+  [key: string]: unknown;
 }
 
 export interface SmplrConfig {
   type: "smplr";
   soundfont: string;
   gain?: number;
+  [key: string]: unknown;
 }
 
 export interface ElementarySynthConfig {
   type: "elementarySynth";
   preset?: string;
   gain?: number;
+  [key: string]: unknown;
 }
 
 export interface UndertaleConfig {
@@ -137,30 +148,23 @@ export interface UndertaleConfig {
   decay?: number;
   sustain?: number;
   release?: number;
+  [key: string]: unknown;
 }
 
 export interface AudioTrackConfig {
   type: "audioTrack";
   gain?: number;
+  [key: string]: unknown;
 }
 
-export type InstrumentConfig =
-  | BasicSynthConfig
-  | SmplrConfig
-  | ElementarySynthConfig
-  | UndertaleConfig
-  | AudioTrackConfig;
-
-export interface InstrumentConfigUpdate {
-  oscillatorType?: OscillatorType;
-  soundfont?: string;
-  preset?: string;
-  instrument?: string;
+// Forme ouverte, à l'image d'EffectInstanceConfig — le `type` est une clé du
+// registre d'instruments, les champs spécifiques (oscillatorType, soundfont,
+// attack...) vivent à plat pour rester compatibles avec les projets déjà
+// sauvegardés.
+export interface InstrumentConfig {
+  type: string;
   gain?: number;
-  attack?: number;
-  decay?: number;
-  sustain?: number;
-  release?: number;
+  [key: string]: unknown;
 }
 
 export interface AudioClip {
diff --git a/webapp/src/stores/timelineStore.ts b/webapp/src/stores/timelineStore.ts
index ea7f968..7144014 100644
--- a/webapp/src/stores/timelineStore.ts
+++ b/webapp/src/stores/timelineStore.ts
@@ -313,14 +313,14 @@ export const useTimelineStore = defineStore("timelineStore", () => {
   };
 
   const generateTrackName = (instrumentType: InstrumentType): string => {
-    const baseNames: Record<InstrumentType, string> = {
+    const baseNames: Record<string, string> = {
       basicSynth: "Synth",
       elementarySynth: "Elementary",
       smplr: "Sampler",
       undertale: "Undertale",
       audioTrack: "Audio",
     };
-    const baseName = baseNames[instrumentType];
+    const baseName = baseNames[instrumentType] ?? "Instrument";
     let counter = 1;
     let name = `${baseName} ${counter}`;