Humusprivate beta

10. Grow your own

Goal: write an organism of your own in C++, put it in a pack, and see it in the organism list next to the ones that ship.

You leave with: a pack you built, installed, and playing in a patch, and the map of where the SDK goes deeper.

How Humus is layered

Three layers, and the arrows only point down:

  • The engine is the host: the patcher, the transport, the timeline, the Metapad, capture. It knows no organism by name.
  • The SDK in sdk/include/hum/ is the contract every organism is written against: Organism, Transport, Parameter, the capability interfaces, and a dsp/ toolkit of building blocks. No dependencies, no GUI.
  • Packs are the organisms. The ones that ship are packs too, built the same way, so nothing you write is second class.

A pack is a folder: a pack.json for identity, one register.cpp, one entry.cpp of boilerplate, and one folder per organism holding the DSP class, its organism.json (class, category, parameters, editor pointer) and an optional editor blueprint. The rule of the system: code registers factories, manifests carry metadata. Your C++ only makes sound; the host learns the knobs, the category and the editor from the JSON.

Steps

  1. Read the sample pack. packs/sample/ holds two commented organisms: Tremolo, the hello world in about fifty lines, and PingPong, a tempo-synced delay on the SDK's delay line.
  2. Build it. make pack builds every pack in the source into .humpack bundles, the sample one included.
  3. Install it. Settings > Packs > Install pack, pick sample.humpack. Tremolo and PingPong appear in the organism list under their own root.
  4. Play it. Cord Tremolo after Grit. It is an organism like any other: presets, the dice, MIDI Learn, capture.
  5. Copy Tremolo into a folder of your own inside the pack, rename the class in the header, the .cpp and the organism.json, and register it.
  6. Change the sound. Reach for hum/dsp/ first: a biquad, an LFO, an envelope follower, a delay line. Read parameters with params.get, never allocate or lock inside process(), and fill every output channel.
  7. Give it knobs. Add a parameter to the organism.json with a min, a max and a default, mark it "random": true if the dice may roll it, and the editor grows a knob without a line of GUI code.
  8. Write its help. help/<Class>.md is the text behind the ? on its bar, and the page the website shows.
  9. Rebuild, reinstall, play. Then share the .humpack; anyone installs it the same way, and a patch that used it still opens without it.

Shot list

  1. The three layers drawn as three boxes, the arrows pointing down.
  2. The sample pack folder opened, Tremolo's header on screen, the fifty lines scrolled.
  3. make pack in the terminal, the bundle appearing.
  4. Settings > Packs, Install pack, the new root in the organism list.
  5. Tremolo cord after Grit, the wobble heard.
  6. Tremolo copied, renamed, one line of DSP changed, the sound changed.
  7. A parameter added to the JSON, the knob appearing on rebuild.
  8. The help file written, the ? showing it.
  9. The .humpack dragged to a friend's machine, the same organism playing.

Go deeper

  • The organism SDK: the layers, the dsp/ toolkit, control pins, families, the dice, sigils.
  • packs/sample/README.md in the source: the full tutorial, the C ABI, packaging and the conformance suite.
  • Architecture notes: why editors are blueprints, the audio graph, the document format, the pack boundary.