Modbits¶

The VMC is the container. Modbits are what goes inside it. A modbit is the atomic unit of modulation in IVLS: one value, applied to one parameter, propagated to all sound events registered on the VMC.

If you want to fade a voice's volume, you create a modbit. If you want to detune a voice in real time, you create a modbit. If you want to pan a voice dynamically, you create a modbit. Each modbit is a single, independent modulation source.

Two Types of Modbits¶

Modbits come in two flavors:

ADD modbits add to the base value. An ADD modbit on VOLUME with a value of -3000 reduces the volume by 3000 units.

MULT modbits multiply the base value. A MULT modbit on VOLUME with a value of 5000 scales the volume to 50%. The scale uses 10000 as the unity value (100%), so 10000 means no change, 5000 means 50%, and 0 means silence.

Multiple modbits can affect the same parameter simultaneously. All ADD modbits are summed, and all MULT modbits are multiplied together. The final result is applied to the sound event.

Built-In Parameters¶

IVLS provides three built-in modulation parameters:

ivls.mod_par.VOLUME -- controls sound event volume
ivls.mod_par.PAN -- controls sound event panning
ivls.mod_par.TUNE -- controls sound event tuning

You can define custom script modulation parameters beyond these three, but that's an advanced topic covered in the module documentation.

Creating a Modbit¶

Modbit.local() creates a new modbit:

declare mb := Modbit.local(ivls.mod_par.VOLUME, ivls.mod_type.MULT)

This creates a MULT modbit targeting VOLUME. Its initial value is 10000 (100% -- no change) for MULT types, or 0 (no offset) for ADD types.

The "local" in Modbit.local() means the modbit is non-static -- it can be created and destroyed dynamically. There's also Modbit.static() for modbits that persist for the lifetime of the instrument, but Modbit.local() is what you'll use for fades and dynamic modulation.

Attaching a Modbit to a Voice¶

A modbit doesn't do anything until it's attached to a voice. Modbit.add_to_voice() links the modbit to the voice's VMC:

Modbit.add_to_voice(mb, target_vo)

After this call, the modbit is registered on target_vo's VMC. Any changes to the modbit's value will be propagated to all sound events on that VMC -- including events from child VMCs in the tree.

Remember: the modbit lives on the VMC, not on the voice. If the voice is deleted but the VMC persists (because a modulation voice still references it), the modbit keeps working.

Setting a Modbit's Value¶

Modbit.set() changes the modbit's value and immediately propagates the change:

Modbit.set(mb, 5000)    { 50% volume for a MULT modbit }

When you call Modbit.set(), the framework updates every sound event registered on the modbit's VMCs. This is how fades work -- a loop that calls Modbit.set() repeatedly with decreasing values, creating a smooth volume ramp.

A Simple Volume Duck¶

Here's a minimal example: duck a voice's volume to 50% for one second, then restore it:

node MyVolumeDuck:
    cb NoteOn:
        declare mb := Modbit.local(ivls.mod_par.VOLUME, ivls.mod_type.MULT)
        Modbit.add_to_voice(mb, self)

        { Duck to 50% }
        Modbit.set(mb, 5000)

        ivls.wait_ms(1000)

        { Restore to full }
        Modbit.set(mb, 10000)
end node

The modbit starts at 10000 (100%), gets set to 5000 (50%), waits a second, then goes back to 10000. Throughout this time, the modbit is affecting the sound event through the VMC -- even if other things happen to the voice tree in the meantime.

Why Modbits Instead of Direct Volume Control¶

You might wonder why you'd use a modbit instead of just calling change_vol() directly. There are two reasons:

Multiple modbits stack. A fade-out modbit and a volume-duck modbit can both target the same voice's VOLUME parameter simultaneously, and the framework correctly combines them. With direct calls, the second change_vol() would overwrite the first.
Modbits survive voice deletion. Because they live on the VMC, modbits can keep adjusting a sound event even after the voice that created them is gone. This is essential for fades that run asynchronously.

Modbits are deliberately simple -- one value, one parameter, one operation. Their power comes from composition: multiple modbits stacking on the same VMC, each controlled by a different part of your instrument's logic. The next page covers fades, which are the most common and practical use of modbits.