# BassMusic.AI — Full LLM & AI Agent Reference Manual

This document provides exhaustive technical specifications, API schemas, model architectures, DSP algorithms, and automation guides for BassMusic.AI.

---

## 1. System Architecture

BassMusic.AI is a zero-backend web application. All computation occurs locally in the user's browser via dedicated Web Workers.

```
+--------------------------------------------------------------------------------+
|                               Browser Main Thread                              |
|  - Angular Reactive UI & State Signals (MusicStateService)                     |
|  - Web Audio API Playback Graph (Parametric EQ, Sub-Bass Shelf, AnalyserNode)  |
|  - Automation Hook (window.bassMusicAI)                                        |
+-------------------+------------------------------------+-----------------------+
                    | (postMessage Transferable Buffers) |
+-------------------v--------------------+   +-----------v-----------------------+
|          Music Worker Thread           |   |           Vocal Worker Thread     |
| - Xenova/musicgen-small (~350MB INT8)  |   | - BricksDisplay/vits-eng (~35MB)  |
| - ONNX Runtime Web (WASM SIMD/WebGPU)  |   | - BricksDisplay/vits-eng-welsh    |
| - Auto-regressive EnCodec generation   |   | - Xenova/mms-tts-eng (16kHz)      |
| - Equal-power seamless loop crossfade  |   | - Multi-track DSP Sidechain Mixer |
+----------------------------------------+   +-----------------------------------+
```

---

## 2. Models & ONNX Checkpoints

| Component | Model Repository | Size | Precision | Sampling Rate | Description |
|---|---|---|---|---|---|
| **Instrumental** | `Xenova/musicgen-small` | ~350MB | INT8 (q8) / FP32 EnCodec | 32,000 Hz | 300M parameter auto-regressive transformer trained on 20k hours of audio. |
| **Vocal MC** | `BricksDisplay/vits-eng` | ~35MB | FP32 ONNX | 22,050 Hz | High-energy punchy male voice delivery for drops and chants. |
| **Vocal Siren** | `BricksDisplay/vits-eng-welsh-female` | ~35MB | FP32 ONNX | 22,050 Hz | Melodic female vocal top-line for intros and breakdowns. |
| **Vocal Host** | `Xenova/mms-tts-eng` | ~35MB | FP32 ONNX | 16,000 Hz | Deep resonant UK/US sound system host voice. |
| **Vocal Cyber** | `BricksDisplay/vits-cmn` | ~35MB | FP32 ONNX | 22,050 Hz | Robotic futuristic cyber vox. |

All models are cached in browser `CacheStorage` via the Cache API, requiring zero downloads after the first execution.

---

## 3. JavaScript Browser Automation API (`window.bassMusicAI`)

AI agents, testing bots, and headless browser scripts can interact directly with the client-side JavaScript runtime through the `window.bassMusicAI` object.

### API Reference

```typescript
interface BassMusicAIAPI {
  version: string;
  getStatus(): {
    isGenerating: boolean;
    generationPhase: 'idle' | 'instrumental' | 'unloading' | 'loading_vocals' | 'vocals' | 'mixing' | 'completed';
    modelStatus: string;
    vocalModelStatus: string;
    vocalPreviewStatus: 'idle' | 'loading' | 'generating' | 'ready' | 'approved' | 'error';
    device: 'webgpu' | 'wasm';
  };
  getPresets(): Array<{ id: string; name: string; genre: string; bpm: number; prompt: string }>;
  selectPreset(presetId: string): void;
  setPrompt(prompt: string): void;
  setBpm(bpm: number): void;
  setDuration(seconds: number): void;
  setMakeLoopable(enabled: boolean, loopBars?: 4 | 8 | 16): void;
  setVocals(options: {
    enabled: boolean;
    lyrics?: string;
    voicePreset?: 'vits_male' | 'vits_female' | 'mms_host' | 'vits_cyber';
    timingMode?: 'intro' | 'pre-drop' | 'chorus' | 'full';
    volume?: number;
    sidechainDb?: number;
    reverbSend?: number;
  }): void;
  previewVocals(options?: { lyrics?: string; voicePreset?: string }): Promise<void>;
  approveVocals(): void;
  clearVocalPreview(): void;
  generate(options?: {
    prompt?: string;
    bpm?: number;
    duration?: number;
    makeLoopable?: boolean;
    vocals?: { enabled: boolean; lyrics: string; voicePreset: string; timingMode: string };
  }): Promise<GeneratedTrack>;
  play(): void;
  pause(): void;
  togglePlay(): void;
  getCurrentTrack(): GeneratedTrack | null;
  getHistory(): GeneratedTrack[];
  downloadCurrentWav(): void;
}
```

### Automation Example (Playwright / Puppeteer / Browser Console)

```javascript
// 1. Configure generation parameters
window.bassMusicAI.setPrompt("150 BPM tearout dubstep, heavy metallic screech bassline, punchy half-time drums");
window.bassMusicAI.setVocals({
  enabled: true,
  lyrics: "Drop the sub bass now!",
  voicePreset: "vits_male",
  timingMode: "pre-drop"
});

// 2. Audition vocals
await window.bassMusicAI.previewVocals();

// 3. Approve and generate track
window.bassMusicAI.approveVocals();
const track = await window.bassMusicAI.generate();
console.log("Track generated:", track.title, track.duration, "seconds");
```

---

## 4. Multi-Stem DSP & Sidechain Ducking Math

The client-side vocal mixer aligns neural voice recordings onto instrumental stems with the following signal processing stages:

1. **Cubic Hermite Resampling**: Interpolates 22,050Hz/16,000Hz vocals to the 32,000Hz instrumental master clock:
   $$p(t) = \frac{1}{2} [ (2y_1) + (-y_0 + y_2)t + (2y_0 - 5y_1 + 4y_2 - y_3)t^2 + (-y_0 + 3y_1 - 3y_2 + y_3)t^3 ]$$
2. **120Hz High-Pass Biquad Filter**: Removes sub-bass rumble to preserve headroom for 808s and reese bass:
   $$\omega_0 = 2\pi \frac{f_c}{f_s}, \quad \alpha = \frac{\sin(\omega_0)}{2Q}$$
3. **Envelope Follower Sidechain Ducking**: Tracks vocal amplitude with 10ms attack and 80ms release, reducing instrumental gain by up to $-12\text{dB}$:
   $$y[n] = \alpha_{\text{attack}} \cdot y[n-1] + (1 - \alpha_{\text{attack}}) \cdot |x[n]|$$
   $$G_{\text{inst}}[n] = 1.0 - \text{Env}[n] \cdot (1.0 - 10^{\frac{\text{duckingDb}}{20}})$$
4. **Soft Limiter (Hyperbolic Tangent)**: Eliminates digital clipping without harsh harmonic distortion:
   $$x_{\text{master}}[n] = \tanh(x_{\text{inst}}[n] \cdot G_{\text{inst}}[n] + x_{\text{vocal}}[n] \cdot V_{\text{gain}})$$

---

## 5. Security & Privacy Guarantees

- **100% Client-Side**: No audio buffers, text prompts, or model telemetry leave the user's device.
- **Strict Content Security Policy (CSP)**: Only connections to `huggingface.co` and `cdn-lfs.huggingface.co` for public ONNX weight downloads are permitted.
- **Isolated Workers**: Model inference runs in sandboxed Web Worker contexts with Transferable ArrayBuffers to prevent memory leaks.