Skip to main content

Overview

StreamVault uses MPV as its primary video player for:
  • Native playback of all formats (MKV, MP4, AVI, HDR, etc.)
  • No transcoding required
  • Resume playback tracking via IPC
  • Subtitle and audio track selection
  • Hardware acceleration support
MPV is a free, open-source media player known for high-quality video playback and extensive format support.

Supported Formats

MPV supports all common video formats:
FormatExtensionNotes
Matroska.mkvPreferred for high-quality rips
MPEG-4.mp4, .m4vUniversal compatibility
AVI.aviLegacy format
QuickTime.movmacOS native
WebM.webmWeb-optimized
Windows Media.wmvWindows native
Flash Video.flvLegacy streaming
MPEG-TS.ts, .m2tsBroadcast/Blu-ray
From database.rs:773-782:
AND (file_path LIKE '%.mkv'
     OR file_path LIKE '%.mp4'
     OR file_path LIKE '%.avi'
     OR file_path LIKE '%.mov'
     OR file_path LIKE '%.webm'
     OR file_path LIKE '%.m4v'
     OR file_path LIKE '%.wmv'
     OR file_path LIKE '%.flv'
     OR file_path LIKE '%.ts'
     OR file_path LIKE '%.m2ts')

Installation by Platform

Option 1: Official Installer

1

Download MPV

2

Run Installer

  • Download the latest 64-bit installer
  • Run the .exe file
  • Follow the installation wizard
  • Choose installation directory (default: C:\Program Files\mpv\)
3

Add to PATH (Optional)

To make MPV accessible from any terminal:
  1. Press Win + XSystemAdvanced system settings
  2. Click Environment Variables
  3. Under System variables, select PathEdit
  4. Click New and add: C:\Program Files\mpv\
  5. Click OK on all dialogs

Option 2: Package Managers

Scoop

scoop install mpv

Chocolatey

choco install mpv
StreamVault automatically searches Scoop and Chocolatey installation paths.

Auto-Detection in StreamVault

StreamVault automatically searches for MPV on Windows in these locations (from config.rs:10-29):
const MPV_SEARCH_PATHS: &[&str] = &[
    // Common installation directories
    "C:\\Program Files\\mpv\\mpv.exe",
    "C:\\Program Files (x86)\\mpv\\mpv.exe",
    "C:\\Program Files\\mpv.net\\mpv.exe",
    "C:\\Program Files (x86)\\mpv.net\\mpv.exe",
    // Scoop installations
    "C:\\Users\\*\\scoop\\apps\\mpv\\current\\mpv.exe",
    "C:\\Users\\*\\scoop\\shims\\mpv.exe",
    // Chocolatey
    "C:\\ProgramData\\chocolatey\\bin\\mpv.exe",
    // Portable installations
    "C:\\mpv\\mpv.exe",
    "C:\\Tools\\mpv\\mpv.exe",
    "D:\\mpv\\mpv.exe",
    "D:\\Tools\\mpv\\mpv.exe",
    // User profile locations
    "C:\\Users\\*\\AppData\\Local\\Programs\\mpv\\mpv.exe",
    "C:\\Users\\*\\mpv\\mpv.exe",
];

Detection Process

From config.rs:33-80:
pub fn find_mpv_executable() -> Option<String> {
    println!("[MPV] Searching for mpv.exe on the system...");

    // First, check if mpv is in PATH (fastest check)
    if let Ok(output) = Command::new("where").arg("mpv.exe").output() {
        if output.status.success() {
            if let Ok(path) = String::from_utf8(output.stdout) {
                let path = path.lines().next().unwrap_or("").trim();
                if !path.is_empty() && Path::new(path).exists() {
                    println!("[MPV] Found mpv in PATH: {}", path);
                    return Some(path.to_string());
                }
            }
        }
    }

    // Check common installation paths
    for pattern in MPV_SEARCH_PATHS {
        if pattern.contains('*') {
            // Handle wildcard patterns (for user-specific paths)
            if let Some(found) = expand_and_check_pattern(pattern) {
                println!("[MPV] Found mpv at: {}", found);
                return Some(found);
            }
        } else if Path::new(pattern).exists() {
            println!("[MPV] Found mpv at: {}", pattern);
            return Some(pattern.to_string());
        }
    }

    println!("[MPV] mpv.exe not found on the system");
    None
}

Configuring MPV Path in Settings

1

Open Settings

Click the Settings gear icon → General section
2

Auto-Detect (Recommended)

Click the Detect button next to the MPV Path field. StreamVault will:
  • Search all common installation locations
  • Check system PATH
  • Display the found path if detected
From SettingsModal.tsx:327-354:
const handleAutoDetectMpv = async () => {
  setDetectingMpv(true)
  try {
    const foundPath = await autoDetectMpv()
    if (foundPath) {
      setConfig({ ...config, mpv_path: foundPath })
      toast({
        title: "MPV Found",
        description: `Detected at: ${foundPath}`
      })
    } else {
      toast({
        title: "MPV Not Found",
        description: "Could not find mpv.exe. Please install MPV or set path manually.",
        variant: "destructive"
      })
    }
  } finally {
    setDetectingMpv(false)
  }
}
3

Manual Entry (Alternative)

If auto-detection fails:
  1. Click the Browse folder icon
  2. Navigate to your MPV installation
  3. Select mpv.exe (Windows) or mpv binary (Linux/macOS)
  4. Click Open
4

Save Configuration

Click Save to persist the MPV path to media_config.json

IPC Configuration

StreamVault communicates with MPV using a Lua script for progress tracking.

Progress Tracking Script

From mpv_ipc.rs:32-130:
-- StreamVault Progress Tracker for MPV
-- Saves playback position to a JSON file periodically and on quit

local progress_file = "%APPDATA%/StreamVault/mpv_progress/{media_id}.json"
local save_interval = 2 -- seconds

local function get_progress_data()
    local pos = mp.get_property_number("time-pos")
    local duration = mp.get_property_number("duration")
    local paused = mp.get_property_bool("pause") or false
    local eof = mp.get_property_bool("eof-reached") or false
    
    return string.format(
        '{"position":%.3f,"duration":%.3f,"paused":%s,"eof_reached":%s}',
        pos, duration,
        paused and "true" or "false",
        eof and "true" or "false"
    )
end

local function save_progress()
    local data = get_progress_data()
    local file = io.open(progress_file, "w")
    if file then
        file:write(data)
        file:close()
    end
end

-- Periodic save timer (every 2 seconds)
local timer = mp.add_periodic_timer(save_interval, save_progress)

-- Save on pause/unpause
mp.observe_property("pause", "bool", save_progress)

-- Save on seek
mp.register_event("seek", save_progress)

-- Save on quit - most important!
mp.register_event("shutdown", save_progress)

-- Save when file ends
mp.register_event("end-file", save_progress)

How Resume Works

1

Playback Starts

StreamVault launches MPV with the Lua script:
mpv --script=tracker_{media_id}.lua --start={resume_position} video.mp4
2

Progress Saved

Every 2 seconds, the script writes:
{
  "position": 1234.567,
  "duration": 7200.0,
  "paused": false,
  "eof_reached": false,
  "quit_time": 1678901234
}
3

On Exit

When you close MPV, the shutdown event triggers a final save
4

Resume Next Time

StreamVault reads the saved position and resumes from that point
Progress is cleared automatically when you watch 95% or more of the video.

Cloud Streaming with Disk Cache

For Google Drive streaming, MPV can use disk caching to improve playback. From mpv_ipc.rs:181-188:
pub struct CloudCacheSettings {
    pub enabled: bool,
    pub cache_dir: String,
    pub max_size_mb: u32,
}

Cache Configuration

In Settings → Cloud Storage:
  • Enable Cloud Cache: Toggles disk caching
  • Cache Directory: Custom cache location (default: %APPDATA%/StreamVault/cloud_cache/)
  • Max Cache Size: Per-movie cache limit (default: 1024 MB = 1 GB)
  • Cache Expiry: Auto-cleanup after 24 hours
From config.rs:186-192:
#[serde(default)]
pub cloud_cache_enabled: bool,
#[serde(default)]
pub cloud_cache_dir: Option<String>,
#[serde(default = "default_cloud_cache_max_mb")]
pub cloud_cache_max_mb: u32,

Troubleshooting

  • Run auto-detection in Settings → General
  • Verify MPV is installed: Open terminal and run mpv --version
  • Manually browse to mpv.exe location
  • Add MPV to system PATH (see installation steps above)
  • Check MPV path is correct in settings
  • Verify file exists and isn’t corrupted
  • Test MPV manually: mpv "path\to\video.mp4"
  • Check Developer Console for error messages
  • Ensure Lua script is loading (check MPV console: ` key)
  • Verify progress directory exists: %APPDATA%/StreamVault/mpv_progress/
  • Check file permissions (script needs write access)
  • Clear old progress: Settings → Advanced → Clean Up Missing Titles
MPV auto-loads subtitles in the same directory as the video. To manually load:
  • Press v during playback to cycle subtitle tracks
  • Drag and drop .srt file onto MPV window
  • Use MPV config file (%APPDATA%/mpv/mpv.conf) to set default subtitle preferences
Edit %APPDATA%/mpv/mpv.conf to configure GPU acceleration:
# Use hardware decoding
hwdec=auto-safe

# Force specific GPU API (if auto fails)
# hwdec=d3d11va  # Windows (Direct3D)
# hwdec=videotoolbox  # macOS
# hwdec=vaapi  # Linux

Advanced MPV Configuration

Custom Config File

Create %APPDATA%/mpv/mpv.conf (Windows) or ~/.config/mpv/mpv.conf (Linux/macOS):
# Video
hwdec=auto-safe              # Hardware decoding
vo=gpu                         # GPU video output
profile=gpu-hq                 # High quality GPU rendering

# Audio
audio-file-auto=fuzzy          # Auto-load audio files
volume=100                     # Default volume

# Subtitles
sub-auto=fuzzy                 # Auto-load subtitle files
sub-font-size=45               # Subtitle size
sub-color="#FFFFFF"            # White text
sub-border-size=2              # Black border

# Performance
cache=yes                      # Enable cache
demuxer-max-bytes=500M         # Max cache size
demuxer-max-back-bytes=100M    # Backward cache

# UI
osc=yes                        # On-screen controller
osd-bar=yes                    # Progress bar

Key Bindings

Default MPV shortcuts:
KeyAction
SpacePlay/Pause
/ Seek forward/backward 5s
/ Volume up/down
fToggle fullscreen
vCycle subtitle tracks
#Cycle audio tracks
sScreenshot
`Show console (debug)
qQuit

Next Steps

TMDB Setup

Configure metadata API

Google Drive Setup

Connect cloud storage

Cloud Streaming

Stream from Google Drive

Playback Features

Resume and progress tracking

Build docs developers (and LLMs) love