Logique de Transformation Personnalisée

Sujet avancé : Créer une logique de traitement MIDI personnalisée au-delà des nœuds intégrés

Aperçu

Note de documentation

Neurode MIDI v2 considère la source NeuroScript 2.0 comme la représentation canonique pour le routage/transformations. La création visuelle peut exister, mais elle compile en NeuroScript (aucune exigence de runtime TransformGraph/DAG).

Le scriptage en Lua est pris en charge, mais est non canonique en v2.

Bien que Neurode MIDI propose des primitives de routage/transformation intégrées, vous pouvez avoir besoin de logique personnalisée pour :

• Composition algorithmique — Des motifs génératifs, des arpégiations, des progressions d'accords
• Traitement adaptatif — Des transformations contextuelles basées sur l'analyse musicale
• Intégration matérielle — Des mappages de contrôleur spécialisés propres à votre matériel
• Effets expérimentaux — Des algorithmes personnalisés non couverts par les nœuds standards

En v2, le traitement personnalisé est exprimé en NeuroScript 2.0 (canonique) et compilé hors-thread en un plan d'exécution immuable.

---

Approche 1 : Neuroscript (Recommandé pour des logiques simples)

Neuroscript est un DSL axé sur les musiciens, optimisé pour les opérations MIDI courantes :

Quand l'utiliser

• Des transformations standard (transposition, échelle de vélocité, filtrage, remappage)
• Des scripts lisibles et maintenables pour les musiciens
• Prototypage rapide sans connaissances de programmation

Exemple : Courbe de vélocité personnalisée

# Compress loud notes, boost quiet notes
when vel > 100: vel scale 90..110
when vel < 40: vel scale 50..70
pass

Exemple : Couche conditionnelle

# Soft notes go to pad, loud notes to lead
when vel < 60: ch 1 -> ch 3
when vel >= 60: ch 1 -> ch 2
pass

Limites

• Aucun état entre les événements (chaque événement traité indépendamment)
• Aucun délai/temps (traitement synchrone uniquement)
• Opérations fixes (aucune mathématique personnalisée/aléatoire)

Référence complète : Langage Neuroscript

---

Approche 2 : Lua (Avancé / Non canonique)

Lua est disponible comme moteur de scriptage pour des logiques avancées, étatiques.

Lua est non canonique (v2)

Si vous créez des préréglages destinés à être portables/auditables, préférez NeuroScript. Lua est mieux traité comme une porte de sortie pour les utilisateurs avancés et peut avoir des limites plus strictes en v2.

Quand l'utiliser

• Des transformations étatiques où NeuroScript n'est pas suffisant encore (compteurs, comportement probabiliste)
• Des logiques expérimentales que vous ne souhaitez pas encoder comme des fonctions intégrées
• Prototypage d'une idée avant qu'elle ne devienne une fonctionnalité première de NeuroScript

Exemple : Accent de vélocité simple

-- Boost note-on velocity slightly
if event.type == "noteOn" then
  event.data2 = MIDI.clamp(event.data2 + 10)
end
return event

Exemple : Compteur étatique (Stockage de contexte)

-- Count note-on events in this script instance (local scope)
if event.type == "noteOn" then
  local count = context.get("local", "count") or 0
  count = count + 1
  context.set("local", "count", count)
end
return event

Référence : API Lua

---

Comparaison : Choisir la bonne approche

Fonctionnalité	NeuroScript	Lua
Canonique	Oui	Non (non canonique)
Détermination	Forte (plan borné)	Dépend des limites de l'engine
Facilité d'utilisation	Très facile	Moyenne
État entre les événements	Limité (dépend des fonctionnalités v2)	Oui (via le contexte)
Meilleur pour	Transformations standard, préréglages auditables	Logique avancée/personnalisée

Matrice de décision

Utilisez Neuroscript si :

• Votre logique correspond à des opérations standard (transposition, filtre, vélocité, remappage)
• Vous souhaitez des scripts lisibles et maintenables
• Vous n'avez pas besoin d'état ou de randomisation

Utilisez Lua si :

• Vous avez besoin de logique étatique ou probabiliste maintenant
• Vous acceptez que les scripts Lua puissent être moins portables que NeuroScript

---

Bonnes pratiques

1. Commencez par les nœuds intégrés

Avant d'écrire des scripts personnalisés, vérifiez si les nœuds intégrés peuvent obtenir le même résultat :

Préférez les transformations intégrées (transposition, écrêtage de vélocité, remappage de canal, etc.) lorsqu'ils existent.

Les nœuds intégrés sont plus rapides, plus maintenables et plus clairs visuellement dans le graphe.

2. Gardez vos scripts courts et ciblés

Bon (script ciblé) :

# Single responsibility: boost quiet notes
when vel < 50: vel scale 60..80
pass

Si un script dépasse 10–15 lignes, envisagez de le diviser ou de le structurer pour améliorer la lisibilité.

3. Utilisez des nœuds de surveillance pour les calculs complexes

Pour les calculs qui peuvent être coûteux, utilisez des nœuds de surveillance pour optimiser les performances.

4. Documentez vos scripts pour faciliter la maintenance

Ajoutez des commentaires clairs et des noms descriptifs pour faciliter la compréhension et la maintenance à long terme.

---

Modèle de routage NeuroScript

Le modèle de routage NeuroScript est une représentation canonique de compilation/execution (aucun runtime de graphe). Cela permet une exécution optimisée et une gestion des ressources efficace.

---

Les transformations personnalisées font partie de Neurode MIDI, un système de routage et de transformation MIDI pour iOS et macOS.