Contributing

Bug reports, feature requests, and pull requests are welcome in the main Orchard repository.

Reporting

Public bug reports and feature requests go in the Issues tab.

Private reports can be filed from Orchard’s in-app Support System, with optional diagnostics and screenshots. Those create a conversation you can follow inside the app.

Either way, include your Orchard version, platform, and the output of Settings → Diagnostics.

Before submitting a code change

1. Create a focused branch.
2. Keep unrelated changes out of the same pull request.
3. Run npm test.
4. Run npm run build:frontend for renderer-only work, or npm run build when native code is affected.
5. Explain what changed and how it was tested.

Step 5 carries more weight than it looks like. Audio work in particular is easy to change in ways that pass every test and sound worse, so say what you listened to and what you measured.

Setting up

See Building from Source. In short:

npm ci
npm run dev

Testing

npm test           # full suite
npm run test:native  # audio, transition, and analysis subset

Tests use Node’s built-in test runner. Add tests alongside behavior changes, particularly for anything in the analysis or transition pipeline, where regressions are hard to hear until they are shipped.

test/ipcChannels.test.js exists specifically to prevent the preload’s duplicated channel literals from drifting from shared/ipcChannels.js. If you add an IPC channel, update both.

Working on audio

A few conventions that have been paid for in advance:

Measure, do not assume. Analysis changes that look right in code have repeatedly turned out worse on real material. Compare against reference captures, and compare at a consistent sample rate, because mismatched rates produce numbers that look meaningful and are not.

Keep confidence attached to values. Every measured quantity in the analyzer travels with a confidence. Policy code grades its own ambition from those confidences. A change that produces a value without a confidence, or that merges an unconfident source at full trust, breaks the guarantee that a bad analysis cannot produce a confident-sounding mix. Catalog BPM merges at beatConfidence 0 for exactly this reason.

Degrade in explicit tiers. When evidence is missing, the answer is a less ambitious transition with a stated reason, and never a confident transition on junk data.

See Smart Crossfade and Native Audio Analyzer.

Working on the process boundary

The preload (electron/preload/index.cjs) is a security boundary. Keep it dependency-free, expose narrow structured operations, and never hand the renderer a raw ipcRenderer.

The renderer runs sandboxed under a strict CSP. Anything requiring eval or Function() will fail there, which is why Zod is configured jitless.

See Architecture.

Code style

Match the surrounding code. Orchard’s existing style favors comments that explain why a threshold or a design choice exists rather than restating what the code does, and the audio modules in particular carry a lot of that reasoning. Preserve it when you touch those files.

Licensing of contributions

Orchard is AGPL-3.0-or-later from 4.0.0 onward. Contributions are accepted under that license. New source files should carry the standard AGPL header used throughout the codebase. See License and Legal.

Supporting the project

If you would like to support development, consider buying the author a coffee on Ko-fi.