# MELODYJED - Wiki / User Guide

Everything you can do in the app, in one place. Read it whenever; you don't need any of it to
start (just hit PLAY). Skim the **Quick Start**, then dip into a section when you want a feature.

## Contents
1. [Run it](#1-run-it)
2. [Quick start (60 seconds)](#2-quick-start-60-seconds)
3. [The layout](#3-the-layout)
4. [Transport - play, tempo, swing, master](#4-transport)
5. [The grid - placing sounds](#5-the-grid)
6. [Sound bank + drag & drop](#6-sound-bank--drag--drop)
7. [Lanes - pitch, volume, mute, dice, delete](#7-lanes)
8. [Key + Scale (never sound wrong)](#8-key--scale)
9. [CRANK UP + per-lane dice (one-click magic)](#9-crank-up--dice)
10. [PUMP (the DNB sidechain bounce)](#10-pump)
11. [Vocals - sing & scream your own words](#11-vocals)
12. [Load your own samples (real guitars etc.)](#12-load-your-own-samples)
13. [Undo / redo](#13-undo--redo)
14. [Presets](#14-presets)
15. [Save / Load projects](#15-save--load)
16. [Export audio (MP3 / WAV)](#16-export-audio)
17. [Keyboard shortcuts](#17-keyboard-shortcuts)
18. [Recipes - heavy DNB x metal](#18-recipes)
19. [FAQ / troubleshooting](#19-faq--troubleshooting)
20. [Running the tests](#20-running-the-tests)

---

## 1. Run it
- **Easiest:** double-click **`Launch MELODY-JED.command`**.
- Or double-click **`index.html`**.

Runs fully offline from a local file. No install, no accounts. Audio starts on your first PLAY
(browsers require a click before making sound - totally normal).

## 2. Quick start (60 seconds)
1. Hit **PLAY** (or press `Space`). A beat is already loaded.
2. Smash **⚡ CRANK UP** and pick **GROOVE** a few times until something grabs you. Not musical? Doesn't matter - it always sounds right.
3. Click squares in the grid to add/remove hits.
4. Drag the **REESE BASS** and **GTR CHUG** **NOTE** sliders around (they stay in key).
5. Leave **PUMP** on, set **TEMPO** ~174, then **EXPORT ♪**. Mistake? `Cmd/Ctrl+Z`.

## 3. The layout
- **Top bar:** the wordmark, transport (PLAY/STOP/TEMPO/SWING/MASTER), **KEY/SCALE**, **PUMP**.
- **Left panel (SOUND BANK):** all the sounds you can drag in, grouped (Drums / Bass / Guitar / Vocals / FX), plus "load your own sample".
- **Middle (SEQUENCER):** the grid. Rows = sounds (lanes), columns = time. Toolbar above it has **⚡ CRANK UP** (the magic menu), +LANE, **PRO**, presets, UNDO, LOG, CLEAR, SAVE, LOAD, EXPORT, ? HELP.
- **Bottom:** status line (tells you what just happened).

## 4. Transport
- **PLAY / PAUSE** - start/stop playback (button or `Space`). The glowing column is the **playhead** - it shows where you are; cells flash and lane dots pulse as they fire.
- **STOP** - stop and reset to the start (`Esc`).
- **TEMPO** - speed in BPM. Type a number or drag the slider. **170-176 is classic DNB.**
- **SWING** - pushes off-beats later for a looser, groovier feel. Start around 8-20%.
- **MASTER** - overall volume.

## 5. The grid
- Each **row** is a sound. Each **column** is a 16th-note step (16 steps = 1 bar). The brighter columns are the main beats.
- **Click a square** to toggle a hit on/off. When you turn one on, you hear it.
- In **LOOP** mode the current section loops; in **SONG** mode the whole arrangement plays (see below).

### Building a full song (sections + arrangement)
A real DNB track is not one loop; it is an arrangement that builds. In the **SONG** bar above the grid:
- **+ SECTION** clones the current pattern into a new section (e.g. INTRO, DROP, BREAKDOWN, DROP 2). Edit each in the grid like normal.
- Each section block has a **repeat stepper** (`x4`), **move** arrows, **rename** (✎), and **remove** (×).
- **BARS** (toolbar) sets a section's length to **1 / 2 / 4 bars** (16 / 32 / 64 steps) so parts can breathe.
- Toggle **MODE: LOOP / SONG**. In SONG mode, PLAY walks the whole arrangement and the grid follows the section currently playing.
- **EXPORT ♪** offers to render the entire song (all sections, in order) to one audio file.
- Try the **FULL TRACK DEMO** preset to hear a complete intro / drop / breakdown / drop arrangement.

## 6. Sound bank + drag & drop
Sounds are grouped: **Drums, Bass, Guitar, Vocals, FX**.
- **Click a chip** to hear it *and "pick it up"* (it glows). Then **click a lane** to swap it, or the pulsing **+ row** to add a new lane. This is the click-only path - you never *have* to drag.
- **Drag a chip onto a lane** to swap that lane's sound (keeps the pattern).
- **Drag a chip onto a square** to place that sound right there (creates the hit).
- Press `Esc` to put a picked-up sound back down.

**What's in the bank (35+ sounds, all synthesized, no downloads):**
- **Drums:** Kick, Sub Kick, Snare, **Break (amen chop)**, Clap, Closed Hat, Open Hat, Rimshot, Tom, Ride, Crash, Shaker, Cowbell.
- **Bass:** **Reese Bass** (the heavy detuned DNB growl), Sub Bass, 808 Slide, Wobble, FM Bass.
- **Guitar:** **Gtr Chug** (palm-muted power chord), Gtr Lead.
- **Synth:** Pluck, Chord Stab, Bell, Saw Lead, Pad.
- **Vocals:** **Female Lead**, **Robo Vox**, Choir Pad, **Scream**, **Growl** (see [section 11](#11-vocals)).
- **FX:** Riser, Impact, Downlift, Zap, Rev Swell.

**Add a lane fast:** drag any chip straight into the grid (there's a "drop a sound here" row at the bottom) to create a new lane for it instantly.

## 7. Lanes
Each lane (row) has, on its left "head":
- **Colored dot + name** - the sound in that lane.
- **NOTE / TUNE slider** - pitch. Melodic sounds (bass/guitar/vocals) show **NOTE**; drums show **TUNE** (fine detune). Melodic notes are locked to the KEY (see below).
- **⚄ dice** - reroll just this lane's pattern (musical, in key). Great for "give me a different bassline".
- **M** - mute the lane.
- **×** - delete the lane.
- **Volume slider** - lane loudness.

Add lanes with **+ LANE** (drop a sound onto it to choose what it is).

### PRO mode - deeper per-lane control
Click **PRO** in the toolbar to reveal extra knobs on every lane head (hidden by default so it stays simple):
- **SPACE** - reverb send (room / air).
- **THROW** - tempo-synced delay send (that DNB echo). Both keep the low end tight - bass stays dry.
- **LEN** - note length (gate) for melodic lanes.
- **GRIT** - extra tear / rasp on SCREAM and GROWL.

Every sound already ships with tasteful defaults, so PRO is only there when you want to go deep. The **pinnacle is reachable by one CRANK UP click *or* by hands-on tweaking.**

## 8. Key + Scale
This is the "can't sound wrong" feature.
- **KEY** (top bar) - the musical root (default **E**).
- **SCALE** - the mood. **Minor** (default) is dark/classic; **Phrygian (metal)** is extra dark/heavy; also Harmonic Minor, Dorian, Minor Pentatonic, Major, and **Chromatic (off)** which disables snapping.
- Every bass/guitar/vocal **NOTE** slider snaps to notes that fit the key, so melodies always sound in tune together. Change the KEY and everything transposes to stay in tune.
- For heavy metal vibes, try **Phrygian**.

## 9. CRANK UP + dice
**⚡ CRANK UP** (the glowing button) is your one-click magic. It opens a small menu:
- **🎲 GROOVE** - writes a whole genre-correct DNB pattern across every lane. Keep picking it for new ideas.
- **✨ POLISH** - auto-mixes the section: resets each lane's SPACE / THROW to a tasteful default and balances levels so it all sits together.
- **🏗 BUILD** - auto-arranges your pattern into a full song (INTRO -> BUILD -> DROP -> BREAKDOWN -> DROP 2) and switches to SONG mode.
- **🔀 VARY** - drops a musical variation of the current section right after it (keeps the kick/snare backbone).
- **🥁 FILL** - rolls a drum fill into the last bar.

Plus the **⚄ dice on each lane** - rerolls only that part. Love the drums but not the bass? Dice just the bass.

Everything uses real DNB pattern templates and the current KEY, so results are always musical (never random noise). Vocal lanes even get a random lyric.

## 10. PUMP
- **PUMP** (top bar toggle) is a **sidechain**: the bass and guitar briefly duck every time the kick hits. That "breathing" bounce is a signature of heavy DNB. Leave it **on** for an instantly more pro sound; turn off for a flatter, wall-of-sound feel.

## 11. Vocals
Five synthesized voices in the **VOCALS** bank:
- **FEMALE LEAD / ROBO VOX** - sung leads (clear / bright-robotic).
- **CHOIR PAD** - soft sustained "ooh/aah" pad.
- **SCREAM** - torn metalcore scream. **GROWL** - guttural death-metal roar.

Screams and growls now have real grit; push it further with the **GRIT** knob in [PRO mode](#7-lanes).

**Type words to sing/scream:**
1. Add a vocal lane (drag one in from the bank).
2. In that lane's **text box**, type a few words (e.g. `rise up`, `burn`).
3. Place a step - the voice will "sing" (or scream) your words by morphing through their vowels and consonants.
4. Use the **NOTE** slider to set the pitch (it stays in key). Longer phrases = give the note more room (place fewer steps so it rings out).

**Expectation:** this is a **vocaloid/robotic** effect, not clear speech. You'll hear the vowels and the rhythm of the words clearly - perfect for hooks and screams - but it's stylized on purpose so it stays part of the beat (pitched, sidechained, exported). It is *not* a talking voice.

## 12. Load your own samples
Want real Rammstein-style guitars or a vocal chop?
- **Drag a `.wav` / `.mp3` file onto a lane**, or
- Select a lane (click its head), then use **"+ load your own sample"** in the SOUND BANK panel.

The sample replaces that lane's synth voice and follows its pitch slider (NOTE = repitch, TUNE = semitone shift). Short, dry one-shots (a single hit, no long reverb tail) sequence tightest.
Good free sources are listed in `sounds/README.md`.

> Note: loaded samples aren't yet embedded in saved `.jed` files - re-load them after opening a project. (On the roadmap.)

## 13. Undo / redo
- **UNDO** button, or `Cmd/Ctrl+Z`.
- **Redo:** `Cmd/Ctrl+Shift+Z`.
- Covers step edits, sound swaps, dice/IDEA, add/remove lane, clear, etc. Experiment freely.

## 14. Presets
Use the **presets** dropdown (sequencer toolbar) to load a starting groove:
- **Banger Starter** - balanced heavy roller with a guitar (default).
- **Heavy Roller** - bass-led two-step.
- **Vox Drop** - shows off the vocals (sings "rise up", screams "burn").
- **Metal Chug** - guitar-driven DNB x metal.
- **Minimal Two-Step** - sparse skeleton to build on.
- **Empty Canvas** - start from scratch.

## 15. Save / Load
- **SAVE** - names your track and downloads a `.jed` file (also keeps a copy in the browser). `.jed` is just JSON: it stores the pattern, sounds, pitches, key/scale, pump, tempo, swing, and lyrics.
- **LOAD** - open a `.jed` file to restore a project.

## 16. Export audio
- **EXPORT ♪** - renders your loop to an audio file. It asks how many bars (loops) to render, then downloads an **MP3** (or WAV if the encoder isn't present).
- It's an offline render, so it's fast and exactly matches what you hear (including PUMP and vocals).
- Take the file into any DAW, or share it directly.

## 17. Keyboard shortcuts
- `Space` - play / pause
- `Esc` - stop (also closes the how-to / puts a picked-up sound back down)
- `Cmd/Ctrl + Z` - undo
- `Cmd/Ctrl + Shift + Z` - redo
- `F1` - open / close the one-screen how-to

## 18. Recipes
**Heavy DNB roller (Dimension / Delta Heavy vibe)**
1. Preset: Heavy Roller (or Banger Starter). KEY E, SCALE Minor. PUMP on. TEMPO ~174.
2. Make sure the **Reese Bass** rolls (hits on several off-beats). Slide its NOTE for movement.
3. Keep kick on 1 and the "and" of 3; snares on beats 2 and 4.

**DNB x metal (Bring Me The Horizon / Bullet feel)**
1. SCALE -> **Phrygian (metal)**. Add a **GTR CHUG** lane, dice it, tune to the low root.
2. Add a **SCREAM** vocal lane, type a word (e.g. `burn`), place it on a big accent (step 13).
3. Add an **IMPACT** on step 1 of the drop for weight.

**Instant banger**
- **⚡ CRANK UP > GROOVE** -> dice the parts you don't like -> **CRANK UP > POLISH** to auto-mix -> **CRANK UP > BUILD** for a full arrangement -> EXPORT.

## 19. FAQ / troubleshooting
- **No sound?** Click **PLAY** once (browsers block audio until you interact). Check MASTER and lane volumes, and that lanes aren't muted (**M**).
- **A melody sounds off?** Make sure SCALE isn't on **Chromatic (off)**; pick Minor/Phrygian so notes snap to key.
- **Vocals aren't clear words.** Expected - it's a stylized robo/scream voice, not speech (see [section 11](#11-vocals)).
- **Export gave a WAV, not MP3.** The MP3 encoder file is missing/blocked; WAV is high quality and works everywhere. Re-adding `js/vendor/lame.min.js` restores MP3.
- **Fonts look plain.** They shouldn't - the pixel/CRT fonts are bundled in `fonts/` and load offline. If a browser blocks local font files it still works fully, just less pretty.
- **My samples vanished after loading a project.** Known MVP limitation - re-load samples (patterns/settings are saved, raw audio isn't yet).

## 20. Running the tests
There's an automated regression suite so future changes don't quietly break things. From the project folder:
```bash
npm test          # or: node tests/run.mjs
```
It needs Node and the Chrome you already have (no installs). It renders the audio engine and checks
playback, key-lock, vocals, undo, save/load, and export, then confirms the app boots with no errors.
Exit code 0 means everything passed. Full details in `tests/README.md`.

---

*See also: `../README.md` (overview), `DESIGN.md` (look & feel intent), `BACKLOG.md` / `EPICS.md` (roadmap), `../sounds/README.md` (sample sources), `../tests/README.md` (test suite).*