BookmarkManager API Reference

BookmarkManager is the orchestrator for bookmark CRUD, collection workflows, playback helpers, and UI message routing.

Class Overview

export class BookmarkManager {
  private bookmarks: BookmarkData[];
  private collections: BookmarkCollection[];
  private smartCollections: SmartCollection[];
  private persistence: BookmarkPersistence;
  private importExport: BookmarkImportExport;
  private thumbnailGenerator: ThumbnailGenerator;

  constructor(dependencies: IINARuntimeDependencies);
}

Current runtime modules are BookmarkPersistence, BookmarkImportExport, and ThumbnailGenerator. There is no cloud-sync module in the current src/bookmark-manager.ts.

Constructor

constructor(dependencies: IINARuntimeDependencies)

Dependencies used by the manager:

console, core, preferences, menu, event
sidebar, overlay, standaloneWindow
utils, file
optional mpv, playlist

Initialization flow (practical):

Create persistence/import-export/thumbnail helpers
Load bookmarks, collections, and saved resume positions
Register event + menu handlers
Initialize UI immediately (if window loaded) or on iina.window-loaded
Register UI message listeners + load saved sort preferences

Public Methods

`addBookmark()`

async addBookmark(
  title?: string,
  timestamp?: number,
  description?: string,
  tags?: string[],
  options?: {
    skipDuplicateCheck?: boolean;
    color?: BookmarkColor;
    endTimestamp?: number;
    scratchpad?: boolean;
  },
): Promise<string | undefined>

Notes:

Returns bookmark ID on success.
Returns undefined when max bookmark cap is reached or near-duplicate detection blocks creation.
Validates timestamp and range fields; sanitizes title/description/tags.
Enriches with chapter/subtitle metadata when available.

`removeBookmark(id: string): void`

Removes bookmark and cleans collection references.

`updateBookmark(id: string, data: BookmarkUpdatableFields): void`

Updates mutable fields (title, description, tags, color, endTimestamp, pinned, scratchpad) and refreshes updatedAt.

`jumpToBookmark(id: string): void`

Seeks directly when bookmark file matches current file.
For cross-file jumps, opens the file and waits for iina.file-started before seeking.

Query helpers

getBookmarksForFile(filepath?: string): BookmarkData[]
getAllBookmarks(): BookmarkData[]
getBookmarkCount(): number

Collections

createCollection(name: string, description?: string, color?: BookmarkColor, icon?: string): void
updateCollection(id: string, data: Partial<Omit<BookmarkCollection, 'id' | 'createdAt'>>): void
deleteCollection(id: string): void
addToCollection(bookmarkIds: string[], collectionId: string): void
removeFromCollection(bookmarkIds: string[], collectionId: string): void

Smart Collections

createSmartCollection(name: string, description?: string, filters?: SmartCollectionFilters, color?: BookmarkColor, icon?: string): void
updateSmartCollection(id: string, data: Partial<Omit<SmartCollection, 'id' | 'createdAt' | 'builtin'>>): void
deleteSmartCollection(id: string): void

Batch + Scratchpad

batchDelete(ids: string[]): void
batchTag(ids: string[], tags: string[], action: 'add' | 'remove'): void
batchAssignCollection(ids: string[], collectionId: string, action: 'add' | 'remove'): void
batchPin(ids: string[], pinned: boolean): void
batchColor(ids: string[], color: BookmarkColor): void
promoteScratchpad(ids: string[]): void
discardScratchpad(ids: string[]): void

getAdjacentBookmark(
  currentId: string,
  direction: 'next' | 'prev',
  scope: 'file' | 'all',
): BookmarkData | null

navigateBookmark(currentId: string, direction: 'next' | 'prev', scope: 'file' | 'all'): void

setABLoop(bookmarkId: string): void
clearABLoop(): void

Resume + cleanup

saveResumePosition(): void
destroy(): void

UI Message Protocol (Current)

Incoming messages (UI → Backend)

type UIToBackendMessageName =
  | 'UI_READY'
  | 'REQUEST_FILE_PATH'
  | 'REQUEST_BOOKMARK_DEFAULTS'
  | 'SAVE_SORT_PREFERENCES'
  | 'ADD_BOOKMARK'
  | 'DELETE_BOOKMARK'
  | 'UPDATE_BOOKMARK'
  | 'JUMP_TO_BOOKMARK'
  | 'HIDE_OVERLAY'
  | 'IMPORT_BOOKMARKS'
  | 'EXPORT_BOOKMARKS'
  | 'CREATE_COLLECTION'
  | 'UPDATE_COLLECTION'
  | 'DELETE_COLLECTION'
  | 'CREATE_SMART_COLLECTION'
  | 'UPDATE_SMART_COLLECTION'
  | 'DELETE_SMART_COLLECTION'
  | 'ADD_TO_COLLECTION'
  | 'REMOVE_FROM_COLLECTION'
  | 'BATCH_DELETE'
  | 'BATCH_TAG'
  | 'BATCH_ASSIGN_COLLECTION'
  | 'BATCH_PIN'
  | 'BATCH_COLOR'
  | 'SET_AB_LOOP'
  | 'CLEAR_AB_LOOP'
  | 'SET_IN_POINT'
  | 'SET_OUT_POINT'
  | 'NEXT_BOOKMARK'
  | 'PREV_BOOKMARK'
  | 'SEEK_TO_TIMESTAMP'
  | 'REQUEST_THUMBNAIL'
  | 'PROMOTE_SCRATCHPAD'
  | 'DISCARD_SCRATCHPAD'
  | 'FILE_RECONCILIATION_REQUEST'
  | 'RECONCILE_FILES'
  | 'CONFIRM_BOOKMARK'
  | 'MERGE_BOOKMARK';

Outgoing messages (Backend → UI)

type BackendToUIMessageName =
  | 'BOOKMARKS_UPDATED'
  | 'CURRENT_FILE_PATH'
  | 'BOOKMARK_ADDED'
  | 'BOOKMARK_DELETED'
  | 'BOOKMARK_JUMPED'
  | 'BOOKMARK_DEFAULTS'
  | 'SORT_PREFERENCES'
  | 'IMPORT_STARTED'
  | 'IMPORT_RESULT'
  | 'EXPORT_RESULT'
  | 'COLLECTIONS_UPDATED'
  | 'SMART_COLLECTIONS_UPDATED'
  | 'SHOW_FILE_RECONCILIATION_DIALOG'
  | 'FILE_RECONCILIATION_RESULT'
  | 'BOOKMARK_NEAR_DUPLICATE'
  | 'THUMBNAIL_READY'
  | 'PLAYBACK_STATUS'
  | 'RESUME_POSITION'
  | 'QUICK_BOOKMARK_CREATED'
  | 'ERROR';

Practical behavior notes

Overlay gets file-scoped bookmarks from backend; sidebar/window get full bookmark arrays.
BOOKMARK_NEAR_DUPLICATE is broadcast to all UIs when duplicate threshold checks trigger.
search_similar reconciliation currently returns an empty list with a "not yet implemented" message.

Example Usage

const manager = new BookmarkManager({
  console: iina.console,
  core: iina.core,
  preferences: iina.preferences,
  menu: iina.menu,
  event: iina.event,
  sidebar: iina.sidebar,
  overlay: iina.overlay,
  standaloneWindow: iina.standaloneWindow,
  utils: iina.utils,
  file: iina.file,
  mpv: iina.mpv,
  playlist: iina.playlist,
});

const id = await manager.addBookmark('Important Scene', 1234.5, 'Key plot point', ['plot']);
if (id) {
  manager.updateBookmark(id, { pinned: true, color: 'yellow' });
  manager.jumpToBookmark(id);
}

If cloud sync is added later, document it as roadmap first; do not add cloud request/response contracts here until code ships.

BookmarkManager API