[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-78632":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":26,"discoverSource":27},78632,"nw_wrld","aagentah\u002Fnw_wrld","aagentah","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.",null,"TypeScript",2014,188,34,2,0,1,5,28.83,"GNU General Public License v3.0",false,"main",[],"2026-06-12 02:03:48","# nw_wrld\n\nnw_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.\n\nVisuals can be triggered via the built-in 16-step sequencer or by configuring external MIDI, OSC, audio capture, or file-upload inputs.\n\n![Node Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fnode-%3E%3D20.0.0-brightgreen)\n![Electron](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Felectron-v39.2.7-blue)\n\n\u003Cimg width=\"1512\" height=\"901\" alt=\"Screenshot 2026-01-09 at 14 17 49\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F9d59fe7d-cc3b-48ec-af11-007a9379cac5\" \u002F>\n\n## Beta Notice\n\nThis project is currently in beta. Downloadable installers are provided via GitHub Releases for macOS, Windows, and Linux, and `nw_wrld` can also be run from source using this repository. Please note that whilst the project is in beta, there may be frequent breaking changes between releases.\n\n## Roadmap\n\n- [x] Isolated sandbox and module-workspace bundling\n- [x] Docblock-declared module dependencies with automated runtime injection\n- [x] TypeScript migration\n- [x] Unit tests, E2E Playwright tests, runtime validations\n- [ ] Use-case specific User Guides (Ableton, strudel, TouchDesigner, etc.)\n- [x] Signed and notarized macOS app builds\n- [x] Signed Windows app builds\n- [x] Robust Linux & WSL support\n- [ ] Userdata, Module, and JSON versioning (+ migration scripts)\n- [x] Multi-band audio threshold analysis (local processing) for channel triggers\n- [ ] Advanced default sequencer (Working sampler with audio FX)\n- [ ] Remote API input source with HTTP\u002FWebSocket client for cloud-based services (audio analysis APIs, ML models, etc.)\n- [ ] Serial port input support for hardware sensor integration\n\n## Features\n\n- **Built-in 16-step pattern sequencer** - Create rhythmic audiovisual compositions without external hardware\n- **External MIDI\u002FOSC\u002Faudio\u002Ffile support** - Use MIDI, OSC, microphone\u002Floopback audio capture, or uploaded audio files as trigger sources\n- **Visual module system** - Build custom visuals with p5.js, Three.js, D3.js, or vanilla JavaScript\n- **Hot module reloading** - Edit modules and see changes instantly\n- **Project folder workflow** - Self-contained, portable projects with modules, assets, and data\n- **Flexible method mapping** - Trigger any visual method with sequencer patterns or external signals\n- **Per-track signal settings** - Configure per-track thresholds and trigger cooldown for audio and file modes\n- **Module enable\u002Fdisable toggle** - Disable modules per track without removing configuration\n\n---\n\n## Installation\n\n### For Developers\n\nBuild from source to contribute or customize:\n\n**Prerequisites:** Node.js v20+ and basic terminal knowledge\n\n```bash\n# 1. Clone the repository\ngit clone https:\u002F\u002Fgithub.com\u002Faagentah\u002Fnw_wrld.git\ncd nw_wrld\n\n# 2. Install dependencies\nnpm install\n\n# 3. Start the app\nnpm start\n```\n\nTwo windows will open:\n\n- **Dashboard**: Control center for creating tracks, programming patterns, and configuring visuals\n- **Projector**: Visual output window\n\n---\n\n## E2E Testing (Playwright)\n\n```bash\nnpm run test:e2e\n```\n\n- E2E tests launch the real Electron app and control the windows via Playwright.\n- Test artifacts (screenshots\u002Ftraces on failure) are written to `test-results\u002F` (gitignored).\n- Tests can boot into an isolated project folder by setting `NW_WRLD_TEST_PROJECT_DIR`.\n\n---\n\n## Project Folders\n\nnw_wrld uses a **project folder** model. Each project is a self-contained folder containing your modules, assets, and data.\n\n**Note:** Workspace modules are JavaScript code executed by nw_wrld. Only open project folders you trust.\n\n### What's Inside a Project Folder\n\n```\nMyProject\u002F\n├── modules\u002F           # Visual modules (hot-reloadable JavaScript files)\n│   ├── Text.js\n│   ├── GridOverlay.js\n│   ├── SpinningCube.js\n│   └── ...16 starter modules\n├── assets\u002F            # Images, JSON, and other resources\n│   ├── images\u002F\n│   │   └── blueprint.png\n│   └── json\u002F\n│       └── meteor.json\n└── nw_wrld_data\u002F      # Tracks, settings, and recordings\n    └── json\u002F\n```\n\n### First Launch Experience\n\nWhen you first launch nw_wrld, you'll be prompted to select or create a project folder. The app automatically scaffolds a working project with:\n\n- **16 starter modules** - Ready-to-use examples (2D, 3D, text, data visualization)\n- **Sample assets** - Images and JSON data files\n- **Data storage** - Configuration, tracks, and recordings\n\n### Portability\n\nProjects 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.\n\n### Lost Project?\n\nIf your project folder is deleted, moved, or disconnected, nw_wrld will prompt you to reselect it (see [Getting Started](GETTING_STARTED.md#if-your-project-folder-goes-missing)).\n\n---\n\n## Quick Start\n\n### 60-Second Test\n\n1. Click **[CREATE TRACK]** → Name it → Create\n2. Click **[+ MODULE]** → Select **Text** or **Corners**\n3. Click **[+ CHANNEL]** to add a sequencer row\n4. Click some cells in the 16-step grid (they turn red)\n5. Assign a method to the channel (e.g., `color` or `rotate`)\n6. Click **[PLAY]** in the footer\n\nYou'll see the playhead move across the grid and trigger your visuals. No external setup required!\n\n---\n\n## How It Works: The Big Picture\n\n```\nSignal Sources:\n┌──────────────┐\n│  Sequencer   │──┐\n│  (Built-in)  │  │\n└──────────────┘  │\n                  ├──▶ Dashboard ──▶ Projector\n┌──────────────┐  │    (Control)     (Visuals)\n│ External     │──┘\n│ MIDI\u002FOSC\u002F    │\n│ Audio\u002FFile   │\n└──────────────┘\n```\n\nDashboard is where you compose and map triggers; Projector is where visuals render and respond.\n\n---\n\n## Your First Workflow (Sequencer Mode)\n\nFollow the [Getting Started Guide](GETTING_STARTED.md) for detailed step-by-step instructions.\n\nThe built-in sequencer is perfect for testing modules and creating standalone audiovisual pieces without external hardware.\n\n---\n\n## Advanced: External Input Control\n\nFor live performance and reactive workflows, you can use MIDI controllers\u002FDAWs, OSC senders, audio input devices, or uploaded audio files.\n\nTo set up input routing and switch modes, see [Getting Started](GETTING_STARTED.md#advanced-connect-external-midiosc).\n\n### DAW Quickstart (Ableton \u002F FL Studio \u002F Logic \u002F etc.)\n\nMost 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:\n\n- **Option A (simplest): Single MIDI channel**\n  - In nw_wrld → Settings → External (MIDI\u002FOSC) → MIDI:\n    - **Method Triggers MIDI Channel**: `1`\n    - **Track Select MIDI Channel**: `1`\n  - Use **Settings → Configure Mappings** to choose either:\n    - **MIDI (Pitch Class)**: octave-agnostic mapping using C..B (avoids DAW octave-name differences)\n    - **MIDI (Exact Note)**: octave-specific mapping using full MIDI note numbers (0–127)\n  - Then map which triggers activate track selection vs method triggers.\n\n- **Option B (clean separation): Split MIDI channels**\n  - In your DAW, route method trigger notes to Channel 1 and track-selection notes to Channel 2 (commonly done with separate MIDI routing tracks\u002Fdevices).\n  - In nw_wrld → Settings:\n    - **Method Triggers MIDI Channel**: `1`\n    - **Track Select MIDI Channel**: `2`\n\n---\n\n## Creating Visual Modules\n\nModules are JavaScript files in your **project's `modules\u002F` folder**. Edit them with any text editor and nw_wrld hot-reloads automatically.\n\n### Quick Module Creation\n\nCreate or edit a `.js` file in your project’s `modules\u002F` folder and save — nw_wrld hot-reloads it automatically.\n\n### Module File Contract (Docblock + Default Export)\n\nWorkspace modules are loaded from your project folder and must follow a strict contract:\n\n- **Filename is identity**: `modules\u002FMyModule.js` → module id `MyModule` (must be alphanumeric and start with a letter)\n- **Docblock metadata is required**: `@nwWrld name`, `@nwWrld category`, `@nwWrld imports`\n- **Imports are declarative**: list what you need; nw_wrld injects safe bindings for you\n- **Default export is required**: `export default MyModule`\n\nAllowed `@nwWrld imports`:\n\n- **SDK**: `ModuleBase`, `BaseThreeJsModule`, `assetUrl`, `readText`, `loadJson`\n- **Global libs**: `THREE`, `p5`, `d3`\n\n```javascript\n\u002F*\n@nwWrld name: My Module (Display Name)\n@nwWrld category: 2D\n@nwWrld imports: ModuleBase, assetUrl, loadJson\n*\u002F\n\nclass MyModule extends ModuleBase {\n  async init() {\n    const imgUrl = assetUrl(\"images\u002Fblueprint.png\");\n    const data = await loadJson(\"json\u002Fmeteor.json\");\n  }\n}\n\nexport default MyModule;\n```\n\nSee the [Module Development Guide](MODULE_DEVELOPMENT.md) for complete documentation including:\n\n- Full module structure and lifecycle\n- Method definitions and option types\n- SDK API reference and asset loading\n- Library usage (p5.js, Three.js, D3.js)\n- Advanced patterns and best practices\n\n---\n\n## Built-in ModuleBase Methods\n\nWhen you extend `ModuleBase`, you inherit powerful methods for free: `show`, `hide`, `offset`, `scale`, `opacity`, `rotate`, `randomZoom`, and `matrix`.\n\nThese methods can be triggered via the sequencer or external signal sources (MIDI\u002FOSC\u002Faudio\u002Ffile), giving you instant control over positioning, visibility, transformations, and effects.\n\nSee the [Module Development Guide](MODULE_DEVELOPMENT.md#option-types-reference) for complete documentation of all built-in methods and their parameters.\n\n---\n\n## Two Modes: Sequencer vs External\n\nSwitch between modes in **Settings → Signal Source**.\n\n**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.\n\n**External Modes (Advanced)** - Use one of the following sources:\n\n- **MIDI (Pitch Class)**: map C..B (octave-agnostic). This avoids “G7 vs G8” naming differences across DAWs because matching is based on pitch class.\n- **MIDI (Exact Note)**: map full MIDI note numbers (0–127) for octave-specific triggers.\n- **OSC**: map OSC addresses.\n- **External Audio**: capture live audio from a selected input device and trigger channels from Low\u002FMedium\u002FHigh bands.\n- **File Upload**: upload an MP3\u002FWAV per track and trigger channels from Low\u002FMedium\u002FHigh bands during playback.\n\nConfigure global mappings in Settings for consistent control across all tracks.\n\nSwitch modes anytime - your tracks, modules, and methods remain the same. Only the trigger source changes.\n\n---\n\n## Starter Modules\n\nEvery new project includes 16 starter modules in your `modules\u002F` folder:\n\n**2D & UI:**\n\n- **Text** - Configurable text display and manipulation\n- **Corners** - DOM-based corner UI elements\n- **GridOverlay** - Canvas-based grid overlay\n- **GridDots** - Animated dot grid patterns\n- **Frame** - Border frame overlay\n- **Image** - Load images from workspace assets\n- **CodeColumns** - Animated code\u002Ftext columns\n\n**3D Graphics:**\n\n- **SpinningCube** - Basic Three.js example\n- **CubeCube** - Nested cube visualization\n- **OrbitalPlane** - Orbital mechanics simulation\n- **LowEarthPoint** - Low earth orbit visualization\n\n**Data Visualization:**\n\n- **AsteroidGraph** - p5.js with workspace JSON data\n- **MathOrbitalMap** - Mathematical orbit mapping\n- **CloudPointIceberg** - 3D point cloud\n- **ZKProofVisualizer** - Zero-knowledge proof visualization\n\n**Getting Started:**\n\n- **HelloWorld** - Minimal working example\n\nStudy these modules to learn patterns for 2D, 3D, text, and data visualization. All are fully editable in your project's `modules\u002F` folder.\n\n---\n\n## Project Structure\n\n### Your Project Folder (Where You Work)\n\n```\nMyProject\u002F\n├── modules\u002F                    # ← YOUR MODULES GO HERE\n│   ├── Text.js\n│   ├── GridOverlay.js\n│   ├── SpinningCube.js\n│   ├── YourCustomModule.js    # Create your own modules here\n│   └── ...16 starter modules\n│\n├── assets\u002F                     # ← YOUR ASSETS GO HERE\n│   ├── images\u002F\n│   │   ├── blueprint.png      # Included starter asset\n│   │   └── your-image.png     # Add your own images\n│   └── json\u002F\n│       ├── meteor.json         # Included starter dataset\n│       └── your-data.json      # Add your own data\n│\n└── nw_wrld_data\u002F               # App data (auto-managed)\n    └── json\u002F\n        ├── userData.json       # Tracks, settings, mappings\n        ├── appState.json       # Current app state\n        ├── config.json         # App configuration\n        └── recordingData.json  # Recording data\n```\n\n### Application Source (For Developers)\n\n```\nnw_wrld\u002F\n├── src\u002F\n│   ├── dashboard\u002F              # React UI for control\n│   │   ├── Dashboard.js        # Main dashboard logic\n│   │   ├── modals\u002F             # UI modals\n│   │   ├── components\u002F         # Reusable components\n│   │   └── styles\u002F             # Dashboard styles\n│   │\n│   ├── projector\u002F              # Visual output window\n│   │   ├── Projector.js        # Main projector logic\n│   │   ├── helpers\u002F\n│   │   │   ├── moduleBase.ts   # Base class (the foundation)\n│   │   │   └── threeBase.ts    # Three.js base class\n│   │   └── templates\u002F\n│   │       └── ThreeTemplate.ts # 3D module template\n│   │\n│   ├── main\u002F                   # Electron main process\n│   │   ├── InputManager.js     # MIDI\u002FOSC input handling\n│   │   ├── starter_modules\u002F    # Starter modules (seeded into projects)\n│   │   └── workspaceStarterModules.js\n│   │\n│   ├── shared\u002F\n│   │   ├── json\u002F               # JSON file management\n│   │   ├── config\u002F             # Default configuration\n│   │   ├── sequencer\u002F          # Sequencer playback engine\n│   │   ├── midi\u002F               # MIDI utilities\n│   │   └── audio\u002F              # Audio feedback\n│   │\n│   └── renderer.ts             # SDK initialization\n│\n├── package.json\n└── README.md\n```\n\n---\n\n## Configuration\n\nConfiguration files are stored in your project's `nw_wrld_data\u002Fjson\u002F` directory:\n\n- **`userData.json`** - Tracks, mappings, and settings (automatically managed)\n- **`appState.json`** - Current app state and workspace path (automatically managed)\n- **`config.json`** - App configuration, aspect ratios, background colors (automatically managed)\n- **`recordingData.json`** - Recording data (automatically managed)\n\nThese files are managed by the Dashboard and typically don't require manual editing.\n\n---\n\n## Troubleshooting\n\n| Issue                                 | Solution                                                                                                       |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| Project folder missing                | App will prompt to reselect - choose or create a new project                                                   |\n| Module doesn't appear                 | Verify filename is `MyModule.js` (letters\u002Fnumbers only), and docblock includes `@nwWrld name\u002Fcategory\u002Fimports` |\n| Module won't load                     | Open Projector devtools; check for syntax errors, missing imports, or unknown imports                          |\n| Module hidden                         | Trigger `show()` method or set `executeOnLoad: true`                                                           |\n| Asset won't load                      | Verify path is relative to `assets\u002F` folder                                                                    |\n| Pattern not playing                   | Check that methods are assigned to channels                                                                    |\n| No MIDI detected                      | Enable IAC Driver\u002FloopMIDI and verify DAW MIDI output                                                          |\n| MIDI works once, then stops (Windows) | Ensure nw_wrld fully closed (no background process). If using a virtual port, restart the port app or reboot.  |\n| Method not triggering                 | Verify mapping, check method name match, check console                                                         |\n| Hot reload not working                | Check file is saved in project's `modules\u002F` folder                                                             |\n| App won't start (dev mode)            | Close other dev servers (port 9000), run `npm install`                                                         |\n\n---\n\n## Performance\n\n- Limit particle\u002Fobject counts\n- Use `requestAnimationFrame` for animations\n- Clean up properly in `destroy()`\n- Test on target hardware\n\n---\n\n## Building for Distribution\n\n### Build the Renderer (Production Bundle)\n\n```bash\nnpm run build\n```\n\n### Build macOS DMG\n\n```bash\nnpm run dist:mac\n```\n\nThis creates a distributable DMG in the `release\u002F` directory.\n\n### Build macOS DMGs (Split by Architecture - Recommended)\n\nUniversal mac builds bundle both Intel (x64) and Apple Silicon (arm64) into a single app, which significantly increases the download size.\n\nTo build two smaller DMGs (one per architecture):\n\n```bash\nnpm run dist:mac:split\n```\n\nOr build a specific architecture:\n\n```bash\nnpm run dist:mac:arm64\nnpm run dist:mac:x64\n```\n\n### Build Windows (portable .exe)\n\n```bash\nnpm run dist:win\n```\n\nThis creates a portable Windows `.exe` in the `release\u002F` directory.\n\n### Build Linux (AppImage + .deb)\n\n```bash\nnpm run dist:linux\n```\n\nThis creates Linux artifacts (typically `.AppImage` and `.deb`) in the `release\u002F` directory.\n\n### Automated Releases\n\nThe project uses GitHub Actions to automatically build and attach release artifacts (macOS DMGs for arm64 + x64, Windows portable `.exe`, and Linux `.AppImage` + `.deb`). A `SHA256SUMS` file is also attached for verifying downloads:\n\n1. Tag a new version: `git tag v1.0.0`\n2. Push the tag: `git push origin v1.0.0`\n3. GitHub Actions builds the artifacts and creates a release automatically\n\nSee `.github\u002Fworkflows\u002Frelease.yml` for the CI configuration.\n\n---\n\n## Contributing\n\n- Report bugs via issues\n- Submit pull requests for improvements\n- Share modules via discussions\n\n---\n\n## License\n\nThis project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Documentation\n\n- [Getting Started Guide](GETTING_STARTED.md)\n- [Module Development Guide](MODULE_DEVELOPMENT.md)\n- [E2E Testing Guidelines](E2E_TESTING_GUIDELINES.md)\n- [Contributing Guide](CONTRIBUTING.md)\n\n---\n\n## Technologies\n\nElectron, React, Three.js, p5.js, D3.js, WebMIDI\n\n## Support\n\n- [GitHub Issues](https:\u002F\u002Fgithub.com\u002Faagentah\u002Fnw_wrld\u002Fissues)\n- [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Faagentah\u002Fnw_wrld\u002Fdiscussions)\n","nw_wrld 是一个基于Web技术的事件驱动序列器，用于触发视觉效果。其核心功能包括内置16步进音序器、支持外部MIDI\u002FOSC\u002F音频文件输入以及自定义视觉模块系统，允许用户通过项目自带的UI编排器来创建和管理视听作品。该项目采用TypeScript编写，提供了热模块重载等开发便利特性，并且支持跨平台运行（macOS、Windows、Linux）。它非常适合用于原型设计、演示、展览及现场表演等多种场景中需要将声音与视觉进行同步展示的情况。","2026-06-11 03:57:04","high_star"]