Onda

Onda is an expressive and performant JIT-compiled audio programming language.

Visit the project's website to try the web compiler and get an introduction to the language.

Here is a code example for a saw oscillator processed by a resonant filter and an oversampled saturator:

import std/osc
import std/filter

params:
  freq = 110.0 {20.0, 880.0}
  cutoff = 1200.0 {40.0, 12000.0}
  resonance = 1.0 {0.1, 8.0}
  drive = 1.0 {1.0, 10.0}

def soft_clip(x):
  return tanh(x)

proc Saturator:
  params:
    amount = 1.0

  sample 4:
    out1 = soft_clip(in1 * amount)

init:
  osc = std::osc::Saw()
  filter = std::filter::Svf(cutoff = cutoff, q = resonance)
  saturator = Saturator()

block:
  filter.update_coeffs(cutoff, resonance)

  sample:
    tone = osc(freq = freq)
    out1 = saturator(filter(tone), amount = drive)

Take a look at the examples/ folder for more usage examples.

GitHub Releases provides precompiled packages for Linux x64, macOS arm64, and Windows x64. Each package includes the CLI, an Onda Run application entry, static and shared C libraries, public headers, hosted and raw processor API references, language guide, standard-library reference, and examples. The Linux archive includes install.sh and uninstall.sh for a per-user CLI and desktop installation.

Tagged releases attach portable tarballs and publish the four public npm packages: @onda-lang/processor-abi, @onda-lang/binaryen-web, @onda-lang/webaudio, and @onda-lang/wasm-compiler.

• CHANGELOG.md: release history and migration notes
• docs/syntax.md: language syntax and semantics
• docs/stdlib.md: generated standard-library API reference
• docs/architecture.md: compiler architecture and codebase navigation
• docs/projects.md: project manifests, typed buffer assets, and project images
• docs/mir.md: backend-neutral MIR and backend boundary
• docs/api.md: complete hosted C API and library integration reference
• docs/processor-abi.md: raw processor-object API, ABI, and target profiles
• docs/web-api.md: complete JavaScript and WebAssembly package API
• packages/onda_wasm_compiler: packaged source-to-WebAssembly compiler and onda-wasm CLI
• packages/onda_binaryen_web: current MIR-to-Wasm backend
• packages/onda_processor_abi: compiler-free artifact schema, validation, and integrity helpers
• packages/onda_webaudio: optional reusable Web Audio adapter
• examples/web/onda_wasm_playground: editable embedded-compiler playground
• examples/native/raw_processor_object: link and call a native relocatable processor object directly

The CLI surface is:

onda
onda compile <input>
onda run [input]
onda run play <input>
onda run render <input>
onda project <directory> [--from <input.onda>]
onda daemon diagnose <input>
onda daemon stdio
onda lsp

<input> may be an .onda source file or an .ondaproject project file.

For a full list of all commands and their flags, run the help file via onda --help.

Compiles an Onda file and optionally emits IR or an object file.

Typical uses:

• syntax and semantic checking
• inspect graph lowering with --dump-graph
• emit backend-neutral MIR for inspection with --emit mir, versioned JSON with --emit mir-json, or compact production transport with --emit mir-messagepack
• select explicitly declared compile-time variants with repeatable --const Name=value, or inspect their resolved types and defaults with --list-consts
• emit LLVM IR with --emit llvm-ir or --ir
• emit a native object file with --emit obj

Examples:

onda compile examples/basic/sine.onda
onda compile examples/basic/sine.onda --emit mir
onda compile examples/basic/sine.onda --emit mir-json --output sine.mir.json
onda compile examples/basic/sine.onda --emit mir-messagepack --output sine.mir.msgpack
onda compile examples/feedback/cybernetic_feedback_graph.onda --dump-graph
onda compile program.onda --const Channels=8 --const 'Window=[0.0, 0.5, 1.0]' --emit mir
onda compile program.onda --list-consts
onda compile examples/basic/sine.onda --emit llvm-ir
onda compile examples/basic/sine.onda --emit obj
onda compile examples/basic/sine.onda --target-triple aarch64-unknown-linux-gnu --emit obj

Cross-target IR and object emission is also supported:

onda compile examples/basic/sine.onda --target-spec ./targets/arm64.toml --emit obj

Opens the standalone UI window. This can be used to interactively play with the live-running code. Running onda without a command opens the same window with its file picker. The empty view lets you choose the sample rate and compile block size before loading a file. Use Unload to return there and recompile with different settings. Loaded filesystem sources and projects reload when their entry, transitive source dependencies, manifest, or file-backed assets change; unresolved and temporarily missing paths remain watchable.

onda
onda run examples/basic/sine.onda

Run host selection:

• egui is the default run host
• --webview selects the webview run host explicitly

Useful flags:

• --sample-rate
• --block-size
• --input-device
• --output-device
• --midi-input-device
• --theme

Runs the real-time playback/control transport without opening the standalone UI. Parameters can be set via the --set argument.

onda run play examples/basic/sine.onda --dur 2
onda run play examples/basic/sine.onda --forever --set freq=220

Useful flags:

• --dur or --forever
• --sample-rate
• --block-size
• --input-device
• --output-device
• --midi-input-device
• --set name=value
• --buffer name=path

With --control-json, onda run play prints a control handshake on stdout and serves a localhost control socket for run clients.

Offline render through the run pipeline. This is useful when you want to render out to a wav file without running real-time playback.

onda run render examples/basic/sine.onda --output ./onda_out.wav --dur 5 --set freq=220

Useful flags:

• --output
• --dur
• --sample-rate
• --block-size
• --set name=value
• --buffer name=path

Creates an empty, editable Onda project folder with a project file named after the target, code/main.onda, and an assets directory. With --from, it instead captures an existing source graph and packages supplied buffers into canonical project assets.

onda project my-project
onda run my-project/my-project.ondaproject

onda project portable-sampler \
  --from sampler.onda \
  --buffer sample=recording.wav

Runs daemon-backed analysis for a file and reports diagnostics.

onda daemon diagnose examples/basic/sine.onda

Starts the daemon control transport over stdio. This is intended for tool/editor integration rather than everyday manual use.

onda daemon stdio

Starts the Onda language server over stdio.

onda lsp

Current LSP support includes:

• open, change, save, and close document tracking
• immediate diagnostics on open/save and debounced diagnostics while editing
• syntax highlighting, hover, navigation and context-aware completion

1. Initialize submodules.

git submodule update --init --recursive

2. Bootstrap LLVM.

Windows PowerShell:

./scripts/bootstrap-llvm.ps1

macOS/Linux:

./scripts/bootstrap-llvm.sh

Local builds use deps/llvm-bootstrap to build LLVM from source on all platforms. When CI is set, the bootstrap scripts may download a matching prebuilt LLVM package instead.

3. Build the CLI:

cargo build -p onda_cli --release

This produces the onda executable in target/release/.

4. Build the static and shared libraries if needed:

To build the C API in release mode:

cargo build -p onda_api --release

This produces the onda C API library artifacts in target/release/ along with the public header in include/onda.h. Depending on platform/toolchain, that includes the static library and the shared library import/runtime pair. On Windows, the shipped static onda.lib is built with the static MSVC CRT (/MT), so hosts linking that library should use a compatible runtime choice.

Already-compiled native processor objects do not require libonda: include include/onda_processor_abi.h, link the emitted object with the application, and call its raw entrypoints directly. The paired JSON descriptor supplies storage sizes, alignments, defaults, and interface layouts. See the native raw-object example for a complete link command.

The VS Code extension lives in the standalone onda-lang/onda-vscode repository. It provides:

• .onda and .on language registration
• builtin LSP through onda lsp
• Onda: Run File for launching the onda run --webview UI directly in-editor

The Neovim plugin lives in the standalone onda-lang/onda-nvim repository. It provides:

• .onda and .on filetype detection
• builtin LSP through onda lsp
• :OndaRunFile for launching the standalone run window