Organize, tag, and browse your local media library with ease.

Website · Downloads · Issues · Discussions

MediaChips is open-source software for organizing, tagging, filtering, and playing local video files.
Attach rich metadata — tags, ratings, favorites, bookmarks, text, dates, numbers, and more — then browse your library as visual cards, filter it in detail, and play files in the built-in or system player.

Privacy first. MediaChips does not collect your data or send it anywhere. The app is fully transparent — inspect the code, extend it, or self-host it on your network.

Starting with v0.13.0, the master branch is a full rewrite:

To work with the old codebase:

git checkout legacy/vue2

Older releases and tags remain available in Releases.

Chips (metadata) are pieces of information attached to your files: tags, ratings, favorites, bookmarks, text, dates, numbers, and custom types you define.
Each chip can be customized — add images, colors, countries, nested chips, and more.

• Video cards with metadata, hover preview, and inline playback
• Built-in player with timeline markers, playlist, and storyboard view
• Customizable appearance: colors, card layout, chip styles, dark mode
• Tabs for videos and tags, multiple databases

• Filter by any parameter or tag
• Save and load filter presets
• Quick filters, favorites, and global search
• Sort by rating, date, and other fields

Open your library in a browser on any device on the local network — phone, tablet, TV, or another computer.
Desktop builds are available for macOS, Windows, and Linux.

• Watched folders for new and removed files
• File operations: move, delete, open containing folder
• Password protection
• Duplicate detection by file size
• Data scraper for adult content
• Path-based tag suggestions (optional ML model)

Pre-built installers are published on GitHub:

⬇ Download latest release

For macOS installation notes (Gatekeeper / quarantine), see INSTALLATION.md.

• Node.js 18 or newer (LTS recommended)
• npm 9+
• Platform build tools for native modules (better-sqlite3, ffmpeg-static)

git clone https://github.com/fupdec/mediaChips.git
cd mediaChips
npm install
npm run download-parser-model   # optional: ML path tag parser model

1. Build the frontend into /dist:

npm run build

2. Start the server (creates config and database on first run):

npm run server

3. Open http://localhost:12321 in your browser.

To expose the server on your LAN:

npm run server-lan

1. Build the frontend once:

npm run build

2. Start the backend (creates public/config.json on first run):

npm run server

3. Copy or edit public/config.json if needed (set ip to your machine's local address for LAN testing).

4. Run the backend with auto-restart:

npm run server-dev

5. In a second terminal, run the Vite dev server for hot reload:

npm run dev

6. Open http://localhost:3000 (frontend) — API requests go to the backend port from config.json (default 12321).

npm run build
npm run electron

Build artifacts are written to the release/ directory.

Desktop auto-update reads installers from GitHub Releases.

1. Bump version in package.json (semver, e.g. 0.13.1).
2. Commit the change on main.
3. Create and push a matching tag (tag must equal version with a v prefix):

git tag v0.13.1
git push origin v0.13.1

4. The Release workflow builds Windows (NSIS), macOS (arm64 + x64 DMG/ZIP), and Linux (AppImage) in parallel and uploads them to the GitHub Release together with latest.yml / latest-mac.yml / latest-linux.yml required by electron-updater.

Expected asset names (legacy style):

5. Installed desktop apps with Settings → About → Check for updates at startup will detect the new version automatically.

No extra GitHub secrets are required: the workflow uses the built-in GITHUB_TOKEN with contents: write.

Notes

• Tag vX.Y.Z must match package.json version exactly.
• Portable Windows builds are not auto-updated in-app; users must download manually.
• macOS builds are ad-hoc signed (identity: "-"). Users still confirm the first launch via right-click → Open (see INSTALLATION.md).
• For fully trusted macOS/Windows builds later, add secrets CSC_LINK, CSC_KEY_PASSWORD (and Apple notarization vars) to the repository.

api/            Database models, migrations, controllers, routes
app/            Express server, tasks, default settings
databases/      Created at runtime — SQLite DBs and generated images
dist/           Production frontend build (generated)
electron/       Electron preload scripts
public/         Static assets, dev config (`config.json`)
src/            Vue 3 frontend source
models/         ML model files for path tag parser
scripts/        Build and utility scripts

Нужна better-sqlite3 12.4.2+ — в 11.x сборка под современный Electron падает (Context::GetIsolate удалён из V8).

Модуль нативный и собирается под один runtime за раз:

Если после npm install видите NODE_MODULE_VERSION mismatch — пересоберите вручную: npm run rebuild:electron или npm run rebuild:node.

На macOS 15+ (особенно macOS 26) Electron может падать с CODESIGNING / Invalid Page при загрузке better-sqlite3: electron-rebuild оставляет linker-signed бинарник, который AMFI отклоняет. rebuild:electron после сборки автоматически переподписывает .node файлы ad-hoc (codesign --sign -). Если запускали electron-rebuild вручную — выполните node scripts/sign-native-modules.js.

electron-builder при pack/dist пересобирает нативные модули сам; в CI отдельный electron-rebuild не нужен.

Electron 32+ may remove the databases directory in certain build configurations.
Keep backups of your databases before packaging, or store them outside the app bundle.

Community macOS builds use ad-hoc signing so Apple Silicon does not show the unfixable "app is damaged" dialog. Users still need one right-click → Open on first launch. See INSTALLATION.md.

Found a bug or want a new feature?

1. Check existing issues
2. Open a new issue with steps to reproduce or a clear feature description
3. Pull requests are welcome

Community: Discord · Reddit

MediaChips is licensed under the GNU General Public License v3.0.

Copyright © 2020–2026 MediaChips contributors