@devaloop/devalang 0.1.3 → 0.1.5

package/README.md

@@ -19,40 +19,50 @@
 
 # 🦊 Devalang — Write music with code
 
-Devalang is a compact domain-specific language (DSL) for music makers, sound designers, and creative coders.
-Compose loops, control samples, synthesize audio, and render your ideas — all in clean, readable text.
+Devalang is a compact **domain-specific language** (DSL) for **music makers**, **sound designers**, and **creative coders**.
+Compose loops, control samples, synthesize audio, and render your ideas — all in clean, **readable text**.
 
-Whether you're prototyping a beat, building generative music, or performing live, Devalang gives you rhythmic precision with the elegance of code.
+Whether you're prototyping a beat, building **generative music**, or **performing live**, Devalang gives you rhythmic precision with the elegance of code.
 
-From studio sketches to live sets, Devalang puts musical ideas into motion.
+**From studio sketches to live sets, Devalang puts musical ideas into motion.**
 
-> **🚀 v0.1.0 - Complete Rewriting**
->
+
+> **🚀 v0.1.0+ - Complete Rewriting**
 >
 > **NEW**: [Devalang Playground V2.0 is now available](https://playground.devalang.com) — Try it in your browser!
 
----
 
 ## 📚 Quick Access
 
+### Websites & Resources
+- [🌐 Website](https://devalang.com) — Project homepage
 - [▶️ Playground](https://playground.devalang.com) — Try Devalang in your browser
 - [📖 Documentation](https://docs.devalang.com) — Complete language reference
-- [🧩 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode) — Syntax highlighting & snippets
+
+### Important files
 - [📜 Changelog](./docs/CHANGELOG.md) — Version history
 - [💡 Examples](./examples/)
-- [🌐 Website](https://devalang.com) — Project homepage
-- [📦 npm Package](https://www.npmjs.com/package/@devaloop/devalang)
-- [📦 Rust Crate](https://crates.io/crates/devalang)
 
----
+### Common projects and tools
+- [📦 Devapack](https://github.com/devaloop-labs/devapack) — Community-driven addons
+- [🧩 VSCode Extension](https://marketplace.visualstudio.com/items?itemName=devaloop.devalang-vscode) — Syntax highlighting & snippets
+
+### Downloads
+- [🐙 Installers](https://devalang.com/download) — For Windows, macOS, and Linux
+- [📦 npm](https://www.npmjs.com/package/@devaloop/devalang) — Install via npm
+- [📦 cargo](https://crates.io/crates/devalang) — Install via Cargo
 
 ## ⚡ Quick Start
 
 ### Try in Your Browser
 
-> **[Launch the Playground](https://playground.devalang.com)** to try Devalang without installing anything.
+> **[Launch the Playground](https://playground.devalang.com) to try Devalang without installing anything.**
+
+### Download the Installers (Recommended)
 
-### Install via npm (Recommended)
+Visit the [Download page](https://devalang.com/download) to get the latest releases for Windows, macOS, and Linux.
+
+### Install via npm (Node.js)
 
 ```bash
 npm install -g @devaloop/devalang
@@ -83,17 +93,48 @@ devalang build --path examples/index.deva --formats wav mid
 devalang play --live --input examples/index.deva
 ```
 
----
+## 📦 (optional) Install addons
+
+Devalang supports addons to extend functionalities. This allows you to easily add sound banks, effects, or other features.
+
+> To create your own addon, please refer to the [Devapack documentation](https://github.com/devaloop-labs/devapack/tree/main/docs).
+
+```bash
+# List available addons
+devalang addon list
+
+# Install an addon (format: <author>.<addon-name>)
+devalang addon install devaloop.808
+```
+
+This will install the `devaloop.808` sound bank in your current working directory inside `.deva` folder.
+
+**You can then use it in your Devalang scripts !**
+
+## 🎵 Your First Devalang File
 
-## 🎵 Your First Devalang Script
+Create a file `hello.deva` or `index.deva` (if you do not specify `--input` argument, it defaults to `index.deva`).
 
-Create a file `hello.deva`:
+#### Nomenclature for .deva files
+
+- Devalang files use the `.deva` extension.
+- Devalang engine is **indentation-sensitive** for blocks, similar to Python.
+- Files are plain text and can be edited with **any text editor** (VSCode recommended).
+- Ensure your text editor supports **UTF-8 encoding**.
+- Devalang is **case-sensitive**, so be consistent with capitalization.
+- Devalang reads files from **top to bottom**, so order matters.
+- Devalang files typically start with global settings (e.g., `bpm`, `bank`), followed by definitions (`synth`, `pattern`, `group`), and finally execution commands (`spawn`, `play`).
+- Devalang files can include comments using `#` or `//` for single-line comments.
+- You can name your files anything, but `index.deva` is a common convention for the main entry file.
+- You can organize your project with subfolders as needed. (use module system like `@import { var } from '<module_path>'` and `@export { var }`).
+
+Refer to the [documentation](https://docs.devalang.com) for a complete syntax reference.
 
 ```deva
 # Set the tempo
 bpm 120
 
-# Load a bank of sounds (make sur you have the bank installed)
+# Load a bank of sounds (make sure you have the bank installed)
 bank devaloop.808 as drums
 
 # Create a simple kick pattern
@@ -104,32 +145,66 @@ let mySynth = synth saw
 
 # Define a melody using a group to organize notes
 group myMelody:
-    mySynth -> note(C5)
-        -> duration(500)
 
-    mySynth -> note(E5)
-        -> duration(500)
+  mySynth -> note(C5)
+      -> duration(500)           # 500ms
+
+  mySynth -> note(E5)
+      -> duration(1/4)           # Quarter note
 
-    mySynth -> note(G5)
-        -> duration(500)
+  mySynth -> note(G5)
+      -> duration(1/16)           # Sixteenth note
+      -> velocity(0.8)            # Velocity (0.0 to 1.0) or 0-127
+      -> lpf(800)                 # Lowpass filter at 800Hz
+      -> reverb({ size: 0.3 })    # Reverb effect
 
-# Play the melody
+# Play the melody (in parallel)
 spawn myMelody
 
-# Play the kick pattern
+# Play the kick pattern (in parallel too)
 spawn kickPattern
 ```
 
+### (optional) Configure project settings
+
+You can create a `devalang.json` (recommended) or `devalang.toml` or even `.devalang` (legacy) file to customize check/build/play settings.
+
+This typically evitate to re-type common arguments like `--path`, `--formats`, etc.
+
+> Comments are not supported in config files, please use `devalang init` to generate a default config.
+
+```jsonc
+{
+  "project": {
+    "name": "My Awesome Project"        // Change this to adjust project name
+  },
+  "paths": {
+    "entry": "audio/helloWorld.deva",   // Change this to adjust entry file path
+    "output": "output"                  // Change this to adjust output directory
+  },
+  "audio": {
+    "format": ["wav", "mid"],           // Change this to adjust output formats (options: wav, mid, mp3)
+    "bit_depth": 16,                    // Change this to 24 or 32 for higher quality
+    "channels": 2,                      // Change this to 1 for mono output
+    "sample_rate": 44100,               // Change this to 48000 for higher quality
+    "resample_quality": "sinc24",       // Change this to adjust resampling quality (options: sinc8, sinc16, sinc24, sinc32)
+    "bpm": 120                           // Change this to adjust the project tempo (only if not set in code)
+  },
+  "live": {
+    "crossfade_ms": 500                  // Change this to adjust crossfade duration when playing live
+  }
+}
+
+```
+
 ### Build the audio
 
 ```bash
-# Build to WAV
-devalang build --path hello.deva --formats wav
-
-# Output: ./output/audio/hello.wav
+# Build to WAV, MP3, and MIDI
+devalang build --path hello.deva --formats wav,mp3,mid
 ```
 
-# Play the audio
+### Play the audio
 
 ```bash
 # Play the audio file
@@ -137,9 +212,11 @@ devalang play --input hello.deva
 
 # Play live (repeats and watch until stopped)
 devalang play --live --input hello.deva
-```
 
----
+# Play live loop with very short crossfade
+# With 50ms, transitions between loops are no more distinguishable
+devalang play --live --crossfade-ms 50 --input hello.deva
+```
 
 ## 🚀 Features
 
@@ -174,7 +251,7 @@ devalang play --live --input hello.deva
 ### 📦 **Output Formats**
 - ✅ **WAV** — 16/24/32-bit audio export
 - ✅ **MIDI** — Standard MIDI file export
-- ✅ **MP3/FLAC** — Planned
+- ✅ **MP3** — Lossy audio export (via LAME)
 
 ### 🎯 **Performance**
 - ⚡ **Fast builds** — 7-10ms for typical projects
@@ -185,8 +262,6 @@ devalang play --live --input hello.deva
 - ✅ **Online Docs** — Complete language reference
 - ✅ **VSCode Extension** — Syntax highlighting
 
----
-
 ## 💡 Why Devalang?
 
 - 🎹 **Prototype audio ideas** without opening a DAW
@@ -197,11 +272,9 @@ devalang play --live --input hello.deva
 - 🎨 **Live code** with fast iteration cycles
 - 📦 **Version control** your music with git
 
----
-
 ## 📖 Documentation
 
-**[Visit docs.devalang.com](https://docs.devalang.com)** for:
+Visit **[docs.devalang.com](https://docs.devalang.com)** for:
 - Complete syntax reference
 - API documentation
 - WASM integration guide
@@ -209,8 +282,6 @@ devalang play --live --input hello.deva
 - Advanced tutorials
 - Best practices
 
----
-
 ## 🔧 Development
 
 ### Build from Source
@@ -220,14 +291,16 @@ devalang play --live --input hello.deva
 git clone https://github.com/devaloop-labs/devalang.git
 cd devalang
 
+# NPM (TypeScript) and Cargo (Rust) are required
+npm install
+
 # Build CLI (Rust)
-cargo build --release --features cli
+cargo build
 
-# Build WASM
-cargo build --release --features wasm --lib
+# Build WASM (Web & Node.js)
+npm run rust:wasm:all
 
 # Build TypeScript
-npm install
 npm run ts:build
 
 # Run tests
@@ -247,18 +320,16 @@ We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guideline
 - 🎵 **Share examples** of your creations
 - 🧪 **Write tests** for new features
 
----
-
 ## 📜 License
 
 MIT License — See [LICENSE](./LICENSE) for details.
 
-Copyright (c) 2025 Devaloop
+Copyright (c) 2025 Labscend Studios
 
 ---
 
 <div align="center">
-    <strong>Made with ❤️ by the Devaloop team</strong>
+    <strong>Made with ❤️ by <a href="https://labscend.studio">Labscend Studios</a></strong>
     <br />
-    <sub>Star ⭐ the repo if you like it!</sub>
+    <sub>Star ⭐ the repo if you like it !</sub>
 </div>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devaloop/devalang",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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",
   "types": "./out-tsc/index.d.ts",