Bookmark Management

Learn how to create, edit, and manage bookmarks in IINA.

🚀 Creating Bookmarks

Instant Bookmark Creation

The fastest method for creating bookmarks with intelligent defaults:

Trigger Creation

Default: Cmd+B (configurable in settings)

Creates instant bookmark at current playback position.

Sidebar Interface → "➕ Add Bookmark" button

Visual interface with preview of current position.

Automatic Processing

The plugin automatically handles:

Media title detection from metadata or filename
Timestamp capture at exact playback position
Intelligent cleanup of titles and formatting
Auto-tagging based on media type and content

// Automatic bookmark creation process
const bookmark = await bookmarkManager.addBookmark();
// Results in:
{
  id: "bookmark_1695740123456",
  title: "The Matrix Reloaded", // Auto-detected
  timestamp: 2847.5, // Current playback time
  filepath: "/Movies/The.Matrix.Reloaded.2003.mp4",
  createdAt: "2024-01-15T10:30:45.123Z",
  tags: ["action", "sci-fi"] // Auto-generated
}

Performance Optimization

Quick creation uses debounced operations to prevent excessive I/O, allowing rapid bookmark creation without performance impact.

Manual Bookmark Creation

For precise control over bookmark properties:

Open Advanced Dialog

Access the full bookmark creation interface:

Double-click the add bookmark button
Right-click in media area → "Create Detailed Bookmark"
Keyboard: Cmd+Shift+B for advanced dialog

Configure Properties

📝 Title & Description

• Auto-detected title with override option
• Rich text description support
• Title validation and suggestions
• Character count and optimization tips

⏰ Timing & Position

• Precise timestamp control (frame-accurate)
• Preview thumbnail at selected time
• Time format customization
• Playback position validation

🏷️ Tags & Organization

• Auto-complete from existing tags
• Hierarchical tag suggestions
• Bulk tag application
• Tag validation and cleanup

🔧 Advanced Options

• Custom bookmark ID generation
• Metadata preservation settings
• Duplicate detection preferences
• Export format preparation

Validation & Save

The system performs comprehensive validation:

// Validation pipeline
interface ValidationResult {
  isValid: boolean;
  errors: string[];
  warnings: string[];
  suggestions: string[];
}

const validation = await bookmarkManager.validateBookmark({
  title: "User Input Title",
  timestamp: 1234.56,
  description: "User description",
  tags: ["custom", "tags"]
});

Smart Validation

Validation includes duplicate detection, timestamp verification, file path validation, and intelligent suggestions for improvements.

Batch Bookmark Creation

Create multiple bookmarks efficiently:

Chapter-Based Creation

Automatically create bookmarks from media chapters:

// Automatic chapter bookmark creation
const chapterBookmarks = await bookmarkManager.createFromChapters({
  includeIntro: true,
  includeOutro: false,
  minChapterLength: 300, // 5 minutes minimum
  tagPrefix: "chapter"
});

Interval-Based Creation

Create bookmarks at regular intervals:

// Create bookmarks every 10 minutes
const intervalBookmarks = await bookmarkManager.createAtIntervals({
  interval: 600, // 10 minutes in seconds
  startTime: 0,
  endTime: mediaDuration,
  titleTemplate: "Interval {index} - {timestamp}"
});

Import-Based Creation

Create bookmarks from external timestamp lists:

// Import from timestamp file
const importedBookmarks = await bookmarkManager.importFromTimestamps([
  { time: "00:05:30", title: "Opening Scene" },
  { time: "00:15:45", title: "Character Introduction" },
  { time: "01:23:15", title: "Climax Scene" }
]);

Performance Considerations

Batch operations use optimized processing with progress tracking and can be cancelled if needed. Large batch operations are processed in chunks to maintain UI responsiveness.

📋 Bookmark Data Structure

Each bookmark follows a comprehensive data model designed for extensibility and performance:

TypeScript Interface Definition

interface BookmarkData {
  // Required core properties
  id: string;              // Unique identifier (auto-generated)
  title: string;           // Display title (auto-detected or custom)
  timestamp: number;       // Playback position in seconds (precision: 0.1s)
  filepath: string;        // Absolute or relative path to media file
  createdAt: string;       // ISO 8601 timestamp of creation
  
  // Optional enhancement properties
  description?: string;    // User-provided description/notes
  tags?: string[];        // Array of organizational tags
}

Schema Evolution

The bookmark schema supports backward compatibility and forward migration for future enhancements while maintaining performance through optimized storage.

Property Specifications

🆔 Unique Identifier

Format: bookmark_{timestamp}_{random}

Example: bookmark_1695740123456_a1b2c3

Purpose: Ensures uniqueness across all bookmarks

Generation: Automatic on creation

Mutability: Immutable after creation

Indexing: Primary key for cache lookups

📝 Title Processing

Source Priority:

User-provided custom title
Media metadata title
Cleaned filename
Generic fallback

Processing Features:

Quality indicator removal
Special character normalization
Length optimization
Encoding standardization

⏱️ Timestamp Precision

Precision: 0.1 second accuracy

Range: 0.0 to media duration

Format: Floating point (seconds.milliseconds)

Display Formats:

HH:MM:SS (default)
MM:SS (under 1 hour)
Seconds.ms (technical)
Frame numbers (advanced)

🏷️ Tag System

Structure: Flat array of strings

Limits: Max 20 tags per bookmark

Validation: Alphanumeric + hyphens/underscores

Auto-generation:

Media type detection
Genre identification
Quality level tagging
Position-based tags

Data Validation Pipeline

Comprehensive validation ensures data integrity and consistency:

interface ValidationPipeline {
  // Core validation checks
  validateId(id: string): ValidationResult;
  validateTitle(title: string): ValidationResult;
  validateTimestamp(timestamp: number, mediaDuration: number): ValidationResult;
  validateFilepath(filepath: string): ValidationResult;
  validateTags(tags: string[]): ValidationResult;
  
  // Advanced validation
  validateDuplicates(bookmark: BookmarkData, existing: BookmarkData[]): ValidationResult;
  validateConsistency(bookmark: BookmarkData): ValidationResult;
  validatePerformance(bookmark: BookmarkData): ValidationResult;
}

✅ Valid Example:

{
"id": "bookmark_1695740123456_a1b2c3",
"title": "The Matrix: Neo's Awakening Scene",
"timestamp": 2847.5,
"filepath": "/Movies/The.Matrix.1999.1080p.mp4",
"description": "The moment Neo chooses the red pill",
"createdAt": "2024-01-15T10:30:45.123Z",
"tags": ["sci-fi", "pivotal-moment", "character-development"]
}

❌ Invalid Example:

{
"id": "",                    // Empty ID - fails validation
"title": "",                 // Empty title - fails validation
"timestamp": -1,             // Negative timestamp - invalid
"filepath": "nonexistent",   // Invalid file path
"tags": ["@invalid!", ""]    // Invalid tag characters and empty tag
}

Validation Performance

Validation is optimized for performance with early termination and cached validation results for frequently accessed bookmarks.

Real-World Examples

🎬 Movie Scene Bookmark

{
"id": "bookmark_1695740123456_movie01",
"title": "Inception: Dream Within Dream Explanation",
"timestamp": 3420.8,
"filepath": "/Movies/Inception.2010.BluRay.1080p.mp4",
"description": "Dom explains the concept of dreams within dreams to Ariadne. Critical plot exposition scene with visual demonstrations of multi-level dreaming architecture.",
"createdAt": "2024-01-15T14:22:33.456Z",
"tags": ["explanation", "plot-critical", "visual-effects", "sci-fi", "favorite"]
}

📚 Educational Content Bookmark

{
"id": "bookmark_1695745678901_edu01",
"title": "Calculus Fundamentals: Derivative Introduction",
"timestamp": 1247.2,
"filepath": "/Education/Mathematics/Calculus_101_Lecture_03.mp4",
"description": "Professor introduces the formal definition of derivatives with geometric interpretation and practical examples.",
"createdAt": "2024-01-15T15:45:12.789Z",
"tags": ["mathematics", "calculus", "derivatives", "lecture", "definition", "study-material"]
}

🎵 Music Video Bookmark

{
"id": "bookmark_1695750234567_music01",
"title": "Bohemian Rhapsody: Opera Section",
"timestamp": 164.7,
"filepath": "/Music/Queen/Bohemian_Rhapsody_Official_Video_Remastered.mp4",
"description": "The iconic opera section begins - 'I see a little silhouetto of a man'",
"createdAt": "2024-01-15T16:12:45.234Z",
"tags": ["queen", "opera", "classic-rock", "iconic", "vocals", "highlight"]
}

Best Practices

Descriptive titles: Use clear, searchable titles that describe the scene or content
Meaningful tags: Include genre, mood, importance level, and content type tags
Rich descriptions: Add context that will be useful when revisiting the bookmark later
Consistent naming: Develop naming conventions for similar content types

Organizing Bookmarks

Tag System

Tags provide flexible organization for your bookmarks:

// Example bookmark with tags
{
  title: "Epic Battle Scene",
  timestamp: 2847.5,
  tags: ["action", "climax", "favorite"],
  description: "Amazing fight choreography"
}

Common Tag Strategies

Genre Tags: action, comedy, drama, documentary

Content Tags: favorite, review-later, share, study

Scene Tags: opening, climax, ending, blooper

Quality Tags: best-scene, poor-quality, needs-review

Filtering and Searching

Find your bookmarks quickly using:

Text Search: Search titles, descriptions, and file paths
Tag Filtering: Filter by one or multiple tags
Date Range: Find bookmarks from specific time periods
Media Type: Filter by file type or format

Bookmark Operations

Viewing Bookmarks

Access your bookmarks through:

Plugin Sidebar - Integrated with IINA
Standalone Window - Dedicated bookmark manager
Quick Preview - Hover tooltips with details

Editing Bookmarks

Modify existing bookmarks:

Double-click to edit inline
Right-click for context menu options
Bulk edit multiple bookmarks at once
Undo/Redo support for changes

Jumping to Bookmarks

Navigate to bookmarked positions:

Single-click - Jump to timestamp in current media
Double-click - Open media file and jump to position
Preview mode - View thumbnail at timestamp (if available)

Advanced Features

Duplicate Detection

The system automatically:

Detects potential duplicate bookmarks
Suggests merging similar entries
Prevents exact duplicates by timestamp

Batch Operations

Perform operations on multiple bookmarks:

Bulk tagging - Add tags to selected bookmarks
Mass deletion - Remove multiple bookmarks
Export selection - Export chosen bookmarks only
Tag management - Rename or merge tags across bookmarks

Smart Suggestions

The plugin provides intelligent suggestions:

Auto-complete tags based on existing tags
Similar bookmarks detection
Optimal timestamp suggestions
Title corrections for common mistakes

Data Integrity

Automatic Backups

Auto-save - Changes saved immediately
Backup rotation - Multiple backup copies maintained
Recovery options - Restore from backup if needed

File Path Management

Relative paths - Bookmarks work across different systems
Missing file detection - Alerts when media files are moved
Path updating - Bulk update paths when media is reorganized

Always backup your bookmark data before major system changes or media reorganization.

Keyboard Shortcuts

Action	Default Shortcut	Description
Create Bookmark	`Cmd+B`	Quick bookmark creation
Open Manager	`Cmd+Shift+B`	Open standalone window
Search Bookmarks	`Cmd+F`	Focus search box
Delete Bookmark	`Delete`	Remove selected bookmark
Edit Bookmark	`Enter`	Edit selected bookmark

All keyboard shortcuts are customizable through the plugin settings.