# 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. To opt‑in to persistence on non‑local hosts, enable "Persist API Keys on Non-Localhost" in Settings > General (not recommended for shared/production environments).
- 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, Persist API Keys on Non-Localhost.
- 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 unless you opt‑in via the "Persist API Keys on Non-Localhost" setting (not recommended for shared/production environments).

## 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.
