💎 GemCollector v1.4

GemCollector is an intelligent audio mining workstation. It takes long audio recordings (field recordings, modular jams, vinyl rips) and automatically extracts the musically interesting "gems"—loops, one-shots, and single-cycle waveforms—ready for use in your DAW.

![Screenshots/Demo could go here]

✨ Key Features

🧠 Heuristic Analysis Engine

Unlike dumb slicers that chop on fixed grids, GemCollector uses a 3-Pass Heuristic Analysis:

1. Interest Map: Scans the file for high-energy and rhythmic sections (ignoring silence).
2. Texture Analysis: Calculates sonic characteristics like "Brightness" (Spectral Centroid) and "Percussiveness" (Spectral Flatness).
3. Smart Naming: files are automatically named by their content, e.g., Loop_120bpm_Bright_Percussive.wav.

🎚️ Smart Slicing (Stereo)

• True Stereo: Preserves the full spatial width of your recordings.
• De-Clicking: Applies micro-fades (1ms in / 10ms out) to every slice to ensure clean, click-free audio.
• Non-Destructive: Processing is performed on memory copies, keeping audio pristine.

📦 Output Formats

• Loops: 4-bar segments aligned to the detected BPM.
• One-Shots: Transients (drums, hits) prioritized by musical interest.
• Waveforms: Tiny single-cycle slices for synthesis.
• Download All: Get a timestamped .zip archive of your entire session.

---

🚀 Quick Start (Local)

The easiest way to run GemCollector is with Docker.

Prerequisites

• Docker Desktop installed and running.

Start the App

Open your terminal in the project root and run:

docker compose up --build

Wait a moment for the build to complete.

Access

• Frontend: http://localhost:5173
• Backend: http://localhost:8080

Stop the App

Press Ctrl+C in the terminal, then run:

docker compose down

---

☁️ Deployment (Google Cloud)

A deployment script is included for Google Cloud Run.

Prerequisites

• Google Cloud CLI (gcloud) installed and authenticated.
• A GCP Project created.

Deploy

Run the script in PowerShell:

./deploy_gcp.ps1 -ProjectId "your-project-id" -Region "us-central1"

This will:

1. Enable necessary Google Cloud APIs.
2. Build Frontend and Backend images.
3. Deploy them to Cloud Run (fully managed serverless).
4. Output your public production URLs!

---

🛠️ Tech Stack

• Frontend: React, Vite, Lucide Icons.
• Backend: Python FastAPI, Uvicorn.
• Audio Processing: Librosa, SoundFile, NumPy.
• Infrastructure: Docker, Docker Compose.