Status: This specification is in drafting. Please feel free to edit this page and add your comments.

DJs often augment their mixes with effects. Mixxx is severely lacking in this department, as released versions of Mixxx only offer EQs and a flanger.

This project aims to bring effects to Mixxx, both via native effects and effects plugins via LADSPA, LV2, or VST.

The goal is that the DJ can enhance their performance through the use of audio effects. To present this in a simple-to-use and powerful way, we introduce the metaphor of “Effect Chains”. An effect chain is nothing more than a list of effects which are applied sequentially to audio. An effect chain can be applied to decks, samplers, the headphone out, and the master output.

The DJ configures effect chains by selecting effects that are available to her from any variety of effect sources (native built-in plugins, LADSPA plugins, LV2 plugins, VST plugins, etc.) and adding them to the chain. She does this from a view called “Effect Chain Edit Mode” that takes the place of where the Mixxx library normally sits.

Once the DJ has selected the effects that she desires to be in the chain, then the parameters of that effect are made available to her to tweak to her liking. Each parameter can be adjusted in the following ways:

• Change the value of the parameter
• Change the minimum / maximum limits of the parameter
• Invert the knob so that turning it clockwise goes from high to low instead of low to high.
• In the case of a knob, change whether the parameter is controlled linearly or logarithmically
• Assign the parameter to be controlled by the effect chain's “Wonder Knob”. See the “Wonder Knob” section below.

Once the DJ is done configuring the effect chain and the parameters of the effects that are in the effect chain, she may save the effect chain and give it a name. Alternatively, she can also load a previously saved chain from the Chain Edit Mode.

The key idea here is that the DJ should invest time in crafting and creating the unique sounds she would like to make via Effect Chains prior to her sets. While it will be possible to create Effect Chains on the fly, it will be a lot less stressful if she has invested the time beforehand.

TODO: Insert marketing name here :) Candidates: SuperKnob, WonderKnob, MetaKnob, HyperKnob, AwesomeKnob, FunkyKnob, MagicKnob

Every effect chain has a single knob called the “Wonder Knob”. This knob is meant to be the go-to knob for the DJ to tweak during her set to make awesome effect noises happen. If you look at a lot of Ean Golden's videos on DJTechTools, this is how many of his combinations of effects work. There is one knob to turn that produces the desired effect. This is both a huge usability win (no knob soup) and allows the DJ to focus on what she is doing. As previously outlined, when creating an effect chain in Chain Edit Mode, the DJ can link one or more of each effect's parameters to the chain's “Wonder Knob”. This, combined with with the ability to tweak the min/max ranges, and the linear/log settings of the knobs, allows the DJ to create one knob that does the work of what she would normally do by tweaking multiple knobs simultaneously.

One benefit of having a “Wonder Knob” is that it maps very naturally to many MIDI controllers, which often have a limited number of knobs available for tweaking effets. One example of this is the Numark V7/NS7, which only has a single effect-selector knob and an effect-parameter knob. In this case, we would make the effect selector knob select the active effect chain, and the effect-parameter knob tweak the “Wonder Knob”. In ITCH, the V7/NS6/NS7FX are limited to only a single effect at a time, and these knobs are designed to reflect that. By mapping this knob to effect chains, we will allow NS7/V7 owners to achieve a categorically more flexible effect setup.

• A general EffectManifest interface which allows each effect to express:
  • The effect name (internationalizable)
  • A description of the effect (internationalizable)
  • The parameters each effect has, including:
    • An internal identifier
    • A human-readable name (internationalizable)
    • A prose description, with support for internationalization, suitable for display in a tooltip. (internationalizable)
    • Units and maximum/minimum/default values of the parameter
  • A preferred ordering of parameters in order of importance
• Backend
  • Support for multiple backends (plugin based or not)
  • A reference implementation of a Mixxx-internal effects backend
    • Support for at least a flanger
• Effect Instances (known as “Effect”)
  • Support the customization of parameter ranges to a subset of the EffectManifest's min/max ranges
  • Support linking of individual parameters to the Effect Chain's meta-knob.
  • TODO: Each effect shall have an individual wet/dry parameter?
• Effect Chains
  • Support chaining multiple Effects together into an Effect Chain.
  • TODO: Each effect chain shall have a wet/dry parameter? Or an enabled button?
  • Each effect chain will have one “Meta/Super/Wonder/Master/Action/Crazy/Funky-Knob” which individual parameters of effects in the chain can be linked to.
  • Must support loading and saving of effect-chains (“Presets”)
  • Support applying effect chains to multiple different audio sources (samplers, decks, master out, headphone out)
• Control (MIDI, etc) Interface
  • MIDI scripts must be able to control loaded effects parameters
  • MIDI scripts must be able to request that an effect be ejected or a next/previous effect be loaded. (support effect knobs on e.g. NS7)
  • MIDI scripts must be able to observe effect chains and make changes.
  • MIDI scripts must have a simple-mode by which they can treat parameters as 0.0 - 1.0 values so they do not have to deal with the complexity of min/max values, types, etc.
• GUI Widgets
  • EffectChain widget
    • Show selected EffectChain name
    • Parameter Knob
    • Channel Select buttons
  • EffectChain Editor Library section
    • See existing chain presets
    • Create new preset
    • Add/remove effect to existing chain
    • Change value of parameter of effect in slot
    • Right-click hover overlay for tweaking ranges, defaults.

The properties of an effect are described by an EffectManifest object. An EffectManifest is an immutable data type (should always be const) that fully describes all of the effect's properties that are relevant to user-facing aspects of effects. This includes a description of each user-facing parameter of each effect, along with metadata describing hints for how the parameter should be presented to the user, limits of the parameter's values, and default values for the parameter. An EffectManifest is strictly an abstract description of the effect, and has nothing to do with an actual instantiation of an effect. An Effect object is an instantiation of an EffectManifest, and manages actual instance values for each parameter described in the EffectManifest.

NOTE: The hints are still under development. Please give feedback!

The effects system will implement a backend model similar to Mixxx's MIDI backend. Multiple backends will provide Effects that are aggregated by an EffectsManager class. Each backend will provide effects either loaded from a plugin system such as LADSPA, LV2, or VST. Alternatively, a backend can implement effects natively and expose them via the same Effect interface used by the plugin-based backends.

Given an Effect instance, a buffer of audio can be processed given the parameter settings in the instance.

The EffectsManager uses the EffectsBackends to instantiate Effects from EffectManifests. Once the EffectsManager instantiates an Effect, it is able to ask the Effect to process a buffer of audio.

An EffectSlot is an abstraction over an Effect. It provides a ControlObject interface for controlling the parameters of an Effect. To a user, an EffectSlot is the equivalent of a “selected” effect. Knobs in the GUI and MIDI controllers connect to the EffectSlot's controls, which in turn are used to control the Effect that is loaded into the slot. Similarly, an EffectChainSlot is an abstraction over an EffectChain. It provides a ControlObject interface to controlling an EffectChain that is loaded into it. To a user, an EffectChainSlot is an “effect unit” which is a chain of EffectSlots.

One or more EffectSlots are grouped into an EffectChainSlot. The EngineMaster and EngineChannels interact with the effects framework at the level of EffectChains. Every EffectChain is conditionally applied to multiple EngineChannel's (e.g. [Channel1], [Channel2], [Sampler1], etc). In addition to EngineChannels, EffectChains are conditionally applied to both the EngineMaster master output ([Master]) and the headphone output ([Headphone]).

The EffectsManager class provides the following global information controls:

EffectChains and EffectSlots both provide a ControlObject interface for both the GUI and MIDI controllers to interact with. At creation time, all EffectChains are assigned a sequential, unique ID starting at 1. All EffectChains have the group [EffectChainN] where N is the EffectChain's ID.

In the above table,

• N ranges from 1 to [Effects],num_effectchains, inclusive.
• M ranges from 1 to [EffectChainN],num_effectslots, inclusive. (For a given value of N)
• K ranges from 1 to [EffectChainN_EffectM],num_parameters, inclusive. (For given values of N and M)
• I ranges from 1 to [Master],num_decks, inclusive.
• J ranges from 1 to [Master],num_samplers, inclusive.

NOTE: The reason for 1-indexing versus 0-indexing is the significant precedent within the Control system for 1-indexing. (e.g. hotcues, Deck/Sampler names, etc.)

Since the Control system is not capable of representing values other than numeric values, for the first iteration of the effects system, we must use a numeric coding system for representing the parameter types. If the GUI or MIDI Script author does not care about choosing correct values, he or she can use the parameterK_value_normalized control, which will always represent the parameter value as normalized to the range of 0.0 to 1.0. To use the parameterK_value control, the setter must check the value against parameterK_type (see the Parameter Types table below), parameterK_value_min, and parameterK_value_max to ensure the value is within the correct range. Invalid settings of any parameterK_value controls will be ignored.

Brainstorming for now. Basing heavily off of Jus's mockups from Summer 2010: Effects Units Mockup Effects Units Editor Mockup

Mockup of Effect-Chain Compact Interface. Only MetaKnobs are showing.

TODO: Need to formalize what “Fit” means. In general, a fit is good if it matches the paradigm of effect-chains being

• Selectable (usually with an FX select knob or button)
• Controllable via 1 single parameter (usually a knob)
• Allow selection of Decks that an effect-chain applies to either directly in the effects section or in the mixer section.
• Optionally, enable via on/off button
• Optionally, a wet/dry effect mix knob

1. Implement effect representation
   1. EffectManifest and its properties
      1. EffectManifestParameter and its properties
   2. Effect
2. Implement backend framework classes
   1. EffectsBackend Interface
      1. Enumeration of EffectManifests
      2. Instantiation of Effects
   2. Native Backend
      1. Add backend to EffectsManager
      2. Implement a bunch of cool effects
         1. Port Flanger from EngineFlanger to NativeBackend
         2. Delay / Tape Echo
         3. Stutter
         4. Backspin
         5. HPF / LPF
         6. Bitcrusher
         7. Gater
3. Implement control layer
   1. EffectChain
      1. Control Interface
      2. EffectSlot lifecycle
      3. Effect loading/unloading logic
      4. Parameter sync between controls and loaded effect
      5. Units tests for consistency of controls / state
   2. EffectSlot
      1. Control Interface
      2. EffectSlotParameter lifecycle
      3. Parameter sync between controls and loaded effect
      4. Units tests for consistency of controls / state
   3. EffectSlotParameter
      1. Control Interface
      2. Effect loading/unloading logic
      3. Parameter sync between controls and loaded effect
      4. Units tests for consistency of controls / state
4. Implement overall effect management layer
   1. EffectsManager
      1. Adding, management of lifecycle of EffectsBackends
      2. Adding, management of lifecycle of EffectChains
      3. Check that EffectManifest/EffectManifestParameter, Effect/EffectParameter, EffectChain/EffectSlot/EffectSlotParameter all get deleted
   2. Preset Management
      1. Implement loading/saving of EffectChain presets
      2. Implement next/prev logic for EffectChains
5. Implement EffectChain parameter linking
   1. EffectSlotParameter's can be linked to the EffectChain's parameter
   2. Propagate changes in the EffectChain's parameter to EffectSlotParameters that are connected to it
6. Implement actual audio processing
   1. EffectChain → EffectSlot processing
   2. EffectSlot → Effect processing
   3. EffectChain processing for given channels can be enabled and disabled
   4. Engine/EngineChannel requests effect-chains enabled for a given channel as it processes them
   5. Engine/EngineChannel applies appropriate effect chains to buffers of audio that are enabled
7. GUI Widgets
   1. EffectChain name widget
      1. Shows the name of the EffectChain that is loaded into EffectChainSlot X
   2. EffectChain Editor Library section
      1. See existing chain presets
      2. Create new preset
      3. Add/remove effect to existing chain
      4. Change value of parameter of effect in slot
      5. Right-click hover overlay for tweaking ranges, defaults.

This feature has been attempted twice by two GSoC students. There is a lot of old code lying around, and we will try to reuse whenever possible. The current branch for work on this feature is the lp:~mixxxdevelopers/mixxx/features_effects branch.

• RJ Ryan