@devaloop/devalang 0.0.1-alpha.3 → 0.0.1-alpha.4

package/.devalang

@@ -1,4 +1,4 @@
 [defaults]
 entry = "./examples"
 output = "./output"
-watch = true
+watch = false

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devalang"
-version = "0.0.1-alpha.3"
+version = "0.0.1-alpha.4"
 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"
@@ -8,8 +8,8 @@ repository = "https://github.com/devaloop-labs/devalang"
 keywords = ["music", "dsl", "audio", "cli"]
 categories = ["command-line-utilities", "audio", "development-tools"]
 readme = "README.md"
-homepage = "https://devaloop.com"
-documentation = "https://docs.rs/devalang"
+homepage = "https://devalang.com"
+documentation = "https://docs.devalang.com/"
 edition = "2024"
 
 [[bin]]

package/README.md

@@ -11,43 +11,42 @@
 ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 ![Platform](https://img.shields.io/badge/platform-Windows-blue)
 
-![npm](https://img.shields.io/npm/dm/@devaloop/devalang)
+![npm](https://img.shields.io/npm/dt/@devaloop/devalang)
 
 ## 🎼 Devalang, by **Devaloop Labs**
 
 🎶 Compose music with code — simple, structured, sonic.
 
 Devalang is a tiny domain-specific language (DSL) for music makers, sound designers, and audio hackers.
-Compose loops, control samples, and automate parameters — all in clean, readable text.
+Compose loops, control samples, render and play audio — all in clean, readable text.
 
 🦊 Whether you're building a track, shaping textures, or performing live, Devalang helps you think in rhythms. It’s designed to be simple, expressive, and fast — because your ideas shouldn’t wait.
 
 From studio sketches to live sets, Devalang gives you rhythmic control — with the elegance of code.
 
-> 🚧 **v0.0.1-alpha.1 Notice** 🚧
+> 🚧 **v0.0.1-alpha.4 Notice** 🚧
 >
-> Devalang is still in early development. This version does not yet include **sound rendering**.
->
-> You can parse code, generate the AST, and validate syntax — all essential building blocks for the upcoming audio engine.
->
-> Custom instruments can be defined with `@load`, allowing any sound sample to be triggered with the same syntax.
+> **Audio Engine** is now integrated, enabling audio playback and rendering capabilities.
 >
 > Currently, Devalang CLI is only available for **Windows**.  
 > Linux and macOS binaries will be added in future releases via cross-platform builds.
 
+---
+
+## 📚 Quick Access
+
+- [📖 Documentation](./docs/)
+- [💡 Examples](./examples/)
+- [🌐 Project Website](https://devalang.com)
+
 ## 🚀 Features
 
-- 🧩 Module system for importing and exporting variables between files (`@import`, `@export`)
-- 📜 Structured AST generation for debugging and future compilation
-- 🔢 Basic data types: strings, numbers, booleans, maps, arrays
-- 👁️ Watch mode for `build` and `check` commands
-- ⏱️ `bpm` assignment for setting tempo
-- 🧱 `bank` declaration to define the instrument set
-- 🔁 Looping system with fixed repetitions (`loop 4:`)
-- 🧪 Instruction calls with parameters (e.g. `.kick auto {reverb:10, decay:20}`) for testing pattern syntax
-- 📄 `let` assignments for storing reusable values
-- 🔄 `@load` assignment to load a sample (.mp3, .wav) to use it as a value
-- 🛠️ CLI tools for syntax checking (`check`), AST output (`build`)
+- 🎵 **Audio Engine**: Integrated audio playback and rendering
+- 🧩 **Module system** for importing and exporting variables between files
+- 📜 **Structured AST** generation for debugging and future compilation
+- 🔢 **Basic data types**: strings, numbers, booleans, maps, arrays
+- 👁️ **Watch mode** for `build`, `check` and `play` commands
+- 📂 **Project templates** for quick setup
 
 ## 📆 Installation
 
@@ -79,7 +78,7 @@ npx @devaloop/devalang <command>
 > cargo install --path .
 ```
 
-Usage for development (feel free to change arguments in package.json)
+Development usage (you can customize arguments in package.json)
 
 ```bash
 # For syntax checking test
@@ -90,6 +89,12 @@ npm run rust:dev:build
 
 ## ❔ Usage
 
+NOTE: Commands are available via `devalang` or `npx @devaloop/devalang`.
+
+NOTE: Arguments can be passed to commands using `--<argument>` syntax. You can also use a configuration file to set default values for various settings, making it easier to manage your Devalang project.
+
+NOTE: Some commands require a mandatory `--entry` argument to specify the input folder, and a `--output` argument to specify the output folder. If not specified, they default to `./src` and `./output` respectively.
+
 For more examples, see [docs/COMMANDS.md](./docs/COMMANDS.md)
 
 ### Initialize a new project
@@ -109,13 +114,25 @@ devalang init --name <project-name> --template <template-name>
 ### Checking syntax only
 
 ```bash
-devalang check --entry <entry-directory> --output <output-directory> --watch
+devalang check --watch
 ```
 
 ### Building output files
 
 ```bash
-devalang build --entry <entry-directory> --output <output-directory> --watch
+devalang build --watch
+```
+
+### Playing audio files (once by file change)
+
+```bash
+devalang play --watch
+```
+
+### Playing audio files (continuous playback, even without file changes)
+
+```bash
+devalang play --repeat
 ```
 
 ## ⚙️ Configuration
@@ -135,6 +152,8 @@ For more examples, see [docs/SYNTAX.md](./docs/SYNTAX.md)
 
 @import { globalBpm, globalBank, kickDuration } from "global.deva"
 
+@load "./examples/samples/kick-808.wav" as customKick
+
 bpm globalBpm
 # Will declare the tempo at the globalBpm variable beats per minute
 
@@ -142,7 +161,7 @@ bank globalBank
 # Will declare a custom instrument bank using the globalBank variable
 
 loop 5:
-    .kick kickDuration {reverb=50, drive=25}
+    .customKick kickDuration {reverb=50, drive=25}
     # Will play 5 times a kick for the duration of the kickDuration variable with reverb and drive effects
 ```
 
@@ -158,7 +177,6 @@ let kickDuration = 500
 
 ## 🧯 Known issues
 
-- No support yet for Audio Engine
 - No support yet for `if`, `else`, `else if` statements
 - No support yet for `@group`, `@pattern`, `@function` statements
 - No support yet for cross-platform builds (Linux, macOS)
@@ -167,7 +185,6 @@ let kickDuration = 500
 
 For more info, see [docs/ROADMAP.md](./docs/ROADMAP.md)
 
-- ⏳ Audio engine integration (priority for alpha.4)
 - ⏳ Other statements (e.g `if`, `@group`, ...)
 - ⏳ Cross-platform support (Linux, macOS)
 - ⏳ More built-in instruments (e.g. snare, hi-hat, etc.)

package/docs/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 # Changelog
 
+## Version 0.0.1-alpha.4 (2025-07-03)
+
+### Audio Engine
+
+- Integrated Audio Engine to handle audio playback and rendering.
+- Implemented Audio Player to play audio files.
+- Added support for audio playback with the `play` command.
+
+### Commands
+
+- Implemented `play` command to play Devalang files.
+  - Added `--watch` option to watch for changes in files and automatically rebuild and play them. (once)
+  - Added `--repeat` option to repeat the playback of the audio file. (infinite)
+  
+  Note : You cannot use `--watch` and `--repeat` options together. Use `--repeat` instead.
+  
+
 ## Version 0.0.1-alpha.3 (2025-07-01)
 
 - /!\ Major refactor of the project structure and module system /!\

package/docs/COMMANDS.md

@@ -52,3 +52,34 @@ Available arguments :
 - `--entry`: The input folder (default to `./src`)
 - `--output`: The output folder (default to `./output`)
 - `--watch`: Whether to watch for changes and rebuild (default to `false`)
+
+
+## Playing
+
+Playing .deva file(s) without audio playback (once)
+
+```bash
+devalang play --entry ./examples --output ./output
+```
+
+Playing .deva file(s) with audio playback (once by file change)
+
+```bash
+devalang play --entry ./examples --output ./output --watch
+```
+
+Playing .deva file(s) with audio playback (infinite loop)
+
+```bash
+devalang play --entry ./examples --output ./output --repeat
+```
+
+Note : You cannot use `--watch` and `--repeat` options together. Use `--repeat` instead.
+
+Available arguments :
+
+- `--no-config`: Whether to ignore the configuration file (default to `false`)
+- `--entry`: The input folder (default to `./src`)
+- `--output`: The output folder (default to `./output`)
+- `--watch`: Whether to watch for changes and rebuild + play (default to `false`)
+- `--repeat`: Whether to repeat the playback of the audio file (default to `false`)

package/docs/CONFIG.md

@@ -18,11 +18,13 @@ The configuration file is a TOML (Tom's Obvious, Minimal Language) file that con
 [defaults]
 entry = "./src"
 output = "./output"
-watch = true
+watch = false
+repeat = true
 ```
 
 ### Available Settings
 
-- `entry`: (String) The entry point for your Devalang project
-- `output`: (String) The output directory for generated files
-- `watch`: (Boolean) Whether to watch for changes in files and automatically rebuild or check them
+- `entry`: (String) The entry point for your Devalang project (default to `./src`)
+- `output`: (String) The output directory for generated files (default to `./output`)
+- `watch`: (Boolean) Whether to watch for changes in files and automatically rebuild or check them (default to `false`)
+- `repeat`: (Boolean) Whether to repeat the playback of audio files (default to `false`)

package/docs/ROADMAP.md

@@ -8,6 +8,7 @@ Devalang is a work in progress. Here’s what we’re planning next:
 
 ### Stable
 
+- ✅ **Audio engine**: Integrate the audio engine for sound playback. 
 - ✅ **Basic syntax**: Implement the core syntax for Devalang, including data types and basic statements.
 - ✅ **Watch mode**: Add a watch mode to automatically rebuild on file changes.
 - ✅ **Module system**: Add support for importing and exporting variables between files using `@import` and `@export`.
@@ -22,7 +23,6 @@ Devalang is a work in progress. Here’s what we’re planning next:
 
 ### Upcoming
 
-- ⏳ **Audio engine**: Integrate the audio engine for sound playback. 
 - ⏳ **VSCode extension**: Create a VSCode extension for syntax highlighting and code completion.
 - ⏳ **WASM support**: Compile Devalang to WebAssembly for use in web applications.
 - ⏳ **Other statements**: Implement `if`, `else`, and other control structures.

package/docs/TODO.md

@@ -24,13 +24,13 @@ This is a list of tasks and features to be implemented in Devalang. Note that th
   - [ ] Implement debug mode
   - [ ] Implement compilation mode
   - [ ] Implement compression mode
-- [ ] Play
-  - [ ] Implement Audio Engine
-  - [ ] Implement loop mode
+- [x] Play
+  - [x] Implement Audio Engine
+  - [x] Implement loop mode
 
 ## Core components
 
-- [ ] Audio Engine
+- [x] Audio Engine
 - [x] Lexer
 - [x] Parser
 - [x] Preprocessor

package/examples/index.deva

@@ -1,10 +1,16 @@
 @import { duration, default_bank, params, loopCount, tempo } from "./examples/exported.deva"
 
 @load "./examples/samples/kick-808.wav" as sample
+@load "./examples/samples/hat-808.wav" as hat
 
 bpm tempo
 
 bank default_bank
 
 loop loopCount:
-    .sample duration params
+    .sample duration params
+
+    # Uncomment the next line (.hat) while executing "play" command 
+    # with `--repeat` option to see magic happen !
+
+    # .hat duration params

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "@devaloop/devalang",
-  "private": false,
-  "version": "0.0.1-alpha.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.",
-  "main": "out-tsc/index.js",
-  "bin": {
-    "devalang": "./out-tsc/bin/index.js"
-  },
-  "scripts": {
-    "prepublish": "cargo build --release && npm run script:postbuild",
-    "rust:dev:build": "cargo run build --entry examples --output output",
-    "rust:dev:check": "cargo run check --entry examples --output output",
-    "script:postbuild": "tsc && node out-tsc/scripts/postbuild.js",
-    "script:version:bump": "tsc && node out-tsc/scripts/version/index.js"
-  },
-  "homepage": "https://devaloop.com",
-  "keywords": [
-    "devalang",
-    "music",
-    "sound",
-    "domain-specific language",
-    "dsl",
-    "programming language",
-    "sound design",
-    "music hacking",
-    "audio",
-    "synthesis",
-    "scripting",
-    "sound synthesis",
-    "music programming"
-  ],
-  "author": "Devaloop",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/devaloop-labs/devalang.git"
-  },
-  "dependencies": {
-    "@types/node": "^24.0.3"
-  }
+{
+  "name": "@devaloop/devalang",
+  "private": false,
+  "version": "0.0.1-alpha.4",
+  "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.",
+  "main": "out-tsc/index.js",
+  "bin": {
+    "devalang": "./out-tsc/bin/index.js"
+  },
+  "scripts": {
+    "prepublish": "cargo build --release && npm run script:postbuild",
+    "rust:dev:build": "cargo run build --entry examples --output output",
+    "rust:dev:check": "cargo run check --entry examples --output output",
+    "script:postbuild": "tsc && node out-tsc/scripts/postbuild.js",
+    "script:version:bump": "tsc && node out-tsc/scripts/version/index.js"
+  },
+  "homepage": "https://devalang.com",
+  "keywords": [
+    "devalang",
+    "music",
+    "sound",
+    "domain-specific language",
+    "dsl",
+    "programming language",
+    "sound design",
+    "music hacking",
+    "audio",
+    "synthesis",
+    "scripting",
+    "sound synthesis",
+    "music programming"
+  ],
+  "author": "Devaloop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devaloop-labs/devalang.git"
+  },
+  "dependencies": {
+    "@types/node": "^24.0.3"
+  }
 }

package/project-version.json

@@ -1,6 +1,6 @@
-{
-  "version": "0.0.1-alpha.3",
-  "channel": "alpha",
-  "lastCommit": "850fd73787ae41844d6669017ee3d01699b2df3c",
-  "build": 2
-}
+{
+  "version": "0.0.1-alpha.4",
+  "channel": "alpha",
+  "lastCommit": "ca5336b3cd3f2189971e9e99a93a66042faff007",
+  "build": 3
+}

package/rust/audio/engine.rs

@@ -0,0 +1,130 @@
+use std::{ collections::HashMap, fs::File, io::BufReader };
+use hound::{ SampleFormat, WavSpec, WavWriter };
+use rodio::{ Decoder, Source };
+
+use crate::core::{
+    parser::statement::Statement,
+    store::variable::VariableTable,
+    utils::path::normalize_path,
+};
+
+const SAMPLE_RATE: u32 = 44100;
+const CHANNELS: u16 = 2;
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct AudioEngine {
+    pub volume: f32,
+    pub variables: VariableTable,
+    pub buffer: Vec<i16>,
+}
+
+impl AudioEngine {
+    pub fn new() -> Self {
+        AudioEngine {
+            volume: 1.0,
+            buffer: vec![],
+            variables: VariableTable::new(),
+        }
+    }
+
+    pub fn mix(&mut self, other: &AudioEngine) {
+        let max_len = self.buffer.len().max(other.buffer.len());
+        self.buffer.resize(max_len, 0);
+
+        for (i, &sample) in other.buffer.iter().enumerate() {
+            self.buffer[i] = self.buffer[i].saturating_add(sample);
+        }
+    }
+
+    pub fn set_duration(&mut self, duration_secs: f32) {
+        let mut total_samples = (duration_secs * (SAMPLE_RATE as f32) * (CHANNELS as f32)) as usize;
+
+        if total_samples % (CHANNELS as usize) != 0 {
+            total_samples += 1;
+        }
+
+        self.buffer.resize(total_samples, 0);
+    }
+
+    pub fn set_variables(&mut self, variables: VariableTable) {
+        self.variables = variables;
+    }
+
+    pub fn generate_wav_file(&mut self, output_dir: &String) -> Result<(), String> {
+        if self.buffer.len() % (CHANNELS as usize) != 0 {
+            self.buffer.push(0);
+            println!("Completed buffer to respect stereo format.");
+        }
+
+        let spec = WavSpec {
+            channels: CHANNELS,
+            sample_rate: SAMPLE_RATE,
+            bits_per_sample: 16,
+            sample_format: SampleFormat::Int,
+        };
+
+        let mut writer = WavWriter::create(output_dir, spec).map_err(|e|
+            format!("Error creating WAV file: {}", e)
+        )?;
+
+        for sample in &self.buffer {
+            writer.write_sample(*sample).map_err(|e| format!("Error writing sample: {:?}", e))?;
+        }
+
+        writer.finalize().map_err(|e| format!("Error finalizing WAV: {:?}", e))?;
+
+        Ok(())
+    }
+
+    pub fn insert(
+        &mut self,
+        filepath: &str,
+        time_secs: f32,
+        dur_sec: f32,
+        effects: Option<HashMap<String, f32>>
+    ) {
+        let normalized_filepath = normalize_path(filepath);
+
+        let file = BufReader::new(
+            File::open(normalized_filepath).expect("Failed to open audio file")
+        );
+        let decoder = Decoder::new(file).expect("Failed to decode audio file");
+
+        // Mono or stereo reading possible here, we will duplicate in L/R
+        let max_mono_samples = (dur_sec * (SAMPLE_RATE as f32)) as usize;
+        let samples: Vec<i16> = decoder.convert_samples().take(max_mono_samples).collect();
+
+        if samples.is_empty() {
+            eprintln!("No samples found in the audio file: {}", filepath);
+            return;
+        }
+
+        // TODO Apply effects here if needed
+        let offset = (time_secs * (SAMPLE_RATE as f32) * (CHANNELS as f32)) as usize;
+        let required_len = offset + samples.len() * (CHANNELS as usize);
+        let padded_required_len = if required_len % 2 == 1 {
+            required_len + 1
+        } else {
+            required_len
+        };
+
+        self.buffer.resize(padded_required_len, 0);
+        self.pad_samples(&samples, time_secs);
+    }
+
+    fn pad_samples(&mut self, samples: &[i16], time_secs: f32) {
+        let offset = (time_secs * (SAMPLE_RATE as f32) * (CHANNELS as f32)) as usize;
+
+        for (i, &sample) in samples.iter().enumerate() {
+            let adjusted_sample = ((sample as f32) * self.volume).round() as i16;
+
+            let left_pos = offset + i * 2;
+            let right_pos = left_pos + 1;
+
+            if right_pos < self.buffer.len() {
+                self.buffer[left_pos] = self.buffer[left_pos].saturating_add(adjusted_sample); // gauche
+                self.buffer[right_pos] = self.buffer[right_pos].saturating_add(adjusted_sample); // droite
+            }
+        }
+    }
+}

package/rust/audio/interpreter.rs

@@ -0,0 +1,143 @@
+use crate::{
+    audio::{ engine::AudioEngine, loader::load_trigger },
+    core::{
+        parser::statement::{ Statement, StatementKind },
+        shared::value::Value,
+        store::variable::VariableTable,
+    },
+};
+
+pub fn interprete_statements(
+    statements: &Vec<Statement>,
+    audio_engine: AudioEngine,
+    entry: String,
+    output: String
+) -> (AudioEngine, f32, f32) {
+    let mut base_bpm = 120.0;
+    let mut base_duration = 60.0 / base_bpm;
+
+    let variable_table = audio_engine.variables.clone();
+
+    let (updated_audio_engine, base_bpm, max_end_time) = execute_audio_statements(
+        audio_engine.clone(),
+        variable_table.clone(),
+        statements.clone(),
+        base_bpm.clone(),
+        base_duration.clone(),
+        0.0,
+        0.0
+    );
+
+    (updated_audio_engine, base_bpm, max_end_time)
+}
+
+pub fn execute_audio_statements(
+    mut audio_engine: AudioEngine,
+    mut variable_table: VariableTable,
+    mut statements: Vec<Statement>,
+    mut base_bpm: f32,
+    mut base_duration: f32,
+    mut max_end_time: f32,
+    mut cursor_time: f32
+) -> (AudioEngine, f32, f32) {
+    for stmt in statements {
+        match &stmt.kind {
+            StatementKind::Load { source, alias } => {
+                variable_table.set(alias.to_string(), Value::String(source.clone()));
+            }
+
+            StatementKind::Let { name } => {
+                variable_table.set(name.to_string(), stmt.value.clone());
+            }
+
+            StatementKind::Tempo => {
+                if let Value::Number(bpm_) = &stmt.value {
+                    base_bpm = *bpm_ as f32;
+                    base_duration = 60.0 / base_bpm;
+                } else {
+                    eprintln!("❌ Invalid tempo value: {:?}", stmt.value);
+                }
+            }
+
+            StatementKind::Trigger { entity, duration } => {
+                if let Some(trigger_val) = variable_table.get(entity) {
+                    let (src, duration_secs) = load_trigger(
+                        trigger_val,
+                        duration,
+                        base_duration,
+                        variable_table.clone()
+                    );
+
+                    audio_engine.insert(&src, cursor_time, duration_secs, None);
+
+                    cursor_time += duration_secs;
+
+                    if cursor_time > max_end_time {
+                        max_end_time = cursor_time;
+                    }
+                } else {
+                    eprintln!("❌ Unknown trigger entity: {}", entity);
+                }
+            }
+
+            StatementKind::Loop => {
+                if let Value::Map(loop_value) = &stmt.value {
+                    let iterator = loop_value.get("iterator");
+                    let body = loop_value.get("body");
+
+                    let loop_count = if let Some(Value::Number(n)) = iterator {
+                        *n as usize
+                    } else {
+                        eprintln!("❌ Loop iterator must be a number: {:?}", iterator);
+                        continue;
+                    };
+
+                    let loop_body = if let Some(Value::Block(body)) = body {
+                        body.clone()
+                    } else {
+                        eprintln!("❌ Loop body must be a block: {:?}", body);
+                        continue;
+                    };
+
+                    for _ in 0..loop_count {
+                        let (loop_engine, _, loop_end_time) = execute_audio_statements(
+                            audio_engine.clone(),
+                            variable_table.clone(),
+                            loop_body.clone(),
+                            base_bpm,
+                            base_duration,
+                            max_end_time,
+                            cursor_time
+                        );
+
+                        audio_engine = loop_engine;
+
+                        // Update time and max_end_time after each loop iteration
+                        cursor_time = loop_end_time;
+                        if loop_end_time > max_end_time {
+                            max_end_time = loop_end_time;
+                        }
+                    }
+                }
+            }
+
+            StatementKind::Bank => {}
+
+            StatementKind::Import { names, source } => {}
+
+            StatementKind::Export { names, source } => {}
+
+            StatementKind::Unknown => {
+                // Ignore unknown statements
+            }
+
+            _ => {
+                eprintln!("Unsupported statement kind: {:?}", stmt);
+            }
+        }
+    }
+
+    audio_engine.set_variables(variable_table);
+
+    (audio_engine, base_bpm, max_end_time)
+}