The previous documentation was pretty scary and misleading, and was also outdated in several sections. It was also difficult to understand some of the paragraphs. The path documentation has now been overhauled to be much easier to understand and to document the latest mpv behavior.
Unified · Split
| @@ -499,41 +499,62 @@ console controls. (Which makes it suitable for playing data piped to stdin.) · 498 unmodified lines | ||
| 499 | 499 | The special argument ``--`` can be used to stop mpv from interpreting the |
| 500 | 500 | following arguments as options. |
| 501 | 501 | |
| 502 | −When using the client API, you should strictly avoid using ``mpv_command_string`` | |
| 502 | +For paths passed to mpv suboptions (options that have multiple `:` and | |
| 503 | +`,`-separated values), the situation is further complicated by the need to | |
| 504 | +escape special characters. To work around this, the path can instead be wrapped | |
| 505 | +in the "fixed-length" syntax, e.g. ``%n%string_of_length_n`` (see above). | |
| 506 | + | |
| 507 | +When using the libmpv API, you should strictly avoid using ``mpv_command_string`` | |
| 503 | 508 | for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command`` |
| 504 | 509 | to avoid the need for filename escaping. |
| 505 | 510 | |
| 506 | −For paths passed to suboptions, the situation is further complicated by the | |
| 507 | −need to escape special characters. To work this around, the path can be | |
| 508 | −additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n`` | |
| 509 | −(see above). | |
| 511 | +The same applies when you're using the scripting API, where you should avoid using | |
| 512 | +``mp.command``, and instead prefer using "separate parameter" APIs, such as | |
| 513 | +``mp.commandv`` and ``mp.command_native``. | |
| 514 | + | |
| 515 | +Some mpv options will interpret special meanings for paths starting with ``~``, | |
| 516 | +making it easy to dynamically find special directories, such as referring to the | |
| 517 | +current user's home directory or the mpv configuration directory. | |
| 518 | + | |
| 519 | +When using the special ``~`` prefix, there must always be a trailing ``/`` after | |
| 520 | +the special path prefix. In other words, ``~`` doesn't work, but ``~/`` will work. | |
| 521 | + | |
| 522 | +The following special paths/keywords are currently recognized: | |
| 523 | + | |
| 524 | +.. warning:: | |
| 525 | + | |
| 526 | + Beware that if ``--no-config`` is used, all of the "config directory"-based | |
| 527 | + paths (``~~/``, ``~~home/`` and ``~~global/``) will be empty strings. | |
| 528 | + | |
| 529 | + This means that ``~~home/`` would expand to an empty string, and that | |
| 530 | + sub-paths such as ``~~home/foo/bar"`` would expand to a relative path | |
| 531 | + (``foo/bar``), which may not be what you expected. | |
| 532 | + | |
| 533 | + Furthermore, any commands that search in config directories will fail | |
| 534 | + to find anything, since there won't be any directories to search in. | |
| 510 | 535 | |
| 511 | −Some mpv options interpret paths starting with ``~``. | |
| 512 | −Currently, the prefix ``~~home/`` expands to the mpv configuration directory | |
| 513 | −(usually ``~/.config/mpv/``). | |
| 514 | −``~/`` expands to the user's home directory. (The trailing ``/`` is always | |
| 515 | −required.) The following paths are currently recognized: | |
| 536 | + Be sure that your scripts can handle these "no config" scenarios. | |
| 516 | 537 | |
| 517 | 538 | ================ =============================================================== |
| 518 | 539 | Name Meaning |
| 519 | 540 | ================ =============================================================== |
| 520 | −``~~/`` If the subpath exists in any of the mpv's config directories | |
| 541 | +``~/`` The current user's home directory (equivalent to ``~/`` and | |
| 542 | + ``$HOME/`` in terminal environments). | |
| 543 | +``~~/`` If the sub-path exists in any of mpv's config directories, then | |
| 521 | 544 | the path of the existing file/dir is returned. Otherwise this |
| 522 | 545 | is equivalent to ``~~home/``. |
| 523 | − Note that if --no-config is used ``~~/foobar`` will resolve to | |
| 524 | − ``foobar`` which can be unexpected. | |
| 525 | −``~/`` user home directory root (similar to shell, ``$HOME``) | |
| 526 | −``~~home/`` mpv config dir (for example ``~/.config/mpv/``) | |
| 527 | −``~~global/`` the global config path, if available (not on win32) | |
| 528 | −``~~osxbundle/`` the macOS bundle resource path (macOS only) | |
| 529 | −``~~desktop/`` the path to the desktop (win32, macOS) | |
| 530 | −``~~exe_dir/`` win32 only: the path to the directory containing the exe (for | |
| 531 | − config file purposes; ``$MPV_HOME`` overrides it) | |
| 532 | −``~~cache/`` the path to application cache data (``~/.cache/mpv/``) | |
| 546 | +``~~home/`` mpv's config dir (for example ``~/.config/mpv/``). | |
| 547 | +``~~global/`` The global config path (such as ``/etc/mpv``), if available | |
| 548 | + (not on win32). | |
| 549 | +``~~osxbundle/`` The macOS bundle resource path (macOS only). | |
| 550 | +``~~desktop/`` The path to the desktop (win32, macOS). | |
| 551 | +``~~exe_dir/`` The path to the directory containing ``mpv.exe`` (for config | |
| 552 | + file purposes, ``$MPV_HOME`` will override this) (win32 only). | |
| 553 | +``~~cache/`` The path to application cache data (``~/.cache/mpv/``). | |
| 533 | 554 | On some platforms, this will be the same as ``~~home/``. |
| 534 | −``~~state/`` the path to application state data (``~/.local/state/mpv/``) | |
| 555 | +``~~state/`` The path to application state data (``~/.local/state/mpv/``). | |
| 535 | 556 | On some platforms, this will be the same as ``~~home/``. |
| 536 | −``~~old_home/`` do not use | |
| 557 | +``~~old_home/`` Do not use. | |
| 537 | 558 | ================ =============================================================== |
| 538 | 559 | |
| 539 | 560 | |