IINA Plugin Bookmarks

March 2, 2026 · View on GitHub

CI License: ISC

A bookmark management plugin for IINA that lets you save, organize, and navigate to specific moments in your media files.

Features

  • Bookmark Management -- Create, edit, delete, and jump to bookmarks at any playback position
  • Tag System -- Organize bookmarks with tags, auto-tagging, and multi-criteria filtering
  • Search and Sort -- Advanced search across titles, descriptions, and tags with multi-criteria sorting
  • Import / Export -- JSON and CSV support with duplicate handling and validation
  • Cloud Sync (Roadmap) -- Provider-based sync is planned; use JSON/CSV export/import for backup and transfer today
  • File Reconciliation -- Detect and resolve bookmarks pointing to moved or renamed files
  • Multiple Interfaces -- IINA sidebar tab, standalone management window, and video overlay
  • Smart Metadata -- Automatic title detection from media metadata with intelligent fallbacks

Prerequisites

Installation

  1. In IINA, open Preferences → Plugins and use Install from GitHub (recommended) with:
    • https://github.com/wyattowalsh/iina-plugin-bookmarks
  2. Or install from a release asset: download the latest .iinaplgz file from Releases, then double-click it (or extract manually): 
    mkdir -p ~/Library/Application\ Support/com.colliderli.iina/plugins/
unzip iina-plugin-bookmarks.iinaplgz -d ~/Library/Application\ Support/com.colliderli.iina/plugins/iina-plugin-bookmarks.iinaplugin
  3. Restart IINA.
  4. The Bookmarks tab appears in the sidebar. Plugin menu items are available under the Plugin menu.

For development, create a symlink so IINA loads the plugin directly from your working copy:

ln -s /path/to/iina-plugin-bookmarks ~/Library/Application\ Support/com.colliderli.iina/plugins/iina-plugin-bookmarks.iinaplugin-dev

Development

pnpm install          # Install dependencies
make dev              # Start dev servers (sidebar, overlay, window)
make build            # Build plugin (TypeScript + UI)
make test             # Run tests
pnpm test             # Run tests (alternative)
pnpm run lint         # Run linter
pnpm run format       # Format code
pnpm run type-check   # TypeScript type checking
make package          # Build and package as .iinaplgz
make release          # Full local release gate: clean install + release-run

Releases (Maintainers)

GitHub release publishing is tag-driven (v* only). For exact steps, use the release runbook.

Canonical release preflight (same lane as .github/workflows/release.yml):

RELEASE_TAG=vX.Y.Z make release-run

Direct-release install URLs:

  • Pinned tag: https://github.com/wyattowalsh/iina-plugin-bookmarks/releases/download/vX.Y.Z/iina-plugin-bookmarks.iinaplgz
  • Latest channel: https://github.com/wyattowalsh/iina-plugin-bookmarks/releases/latest/download/iina-plugin-bookmarks.iinaplgz

Project Structure

src/
  index.ts                  Main plugin entry point
  bookmark-manager.ts       Core bookmark orchestration
  bookmark-import-export.ts Import/export and duplicate handling
  bookmark-persistence.ts   Local persistence and backup recovery
  thumbnail-generator.ts    Thumbnail generation utilities
  types.ts                  TypeScript type definitions

ui/
  sidebar/                  IINA sidebar interface
  window/                   Standalone management window
  overlay/                  Video overlay
  components/               Shared React components

tests/                      Test suite (Vitest)
docs/                       Documentation site (Fumadocs)
dist/                       Build output
packaging/                  Plugin package output

Contributing

  • Pre-commit hooks (ESLint, Prettier) run automatically on commit via Husky.
  • Branch naming: feat/description, fix/description, chore/description.
  • All PRs should pass CI checks: lint, type-check, test, build.
  • See .github/PULL_REQUEST_TEMPLATE.md for the PR checklist.

For detailed contributing guidelines, see CONTRIBUTING.md.

License

ISC