Merge pull request #64 from Be-ing/effects_chapter

Effects chapter

Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = sphinx-build-3
 #SPHINXBUILD   = sphinx-build-2.7    #For OSX if sphinx has been installed via MacPorts
 
 PAPER         =

source/chapters/djing_with_mixxx.rst

@@ -178,152 +178,6 @@ detect the key of a track and will display it in the library and the decks. The
 notation which is used to display a key can be changed in :ref:`Key Detection
 Preferences <configuration-key-detection>`.
 
-.. _djing-with-effects:
-
-Using Effects
-=============
-
-.. versionadded:: 2.0
-
-Mixxx comes with a set of native effects.
-
-.. _effects-flanger:
-
-Flanger
--------
-
-..
-   .. figure:: ../_static/Mixxx-111-Deere-Mixer-FX.png
-      :align: center
-      :width: 321px
-      :figwidth: 100%
-      :alt: The effect control section of the mixer
-      :figclass: pretty-figures
-
-      Flanger controls
-
-The Flanger is simple modulation effect, created by taking the input signal and
-mixing it with a delayed, pitch modulated copy of itself.
-
-**Depth**
-  Controls the intensity of the effect.
-
-**Delay**
-  Sets the value for the delay length.
-
-**Period**
-  Controls the speed of the effect.
-
-.. _effects-bitcrusher:
-
-BitCrusher
-----------
-
-..
-   .. figure:: ../_static/Mixxx-112-LateNight-Effects-BitCrusher.png
-      :align: center
-      :width: 321px
-      :figwidth: 100%
-      :alt: The effect control section of the mixer
-      :figclass: pretty-figures
-
-      BitCrusher controls
-
-The BitCrusher is an effect that adds quantization noise to the signal
-by the reduction of the resolution or bandwidth of the samples.
-
-**Bit Depth**
-  Adjusts the bit depth of the samples.
-
-**Downsampling**
-  Adjusts the sample rate to which the signal is downsampled.
-
-.. _effects-filter:
-
-Filter
-------
-
-..
-   .. figure:: ../_static/Mixxx-112-LateNight-Effects-Filter.png
-      :align: center
-      :width: 321px
-      :figwidth: 100%
-      :alt: The effect control section of the mixer
-      :figclass: pretty-figures
-
-      Filter controls
-
-The filter changes the tone of the music by allowing only high or low
-frequencies to pass through.
-
-**LPF**
-  Corner frequency ratio of the low pass filter.
-
-**Q**
-  Resonance of the filters, default = Flat top.
-
-**HPF**
-  Corner frequency ratio of the high pass filter.
-
-.. _effects-reverb:
-
-Reverb
-------
-..
-   .. figure:: ../_static/Mixxx-112-LateNight-Effects-Reverb.png
-      :align: center
-      :width: 321px
-      :figwidth: 100%
-      :alt: The effect control section of the mixer
-      :figclass: pretty-figures
-
-      Reverb controls
-
-
-This is a port of the GPL'ed CAPS Reverb plugin, which has the following
-description: This is based on some of the famous Stanford CCRMA reverbs (NRev,
-KipRev) all based on the Chowning/Moorer/Schroeder reverberators, which use
-networks of simple allpass and comb delay filters.
-
-**Bandwidth**
-  Higher bandwidth values cause more bright (high-frequency) tones to be
-  included.
-
-**Damping**
-  Higher damping values cause reverberations to die out more quickly.
-
-.. note:: This effect is not available in the Mac App Store version of Mixxx.
-
-.. _effects-echo:
-
-Echo
-----
-
-..
-   .. figure:: ../_static/Mixxx-112-LateNight-Effects-Echo.png
-      :align: center
-      :width: 321px
-      :figwidth: 100%
-      :alt: The effect control section of the mixer
-      :figclass: pretty-figures
-
-      Echo controls
-
-Simple Echo with pingpong
-
-**Send**
-  How much of the signal to send into the delay buffer.
-
-**Delay**
-  Delay time in seconds.
-
-**Feedback**
-  Amount the echo fades each time it loops.
-
-**PingPong**
-  As the ping-pong amount increases, increasing amounts of the echoed signal is
-  bounced between the left and right speakers.
-
 .. _djing-recording-your-mix:
 
 Recording Your Mix

source/chapters/effects.rst

@@ -0,0 +1,125 @@
+.. _effects:
+
+Effects
+*******
+
+Mixxx has a powerful sound effects system. Understanding how it works can open
+you up to a wide variety of mixing techniques.
+
+.. _effects-effect-unit:
+
+Effect Units
+============
+Mixxx has 4 effect units. By default, only 2 of them are shown. The other 2
+effect units can be shown by toggling the setting in the skin settings menu.
+
+.. figure:: ../_static/effect-unit-collapsed.png
+   :align: center
+   :alt: An effect unit
+   :figclass: pretty-figures
+
+   An effect unit
+
+Each effect unit can load up to 3 effects in a chain. These effects are
+processed one after the other in series. You will hear different sounds
+depending on the order of effects within the chain. Each effect in the chain
+has its own button to toggle it on and off.
+
+Effect units can process sound from:
+  * decks
+  * microphones
+  * auxiliary inputs
+  * the master mix
+  * the :term:`PFL` (headphone) mix
+  * left/middle/right crossfader buses
+
+The buttons to route effect units to decks, microphones, and auxiliary inputs
+are located in the deck, microphone, and auxiliary sections of the skin. The
+buttons for routing other inputs to effect units are in different locations
+depending on the skin.
+
+If a channel is assigned to multiple effect units, those effect units are
+chained together. This allows you to chain more than 3 effects at a time.
+
+The mix knob adjusts the mix between the dry signal (input to the unit) and the
+wet signal (output of the last effect in the unit). It changes the level of
+all 3 effects in the unit together. When the knob is fully left, no sound will
+be heard from the effect unit. When the knob is fully right, only the output of
+the effect unit will be heard without any of the dry input signal.
+
+Effects are processed after the deck faders and crossfader. This allows effects
+like Echo and Reverb to continue outputting sound after their input has been
+cut off by lowering the fader. Unlike other DJ software and hardware, effects
+can also be heard in headphones even though they are processed after the faders
+for the master output. Refer to the :ref:`effects-in-headphones` section below
+for details.
+
+Note that equalizer and filter effects create a phase shift. If the mix knob is
+anywhere in the middle between dry and wet and any of these effects are enabled
+in the unit, there will be comb filtering which is probably not desired. For
+more background information, read `Equalizers and Phase Shift
+<http://ethanwiner.com/EQPhase.html>`_.
+
+Effect Parameters & Metaknobs
+=============================
+Every effect within an :ref:`Effect Unit <effects-effect-unit>` has its own set
+of parameters. By default, these are hidden. Instead, there is a single knob
+called a "metaknob" for each effect which is linked to the different
+parameters. The metaknob allows you to easily control the effects in a unit
+without having to manipulate every parameter individually.
+
+If you want more detailed control of effects, press the expansion button on the
+effect unit to reveal the effect parameters:
+
+.. figure:: ../_static/effect-unit-expanded.png
+   :align: center
+   :alt: An effect unit with parameters showing
+   :figclass: pretty-figures
+
+   An effect unit with parameters showing
+
+You can customize how the metaknob is linked to the parameters by clicking the
+buttons below the parameter knobs. The button under the parameter name
+controls the metaknob link mode:
+
+  * Inactive: parameter not linked
+  * Active: parameter moves with metaknob
+  * Left side active: parameter moves with left half of metaknob turn
+  * Right side active: parameter moves with right half of metaknob turn
+  * Left and right side active: parameter moves across range with half of
+    metaknob turn and back with the other half
+
+The button below the metaknob link button inverts the parameter's relationship
+to the metaknob.
+
+For information about specific effects and their parameters, hover your mouse
+over them to show the tooltip. If you do not see tooltips, check that you have
+them enabled for the skin in :menuselection:`Preferences --> Interface`.
+
+Effects (except for Reverb) that have a length of time as a parameter are
+synchronized to the tempo of decks.
+
+.. _effects-in-headphones:
+
+Effects In Headphones
+=====================
+To preview how a track will sound with effects before you mix in the track,
+simply assign the deck to an effect unit and enable the headphone button for
+the deck. Note that this will increase CPU compared to assigning an effect
+unit to a deck without the headphone button enabled. This is because effects
+are processed in parallel for the headphone output (prefader) and master output
+(postfader).
+
+Effects can also be previewed in headphones on decks that are playing to the
+audience, but this requires a few more steps:
+
+  #. Disable the effect unit for the deck
+  #. Enable the headphone button for the deck
+  #. Enable the headphone button for the effect unit
+  #. Enable effects and adjust their metaknobs and parameters for how you want
+     the effects to sound.
+  #. When you are ready to mix in the effect, turn the mix knob fully left (dry)
+  #. Enable the effect unit for the deck
+  #. Turn the mix knob right so the effects are heard in the master output
+  #. Disable the headphone button for the effect unit so you do not forget to
+     turn it off later

source/chapters/example_setups.rst

@@ -1,4 +1,4 @@
-.. _setup::
+.. _setup:
 
 Example Setups
 **************

source/chapters/user_interface.rst

@@ -1057,55 +1057,21 @@ Sample Deck Controls
 
 The Effects Section
 ===================
-
-.. versionadded:: 2.0
-
-..
-   .. figure:: ../_static/Mixxx-112-LateNight-Effects-Deck.png
+   .. figure:: ../_static/effect-unit-collapsed.png
       :align: center
-      :width: 304px
       :figwidth: 100%
-      :alt: A sample deck
+      :alt: An effect unit
       :figclass: pretty-figures
 
-      A Effect Chain
-
-Effect chains allow you to apply various effects to your mix. You can either add
-the effects to the master-output or individually for each deck.
+      An effect unit
 
-The Effects section is **hidden** in the default :ref:`Mixxx user interface
-<interface-overview>` to save room on small screens. Click the :ref:`EFFECTS
-<interface-expansion-buttons>` button in the mixer section, or use the specific
-:ref:`appendix-shortcuts` to show or hide the section.
-
-.. seealso:: As an advanced user, you can route your audio signal to external
-             software and then apply additional effects. Go to
-             :ref:`advanced-external-fx` for more information.
-
-General Effects Controls
--------------------------
-
-**Eject Effect Button**
-  Eject the currently loaded effect.
-
-**Effect on/off Button**
-  Turn the effect on or off.
-
-**Select Buttons**
-  Select an effect.
-
-**Mix Knob**
-  Allows to decide how **strong** the effect should be.
-
-**Channel Buttons**
-  Select if the effect should be applied to master/pfl or different decks. The
-  buttons will light up if the effect is applied to a specific deck.
-
-Specific Effect Controls
--------------------------
+Mixxx comes with some built in sound effects that can be chained together in
+effect units. Effect units can be freely assigned to different decks as well
+as other inputs. The buttons for routing decks to effect units are in the
+:ref:`interface-decks`.
 
-Each effect provides it's own set of controls, see the :ref:`Use Effects
-<djing-with-effects>` section for more information.
+.. seealso:: The :ref:`effects` chapter has a more detailed explanation of the
+             effects system.
 
 .. _interface-mic:
 

source/index.rst

@@ -41,6 +41,7 @@ Table of Contents
    chapters/vinyl_control
    chapters/microphones
    chapters/livebroadcasting
+   chapters/effects
    chapters/djing_with_mixxx
    chapters/preferences
    chapters/advanced_topics