KGStudio/docs/USER_GUIDE.md

# K.G.Studio User Guide

A lightweight, browser‑based DAW with an AI Agent "K.G.Studio Musician Assistant". This guide walks you through setup, the interface, and everyday workflows.

## 1. Introduction
- K.G.Studio runs entirely in your browser. It provides track and region editing, a piano‑roll editor, realistic instrument playback (Tone.js samplers with FluidR3 soundfonts), robust undo/redo, and project persistence.
- K.G.Studio Musician Assistant can respond to natural language prompts and execute edit tools on your behalf.

## 2. System Requirements
- Tested on Chrome, Firefox, and Safari. It should work on other modern browsers, but those are not officially tested yet.
- macOS, Windows, or Linux.
- Network access is only needed for downloading instrument sound samples and contacting your selected LLM provider.

## 3. Quick Start
- **Use the hosted app: [K.G.Studio (kgaudiolab.github.io/kgstudio)](https://kgaudiolab.github.io/kgstudio)**
- Or clone and run locally:
  ```bash
  # Make sure you have Node.js >= 20.19.3 installed
  # Clone the repository
  git clone https://github.com/KGAudioLab/KGStudio {your-local-path}
  cd {your-local-path}

  # Install dependencies
  npm install

  # Run the development server
  npm run dev
  ```
- First run:
  - A welcome message will be shown on the K.G.Studio Musician Assistant chatbox, please follow the instructions to configure the LLM provider.
- Your data is stored in your browser’s IndexedDB (on your device).

## 4. Data, Privacy, and Connectivity
- IndexedDB is your browser’s local database for this site; it never leaves your machine and is cleared if you clear the site’s data.
- Per‑origin storage: IndexedDB is not shared across different hosts/origins, across different browsers, or separate browser profiles. To move or share your work, use Export (KGStudio JSON) and Import on the destination.
- K.G.Studio is fully client‑side. It connects to the network only to:
  - Download instrument soundfonts from the configured CDN
  - Communicate with your chosen LLM provider (OpenAI or OpenAI‑compatible)
- API keys are not persisted when running from a non‑local host (to reduce XSS risk). You’ll be prompted to re‑enter them on each start in that scenario.
- Important: While K.G.Studio does not collect your data, different LLM providers may have different data‑retention policies. Review the policy of the provider you select before use.

## 5. User Interface Tour
### Toolbar
- Left
  - Logo
  - Project name (click to rename)
- Center (exact order)
  - New, Load, Save, Export (dropdown), Import
  - Undo, Redo
  - Pointer tool, Pencil tool
  - Copy, Paste, Delete
  - Back to beginning, Play/Pause
  - Piano button (open piano roll for the active/selected region)
- Right
  - Transport readouts: current time | BPM | time signature | key signature
    - Click time to set max bars, BPM to change BPM, time signature to change signature; key signature opens a dropdown.
  - Settings (gear)
  - Chat (speech bubble) — toggles the AI chatbox on the right

### Track Area
- Track info column
  - Solo (S), Mute (M), volume, instrument button (piano icon)
  - Settings button (to the right of the instrument button) with a Delete Track option
- Track grid
  - Regions display as blocks with a header; the small pencil on the top‑left of a region opens its Piano Roll.

### Instrument Selection Panel
- Appears automatically on load/first track creation, or when clicking a track’s instrument button (to the right of “M”).
- Choose instrument groups and individual instruments; a large preview is shown.
- Stays open until you close it (X) or click the same track’s instrument button again.

### Chatbox (AI Assistant)
- Docked on the right; toggle from the toolbar.
- Press Enter to send; Shift+Enter for a new line.

### Status Bar and Loading Overlay
- Status messages appear at the bottom.
- A global loading overlay shows while soundfonts are downloading.

### Piano Roll Window
- Header: close (X) on the left; title (click to rename); tools (Select, Pencil); menus on the right: NO SNAP, Qua. Pos. (quantize start), Qua. Len. (quantize length).
- ESC closes the piano roll.

## 6. Projects
- New, Save (to IndexedDB), Load (from IndexedDB by name).
- Export: KGStudio JSON, MIDI.
- Import: KGStudio JSON (replaces current project state), MIDI (appends tracks/regions into the current project).
- Legacy compatibility: projects are upgraded to the latest structure on load.

## 7. Tracks
- Add, rename, and reorder tracks.
- Change instrument (instrument button in the track info row). Real instruments are powered by Tone.Sampler and FluidR3 soundfonts.
- Solo/Mute/Volume controls for quick mixing.
- Track settings (button to the right of the instrument) provides Delete Track.

## 8. Regions
- Create regions
  - Pointer tool: double‑click; or hold Ctrl/Cmd and click
  - Pencil tool: single‑click to create
- Move/resize by dragging the region or its edges; copy/paste with toolbar buttons or shortcuts.
- Delete selected regions from the toolbar delete button.
- Open Piano Roll via the region’s small pencil on the top‑left.

## 9. Piano Roll (MIDI Editing)
- Tools: Select vs Pencil.
- Create notes: double‑click or Ctrl/Cmd+click (Select); single‑click (Pencil).
- Move/resize notes by dragging; box‑select or Shift‑click for multi‑selection.
- NO SNAP menu controls snapping for create/move/resize.
- Quantize using Qua. Pos. (start) and Qua. Len. (length) menus.
- Close with X or ESC.

## 10. Playback and Transport
- Back to beginning; Play/Pause.
- Set playhead by clicking bar numbers in the main grid; in Piano Roll, click the header timeline (respects snapping).
- Edit time/BPM/time signature/key signature via the toolbar readouts.

## 11. Undo/Redo and Clipboard
- Undo/Redo available for tracks, regions, notes, and project properties.
- Copy/Paste works for regions in the main grid and notes in the piano roll.
- Use toolbar buttons or keyboard shortcuts.

## 12. Instruments and Soundfonts
- Instruments are organized by groups (e.g., Piano & Keyboards, Strings, Brass, Woodwind, Percussion Kit, Synthesizer).
- Playback uses high‑quality FluidR3 soundfonts via Tone.Sampler.
- If loading stalls, the overlay will time out; refresh to retry downloading.

## 13. Settings
- General: LLM provider (OpenAI or OpenAI‑compatible), API key, model, soundfont base URL.
- Behavior: chatbox default open at startup.
- Templates: custom instructions for the AI.
- Settings persist in IndexedDB (local); API keys are not persisted on non‑local hosts.

## 14. AI Agent "K.G.Studio Musician Assistant"
- Open the chat (toolbar). Describe goals in natural language (e.g., “Can you help me write a 4‑bar chord progression for the melody?”).
- The agent executes tools to edit your project. Actions are typically scoped to the selected region.
- Slash‑commands:
  - `/clear` — clear chat history
  - `/welcome` — show the welcome message
- Providers: OpenAI or OpenAI‑compatible (e.g., OpenRouter). Due to CORS, some providers are supported via OpenRouter.
 - Reminder: LLM providers differ in data retention and usage policies. Check your provider’s policy and configure keys/models accordingly.

## 15. Keyboard Shortcuts (defaults)
- Global
  - Play/Pause: Space
  - Undo / Redo: Ctrl/Cmd+Z / Ctrl/Cmd+Shift+Z
  - Copy / Cut / Paste: Ctrl/Cmd+C / Ctrl/Cmd+X / Ctrl/Cmd+V
  - Save: Ctrl/Cmd+S
  - Hold to create region: Ctrl/Cmd
- Piano Roll
  - Tools: Select (Q), Pencil (W)
  - Hold to create note: Ctrl/Cmd
  - Snap: 1(None), 2(1/4), 3(1/8), 4(1/16)
  - Quantize Position: 5(1/4), 6(1/8), 7(1/16)
  - Quantize Length: 8(1/4), 9(1/8), 0(1/16)

## 16. Troubleshooting
- No sound: ensure soundfonts can download; check network; try refreshing.
- Chat/LLM errors: verify provider, base URL (if compatible), API key, and model name; check CORS if using third‑party gateways.
- MIDI import: only valid `.mid/.midi` files; malformed files will show an error.
- Performance: close unused panels; reduce concurrent soundfont loads.

## 17. FAQ
- Where are my projects saved? In your browser’s IndexedDB on your device.
- Can I use the app offline? Yes, core editing works offline; instruments and AI need network when first used.
- Does the app send my projects to a server? No. Only your LLM requests go to your chosen provider.

## 18. Glossary
- Project, Track, Region, Note, Snapping, Quantize, General MIDI (GM), IndexedDB, Soundfont, LLM.

## 19. Known Limitations
- Limited note editing (no velocity editing yet)
- No region duplication shortcut
- Export UI present; audio export not implemented
- No audio recording yet; limited effects processing
- No project browser UI (load by name)

## 20. Credits and Licenses
- Licensed under Apache 2.0 with additional terms (see `LICENSE`).
- Third‑party attributions: FluidR3_GM soundfont, midi‑js‑soundfonts, and prompt structure notes.