id       = "mpv"
name     = "mpv"
homepage = "https://mpv.io"
description = "a free, open source, and cross-platform media player"
icon     = "SimpleIcons:mpv"
executables   = ["mpv"]

[dotfiles]

# The mpv manual's FILES section (https://mpv.io/manual/stable/#files):
# ~/.config/mpv is the config directory, overridable with $XDG_CONFIG_HOME or
# $MPV_HOME, and ~/.mpv/ is the pre-0.5.0 location mpv still reads. FILES ON
# WINDOWS puts the same directory at %APPDATA%/mpv/. mpv follows the XDG spec
# on macOS too — the manual gives no ~/Library path — so the config directory
# is one place under three names, which is what [configHome] stands for.
#
# The named files inside it are all in that section: mpv.conf (user settings),
# input.conf (key bindings), fonts.conf, subfont.ttf, scripts/ (auto-loaded
# scripts), script-opts/ and fonts/. The directory is listed whole rather than
# file by file, because a user's scripts are as much their configuration as
# mpv.conf is.
paths = [
  "[configHome]/mpv/",
  "~/.mpv/",
]

# watch_later is the resume-playback bookkeeping — one file per media file the
# user stopped part-way through, keyed by that file's path on this machine.
# Current mpv keeps it at ~/.local/state/mpv/watch_later/ and
# %LOCALAPPDATA%/mpv/watch_later, neither of which is inside the directories
# above; older versions kept it in the config directory itself, which is the
# copy carved out here. %LOCALAPPDATA%/mpv/cache is named for the same reason
# even though nothing above contains it.
exclude = [
  "[configHome]/mpv/watch_later/",
  "~/.mpv/watch_later/",
  "%LOCALAPPDATA%/mpv/watch_later/",
  "%LOCALAPPDATA%/mpv/cache/",
]

# mpv signs in to nothing; there is no credential file in the config directory.
secret = []

# No machine_lines. mpv.conf is profiles, output settings, subtitle and
# keybinding preferences — what a user wants on their other machine. The
# options that do name this machine's disk (--screenshot-directory,
# --watch-later-dir) are set by the few users who set them, and blanking a
# line the user wrote deliberately would be worse than carrying it.

[commands]
format = 1
label = "Play media"
description = "Play one or more files or URLs with common startup options. Video output, filters, shaders and scripting options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "manual"
kind = "manual"
url = "https://mpv.io/manual/stable/"
revision = "master 2026-10"
evidence = """
--start=<relative time>
--speed=<0.01-100>
--volume=<value>
--mute=<yes|no>  Set startup audio mute status (default: no). e.g. --mute=yes
--pause
--loop-file=<N|inf|no>, --loop=<N|inf|no>
--loop-playlist=<N|inf|force|no>, --loop-playlist
--shuffle=<yes|no>
--sub-file=<filename>
--audio-file=<file>
--really-quiet
--no-config
--fs
--ontop
--title=<string>
--geometry=<[W[xH]][+-x+-y][/WS]>, --geometry=<x:y>
"""

[[commands.field]]
id = "files"
label = "Files or URLs"
type = "string"
position = 0
multiple = true
sources = ["manual"]

[[commands.field]]
id = "start"
label = "Start at"
description = "Time as [[hh:]mm:]ss[.ms]; a leading - counts from the end."
type = "string"
option = ["--start"]
sources = ["manual"]

[[commands.field]]
id = "speed"
label = "Speed"
type = "number"
option = ["--speed"]
sources = ["manual"]

[[commands.field]]
id = "volume"
label = "Startup volume"
type = "number"
option = ["--volume"]
sources = ["manual"]

[[commands.field]]
id = "mute"
label = "Start muted"
type = "boolean"
option = ["--mute=yes"]
sources = ["manual"]

[[commands.field]]
id = "pause"
label = "Start paused"
type = "boolean"
option = ["--pause"]
sources = ["manual"]

[[commands.field]]
id = "loop_file"
label = "Loop file"
description = "A count, inf, or no."
type = "string"
option = ["--loop-file"]
suggestions = [{ value = "inf", label = "Forever" }, { value = "no", label = "No" }]
sources = ["manual"]

[[commands.field]]
id = "fullscreen"
label = "Fullscreen"
type = "boolean"
option = ["--fs"]
sources = ["manual"]

[[commands.field]]
id = "sub_file"
label = "Subtitle file"
type = "path"
option = ["--sub-file"]
path = { kind = "file", role = "input" }
sources = ["manual"]

[[commands.field]]
id = "audio_file"
label = "External audio file"
type = "path"
option = ["--audio-file"]
path = { kind = "file", role = "input" }
sources = ["manual"]

[[commands.field]]
id = "no_config"
label = "Ignore config files"
type = "boolean"
option = ["--no-config"]
sources = ["manual"]

[[commands.task]]
id = "play"
label = "Play"
fields = ["files", "start", "speed", "volume", "fullscreen", "sub_file"]
required = ["files"]

[[commands.task]]
id = "loop"
label = "Loop a file"
set = { loop_file = ["inf"] }
fields = ["files", "loop_file", "volume", "pause"]
required = ["files"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["files", "start", "speed", "volume", "mute", "pause", "loop_file", "fullscreen"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["sub_file", "audio_file", "no_config"]