@devaloop/devalang 0.0.1-beta.2 → 0.0.1-beta.3

package/Cargo.toml

@@ -1,81 +1,84 @@
-[package]
-name = "devalang"
-version = "0.0.1-beta.2"
-authors = ["Devaloop <contact@devaloop.com>"]
-description = "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text."
-license = "MIT"
-repository = "https://github.com/devaloop-labs/devalang"
-keywords = ["music", "dsl", "audio", "cli"]
-categories = ["command-line-utilities", "development-tools", "parser-implementations"]
-readme = "README.md"
-homepage = "https://devalang.com"
-documentation = "https://docs.devalang.com/"
-edition = "2024"
-
-[[bin]]
-name = "devalang"
-path = "rust/main.rs"
-
-[lib]
-name = "devalang_core"
-path = "rust/lib.rs"
-crate-type = ["cdylib", "rlib"]
-
-[profile.release]
-opt-level = "s"
-
-[features]
-default = ["cli"]
-cli = ["crossterm", "indicatif", "inquire", "zip", "reqwest", "flate2", "tokio"]
-
-[dependencies]
-devalang_types = { path = "rust/types", version = "0.0.3" }
-clap = { version = "4.5", features = ["derive"] }
-serde = { version = "1.0", features = ["derive"] }
-serde_json = "1.0"
-rodio = "0.17"
-hound = "3.4.0"
-toml = "0.8"
-notify = "6.1"
-fs_extra = "1.3"
-include_dir = "0.7"
-wasm-bindgen = "0.2"
-serde-wasm-bindgen = "0.4"
-nom_locate = "4.0.0"
-chrono = "0.4"
-crossterm =  { version = "0.27", optional = true }
-indicatif = { version = "0.17", optional = true }
-inquire = { version = "0.7.5", optional = true }
-js-sys = "0.3"
-getrandom = { version = "0.3", features = ["wasm_js"] }
-reqwest = { version = "0.12.22", optional = true, features = ["json"] }
-flate2 = { version = "1.0", optional = true }
-tokio = { version = "1", features = ["full"], optional = true }
-zip = { version = "4.3.0", optional = true }
-rayon = "1.10.0"
-webbrowser = "0.8"
-tiny_http = "0.9.0"
-dirs = "5"
-urlencoding = "2.1"
-uuid = { version = "1.18.0", features = ["v4"] }
-console_error_panic_hook = "0.1.7"
-midly = "0.5.3"
-
-[dev-dependencies]
-assert_cmd = "2"
-predicates = "2"
-tempfile = "3"
-
-# For wasm32, enable wasm-friendly randomness backends and avoid
-# pulling in native-only CLI dependencies.
-[target.'cfg(target_arch = "wasm32")'.dependencies]
-getrandom = { version = "0.3", features = ["wasm_js"] }
-uuid = { version = "1.18.0", features = ["v4", "js", "rng-getrandom"] }
-# Keep a lightweight linkage to the utils crate for wasm builds without
-# enabling native CLI features.
-devalang_utils = { path = "rust/utils", default-features = false, version = "0.0.2" }
-
-# devalang_utils with CLI and wasmtime are only needed for native targets.
-[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
-devalang_utils = { path = "rust/utils", features = ["cli"], version = "0.0.2" }
-wasmtime = "19"
+[package]
+name = "devalang"
+version = "0.0.1-beta.3"
+authors = ["Devaloop <contact@devaloop.com>"]
+description = "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text."
+license = "MIT"
+repository = "https://github.com/devaloop-labs/devalang"
+license-file = "LICENSE"
+keywords = ["music", "dsl", "audio", "cli", "synthesis"]
+categories = ["command-line-utilities", "development-tools", "parser-implementations"]
+readme = "README.md"
+homepage = "https://devalang.com"
+documentation = "https://docs.devalang.com/"
+edition = "2024"
+
+[[bin]]
+name = "devalang"
+path = "rust/main.rs"
+
+[lib]
+name = "devalang_core"
+path = "rust/lib.rs"
+crate-type = ["cdylib", "rlib"]
+
+[profile.release]
+opt-level = "s"
+
+[features]
+default = ["cli"]
+cli = ["crossterm", "indicatif", "inquire", "zip", "reqwest", "flate2", "tokio"]
+
+[dependencies]
+devalang_types = { path = "rust/types", version = "0.0.4" }
+devalang_bindings = { path = "rust/bindings", version = "0.0.1" }
+devalang_macros = { path = "rust/macros", version = "0.0.1" }
+clap = { version = "4.5", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+rodio = "0.17"
+hound = "3.4.0"
+toml = "0.8"
+notify = "6.1"
+fs_extra = "1.3"
+include_dir = "0.7"
+wasm-bindgen = "0.2"
+serde-wasm-bindgen = "0.4"
+nom_locate = "4.0.0"
+chrono = "0.4"
+crossterm =  { version = "0.27", optional = true }
+indicatif = { version = "0.17", optional = true }
+inquire = { version = "0.7.5", optional = true }
+js-sys = "0.3"
+getrandom = { version = "0.3", features = ["wasm_js"] }
+reqwest = { version = "0.12.22", optional = true, features = ["json"] }
+flate2 = { version = "1.0", optional = true }
+tokio = { version = "1", features = ["full"], optional = true }
+zip = { version = "4.3.0", optional = true }
+rayon = "1.10.0"
+webbrowser = "0.8"
+tiny_http = "0.9.0"
+dirs = "5"
+urlencoding = "2.1"
+uuid = { version = "1.18.0", features = ["v4"] }
+console_error_panic_hook = "0.1.7"
+midly = "0.5.3"
+
+[dev-dependencies]
+assert_cmd = "2"
+predicates = "2"
+tempfile = "3"
+
+# For wasm32, enable wasm-friendly randomness backends and avoid
+# pulling in native-only CLI dependencies.
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+getrandom = { version = "0.3", features = ["wasm_js"] }
+uuid = { version = "1.18.0", features = ["v4", "js", "rng-getrandom"] }
+# Keep a lightweight linkage to the utils crate for wasm builds without
+# enabling native CLI features.
+devalang_utils = { path = "rust/utils", default-features = false, version = "0.0.3" }
+
+# devalang_utils with CLI and wasmtime are only needed for native targets.
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+devalang_utils = { path = "rust/utils", features = ["cli"], version = "0.0.3" }
+wasmtime = "19"

package/README.md

@@ -32,9 +32,8 @@ From studio sketches to live sets, Devalang gives you rhythmic control — with
 >
 > Includes synthesis, playback, and rendering features, but is still in early development, and breaking changes may occur.
 >
-> **NEW**: [Devaforge is now available for creating addons](https://github.com/devaloop-labs/devaforge).
+> **NEW**: [Devalang WORKSHOP is now available](https://workshop.devalang.com).
 >
-> **NEW**: Now available for Windows, Linux, and macOS.
 
 ## 📚 Quick Access
 
@@ -192,6 +191,8 @@ devalang play --repeat
 
 ## 📰 What's new
 
+- **Effects chaining**: Added support for chaining multiple effects on synths and samples.
+- **New addons system**: Revamped the addons system for better management and integration.
 - **MIDI export**: Added the ability to export MIDI files from Devalang scripts.
 - **Synthesizer improvements**: Enhanced the built-in synthesizer with new types and modulation options.
 - **Devaforge**: Introduced a new system for creating and managing addons, including a CLI for addon generation.

package/docs/CHANGELOG.md

@@ -4,6 +4,47 @@
 
 # Changelog
 
+## Version 0.0.1-beta.3 (2025-09-20)
+
+### ✨ Language Features
+
+- Implemented `synth` effects chaining to apply effects to individual synth notes.
+  - Example: `mySynth -> note(C4) -> slide({ duration: 2000 }) -> reverb({ room_size: 0.8 })`
+
+### 🛠️ CLI & Addons
+
+- Introduced a unified addon manager and removed the legacy `install` / `bank` commands:
+
+  - Use `devalang addon install <publisher>.<name>` to install banks or plugins.
+  - Use `devalang addon remove <publisher>.<name>` to remove banks or plugins.
+  - Use `devalang addon list` to list installed addons.
+
+- Improved the `discover` workflow:
+
+  - Recursively scans `.deva` for compiled archives (`.tar.gz` / `.tgz`) and proposes them for installation.
+  - Pre-classifies addon types by inspecting archive contents so installations can target the correct folder (bank/plugin/preset/template).
+  - Robust selection labels and mapping ensure the chosen addon is installed correctly.
+
+- Installation and extraction improvements:
+
+  - Archives are extracted into the appropriate destination based on detected type.
+  - Temporary extraction folder is cleaned up only when empty after installation.
+  - Added `--no-clear-tmp` flag to `discover` and addon install flows to preserve the temporary folder when desired.
+
+- Bugfixes: fixed selection-to-install mapping and improved success/error logging during install flows.
+
+### 🧪 Telemetry & Versioning
+
+- Telemetry now uses a runtime-first strategy to resolve the CLI version
+
+### 📦 Packaging & Tools
+
+- Added `typescript/scripts/version/copy-to-binary.ts` to copy `project-version.json` next to a packaged binary during release/packaging steps.
+
+### ✅ Bugfixes & Misc
+
+- Various fixes around temporary folder cleanup, archive detection, config updates and CLI ergonomics.
+
 ## Version 0.0.1-beta.2 (2025-09-07)
 
 ### 🛠️ MIDI & format

package/docs/ROADMAP.md

@@ -23,16 +23,16 @@ Devalang is a work in progress. Here’s what we’re planning next:
 - ✅ **Sample loading**: Add `@load` assignment to load samples (.mp3, .wav) for use as values.
 - ✅ **WASM support**: Compile Devalang to WebAssembly for use in web applications and other environments.
 - ✅ **VSCode extension**: Create a VSCode extension for syntax highlighting and code completion.
+- ✅ **Addon generator**: Implement addon generation for creating reusable plugins, banks and presets.
+- ✅ **Effect chains**: Implement effect chains for applying multiple effects to a single note or group.
 
 ## In Progress
 
-- ⏳ **Addon generator**: Implement addon generation for creating reusable plugins, banks and presets.
 - ⏳ **Testing**: Expand test coverage for all features.
+- ⏳ **Mixing & Routing**: Implement mixing and routing capabilities for advanced audio control.
 
 ## Planned
 
 - ⏳ **MIDI mapping**: Implement MIDI mapping for external control.
 - ⏳ **GUI**: Develop a graphical user interface for easier interaction.
-- ⏳ **Mixing & Routing**: Implement mixing and routing capabilities for advanced audio control.
-- ⏳ **Effect chains**: Implement effect chains for applying multiple effects to a single note or group.
 - ⏳ **Smart modules**: Let Devalang detect and use groups, samples, and variables without needing to import them manually.

package/examples/chain.deva

@@ -0,0 +1,19 @@
+let myChord = synth sine
+
+myChord -> note(C4)
+        -> arp({ pattern: "up", rate: 1/8 }) 
+        -> slide({ duration: 2000 }) 
+        -> echo({ delay: 250, feedback: 0.5 }) 
+        -> reverb({ room_size: 0.8 })
+
+myChord -> note(E4)
+        -> arp({ pattern: "up", rate: 1/8 }) 
+        -> slide({ duration: 2000 }) 
+        -> echo({ delay: 250, feedback: 0.5 }) 
+        -> reverb({ room_size: 0.8 })
+
+myChord -> note(G4)
+        -> arp({ pattern: "up", rate: 1/8 })
+        -> slide({ duration: 2000 })
+        -> echo({ delay: 250, feedback: 0.5 })
+        -> reverb({ room_size: 0.8 })

package/examples/plugin.deva

@@ -1,16 +1,16 @@
 # This is an example of using a plugin in Devalang.
-# Make sure you have the plugin installed in your Devaloop application. (devalang install plugin <author>.<plugin_name>)
+# Make sure you have the plugin installed in your Devaloop application. (devalang addon install <author>.<addon_name>)
 
 @use devaloop.acid as acidPlugin
 
-let acidSynth = synth acidPlugin.synth {
-    waveform: "saw",
-    accent: 0.1,
-    decay: 250
-}
+group acidSynthGroup:
+    let acidSynth = synth acidPlugin.synth {
+        waveform: "saw",
+        resonance: 1.0,
+    }
 
-group mySynthGroup:
-    acidSynth -> note(C4, { duration: 600 })
-    acidSynth -> note(E4, { duration: 600 })
+    acidSynth -> note(C4, { duration: 1000 })
+    acidSynth -> note(E3, { duration: 1000 })
+    acidSynth -> note(B2, { duration: 1000 })
 
-call mySynthGroup
+call acidSynthGroup

package/examples/routing.deva

@@ -0,0 +1,23 @@
+# NOTE Future version of Deva may include built-in routing capabilities.
+
+# @load "./samples/kick-808.wav" as kickCustom
+
+# group myLead:
+#     let mySynth = synth sine
+    
+#     mySynth -> note(C4, { duration: 400 })
+
+# group myKick:
+#     .kickCustom 1/4
+    
+# routing:
+#     node $master
+#     node myLead
+#     node myKick
+#     node hallReverb = effect reverb { decay: 3.0, mix: 0.5 }
+
+#     connect myLead -> hallReverb -> $master
+    
+#     connect myLead -> $master with { delay: { time: 300, feedback: 0.3 } }
+    
+#     connect myKick -> myLead with { sidechain: 0.6 }

package/out-tsc/bin/project-version.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.0.1-beta.3",
+  "channel": "beta",
+  "lastCommit": "d9c8d5927288897aebf7faceb2b3495b5b8b87eb",
+  "build": 2
+}

package/out-tsc/pkg/devalang_core_bg.wasm.d.ts

@@ -1,29 +1,29 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
-export const parse: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const collect_playhead_events: () => [number, number, number];
 export const debug_render: (a: number, b: number) => [number, number, number];
-export const render_audio: (a: number, b: number) => [number, number, number];
+export const parse: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const register_playhead_callback: (a: any) => void;
-export const collect_playhead_events: () => [number, number, number];
+export const render_audio: (a: number, b: number) => [number, number, number];
 export const unregister_playhead_callback: () => void;
-export const rust_lzma_wasm_shim_malloc: (a: number) => number;
 export const rust_lzma_wasm_shim_calloc: (a: number, b: number) => number;
 export const rust_lzma_wasm_shim_free: (a: number) => void;
+export const rust_lzma_wasm_shim_malloc: (a: number) => number;
+export const rust_lzma_wasm_shim_memchr: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memmove: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_memset: (a: number, b: number, c: number) => number;
 export const rust_lzma_wasm_shim_strlen: (a: number) => number;
-export const rust_lzma_wasm_shim_memchr: (a: number, b: number, c: number) => number;
-export const rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
-export const rust_zstd_wasm_shim_malloc: (a: number) => number;
-export const rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_calloc: (a: number, b: number) => number;
 export const rust_zstd_wasm_shim_free: (a: number) => void;
+export const rust_zstd_wasm_shim_malloc: (a: number) => number;
+export const rust_zstd_wasm_shim_memcmp: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memcpy: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memmove: (a: number, b: number, c: number) => number;
 export const rust_zstd_wasm_shim_memset: (a: number, b: number, c: number) => number;
+export const rust_zstd_wasm_shim_qsort: (a: number, b: number, c: number, d: number) => void;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store: (a: number) => void;

package/out-tsc/scripts/version/copy-to-binary.d.ts

@@ -0,0 +1 @@
+export {};

package/out-tsc/scripts/version/copy-to-binary.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const argv = process.argv.slice(2);
+let sourceArg;
+let binaryArg;
+let outDirArg;
+for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--source") {
+        sourceArg = argv[++i];
+    }
+    else if (a === "--binary") {
+        binaryArg = argv[++i];
+    }
+    else if (a === "--out-dir") {
+        outDirArg = argv[++i];
+    }
+    else if (a === "--help" || a === "-h") {
+        process.exit(0);
+    }
+    else {
+        console.error(`Unknown arg: ${a}`);
+        process.exit(1);
+    }
+}
+// Default source: attempt to locate project-version.json at repo root
+const defaultSource = path_1.default.resolve(__dirname, "..", "..", "..", "project-version.json");
+const sourcePath = sourceArg ? path_1.default.resolve(sourceArg) : defaultSource;
+if (!fs_1.default.existsSync(sourcePath)) {
+    console.error(`Source project-version.json not found at '${sourcePath}'. Please provide --source or ensure file exists.`);
+    process.exit(2);
+}
+let destDir = null;
+if (binaryArg) {
+    const binPath = path_1.default.resolve(binaryArg);
+    // If it's an existing file, use its directory, otherwise assume user passed target path and use its parent
+    if (fs_1.default.existsSync(binPath) && fs_1.default.statSync(binPath).isFile()) {
+        destDir = path_1.default.dirname(binPath);
+    }
+    else {
+        // If binPath looks like a file path (has extension) use parent, else treat as dir
+        const ext = path_1.default.extname(binPath);
+        if (ext) {
+            destDir = path_1.default.dirname(binPath);
+        }
+        else {
+            destDir = binPath;
+        }
+    }
+}
+else if (outDirArg) {
+    destDir = path_1.default.resolve(outDirArg);
+}
+else {
+    // Default: try to copy next to the running node current working dir (useful when packaging)
+    destDir = process.cwd();
+}
+if (!destDir) {
+    console.error("Could not resolve destination directory");
+    process.exit(3);
+}
+try {
+    if (!fs_1.default.existsSync(destDir)) {
+        fs_1.default.mkdirSync(destDir, { recursive: true });
+    }
+    const destPath = path_1.default.join(destDir, "project-version.json");
+    fs_1.default.copyFileSync(sourcePath, destPath);
+    console.log(`project-version.json copied to '${destPath}'`);
+    process.exit(0);
+}
+catch (err) {
+    console.error("Failed to copy project-version.json:", err);
+    process.exit(4);
+}

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@devaloop/devalang",
   "private": false,
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.3",
   "description": "Write music like code. Devalang is a domain-specific language (DSL) for sound designers and music hackers. Compose, automate, and control sound — in plain text.",
+  "longDescription": "Devalang is a compact, performant DSL and toolchain for composing, automating and rendering sound. It provides a CLI, WASM bindings, a TypeScript API, and plugins for editors. Ideal for live-coding, sample-based production, algorithmic composition, and fast prototyping.",
   "main": "out-tsc/index.js",
   "bin": {
     "devalang": "./out-tsc/bin/index.js"
@@ -18,6 +19,7 @@
     "rust:prepack": "cargo build --release",
     "scripts:postbuild": "tsc && node out-tsc/scripts/postbuild.js",
     "scripts:version:bump": "tsc && node out-tsc/scripts/version/index.js",
+    "scripts:copy-version": "tsc && node out-tsc/scripts/version/copy-to-binary.js --out-dir ./out-tsc/bin",
     "scripts:build": "tsc",
     "types:build": "tsc --emitDeclarationOnly",
     "types:wasm": "tsc && node out-tsc/scripts/copy-wasm-dts.js",
@@ -25,25 +27,36 @@
     "test:rust": "cargo test",
     "test:ts": "mocha -r ts-node/register tests/typescript/**/*.spec.ts --exit",
     "test": "npm run test:ts",
-    "postinstall": "node out-tsc/scripts/postinstall.js"
+    "postinstall": "node out-tsc/scripts/postinstall.js",
+    "beforepublish": "npm run types:all && npm run scripts:copy-version"
   },
   "homepage": "https://devalang.com",
   "keywords": [
     "devalang",
     "music",
     "sound",
-    "domain-specific language",
     "dsl",
-    "programming language",
-    "sound design",
-    "music hacking",
+    "domain-specific-language",
     "audio",
+    "music-programming",
     "synthesis",
-    "scripting",
-    "sound synthesis",
-    "music programming"
+    "midi",
+    "wasm",
+    "vscode",
+    "live-coding",
+    "sound-design",
+    "samples",
+    "cli"
   ],
-  "author": "Devaloop",
+  "author": {
+    "name": "Devaloop",
+    "email": "contact@devaloop.com",
+    "url": "https://devaloop.com"
+  },
+  "bugs": {
+    "url": "https://github.com/devaloop-labs/devalang/issues",
+    "email": "contact@devaloop.com"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/project-version.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.1-beta.2",
+  "version": "0.0.1-beta.3",
   "channel": "beta",
-  "lastCommit": "024b7abee45bdc5e034a4efd4a3f60dbd958eec0",
-  "build": 1
+  "lastCommit": "d9c8d5927288897aebf7faceb2b3495b5b8b87eb",
+  "build": 2
 }

package/rust/bindings/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "devalang_bindings"
+version = "0.0.1"
+description = "Bindings for Devalang (to use them in external contexts)"
+license = "MIT"
+authors = ["Devaloop <contact@devaloop.com>"]
+edition = "2024"
+
+[dependencies]

package/rust/bindings/src/lib.rs

@@ -0,0 +1,86 @@
+//! Minimal, focused bindings helpers for writing custom render functions in
+//! plugin crates.
+//!
+//! The core runtime already handles registration and FFI bridging. This crate
+//! only exports the types and function-signature aliases that plugin authors
+//! should implement in safe Rust. The host will convert raw buffers/pointers
+//! into these safe types before calling the plugin function.
+//!
+//! Guiding principle: plugin authors write purely safe Rust functions with
+//! clear parameters (slices and small structs). No registration helpers or
+//! global registries are provided here.
+
+/// Lightweight representation of a musical note.
+#[derive(Debug, Clone, Copy)]
+pub struct Note {
+	/// MIDI pitch 0..127
+	pub pitch: u8,
+	/// Velocity 0..127
+	pub velocity: u8,
+	/// Note duration in milliseconds (approximate)
+	pub duration_ms: u32,
+}
+
+impl Default for Note {
+	fn default() -> Self {
+		Self { pitch: 60, velocity: 100, duration_ms: 500 }
+	}
+}
+
+/// Parameters describing the output buffer and audio context.
+#[derive(Debug, Clone, Copy)]
+pub struct BufferParams {
+	/// Sample rate in Hz
+	pub sample_rate: u32,
+	/// Number of channels (1 = mono, 2 = stereo, ...)
+	pub channels: u32,
+	/// Number of frames (samples per channel) available in the buffer
+	pub frames: u32,
+}
+
+/// Helper to compute expected buffer length (frames * channels).
+impl BufferParams {
+	/// Returns the expected length of the interleaved buffer (frames * channels)
+	/// as a host-friendly `usize`. The host is responsible for converting
+	/// its platform-sized integers into these explicit-width fields.
+	pub fn buffer_len(&self) -> usize {
+		(self.frames as usize).saturating_mul(self.channels as usize)
+	}
+
+	/// Quick validation helper that plugins can call to ensure the provided
+	/// output slice matches the declared `params` length.
+	pub fn validate_buffer(out: &mut [f32], params: BufferParams) -> Result<(), &'static str> {
+		let expected = params.buffer_len();
+		if out.len() < expected { Err("output buffer too small") } else { Ok(()) }
+	}
+}
+
+impl Default for BufferParams {
+	fn default() -> Self {
+		Self { sample_rate: 44100, channels: 1, frames: 0 }
+	}
+}
+
+/// Common render function signature plugin authors should implement.
+///
+/// - `out` is a mutable slice of f32 samples (interleaved if channels > 1).
+/// - `params` provides sample rate / channels / frames info.
+/// - `note` is the Note descriptor.
+/// - `freq`/`amp` give additional voice parameters the host may pass.
+pub type RenderFn = fn(out: &mut [f32], params: BufferParams, note: Note, freq: f32, amp: f32);
+
+/// A more complete signature used by synth-style plugins that also need
+/// access to extra controls (e.g. voice index or time offset).
+pub type RenderFnExt = fn(
+	out: &mut [f32],
+	params: BufferParams,
+	note: Note,
+	freq: f32,
+	amp: f32,
+	voice_index: u32,
+	time_ms: u64,
+);
+
+/// Optional signature for control parameter setters. The host can call these
+/// safely by converting raw values into primitives.
+pub type SetParamFn = fn(param_name: &str, value: f32);