BookmarkManager API Reference

The BookmarkManager class is the central orchestrator for all bookmark operations, UI communication, and system integration.

Class Overview

export class BookmarkManager {
  private bookmarks: BookmarkData[];
  private readonly SORT_PREFERENCES_KEY = 'sortPreferences';
  private deps: IINARuntimeDependencies;
  private persistence: BookmarkPersistence;
  private importExport: BookmarkImportExport;
  private cloudSync: CloudSyncHandler;
  private eventIds: string[];
  private idCounter: number;

  constructor(dependencies: IINARuntimeDependencies)
}

Constructor

Creates a new BookmarkManager instance and initializes all subsystems.

constructor(dependencies: IINARuntimeDependencies)

Parameters:

• dependencies - IINA runtime dependencies (console, core, preferences, menu, event, sidebar, overlay, standaloneWindow, utils, file, http)

Initialization sequence:

1. Creates persistence, import/export, and cloud sync handlers
2. Loads existing bookmarks from storage
3. Loads sort preferences
4. Sets up event listeners for file-loaded events
5. Sets up web UI (sidebar, overlay, window)
6. Sets up UI message listeners for all message types

Core Methods

async addBookmark(
  title?: string,
  timestamp?: number,
  description?: string,
  tags?: string[]
): Promise<void>

// Quick bookmark at current position with auto-generated title
await manager.addBookmark();

// Custom bookmark with full details
await manager.addBookmark(
  "Epic Battle Scene",
  2847.5,
  "Amazing fight choreography",
  ["action", "favorite"]
);

removeBookmark(id: string): void

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

manager.updateBookmark("bookmark_123", {
  title: "Updated Title",
  description: "New description",
  tags: ["updated", "favorite"]
});

jumpToBookmark(id: string): void

getBookmarksForFile(filepath?: string): BookmarkData[]

// Get all bookmarks
const all = manager.getBookmarksForFile();

// Get bookmarks for specific file
const movieBookmarks = manager.getBookmarksForFile('/Movies/Inception.mp4');

getAllBookmarks(): BookmarkData[]

getBookmarkCount(): number

destroy(): void

Private Methods

The BookmarkManager uses several private methods for internal operations:

UI Communication

• setupWebUI() - Loads sidebar, overlay, and window HTML files
• setupUIMessageListeners() - Registers message handlers for all UI message types
• handleUIMessage() - Routes incoming messages to appropriate handlers
• getUITarget() - Returns the correct UI API object (sidebar/overlay/window)
• sendCurrentFilePath() - Sends current media file path to UI
• sendBookmarksToUI() - Sends filtered bookmarks to UI
• sendBookmarkDefaults() - Sends auto-populated bookmark defaults for creation
• refreshUI() - Refreshes all three UI interfaces

Event Handling

• setupEventListeners() - Registers file-loaded events and menu items
• loadSortPreferences() - Loads and sends sort preferences to all UIs
• saveSortPreferencesFromUI() - Saves sort preferences from UI

Data Management

• saveBookmarks() - Delegates to BookmarkPersistence, then refreshes UIs
• importBookmarks() - Delegates to BookmarkImportExport
• exportBookmarks() - Delegates to BookmarkImportExport
• handleCloudSync() - Delegates to CloudSyncHandler

File Reconciliation

• handleReconcileFiles() - Finds bookmarks with missing files
• handleFileReconciliation() - Routes reconciliation actions (update_path, remove_bookmark, search_similar)
• updateBookmarkPath() - Updates a bookmark's file path
• searchForSimilarFiles() - Placeholder for similar file search (not yet implemented)

Utilities

• generateId() - Generates unique bookmark IDs using timestamp + counter + random

UI Message Protocol

The BookmarkManager handles the following messages from UIs:

Incoming Messages (UI → Backend):

• UI_READY - UI initialization complete, triggers bookmark sync
• REQUEST_FILE_PATH - Request current media file path
• REQUEST_BOOKMARK_DEFAULTS - Request auto-populated defaults for new bookmark
• ADD_BOOKMARK - Create new bookmark
• DELETE_BOOKMARK - Remove bookmark by ID
• UPDATE_BOOKMARK - Update bookmark fields
• JUMP_TO_BOOKMARK - Seek to bookmark timestamp
• HIDE_OVERLAY - Hide overlay UI
• IMPORT_BOOKMARKS - Import bookmarks from external data
• EXPORT_BOOKMARKS - Export bookmarks to JSON/CSV
• CLOUD_SYNC_REQUEST - Perform cloud sync operation
• FILE_RECONCILIATION_REQUEST - Handle file path reconciliation
• RECONCILE_FILES - Show file reconciliation dialog
• SAVE_SORT_PREFERENCES - Save sort preferences

Outgoing Messages (Backend → UI):

• BOOKMARKS_UPDATED - Current bookmarks for file
• CURRENT_FILE_PATH - Current media file path
• BOOKMARK_ADDED - Confirmation of bookmark creation
• BOOKMARK_DELETED - Confirmation of bookmark deletion
• BOOKMARK_JUMPED - Confirmation of seek operation
• BOOKMARK_DEFAULTS - Auto-populated bookmark defaults
• SORT_PREFERENCES - Current sort preferences
• IMPORT_RESULT - Import operation result
• EXPORT_RESULT - Export operation result
• CLOUD_SYNC_RESULT - Cloud sync operation result
• SHOW_FILE_RECONCILIATION_DIALOG - Trigger reconciliation dialog
• FILE_RECONCILIATION_RESULT - File reconciliation result

Example Usage

// Initialize BookmarkManager with IINA runtime dependencies
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,
  http: httpAdapter
});

// Add a bookmark at current position
await manager.addBookmark();

// Add a bookmark with custom details
await manager.addBookmark(
  "Important Scene",
  1234.5,
  "Key plot point revealed",
  ["plot", "important"]
);

// Get bookmarks for current file
const currentPath = iina.core.status.path;
const bookmarks = manager.getBookmarksForFile(currentPath);

// Jump to a bookmark
manager.jumpToBookmark("bookmark_id_here");

// Update bookmark
manager.updateBookmark("bookmark_id", {
  title: "Updated Title",
  tags: ["updated"]
});

// Remove bookmark
manager.removeBookmark("bookmark_id");

// Clean up when done
manager.destroy();