Document the Denon MC3000 controller mapping

Replace the stub page (no content, just a note asking for a
contribution) with full documentation for the rewritten mapping:
compatibility notes, audio interface setup, and per-section control
tables (mixer, deck, hot cue, loop, FX, sampler, library), plus a
Known Issues section covering the DECK CHG/LOAD A-B interaction, the
decks C/D EQ-kill limitation, and the unconfirmed DUCKING LED.

Author: dtavan

source/hardware/controllers/denon_mc3000.rst

@@ -1,11 +1,254 @@
 Denon MC3000
 ============
 
--  `Manufacturer’s product page <https://web.archive.org/web/20140713040211if_/https://www.denondj.com/products/view/mc3000>`__ (archived)
+The Denon MC3000 is a 4-channel, 4-deck DJ controller and mixer with a
+built-in USB audio interface. It has two physical deck sections (jog wheel,
+transport, hot cues, loop controls) and a 4-channel mixer, but only two FX
+units and eight sampler pads shared across all four decks. The manual
+describes this as a "deck layer function that can control four decks
+separately": the left deck section can be switched between controlling deck
+A or deck C with the :hwlabel:`DECK CHG.` buttons, and the right deck
+section between deck B or deck D.
 
 .. versionadded:: 2.0
 
+.. versionchanged:: 2.6
+   Added full 4-deck (A/B/C/D) support, current EffectRack/beatloop/
+   QuickEffect controls, and LED feedback for all four decks.
+
+Useful links
+------------
+
+- `Manufacturer's product page <https://web.archive.org/web/20140713040211if_/https://www.denondj.com/products/view/mc3000>`_ (archived, product discontinued)
+- `Forum thread <https://mixxx.discourse.group/t/denon-mc3000-midi-script/12283>`_
+- `Owner's manual (PDF) <https://cdn.inmusicbrands.com/denondj/legacy/mc3000/MC3000EM_ENG_IM_v00.pdf>`_
+- `Quick setup guide (PDF) <https://cdn.inmusicbrands.com/denondj/legacy/mc3000/MC3000EM_Quick_Setup_Guide.pdf>`_
+- `Windows driver v1.0.0, 2015 <https://cdn.inmusicbrands.com/denondj/legacy/mc3000/Denon_DJ_MC3000_Driver_v1.0.0(2015).zip>`_
+
+Compatibility
+-------------
+
+- **macOS**: no driver installation is required. The official quick setup
+  guide's only macOS step is configuring the device in Audio MIDI Setup,
+  with no driver install step at all, consistent with class-compliant USB
+  audio.
+- **Windows**: requires the official ASIO driver, linked above (also
+  originally shipped on the controller's Resource CD-ROM). After
+  installing, check that MC3000 has a checkmark in the ASIO driver control
+  panel and is enabled. The driver is old (2015) and not verified against
+  recent Windows versions - if it fails to install, Windows' generic USB
+  audio class driver may still work for basic use.
+- **Linux**: not explicitly documented by the manufacturer; expected to
+  work with the kernel's built-in ALSA USB audio driver as a
+  class-compliant device, but not verified.
+
+Audio Interface Setup
+----------------------
+
+The MC3000's built-in USB audio interface is documented (official quick
+setup guide) as:
+
+- Channels 1-2 = Master output.
+- Channels 3-4 = Headphone output.
+
+Configure these in Mixxx's Sound Hardware preferences accordingly. The
+single 1/4" microphone input and the LINE 1/2 inputs are analog mixer
+inputs only - not available to Mixxx as audio devices.
+
+.. note::
+   :hwlabel:`MASTER LEVEL`, :hwlabel:`MIC LEVEL`, :hwlabel:`MONITOR PAN`,
+   :hwlabel:`MONITOR PHONES`, and :hwlabel:`LINE TO MASTER` are fully analog
+   on this hardware and are not sent over MIDI at all, so adjusting them
+   changes nothing on screen in Mixxx.
+
+Mixer Section
+-------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - Channel fader, Cross fader
+     - Standard volume and crossfader control.
+   * - :hwlabel:`LEVEL`
+     - Channel pregain/trim.
+   * - :hwlabel:`FILTER`
+     - QuickEffect filter.
+   * - :hwlabel:`HI` / :hwlabel:`MID` / :hwlabel:`LOW`
+     - 3-band channel EQ.
+   * - :hwlabel:`CUE DECK A` / :hwlabel:`CUE DECK B` / :hwlabel:`CUE DECK C` / :hwlabel:`CUE DECK D`
+     - Headphone cue (PFL) toggle, one button per deck letter.
+   * - :hwlabel:`KEY LOCK`
+     - Toggles keylock for the deck.
+   * - :hwlabel:`SYNC`
+     - Beat-syncs the deck.
+   * - :hwlabel:`SAMPLE` (deck A) / :hwlabel:`EFX` (deck B)
+     - Kills the mid EQ band. Not available on decks C/D - there are no
+       spare buttons to extend this further.
+   * - :hwlabel:`BROWSE` (deck A) / :hwlabel:`RECORD` (deck B)
+     - Kills the low EQ band. Not available on decks C/D.
+   * - :hwlabel:`SHIFT` + :hwlabel:`BROWSE` (deck A) / :hwlabel:`SHIFT` + :hwlabel:`RECORD` (deck B)
+     - Kills the high EQ band instead of the low band.
+   * - :hwlabel:`DUCKING`
+     - Cycles microphone ducking mode (off / auto / manual).
+
+.. note::
+   :hwlabel:`SAMPLE`, :hwlabel:`EFX`, :hwlabel:`BROWSE`, and
+   :hwlabel:`RECORD` are originally window-switch buttons for
+   Traktor/VirtualDJ's on-screen browser panes, which Mixxx doesn't have.
+   This mapping repurposes them as EQ kill switches instead.
+
+Deck Section
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - :hwlabel:`PLAY`
+     - Standard play/pause.
+   * - :hwlabel:`CUE`
+     - Standard cue-point behavior.
+   * - Jog wheel (touch + turn)
+     - Scratches when touched with :hwlabel:`VINYL MODE` on; otherwise
+       bends pitch while turning.
+   * - :hwlabel:`VINYL MODE`
+     - Toggles scratch (vinyl) mode for the deck.
+   * - Pitch fader
+     - Adjusts the deck's playback rate.
+   * - :hwlabel:`PITCH BEND -` / :hwlabel:`PITCH BEND +`
+     - Temporary pitch bend while playing.
+   * - :hwlabel:`SHIFT` + :hwlabel:`PITCH BEND -` / :hwlabel:`SHIFT` + :hwlabel:`PITCH BEND +`
+     - While paused, jumps to the track start/end instead of bending pitch.
+   * - :hwlabel:`SHIFT`
+     - Modifier used by several controls throughout this mapping.
+   * - :hwlabel:`DECK CHG.` (A/B/C/D)
+     - Switches the left (A/C) or right (B/D) deck layer. See "Known
+       Issues" below for a limitation of this control.
+
+Hot Cue Section
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - :hwlabel:`CUE1` - :hwlabel:`CUE4`, :hwlabel:`CUE5` - :hwlabel:`CUE8` (with :hwlabel:`CUE5-8 MODE`)
+     - Sets/jumps to a hot cue point.
+   * - :hwlabel:`SHIFT` + hot cue button
+     - Clears the hot cue instead.
+   * - :hwlabel:`AUTO LOOP` + hot cue button
+     - Sets a beat-synced loop starting at that hot cue point, 8 beats long.
+
+Loop Section
+------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - :hwlabel:`AUTO LOOP`
+     - Engages/releases a beat-synced loop at the current position.
+   * - :hwlabel:`SHIFT` + :hwlabel:`AUTO LOOP`
+     - Deletes the current loop points instead of engaging a loop.
+   * - :hwlabel:`LOOP IN` / :hwlabel:`LOOP OUT`
+     - Manually sets the loop start/end point.
+   * - :hwlabel:`LOOP CUT -` / :hwlabel:`LOOP CUT +`
+     - Halves or doubles the active (or next) loop's length.
+   * - :hwlabel:`AUTO LOOP` + track select knob
+     - Moves the active loop earlier/later.
+
+FX Section
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - :hwlabel:`EFX.1` - :hwlabel:`EFX.4` buttons
+     - Toggles the corresponding effect slot on/off in the side's assigned
+       effect unit (left = Unit 1, right = Unit 2).
+   * - :hwlabel:`EFX.1` - :hwlabel:`EFX.4` knobs
+     - Adjusts the effect's meta knob parameter.
+   * - :hwlabel:`FX ON 1` / :hwlabel:`FX ON 2`
+     - Assigns effect Unit 1 or Unit 2 to whichever deck is currently
+       active on that side.
+
+Sampler Section
+----------------
+
 .. note::
-   Unfortunately a detailed description of this controller mapping is still missing.
-   If you own this controller, please consider
-   `contributing one <https://github.com/mixxxdj/mixxx/wiki/Contributing-Mappings#user-content-documenting-the-mapping>`__.
+   Per the official manual, the four :hwlabel:`EFX.1` - :hwlabel:`EFX.4`
+   knob/button pairs above are dual-purpose, switched entirely in hardware
+   by the :hwlabel:`SAMP.` button: "OFF: Switches to the effect mode. EFX.
+   1-4 are used to operate the effects. ON: Switches to the sample deck
+   mode. EFX. 1-4 are used to operate the sample deck." There is no
+   separate physical SAMP 1-4 control - it is the same EFX.1-4
+   buttons/knobs, relabeled in hardware.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - :hwlabel:`EFX.1` - :hwlabel:`EFX.4` as SAMP 1-4 buttons (while :hwlabel:`SAMP.` is on)
+     - Plays the corresponding sampler from its cue point.
+   * - :hwlabel:`SHIFT` + SAMP button
+     - Stops the sampler if playing, or ejects the loaded track if
+       stopped.
+   * - :hwlabel:`EFX.1` - :hwlabel:`EFX.4` as SAMP 1-4 knobs (while :hwlabel:`SAMP.` is on)
+     - Adjusts the sampler's gain.
+
+Library Section
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Control
+     - Function
+   * - Track select knob (:hwlabel:`SEL.`)
+     - Browses the track library.
+   * - :hwlabel:`SHIFT` + track select knob
+     - Nudges the cue point instead of browsing.
+   * - Track select knob push (:hwlabel:`SW`)
+     - Loads the highlighted track into the first stopped deck.
+   * - :hwlabel:`FWD` / :hwlabel:`BCK`
+     - Selects the next/previous playlist or crate.
+   * - :hwlabel:`LOAD A` / :hwlabel:`LOAD B`
+     - Loads the selected track. See "Known Issues" below for how these
+       route to the correct deck.
+
+Known Issues
+-------------
+
+- :hwlabel:`LOAD A` / :hwlabel:`LOAD B` do not read the :hwlabel:`DECK
+  CHG.` buttons directly - their MIDI signal has not yet been confirmed
+  working for this purpose. Instead, LOAD tracks whichever deck was most
+  recently interacted with on that side (left = A/C, right = B/D). After
+  switching layers with :hwlabel:`DECK CHG.`, touch any other control on
+  the newly active deck (jog wheel, a hot cue, a loop button, and so on)
+  before pressing LOAD, otherwise LOAD still targets whichever deck was
+  last used on that side.
+- EQ Kill (:hwlabel:`SAMPLE` / :hwlabel:`EFX` / :hwlabel:`BROWSE` /
+  :hwlabel:`RECORD`) is only available on decks A/B - there are no spare
+  buttons to extend it to C/D.
+- :hwlabel:`CF MODE` is not mapped: its stock function, toggling the
+  crossfader between audio and video assignment, has no Mixxx equivalent.
+- :hwlabel:`MASTER LEVEL`, :hwlabel:`MIC LEVEL`, :hwlabel:`MONITOR PAN`,
+  :hwlabel:`MONITOR PHONES`, and :hwlabel:`LINE TO MASTER` are fully analog
+  hardware controls, invisible to MIDI.
+- :hwlabel:`DUCKING`'s LED feedback is a best-effort implementation derived
+  from the manual's MIDI command list, not yet confirmed on real hardware.