K.G.One/README.md

K.G.One Music Studio

AI-native music creation. Compose, generate, and produce — right in your browser.

---

What is K.G.One Music Studio?

K.G.One Music Studio is an AI-powered music production platform — think Cursor, but for making music. It pairs K.G.Studio, a lightweight browser-based DAW, with K.G.One, a local AI backend that brings real generative AI capabilities to your workflow.

No heavy software to install. Open K.G.Studio in any modern browser, point it at your K.G.One server, and you can generate full songs from text, produce MIDI clips and WAV loops, or strip apart any track into clean stems — all without leaving the browser.

K.G.Studio ships with a built-in AI Musician Assistant for harmony, arrangement, and note editing through natural conversation. K.G.One extends the DAW with a dedicated K.G.One Music Generator panel — GPU-accelerated tools for generating full songs, producing MIDI clips, and separating stems, all accessible directly from the browser interface.

Both K.G.Studio and K.G.One are built by the same author.

---

Components

	Component	Capabilities
	K.G.Studio	Browser-based DAW — compose, edit, and produce in any modern browser
	ACE-Step 1.5	Generate full-length songs from text prompts
	Foundation-1	Generate instrument clips and MIDI loops from text
	python-audio-separator	Separate any audio into vocals, instrumental, and more

Note: All AI models require a GPU. Only one model can be active at a time — you switch explicitly via POST /v1/models/load.

---

How It Works

K.G.Studio runs entirely in the browser — it stores your projects locally and never requires a server to use as a standalone DAW. When you connect it to K.G.One, the K.G.One Music Generator panel unlocks inside K.G.Studio, letting you generate full songs, produce MIDI clips, and separate stems without leaving your session.

K.G.One manages a single NVIDIA GPU across all three AI services. When you switch models via the API, the active service is shut down before the next one loads. This keeps VRAM clean and prevents conflicts between the very different dependency stacks each model requires.

---

Requirements

Requirement	Notes
Windows 10/11 or Linux	Use init.bat on Windows, init.sh on Linux
NVIDIA GPU	CUDA required for all AI models
Git	For cloning sub-projects
uv	Python environment manager
nvm (Windows / Linux)	Node.js version manager (for building K.G.Studio)
jq	JSON parser — Linux only (e.g. sudo apt install jq)
Python 3.10	Required by Foundation-1; ACE-Step works with 3.10+

---

Setup

1. Initialize

Run the init script from the project root. It will:

1. Read pinned commit hashes and URLs from submodules.json
2. Clone (or update) ACE-Step 1.5 → ace-step/
3. Clone (or update) Foundation-1 → foundation1/
4. Clone (or update) python-audio-separator → separator/
5. Clone (or update) K.G.Studio, install Node dependencies, and build the SPA → kgstudio/dist/
6. Clone (or update) soundfonts → soundfonts/
7. Create four isolated Python environments:
   • .venv — K.G.One server (fastapi, httpx)
   • ace-step/.venv — ACE-Step and its CUDA dependencies
   • foundation1/.venv — Foundation-1 (Python 3.10, scipy==1.8.1)
   • separator/.venv — python-audio-separator (GPU)
8. Create output and upload directories
9. Download ACE-Step and Foundation-1 model weights

Windows:

init.bat

Linux:

./init.sh

Note: The first run downloads large runtime packages and model weights (several GB total). How long it takes depends on your network speed and machine — subsequent runs skip already-completed steps.

To use a local Foundation-1 checkpoint instead of downloading from HuggingFace:

Windows:

set FOUNDATION1_CKPT_PATH=C:\path\to\foundation1.safetensors
set FOUNDATION1_CONFIG_PATH=C:\path\to\model_config.json

Linux:

export FOUNDATION1_CKPT_PATH=/path/to/foundation1.safetensors
export FOUNDATION1_CONFIG_PATH=/path/to/model_config.json

2. Start K.G.One Music Studio

Windows:

uv run .\main.py

Linux:

uv run ./main.py

The server starts on http://localhost:8000 and automatically opens K.G.Studio in your browser.

To allow access from other devices on your network:

uv run ./main.py --host 0.0.0.0
uv run ./main.py --host 0.0.0.0 --port 8080

Upgrading a pinned dependency

Edit the commit field in submodules.json, delete the corresponding subfolder, then re-run init.bat (Windows) or ./init.sh (Linux).

---

Using K.G.One Music Studio

K.G.Studio is the recommended way to use K.G.One Music Studio. It opens automatically in your browser when the server starts and covers every capability through a visual interface.

K.G.One Music Generator panel (requires K.G.One server):

• Generate a full song — describe the mood, genre, and style; get back a full-length audio track
• Generate MIDI clips + WAV loops — produce instrument loops that land directly on your tracks, ready to edit in the piano roll
• Separate stems — split any audio file into vocals, instrumentals, or individual instruments

K.G.Studio Musician Assistant (works standalone, no K.G.One needed):

• Arrange, edit, and compose using the AI chat panel — describe what you want and the assistant makes edits directly in the project

AI generation tools (full song, clip, stem separation) will be integrated into the Musician Assistant in a future release.

First time? Head to K.G.Studio's Quick Start guide to set up the AI assistant, or read the full K.G.Studio User Guide for a complete walkthrough.

---

For Developers

If you want to call the AI features programmatically, integrate K.G.One into your own tooling, or explore what's under the hood:

• API Reference → — full REST API documentation with request/response examples for all endpoints
• Interactive Swagger UI — http://localhost:8000/docs (available while the server is running)

---

Project Structure

K.G.One/
├── submodules.json          # Pinned commits — source of truth for dependency versions
├── init.bat                 # Windows bootstrap script
├── init.sh                  # Linux bootstrap script
├── pyproject.toml           # K.G.One Python project
├── main.py                  # K.G.One FastAPI server (port 8000); serves K.G.Studio at /kgstudio/
├── services/
│   ├── model_manager.py     # GPU mutex — starts/stops AI model subprocesses
│   ├── acestep_client.py    # ACE-Step connection config
│   ├── foundation1_client.py# Foundation-1 connection config
│   └── separator_runner.py  # Runs audio-separator CLI per-request, manages tasks
├── foundation1_server/
│   └── server.py            # Foundation-1 FastAPI wrapper (port 8002)
├── kgstudio/                # K.G.Studio browser DAW — built as a static SPA, served at /kgstudio/
├── ace-step/                # Cloned by init.bat — ACE-Step 1.5 source
├── foundation1/             # Cloned by init.bat — RC-stable-audio-tools source
├── separator/               # Cloned by init.bat — python-audio-separator source + venv
├── soundfonts/              # Cloned by init.bat — soundfont samples for K.G.Studio
├── docs/
│   └── API.md               # Full REST API reference
├── outputs/
│   ├── clip/                # Foundation-1 generated WAV + MIDI files
│   ├── fullsong/            # (reserved for ACE-Step output references)
│   └── separator/           # Separated stem MP3 files
└── uploads/
    └── separator/           # Temporary upload storage (auto-deleted after processing)

---

Contributing

K.G.One Music Studio is an experimental, actively evolving project — contributions are very welcome! Whether you're a developer, musician, or designer, your expertise can make a real difference.

How You Can Help

🎵 Musicians & Music Producers

• Test the platform with real-world music production workflows
• Provide feedback on generation quality and integration with K.G.Studio
• Suggest AI models or features that would improve your creative process
• Help improve prompting guides for ACE-Step and Foundation-1

💻 Developers

• Implement new features from the roadmap
• Fix bugs and improve performance
• Add support for new AI models or stem separation models
• Improve Linux/macOS compatibility
• Work on K.G.Studio's AI Musician Assistant capabilities

🎨 UI/UX Designers

• Improve the K.G.Studio DAW interface and workflows
• Design better visual feedback for generation and separation tasks
• Create more intuitive interactions for AI-assisted music production

Get Involved

• Email: kgstudio@duck.com
• Issues: Browse open issues labeled help wanted or good first issue
• Discussions: Share ideas and feedback in GitHub Discussions

No contribution is too small — from reporting bugs to suggesting new features, every bit of help moves the project forward!

---

License

K.G.One Music Studio is licensed under the Apache License 2.0 with two supplemental conditions:

• No patents — this software may not be used to file or support any patent application in any jurisdiction.
• Attribution — public or commercial deployments must display Powered by K.G.One © 2026 Xiaohan Tian in a prominent location visible to end users.

Third-party component licenses

K.G.One Music Studio integrates or proxies the following projects. If you use the corresponding features, you are responsible for complying with their licenses.

Component	Used for	License	Notes
K.G.Studio	Browser DAW UI	Apache 2.0 + custom terms	Public/commercial use requires displaying Powered by K.G.Studio © 2025 Xiaohan Tian; no patent filing permitted
ACE-Step 1.5	Full-song generation (/v1/fullsong/*)	MIT	Permissive — attribution required
stable-audio-open-1.0	Clip generation (/v1/clip/*) via Foundation-1	Stability AI Community License	Non-commercial only. Commercial use requires a separate license from Stability AI — see stability.ai/license
python-audio-separator / UVR5	Stem separation (/v1/separator/*)	MIT	Permissive — attribution required

Note: The clip generation feature is powered by a model released under the Stability AI Community License, which does not permit commercial use. If you intend to use K.G.One Music Studio in a commercial product, you must obtain a commercial license from Stability AI before enabling or exposing the /v1/clip/* endpoints.

See LICENSE for the full terms including third-party notices.