Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
Contributing to Nota
Thanks for wanting to help. This document covers the things that are specific to this project — the licensing agreement, the architecture rules you must not break, and how to get a change reviewed.
Start with ARCHITECTURE.md. Nota is a real-time audio application,
and a change that looks harmless in most codebases (allocating in a callback, taking a
lock, logging from the wrong thread) will produce audible dropouts here.
Start with an approved issue
Every change needs an issue that a core contributor has approved — before you write code, a spec, or a prompt for an agent. This includes typos and one-line fixes. Pull requests without one are closed unreviewed, however good the work is.
- Find an existing issue or open one: what you want to change and why. For a bug, the report itself is enough.
- Wait for a core contributor (see
.github/CODEOWNERS) to add theapprovedlabel. They may ask questions, narrow the scope or decline — that is the point: it costs a comment, not a weekend of your time and tokens. - Comment that you are taking it, so two people don't build the same thing.
- Build exactly what the issue agreed. If the scope needs to change along the way, say so in the issue first.
- Link it from the pull request:
Closes #N(orRefs #N).
Issues labelled good first issue or help wanted are already approved. Release pull
requests cut by core contributors are the one exception.
Licensing your contribution
Nota is licensed under AGPL-3.0-only (see LICENSES/).
By submitting a contribution, you agree that your work is licensed under AGPL-3.0-only.
If you are not comfortable with that, please open an issue to discuss instead of sending code.
If you are employed as a programmer, check your employment agreement before contributing. Many contracts assign copyright in your code to your employer, in which case they — not you — must grant the license above.
Every new source file needs the standard two-line header:
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2026 Egor Khindikaynen (Nota). See LICENSES/ for license terms.
Adding a dependency
Don't add one without checking it first. Every dependency must be AGPL-compatible.
- Confirm the license qualifies.
- Add a row to
LICENSES/third-party.md. - Say so in the pull request.
A copyleft dependency that is not already accounted for will be rejected — the JUCE situation (which is why this project is AGPL rather than GPL) is the one exception, and it took a deliberate architectural decision to contain it.
Rules you must not break
These are described in full in ARCHITECTURE.md.
The short version:
- The audio thread never allocates, locks, or does I/O (AR-6). No
new, nomalloc, nostd::string, no mutex, no file access, no logging. If you need to get data to the audio thread, use the lock-free command queue (AR-4). - Structural edits publish a new immutable graph snapshot (AR-5). Do not mutate a live graph in place.
- Only a pure C ABI crosses the managed/native boundary (AR-7). No C++ types, no
exceptions. Extend
nota_engine.hrather than working around it. - No JUCE outside
pluginhost/. The core engine's JUCE-freedom is both an architectural and a licensing constraint. Transportis the only source of musical time (AR-9).
Spec-driven workflow
For anything non-trivial — a feature, a behaviour change, a hard bug — don't start with code. Start with a spec. This repository runs Spec Kit, and the AI agents it supports (Claude Code, Copilot, Cursor, Gemini, Codex) already have the commands installed. The workflow:
/speckit-specify— writespec.md: what and why, user stories, requirements./speckit-clarify(optional) — tighten underspecified areas./speckit-plan— writeplan.md: technical approach, audio-thread impact./speckit-tasks— break it into dependency-orderedtasks.md./speckit-implement— execute the tasks./speckit-converge— verify nothing was missed; repeat until it reports Converged.
Artifacts live in specs/<slug>/ and are committed alongside the code. A completed
example is kept at specs/000-example/ — read it before your
first run. Bug reports can take the analogous /speckit-bug-assess → /speckit-bug-fix
→ /speckit-bug-test path; the report directory lands in .specify/bugs/<slug>/.
Two things govern agents working here: the project constitution at
.specify/memory/constitution.md (principles distilled from this document and
ARCHITECTURE.md), and this document — which remains canonical for
humans. You don't need an AI agent to contribute: writing spec.md and plan.md by
hand from the templates in .specify/templates/ is equally welcome.
The project skills (nota-design, nota-docs, nota-features, nota-instrument,
nota-pr, nota-shortcuts, release) are written once in .claude/skills/ and copied
into the directories the other agents read (.agents/skills/, .github/skills/,
.cursor/skills/, .gemini/skills/). Edit the source, then run
scripts/sync-agent-skills.sh; CI fails if a copy is out of date. Typos, small fixes
and doc edits don't need a spec — but they still need an approved issue (see
Start with an approved issue).
If you work with an AI agent, the agent instructions in AGENTS.md and
CLAUDE.md tell it to check for an approved issue before it does anything.
Give it the issue number up front; don't override that check.
Translating Nota
The desktop app's interface is translated through one mechanism (specs
068 and 077): every text is asked
for by a key, and its English lives in one file, the English reference
src/managed/Nota.Application/Localization/en.json. Nota ships English only. Every other
language lives in nota-daw/nota-translations —
translating, fixing a translation and adding a language happen there, with its own README —
and Nota downloads it from Settings → Appearance → Language.
- Every new user-visible text goes through
Loc, by key. Add the key and its English toen.json, then writeLoc.T("preferences.language.restart")for a text,Loc.F("arrangement.delete_clips", n)for a text with values ("Delete {0} clips?"— the whole sentence, never a piece of it) andLoc.Plural("arrangement.clips", n)for a counted text ({ "one": "{0} clip", "other": "{0} clips" }inen.json); in XAML write{app:T 'main.save_as'}. The key is always a plain literal. - Keys: lower-case, dot-separated, area first, then what the text says —
<area>[.<sub-area>].<what>, segments ofa-z 0-9 _, up to 80 characters. The area is the window or view the text belongs to (preferences,arrangement,main.menu,device.reverb); a text used the same way in three or more areas iscommon.<what>(common.cancel). Two meanings of one English word are two keys (menu.open,clip.open) — there are no contexts. - Changing English: edit the text in
en.jsononly; no call site and no translation changes, and every translation stays attached. If the meaning or the placeholders change, make a new key instead and delete the old one, so translators see a new text rather than a stale one. Placeholders are{0}…{9}, and every text must format. - The smoke test fails on a key used in the code that is not in
en.json, anen.jsonkey nothing uses, a key used against its shape (a counted text throughLoc.T, a pattern with{0}throughLoc.T), an English text that does not format, a translation file inside the app, and a new plain literal that reads as interface text. Text that is not translated on purpose — user content, device and parameter names, proper nouns, units, logs, the Remote web page and MCP — is listed with its reason as# data:intests/Nota.SmokeTest/LocalizationAllowList.txt. - New texts reach translators by themselves: nota-translations pulls
en.jsonfromdevelopand from every release tag, and checks each language against them. A new key shows in English until a translation for it is merged there — nothing to do in this repository. - Look at it:
NOTA_UI_LANGUAGE=fr(an installed language) orNOTA_UI_LANGUAGE=/path/to/fr.json(any language file) starts Nota in that language for one run without touching the saved setting; check that nothing is clipped or overlaps at each interface scale.NOTA_LANGUAGES_URLpoints the language list at another copy of nota-translations (a URL, or a local folder with its layout).NOTA_LOC_WRITE_BASELINE=1rewrites the allow-list after you wrap or add text.
Building
See README.md for prerequisites and per-platform build commands, and
BUILD.md for details. In short:
scripts/build.sh # macOS — native + managed + smoke test
pwsh scripts/build-win.ps1 # Windows (Developer PowerShell for VS 2022)
scripts/build-linux.sh # Linux
dotnet run --project src/managed/Nota.App
The build scripts run the smoke test (tests/Nota.SmokeTest), which drives the engine
end-to-end through the C ABI. It must pass before you open a pull request.
Branches
developis where work lands. Branch from it and open your pull request against it.mainholds released code only. It moves forward when a release is cut fromdevelop; pull requests straight intomainare not accepted.
Name your branch after the change — feat/stereo-pan-law, fix/clip-fade-click — and
keep it up to date by rebasing on, or merging in, the latest develop. Pull requests are
squash-merged, so the pull request title becomes the commit message on develop: write
it in the same form as the existing history, (feat) …, (fix) …, (docs) …,
(chore) ….
Continuous integration
Every pull request is built on macOS, Windows and Linux, and the smoke test runs on each
(.github/workflows/ci.yml). All three must pass before a pull request can be merged.
If this is your first contribution, a maintainer approves the CI run before it starts.
A pull request that touches the engine also runs the performance gate
(.github/workflows/perf.yml, see BUILD.md). It fails when
any engine scenario does more than 1% more work (CPU instructions) or takes more than
15% longer than on the base branch, or when an idle engine uses CPU. If a slowdown is the price of a deliberate change (a better-sounding
default, say), say why in the PR; a maintainer accepts it by adding the
perf-regression-accepted label, and the report still lists it.
Pull requests
- Target
develop. - Link the approved issue it implements (
Closes #N). - One logical change per pull request.
- Match the style of the code around you. Comment headers explain why a file exists, not what each line does — keep that convention.
- If you change engine behaviour, extend the smoke test to cover it.
- If you change user-visible behaviour, add a
CHANGELOG.mdentry. - Say which platforms you actually built and tested on.
- For a visible change, show it: add before/after screenshots to the description (see below).
Screenshots and other images
Images for pull request descriptions and issues live on the pr-assets branch. It
is an orphan branch with no code that is never merged, so images don't bloat develop
and stay available after a branch is deleted. Use that one branch rather than creating a
new branch per pull request.
- Put each pull request's images in their own folder, named after the change or the
issue, for example
fold/orissue-137/. Images attached to issues from outside GitHub go underissues/. - Add images by committing on top of
pr-assets. Never force-push it or rewrite its history, because existing descriptions link to its files. - Embed with the raw URL:

git fetch origin pr-assets
git worktree add ../nota-assets pr-assets
mkdir -p ../nota-assets/my-change && cp after.png ../nota-assets/my-change/
git -C ../nota-assets add my-change && git -C ../nota-assets commit -m "Images for my change"
git -C ../nota-assets push origin HEAD:pr-assets
A user-visible UI change carries before/after screenshots there; a performance change
carries a before/after benchmark — scripts/bench-engine.sh measures engine builds through
the C ABI and scripts/bench-chart.py turns the results into charts and a table. The
smoke test's render-pool guards (RenderPoolTests, -- --perf alone) catch the
regressions automatically; a performance fix adds a guard there.
You can also drag images straight into the GitHub description box when you write it by hand. The branch is for images added by scripts or tools, and for anything you want to keep alongside the repository.
Reporting bugs
Include your OS and version, the Nota version (Help -> About), your audio device and buffer size, and — for audio problems — whether it reproduces with plugins disabled. Crash and dropout reports are much more useful with a project that reproduces them.