mediahound 0.2.0__tar.gz

mediahound-0.2.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-06-11 — "MediaHound"
+
+Renamed **ReelShelf → MediaHound** and grew from a movie catalog into a **multi-media** catalog
+(movies *and* music).
+
+### Added
+- **Music support** — catalog CDs, vinyl and cassettes. New `media_type` discriminator and a
+  `MusicMeta` model; **MusicBrainz + Cover Art Archive** metadata provider (open, zero-key); keyless
+  **Spotify / Apple Music / YouTube Music** "where-to-listen" links.
+- **Raw-image folder convention** — `RawImages/video/` → movies, `RawImages/audio/` → music; the
+  build routes each photo to the right identify/enrich path by its subfolder, and `init` scaffolds both.
+- **CSV import/export** — `mediahound import catalog.csv` bulk-adds movies & music (no photos
+  needed), optionally enriched online; `mediahound export -o catalog.csv` backs up the catalog.
+- **Frontend** — a **🎬 Movies / 🎵 Music** segmented filter, per-media-type cards (artist / label /
+  tracklist / ♫ listen for music), and music-aware search.
+- Provider factory now routes by media type: `get_metadata_provider(cfg, media_type)`.
+- **`mediahound serve`** — preview the generated site over http (no more file:// fetch limits).
+- **`mediahound serve --admin`** — a localhost-only write API so admin-portal edits save **straight
+  into `data/corrections.json`** (and `seen-overrides.json`) as you make them. No "Export changes →
+  drop file in" step; edits persist immediately and **survive every future build** (the long-standing
+  cause of "my manual title fix reverted on rebuild"). Cross-origin writes are refused; a **↻ Rebuild**
+  button re-bakes the catalog in place. See `mediahound/serve.py` and
+  [docs/EDITING.md](docs/EDITING.md).
+- **Move a title between Movies & Music from the admin screen** — the inline editor now has a
+  🎬 Movie / 🎵 Music selector (with an Artist field and CD/Vinyl/Cassette formats for music).
+  Switching type sets a `media_type` correction, clears the previous type's exclusive fields, and
+  auto-ticks re-query so the next `--online` build re-enriches with the correct provider
+  (movie ↔ music). New `_apply_meta_to_music()`; `_apply_corrections` is now media-type-aware.
+  On the next build the move also **relocates the source cover photo** into the matching
+  `RawImages/video` or `RawImages/audio` folder (idempotent, path-traversal-guarded), so a
+  reclassified title is correct at the source and won't revert if `corrections.json` is cleared.
+- **⬆ Import list (admin screen)** — under `serve --admin`, a new button + `POST /api/import` lets you
+  paste or upload a CSV and bulk-add titles (optionally enriched online), with the site rebuilt in
+  place. Same importer as the CLI: only `title` is required.
+
+### Changed
+- **Filters are now media-type-aware** — the Format / Genre / Studio·Label / Language dropdowns
+  narrow to the active 🎬 Movies or 🎵 Music tab (and show everything under *All*), so you no longer
+  see movie-only formats while browsing music.
+- Rebrand across package, CLI (`mediahound`), JS data global, `localStorage` keys, branding and docs.
+- Default site title/subtitle are media-generic.
+
+### Fixed
+- **“Export changes” now merges** with the site's existing `data/corrections.json` before downloading,
+  so exporting can never silently drop a previously-saved correction (which would make that title
+  revert on the next build).
+- **Format is normalised when a title changes type** — a movie-only format left on a music item
+  (e.g. a CD that was catalogued as a `DVD`) is reset to the new type's default, so the card's format
+  badge and meta line no longer show `DVD` on music (or `CD` on a movie). Applied both in the build
+  and live in the portal.
+
+## [0.1.0] — 2026-06-09
+
+First public release.
+
+### Added
+- **CLI** — `mediahound init <dir>` scaffolds a site; `mediahound build` turns a folder of cover
+  photos into a static catalog. Incremental (only new photos are processed, tracked by sha256).
+- **Offline-first** — builds never touch the network unless `--online` is passed.
+- **Pluggable providers**
+  - Identify: `tesseract` (default, zero-key OCR), `claude` (vision), `ollama` (local).
+  - Metadata: `wikidata` (default, zero-key), `tmdb`, `omdb`.
+  - Where-to-watch via JustWatch (no key); resale estimates with eBay sold-listings links.
+- **Static web app** (vanilla JS, no build step)
+  - Read-only **default view** + password-protected **admin view** (read/write).
+  - Dense, aligned cards: poster, title·year, rating·format·runtime·language, genres, director +
+    cast, studio, where-to-watch, intro hook, estimated resale value.
+  - Clickable genre / person / studio filters; streaming-service filter; adjustable columns;
+    responsive web + mobile.
+  - Multi-photo galleries with ‹ › arrows, click-to-zoom, rotate, and set-default.
+  - Admin: edit name/year/format/studio, mark seen, delete a title or a photo, manual
+    identification (name or discard unidentified covers), and configure the library name, logo,
+    description, shown fields, and default columns.
+  - Edits round-trip through small JSON files (`corrections.json`, `seen-overrides.json`,
+    `view-config.json`, `identify-queue.json`) applied on the next build.
+  - Works from `file://` via an embedded `data/bundle.js`; content-hash cache-busting for updates.
+- **Demo** — `--mock` builds a 10-title sample catalog (real posters hotlinked for illustration;
+  no copyrighted images stored in the repo). Hosted live on GitHub Pages.
+- **Robustness** — metadata caching, soft-failing providers, and a plausible-title guard that
+  rejects fuzzy mismatches so they can't corrupt your data.
+- **Docs & CI** — README, ARCHITECTURE, DEPLOYMENT (with free-hosting options), SECURITY,
+  CONTRIBUTING; GitHub Actions CI (tests + mock build + `pip-audit`); Dependabot.
+
+### Security
+- All rendered data is HTML-escaped; links are restricted to `http(s)` / site-relative URLs.
+- Photo-rotation corrections are guarded against path traversal; poster downloads are `http(s)`-only.
+- Secrets live only in a gitignored `.env`; only the admin password **hash** is published. The admin
+  gate is a convenience control, not server-side auth (see [SECURITY.md](SECURITY.md)).
+
+[0.2.0]: https://github.com/jchirayath/mediahound/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jchirayath/mediahound/releases/tag/v0.1.0

mediahound-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Chirayath
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mediahound-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include mediahound/web *
+include mediahound/config.example.toml
+include README.md LICENSE CHANGELOG.md

mediahound-0.2.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: mediahound
+Version: 0.2.0
+Summary: Turn photos of your movie & music collection into a sleek, searchable web catalog.
+Author: Jacob Chirayath
+License: MIT
+Project-URL: Homepage, https://github.com/jchirayath/mediahound
+Project-URL: Source, https://github.com/jchirayath/mediahound
+Project-URL: Demo, https://jchirayath.github.io/mediahound/
+Project-URL: Issues, https://github.com/jchirayath/mediahound/issues
+Project-URL: Changelog, https://github.com/jchirayath/mediahound/blob/main/CHANGELOG.md
+Keywords: dvd,vhs,movies,catalog,collection,ocr,tmdb,wikidata
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: Pillow>=9.0
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == "ocr"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# 🎬🎵 MediaHound
+
+[![CI](https://github.com/jchirayath/mediahound/actions/workflows/ci.yml/badge.svg)](https://github.com/jchirayath/mediahound/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/jchirayath/mediahound/actions/workflows/codeql.yml/badge.svg)](https://github.com/jchirayath/mediahound/actions/workflows/codeql.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
+[![Live demo](https://img.shields.io/badge/live-demo-ff5252.svg)](https://jchirayath.github.io/mediahound/)
+
+**Turn photos of your movie *and* music collection into a sleek, searchable web catalog.**
+
+Point MediaHound at a folder of cover photos — DVDs, VHS, Blu-ray, **CDs, vinyl, cassettes** — or
+**import a CSV**. It identifies each item, pulls in cover art, genres, cast/artist, studio/label,
+runtime/tracklist and ratings, writes a short enticing intro, estimates the used resale value, links
+where to **watch** (movies) or **listen** (music), and generates a polished static website you can
+search, filter by **🎬 Movies / 🎵 Music**, sort, and curate — with a password-protected admin mode.
+
+Movies are identified/enriched via TMDB / OMDb / Wikidata + JustWatch; music via **MusicBrainz +
+Cover Art Archive** (open, zero-key) with keyless Spotify / Apple Music / YouTube Music links.
+
+**▶ [Live demo](https://jchirayath.github.io/mediahound/)** — explore a sample catalog in your browser (admin password: `changeme`).
+
+[![MediaHound screenshot](docs/screenshot.jpg)](https://jchirayath.github.io/mediahound/)
+
+> ℹ️ The demo shows **real movie posters and album covers** (hotlinked from IMDb/OMDb and Cover Art
+> Archive / Apple) so you can see what a finished catalog looks like — no cover images are stored in
+> this repo. Extra gallery photos are generated placeholders standing in for *your own* photos. Your
+> real catalog pulls art from TMDB / OMDb / Wikidata (movies) and MusicBrainz / Cover Art Archive
+> (music), or falls back to the photos you take.
+
+- **Runs for anybody with zero API keys** — open-source OCR + open data by default.
+- **Offline-first** — never contacts the internet unless you explicitly ask (`--online`).
+- **Static output** — deploy anywhere (Netlify, GitHub Pages, S3, Vercel) or just open the HTML file.
+- **No secrets in the repo** — keys live in a gitignored `.env`; your catalog is generated output.
+
+> MIT-licensed. Your photos, keys and catalog never get committed to this tool's repo.
+
+---
+
+## See it in 30 seconds (no photos, no keys)
+
+```bash
+git clone https://github.com/jchirayath/mediahound && cd mediahound
+pip install -e .
+
+mediahound init demo
+mediahound build --config demo/config.toml --mock   # generates a 10-title sample catalog
+cd demo && python3 -m http.server 8000              # open http://localhost:8000
+```
+
+That's the screenshot above. Click **🔒 Admin** and sign in with **`changeme`** to try the
+read/write admin tools. Everything you see is generated by `--mock` — no internet, no API keys.
+
+> Once published to PyPI you can skip the clone and just `pip install mediahound` (then
+> `mediahound init …`). Maintainers: see [RELEASING.md](RELEASING.md) for the one-time publish setup.
+
+---
+
+## Cataloguing your own collection
+
+```bash
+pip install -e ".[ocr]"     # adds the default OCR identifier
+# Install the Tesseract engine for OCR:
+#   macOS:  brew install tesseract
+#   Debian: sudo apt-get install tesseract-ocr
+
+mediahound init mysite      # scaffolds mysite/ (RawImages/{video,audio}/, config.toml, web template)
+
+# Sort your cover photos by media type:
+cp ~/Pictures/dvd-covers/*.jpg   mysite/RawImages/video/    # 🎬 movies (DVD/VHS/Blu-ray/LaserDisc)
+cp ~/Pictures/album-covers/*.jpg mysite/RawImages/audio/    # 🎵 music  (CD/vinyl/cassette)
+
+mediahound build --config mysite/config.toml --online   # identify + enrich (see Providers below)
+cd mysite && python3 -m http.server 8000
+```
+
+#### Raw-image folder convention
+
+Photos are sorted into **media-type subfolders** so MediaHound knows how to identify each item:
+
+| Folder | Media type | Identified/enriched via |
+|---|---|---|
+| `RawImages/video/` | 🎬 movies | TMDB / OMDb / Wikidata + JustWatch |
+| `RawImages/audio/` | 🎵 music | MusicBrainz + Cover Art Archive + listen links |
+| `RawImages/` (root) | defaults to movies | — |
+
+(`movies/` and `music/` are accepted aliases.) Add more photos anytime and re-run `build` — only the
+**new** ones are processed (state is tracked by content hash in `data/manifest.json`).
+
+### Or import from a CSV (no photos)
+
+```bash
+mediahound import catalog.csv --config mysite/config.toml          # add rows offline
+mediahound import catalog.csv --config mysite/config.toml --online # …and fetch cover art + metadata
+mediahound export --config mysite/config.toml -o backup.csv        # dump the whole catalog back to CSV
+```
+
+Columns (case-insensitive; extras ignored): `media_type, title, artist, director, year, format,
+label, studio, genres, rating, barcode, cover_url, intro`. **Only `title` is required** — any missing
+fields are left blank (or filled by `--online`); even a one-column list of titles works. `media_type`
+is inferred (`music` if an `artist` is given, else `movie`). See
+[`examples/sample-import.csv`](examples/sample-import.csv).
+
+Prefer a UI? Under **`mediahound serve --admin`** the admin screen has an **⬆ Import list** button —
+paste or upload the same CSV, optionally tick *enrich online*, and the titles are added and the site
+rebuilt in place.
+
+---
+
+## Features
+
+### The catalog
+- **Search** title / genre / cast / studio / intro, **sort** by title, year, recently-added, value or rating.
+- **Filters**: format, genre, studio, **streaming service**, language, category, seen / unseen.
+- **Dense, aligned cards** showing poster, title·year, ★rating · format · runtime · language,
+  genres, director + cast, studio, where-to-watch, intro hook, and estimated resale value.
+- **Clickable everything**: a genre, person, or studio filters the grid to matching titles.
+- **Adjustable density** — viewers pick how many movies per row; responsive on web & mobile.
+
+### Photos
+- **Multi-photo galleries** — flip through every photo of a title with ‹ › arrows.
+- **Click-to-zoom** lightbox; set any photo as the default; rotate photos (baked in on rebuild).
+- Auto-uprights sideways/landscape cover photos to portrait.
+
+### Where to watch & resale
+- **Where to watch** — is it on Netflix / Amazon Prime / Hulu? A clickable ▶ badge + pills link
+  straight to the title (via JustWatch, no key). A filter narrows to a specific service.
+- **Resale value** — a heuristic estimate plus a live link to eBay sold/completed listings.
+
+### Two views
+- **Default view** — public, read-only.
+- **Admin view** — password-protected, read/write. Edit a title's name, year, format, studio &
+  distributor; **move a title between 🎬 Movies and 🎵 Music**; mark seen; rotate / set-default /
+  delete a photo; delete a title; and configure the **library name, description, logo, which fields
+  are shown, and default columns**.
+
+### Editing & persisting your changes
+
+Your edits are recorded as small **corrections** (keyed by title id). There are two ways to make
+them permanent so they **survive every future `mediahound build`** — pick one:
+
+**A. Live admin server (recommended — zero manual steps)**
+
+```bash
+mediahound serve --admin          # serves the site at http://127.0.0.1:8765
+```
+
+Open the site, unlock admin, and edit. Every change is written **straight into
+`data/corrections.json`** (and `seen-overrides.json`) as you go — the badge shows
+*“✓ Saved to disk.”* Click **↻ Rebuild** to re-bake the catalog and reload. Because the edit is
+already in `data/`, the next `mediahound build` (and any re-query) keeps it — **edits never revert.**
+The write API is **localhost-only** and refuses cross-origin requests; never expose it publicly.
+
+**B. Static export (for read-only/CDN hosting like Netlify or GitHub Pages)**
+
+When the site is served as plain files (no admin server), edits live in your browser. Click
+**Export changes** / **Export seen** — the download is **merged with the site's existing
+`data/corrections.json`** so nothing already saved is lost — then drop the file into `data/` and run
+`mediahound build`.
+
+> Either way the source of truth is `data/corrections.json`. A title you fix only in the browser
+> (without server-admin or an export) shows locally but **reverts on the next rebuild**, because the
+> build regenerates the catalog from `data/`.
+
+### Manual identification
+- Covers that couldn't be read are grouped on `identify.html`, where you **name** them (queued for
+  discovery on the next online build) or **discard** them (e.g. blank tapes).
+
+---
+
+## How it compares
+
+Most movie-collection tools add items by **barcode scan or manual entry** and keep your catalog in
+**their cloud** or a dated desktop app. MediaHound is the only one that identifies titles from
+**photos of the covers** and generates a **modern static website you own and host for free** —
+offline-first and open-source. It's also one of the few that handles **VHS** (which usually has no
+scannable barcode in the disc databases others rely on).
+
+| | MediaHound | CLZ / Libib | Tellico / GCstar | Plex / Jellyfin |
+|---|---|---|---|---|
+| Add by **photo of cover** | ✅ OCR/AI | ❌ barcode/manual | ❌ search/manual | ❌ scans video files |
+| Modern **website you host free** | ✅ | ❌ their cloud | ◻︎ dated HTML export | ❌ private server |
+| Open-source / offline / no account | ✅ | ❌ | ✅ desktop | ✅ (Jellyfin) |
+| For a **physical** shelf | ✅ | ✅ | ✅ | ❌ digital files |
+
+See **[COMPARISON.md](COMPARISON.md)** for the full, honest analysis — including when a barcode app
+(CLZ/Libib), an OSS desktop cataloger (Tellico/Data Crow), or a media server (Plex/Jellyfin) is the
+better choice.
+
+---
+
+## Providers (how titles get identified & enriched)
+
+Both paths are first-class — pick them per-site in `config.toml`. The default needs **zero keys**.
+
+| Concern | Default (no key) | Optional upgrade |
+|---|---|---|
+| **Identify** title from a cover | `tesseract` — open-source OCR | `claude` (Anthropic vision, also writes the intro) · `ollama` (local model) |
+| **Movie** metadata + poster | `wikidata` — Wikidata + Wikipedia + Wikimedia | `tmdb` (free key) · `omdb` (free key) |
+| **Music** metadata + cover art | `musicbrainz` — MusicBrainz + Cover Art Archive | `discogs` *(planned)* |
+| **Where to watch / listen** | `justwatch` (movies) · keyless Spotify/Apple/YouTube search (music) | Spotify / Apple Music keys *(planned)* |
+| **Resale** | eBay sold-listings link + estimate | Discogs price *(planned, music)* |
+
+Switch to a premium provider in `config.toml`:
+
+```toml
+[identify]
+provider = "claude"      # needs ANTHROPIC_API_KEY
+[metadata]
+provider = "tmdb"        # needs TMDB_API_KEY (or use "omdb" + OMDB_API_KEY)
+```
+
+…and create a **gitignored** `.env` next to `config.toml`:
+
+```
+ANTHROPIC_API_KEY=sk-ant-...
+TMDB_API_KEY=...
+```
+
+Robustness built in: results are cached (`data/.metadata-cache.json`) so rebuilds never re-hit a
+rate-limited free key, providers fail soft (a bad lookup never drops a title), and a fuzzy match
+that returns the wrong film is rejected so it can't corrupt your names.
+
+---
+
+## Offline by default
+
+`mediahound build` is **offline** — it regenerates the site from existing data and never contacts
+the internet. Add `--online` to allow identification / metadata / where-to-watch lookups:
+
+```bash
+mediahound build --config mysite/config.toml              # offline: just rebuild the site
+mediahound build --config mysite/config.toml --online     # online: identify + enrich new titles
+mediahound build --config mysite/config.toml --online --refresh-streaming   # also re-check where-to-watch
+```
+
+Useful flags: `--mock` (demo data), `--force` (reprocess everything), `--limit N`, `--reidentify <sha256>`.
+
+---
+
+## Deploy
+
+The generated site folder (`mysite/`) is plain static files (`index.html`, `identify.html`,
+`assets/`, `data/`, `posters/`, `originals/`). It's just static files, so you can **host it free**
+on **GitHub Pages, Cloudflare Pages, Netlify, Vercel, Render, or Surge.sh** — no server, database,
+or build step required. Quickest:
+
+```bash
+cd mysite && npx netlify deploy --prod          # Netlify
+cd mysite && npx wrangler pages deploy .         # Cloudflare Pages
+cd mysite && npx surge .                         # Surge.sh
+```
+
+See **[DEPLOYMENT.md](DEPLOYMENT.md)** for the full free-hosting comparison plus GitHub Pages, Vercel
+and S3 instructions. The live demo above is itself hosted free on GitHub Pages via a workflow.
+
+It even works by **double-clicking `index.html`** — the build embeds the catalog in `data/bundle.js`
+so it loads without a web server.
+
+---
+
+## Architecture
+
+See **[ARCHITECTURE.md](ARCHITECTURE.md)** for the full picture. In short:
+
+```
+RawImages/*.jpg ─▶ identify (OCR / vision) ─▶ enrich (poster, genres, cast, studio, rating)
+                                                    │
+                          confidence too low? ──────┴─▶ data/unidentified.json → identify.html
+                                                    ▼
+   + intro + resale + where-to-watch ─▶ data/collection.json ─▶ static site (index.html)
+```
+
+Python CLI (`mediahound/`) builds the data; a dependency-free vanilla-JS frontend (`mediahound/web/`) renders it.
+
+---
+
+## Attribution & licensing
+
+- Code: **MIT** (see [LICENSE](LICENSE)).
+- Default data: **Wikidata** (CC0), **Wikipedia** text (CC BY-SA), images via **Wikimedia Commons**.
+- If you enable **TMDB**: uses the TMDB API but is not endorsed or certified by TMDB.
+- Where-to-watch data via **JustWatch**; resale links to **eBay** sold listings (estimates are heuristics).
+
+## Security
+
+MediaHound output is a **static site** — read-only to everyone, with no server to attack. The admin
+password is a convenience gate, **not** an access-control boundary (the published catalog can't be
+changed without rebuilding + redeploying). API keys stay in a gitignored `.env`; only the password
+hash ships. All rendered data is HTML-escaped and links are scheme-restricted. See
+**[SECURITY.md](SECURITY.md)** for the full threat model and reporting instructions.
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).