operator

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 15 Open GitHub ↗

A modular synthesizer with a livecoding interface.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Operator

A real-time modular synthesizer desktop app with a JavaScript DSL for live-coding audio patches, built with Electron and a Rust DSP engine.

## Features

- **JavaScript DSL** - Expressive, fluent API with `$`-prefixed functions for building synthesis patches
- **Real-time Audio** - Low-latency audio processing in Rust via N-API, running directly in-process
- **Live Coding** - Update patches on-the-fly with Alt+Enter
- **Monaco Editor** - Full-featured code editor with autocomplete, inline error highlighting, and oscilloscope overlays
- **UI Sliders** - Bind real-time UI sliders to signal parameters with `$slider()`
- **Module Library** - Oscillators, filters, effects, sequencers, envelopes, and more

## Quick Start

### Prerequisites

- Rust (latest stable)
- Node.js 24.12+
- Yarn (latest)

> **Note:** This project uses [Volta](https://volta.sh/) to manage the Node.js version. If you have Volta installed, it will automatically use the correct version pinned in `package.json`.

### Acquiring submodules

Ensure that you've fetched the git submodules:

```bash
git submodule update --init --recursive
```

> **Note:** Failure to do so will produce an error along the lines of:

```
error: failed to load manifest for workspace member `/projects/operator/crates/modular_core`
referenced by workspace at `/projects/operator/Cargo.toml`
```

### Running the App

```bash
yarn install
yarn start
```

This builds the native Rust audio module and launches the Electron app.

## Usage

1. Launch the app with `yarn start`
2. Write a patch using the JavaScript DSL (see examples below)
3. Press **Alt+Enter** to execute and hear the result
4. Press **Alt+.** to stop audio

### Example Patches

**Simple Sine Wave:**

```javascript
$sine('440hz').out();
```

**Musical Note:**

```javascript
$sine('a3').out();
```

**FM Synthesis:**

```javascript
const mod = $sine('220hz');
const carrier = $sine('440hz').phase(mod.amplitude(0.5));
carrier.out();
```

**With a UI Slider:**

```javascript
const shape = $slider('Shape', 0, 0, 5);
$saw('a3', { shape }).out();
```

## Project Structure

```
modular/
├── crates/
│   ├── modular_core/      # Core DSP engine (Rust)
│   ├── modular/           # N-API bindings + audio thread (Rust)
│   └── modular_derive/    # Proc macros for the module system (Rust)
├── src/
│   ├── main/              # Electron main process (TypeScript)
│   │   └── dsl/           # DSL executor, factories, type generation
│   ├── renderer/          # React renderer (TypeScript)
│   ├── preload/           # Electron preload scripts
│   └── shared/            # Shared types between main and renderer
└── docs/                  # Documentation
```

## Architecture

### Rust DSP Engine

- **modular_core** - Audio DSP engine: oscillators, filters, effects, sequencers, envelopes
- **modular** - N-API bindings exposing the engine to Node.js; runs the audio callback via cpal; streams scope data back to the renderer
- **modular_derive** - Proc macros for the module output system

### Electron App (TypeScript/React)

- **DSL Runtime** - Executes JavaScript patches via `new Function(...)`, generates `PatchGraph` JSON
- **Editor** - Monaco-based editor with autocomplete, inline error display, and waveform overlays
- **IPC** - Patch graphs are sent from the renderer to the main process over Electron IPC, which forwards them to the Rust synthesizer

## Development

### Type Generation

After modifying Rust N-API types, regenerate the DSL type definitions:

```bash
yarn generate-lib
```

### Building

```bash
# Build native Rust module only
yarn build-native

# Build and launch the full app
yarn start
```

### Testing

```bash
# Rust DSP unit tests
yarn test:rust

# JavaScript unit/integration tests (Vitest)
yarn test:unit

# End-to-end tests (Playwright + Electron)
yarn test:e2e

# All tests
yarn test:all
```

See [TESTING.md](TESTING.md) for more details on the test infrastructure.

## License

AGPL-3.0

operator

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README