MediaChips
Custom metadata. Deep tags & filters. Visual browsing.
Build the library interface that fits your collection.
Website ·
Download ·
Issues ·
Discord ·
Reddit
MediaChips is an open-source desktop app for local videos, images, audio, and text.
You shape the library: define chips (custom metadata), keep rich tags, filter by anything, and browse with previews and view modes that make the collection readable — not just a folder tree.
> Private. Local. Yours. Nothing is uploaded to the cloud. Inspect the code, extend it with plugins, or self-host on your LAN / NAS.
Why MediaChips?
- Custom chips — ratings, favorites, dates, numbers, nested fields, or whatever schema your collection needs
- Detailed tags — images, synonyms, categories, hierarchy, and full tag pages
- Deep filters — any field or tag combination; save presets and refine until it fits
- Visual previews — storyboards, hover / timeline scrub, inline playback, big preview
- View modes — browser layout (sidebar + grid + inspector), media / tags / folders, cards you can tune
- Stays usable at scale — the same workflow on small libraries and on hundreds of thousands of files
- Windows · macOS · Linux · Docker / NAS
Download
⬇ Download the latest release
macOS Gatekeeper / quarantine notes: INSTALLATION.md.
Docker / Synology / NAS
cp .env.docker.example .env # optional
docker compose up -d
# vinsdoe/mediachips:latest — open http://localhost:12321
# or: docker pull ghcr.io/fupdec/mediachips:latest
Full NAS setup (volumes, PUID/PGID, mounts): DOCKER.md.
Coming from Stash?
Install the Stash import plugin and import from your stash-go.sqlite database.
MediaChips can import scenes, performers, studios, tags, and markers (matched by path / oshash). Galleries, performer images, and some Stash-only structures are not a full 1:1 migrate — then keep organizing with your own chips, filters, and views.
More: mediachips.app · plugin docs in plugins/official/stash/.
Features
Chips & tags
- Built-in and custom chip types (tags, ratings, favorites, bookmarks, text, dates, numbers, colors, …)
- Rich tag profiles — images, countries, nested chips, synonyms
- Chip recipes — installable metadata presets for common setups
- Tag hierarchy, categories, merge tools, virtual folder tags
Filters & search
- Filter by any parameter or tag (including nested fields); exact / negative conditions
- Saved filter presets; sort and group-by controls
- Global search (
/) across names and tags
- Optional CLIP Find scene and on-device face tools
Browse & preview
- Eagle-style browser: tags sidebar, inspector, docked filters
- Hover preview, 3×3 storyboard grids, timeline scrub, inline play
- Media, tags, and folders views; customizable cards and layouts
- Built-in player with timeline markers, chapters, and playlists
Library tools
- Path tags & regex extraction, watched folders, bulk edit
- Duplicate finder (hybrid fingerprint + visual grid)
- Multiple databases, backup & restore, LAN / mobile browser access
- Plugins (Stash, Jellyfin, Plex, Emby, TMDB, Adult scrapers, …)
Community
Chip recipes (metadata schemas): see chip-recipes/.
Build from source
Requirements
- Node.js 18 or newer (LTS recommended)
- npm 9+
- Platform build tools for native modules (
better-sqlite3, ffmpeg-static)
Install
git clone https://github.com/fupdec/mediaChips.git
cd mediaChips
npm install
The ML path tag parser model is downloaded when building distribution packages. Face detection (SCRFD ~16 MB) and recognition (InsightFace R50 ~170 MB) are not bundled — users download them once from Face settings (or automatically on first detect/enroll/match). For local development, run node scripts/compile.mjs scripts && node .scripts-build/download-parser-model.js if you use path-based tag suggestions.
Production (server + browser)
npm run build
npm run server
# open http://localhost:12321
LAN:
npm run server:lan
Development
npm run build
npm run server:dev # terminal 1 — API (nodemon)
npm run dev # terminal 2 — Vite on http://localhost:3000
Copy or edit public/config.json after first server start if you need a LAN IP.
Desktop (Electron)
npm run build
npm run electron
Distribution packages
| Command | Description |
|---|
npm run pack | Unpacked app (release/) |
npm run dist | Installers for the current platform |
npm run dist -- --mac / --win / --linux | Installers for one platform |
npm run portable | Windows portable build |
Publishing a release (maintainers)
Desktop auto-update reads installers from GitHub Releases.
- Bump
version in package.json.
- Move
[Unreleased] in CHANGELOG.md to [X.Y.Z] - YYYY-MM-DD.
- Commit, then tag and push (
vX.Y.Z must match package.json):
git tag v0.13.1
git push origin v0.13.1
- The Release workflow builds Windows / macOS / Linux assets and updater manifests. Notes: tag must match version; portable Windows is not auto-updated; macOS community builds are ad-hoc signed (INSTALLATION.md); Developer ID + notarize via
build/mac-signing.env.example.
npm scripts
| Script | Description |
|---|
dev | Vite hot reload |
build | Frontend → dist/ |
server / server:lan / server:dev | Express backend |
electron | Desktop shell |
pack / dist / portable | Electron-builder packages |
Project structure
api/ Database, migrations, controllers, routes
app/ Express server, tasks, defaults
databases/ Runtime SQLite DBs and generated images
dist/ Production frontend build
electron/ Electron preload
public/ Static assets, dev config
src/ Vue 3 frontend
models/ Optional ML models
scripts/ Build utilities
packages/ Official plugins (stash, jellyfin, …)
Legacy Vue 2 branch
master is the Vue 3 rewrite (v0.13.0+). The old stack lives on legacy/vue2 for reference only:
git checkout legacy/vue2
Troubleshooting
better-sqlite3 and Electron
Need better-sqlite3 12.4.2+. The native module builds for one runtime at a time:
| Task | What happens |
|---|
npm run server / server:dev | Rebuilt for Node on postinstall / start |
npm run electron | Rebuilt for Electron via scripts/ensure-electron-native.mjs |
On NODE_MODULE_VERSION mismatch: npm rebuild better-sqlite3 or node scripts/ensure-electron-native.mjs --force.
On macOS 15+ (esp. 26), AMFI may reject linker-signed natives — ensure-electron-native.mjs re-signs ad-hoc; or run node scripts/sign-native-modules.mjs.
Electron and the databases folder
Keep backups before packaging, or store DBs outside the app bundle.
macOS code signing
Community builds use ad-hoc signing. First launch: right-click → Open. See INSTALLATION.md.
Contributing
- Check existing issues
- Open a new issue with repro steps or a clear feature request
- Pull requests are welcome
License
MediaChips is licensed under the GNU General Public License v3.0.
Copyright © 2020–2026 MediaChips contributors