Resources

Driving dew

dew://guide/index

dew is a desktop DAW in the FL Studio shape. A project holds CHANNELS, each carrying one instrument - a three-oscillator synth, a recording, or a soundfont - and its own chain of effects. PATTERNS hold notes. The PLAYLIST arranges clips of those patterns into a song. A MIXER routes channels through inserts to a master.

Start with project_describe. It returns the tempo, the metre, and every channel, pattern, lane, insert and automation by name and id, with not one note in it. Everything else is addressed by the ids it gives you.

Then: params_list and params_write reach every value in the document - a volume, an oscillator's detune, an envelope, any effect's anything, a fader, the tempo. channels_write, effects_write and mixer_write add and arrange the objects those values live on. notes_write and clips_write are the piano roll and the arrangement. score_compile is the fast way to write a lot of music at once.

Read dew://guide/addressing before writing anything, and dew://guide/undo before writing a lot of it.

How things are addressed

dew://guide/addressing

Channels, patterns, mixer inserts and automations carry IDS, and an id is stable for as long as the thing exists. Playlist lanes do not: lanes are positional, so a lane is addressed by its index, and removing one renumbers the lanes after it. Clips are addressed by the lane and the bar they sit on, which is how they are identified on screen.

Every parameter in the project is addressed by the same five fields. target is project, channel, mixerTrack or master. id is the channel or mixer track id. group says which part of the thing: leave it empty for the target's own parameters, or give oscillators, amp, sample, soundfont or effects. slot picks which oscillator or which effect. param is the parameter's name.

What a channel offers depends on what instrument it carries, which project_describe reports as its source: a synth has oscillators and an amp envelope, an audio channel has a sample, a soundfont channel has a soundfont. Call params_list at an address to see exactly what is there, with each parameter's range, its default and whether it can be automated.

automation_targets_list answers in the same five fields, so a parameter you have just set can be automated without translating anything. Not every parameter can be: whether one is worth a curve is declared beside the parameter itself.

Notes, patterns and the arrangement

dew://guide/arrangement

Time inside a pattern is whole STEPS. A step is one over stepsPerBeat of a beat - at the default of 4, a step is a sixteenth note. There is no fractional step, so a rhythm the grid does not divide cannot be written. stepsPerBeat is the project's own grid and no operation here changes it: project_describe reports it, and a score compiled into an empty project is the one thing that sets it.

A PATTERN holds every channel's notes for its span. It is a section of the song rather than one instrument's part, which is the thing most likely to surprise you: a drum pattern and a bass pattern covering the same four bars are usually one pattern, not two.

The PLAYLIST is measured in BARS, and a bar is stepsPerBeat * beatsPerBar steps - 16 in a default 4/4 project, not 4. Placing two clips of one pattern is how a section repeats identically. Duplicating the pattern first, with patterns_write and duplicateOf, is how it repeats with variation. A lane can carry a clip of any pattern; lanes are not instruments either.

Changing the metre redefines what a bar IS, so the bar lines move - and nothing you have written moves with them. Notes and clips are stored in STEPS, so every one of them stays exactly where it sounded; what moves is the song's length in bars, which is rounded up to cover what was there.

A pattern's LENGTH follows its notes, in both directions: writing a note further in lengthens it, and removing the notes at the end shortens it again. The SONG only grows - trailing empty bars are a deliberate silence, and nothing trims those behind your back.

The score language

dew://guide/score

dew carries a declarative language for arrangement. You say what the music IS - a key, a harmonic progression, rhythms, voicings, a counterpoint - and the compiler works out the notes, the patterns and the clips. For anything longer than a few bars this is worth far more per call than placing notes one at a time.

score_write stores the text and compiles nothing; score_compile turns it into real notes as one undo step. They are separate because a compile writes notes, and text being worked on should not fill the undo stack with them. Both report diagnostics with a code, a line and a column.

The language owns notes, patterns and clips. You own channels, instruments, effects and the mixer - so set up the sounds with the other tools, and let the score put the music on them. Recompiling is an update rather than a second copy, and edits made by hand are kept unless you ask for them to be discarded.

Three things it cannot say, because the host cannot hold them: time is whole steps, so a rhythm needing a finer grid than the project has is an error naming both offenders; there is one tempo and one metre for the whole project, so a section in another metre is not expressible; and a pattern holds every channel's notes for its span.

The same source always compiles to the same notes, on any machine. The full reference is on the website.

Changes, undo and consent

dew://guide/undo

Every operation that writes is exactly ONE undo step, however many entries its batch carried. Two hundred notes in one notes_write call is one press of Cmd-Z. The user approved a client, not each of its actions, so an action they can take back whole is what the approval rests on.

Prefer one batched call over many small ones for the same reason, and not only for speed. Ten separate calls are ten undo steps and ten chances to leave the document half-changed.

A batch is checked before any of it is written. An entry naming a channel that does not exist fails the whole call and changes nothing, rather than applying the entries it understood: a half-applied batch tells the caller it failed and moves the document anyway.

A grant is read-only or read-and-write, chosen by the user when they approved the client. Under a read-only grant every writing operation is refused before it runs. project_command can undo and redo, so a client can take back its own work - and so can the person at the keyboard.

Nothing here can approve itself or change a grant. What a write grant DOES reach outside the open project is worth knowing before you give one: render_audio and export_midi write the file they are asked for, project_command saves to a path you give it and opens one, and source_write reads a sample or a soundfont from anywhere on disk. Every one of those takes the path from the caller.