Cross Player

A powerful media player plugin for Obsidian focused on seamless playback across desktop and mobile devices. It transforms a local folder into a managed playback queue so you can keep watching and listening wherever you are, with support for video and audio files, advanced playback controls, YouTube downloading, and storage management.

Features

📺 Media Playback

• Cross-Device Focus: Built first and foremost to let you keep playback flowing across desktop and mobile devices inside the same vault.
• Universal Player: Supports a wide range of formats.
  • Audio: mp3, wav, ogg, opus, m4a, m4b, weba, flac, aac, aif, aiff, caf.
  • Video: mp4, webm, ogv, mkv, 3gp.
• Enhanced Audio Experience: Audio files feature a dedicated placeholder with a music icon and file name, keeping the interface clean and informative.
• Smart Resume: Automatically resumes where you left off. New files start paused; in-progress files auto-play.
• Auto-play Next: Automatically plays the next unread item in the queue when the current one finishes (configurable).
• Variable Speed: Adjustable playback speed (default 2x) with persistence per session.
• Subtitle Support:
  • Supports sidecar .vtt and .srt files (must have the same name as the media file).
  • Automatically detects and enables embedded subtitle tracks.
  • Note: MKV embedded subtitles (PGS/ASS) may have limited native browser support.
• Seek Controls: Customizable forward/backward seek intervals.

📱 Mobile Experience

• Unified Touch Overlay: Large, touch-friendly controls for both Audio and Video files.
• Smart Gestures:
  • Tap Video: Pauses playback and reveals the control overlay.
  • Tap Background: Hides the overlay immediately.
  • Safe Progress Strip: Hidden mobile controls no longer capture taps until the overlay is visible again.
• Theme Adaptive: Overlay buttons automatically switch between Light and Dark modes to match your system/app theme.
• Conflict Free: Native play buttons are hidden on mobile to prevent accidental double-triggering and visual clutter.

📋 Queue Management

• Watched Folder: Automatically monitors a specific folder (and subfolders) for new media.
• Progress Tracking:
  • Visual indicators for completed, playing, and pending items.
  • Progress Background: Optional setting to show playback progress as a subtle background color in the queue list.
• Sort Queue: Sort by Name, Type, or Size (Ascending/Descending).
• Drag & Drop: Reorder your queue manually to prioritize content. Optimized for mobile touch dragging.
• Visual Indicators: Distinct icons for audio (headphones) and video (film) files (toggleable in settings).
• ETC & Storage: Displays "Estimated Time to Complete" based on current playback speed and warns when storage limits are exceeded.
• Sleep Timer: Pause playback after a set number of minutes, or stop after the current file, straight from the queue header. The countdown stays visible in the header while the timer is active.

⬇️ YouTube Integration

• Built-in Downloader: Download videos or audio directly from YouTube using yt-dlp.
• Batch Processing: Paste multiple links (one per line) to queue several downloads at once.
• Quality Options: Choose between Video (Best, 1080p, 720p, 480p) or Audio-only (mp3).
• Collapsible Progress: Monitor active downloads in a dedicated, collapsible section at the bottom of the queue.

For Android users, please note that you should use Seal for downloading YouTube videos, as this feature does not work on mobile.

🧹 Maintenance

• Clean Consumed: One-click command to permanently delete all completed files from disk to free up space.
• Storage Limits: Set a maximum storage limit (GB) to get visual warnings when your queue gets too big.

Usage

1. Setup:
   • Go to Settings > Cross Player.
   • Set your Watched Folder (absolute path).
   • To use the downloader, install yt-dlp and ffmpeg (both are mandatory) and make sure they are on your PATH. You can also set custom binary paths in settings.
2. Queue:
   • Open "Cross Player" from the ribbon icon or command palette.
   • Files from your watched folder appear automatically.
3. Playback:
   • Click an item to play it in the main view.
   • Use the player controls, the left/right arrow keys, or commands to seek and change speed.
   • Move between desktop and mobile with the same vault to continue playback with synced queue state and progress.
   • On mobile, tap the video area to pause and show large overlay controls.

Commands

• Open Cross Player: Opens the queue view.
• Download YouTube Video: Opens the modal to paste YouTube links.
• Clean Consumed Media: Permanently deletes all files marked as "completed".
• Reload Data from Disk: Manually re-loads data and scans the folder for new files.
• Set Watched Folder: Picker to select a folder via UI.
• Increase/Decrease Playback Speed: Adjust speed by 0.1x steps.
• Go to Next/Previous File: Skip through your queue.
• Delete Current File: Permanently delete the currently playing file immediately.
• Set Current File as Unread: Reset status to pending.
• Toggle Fullscreen: Enter or exit fullscreen mode.
• Toggle Subtitles: Enable/disable subtitle tracks.
• Switch Subtitle Track: Cycle through available subtitle tracks.
• Set Sleep Timer: Opens the queue and shows the sleep timer menu.
• Cancel Sleep Timer: Turns off an active sleep timer (hidden when no timer is active).
• Test yt-dlp Configuration: Verify that yt-dlp is correctly installed and accessible (Desktop only).

Settings

General Settings

• Watched Folder: The absolute path to your media folder.
• Default Playback Speed: Speed to start new files at.
• Auto-play Next: Toggle automatic playback of the next unread item.
• Sleep Timer Presets: Comma-separated minutes shown in the sleep timer menu (leave empty to only offer Custom and End of current file).
• Seek Intervals: Custom seconds used by the left/right arrow keys and the on-screen seek buttons.
• Show Media Indicator: Toggle audio/video icons in the queue.
• Show Progress Color: Toggle the background progress bar in the queue list.

Storage & Download Settings

• yt-dlp Path: Path to the yt-dlp executable.
• FFmpeg Path: Path to the ffmpeg executable. Leave empty to use the one on your PATH.
• Download Folder: Where to save YouTube downloads (defaults to watched folder).
• Default Quality/Type: Set your preferred download format.
• Storage Limit: Warning threshold in GB.

Requirements

• Obsidian: Latest version recommended.
• yt-dlp AND ffmpeg are both mandatory for YouTube downloads. yt-dlp fetches the media; ffmpeg is required for every audio-to-mp3 conversion and for merging video + audio into a single MP4.
• Both yt-dlp and ffmpeg must be on your PATH, or configured with their full executable paths in Settings > Cross Player. On macOS the plugin automatically adds /usr/local/bin and /opt/homebrew/bin to the PATH it uses.
• Desktop only: YouTube downloading is not available in the mobile app. Android users can use Seal instead.

Created for personal productivity and cross-device media consumption.