Skip to content

Latest commit

 

History

History
74 lines (63 loc) · 3.82 KB

README.md

File metadata and controls

74 lines (63 loc) · 3.82 KB

Beatrove

Beatrove is a DJ-focused music library manager with an optional vinyl-ingest backend. The browser UI handles all day-to-day crate digging (filters, playlists, waveforms), while an opt-in FastAPI service lets you upload sleeve scans, run OCR, and normalize the metadata with a local LLM.

System Architecture

  • Browser UI (index.html, assets/js/) – Single-page app that loads tracklists, applies search/filter logic, and renders the DJ tooling. Uses npm run serve (Python HTTP server) so no Node backend is required.
  • FastAPI Vinyl API (server/app.py) – Handles /api/v1/records for vinyl intake. Stores records in server/vinyl.db (SQLite) with inline base64 cover images.
  • OCR Pipeline (server/ocr/) – service.py iterates provider strategies (providers.py). The default providers support HTTP-based OCR endpoints and local CLI commands; responses are flattened into plain text via shared utilities (utils.py) so downstream components receive uniform transcripts.
  • Metadata Enrichment (server/metadata/) – Uses strategy objects to interpret OCR transcripts. LLMEnrichmentStrategy prompts your configured LLM endpoint to produce structured record data, while HeuristicEnrichmentStrategy extracts keys/genres/catalog codes deterministically. Additional strategies can be added by implementing EnrichmentStrategy.apply.
  • SQLite Storage (server/vinyl.db) – Persisted records with merged manual fields, LLM-enriched metadata, cover images, and raw OCR payloads for auditing.

Local Development

Prerequisites

  • Node.js 20+
  • Python 3.11+ (with pip)
  • Git

Setup Steps

  1. Clone the repo 
    git clone https://github.com/jcrouthamel/Beatrove.git
cd Beatrove
  2. Install front-end dependencies 
    npm install
  3. Create a Python virtual environment (recommended) 
    python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
  4. Install backend requirements 
    pip install -r server/requirements.txt
  5. Run the static UI 
    npm run serve
    This starts python -m http.server 8000. Visit http://localhost:8000 to work with the client-only features (CSV import, filtering, playlists).
  6. Run the FastAPI service (optional vinyl intake) 
    uvicorn server.app:app --reload --port 9000
    The UI expects the API at http://localhost:9000/api/v1. Set VITE_API_BASE or update your local config if needed.
  7. Configure OCR/LLM (optional) 
    # HTTP OCR endpoint (path defaults to /v1/chat/completions if omitted)
export VINYL_OCR_HTTP_URL="http://127.0.0.1:8089"
export VINYL_OCR_MODEL="nanonets/Nanonets-OCR2-3B"
# or provide a local CLI command that prints plain text to STDOUT
# export VINYL_OCR_COMMAND="python /path/to/ocr.py --image {image}"

export LLM_ENDPOINT="http://127.0.0.1:8088/v1/completions"
export LLM_MODEL="gemma3"
# optional tuning variables: LLM_TEMPERATURE, LLM_TOP_P, LLM_MAX_TOKENS, LLM_TIMEOUT_SECONDS
    Set either VINYL_OCR_HTTP_URL or VINYL_OCR_COMMAND (HTTP is tried first if both exist). The LLM strategy runs only when LLM_ENDPOINT is defined.

Useful Commands

  • make test – Run the Vitest suite (npm test)
  • make python-test – Run Python unit tests (python -m unittest discover)
  • npm run test:watch – Watch mode for the UI tests
  • uvicorn server.app:app --reload – Start the FastAPI vinyl API

Troubleshooting

  • OCR still returns JSON – Ensure your OCR provider obeys the prompt or add a custom adapter in server/ocr/providers.py.
  • LLM not invoked – Confirm LLM_ENDPOINT and LLM_MODEL are set. Without them, only heuristics run.
  • SQLite locked errors – Stop other FastAPI instances or delete server/vinyl.db (after backing up) before restarting.