Your own TheRaK devices

Turn your own MetaSound into an instrument or effect that TheRaK offers in + Add Device, next to Afterglow and the Stereo Delay. You build the sound in the MetaSound editor; DAWntless checks it, keeps its knob layout, and wires it into rack chains for you. No C++ is needed.

A DAWntless device is two assets:

• The graph: a MetaSound Patch, or a MetaSound Source for an instrument, that declares a DAWntless interface. The interface gives the graph its rack connections: MIDI in for an instrument, a bypass flag for an effect, and the tempo for anything that wants it. Audio goes in and out through Unreal's standard audio format interfaces.
• The definition, DA_Device_<GraphName>, saved next to the graph. It holds what a MetaSound cannot keep in a packaged game: the name and category shown in Add Device, the colour, the knob ranges and units, and the validation stamp.

The Device Validator checks a graph against the rules on this page, renders it offline, and registers it, which stamps and saves the definition. Only registered devices whose stamp is still current appear in + Add Device, under INSTRUMENTS > User > <Category> or EFFECTS > User > <Category>, with a USER tag.

In a rack, TheRaK embeds your graph in the chain's own MetaSound, wires MIDI, audio and tempo to it, and turns its inputs into knobs on the device card. Every device in every rack keeps its own knob values; the definition is shared by all of them. In a game, a Blueprint can set your device's Float knobs through the TheRaK Performer's Set Parameter with their chain names (see Parameters and names).

Three example devices, built from stock MetaSound and Harmonix nodes, are in DAWntless Content > Examples > UserDevices (enable Show Plugin Content): Chorus (effect), Pluck (instrument) and Source Lead (a Source instrument). See Example devices.

Use a Patch unless you already have a Source instrument you want to reuse:

• A Patch is Referenceable by default, so a chain can embed it at once. A Source starts without that access flag; the validator's Make Referenceable fix sets it (E7).
• A Source's own settings (attenuation, sends, source effects, concurrency, rate overrides) do nothing inside a chain, because the chain is the sound that plays (warning W1). One Shot is ignored too: the chain keeps playing and never reads On Finished (W2).
• The rack starts an embedded Source for you: it connects the chain's On Play to your Source's On Play, so a graph that waits for On Play works unchanged.
• Sources are instruments only. In Unreal Engine 5.8 a Source cannot declare UE.InputFormat.*, so it has no audio input and cannot process a chain's sound. A Source that declares DAWntless.Effect gets error E6 and the Duplicate as Patch... button. It creates a new Patch next to the Source, with the effect and format interfaces declared, opens it, and lists what to connect. The Source itself is never changed.

Add interfaces in the MetaSound editor, in the MetaSound's Interfaces list, or let the Device Validator's Fix buttons add them. Members are never renamed; new members arrive only in new interface versions, and old versions keep working.

Audio uses Unreal's format interfaces: the inputs In Left and In Right of UE.InputFormat.Stereo (members UE.InputFormat.Stereo.Audio:0 and .Audio:1) and the outputs Out Left and Out Right of UE.OutputFormat.Stereo. Mono works too: a mono output is copied to both channels (W8), and a mono effect input receives the average of left and right.

• MIDI. Notes arrive on track 1, channel 1. The Harmonix MIDI Note Trigger reads every track and channel, so it works as it is. A Fusion Sampler needs its Track Number at 1 or 0. When a rack stops, the instrument receives all-notes-off; MIDI Note Trigger ends its note on it.
• Bypass. The rack wraps every effect in a crossfade, and while the effect is bypassed the chain hears the effect's input exactly, so a rack never needs more. The Bypass member is true at the same time: while it is true, pass your input through unchanged. The validator checks that (R8, a warning) by rendering your effect without the rack's crossfade. The Chorus example does it by setting its delays' wet level to 0 and dry level to 1 while Bypass is true.
• Transport. BPM is the quarter-note tempo, Beat the position in quarter notes at the start of each audio block, and Beats Per Bar the bar length in quarter notes (4 in 4/4, 3 in 3/4 and in 6/8), so the bar phase is Beat modulo Beats Per Bar. Playing is true while the rack transport runs.

Every input of your graph besides the interface members, of type Float, Int32, Bool or Trigger, becomes a device parameter: a knob, a switch or a button on the card, and a name you can automate. Inputs of other types (arrays, audio, objects) stay internal (W3). Constructor inputs cannot change while the sound plays: changing one rebuilds the chain (W4), and they cannot be listed in the definition.

Inside a chain each parameter gets a unique name:

n is the lowest number the tag does not use yet in the rack when you add the effect. It stays when you move the effect; a copy gets a new one. Characters other than letters, digits and _ become _ (Filter Cutoff becomes Inst_Filter_Cutoff), and two pins that end up with the same name are an error (E11). These are the names Add MetaSound Automation lists for a printed chain.

Reserved names. Case does not matter. A pin, or an effect's short tag, must not produce:

• a name starting with Rack_, Chain_, Wave_, Thumpr_, SQLCH_, Inst_, DrumKing or GLTCH;
• Key or Delay followed by a digit (Key3_OnNote, Delay2Time);
• a name containing a . (the UE. and DAWntless. interface names);
• exactly Session.

A short tag has 1 to 10 letters and digits and ends in a letter, because the device number follows it: Chorus gives Chorus1, Chorus2, while Chorus2 would give Chorus21. Key, Delay, and tags starting with GLTCH or DrumKing are refused, because <Tag>1_ would be reserved. Instruments do not use the short tag: their parameters are always Inst_<Pin>.

The Device Validator creates DA_Device_<GraphName> next to the graph, with Create definition or on Register, and fills it from the graph: the display name, a suggested short tag, no category (the device is listed directly under User), and one parameter per pin with a guessed range. The range always includes the pin's graph default, so a new definition never changes the sound. Edit it in the validator's parameter table or in the asset's details panel.

Each entry of Params:

A pin you leave out of Params plays at its graph default and has no knob. [...] > Reset on the card returns every knob to its default.

Once a chain is printed into a Level Sequence, its MIDI track can automate your device from the track's MetaSound Automation lane, which you edit in Unreal's Curve Editor. The track's Add MetaSound Automation menu has one submenu per device of the chain, in chain order, and your device is one of them:

Tooltips read Chorus1 > Rate: 0.1 to 8 Hz; rests at 0.8. Triggers are never listed, and two entries with the same label are told apart by their group or pin.

• Kinds. A Float parameter gets a curve, an Int parameter a stepped channel that never interpolates, a Bool parameter an on/off channel. Each value reaches your graph in the pin's own type.
• Range. The channel keeps a copy of the entry's Min, Max and Units from the moment you add it, so a packaged game needs no definition to play it. Every value the lane sends is clamped into that range; keys keep what you typed. After you change the range in the definition, choose the checked entry again: it refreshes the copy and keeps the keys.
• Starting value. A new channel starts at the device's current value (the knob as it was printed, or the bypass state), and the menu keys that value at the playhead, so adding a channel changes nothing you hear.
• While playing, the lane wins. From Play to Stop (the Sequencer in the editor, the clock actor in PIE and packaged games) the automated value is the last value written to the input, even when the card or a preset re-applies the device's parameters. Values are sent at frame rate, not sample-accurately. When playback stops, or when you remove the channel (Remove MetaSound Automation), the input returns to the device's own value, the knob's.
• From the knob. Right-click a Float or Int knob of your device in TheRaK (only a parameter ticked Automatable: the others keep the card's menu): Automate in Sequencer adds the channel to the first printed track of the chain in the open Level Sequence, keys the knob's value at the playhead and opens the Curve Editor; Key current value only adds the key. Turning a knob never records.
• Scripts. unreal.DAWntlessDeviceLibrary list_automation_targets, add_automation_channel and add_automation_keys use the same targets.

An instrument can play its own patterns instead of taking notes from STPR-1, as Thumpr and SQLCH do. Make it self-sequenced in one of two ways:

• declare DAWntless.Transport without DAWntless.Instrument; or
• tick Has Built In Sequencer in the definition. The graph then needs DAWntless.Transport (E10).

TheRaK wires the rack transport to it. STPR-1 cannot attach to it, and the menu and the drag preview say so. Step your pattern from Beat and Playing: the instrument then follows the jam's tempo and launch point. Print skips it with "not printed: self-sequenced device", because it has no notes to write.

An instrument that declares both DAWntless.Instrument and DAWntless.Transport is an ordinary instrument that also knows the tempo.

1. In the Content Browser, create a MetaSound Patch, for example MSP_MySynth.
2. Open it and add the interfaces DAWntless.Instrument and UE.OutputFormat.Stereo. You can also skip this step and use the validator's Fix buttons in step 5.
3. Build the voice. A minimal one: connect MIDI (DAWntless.Instrument.MIDI) to a Harmonix MIDI Note Trigger. Connect its MIDI Note # to MIDI To Frequency and on to a Saw's Frequency, and its Note On to the Trigger of an AD Envelope (Audio). Multiply the saw by the envelope with Multiply (Audio).
4. Add a knob: create a Float input Cutoff with the default 2000, put a Ladder Filter after the multiply, connect Cutoff to its Cutoff Frequency, and connect the filter to Out Left and Out Right. Save.
5. Open Tools > DAWntless > Device Validator, or right-click the asset and choose Validate as DAWntless Device.... Select MSP_MySynth. The report lists every problem with its code; press Fix where one is offered, then save the graph.
6. Press Create definition. In the parameter table, give Cutoff the range 100 to 10000, the unit Hz and the curve Log. Set a display name and a category.
7. Press Audition and play the on-screen keyboard. Then press Run render test and read the results under the report.
8. Press Register and confirm the list of what is written. The definition is stamped and saved.
9. In TheRaK, choose + Add Device > INSTRUMENTS > User > <your category> > MySynth. Attach an STPR-1 from SEQUENCERS, press Play jam, and turn Cutoff on the card.

The stock MIDI Note Trigger is monophonic: it plays one note at a time, so a chord plays only its last note. For chords, build around a polyphonic node. The Pluck example does it in five nodes: a Harmonix Fusion Sampler Stereo fed by MIDI, playing a Fusion patch, followed by a low-pass and a gain.

1. Create a MetaSound Patch MSP_MyFilter and add DAWntless.Effect, UE.InputFormat.Stereo and UE.OutputFormat.Stereo, or add them later with Fix.

2. Put a One-Pole Low Pass Filter after In Left, and another after In Right. Create a Float input Cutoff (default 2000) and connect it to both filters' Cutoff Frequency.

3. Wire Bypass so that the effect passes its input through unchanged while the rack bypasses it. Use it as a switch between the filtered and the dry sound:

   • Connect Bypass (DAWntless.Effect.Bypass) to the second operand of a Subtract (Float), and type 1 in its first operand. The editor inserts a Bool-to-Float conversion node. The conversion outputs 1 while the effect is bypassed and 0 otherwise; the Subtract outputs the opposite.
   • Left side: multiply the filter's output by the Subtract's output with a Multiply (Audio by Float). Multiply In Left by the conversion's output with a second Multiply (Audio by Float). Connect both products to an Add (Audio), and its output to Out Left.
   • Do the same for the right side, into Out Right. Save.

   While Bypass is false, the output is exactly the filtered sound; while it is true, it is exactly the input. Without this step the effect still works in a rack, whose crossfade bypasses it cleanly, but the render test warns with R8.

4. In the Device Validator, select MSP_MyFilter, apply any Fix, and press Create definition. Set Short Tag to MyFilter, so the rack names the knob MyFilter1_Cutoff, and give Cutoff the range 200 to 20000 Hz with the curve Log.

5. Press Audition to hear a drum loop through the effect. Run render test plays an impulse, a 1 kHz tone and pink noise through it. With Bypass on, it checks that the effect returns its input.

6. Press Register. In TheRaK, select a card in a chain and choose + Add Device > EFFECTS > User > MyFilter, or User > <your category> > MyFilter if you gave it a category. Its (o) switch bypasses it through the rack's crossfade.

Open it from Tools > DAWntless > Device Validator, with the console command DAWntless.Devices, with Validate as DAWntless Device... on a MetaSound in the Content Browser, or with + Add Device > Manage user devices... in TheRaK.

+- DAWntless Device Validator -----------------------------------------------------------------------+
| [Search...] [x] Only assets declaring DAWntless interfaces   | MSP_MyFilter (Patch)                  |
| MSP_MyFilter     EFFECT  ok                                  | Role EFFECT  Format Patch  Stamp current |
| MSS_MyLead       INSTR   2 errors                            | [ok] DAWntless.Effect v1.0             |
| MSP_OldPad       ---     legacy contract                     | [!!] UE.OutputFormat.Stereo   [Fix]    |
|                                                              | Parameters: pin|label|min|max|default|unit|curve|group|hide|auto |
|                                                              | [Audition] [Run render test] [Register] |
+--------------------------------------------------------------+----------------------------------------+

• The list shows your MetaSound Patches and Sources and the definitions, without loading them. Untick Only assets declaring DAWntless interfaces to see every MetaSound.
• The report checks the selected graph as soon as you select it: one line per problem, with its code and, when one exists, a Fix button.
• Fixes edit your graph. The window asks first; each fix is one Undo step and never saves, so save the graph afterwards. With source control on, the graph is checked out first; if the check-out is refused, nothing changes.
• The parameter table edits the definition's Params in place. Each edit is one Undo step and reaches devices already playing in TheRaK. An edit that would make the definition invalid, for example a Min above Max or a Log curve with a Min of 0, is refused with the reason.
• Audition plays the device through the same chain a rack builds: a two-octave keyboard for instruments, a drum loop for effects. It stops when Play In Editor starts.
• Run render test runs the checks in Render checks.
• Register creates the definition if needed, validates, stamps and saves (next section).

Register validates the device: its structure, then the render test. Registration needs the render test, so it only works in an editor with audio (not under -nosound); save the graph first, because the stamp describes the graph on disk. Only when there is no error does it write the stamp into the definition, check the definition out (or mark a new one for add), save it, and add the device to Add Device. With errors, nothing is written.

The stamp records the validation rules' version, the graph (its path and class name), the graph's interface signature, a signature of the definition's parameters and sequencer settings, the result (Passed or Passed With Warnings), that the render test ran, the time, the engine version, and the render's CPU time and peak. It stays current while all of these hold: it passed after a completed render, the validation rules have not changed in a DAWntless update, the definition still names the same graph, the graph's interface signature is unchanged, and the definition's parameters and sequencer settings are unchanged. The signature covers every graph input (its name, type, access and default value), every output and the declared interfaces. Moving nodes or re-saving never changes it.

NEEDS VALIDATION means:

• The device leaves Add Device until you register it again.
• Devices already in racks keep playing, and their cards show an amber NEEDS VALIDATION header.
• Their chains hold the graph they play now: nothing rebuilds them with the unvalidated graph. Their strips show GRAPH OUT OF DATE with the reason ("validate <device> to rebuild"). Play still uses the current graph; [Rebuild], Save rack and Print refuse those chains until the device is registered again. Other chains are not affected.

To clear it, open the device in the Device Validator, check the report, and press Register. Then press [Rebuild] on each strip still marked GRAPH OUT OF DATE and save the rack.

A user device can also be:

A mistake that is only in the definition's metadata never silences a device: a range, a curve, value labels, a parameter listed twice, or the short tag. The device shows NEEDS VALIDATION with the reason ("Its definition has an error: …"), and its chain holds its graph as described above. A parameter whose entry cannot be used plays at its graph default, and its knob shows "graph default". Values outside a range play clamped into it.

The render test builds a real chain around the device, renders it offline at 48 kHz in 480-frame blocks and 120 BPM, and measures it.

• Instruments get 20 seconds of notes on track 1, channel 1: nothing until 2 s; MIDI 60 at velocity 100 at 2 s, held 0.5 s; a 16-note chord in whole tones from MIDI 48, velocity 127, at 3 s, held 1 s; 64 fast repeats of MIDI 60 (1/64 notes) from 4.5 s; the last note-off at 6.5 s. (The checks call MIDI 60 "C3", as Ableton does; STPR-1 labels it C4.) A definition in Drum sequencer mode is played on its pads instead: its first pad (Drum Root Note) for the response check and the parameter sweep, every pad at once in place of the chord, and a roll over the pads in place of the repeats. The report names the note it played.
• Effects get an impulse, a 1 kHz tone at −6 dBFS and pink noise, 4 seconds each, through the same bypass crossfade a rack uses, compared with a dry reference. The delay of the effect's output is reported as its latency.
• Every parameter in Params is set to its minimum, maximum and default for 0.25 s each, and measured from 20 ms after the change (a smoothed input still carries the previous value in its first block).
• The render runs twice; any difference is reported as information.
• A check that cannot be measured is listed as "not measured", with the reason, and its level is null in the JSON. For example, the hanging-note check needs 10 s after the last note-off.
• The report records the note the instrument checks played (respondNote in the JSON): MIDI 60, or Drum Root Note in Drum mode.

The render needs an editor that can play audio. Without one (for example with -nosound), the report says "render skipped (no audio)" as information, and the structural checks still run. A graph that reads an Audio Bus cannot be rendered offline and is refused (R10).

Errors stop registration; warnings do not.

The examples are registered, and Add Device lists them under INSTRUMENTS > User > Examples and EFFECTS > User > Examples. Duplicate an example to start your own device; the copy needs its own definition and registration.

Perforce and other source control:

• Fix checks out your graph and leaves it unsaved: save it.
• Register checks out the definition, or marks a new one for add, and saves it. It never saves the graph.
• Duplicate as Patch... saves the new patch and marks it for add. The Source is not touched.
• Submit together: the graph, its DA_Device_ definition, the racks and Level Sequences that use the device, and the new MSS_Chain_ graphs (see Generated chain graphs and Perforce).
• The stamp lives in the definition. When a teammate changes a graph's inputs, everyone sees NEEDS VALIDATION until someone registers the device again and submits the definition. Register after you sync a graph change.
• Chain graphs your experiments no longer use can be removed with TheRaK's [...] > Clean up unused chain graphs.... It keeps every graph that an asset on disk refers to, hard or soft, or that an open rack holds, and deletes the rest only after you confirm its report (see Clean up unused chain graphs). It never touches your device graphs or definitions.

Cooking. A rack's device references its definition, the definition references the graph, and every saved chain graph embeds the device graph, so cooking a level or sequence that uses the rack or its printed tracks cooks all of it, including assets the graph references, such as a Fusion patch. That includes a level whose TheRaK Performer component plays the rack (see TheRaK Performer (gameplay)). A packaged game neither looks for devices nor builds chains: it plays the chain graphs saved with your racks and printed tracks. A definition that no rack uses is not cooked, and is not needed there.

CI. The DAWntlessValidateDevices commandlet runs the same checks as the window and writes nothing to your assets:

UnrealEditor-Cmd.exe YourProject.uproject -run=DAWntlessValidateDevices -Paths=/Game/Devices,/DAWntless/Examples/UserDevices
    -Render -AllowCommandletAudio -Report=Saved/DeviceValidation.json -unattended -SCCProvider=None

• -Paths (required): content folders, searched with their subfolders, or single assets, separated by , or ;. Every MetaSound there that declares a DAWntless interface, and every definition, is checked.
• -Render: run the render checks too. It needs -AllowCommandletAudio (a commandlet has no audio without it), no -nosound, and a Development editor build. Otherwise each device reports "render skipped".
• -Report: where to write the JSON report (folders are created). Without it, results go to the log only.
• Each definition gets one entry, validated with its graph; a DAWntless graph gets its own entry only when no definition in the paths covers it (then with its definition from elsewhere, if it has one). An asset that does not load is an entry with an error.
• Exit code: 0 no device has errors, 1 at least one device has errors, 2 bad arguments (for example no -Paths), 3 the report could not be written, 4 -Render was asked for but the process cannot render (add -AllowCommandletAudio, drop -nosound). The last log line starts with DAWNTLESS_VALIDATE_DEVICES and carries the summary.

Validate Assets (Unreal's Data Validation, including its commandlet) also checks every MetaSound that declares a DAWntless interface, structurally only.

Python. unreal.DAWntlessDeviceLibrary scripts the same workflow: validate_device(graph, render), fix_device(graph, fix_name), create_definition(graph) and register_device(definition, render) (it needs render true and an editor with audio). The fix names are SetReferenceable, AddInstrumentInterface, AddEffectInterface, AddOutputFormatStereo, AddInputFormatStereo, DuplicateAsPatch and UpdateInterfaceVersion. Registration from Python follows the same rules as the window: it stamps only a device without errors. Following Unreal's Python convention for functions that return a bool, validate_device and register_device return (report_json, error) on success and None on failure, and fix_device returns (error, created_asset_path) on success (the new patch's path for DuplicateAsPatch) and None on failure; the reason, with the report, is then in the Output Log (a DAWntlessLog warning). create_definition returns (definition, error).

measure_fundamental_hz(graph, note) renders one note of an instrument: velocity 100, held for 1 s. It returns (hz, error). hz is the note's fundamental frequency, measured over the steady part of the note, or 0 when the graph cannot render or has no clear pitch; error then gives the reason. Use it to check the tuning of a sampler patch or of a drum pad. It needs an editor with audio, like the render test.

• Sources are instruments only (E6); effects must be Patches.
• Stereo at most (E9).
• Parameters are Float, Int32, Bool or Trigger inputs; constructor inputs rebuild the chain when they change. Automation lanes carry Float, Int and Bool channels (no Trigger) and send them at frame rate.
• Polyphony is up to your graph. The stock MIDI Note Trigger is monophonic and stock MetaSound nodes have no voice allocator. For chords use a polyphonic node: the Harmonix Fusion Sampler, as the Pluck example does, or a native MetaSound node, as Afterglow uses.
• One instrument per chain, and user effects go in chains only: master effects arrive in a later update.
• Self-sequenced instruments are not printed.
• Audio Bus readers cannot be devices (R10).
• Tempo comes as numbers (DAWntless.Transport). A Harmonix MIDI clock member is planned for a later interface version.
• Unreal Engine 5.8. The validation rules target 5.8's MetaSound formats; a DAWntless update that changes them asks for re-validation (NEEDS VALIDATION).