@djodjonx/x32-simulator 0.0.3 → 0.0.4

package/docs/X32-INTERNAL.md

@@ -1,262 +0,0 @@
-Voici le texte converti en format Markdown structuré et technique.
-
-# Rapport Technique Exhaustif : Conception et Implémentation d'un Simulateur de Console Numérique Behringer X32 via le Protocole Open Sound Control (OSC) en TypeScript
-
-## 1. Introduction et Contexte Architectural
-
-La conception d'un simulateur haute fidélité pour la console de mixage numérique **Behringer X32** représente un défi d'ingénierie logicielle complexe, nécessitant une maîtrise approfondie des protocoles réseaux temps réel et de l'architecture des systèmes embarqués audio. Ce rapport technique a pour objectif de fournir une spécification exhaustive pour le développement d'un émulateur "serveur" en **TypeScript**, capable d'interagir de manière indiscernable avec les clients officiels tels que l'application **X32-Mix** (macOS/iPad) et des plugins tiers communiquant via OSC.
-
-Contrairement à une simple télécommande qui envoie des commandes, un simulateur doit répliquer le comportement d'état (**"State Machine"**) de la console physique. Il doit :
-
-* Gérer les connexions concurrentes.
-* Maintenir la cohérence des données entre les clients.
-* Répondre aux mécanismes de découverte ("Handshake").
-* **Point crucial :** Générer les flux de données de vumètres ("Metering") selon un format binaire propriétaire spécifique.
-
-L'analyse des documents techniques et des travaux de rétro-ingénierie révèle que le protocole X32 OSC s'écarte des spécifications standards sur des points critiques tels que l'endianness (boutisme) des données binaires et la gestion des souscriptions.
-
----
-
-## 2. Fondamentaux du Protocole de Transport et Configuration Réseau
-
-### 2.1 Architecture UDP et Gestion des Ports
-
-Le socle de communication de l'écosystème X32 repose quasi exclusivement sur le protocole **UDP (User Datagram Protocol)**. Pour un simulateur, cela implique que la couche réseau doit être résiliente à la perte de paquets et ne pas dépendre de mécanismes de reconnexion complexes propres à TCP.
-
-* **Port d'écoute :** **10023** (Standard pour X32/M32).
-* *Note :* La série X-Air utilise le port 10024.
-
-
-* **Implémentation Node.js :** Utilisation recommandée du module natif `dgram`.
-* **Binding :** Lier le socket à `0.0.0.0` pour accepter les diffusions ("broadcasts").
-
-### 2.2 Structure des Paquets OSC et Alignement Mémoire
-
-Le protocole suit des règles d'alignement mémoire strictes (32 bits / 4 octets). Chaque composant (Address Pattern, Type Tag String, Arguments) doit être aligné.
-
-**Règle de Padding :** Si une chaîne (incluant son `\0` terminal) ne remplit pas un multiple de 4 octets, elle doit être complétée par des octets nuls.
-
-> **Exemple pour la commande `/info` :**
-> * Chaîne : `/info` (5 chars) + `\0` = 6 octets.
-> * Multiple de 4 supérieur = 8.
-> * Padding nécessaire = 2 octets nuls.
-> * Hexadécimal : `2f 69 6e 66 6f 00 00 00`
->
->
-
-Une erreur d'un seul octet rendra le paquet illisible pour X32-Mix.
-
-### 2.3 Typage des Données et Robustesse du Serveur
-
-Le simulateur doit impérativement inclure les chaînes de types (Type Tags) dans les réponses.
-
-* **Int32 (`i`)** : Entier signé 32 bits, **Big-Endian**. (Énumérations, ID, Booléens).
-* **Float32 (`f`)** : Flottant IEEE 754 32 bits, **Big-Endian**. (Niveaux, Fréquences).
-* **String (`s`)** : Chaîne ASCII terminée par nul + Padding.
-* **Blob (`b`)** : "Binary Large Object". *Voir section 6.2 pour la spécificité d'endianness.*
-
----
-
-## 3. Séquence d'Initialisation et Protocole de Découverte
-
-### 3.1 Découverte du Serveur : La commande `/info`
-
-Dès le lancement, X32-Mix émet `/info`. Le simulateur doit répondre immédiatement avec 4 arguments de type string (`,ssss`).
-
-| Argument | Valeur Type | Description |
-| --- | --- | --- |
-| **Arg 1** | `V2.05` | Version du protocole serveur. |
-| **Arg 2** | `osc-server` | Nom réseau de la console. |
-| **Arg 3** | `X32` | **Critique.** Modèle de console. Utiliser `X32`, `M32`, `X32RACK`. Une valeur inconnue bloque le chargement de l'UI. |
-| **Arg 4** | `2.12` | Version du firmware (ex: `4.06`). |
-
-### 3.2 Vérification d'État : La commande `/status`
-
-Réponse attendue (`,sss`) :
-
-1. **État :** `active` (Moteur audio fonctionnel).
-2. **IP :** Adresse IP locale du simulateur.
-3. **Nom :** Nom de la console.
-
-### 3.3 Négociation de la Session : Le mécanisme `/xremote`
-
-La X32 est un serveur passif par défaut. Le client doit s'abonner aux mises à jour.
-
-1. **Réception :** Le simulateur reçoit `/xremote`.
-2. **Enregistrement :** Ajout de l'IP/Port du client dans une "Subscribers List".
-3. **Watchdog :** Timer de 10 secondes. Sans renouvellement, le client est éjecté.
-4. **Feedback :** Tant que le client est abonné, **chaque** changement d'état interne (fader, mute) doit générer un message OSC sortant vers le client pour éviter l'effet "rubber-banding" (saut de fader).
-
----
-
-## 4. Architecture de la Carte Mémoire (Address Map)
-
-### 4.1 Hiérarchie Principale
-
-* `/ch/[01..32]` : Canaux d'entrée.
-* `/auxin/[01..08]` : Auxiliaires.
-* `/fxrtn/[01..08]` : Retours d'effets.
-* `/bus/[01..16]` : Bus de mixage.
-* `/mtx/[01..06]` : Matrices.
-* `/main/st`, `/main/m` : Sorties Master.
-* `/dca/[1..8]` : DCA.
-* `/config`, `/headamp` : Configuration et Préamplis.
-
-### 4.2 Structure d'une Tranche ("Channel Strip")
-
-Sous-modules pour `/ch/01/...` :
-
-* `/config` : `name`, `icon`, `color`.
-* `/preamp` : `trim`, `inv` (phase), `hpf` (passe-haut).
-* `/gate` : `mode`, `thr`, `attack`, `hold`, `release`.
-* `/dyn` : Compresseur (`ratio`, `thr`, `knee`, etc.).
-* `/eq` : Paramétrique 4 bandes (`/eq/1` à `/eq/4`). Paramètres : `type`, `f`, `g`, `q`.
-* `/mix` :
-* `fader` : Float (0.0 - 1.0).
-* `on` : Mute (0/1). **Attention :** Logique inversée possible selon le contexte, mais généralement 1 = Audio Passant.
-* `pan` : 0.0 (G) - 1.0 (D).
-
-
-
-### 4.3 Normalisation des Valeurs
-
-Les valeurs sont normalisées sur `[0.0, 1.0]`.
-
-* **Faders :** Non-linéaire. `0.0` = -∞ dB, `0.75` ≈ 0 dB, `1.0` = +10 dB.
-* **Fréquences :** Logarithmique (20 Hz - 20 kHz).
-
----
-
-## 5. Gestion des Scènes et Fichiers
-
-Commandes clés à supporter :
-
-* `/-action/goscene ,i [index]` : Charger une scène.
-* `/-action/setscene ,i [index]` : Définir la scène courante.
-
-Le simulateur doit parser les fichiers `.scn` (texte clair contenant des commandes OSC) et les appliquer ligne par ligne à l'état interne.
-
----
-
-## 6. Implémentation Avancée du Système de Vumètres (Metering)
-
-### 6.1 La Commande `/meters`
-
-Requête client : `/meters ,si [Chemin] [Temps]`
-
-* `/meters/0` : Global.
-* `/meters/1` : Canaux détaillés (Entrées + Gate + Dyn).
-* Mise à jour continue (~50ms) pendant 10s si Temps = 0.
-
-### 6.2 Le Format Binaire Hybride (Mixed Endianness)
-
-**Anomalie Critique :** Alors que l'en-tête OSC est en Big-Endian, le contenu du Blob ("Payload") contenant les vumètres utilise le **Little-Endian** pour les flottants.
-
-**Structure du Blob :**
-
-1. **Taille du Blob (Int32)** : **Big-Endian** (Format OSC Standard).
-2. **Taille Interne (Int32)** : **Big-Endian** (Début du Payload).
-3. **Nombre d'Éléments (Int32)** : **Little-Endian**.
-4. **Données (Float32 Array)** : **Little-Endian**.
-
-**Implémentation TypeScript :**
-L'utilisation de bibliothèques OSC standard échouera ici. Il faut construire le buffer manuellement.
-
-```typescript
-// Exemple conceptuel de génération de blob pour /meters/1 (96 valeurs)
-function generateMeterBlob(values: number[]): Buffer {
-    const numFloats = values.length; // 96
-    const headerBytes = 4; // Taille interne
-    const countBytes = 4; // Nombre d'éléments
-    const dataBytes = numFloats * 4;
-    const totalBlobSize = headerBytes + countBytes + dataBytes;
-
-    // Création du buffer pour le contenu du blob
-    const blobBuffer = Buffer.alloc(totalBlobSize);
-    let offset = 0;
-
-    // 1. Taille Interne (Big Endian) - Spécificité X32
-    blobBuffer.writeInt32BE(totalBlobSize, offset);
-    offset += 4;
-
-    // 2. Compteur d'éléments (Little Endian)
-    blobBuffer.writeInt32LE(numFloats, offset);
-    offset += 4;
-
-    // 3. Données Flottantes (Little Endian)
-    for (let i = 0; i < numFloats; i++) {
-        blobBuffer.writeFloatLE(values[i], offset);
-        offset += 4;
-    }
-
-    return blobBuffer;
-}
-
-```
-
-### 6.3 Mapping des Vumètres (`/meters/1`)
-
-* **0-31 :** Canaux 1-32 (Pre-Fader).
-* **32-63 :** Gate Gain Reduction.
-* **64-95 :** Compressor Gain Reduction.
-
----
-
-## 7. Architecture Logicielle du Simulateur en TypeScript
-
-### 7.1 Gestionnaire d'État (State Store)
-
-Utiliser une structure arborescente émettant des événements.
-
-```typescript
-type X32Parameter = number | string;
-
-class X32Node {
-    private value: X32Parameter;
-    private path: string;
-    
-    setValue(val: X32Parameter) {
-        this.value = val;
-        this.emit('change', this.path, this.value);
-    }
-}
-
-```
-
-### 7.2 Boucle de Rétroaction
-
-Le serveur UDP s'abonne au Store :
-`StateStore.on('change', (path, value) => { Server.broadcast(path, value); });`
-
----
-
-## 8. Méthodologie de Rétro-Ingénierie avec le Simulateur
-
-1. **Mode Espion (Snooping) :** Logger chaque paquet entrant pour mapper les commandes inconnues envoyées par X32-Mix.
-2. **Validation par Écho :** Envoyer périodiquement des commandes au client pour vérifier si l'UI réagit (boutons qui tournent).
-3. **Analyse Wireshark :** Filtrer sur `udp.port == 10023` pour valider les séquences d'initialisation et l'endianness des blobs.
-
----
-
-## 9. Conclusion et Tableaux Récapitulatifs
-
-La réussite du simulateur repose sur le respect strict des spécificités Behringer : **Port 10023**, **Handshake précis**, **Souscription active**, et **Endianness hybride** pour les vumètres.
-
-### Tableau Récapitulatif des Types OSC X32
-
-| Type Tag | Description | Encodage Réseau (Standard) | Encodage Vumètres (Blob Payload) |
-| --- | --- | --- | --- |
-| `,i` | Entier 32 bits | Big-Endian | N/A |
-| `,f` | Flottant 32 bits | Big-Endian | **Little-Endian** |
-| `,s` | Chaîne | ASCII + Padding | N/A |
-| `,b` | Blob | Taille en Big-Endian | **Mixte** (Taille BE, Data LE) |
-
-### Tableau des Principaux Chemins OSC
-
-| Chemin | Description | Arguments Typiques |
-| --- | --- | --- |
-| `/info` | Découverte serveur | Réponse: `,ssss` |
-| `/status` | État système | Réponse: `,sss` |
-| `/xremote` | Souscription | Aucun |
-| `/ch/[01-32]/mix/fader` | Fader Canal | `,f` [0.0 - 1.0] |
-| `/meters/[id]` | Requête Vumètres | `,b` (Blob réponse) |

package/src/application/use-cases/BroadcastUpdatesUseCase.ts

@@ -1,120 +0,0 @@
-import { SubscriptionManager } from '../../domain/entities/SubscriptionManager';
-import { INetworkGateway } from '../../domain/ports/INetworkGateway';
-import { X32State } from '../../domain/entities/X32State';
-import { SchemaRegistry } from '../../domain/services/SchemaRegistry';
-import { MeterService } from '../../domain/services/MeterService';
-import { ILogger, LogCategory } from '../../domain/ports/ILogger';
-
-export class BroadcastUpdatesUseCase {
-    constructor(
-        private subscriptionManager: SubscriptionManager,
-        private state: X32State,
-        private gateway: INetworkGateway,
-        private logger: ILogger,
-        private meterService: MeterService,
-        private schemaRegistry: SchemaRegistry
-    ) {}
-
-    public execute(): void {
-        this.subscriptionManager.getSubscribers().forEach(sub => {
-            if (sub.type === 'path' || !sub.alias) {
-                 if (sub.type === 'meter' && sub.meterPath) {
-                     const meterData = this.meterService.generateMeterData(sub.meterPath, this.state);
-                     this.gateway.send({ address: sub.address, port: sub.port }, sub.meterPath, [meterData.toBlob()]);
-                 }
-                 return; 
-            }
-  
-            const rinfo = { address: sub.address, port: sub.port };
-            
-            if (sub.type === 'batch' && sub.paths) {
-               if (sub.paths.length === 1 && sub.paths[0].startsWith('/meters')) {
-                   const meterData = this.meterService.generateMeterData(sub.paths[0], this.state);
-                   this.gateway.send(rinfo, sub.alias, [meterData.toBlob()]);
-                   return;
-               }
-  
-               let stride: number;
-               const dataSize = sub.paths.length * 4;
-               const factor = sub.factor || 0;
-               const count = sub.count || 0;
-  
-               if (factor > 0) {
-                   stride = Math.max(factor * 4, dataSize);
-               } else {
-                   stride = (sub.paths.length === 3) ? 16 : dataSize;
-               }
-               
-               const blobSize = count * stride;
-               if (isNaN(blobSize) || blobSize < 0) {
-                   this.logger.error(LogCategory.SYSTEM, `Invalid blob size`, { alias: sub.alias, blobSize, count, stride, factor, dataSize });
-                   return;
-               }
-  
-               const blob = Buffer.alloc(blobSize);
-               
-               for (let i = 0; i < count; i++) {
-                  const root = this.schemaRegistry.getRootFromIndex(sub.start! + i);
-                  let currentOffset = i * stride;
-                  
-                  if (!root) { continue; }
-                  
-                  sub.paths.forEach((s, pIdx) => {
-                      if (pIdx * 4 >= stride) return;
-  
-                      if (s.startsWith('/meters')) {
-                          blob.writeFloatLE(0.0, currentOffset);
-                      } else {
-                          const target = `${root}${s}`;
-                          const node = this.schemaRegistry.getNode(target);
-                          let val = this.state.get(target);
-                          if (val === undefined) val = node ? node.default : 0;
-                          
-                          if (typeof val === 'number') {
-                              if (node && node.type === 'f') {
-                                  blob.writeFloatLE(val, currentOffset);
-                              }
-                              else blob.writeInt32LE(val, currentOffset);
-                          } else blob.writeInt32LE(0, currentOffset);
-                      }
-                      currentOffset += 4;
-                  });
-               }
-               this.gateway.send(rinfo, sub.alias, [blob]);
-            } else if (sub.type === 'format' && sub.pattern) {
-               const stride = sub.factor ? sub.factor * 4 : 4;
-               const start = sub.start || 0;
-               const count = sub.count || 0;
-               
-               const totalSize = (start + count) * stride;
-               if (isNaN(totalSize) || totalSize < 0) return;
-  
-               const blob = Buffer.alloc(totalSize);
-               let offset = start * stride;
-               
-               for (let i = start; i < start + count; i++) {
-                  const id = i.toString().padStart(2, '0');
-                  const target = sub.pattern!.replace(/\*\*?/, id);
-                  let val = this.state.get(target);
-                  if (val === undefined) val = 0;
-                  if (typeof val === 'number') {
-                      const node = this.schemaRegistry.getNode(target);
-                      if (node && node.type === 'f') blob.writeFloatLE(val, offset);
-                      else blob.writeInt32LE(val, offset);
-                  } else blob.writeInt32LE(0, offset);
-                  offset += stride;
-               }
-               this.gateway.send(rinfo, sub.alias, [blob]);
-            }
-        });
-    }
-
-    public broadcastSingleChange(path: string, value: number | string): void {
-        this.subscriptionManager.getSubscribers().forEach(sub => {
-            const match = path === sub.path || sub.path === '/xremote' || (sub.path && sub.path.includes('*') && path.startsWith(sub.path.split('*')[0]));
-            if (match) {
-                this.gateway.send({ address: sub.address, port: sub.port }, path, [value]);
-            }
-        });
-    }
-}

package/src/application/use-cases/ManageSessionsUseCase.ts

@@ -1,9 +0,0 @@
-import { SubscriptionManager } from '../../domain/entities/SubscriptionManager';
-
-export class ManageSessionsUseCase {
-    constructor(private subscriptionManager: SubscriptionManager) {}
-
-    public cleanup(): void {
-        this.subscriptionManager.cleanup();
-    }
-}

package/src/application/use-cases/ProcessPacketUseCase.ts

@@ -1,26 +0,0 @@
-import { OscPacket, OscArgument, RemoteClient } from '../../domain/models/types';
-import { OscMessageHandler } from '../../domain/services/OscMessageHandler';
-import { INetworkGateway } from '../../domain/ports/INetworkGateway';
-
-export class ProcessPacketUseCase {
-    constructor(
-        private messageHandler: OscMessageHandler,
-        private gateway: INetworkGateway
-    ) {}
-
-    public execute(packet: OscPacket, rinfo: RemoteClient): void {
-        if (packet.oscType === 'bundle') {
-            packet.elements?.forEach((el: OscPacket) => this.execute(el, rinfo));
-        } else if (packet.oscType === 'message') {
-            const args = packet.args.map((arg: OscArgument) => {
-                if (typeof arg === 'object' && arg !== null && 'value' in arg) return arg.value;
-                return arg;
-            });
-
-            const replies = this.messageHandler.handle({ address: packet.address, args }, rinfo);
-            replies.forEach(reply => {
-                this.gateway.send(rinfo, reply.address, reply.args);
-            });
-        }
-    }
-}

package/src/application/use-cases/SimulationService.ts

@@ -1,146 +0,0 @@
-import { ProcessPacketUseCase } from './ProcessPacketUseCase';
-import { BroadcastUpdatesUseCase } from './BroadcastUpdatesUseCase';
-import { ManageSessionsUseCase } from './ManageSessionsUseCase';
-import { INetworkGateway } from '../../domain/ports/INetworkGateway';
-import { ILogger, LogCategory } from '../../domain/ports/ILogger';
-import { IStateRepository } from '../../domain/ports/IStateRepository';
-import { SubscriptionManager } from '../../domain/entities/SubscriptionManager';
-import { OscMessageHandler } from '../../domain/services/OscMessageHandler';
-import { MeterService } from '../../domain/services/MeterService';
-import { SchemaRegistry } from '../../domain/services/SchemaRegistry';
-import { StaticResponseService } from '../../domain/services/StaticResponseService';
-import * as os from 'os';
-
-/**
- * Gets the first non-internal IPv4 address found on this machine.
- * @returns Detected IP or localhost.
- */
-function getLocalIp(): string {
-    const interfaces = os.networkInterfaces();
-    for (const name of Object.keys(interfaces)) {
-        for (const iface of interfaces[name]!) {
-            if (iface.family === 'IPv4' && !iface.internal) {
-                return iface.address;
-            }
-        }
-    }
-    return '127.0.0.1';
-}
-
-/**
- * The core service that manages the X32 simulation, including networking, 
- * state management, and OSC message handling.
- */
-export class SimulationService {
-    private subscriptionManager: SubscriptionManager;
-    private messageHandler: OscMessageHandler;
-    
-    // Use Cases
-    private processPacket: ProcessPacketUseCase;
-    private broadcastUpdates: BroadcastUpdatesUseCase;
-    private manageSessions: ManageSessionsUseCase;
-
-    // Services
-    private meterService: MeterService;
-    private staticResponseService: StaticResponseService;
-
-    private updateInterval: NodeJS.Timeout | null = null;
-    private cleanupInterval: NodeJS.Timeout | null = null;
-
-    /**
-     * Creates a new SimulationService instance.
-     * @param gateway - The network gateway for OSC communication.
-     * @param logger - The logger service.
-     * @param stateRepo - The repository managing the mixer state.
-     * @param schemaRegistry - The registry for X32 OSC schema.
-     * @param port - UDP port to listen on (default 10023).
-     * @param ip - IP address to bind to (default '0.0.0.0').
-     * @param name - Reported console name.
-     * @param model - Reported console model.
-     */
-    constructor(
-        private gateway: INetworkGateway,
-        private logger: ILogger,
-        private stateRepo: IStateRepository,
-        private schemaRegistry: SchemaRegistry,
-        private port: number = 10023,
-        private ip: string = '0.0.0.0',
-        name: string = 'osc-server',
-        model: string = 'X32'
-    ) {
-        // Initialize Domain Entities
-        const state = this.stateRepo.getState();
-        this.subscriptionManager = new SubscriptionManager(logger);
-        
-        // Initialize Services
-        this.meterService = new MeterService();
-        this.staticResponseService = new StaticResponseService();
-
-        const reportedIp = (this.ip === '0.0.0.0') ? getLocalIp() : this.ip;
-        this.messageHandler = new OscMessageHandler(
-            state,
-            this.subscriptionManager,
-            logger,
-            reportedIp,
-            name,
-            model,
-            this.meterService,
-            this.schemaRegistry,
-            this.staticResponseService
-        );
-
-        // Initialize Use Cases
-        this.processPacket = new ProcessPacketUseCase(this.messageHandler, gateway);
-        this.broadcastUpdates = new BroadcastUpdatesUseCase(
-            this.subscriptionManager, 
-            state, 
-            gateway, 
-            logger,
-            this.meterService,
-            this.schemaRegistry
-        );
-        this.manageSessions = new ManageSessionsUseCase(this.subscriptionManager);
-
-        // Bind State Changes to Broadcast
-        state.on('change', (evt: { address: string, value: number | string }) => {
-            this.logger.info(LogCategory.STATE, `State Changed`, evt);
-            this.broadcastUpdates.broadcastSingleChange(evt.address, evt.value);
-        });
-
-        // Bind Gateway Packet Handling
-        this.gateway.onPacket((packet, source) => this.processPacket.execute(packet, source));
-    }
-
-    /**
-     * Starts the simulator server and internal loops.
-     */
-    public async start(): Promise<void> {
-        await this.gateway.start(this.port, this.ip);
-        
-        // Cleanup expired subscribers every 5s
-        this.cleanupInterval = setInterval(() => {
-            this.manageSessions.cleanup();
-        }, 5000);
-
-        // Send updates every 100ms
-        this.updateInterval = setInterval(() => {
-            this.broadcastUpdates.execute();
-        }, 100);
-    }
-
-    /**
-     * Stops the simulator server and stops all internal loops.
-     */
-    public async stop(): Promise<void> {
-        if (this.updateInterval) clearInterval(this.updateInterval);
-        if (this.cleanupInterval) clearInterval(this.cleanupInterval);
-        await this.gateway.stop();
-    }
-
-    /**
-     * Resets the mixer state to default values.
-     */
-    public resetState() {
-        this.stateRepo.reset();
-    }
-}