Xtal

A framework build around Nannou with a feature-packed control UI for creating stuff like this:

You can see more screenshots here on github by looking at the auto generated markdown index or checkout audio-visual compositions on Instagram.

Intro

Xtal is a hybrid Rust application and library build on top of the Nannou creative coding framework. It is essentially one big Nannou app packed with tons of features to aid in live performance with a strong emphasis on interaction and musically-aware synchronization.

If you are already familiar with Rust and Nannou you should have no problem getting Xtal up and running quickly. If you are not familiar with Rust or Nannou but have experience with creative coding then I highly recommend you get comfortable building Nannou sketches first, starting with their guide.

Features

• Runtime switching of sketches
• Video recording with one button press (requires ffmpeg)
• Beat-based animation with musical timing
• Flexible synchronization - BPM, MIDI clock, MIDI Time Code, or Ableton
• Parameter automation via MIDI CC, OSC, and audio input
• Recording sync with MIDI Start for perfect post-production alignment
• Hot-reloadable controls via YAML files (see Control Scripting)
• Simple UI controls - Add sliders, checkboxes, and selects with minimal code
• Persistent parameters automatically saved per sketch
• Hot-reloadable WGSL shaders with starter templates
• Snapshots system - Store/recall settings with musical transitions
• Parameter randomization with configurable transition times
• Selective control exclusions from randomization
• MIDI Learn - Map hardware controllers to any UI parameter
• Tap Tempo for syncing with live music
• Adaptive theming for light/dark mode

Light Mode

Dark Mode

Getting Started

Note: Xtal is pre-v1 and transitioning from an application to a reusable library. Currently developed on macOS and requires running in "dev mode." Cross-platform compatibility expected but not fully tested.

Requirements:

• Rust
• Node or Bun (preferred) for the UI
• (Optional) ffmpeg for video exports

1. Clone or fork this repo. Until Xtal has a proper release on crates.io, you must use the [sketches] app (alternatively you can create your own workspace folder and follow the same pattern – this will make it easier to merge in upstream changes without interfering with your own code).
2. Start the UI server:

   cd ./xtal-ui
   bun install  # or npm install (first time only)
   bun start    # or npm start
   

3. In another terminal, run the main app:

   cargo run --release  # optionally add <sketch> to specify which loads
   

For full documentation, run cargo doc --package xtal --open in the project root. There is also a dumping ground of documentation and tips in the docs folder. If you need help or come across any issues please don't hesitate to file an issue. Happy coding!