> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sampler.meiji.industries/llms.txt
> Use this file to discover all available pages before exploring further.

# DJ Mode

> Perform your bounced songs on two decks — keyboard-first, with plug & play DDJ-REV7 support and Serato-compatible cues.

# DJ Mode

DJ mode turns your Bounces folder into a performable library. Every song you bounce appears automatically with its BPM, length, and date — no import step — and can be loaded onto two decks with pitch, nudge, hot cues, SYNC, and keylock.

DJ mode is currently feature-flagged and rolling out gradually.

## Where it lives

Press `[TAB]` to cycle to the `DJ` tab (`Create → Perform → DJ → Settings`).

## The library

The library lists every master bounce from `~/Documents/Meiji Sampler/Bounces/`, newest first. BPM is captured automatically at bounce time from your project tempo.

* `[↑/↓]` and `[PGUP/PGDN]` — select a track
* `[ENTER]` — preview the selected track
* `[L]` — load onto the focused deck, `[SHIFT+L]` — load onto the other deck

New bounces appear in the library within a couple of seconds, even while the DJ tab is open.

Each track's BPM is tinted by how reachable it is from the focused deck: **green** when the pitch fader can match it straight, **amber** when it only matches at half or double time, and **grey** when it is out of range or untagged. It is a quick read on what will mix with what is already playing.

## Record a DJ set

Press `[R]` in DJ mode to toggle DJ master recording. The library footer reads `[R] record` when idle and `[R] stop recording` while a take is active. The status row keeps a red `REC mm:ss` clock visible while you perform, without replacing other status messages.

`[CTRL+R]` remains the shortcut for input recording. Use it when you want to sample an input device. Use `[R]` in DJ mode when you want to print the set that Meiji Sampler is playing.

DJ set files are stereo IEEE Float32 32-bit WAV files at the active DJ output rate. They are saved in Bounces as `DJ Set YYYY-MM-DD HH-MM-SS.wav`. If that name is already taken, Meiji Sampler adds a collision suffix such as `DJ Set YYYY-MM-DD HH-MM-SS (2).wav`. Very long recordings roll into numbered `Part 2` files before classic WAV reaches its size limit.

Both system-output and REV7 hardware-output sets capture Meiji Sampler's safety-limited post-PerformFX software master. In hardware mode, that master is the unity-gain sum of the two post-PerformFX deck stems before the REV7 physical mixer. The REV7 EQ, channel faders, crossfader, microphone or auxiliary input, and hardware master processing are intentionally not recorded.

If an overflow, tap failure, disk error, or finalization error interrupts a set, Meiji Sampler retains its `.partial` file for recovery. A partial is never announced or scanned as a completed bounce. See [File And Project Problems](/troubleshooting/files-and-projects#recover-a-dj-recording-partial) before attempting recovery, and see [Exporting And Bouncing](/guides/exporting-and-bouncing#dj-master-recordings) for how the recorded master differs from an arrangement bounce.

## Decks

The DJ tab is laid out like a horizontal-waveform DJ rig. Two deck info blocks sit side by side at the top, full-width scrolling waveforms fill the middle, and the library runs along the bottom. Decks keep playing when you peek at another tab.

Buttons and hot cues are dispatched as soon as their bounded controller snapshot arrives; they do not wait for a redraw. Continuous jog and pitch-fader reports are combined over a fixed 5 ms window before the deck estimates velocity. That window averages the REV7's quantized 1 kHz encoder reports so vinyl movement stays stable instead of turning report-to-report jitter into audible pitch modulation. Hot-cue jumps and scratch onset use a roughly 1 ms click-safe transition, while ordinary play, pause, and scratch release retain the gentler 5 ms transport fade. Scratch audio follows the resulting velocity curve continuously instead of teleporting its playhead to each controller report. Cue capture still follows the event-time controller position, so realtime cue placement stays responsive without adding phase jumps to the audio path.

DJ output honors `Settings → Audio → Buffer Size`. Choose `64 samples` for the shortest controller-to-speaker path, then use `Apply Now` when prompted. If that device crackles at 64, use `128` or `256` rather than sacrificing audio stability; the selected size applies to both system-output and REV7 hardware-output DJ streams.

Each **deck info block** carries the track name, the effective BPM with the natural tempo it came from, the pitch fader position and its range, `SYNC` / `KEYLOCK` / `VINYL` badges, elapsed and remaining time, the temp-cue readout, eight hot-cue chips tinted in their own cue colors, and a one-row overview of the whole track with the played portion dimmed and a `█` marking the playhead. Each deck has an identity color — cyan-green for deck A, magenta for deck B — worn by its border, badges, transport glyph, overview strip, and its half of the waveform panel, so the two decks are never ambiguous.

The **waveform panel** shows both decks stacked full width, each drawn in its own deck color, scrolling right to left under a fixed white playhead at the center. A beat ruler runs alongside each waveform with a tick on every beat and the bar number printed at each downbeat. Hot cues mark the waveform the same way chop markers do in the trim view — the cue number itself runs as a colored column down the full height of the deck, so you read which cue you are looking at without a legend. When the playhead lands on a cue it keeps that cue's number rather than hiding it. Between the two waveforms is a **phase-match strip**: deck A's beats draw above the line, deck B's below, and a cell turns white where both land together — so "in phase" is something you see rather than something you count. A track with no BPM tag reads `no beatgrid` and still renders its waveform.

Taller terminals give their extra rows to the waveform rather than the list, so a full-screen window gets a noticeably bigger waveform.

### PerformFX focus

When PerformFX is enabled, each nonblank bank appears in a compact row between the deck blocks and the dual waveforms. Empty banks stay hidden. The focused row has the active border, and its slots use the same assigned, queued, active, release-pending, releasing, and missing states as the Perform tab.

Use `[↑/↓]` to move through `Decks → Bank A → Bank B → Library`; hidden banks are skipped. `[TAB]` remains the application-tab switch and never changes focus inside DJ mode. DJ mode keeps `[K]` for keylock, so Vim direction aliases are intentionally not used for this focus control. Number keys follow the focused zone:

* **Decks:** `[1]`–`[8]` set or trigger hot cues. `[9]` and `[0]` are consumed.
* **PerformFX bank:** `[1]`–`[9]`, `[0]` trigger that bank's ten fixed slots. Empty slots report that they are empty.
* **Library:** number keys are consumed so a library selection cannot accidentally fire a cue or effect.

Press `[A]` or `[B]` at any time to focus that deck and return keyboard control to the Decks zone.

### Pitch range and live BPM

Each deck owns its current pitch range. Use a narrow range for fine beat-matching, a wider range for tracks with larger tempo differences, and `±50%` for deliberate varispeed moves.

Changing a range immediately reinterprets the owning deck's current physical tempo-fader position. For example, a fader halfway above centre becomes `+8%` when the range changes from `±8%` to `±16%`. Pressing `[P]` or a REV7 `TEMPO RANGE` button changes only its owning deck immediately, then saves one global future default. The next track load on either deck uses that saved default; the other active deck remains unchanged.

The Settings `DJ → Pitch Range` value is the default for the next track load on either deck. Changing it leaves both active decks unchanged. When you load another track on deck A or B, that deck adopts the current default and returns to neutral pitch; the other deck keeps its current range, pitch, and fader position.

On the optional high-resolution jog surface, Meiji Sampler streams the current beatgrid BPM after the deck's pitch is applied to the REV7 platter readout. It refreshes when asynchronous beatgrid analysis finishes and after you edit the grid, so its value stays aligned with the active mix. Pressing `[P]` replays the complete loaded-track display state at the live playhead, including the owning deck's tempo-range slot, instead of sending an isolated range byte that the platter can ignore. The default Pioneer surface keeps the controller's own idle display.

<Note>
  REV7 hardware has confirmed the live post-pitch BPM readout. Pitch ranges use the controller's native `±8`, `±16`, and `±50` values in the TUI and audio engine. The refreshed physical tempo-range indicator still requires controller confirmation.
</Note>

Developers preparing a capture matrix can run `cargo run --release --features hid --example rev7_display_proof` to emit the source BPM, pitch, pitch range, effective BPM, encoded whole/tenths bytes, tempo-range slot, and complete outgoing `0x27` frame for each proof row.

* `[A]` / `[B]` — focus a deck (the focused deck receives all transport keys)
* `[SPACE]` — play/pause
* `[C]` — cue: while stopped, sets the temp cue at the playhead; while playing, jumps back to it and stops
* `[-]` / `[=]` — pitch fader down/up (`[_]` / `[+]` for fine steps)
* `[P]`: cycle the focused deck's pitch range: `±8% → ±16% → ±50% → ±8%`
* `[Q]` / `[W]` — nudge backward/forward while held (momentary pitch bend for beat-matching)
* `[←]` / `[→]` — scrub: audibly wind the track backward/forward (vinyl-style, works while paused too, and winds into the silent lead-in below `0:00`)
* `[S]` — SYNC: matches this deck's tempo to the other deck *and* snaps it onto the other deck's beat, the way Serato and other DVS behave. Uses double or half time when the straight match exceeds the pitch range. Moving the pitch fader releases the latch.
* `[K]` — keylock (master tempo): pitch changes tempo without changing musical key
* `[V]` — jog mode: `VINYL` (default) or `BEND`, shown as the `VINYL` badge on both deck blocks and saved in your settings
* `[Z]` / `[X]` — waveform zoom: halve or double the visible window (1.5 s–24 s, default 6 s). Zoom is shared by both decks and resets each session.
* `[;]` / `[\']` — halve or double the focused deck's grid tempo (the one keypress that fixes a wrong octave)
* `[,]` / `[.]` — shift the grid anchor by 10 ms; `[<]` / `[>]` by 1 ms

### Cueing before the track starts

Like a real record, each deck has 1.8 seconds of silent groove ahead of the first sample — one full platter revolution at 33⅓ RPM. Wind back past `0:00` with `[←]` or the jog ring and the deck clock counts negative (`-0:01.4`) while the deck stays silent.

That silent runway is where you cue a drop. Hold a baby scratch in it, keep the motion going while you wait for the "one", and let go or hit `[SPACE]` — the deck counts in through the silence and the track always begins at exactly `0:00`, at full level. Without the lead-in the only way to cue is to hold the record still and release it, because any forward motion plays immediately.

The playhead stops at the end of the lead-in, and the track's own end has the same silent run-out. Cue points always mark positions inside the track, so setting one from the lead-in marks the start.

## Beatgrids

Bounces made since DJ mode shipped carry their tempo and beatgrid in the file. Anything older — or imported from elsewhere — arrives without one, so **Meiji Sampler analyses it the first time you load it onto a deck**. The beat ruler reads `analyzing beatgrid…` for a moment, then fills in.

The detected grid is written into the file in Serato's format and cached, so it is instant on every subsequent load, and the same file opens in Serato DJ with the grid already there.

Detection is not infallible. Two things to know:

* **Tempo is biased toward the slower reading.** A 170 BPM track may be gridded at 85. The beats still land on beats, so SYNC and the phase strip work correctly — only the number is halved. `[;]` and `[']` fix the label instantly.
* **A tempo the analyser wasn't sure about is marked with `?`** (`84.0? BPM`). The grid still works; the marker is telling you to trust your ears over the number. A grid you adjust by hand loses the `?`, because you have overruled the guess.

Tracks under eight seconds, and free-tempo material with no steady pulse, get no grid at all rather than a fabricated one.

## Hot cues

Eight hot cues per deck on the numbered keys — the same muscle memory as Create-tab pads:

* `[1]`–`[8]` — set the cue if the slot is empty, otherwise jump to it and play
* `[CTRL+1–8]` — clear a cue

Cues are written into the song file itself in Serato's native format a moment after you set them, and reload with the track — on either deck, in any session.

## Serato interop

Every bounce carries its BPM, a beatgrid anchored at the first beat, and your hot cues inside the WAV in Serato's own metadata format. Open the same file in Serato DJ Pro and the grid and cues are already there.

## Pioneer DDJ-REV7 plug & play

Connect a DDJ-REV7 over USB and Meiji Sampler makes its mapped controls live without a manual mapping or configuration step. The control map follows AlphaTheta's official MIDI specification:

* `START/STOP`, `BEAT SYNC`, `KEY LOCK`, and `TEMPO RANGE` buttons, performance pads (hot cues, `SHIFT`+pad clears), `PITCH BEND −/+` buttons (nudge), tempo faders, and jog rings control the decks. `TEMPO RANGE` cycles the range of its own deck through `±8%`, `±16%`, and `±50%`, immediately reinterprets that deck's physical tempo fader, and saves one global default for the next track load on either deck.
* Jog behavior follows the `[V]` jog mode: in `VINYL` (default), rotating the platter takes the playhead with it — wheel back and the record audibly winds backwards, and playback resumes the moment the platter stops. In `BEND`, rotation nudges the pitch like a CDJ. Paused decks always scrub audibly. (No platter touch message has been identified on either of the REV7's MIDI surfaces, so vinyl mode releases on motion-stop rather than on lifting your hand.)
* Pad and transport LEDs mirror deck state
* The rotary selector scrolls the library (press to preview); `LOAD` buttons load decks
* Motorized platter drive follows the transport when the high-resolution jog surface is switched on (see below): playing a deck spins its physical platter, and pausing brakes it — the platter takes about a second to coast down. On the default surface the platter stays still, and deck controls, LEDs, jog motion, and audio routing all work without it.
* Deck audio routes to the REV7's own hardware mixer (deck A → channels 1/2, deck B → 3/4), so the physical faders, EQ, and crossfader do the mixing

Power the REV7 on before or after launching Meiji Sampler. When its MIDI port becomes available, the status reports `Pioneer DDJ-REV7 connected — decks are live`. The REV7 can expose its MIDI controls before its audio interface or optional HID display finishes booting. Controls and LEDs may therefore be ready first. Meiji Sampler keeps the set on system output until the controller audio interface appears, then opens the established four-channel deck route at the controller's current native sample rate. It retries every 250 ms for up to 20 seconds without tearing down the working system-output stream. With the high-resolution jog surface enabled, the cosmetic HID endpoint is retried independently; once it appears, both loaded decks replay their complete waveform, position, pitch, range, and BPM state.

Unplugging or powering off mid-set is equally safe: the status reports `Pioneer DDJ-REV7 disconnected — keyboard control continues`, the decks keep playing, and audio falls back to your system output. Every hardware control has a keyboard equivalent.

The runtime attachment lifecycle is verified through virtual CoreMIDI add/remove coverage. That hardware-independent proof confirms the connection and disconnection workflow, but it is not physical REV7 boot-timing certification. If the controller remains invisible after it has completed its boot sequence, follow [Audio And Playback Problems](/troubleshooting/audio-and-playback#a-rev7-does-not-appear-after-powering-on).

The default Pioneer jog surface keeps the controller's own idle display. On the optional high-resolution Serato surface, Meiji Sampler attempts to stream the deck waveform, position, pitch, and live post-pitch BPM through the REV7's HID display endpoint. If that cosmetic endpoint is unavailable, the displays may remain blank while deck control and audio continue normally.

Meiji Sampler derives the high-resolution platter waveform and remaining-time
countdown from one display timeline based on the decoded track length. For the
reported 96.6-second track, it sends an extent intended to carry both readouts
past `-01:00.4` to the track end. Post-fix physical display behavior awaits
hardware confirmation.

### High-resolution jog

`dj.hi_res_jog` in `config.json` switches the REV7 onto its high-resolution jog surface. It is `false` by default, and the change takes effect the next time the controller connects — set it, then unplug and replug the REV7.

Switching it on gives you:

* **Scratch-grade jog resolution** — the platter reports 10,080.7 encoder ticks per revolution (the device caps the stream at 1,000 messages per second) instead of the public surface's coarse direction ticks
* **Motorized platter drive** — playing a deck spins its physical platter, pausing brakes it
* **Software-driven platter display** — Meiji Sampler sends waveform, position, pitch, the owning deck's tempo-range slot, and current post-pitch BPM when the REV7 HID endpoint opens

The display path is cosmetic and still awaiting the physical capture matrix. A failed HID open can leave it blank without affecting control or audio. The default surface continues to show the controller's idle screen. Nothing else about the controller changes, and no replug is needed to keep using it.

Keylock and vinyl manipulation use the active output rate, including 44.1, 48, 88.2, and 96 kHz paths. Motor-idle filtering releases the scratch path after platter motion settles, so ordinary pitched playback returns to keylock instead of remaining latched in vinyl processing.

## Troubleshooting

* **Controller not detected** — wait for the REV7 boot sequence to finish, then check the USB connection and that no other DJ software holds the device. The MIDI monitor (`Settings → MIDI Monitor`) shows incoming messages. If it remains invisible, use [Audio And Playback Problems](/troubleshooting/audio-and-playback#a-rev7-does-not-appear-after-powering-on).
* **No sound from the REV7** — its audio interface can appear after its controls. Meiji Sampler keeps using system output while it waits, then opens the proven four-channel deck route at the controller's native rate. Hardware routing can be disabled in `config.json` (`dj.hardware_audio_enabled`).
* **Number keys do nothing to hot cues** — press `[A]` or `[B]` to return focus to Decks. Number keys intentionally target PerformFX while an FX bank is focused and are consumed while Library is focused.
* **Platter BPM looks implausible or stale**: wait for the `analyzing beatgrid…` state to finish, then correct a half or double-time grid with `[;]` or `[']`, or nudge its anchor with `[,]` or `[.]`. The readout refreshes after analysis and grid edits.
* **Platters do not spin** — platter drive rides on the high-resolution jog surface, which is off by default. Set `dj.hi_res_jog` to `true` in `config.json` and reconnect the controller. Deck controls and audio work either way.
* **Cues missing in Serato** — cues are written a couple of seconds after you set them; make sure the file isn't read-only. The status line warns when a write falls back to cache-only.
* **DJ recording stopped with a `.partial` file**: preserve the file, but do not rename it into the Bounces library. Follow [the recovery steps](/troubleshooting/files-and-projects#recover-a-dj-recording-partial) to copy and recover it in an audio editor.