Multi-Criteria Bookmark Sorting

The IINA Bookmarks Plugin features a comprehensive sorting system that allows you to organize bookmarks using multiple criteria with priority-based ordering, giving you precise control over how your bookmarks are displayed.

Sorting Options

The plugin supports six different sorting fields that can be used individually or in combination:

Single-Sort Mode

The default sorting mode provides a straightforward interface for basic sorting needs.

Features

• Enhanced dropdown with all 6 sorting options
• Direction indicators: ↑ Ascending, ↓ Descending
• Quick toggle between ascending and descending order
• Multi-sort activation via "⚡ Multi" button

Multi-Sort Mode

For advanced organization needs, multi-sort mode allows up to 3 simultaneous sort criteria with priority-based fallback.

Key Features

1. Priority-based ordering with numbered indicators
2. Up to 3 criteria for complex sorting scenarios
3. Individual field and direction selectors per criterion
4. Easy management with add/remove controls
5. Smooth UI transitions for better user experience

How Multi-Sort Works

Multi-criteria sorting uses a priority-based comparison algorithm:

1. Sort criteria by priority (1 = highest priority)
2. For each criterion in priority order:
   a. Apply field-specific comparison
   b. If items are not equal, use this result
   c. If items are equal, continue to next criterion
3. If all criteria result in equality, maintain original order

Visual Design

• Color-coded priority badges with #4a90e2 blue theme
• Numbered indicators (1, 2, 3) show sort priority clearly
• Remove buttons (✕) for individual criteria
• Add button for additional criteria (up to limit)
• Compact variations for sidebar and overlay views

User Interface Integration

Window View (Full-Featured)

• Complete multi-sort interface with all controls
• Visual priority indicators and management tools
• Full add/remove/modify functionality
• Detailed sort preference settings

Sidebar View (Compact)

• Streamlined multi-sort controls optimized for narrow space
• Essential functionality preserved in compact layout
• Responsive design for smaller screens
• Quick access to most-used sort options

Overlay View (Minimal)

• Basic multi-sort for quick access during video playback
• Context-aware defaults based on current media
• Compact dropdown interface
• Essential controls only for focused experience

Persistent Preferences

Sort preferences are automatically saved and restored for each UI view:

Per-View Settings

• Overlay preferences saved separately from sidebar/window
• Automatic persistence using IINA's preference system
• Preference restoration on plugin reload
• Independent settings for different use contexts

What Gets Saved

• Current sort criteria and their priority order
• Ascending/descending direction for each criterion
• Multi-sort mode enabled/disabled state
• Recently used sort combinations

Practical Examples

Common Sorting Scenarios

Performance Optimization

The sorting system is designed for efficiency even with large bookmark collections:

Algorithm Optimizations

• Efficient comparison: Priority-based algorithm minimizes unnecessary comparisons
• Filename caching: Extracted filenames are cached to avoid repeated processing
• Responsive UI: Minimal reflow during sort operations
• Smart defaults: Intelligent fallback behavior for missing data

Performance Characteristics

• Fast sorting: Optimized for collections of 100+ bookmarks
• Smooth UI: No blocking operations during sort changes
• Memory efficient: Minimal memory overhead for sort operations
• Responsive feedback: Immediate visual updates when changing sort criteria

Advanced Features

Filename Processing

When sorting by media file name, the system intelligently processes filenames:

1. Extension removal: .mp4, .mkv, etc. are stripped
2. Separator replacement: Dots, underscores, dashes become spaces
3. Quality indicator removal: 720p, 1080p, 4K, etc. are removed
4. Source indicator cleanup: BluRay, DVDRip, WEB-DL, etc. are stripped
5. Codec information removal: x264, x265, H264, etc. are removed
6. Year removal: Years in parentheses are stripped
7. Proper capitalization: Words are capitalized appropriately

Example Transformations

Troubleshooting

Common Issues

Debug Information

For troubleshooting sort issues, enable debug mode:

// Enable debug logging for sort operations
localStorage.setItem('bookmark-sort-debug', 'true')

This will log detailed information about sort operations, performance metrics, and preference handling.

Implementation Details

Core Algorithm

The multi-criteria sorting uses a sophisticated comparison function:

function compareBookmarks(a: Bookmark, b: Bookmark, criteria: SortCriterion[]): number {
  for (const criterion of criteria.sort((a, b) => a.priority - b.priority)) {
    const result = compareByCriterion(a, b, criterion);
    if (result !== 0) {
      return criterion.direction === 'desc' ? -result : result;
    }
  }
  return 0; // Equal on all criteria
}

Field-Specific Comparisons

Each sorting field uses optimized comparison logic:

• Title/Description: localeCompare() for proper Unicode and locale handling
• Timestamp/Creation Date: Numeric comparison for precise ordering
• Tags: Concatenated string comparison with consistent separator handling
• Media File Name: Processed filename comparison with intelligent cleanup

Future Enhancements

Planned improvements for upcoming releases:

• Drag-and-drop priority reordering: Visual priority management
• Custom sort orders: User-defined sort templates and presets
• Sort performance indicators: Visual feedback for sort complexity
• Additional sort fields: Duration, file size, path depth
• Advanced sort expressions: Formula-based sorting with custom logic
• Sort presets: Save and share common sort configurations

For technical questions about the sorting implementation, please open an issue on the project repository.