@djodjonx/x32-simulator 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.5](https://github.com/djodjonx/x32-simulator/compare/v0.0.4...v0.0.5) (2026-01-10)
+
+
+### Features
+
+* **cli:** fix npx execution by adding dedicated bin entry point ([1b0de49](https://github.com/djodjonx/x32-simulator/commit/1b0de498b2706c7c8caf86488c8545742344b970))
+
+### [0.0.4](https://github.com/djodjonx/x32-simulator/compare/v0.0.3...v0.0.4) (2026-01-08)
+
 ### [0.0.3](https://github.com/djodjonx/x32-simulator/compare/v0.0.2...v0.0.3) (2026-01-08)
 
 

package/README.md

@@ -160,6 +160,28 @@ The simulator covers a vast majority of the X32 OSC command set:
 
 ---
 
+## 🧪 Testing Example (E2E)
+
+The simulator is ideal for testing broadcast behavior and multi-client synchronization. When one client changes a parameter, the simulator automatically broadcasts that update to all other clients subscribed via `/xremote`.
+
+You can find a complete, runnable example of this in [examples/dual-client-e2e.ts](./examples/dual-client-e2e.ts).
+
+### Multi-Client Sync Test Snippet
+
+```typescript
+// Client A and Client B both subscribe to /xremote
+clientA.send('/xremote');
+clientB.send('/xremote');
+
+// Client A changes a fader
+clientA.send('/ch/01/mix/fader', 0.85);
+
+// Result: BOTH Client A and Client B receive the update from the simulator
+// This ensures your UI stays in sync across multiple devices.
+```
+
+---
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see [INSTALL.md](./INSTALL.md) for development instructions.

package/dist/server.cjs

@@ -6,7 +6,6 @@ let node_fs = require("node:fs");
 node_fs = require_SchemaRegistry.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_SchemaRegistry.__toESM(node_path);
-let node_url = require("node:url");
 
 //#region src/presentation/cli/server.ts
 const loadEnv = () => {
@@ -133,9 +132,9 @@ const bootstrap = async () => {
 		process.exit(0);
 	});
 };
-if (process.argv[1] === (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)) bootstrap();
 
 //#endregion
-exports.bootstrap = bootstrap;
-exports.loadEnv = loadEnv;
-exports.parseArgs = parseArgs;
+//#region src/presentation/cli/bin.ts
+bootstrap();
+
+//#endregion

package/dist/server.d.cts

@@ -1,10 +1 @@
-#!/usr/bin/env node
-//#region src/presentation/cli/server.d.ts
-declare const loadEnv: () => void;
-declare const parseArgs: (argv: string[]) => {
-  PORT: number;
-  HOST: string;
-};
-declare const bootstrap: () => Promise<void>;
-//#endregion
-export { bootstrap, loadEnv, parseArgs };
+export { };

package/dist/server.d.mts

@@ -1,10 +1 @@
-#!/usr/bin/env node
-//#region src/presentation/cli/server.d.ts
-declare const loadEnv: () => void;
-declare const parseArgs: (argv: string[]) => {
-  PORT: number;
-  HOST: string;
-};
-declare const bootstrap: () => Promise<void>;
-//#endregion
-export { bootstrap, loadEnv, parseArgs };
+export { };

package/dist/server.mjs

@@ -3,7 +3,6 @@ import { a as ConsoleLogger, i as UdpNetworkGateway, n as SchemaFactory, o as Lo
 import * as readline from "node:readline";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 
 //#region src/presentation/cli/server.ts
 const loadEnv = () => {
@@ -130,7 +129,10 @@ const bootstrap = async () => {
 		process.exit(0);
 	});
 };
-if (process.argv[1] === fileURLToPath(import.meta.url)) bootstrap();
 
 //#endregion
-export { bootstrap, loadEnv, parseArgs };
+//#region src/presentation/cli/bin.ts
+bootstrap();
+
+//#endregion
+export {  };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djodjonx/x32-simulator",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "X32 Simulator",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -21,6 +21,10 @@
       }
     }
   },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "dev": "tsdown --watch",
     "build": "tsdown",

package/.commitlintrc.json

@@ -1,3 +0,0 @@
-{
-  "extends": ["@commitlint/config-conventional"]
-}

package/.github/workflows/publish.yml

@@ -1,38 +0,0 @@
-name: Publish Package to npmjs
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-permissions:
-  id-token: write  # Required for OIDC
-  contents: write  # Required to create GitHub Releases
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      # Ensure npm is up-to-date
-      - name: Update npm
-        run: npm install -g npm@latest
-
-      - run: npm ci
-      - run: npm run build
-      - run: npm test
-      - run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Create GitHub Release
-        uses: softprops/action-gh-release@v2
-        with:
-          generate_release_notes: true
-          make_latest: true

package/.husky/commit-msg

@@ -1 +0,0 @@
-npx --no -- commitlint --edit $1

package/.husky/pre-commit

@@ -1 +0,0 @@
-npx lint-staged

package/.oxlintrc.json

@@ -1,56 +0,0 @@
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": [
-    "typescript",
-    "vitest",
-    "unicorn",
-    "oxc",
-    "import",
-    "jsdoc"
-  ],
-  "categories": {
-    "correctness": "error",
-    "suspicious": "error",
-    "pedantic": "off",
-    "style": "off",
-    "perf": "warn"
-  },
-  "rules": {
-    "import/prefer-default-export": "off",
-    "import/no-named-export": "off",
-    "unicorn/filename-case": "off",
-    "eslint/no-magic-numbers": "off",
-    "eslint/max-lines-per-function": "off",
-    "eslint/max-statements": "off",
-    "eslint/max-params": "off",
-    "eslint/max-lines": "off",
-    "unicorn/no-zero-fractions": "off",
-    "eslint/sort-keys": "off",
-    "eslint/sort-imports": "off",
-    "typescript/consistent-type-imports": "off",
-    "jsdoc/require-param-type": "off",
-    "jsdoc/require-returns-type": "off",
-    "jsdoc/require-returns": "off",
-    "typescript/no-inferrable-types": "off",
-    "unicorn/prefer-top-level-await": "off",
-    "unicorn/no-null": "off",
-    "unicorn/prevent-abbreviations": "off",
-    "eslint/id-length": "off"
-  },
-  "overrides": [
-    {
-      "files": ["tests/**/*.ts"],
-      "rules": {
-        "eslint/no-magic-numbers": "off"
-      }
-    }
-  ],
-  "settings": {
-    "vitest": {
-      "typecheck": true
-    }
-  },
-  "env": {
-    "builtin": true
-  }
-}

package/INSTALL.md

@@ -1,107 +0,0 @@
-# Development Guide
-
-This guide is for developers who want to contribute to the `x32-simulator` project or build it from source.
-
-## 📋 Prerequisites
-
-*   **Node.js**: Version 20 or higher is required.
-    *   Verify with `node -v`
-*   **npm**: Comes bundled with Node.js.
-
-## 🛠️ Setup
-
-1.  **Clone the repository:**
-    ```bash
-    git clone https://github.com/djodjonx/x32-simulator.git
-    cd x32-simulator
-    ```
-
-2.  **Install dependencies:**
-    We use `npm ci` for reliable builds based on `package-lock.json`.
-    ```bash
-    npm ci
-    ```
-
-## 💻 Development Workflow
-
-### Running in Watch Mode
-For rapid development, use the dev script. It re-bundles the project on file changes.
-```bash
-npm run dev
-```
-
-### Running Tests
-We use **Vitest** for testing.
-
-*   **Run all tests:**
-    ```bash
-    npm test
-    ```
-*   **Run with coverage:**
-    ```bash
-    npm run test:coverage
-    ```
-*   **Watch mode (TDD):**
-    ```bash
-    npm run test:watch
-    ```
-
-### Code Quality
-Ensure your code meets the project standards before committing.
-
-*   **Linting (Oxlint):**
-    ```bash
-    npm run lint
-    ```
-*   **Type Checking:**
-    ```bash
-    npm run type-check
-    ```
-
-## 🏗️ Building
-
-To build the project for production distribution:
-
-```bash
-npm run build
-```
-
-This uses `tsdown` to bundle the code into the `dist/` directory:
-*   `dist/server.mjs`: The executable CLI.
-*   `dist/index.mjs` / `.cjs`: The library entry points.
-
-## 📂 Project Structure
-
-The project follows a **Clean Architecture** / **Hexagonal** structure:
-
-```
-src/
-├── application/       # Use Cases (Business Logic orchestration)
-├── domain/            # Core Business Logic (Entities, Models, Ports)
-├── infrastructure/    # External adapters (UDP, Logging, Repositories)
-└── presentation/      # Entry points
-    ├── cli/           # CLI Server implementation
-    └── library/       # Library exports
-```
-
-## 🚀 Releasing
-
-We use `standard-version` to automate versioning and changelog generation.
-
-1.  **Create a release:**
-    ```bash
-    npm run release
-    ```
-    This command will:
-    *   Bump the version in `package.json`.
-    *   Update `CHANGELOG.md`.
-    *   Commit these changes.
-    *   Create a git tag (e.g., `v1.1.0`).
-
-2.  **Push changes:**
-    ```bash
-    git push --follow-tags
-    ```
-
-3.  **Publish:**
-    The GitHub Action workflow will automatically detect the new tag, build the project, and publish it to NPM.

package/docs/OSC-Communication.md

@@ -1,184 +0,0 @@
-# Protocol Analysis and Implementation Strategies regarding the Behringer X32 Digital Mixing Console Ecosystem
-
-## 1. Introduction to Networked Audio Control Systems
-The transition from analog to digital mixing consoles has fundamentally altered the landscape of live sound reinforcement, studio recording, and broadcast audio. Among the myriad devices that have driven this paradigm shift, the **Behringer X32** and **Midas M32** families of digital consoles stand as preeminent examples of commercial success and technical ubiquity.
-
-A central feature of these ecosystems is their capability for remote control and telemetry via standard network protocols. Unlike their analog predecessors, which relied on voltage-controlled amplifiers and physical patching, modern digital consoles operate as sophisticated computers that process audio signals via **Digital Signal Processing (DSP)** algorithms. This architecture allows the control surface—the physical faders, knobs, and buttons—to be decoupled from the audio processing engine. Consequently, the manipulation of audio parameters can be achieved not only through the physical interface but also via external software applications and automated scripts communicating over a Local Area Network (LAN).
-
-The mechanism governing this external communication is the **Open Sound Control (OSC)** protocol. Optimized for modern networking technology, OSC provides a flexible, URL-style symbolic naming scheme (e.g., `/ch/01/mix/fader`) that is significantly more human-readable and granular than the legacy MIDI standard.
-
-For the X32 ecosystem, this protocol facilitates the operation of:
-* The official **X32-Edit** software (PC/Mac/Linux)
-* The **X32-Mix** app (iPad)
-* The **Mixing Station** app (Android)
-* A host of third-party integration tools
-
----
-
-## 2. The Documentation Landscape
-A critical challenge for developers and integrators working with the X32 platform is the scarcity and incompleteness of official documentation provided by the manufacturer, Music Tribe. While Behringer released a preliminary OSC document in late 2012 (Version 1.01), it has not been officially updated to reflect substantial feature additions (Firmware 2.x, 3.x, and 4.x), such as new effects engines, extended routing options, and the "User" layer.
-
-### 2.1 The "Unofficial" Standard
-To bridge this information gap, the user community—spearheaded by researcher and developer Patrick-Gilles Maillot—undertook a massive effort to reverse-engineer the complete protocol. The resulting document, **"Unofficial X32/M32 OSC Remote Protocol,"** is widely regarded as the definitive technical reference.
-
-> **Note:** This documentation distinguishes itself by detailing data types, value ranges, and context-dependent behaviors of the network stack, such as the critical distinction between the `/subscribe` command and the `/xremote` command.
-
-The documentation is maintained in a live repository, covering nuanced differences between hardware models (X32 Rack, Core, Compact) which share a common firmware core but report different hardware identifiers.
-
----
-
-## 3. Network Transport and Architecture
-The foundation of the X32’s remote control capability is the **User Datagram Protocol (UDP)**.
-
-### 3.1 UDP vs. TCP in Audio Control
-TCP is connection-oriented, guaranteeing packet delivery via handshakes and acknowledgments (ACKs). In live mixing, however, **latency is the enemy**. If a packet containing a fader move is dropped, pausing the stream for retransmission is undesirable. The X32 network stack is therefore **stateless** and "fire-and-forget." It listens for incoming UDP datagrams, processes valid OSC messages, and sends replies to the source address without maintaining a persistent socket connection.
-
-### 3.2 Port Assignments and Addressing
-* **Target Port:** UDP Port **10023** (Hard-coded).
-* **Source Port:** Ephemeral (chosen by the client OS).
-
-**Critical Implementation Detail:** The X32 sends replies back to the *source IP* and *source port* of the incoming packet. Developers must bind to a specific local UDP socket for both sending and receiving. If the OS assigns a new port for the next message, the reply from the X32 will be sent to the original port and potentially discarded.
-
-### 3.3 Endianness and Data Representation
-The OSC specification 1.0 mandates Big-Endian (network byte order).
-* **Integers:** 32-bit signed ($i$)
-* **Floats:** 32-bit IEEE 754 ($f$)
-* **Strings:** Null-terminated ASCII ($s$)
-* **Blobs:** Int32 size count + binary data ($b$)
-
-**The Deviation:** While OSC headers are Big-Endian, the internal content of binary blobs returned by the `/meters` command is encoded in **Little-Endian** format, reflecting the internal architecture of the DSP (likely Analog Devices SHARC).
-
----
-
-## 4. Device Discovery and Enumeration
-Applications utilize the `/xinfo` mechanism to locate the console, as IP addresses may be dynamic (DHCP).
-
-### 4.1 The `/xinfo` Handshake
-1.  **Query:** Client sends `/xinfo` (Broadcast or Unicast) on port 10023.
-2.  **Response:** X32 replies with ` /xinfo ,ssss`.
-
-**Response Arguments:**
-1.  **IP Address:** The console's self-reported IP (e.g., `192.168.1.50`).
-2.  **Console Name:** User-defined network name (e.g., `X32-FOH`).
-3.  **Model Identifier:** Hardware ID used to customize UI (e.g., `X32`, `X32RACK`, `X32CORE`).
-4.  **Firmware Version:** Critical for version control and compatibility checks (e.g., `4.06`).
-
-### 4.2 Application Implementation
-A typical implementation creates a UDP socket with `SO_BROADCAST` permissions, sends the `/xinfo` packet, and employs a short timeout (e.g., 2 seconds) to listen for the "business card" response.
-
----
-
-## 5. Session Persistence and State Synchronization
-Since UDP is stateless, the X32 does not inherently know if a client is "connected." To support real-time animation of faders, the protocol implements a subscription-based heartbeat.
-
-### 5.1 The `/xremote` Command
-* **Function:** Acts as a subscription request.
-* **Behavior:** The X32 adds the sender to an internal list of "active remote clients" and mirrors **every** parameter change on the console to that client.
-* **Timeout:** A watchdog timer (approx. 10 seconds) purges clients if no further command is received.
-* **Keep-Alive:** Clients must resend `/xremote` in a background loop (every 7–9 seconds) to reset the watchdog.
-
-### 5.2 `/xremote` vs. `/subscribe`
-* **`/xremote`**: The "firehose" command. Requests *all* console changes. Efficient for full desktop editors.
-* **`/subscribe`**: Requests updates for specific addresses or ranges. Efficient for mobile apps focusing on specific features.
-
-For intercepting active channel info, `/xremote` is superior as it guarantees any selection change is broadcast without a priori knowledge.
-
----
-
-## 6. Intercepting Active Channel Information
-"Active Channel" refers to the channel currently selected by the **SEL** button on the hardware surface.
-
-### 6.1 The `/-stat/selidx` Command
-The X32 broadcasts the selection state via:
-* **OSC Path:** `/-stat/selidx`
-* **Data Type:** 32-bit Integer (`,i`)
-* **Value Range:** 0 to 71
-
-### 6.2 Decoding the Selection Index
-The integer corresponds to a fixed map of channel strips:
-
-| Index Range (Int) | Channel Type | Specific Channels | OSC Address Path |
-| :--- | :--- | :--- | :--- |
-| **0 – 31** | Input Channels | Channels 1 – 32 | `/ch/01` ... `/ch/32` |
-| **32 – 39** | Aux Inputs | Aux 1 – 6, USB L/R | `/auxin/01` ... |
-| **40 – 47** | FX Returns | FX 1L, 1R ... 4R | `/fxrtn/01` ... |
-| **48 – 63** | Mix Buses | Bus 1 – 16 | `/bus/01` ... |
-| **64 – 69** | Matrix Outputs | Matrix 1 – 6 | `/mtx/01` ... |
-| **70** | Main LR | Stereo Master Bus | `/main/st` |
-| **71** | Mono/Center | Mono Bus | `/main/m` |
-
-> **Important:** DCAs are absent from this range as they are control groups, not processing paths with full channel strips.
-
-### 6.3 Implementation of Interception
-To intercept this data, a custom script acts as a parallel client:
-1.  **Subscription:** Send `/xremote` to register for updates.
-2.  **Listening:** Listen on the bound UDP port.
-3.  **Parsing:** When `/-stat/selidx` is received, parse the integer.
-4.  **Logic:** Map the integer (e.g., `0`) to the channel (`Channel 1`).
-
-### 6.4 The `/-prefs/autosel` Variable
-* **autosel ON:** Touching a fader triggers `/-stat/selidx`.
-* **autosel OFF:** Only pressing the "Select" button triggers the message.
-
----
-
-## 7. Information About Channels: Command Hierarchy
-The root address for inputs is `/ch/` using a two-digit string index (`01`–`32`).
-
-### 7.1 Functional Blocks
-
-**Configuration (`/config`)**
-* `/ch/{n}/config/name`: String (User name)
-* `/ch/{n}/config/icon`: Integer (Icon index)
-* `/ch/{n}/config/color`: Integer (Color index)
-
-**Preamp (`/preamp`)**
-* `/ch/{n}/preamp/gain`: Float (0.0–1.0 mapping to -12dB to +60dB)
-* `/ch/{n}/preamp/rtnsw`: Integer (48V Phantom Power, 0/1)
-
-**Gate & Dynamics (`/gate`, `/dyn`)**
-* `/ch/{n}/gate/on`: Integer (Active/Bypass)
-* `/ch/{n}/dyn/ratio`: Enum (Compression ratio)
-
-**Equalizer (`/eq`)**
-* `/ch/{n}/eq/{b}/f`: Float (Frequency, log mapping 20Hz–20kHz)
-* `/ch/{n}/eq/{b}/g`: Float (Gain, -15dB to +15dB)
-
-**Mix & Fader (`/mix`)**
-* `/ch/{n}/mix/fader`: Float (Level, 0.75 ≈ 0dB)
-* `/ch/{n}/mix/on`: Integer (**Note:** 1 = Unmuted/On, 0 = Muted/Off)
-* `/ch/{n}/mix/pan`: Float (0.0 = Left, 1.0 = Right)
-
-### 7.2 "Sends on Fader" Telemetry
-Scripts can monitor `/-stat/sendsonfader` (0/1) to detect this mode. If active, fader moves control bus sends rather than the main mix.
-
----
-
-## 8. Metering and Bulk Data Transfer
-To avoid network flooding, metering is handled via OSC Blobs.
-
-### 8.1 The `/meters` Command
-Request: `/meters ,s "/meters/1"` (where `/meters/1` covers input channels).
-
-### 8.2 Blob Structure and Endianness
-The response uses ` /meters ,b <binary_data>`.
-1.  **Size (Int32):** Big-Endian
-2.  **Count (Int32):** **Little-Endian**
-3.  **Data (Float32 Array):** **Little-Endian**
-
-**Critical:** Developers must switch byte-parsing logic after extracting the blob header to avoid nonsensical numeric values.
-
----
-
-## 9. Application Analysis: X32-Edit
-The official software follows this blueprint:
-1.  **Startup:** Broadcast `/xinfo`.
-2.  **Connect:** Establish unicast UDP session to port 10023.
-3.  **Sync:** Send `/xremote` and dump console state (via `/status` or node requests).
-4.  **Operation:** Loop `/xremote` every ~9s; process `/ch/...` and `/meters` updates.
-5.  **Termination:** Stop heartbeat; session times out.
-
----
-
-## 10. Conclusion
-The Behringer X32 OSC protocol is a robust system for remote audio control. By utilizing **UDP port 10023**, initiating discovery via **/xinfo**, and maintaining session persistence via **/xremote**, developers can effectively communicate with the console. Furthermore, intercepting "Active Channel" information is achievable by monitoring the **`/-stat/selidx`** command within an active subscription, enabling the creation of sophisticated custom controllers and automated workflows.