README.md

metadata

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:

# 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