README.md

---
title: StemToMIDI
emoji: 🎹
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# StemToMIDI Workspace

A professional-grade, high-fidelity browser workstation for Separating Auditory Stems, extracting pitch arrays, and compiling standard MIDI files. It features state-of-the-art client-side digital signal processing (DSP), advanced spectral filtering, and AI Music Transcription powered by **Gemini 3.5 Flash**.

This application is built for direct, single-click deployment to **Hugging Face Spaces** as a Docker SDK container.

---

## 🚀 Hugging Face Space Quick Start

### 1. Host on Hugging Face
To deploy this workspace directly onto Hugging Face Spaces:
1. Create a new Space in your Hugging Face account.
2. Select **Docker** as the SDK.
3. Choose the **Blank** template (default).
4. Commit/Push these workspace files into the repository. Hugging Face will automatically read the `Dockerfile` and `README.md` to trigger a container build.

### 2. Configure Your API Keys
This workstation requires a Gemini API Key to run model-guided pitch detection:
1. Retrieve your API Key from the Google AI Studio console.
2. Inside your Hugging Face Space, navigate to **Settings** > **Variables and Secrets**.
3. Create a new secret called:
   - **Key:** `GEMINI_API_KEY`
   - **Value:** *[Your actual API Key string]*
4. Save and restart the Space. The server will automatically connect to transcribing engines securely!

---

## 🛠️ High-Performance Architectural Stack

- **Ambient Cosmic Slate Interface:** Designed for dark, low-fatigue studio conditions with high density indicators, clean typography, responsive menus, and canvas dashboards. 
- **Client-Side Audiophile Resampler:** Prevents bandwidth saturation by downsampling user audio tracks to exact **16000Hz Mono 16-bit PCM WAV** directly in the browser via fast OfflineAudioContext, decreasing network upload weight by up to 90%.
- **Separation Filtering Preset Models:** Employs a Wiener soft-mask harmonic filter framework enabling surgical stem presets (`melodic / piano`, `bass`, `vocal`, `drums / percussive`) before triggering model interpretation.
- **Strict-Schema AMT Engine:** Feeds resampled audio payloads directly into **Gemini 3.5 Flash** with precise object schemas, guaranteeing immediate, structured JSON lists of MIDI pitch values, onsets, offsets, and velocity curves.
- **Diagnostic Failure & Report Generator:** An advanced integrated framework that monitors transcription lifecycles, collects secure browser telemetries, formats incidents to markdown/JSON, maintains histories, and enables emails to support.

---

## 💻 Local Workspace Development

To run this workspace locally inside your terminal:

```bash
# 1. Clone your Hugging Face Space or repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/StemToMIDI
cd StemToMIDI

# 2. Install dependencies
npm install

# 3. Add your credentials in a local .env file
echo 'GEMINI_API_KEY="AIzaSyYourKeyHere..."' > .env

# 4. Trigger the local build and start the dev workspace
npm run dev
# -> The application will launch locally at http://localhost:3000
```

---

## 📝 Configuration Manual & Custom DSP Inputs

- **Blend Factor (`0.00` to `1.00`):** Controls the harmonic blend ratio during separation. Higher values isolate musical tones, whereas lower values emphasize acoustic resonance.
- **Spectral Margin (`1.00` to `6.00`):** Sets separation boundary margins. Custom levels block percussion leakage into lead melodic lines.
- **Max Note Count Limit (`200` notes):** Express constraints filter transient background noise, optimizing piano rolls for clean editing inside DAWs.

---

*Developed by Ryan — [buildwhilebleeding.com](https://buildwhilebleeding.com)*