Sample IQ

Modern sample management platform for beatmakers and producers.

Sample IQ is a local-first workflow application for organizing, previewing, and planning with audio samples. Browse a searchable library, audition waveforms in the browser, build packs, sketch beat ideas on a session board, and surface library insights — backed by a typed React frontend and ASP.NET Core API.

---

Features

Module	Capabilities
Sample Library	Grid and table views, advanced filters, favorites, bulk actions, play counts
Waveform Preview	In-browser auditioning with WaveSurfer.js and neutral unavailable-state handling
Import	Upload .wav, .mp3, .ogg with metadata and reusable preset templates
Pack Builder	Create packs, add/remove samples, preview collections, export JSON manifests
Session Board	Lane-based arrangement, drag-and-drop, BPM/key compatibility scoring, JSON export
Duplicate Detector	Title, metadata signature, and file-size matching with confidence scores
Presets	Saved metadata templates for consistent sample imports
Analytics	Library distribution charts and usage insights with Recharts

---

Tech stack

Layer	Technology
Frontend	React 19, TypeScript, Vite, Tailwind CSS 4, React Router
Audio	WaveSurfer.js
Visualization	Recharts
Backend	ASP.NET Core 9 Web API
Data	SQLite, Entity Framework Core 9
Deployment	Docker, nginx, docker-compose

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│  React SPA (Vite)                                            │
│  Routing · Session state · WaveSurfer playback · localStorage│
└────────────────────────────┬─────────────────────────────────┘
                             │  /api  /uploads  /audio
┌────────────────────────────▼─────────────────────────────────┐
│  ASP.NET Core API                                            │
│  REST controllers · EF Core · static file hosting            │
└────────────────────────────┬─────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
        sampleiq.db (SQLite)     wwwroot/uploads + bundled audio

Domain model: Creators publish Sample Packs with a many-to-many relationship to Samples. Presets provide reusable import metadata templates. Uploaded audio is stored on disk; library metadata lives in SQLite.

Client architecture: Feature pages consume a typed API client. Session board state persists in localStorage. The Vite dev server proxies API, upload, and audio routes to the backend.

---

Screenshots

Home

_{Category browse, trending samples, and quick entry points into the library workflow.}

Sample Library

_{Searchable library with filters, table/grid views, favorites, and inline preview controls.}

Session Board

_{Lane-based beat sketching with drag-and-drop, BPM/key scoring, and session export.}

Pack Builder

_{Assemble curated sample collections and export structured pack manifests.}

Analytics

_{Library distribution, category breakdowns, and usage metrics at a glance.}

Import Workflow

_{Upload audio with metadata fields and apply presets for consistent tagging.}

Presets

_{Reusable metadata templates to accelerate sample intake and organization.}

---

Getting started

Docker (recommended)

Prerequisites: Docker Desktop

git clone https://github.com/tolga-ileri/Sample-IQ.git
cd Sample-IQ
docker compose up --build

Service	URL
Application	http://localhost:3000
API	http://localhost:5280
Health check	http://localhost:5280/health

docker compose down      # stop services
docker compose down -v   # stop and reset database volume

Local development

Prerequisites: Node.js 20+, .NET 9 SDK

Backend

cd backend/SampleIQ.Api
dotnet run

Runs at http://localhost:5280. SQLite database and seed data are created on first launch.

Frontend

cd frontend
npm install
npm run dev

Runs at http://localhost:5173. Vite proxies /api, /uploads, and /audio to the backend.

---

API overview

Samples

Method	Endpoint	Description
GET	/api/samples	List all samples
GET	/api/samples/search	Search with filters
GET	/api/samples/{id}	Get sample by ID
POST	/api/samples/upload	Upload audio and metadata
POST	/api/samples/{id}/favorite	Toggle favorite
POST	/api/samples/{id}/play	Increment play count

Packs

Method	Endpoint	Description
GET	/api/packs	List packs
GET	/api/packs/{id}	Pack with samples
POST	/api/packs	Create pack
PUT	/api/packs/{id}	Update pack
DELETE	/api/packs/{id}	Delete pack
POST	/api/packs/{id}/samples/{sampleId}	Add sample to pack
DELETE	/api/packs/{id}/samples/{sampleId}	Remove sample from pack

Presets

Method	Endpoint	Description
GET	/api/presets	List presets
POST	/api/presets	Create preset
PUT	/api/presets/{id}	Update preset
DELETE	/api/presets/{id}	Delete preset

Other

Method	Endpoint	Description
GET	/api/creators	List creators
GET	/api/analytics	Dashboard analytics
GET	/health	Health check

Search parameters: q, category, genre, mood, bpmMin, bpmMax, musicalKey, licenseType, onlyFavorites, packId, sort

---

Project structure

Sample-IQ/
├── frontend/                 # React + TypeScript + Vite SPA
├── backend/SampleIQ.Api/     # ASP.NET Core Web API
├── README-assets/            # README screenshots
├── scripts/                  # Development utilities
├── docker-compose.yml
├── LICENSE
└── README.md

---

Roadmap

• Cloud sync and multi-device library backup
• Audio fingerprinting for high-confidence duplicate detection
• DAW-oriented export workflows
• Collaborative pack sharing between producers
• AI-assisted tagging and auto-segmentation

---

License

MIT — see LICENSE.