diff --git a/docs/assets/screenshots/editor/drums.png b/docs/assets/screenshots/editor/drums.png new file mode 100644 index 0000000..3e9eb1b Binary files /dev/null and b/docs/assets/screenshots/editor/drums.png differ diff --git a/docs/assets/screenshots/editor/import.png b/docs/assets/screenshots/editor/import.png new file mode 100644 index 0000000..df57b41 Binary files /dev/null and b/docs/assets/screenshots/editor/import.png differ diff --git a/docs/assets/screenshots/editor/landing.png b/docs/assets/screenshots/editor/landing.png new file mode 100644 index 0000000..bfd9e1f Binary files /dev/null and b/docs/assets/screenshots/editor/landing.png differ diff --git a/docs/assets/screenshots/editor/mixer.png b/docs/assets/screenshots/editor/mixer.png new file mode 100644 index 0000000..22c9eb8 Binary files /dev/null and b/docs/assets/screenshots/editor/mixer.png differ diff --git a/docs/assets/screenshots/editor/notation.png b/docs/assets/screenshots/editor/notation.png new file mode 100644 index 0000000..266e810 Binary files /dev/null and b/docs/assets/screenshots/editor/notation.png differ diff --git a/docs/assets/screenshots/editor/notes.png b/docs/assets/screenshots/editor/notes.png new file mode 100644 index 0000000..bc61ccc Binary files /dev/null and b/docs/assets/screenshots/editor/notes.png differ diff --git a/docs/assets/screenshots/editor/pianoroll.png b/docs/assets/screenshots/editor/pianoroll.png new file mode 100644 index 0000000..e74be59 Binary files /dev/null and b/docs/assets/screenshots/editor/pianoroll.png differ diff --git a/docs/assets/screenshots/editor/tempomap.png b/docs/assets/screenshots/editor/tempomap.png new file mode 100644 index 0000000..87e1790 Binary files /dev/null and b/docs/assets/screenshots/editor/tempomap.png differ diff --git a/docs/assets/screenshots/editor/workspace.png b/docs/assets/screenshots/editor/workspace.png new file mode 100644 index 0000000..c333fef Binary files /dev/null and b/docs/assets/screenshots/editor/workspace.png differ diff --git a/docs/feedpak/authoring.md b/docs/feedpak/authoring.md index 7507654..329ae26 100644 --- a/docs/feedpak/authoring.md +++ b/docs/feedpak/authoring.md @@ -1,6 +1,13 @@ # Authoring and Editing feedpak Files -Short answer: advanced users can author or edit feedpak files by changing the manifest and related data files. +Short answer: most authoring is easiest in the **[Song Editor](../plugins/editor.md)**; +advanced users can also edit feedpak files by hand by changing the manifest and +related data files. + +!!! tip "Prefer the Song Editor" + For almost everything below — arrangements, tempo, sections, stems, and + metadata — the [Song Editor](../plugins/editor.md) is faster and safer than + hand-editing, and it validates and rebuilds the pack for you. ## Before You Start @@ -18,6 +25,7 @@ Short answer: advanced users can author or edit feedpak files by changing the ma ## Related Links +- [Song Editor](../plugins/editor.md) +- [Importing Tabs and Editing Arrangements](importing-tabs-editor.md) - feedpak spec: https://got-feedback.github.io/feedpak-spec/ - hand-editing guide: https://github.com/got-feedback/feedpak-spec - diff --git a/docs/feedpak/importing-tabs-editor.md b/docs/feedpak/importing-tabs-editor.md index 58504cb..fe5e9fe 100644 --- a/docs/feedpak/importing-tabs-editor.md +++ b/docs/feedpak/importing-tabs-editor.md @@ -1,13 +1,37 @@ # Importing Tabs and Editing Arrangements -Short answer: authoring tools and plugins can help turn source material into playable FeedBack arrangements. +Short answer: the **[Song Editor](../plugins/editor.md)** turns source material — a +Guitar Pro or MIDI file, a MusicXML score, or even a bare recording — into a +playable FeedBack arrangement, and edits any feedpak you already have. + +## The Song Editor + +Most importing and editing happens in the Song Editor. Open **Song Editor** from +the navigation, then choose **Create New** to import, or **Load…** to open an +existing feedpak. + +![The Song Editor: the Tracks column at left, the waveform and beat grid up top, and a chart laid out on the string lanes.](../assets/screenshots/editor/workspace.png) + +See the full **[Song Editor guide](../plugins/editor.md)** for the whole +create → chart → build workflow. + +## What You Can Import + +| Source | Notes | +|---|---| +| Guitar Pro (GP3–GP8) | Notes, tunings, and techniques. | +| MIDI | Notes plus the file's tempo map. | +| MusicXML | Guitar/bass tab, or a keyboard score (keeps left/right hands). | +| Arrangement XML | Community chart files. | +| Audio | A recording to chart from scratch — add a chart alongside it and they auto-sync bar by bar. | +| Existing feedpak | Open any pack to correct it. | ## Common Workflows | Workflow | Use It For | |---|---| | Import a tab file | Start from existing tab/notation data. | -| Arrangement editor | Fix notes, timing, sections, or metadata. | +| Song Editor | Fix notes, timing, tempo, sections, tracks, or metadata. | | Hand edit feedpak | Advanced correction of manifest or JSON files. | | Validate | Check that the feedpak still loads correctly. | @@ -23,14 +47,14 @@ Short answer: authoring tools and plugins can help turn source material into pla 1. Import or create the arrangement. 2. Confirm title, artist, and arrangement name. 3. Check tuning and string count. -4. Check note timing. -5. Add or verify sections. -6. Validate the feedpak. -7. Rescan/import into FeedBack. +4. Line the beat grid up to the audio (**Tempo Map**). +5. Check note timing. +6. Add or verify sections. +7. **Build** the feedpak, then rescan/import into FeedBack. ## Related Pages +- [Song Editor](../plugins/editor.md) - [Authoring and Editing](authoring.md) - [Validating feedpak Files](validation.md) - [Arrangements](arrangements.md) - diff --git a/docs/plugins/directory.md b/docs/plugins/directory.md index 78be783..a94f74c 100644 --- a/docs/plugins/directory.md +++ b/docs/plugins/directory.md @@ -50,6 +50,12 @@ Each plugin card should include: | Song Preview | Preview songs from library cards. | Available | [Song Preview](song-preview.md) | | Update Manager | Install, update, and remove plugins. | Available | [Update Manager](update-manager.md) | +## Authoring + +| Plugin | Purpose | Status | Guide | +|---|---|---|---| +| Song Editor | Turn a recording or an imported tab into a playable arrangement: chart notes, map tempo, add tracks and drums, and build a feedpak. | Available | [Song Editor](editor.md) | + ## Audio and Production | Plugin | Purpose | Status | Guide | diff --git a/docs/plugins/editor.md b/docs/plugins/editor.md new file mode 100644 index 0000000..b6ce337 --- /dev/null +++ b/docs/plugins/editor.md @@ -0,0 +1,188 @@ +# Song Editor + +Short answer: the **Song Editor** turns a recording — or an existing tab — into a +playable FeedBack arrangement. You line a grid up to the music, chart the notes, +add tracks and drums, and build a feedpak the rest of the app can practice against. + +The Song Editor is the authoring tool behind the whole library: every feedpak you +play can be opened, corrected, and rebuilt here. + +## When To Use This + +- You have a recording and want to chart it into a playable arrangement. +- You have a Guitar Pro, MIDI, or MusicXML file and want it as a feedpak. +- You want to fix the notes, timing, sections, tracks, or metadata of an existing feedpak. +- You want to add stems, drums, or a second instrument to a song you already have. + +## Open the Editor + +Open **Song Editor** from the left navigation. If no song is loaded you land at the +front door: + +![The Song Editor entry screen: Load an existing feedpak to edit, or Create New.](../assets/screenshots/editor/landing.png) + +- **Load…** opens a feedpak from your library to edit. +- **Create New** starts a project from scratch — from audio, a chart, or both. + +## Create a Project + +**Create New** takes almost anything as a starting point, and you can mix sources: + +| Start from | Details | +|---|---| +| A recording | An audio file (MP3, WAV, FLAC, OGG, M4A, OPUS, AAC, WEM) or a YouTube URL. | +| An existing chart | Guitar Pro (GP3–GP8), MIDI (its tempo map comes along), MusicXML (tab or keys), community arrangement XML, or an existing feedpak. | +| Both at once | Add one audio file **and** a chart — **auto-sync** lines the chart up to the recording bar by bar. This is the recommended start. | +| Nothing | Pick your arrangements from the chips and chart on an empty timeline. | + +Everything you add lands in one table: every audio source and every track inside +every chart file. Check the tracks you want, choose one audio row as the **Guide** +(the recording the tempo map follows), fill in the song details, then **Create & +Open in Editor**. + +![The Create New Arrangement dialog: a master audio and a Guitar Pro chart staged for import, the track table, the Guide selector, and auto-filled song details.](../assets/screenshots/editor/import.png) + +!!! note "Nothing touches your library until you Build" + The editor works on a private session. Save often with `Ctrl+S`; the **Build + feedpak** step (below) is the only thing that writes to your library. + +## The Workspace + +![The Song Editor loaded with a song: the multitrack Tracks column at left, the menu bar and toolbars up top, the waveform and note lanes filling the canvas.](../assets/screenshots/editor/workspace.png) + +- **Menu bar & toolbars** (top) — every command, grouped by what it acts on, plus + quick toggles for the transport, snap, views, and the BPM / Offset boxes. +- **Tracks column** (left) — the master mix, any stems, and every transcription + part, each beside its timeline lane. Rename, reorder, fold into folders, resize. +- **Timeline canvas** (center) — the waveform, the beat grid, and your notes. The + mouse wheel **pans**; hold **Ctrl** and scroll to **zoom** (**Alt+scroll** + stretches the piano-roll lanes). The overview strip above the lanes is a real + horizontal scrollbar — drag it to skim a long song, or double-click it to fit + the whole song. +- **Transport** (bottom) — play/stop, the playhead clock, loop, count-in, + metronome, and follow-playhead. +- **Mixer** (`Shift+C`) — vertical channel strips with live meters (see below). + +Press **`?`** for the searchable shortcut panel, or **`Ctrl+K`** for the command palette. + +## Chart the Notes + +Each part gets the view that fits it, chosen from the **view dropdown** (top-right): +**String view**, **Piano roll**, **Notation**, or **Notation + Tab**. + +### String view + +Colored blocks on per-string lanes — the number on each block is the fret. +Double-click to place a note, drag to move, drag the tail to change its length. + +![String view: colored note blocks per string with fret numbers, over the waveform and beat grid.](../assets/screenshots/editor/notes.png) + +Edit the selection: `F` (or `0`–`9`) sets the fret; `↑`/`↓` move between strings; +`Shift+↑`/`↓` move while keeping the pitch. Toggle techniques with single keys — +`H` hammer-on, `P` pull-off, `B` bend, `S` slide, `M` palm mute, `V` vibrato, and +more under **Note ▸ Techniques**. Press **`T`** for the tool palette (pointer, +pencil/draw, eraser, marquee, mute, scissors). + +### Piano roll + +Notes as bars on a keyboard, colored by octave — ideal for keys parts, and a +reference for fretted parts (shown at sounding pitch); you can add notes there by +sounding pitch and the resolver picks the string and fret. + +![Piano roll: notes as horizontal bars laid out on a piano keyboard.](../assets/screenshots/editor/pianoroll.png) + +### Notation and tab + +A live engraved score — standard notation and tablature, following every edit. +Click a beat to select its notes and seek. + +![Notation and tab view: an engraved staff over tablature for the arrangement.](../assets/screenshots/editor/notation.png) + +## Line the Grid Up (Tempo Mapping) + +This is the heart of charting a recording. The grid is **beat-primary**: a note +remembers its bar-and-beat, and its clock time comes from where the barlines sit. +Move the barlines and every note rides along — you fit the grid to the fixed +recording, never the other way around. + +![Tempo Map mode: vertical barline poles across the timeline, each labeled with its measure and BPM, over the waveform.](../assets/screenshots/editor/tempomap.png) + +Three ways to set the tempo, coarse to fine: + +1. **Sync tempo to audio** — detects the recording's BPM and scales the whole grid. +2. **Set a constant BPM** — type into the BPM box for a song at one tempo. +3. **Tempo Map mode** (press `T`, then `T` again) — the precise tool. Drag a barline onto its downbeat and + the surrounding bars re-space. From there: **`G`** suggests downbeats from the + audio's onsets to the end of the song, **`Shift+B`** taps the tempo, and you can + **beat-lock** a bar you've verified so later auto-fits leave it alone. + +Everything here moves **every track at once** and is undoable — experiment freely. + +## Tracks, Stems, and the Mixer + +A song can hold several tracks — lead, rhythm, bass, keys, drums — as first-class +objects. From a track's row you can rename it, drag to reorder or drop it into a +folder, set its level / mute / solo, and **pair** a transcription with the studio +stem it was charted against. Load per-instrument **stems** and chart against any of +them in isolation. + +The **mixer console** (`Shift+C`) is vertical channel strips with live meters over +the SOURCE / GUIDE / CLICK buses and a MASTER output. + +![The mixer console: channel strips per track plus the SOURCE, GUIDE, CLICK, and MASTER buses.](../assets/screenshots/editor/mixer.png) + +!!! tip "Fretted-track strings and keyboard hands" + Guitar tracks support 6–8 strings and bass 4–6 — the **− / +** buttons under the + lowest string change the count. Keys notes can carry a **left/right hand** + assignment (imported from MusicXML or authored yourself), which drives the + grand-staff notation's hand split. + +## Drums + +Drum tracks use a **piece-lane grid**: rows are kit pieces (kick, snare, hats, +toms, ride…), columns are grid positions. Click to place a hit; the **drum pad +strip** below maps a MIDI e-kit or your keyboard for monitoring. The **Rows** button +cycles Full / Compact / GM-roll density. + +![The drum piece-lane grid with a groove charted across the bars, and the kit map below.](../assets/screenshots/editor/drums.png) + +## Save and Build + +- **`Ctrl+S`** saves your working session as you go. +- **Build feedpak** assembles the finished feedpak and writes it to your library — + the only step that changes what the rest of the app sees. The pack carries + everything you authored: every arrangement, the tempo map, sections and phrases, + techniques, keys notation with its hand split, stems, tones, and art. + +Rebuild any time; your working session stays editable. **Undo/redo** (`Ctrl+Z` / +`Ctrl+Y`) covers every edit, including tempo moves and imports. + +## Shortcut Profiles + +The editor ships four keyboard profiles so it matches muscle memory you may already +have: **FeedBack** (the default), **Logical** (Logic-style), **Cableton** +(Ableton-style), and **Legacy (EOF)**. Switch in **Help ▸ Shortcut profile** or the +shortcut panel (`?`). The full, profile-aware list lives in that panel. + +## Common Problems + +| Problem | Try This | +|---|---| +| The editor buttons do nothing / it never loads | The editor needs a current FeedBack host. Update FeedBack, then reopen it. | +| The chart drifts out of time with the recording | Open **Tempo Map** (`T,T`) and drag the beat grid onto the audio, or nudge the whole chart with the **Offset** box. | +| An import brought in the wrong instruments | Re-check the track table in **Create New**, or use **File ▸ Import** / **＋ Track** to add the right one. | +| Drum notes were dropped on import | The wizard offers to remap percussion outside the kit vocabulary — accept the remap, or add the drums to an existing project. | +| My build isn't in the library | **Build feedpak** writes to the library; a plain save only updates the working session. | + +## Related Pages + +- [Importing Tabs and Editing Arrangements](../feedpak/importing-tabs-editor.md) +- [Authoring and Editing feedpak Files](../feedpak/authoring.md) +- [What Is a feedpak?](../feedpak/index.md) +- [Arrangements](../feedpak/arrangements.md) +- [Plugin Directory](directory.md) + +## Applies To + +Version: FeedBack 0.3.0+ (desktop and web) +Platforms: Windows, macOS, Linux diff --git a/mkdocs.yml b/mkdocs.yml index 41c8152..7f0be13 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ nav: - Stems and Stem Mixer: plugins/stems.md - Lyrics: plugins/lyrics.md - NAM Tone: plugins/nam-tone.md + - Song Editor: plugins/editor.md - Studio: plugins/studio.md - Rig Builder: plugins/rig-builder.md - Setlist: plugins/setlist.md