README file from
GithubCross Player for Obsidian
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
.vttand.srtfiles (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.
- Supports sidecar
- 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
- 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.
- Queue:
- Open "Cross Player" from the ribbon icon or command palette.
- Files from your watched folder appear automatically.
- 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 thatyt-dlpis 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-dlpexecutable. - FFmpeg Path: Path to the
ffmpegexecutable. Leave empty to use the one on yourPATH. - 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-dlpfetches the media;ffmpegis required for every audio-to-mp3 conversion and for merging video + audio into a single MP4. - Both
yt-dlpandffmpegmust be on yourPATH, or configured with their full executable paths in Settings > Cross Player. On macOS the plugin automatically adds/usr/local/binand/opt/homebrew/binto thePATHit 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.