VinylCat is a self-hosted web application for cataloguing vinyl record collections.
It combines Discogs integration, cover-image + barcode recognition, and full manual entry — with a clean Bootstrap UI and multi-collection support.
Designed for personal use, small groups, and “family/friends sharing” scenarios where you want one place to manage collections without relying on a third-party hosted service.
- Each user can own one or more collections
- Every user always has at least one collection
- Edit collection name after creation
- Deleting a collection deletes all contained records
- Records belong to exactly one collection
- Collection sharing by email (share access with another user if their email is known)
- Add records via:
- Discogs search/import
- Manual entry
- Manual mode supports:
- Artist (required)
- Title (required)
- Year
- Barcode (UPC/EAN)
- Notes
- Structured tracklist editor (title + duration)
- Full editing after creation
- Upload cover images (front/back)
- OCR + barcode recognition can extract:
- Artist, Title, Year, Barcode
- Designed to help in both Discogs and Manual flows
(Real-world barcode reliability varies with lighting/sharpness; see notes in Timeline.)
- Mobile barcode scanning flow integrated in the “Add record” experience (camera-based UX)
- Improved control over scanning behavior (avoid auto-submit, more predictable open/close flow)
- Improved record browsing with sorting options (e.g., artist ascending, etc.)
- Discogs import/search logic improvements:
- Better handling of large result sets
- Country/market filtering support to narrow results (where applicable)
- Registration with email activation
- Account must be activated before login
- Per-user Discogs tokens
- Strong ownership isolation
- Password reset (lost password → email link → set a new password)
- Bootstrap UI
- Theme support (Bootswatch-based light & dark)
- Preferences saved per user
- Gallery-style image viewing on top of record pages (overlay), with “open image in new tab”
- A refreshed stats page with improved layout and visual components
- Translation handling improved: defaults gracefully to English if keys are missing
- Google Analytics support with consent flow (where enabled)
- “Buy me a coffee” button can be embedded and styled to work across themes
- Backend: FastAPI (Python 3.11)
- Frontend: Jinja2 + Bootstrap
- ORM: SQLAlchemy
- Databases:
- SQLite (local development)
- PostgreSQL (Docker / production)
- Deployment: Docker / Docker Compose
| Environment | Database |
|---|---|
| Local dev | SQLite |
| Docker Compose | PostgreSQL |
| Production | PostgreSQL (recommended) |
- Docker + Docker Compose (recommended)
or - Python 3.11+
git clone https://github.com/yourname/vinylcat.git
cd vinylcatcp .env.example .envdocker compose up -d --buildVinylCat uses Discogs for search/import. You’ll need to configure Discogs API details and/or per-user tokens depending on your setup.
Results depend heavily on photo quality:
- take sharp photos
- avoid glare
- ensure barcode area is readable and not curved/blurred
If you experience poor barcode detection, try a closer crop or improved lighting.
This section is a “living changelog” capturing the main improvements added after the initial baseline README.
- Added collection name editing (rename collections after creation)
- Added collection sharing by email (share access between users)
- Added/expanded sorting options (e.g., default fetch based on artist ascending)
- General UX improvements around record lists and navigation
- Added country/market filtering support to reduce irrelevant results
- Worked on improving logic where Discogs API results may miss known releases even when increasing result counts
- Implemented a mobile-friendly barcode scanning flow in the Add Record page
- Improved scan behavior (avoid unwanted auto-submit; increased reliability when closing/reopening scanner)
- Added a gallery overlay on record pages:
- clicking a photo opens an overlay gallery on top of the record page
- clicking the image in the gallery can open it in a new tab
- Improved stats UI with more “dashboard-like” components
- Translation handling improved (fallback to English if keys are missing)
- Added password reset flow (lost password recovery via email link)
- Added Google Analytics consent support (when enabled)
- Embedded Buy Me a Coffee button with improvements for theme awareness and styling consistency
- Tested OCR + barcode extraction on real photos; found that OCR-only approaches can fail on barcodes in difficult images
- Adjustments and iterations were made to improve reliability, but photo quality remains a key factor
- Smarter Discogs matching (hybrid: web search → candidate list → Discogs refine)
- Duplicate explorer / accordion-style components for top artists/labels
- Improved barcode pipeline (better preprocessing; optional external barcode service fallback)
- More sharing controls (read-only vs edit access)
Private / internal use