Your First Project

So far you’ve been evaluating code line by line in VSCode — perfect for exploring and live coding. But when you want to save a piece, share it, or run it straight from the command line, you wrap it in a project. Let’s make one.

Two Ways to Work

Note

Resonon gives you two complementary workflows, and they speak the same language:

• VSCode (select-and-execute) — for live coding and experimentation. Evaluate individual lines or selections with Cmd+Enter; state accumulates as you go.
• resonon run — for running a complete script from the command line. Executes src/main.non top to bottom. Use it for rendering, automation, or sharing a reproducible piece.

Code that works in one works in the other.

Create a Project

Scaffold a project with resonon new:

resonon new my_song

You’ll see exactly what it created:

  Created resonon.toml
  Created src/
  Created src/main.non
  Created README.md
  Created LICENSE
  Created .gitignore
  Initialized git repository

Project 'my_song' initialized.

That’s a complete, ready-to-run project in a my_song/ directory.

Project Structure

my_song/
├── resonon.toml          # Project manifest
├── src/
│   └── main.non          # Entry point
├── README.md
├── LICENSE
└── .gitignore

resonon.toml

The manifest describes your project:

[package]
name = "my_song"
version = "0.1.0"
authors = ["Your Name <email>"]
resonon = "0.8.22"          # filled in with your installed Resonon version

[dependencies]
# example = { source = "gh:user/repo", version = "v1.0" }

Field	Description
name	Project name
version	Your project’s version
authors	List of authors
resonon	Minimum Resonon version required
[dependencies]	External packages (empty by default)

src/main.non

This is the entry point — the file resonon run executes. The scaffolded template just prints a greeting:

// Entry point — run with `resonon run`

project_title("my_song");
project_bpm(120);

fn greet(name) {
    PRINT f"Hello from {name}!";
}

greet("my_song");

project_title and project_bpm set metadata for the piece. Everything else is yours to replace with music.

Run the Project

From inside the project directory (or any subdirectory), run:

cd my_song
resonon run

Resonon searches upward for resonon.toml, then executes src/main.non. You’ll see the greeting print in your terminal.

You can also run any .non file directly, no project required:

resonon my_script.non

Adding Music

Now swap the template for something that actually plays. Here’s a starting point using what you built in the previous guides — drums and a clap, all from the bundled CR-78 kit:

project_title("my_song");
project_bpm(120);

use "std/instruments" { Sampler, Kit };

// Drums
let drums = AudioTrack("drums");
drums.load_instrument(Sampler(Kit("CR-78")));
drums << [bd _ sd _, hh hh hh hh];

// Clap on the off-beats
let perc = AudioTrack("perc");
perc.load_instrument(Sampler(Kit("CR-78")));
perc << [_ cp _ cp];

PLAY;

Drop that into src/main.non and resonon run will play it.

Tip

Open the project in VSCode and use select-and-execute to develop interactively. Once you’re happy with the result, save it in src/main.non so it’s reproducible with resonon run.

Project Variants

resonon new takes flags for different kinds of projects:

Flag	Description
--lib	Library project (src/lib.non instead of src/main.non)
--kit	Sample kit project (adds a kits/ directory)
--native	Native Rust extension project (adds a native/ crate)

resonon new my_library --lib           # Importable library
resonon new my_drums --kit             # Sample kit with kits/ directory
resonon new my_plugin --native         # Rust extension with native/ crate

Already inside a directory? Scaffold in place with resonon init:

mkdir my_project && cd my_project
resonon init my_project

Next Steps

Continue the quickstart or jump into the reference docs:

• Custom DSP — write your own effects and synthesizers
• MIDI I/O — MIDI output, input, and learn mapping
• Pattern Basics — deep dive into time division, pattern types, and looping
• Samplers — drum kits, melodic samplers, and sample manipulation
• VSCode Extension — full editor reference with shortcuts and features