Video Tagger

Bookmark any moment in a video with a note. Works on YouTube, Netflix, Twitch, Vimeo, and any site with an HTML5 video player.

How it works

Three pieces work together:

extension/   →   Browser extension (Chrome, Firefox, Safari)
server/      →   Local Node.js server — stores tags in SQLite
frontend/    →   React dashboard to view, search, and edit your tags

The extension injects a content script that adds a keyboard shortcut and bookmark markers on the video progress bar. When you tag a moment, it POSTs to the local server (localhost:3333). The frontend reads from the same server and lets you manage everything.

Your data lives entirely on your machine at ~/.video-tagger/tags.db.

---

Setup

1. Start the server

Requires Node.js 22+ (uses the built-in node:sqlite module).

cd server
node server.js

Server runs at http://localhost:3333. The frontend is served from the same port — open it in your browser.

2. Build the frontend (first time / after changes)

cd frontend
npm install
npm run build

The built files go to frontend/dist/, which the server serves automatically.

3. Install the browser extension

Chrome / Edge / Brave / Arc:

1. Go to chrome://extensions
2. Enable Developer Mode
3. Click "Load unpacked" and select the extension/ folder

Firefox:

1. Go to about:debugging#/runtime/this-firefox
2. Click "Load Temporary Add-on" and select extension/manifest.json

Safari:

Safari requires wrapping the extension in a native macOS app. Do this once:

xcrun safari-web-extension-converter extension/ \
  --project-location . \
  --app-name "Video Tagger" \
  --bundle-identifier com.yourname.video-tagger \
  --no-open

This generates a Video Tagger/ Xcode project. Open it, build and run the macOS target, then enable the extension in Safari → Settings → Extensions.

The generated Video Tagger/ folder is not checked into this repo — regenerate it with the command above whenever you need to build for Safari.

---

Usage

Action	How
Tag the current moment	⌘⇧S (Mac) / Ctrl+Shift+S (Windows/Linux), or click the extension icon
Add a note	Type in the overlay that appears, then ⌘↵ to save
View all tags	Open http://localhost:3333
Jump to a tag	Click the timestamp link in the dashboard, or click a marker on the progress bar
Edit a tag note	Click the note text in the dashboard, or hover a progress bar marker and click "Edit note"
Delete a tag	Click the × button in the dashboard
Search	Type in the search bar — searches video titles and note text

---

Features

• Progress bar markers — yellow bookmark pins appear on the video timeline for all your saved tags; hover to see the note, click to seek
• Edit from the video — hover a marker, click "Edit note" to update it without leaving the page
• Dashboard — grouped by video with thumbnail, platform badge, tag count, and timestamps for when each tag was added
• Search — filters across video titles and note content in real time
• Multi-platform — YouTube, Netflix, Twitch, Vimeo, and any HTML5 video site

---

Project structure

extension/
  manifest.json       MV3 extension manifest
  content.js          Injected into video pages — overlay, markers, edit
  background.js       Service worker — forwards keyboard shortcut to content script
  popup.html/js       Extension toolbar popup

server/
  server.js           HTTP server + SQLite — handles all /tags routes
  db.js               (unused stub)

frontend/
  src/
    App.jsx           Root — fetches /tags, manages state
    components/
      VideoCard.jsx   Collapsible card per video
      TagItem.jsx     Single tag row with inline editing
  src/App.css         All styles

---

API

The server exposes a simple REST API at localhost:3333:

Method	Path	Description
GET	/tags	All tags grouped by video
GET	/tags?url=<url>	Tags for a specific video URL
POST	/tags	Create a tag
PATCH	/tags/:id	Update a tag's note
DELETE	/tags/:id	Delete a tag

---

Hosting

This app is designed to run locally — the extension hardcodes localhost:3333 and your data stays on your machine. Hosting it remotely is possible but requires updating every localhost:3333 reference in content.js, popup.js, and the extension manifest, plus adding some auth so the API isn't public.

If you do want it hosted, the realistic free options:

Platform	Notes
Railway	Best fit. Supports Node.js, persistent volumes (SQLite survives redeploys). Free tier: $5 credit/month — enough for a small always-on app.
Fly.io	Free tier with 3 VMs and persistent volumes. More setup (own CLI) but reliable and never sleeps.
Render	Free Node.js hosting but sleeps after 15 min of inactivity — the extension will fail on the first tag attempt after a sleep. Persistent disk is paid.
Vercel / Netlify	Serverless only — no persistent disk, SQLite won't work. Fine for hosting just the frontend as a static site if you keep the server local.

---

Requirements

• Node.js 22+
• Chrome, Firefox, or Safari (macOS)
• Xcode (only needed for the Safari build)