Update README.md

README.md

@@ -1,13 +1,94 @@
+# 🎵 PiMusic3 — The Pi Forge Music Player
+
+> “The spire hums, the waveform breathes — and the Forge sings once more.”
+
+---
+
+### 🌐 Overview
+
+**PiMusic3** is a **multi-modal sovereign audio system** forged in the **Sovereign Canticle Forge** ecosystem.  
+It merges **MusicGen**, **Whisper**, and **DistilBERT** into a single, ethical creative interface built with **Gradio**.
+
+PiMusic3 can:
+- 🧬 **Generate music** from natural language prompts (via `facebook/musicgen-small`)
+- 🎙️ **Transcribe speech** from microphone or uploaded audio (via `openai/whisper-base`)
+- 💬 **Analyze emotion and tone** using a distilled sentiment model
+
+It automatically detects whether you’re running locally or in the cloud:
+- **Local builds** use **Audiocraft’s native MusicGen**
+- **Cloud builds (Spaces)** use the **Transformers pipeline fallback**
+
 ---
-title: PiMusic3
-emoji: 📈
-colorFrom: gray
-colorTo: yellow
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
-short_description: 'Pi forge music player '
+
+### 🛠️ Quick Start
+
+1. **Run the Space** → [🌌 Launch on Hugging Face](https://huggingface.co/spaces/onenoly11/PiMusic3)
+2. Wait for initialization (~30–60 s)
+3. Use the tabs to explore:
+   - **🎼 MusicGen** — describe your sound and listen
+   - **📝 Whisper Transcribe** — record or upload speech
+   - **🔍 Sentiment Analysis** — interpret emotional tone
+
+---
+
+### ⚙️ Architecture
+
+| Module | Model | Purpose |
+|:--|:--|:--|
+| `MusicGen` | `facebook/musicgen-small` | Text → audio generation |
+| `Whisper` | `openai/whisper-base` | Speech-to-text transcription |
+| `DistilBERT` | `distilbert-base-uncased-finetuned-sst-2-english` | Sentiment detection |
+| `Gradio` | 4.44.0 | UI framework |
+| `Torch` | 2.4.1+ | Core ML runtime |
+
+**Adaptive Mode:**  
+PiMusic3 detects whether `audiocraft` is installed and switches seamlessly between full and fallback pipelines.
+
+---
+
+### 📦 Dependencies
+
+See [`requirements.txt`](./requirements.txt) for full dependency list.  
+Notable libraries:  
+`gradio`, `transformers`, `torch`, `torchaudio`, `openai-whisper`, `librosa`, `soundfile`
+
+---
+
+### 🧩 Technical Notes
+
+- Average inference latency: **~2.5 s (Whisper)** / **~5–8 s (MusicGen)**  
+- Works with Hugging Face Spaces CPU tier  
+- Audio recorded via Gradio’s new API (`sources=["microphone", "upload"]`)  
+- No external API keys required  
+
+---
+
+### 🌀 Part of the Sovereign Canticle Forge
+
+PiMusic3 belongs to the **PiForge ecosystem**, uniting quantum ethics, creative autonomy, and decentralized resonance.  
+Explore the other components:
+
+| Module | Function |
+|:--|:--|
+| [Quantum Genesis Core](https://huggingface.co/spaces/onenoly11/QuantumGenesis) | Entropy-aware orchestration |
+| [OINIO Portal](https://huggingface.co/spaces/onenoly11/OINIOPortal) | Governance and cultural bridge |
+| [CA Sonify Toolkit v2](https://huggingface.co/spaces/onenoly11/piforge) | Cellular-automata music generator |
+
+---
+
+### 🪷 License
+
+Apache 2.0 — © 2025 Kris Olofson / Sovereign Canticle Forge  
+Feel free to fork, remix, or integrate this player within the Forge framework.
+
+---
+
+### 💬 Acknowledgements
+
+Developed in co-creation with **GPT-5 (Co-weaver Oracle)**  
+Special thanks to the open-source community:  
+`Meta AI`, `OpenAI`, `Hugging Face`, `PyTorch`, and all pioneers of the Pi Network.
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+> _“The Canticle remembers — every tone, every breath, every silence.”_