MediaChips

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.

---

Vue 3 rewrite (v0.13.0+)

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

	Current (master)	Legacy (legacy/vue2)
Stack	Vue 3 · Vite · Vuetify 3 · Express · Electron	Vue 2 · Webpack · Vuetify 2
Last release	v0.13.0	v0.12.5-beta
Status	Active development	Maintenance / reference only

To work with the old codebase:

git checkout legacy/vue2

Older releases and tags remain available in Releases.

---

Features

Media + Chips

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.

Browse

• 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 & Sort

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

Share on your LAN

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.

Tools

• 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)

---

Download

Pre-built installers are published on GitHub:

⬇ Download latest release

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

---

Build from source

Requirements

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

Install dependencies

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

Production

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

Development

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).

Desktop app (Electron)

npm run build
npm run electron

Distribution packages

Command	Description
npm run pack	Build unpacked app (release/)
npm run dist	Build installers (NSIS / AppImage / DMG + ZIP)
npm run portable	Windows portable build
npm run dist:publish	Build frontend and publish all installers to GitHub Releases

Build artifacts are written to the release/ directory.

Publishing a release (maintainers)

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):

Platform	File
Windows	MediaChips.vX.Y.Z.Windows.Installer.exe
macOS (install)	MediaChips.vX.Y.Z.Mac.arm64.dmg, MediaChips.vX.Y.Z.Mac.x64.dmg
macOS (auto-update)	MediaChips.vX.Y.Z.Mac.arm64.zip, MediaChips.vX.Y.Z.Mac.x64.zip
Linux	MediaChips.vX.Y.Z.Linux.AppImage

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.

---

npm scripts

Script	Description
dev	Vite dev server with hot reload
build	Compile frontend to dist/
preview	Preview production build
server	Start Express server / app backend
server-dev	Start server with nodemon (auto-restart)
server-lan	Start server bound to 0.0.0.0 for LAN access
electron	Run the Electron desktop shell
download-parser-model	Download ML model for path tag suggestions
pack	Electron-builder — unpacked output
dist	Electron-builder — full installers
dist:publish	Build frontend + publish all platforms to GitHub Releases
dist:win / dist:mac / dist:linux	Publish a single platform (used in CI)
portable	Electron-builder — Windows portable

---

Project structure

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

---

Troubleshooting

sqlite3 on Apple Silicon (M1/M2/M3)

If sqlite3 fails to compile for arm64, rebuild it for Electron:

npm install sqlite3 --build-from-source --target_arch=arm64 --fallback-to-build

For regular Node.js development, reinstall normally:

npm install sqlite3

sqlite3 5.1.6+ works well on macOS and Windows 11.
To avoid rebuilding separately for Electron and for development, run dev scripts and Electron in parallel against the same node_modules install.

Electron and the databases folder

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.

macOS code signing

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.

---

Contributing

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

---

License

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

Copyright © 2020–2026 MediaChips contributors