nw_wrld is an event-driven sequencer for triggering visuals using web technologies. It enables users to scale up audiovisual compositions for prototyping, demos, exhibitions, and live performances. Users code their own visual modules, then orchestrate them using the project's native UI composer.

Visuals can be triggered via the built-in 16-step sequencer or by configuring external MIDI/OSC inputs.

This project is currently in beta. Downloadable installers are not currently provided; run nw_wrld from source using this repository. Please note that whilst the project is in beta, there will likely be frequent breaking changes between releases.

• Isolated sandbox and module-workspace bundling
• Docblock-declared module dependencies with automated runtime injection
• TypeScript migration
• Unit tests, E2E Playwright tests, runtime validations
• Use-case specific User Guides (Ableton, strudel, TouchDesigner, etc.)
• Signed and notarized MacOS app builds
• Signed Windows app builds
• Robust Linux & WSL support
• Userdata, Module, and JSON versioning (+ migration scripts)
• Multi-band audio threshold analysis (local processing) for channel triggers
• Advanced default sequencer (Working sampler with audio FX)
• Remote API input source with HTTP/WebSocket client for cloud-based services (audio analysis APIs, ML models, etc.)
• Serial port input support for hardware sensor integration

• Built-in 16-step pattern sequencer - Create rhythmic audiovisual compositions without external hardware
• External MIDI/OSC support - Connect Ableton Live, TouchOSC, or any MIDI/OSC source for live performance
• Visual module system - Build custom visuals with p5.js, Three.js, D3.js, or vanilla JavaScript
• Hot module reloading - Edit modules and see changes instantly
• Project folder workflow - Self-contained, portable projects with modules, assets, and data
• Flexible method mapping - Trigger any visual method with sequencer patterns or external signals

Build from source to contribute or customize:

Prerequisites: Node.js v20+ and basic terminal knowledge

# 1. Clone the repository
git clone https://github.com/aagentah/nw_wrld.git
cd nw_wrld

# 2. Install dependencies
npm install

# 3. Start the app
npm start

Two windows will open:

• Dashboard: Control center for creating tracks, programming patterns, and configuring visuals
• Projector: Visual output window

npm run test:e2e

• E2E tests launch the real Electron app and control the windows via Playwright.
• Test artifacts (screenshots/traces on failure) are written to test-results/ (gitignored).
• Tests can boot into an isolated project folder by setting NW_WRLD_TEST_PROJECT_DIR.

nw_wrld uses a project folder model. Each project is a self-contained folder containing your modules, assets, and data.

Note: Workspace modules are JavaScript code executed by nw_wrld. Only open project folders you trust.

MyProject/
├── modules/           # Visual modules (hot-reloadable JavaScript files)
│   ├── Text.js
│   ├── GridOverlay.js
│   ├── SpinningCube.js
│   └── ...16 starter modules
├── assets/            # Images, JSON, and other resources
│   ├── images/
│   │   └── blueprint.png
│   └── json/
│       └── meteor.json
└── nw_wrld_data/      # Tracks, settings, and recordings
    └── json/

When you first launch nw_wrld, you'll be prompted to select or create a project folder. The app automatically scaffolds a working project with:

• 16 starter modules - Ready-to-use examples (2D, 3D, text, data visualization)
• Sample assets - Images and JSON data files
• Data storage - Configuration, tracks, and recordings

Projects are completely portable - copy the folder to share with others, work across machines, or back up your work. Everything needed to run your audiovisual compositions is contained in one folder.

If your project folder is deleted, moved, or disconnected (e.g., external drive unplugged), nw_wrld will detect the issue and prompt you to reselect or choose a different project.

1. Click [CREATE TRACK] → Name it → Create
2. Click [+ MODULE] → Select Text or Corners
3. Click [+ CHANNEL] to add a sequencer row
4. Click some cells in the 16-step grid (they turn red)
5. Assign a method to the channel (e.g., color or rotate)
6. Click [PLAY] in the footer

You'll see the playhead move across the grid and trigger your visuals. No external setup required!

Signal Sources:
┌──────────────┐
│  Sequencer   │──┐
│  (Built-in)  │  │
└──────────────┘  │
                  ├──▶ Dashboard ──▶ Projector
┌──────────────┐  │    (Control)     (Visuals)
│ External     │──┘
│ MIDI/OSC     │
└──────────────┘

• Create tracks and add visual modules
• Program patterns with the 16-step sequencer
• Configure module methods and parameters
• (Optional) Connect external MIDI/OSC sources

• Displays active visual modules
• Responds to sequencer or external triggers in real-time
• Can be full-screened on external displays

Follow the Getting Started Guide for detailed step-by-step instructions.

Quick overview:

1. Create a track and add visual modules
2. Add channels and program patterns in the 16-step grid
3. Assign methods to channels (color, scale, rotate, etc.)
4. Click PLAY to see your patterns trigger visuals in real-time

The built-in sequencer is perfect for testing modules and creating standalone audiovisual pieces without external hardware.

For live performance with external hardware, you can connect MIDI controllers or DAWs.

• A DAW that outputs MIDI (Ableton Live, FL Studio, Logic Pro, etc.)
• MIDI routing setup:
  • Mac: IAC Driver (built-in) - Setup Guide
  • Windows: loopMIDI or similar virtual MIDI port

Mac:

1. Open Audio MIDI Setup → Show MIDI Studio
2. Enable IAC Driver

Windows:

1. Install loopMIDI

In Ableton:

1. Preferences → MIDI
2. Enable your virtual port for Track/Remote output

1. Dashboard → Settings → Signal Source
2. Select External (MIDI/OSC)
3. Configure MIDI device or OSC port
4. Go to Settings → Configure Mappings to customize trigger mappings (MIDI Pitch Class or MIDI Exact Note / OSC addresses)

Most DAW setups send notes on MIDI Channel 1 unless you explicitly route or change it. nw_wrld supports both single-channel and split-channel workflows:

• Option A (simplest): Single MIDI channel

  • In nw_wrld → Settings → External (MIDI/OSC) → MIDI:
    • Method Triggers MIDI Channel: 1
    • Track Select MIDI Channel: 1
  • Use Settings → Configure Mappings to choose either:
    • MIDI (Pitch Class): octave-agnostic mapping using C..B (avoids DAW octave-name differences)
    • MIDI (Exact Note): octave-specific mapping using full MIDI note numbers (0–127)
  • Then map which triggers activate track selection vs method triggers.

• Option B (clean separation): Split MIDI channels

  • In your DAW, route method trigger notes to Channel 1 and track-selection notes to Channel 2 (commonly done with separate MIDI routing tracks/devices).
  • In nw_wrld → Settings:
    • Method Triggers MIDI Channel: 1
    • Track Select MIDI Channel: 2

1. Play your DAW
2. Track activation note loads modules
3. MIDI Pitch Class or Exact Note triggers mapped methods
4. Real-time audiovisual performance

Modules are JavaScript files in your project's modules/ folder. Edit them with any text editor and nw_wrld hot-reloads automatically.

1. Navigate to your project folder
2. Open the modules/ directory
3. Create or edit a .js file
4. Save → nw_wrld detects changes and reloads

Workspace modules are loaded from your project folder and must follow a strict contract:

• Filename is identity: modules/MyModule.js → module id MyModule (must be alphanumeric and start with a letter)
• Docblock metadata is required: @nwWrld name, @nwWrld category, @nwWrld imports
• Imports are declarative: list what you need; nw_wrld injects safe bindings for you
• Default export is required: export default MyModule

Allowed @nwWrld imports:

• SDK: ModuleBase, BaseThreeJsModule, assetUrl, readText, loadJson
• Global libs: THREE, p5, d3

/*
@nwWrld name: My Module (Display Name)
@nwWrld category: 2D
@nwWrld imports: ModuleBase, assetUrl, loadJson
*/

class MyModule extends ModuleBase {
  async init() {
    // Load images from project assets/
    const imgUrl = assetUrl("images/blueprint.png");

    // Load JSON data from project assets/
    const data = await loadJson("json/meteor.json");
  }
}

export default MyModule;

See the Module Development Guide for complete documentation including:

• Full module structure and lifecycle
• Method definitions and option types
• SDK API reference and asset loading
• Library usage (p5.js, Three.js, D3.js)
• Advanced patterns and best practices

When you extend ModuleBase, you inherit powerful methods for free: show, hide, offset, scale, opacity, rotate, randomZoom, and matrix.

These methods can be triggered via the sequencer or external MIDI/OSC, giving you instant control over positioning, visibility, transformations, and effects.

See the Module Development Guide for complete documentation of all built-in methods and their parameters.

Switch between modes in Settings → Signal Source.

Sequencer Mode (Default) - Program patterns with a 16-step grid per channel. Perfect for getting started, testing modules, and creating standalone pieces without external hardware. Adjustable BPM (60-130), patterns loop continuously and save with your tracks.

External Mode (Advanced) - Connect MIDI/OSC hardware for live performance.

• MIDI (Pitch Class): map C..B (octave-agnostic). This avoids “G7 vs G8” naming differences across DAWs because matching is based on pitch class.
• MIDI (Exact Note): map full MIDI note numbers (0–127) for octave-specific triggers.
• OSC: map OSC addresses.

Configure global mappings in Settings for consistent control across all tracks.

Switch modes anytime - your tracks, modules, and methods remain the same. Only the trigger source changes.

Every new project includes 16 starter modules in your modules/ folder:

2D & UI:

• Text - Configurable text display and manipulation
• Corners - DOM-based corner UI elements
• GridOverlay - Canvas-based grid overlay
• GridDots - Animated dot grid patterns
• Frame - Border frame overlay
• Image - Load images from workspace assets
• CodeColumns - Animated code/text columns

3D Graphics:

• SpinningCube - Basic Three.js example
• CubeCube - Nested cube visualization
• OrbitalPlane - Orbital mechanics simulation
• LowEarthPoint - Low earth orbit visualization

Data Visualization:

• AsteroidGraph - p5.js with workspace JSON data
• MathOrbitalMap - Mathematical orbit mapping
• CloudPointIceberg - 3D point cloud
• ZKProofVisualizer - Zero-knowledge proof visualization

Getting Started:

• HelloWorld - Minimal working example

Study these modules to learn patterns for 2D, 3D, text, and data visualization. All are fully editable in your project's modules/ folder.

MyProject/
├── modules/                    # ← YOUR MODULES GO HERE
│   ├── Text.js
│   ├── GridOverlay.js
│   ├── SpinningCube.js
│   ├── YourCustomModule.js    # Create your own modules here
│   └── ...16 starter modules
│
├── assets/                     # ← YOUR ASSETS GO HERE
│   ├── images/
│   │   ├── blueprint.png      # Included starter asset
│   │   └── your-image.png     # Add your own images
│   └── json/
│       ├── meteor.json         # Included starter dataset
│       └── your-data.json      # Add your own data
│
└── nw_wrld_data/               # App data (auto-managed)
    └── json/
        ├── userData.json       # Tracks, settings, mappings
        ├── appState.json       # Current app state
        ├── config.json         # App configuration
        └── recordingData.json  # Recording data

nw_wrld/
├── src/
│   ├── dashboard/              # React UI for control
│   │   ├── Dashboard.js        # Main dashboard logic
│   │   ├── modals/             # UI modals
│   │   ├── components/         # Reusable components
│   │   └── styles/             # Dashboard styles
│   │
│   ├── projector/              # Visual output window
│   │   ├── Projector.js        # Main projector logic
│   │   ├── helpers/
│   │   │   ├── moduleBase.js   # Base class (the foundation)
│   │   │   └── threeBase.js    # Three.js base class
│   │   └── templates/
│   │       └── ThreeTemplate.js # 3D module template
│   │
│   ├── main/                   # Electron main process
│   │   ├── InputManager.js     # MIDI/OSC input handling
│   │   ├── starter_modules/    # Starter modules (seeded into projects)
│   │   └── workspaceStarterModules.js
│   │
│   ├── shared/
│   │   ├── json/               # JSON file management
│   │   ├── config/             # Default configuration
│   │   ├── sequencer/          # Sequencer playback engine
│   │   ├── midi/               # MIDI utilities
│   │   └── audio/              # Audio feedback
│   │
│   └── renderer.ts             # SDK initialization
│
├── package.json
└── README.md

Configuration files are stored in your project's nw_wrld_data/json/ directory:

• userData.json - Tracks, mappings, and settings (automatically managed)
• appState.json - Current app state and workspace path (automatically managed)
• config.json - App configuration, aspect ratios, background colors (automatically managed)
• recordingData.json - Recording data (automatically managed)

These files are managed by the Dashboard and typically don't require manual editing.

• Limit particle/object counts
• Use requestAnimationFrame for animations
• Clean up properly in destroy()
• Test on target hardware

npm run build

npm run dist:mac

This creates a distributable DMG in the release/ directory.

Universal mac builds bundle both Intel (x64) and Apple Silicon (arm64) into a single app, which significantly increases the download size.

To build two smaller DMGs (one per architecture):

npm run dist:mac:split

Or build a specific architecture:

npm run dist:mac:arm64
npm run dist:mac:x64

npm run dist:win

This creates a portable Windows .exe in the release/ directory.

The project uses GitHub Actions to automatically build and attach release artifacts (macOS DMGs for arm64 + x64, plus Windows portable .exe):

1. Tag a new version: git tag v1.0.0
2. Push the tag: git push origin v1.0.0
3. GitHub Actions builds the artifacts and creates a release automatically

See .github/workflows/release.yml for the CI configuration.

• Report bugs via issues
• Submit pull requests for improvements
• Share modules via discussions

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

• Getting Started Guide
• Module Development Guide
• E2E Testing Guidelines
• Contributing Guide

Electron, React, Three.js, p5.js, D3.js, WebMIDI

• GitHub Issues
• GitHub Discussions