SONIC FACILITY :: MUSIC ORGANIZATION & PUBLISHING

A full facility for organizing, analyzing, and releasing music. Ingest any audio file, get instant BPM / key / Camelot / mood analysis, auto-organize your library, generate artwork (offline procedural or AI img2img), and ship a complete social + publishing package — all from one dashboard.

IDENT ......... SONIC-02
CLASS ......... MUSIC FACILITY / PUBLISHING PIPELINE
STATUS ........ SHIPPED / ONLINE
PIPELINE ...... INGEST → ANALYZE → ORGANIZE → ART → RELEASE
FREQ .......... BPM · KEY · CAMELOT · MOOD
LINK .......... /sonic-facility

---

// 01 :: SIGNAL

A full facility for organizing, analyzing, and releasing music. Ingest any audio file, get instant BPM / key / Camelot / mood analysis, auto-organize your library, generate artwork (offline procedural or AI img2img), and ship a complete social + publishing package — all from one dashboard.

Screenshots

Dashboard	Library

Image Studio	Social Pack

Procedural artwork (seeded by the track's analysis — no AI needed):

spectrum	orbit	vapor

Quick start

Option A — Standalone exe (recommended)

1. Download SONIC_FACILITY.exe from the latest release.
2. Put it in a folder with config.json (shipped in this repo) and double-click.
3. The dashboard opens automatically at http://127.0.0.1:8765.

The exe also runs the CLI when given a command:

SONIC_FACILITY.exe scan C:\path\to\music
SONIC_FACILITY.exe catalog
SONIC_FACILITY.exe platforms

Option B — From source

.\setup.ps1        # venv + Python deps + Node deps
.\run.ps1          # API (:8765) + Vite dashboard (:5173)

Open http://localhost:5173.

CLI

python -m backend.cli scan [--path ...]           # ingest files into catalog
python -m backend.cli analyze [--id N | --all]    # BPM/key/tone analysis
python -m backend.cli catalog list                # list tracks
python -m backend.cli organize [--apply]          # rename/move per scheme
python -m backend.cli images generate --id N --style spectrum --size 3000
python -m backend.cli images ai --id N --prompt "..."
python -m backend.cli social generate --id N --template drop
python -m backend.cli post soundcloud --id N
python -m backend.cli serve                       # launch API

Pipeline

audio files ──scan──▶ Track row ──analyze──▶ BPM · key · Camelot · tone · mood · LUFS
                                                     │
               ┌─────────────────────────────────────┼──────────────────────────┐
               ▼                                     ▼                          ▼
        Image Studio                      Social Package                 Publishing
        procedural + AI                  captions · hashtags            SoundCloud +
        ──▶ /exports/images              · platform art                 adapter stubs
                                          ──▶ /exports/social            ──▶ platform APIs

• Analysis — librosa pipeline: onset-strength BPM (wrapped to range, IBI confidence), chroma_cqt → Krumhansl-Kessler key detection with Camelot wheel, median-f0 dominant pitch, spectral centroid/rolloff, RMS + BS.1770 LUFS, rule-based mood classifier.
• Imagery — deterministic procedural styles (spectrum / waveform / orbit / flowfield / vapor) seeded by sha256(track_id|title|bpm|tonic|size|style), plus AI img2img where the procedural render seeds the provider. specs.py exports every platform surface.
• Social — 8 caption templates, genre/mood/key hashtag engine, per-platform character limits, content-calendar CSV, ZIP download.
• Publishing — PlatformAdapter ABC + registry; SoundCloud v2 (upload/download/update) is fully wired; YouTube/Bandcamp/IG/TikTok/Spotify/X/Facebook are structured stubs that report exactly which credentials they need (see docs/PLATFORMS.md).

Configuration

Put API keys / tokens in config.json (never commit) — or config.local.json / .env. Any value can be overridden at runtime:

SONIC_PLATFORMS_SOUNDCLOUD_ACCESS_TOKEN=...
SONIC_IMAGES_AI_PROVIDER=stability

Stack

Layer	Tech
Backend	Python 3.14, FastAPI, SQLModel/SQLite, librosa, mutagen, Pillow, typer
Frontend	React 19, Vite 7, TypeScript, Tailwind CSS v4
AI art	Procedural (offline) + OpenAI / Stability / FAL adapters
Publish	Pluggable platform adapters (SoundCloud first-class)

Layout

backend/   FastAPI app, analysis, organizer, image studio, social, platforms
frontend/  React dashboard (Vite)
data/      SQLite catalog (gitignored)
exports/   generated images + social packages
docs/      ARCHITECTURE.md · PLATFORMS.md · USAGE.md · screenshots/
launcher.py  single-file exe entrypoint (PyInstaller)

Building the exe

npm --prefix frontend run build                          # bundle dashboard
.venv\Scripts\python -m pip install pyinstaller
.venv\Scripts\python -m PyInstaller --onefile `
  --name SONIC_FACILITY `
  --add-data "frontend/dist;frontend_dist" `
  --collect-submodules librosa `
  --hidden-import soundfile --hidden-import audioread `
  --hidden-import pyloudnorm --hidden-import soxr `
  launcher.py

The exe resolves config.json, data/, and exports/ relative to its own folder. No arguments = serve + open browser. Any argument = CLI mode.

License

MIT — see LICENSE.