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 | The special argument ``--`` can be used to stop mpv from interpreting the | 499 | The special argument ``--`` can be used to stop mpv from interpreting the |
| 500 | following arguments as options. | 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 | for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command`` | 508 | for invoking the ``loadfile`` command, and instead prefer e.g. ``mpv_command`` |
| 504 | to avoid the need for filename escaping. | 509 | to avoid the need for filename escaping. |
| 505 | 510 | ||
| 506 | For paths passed to suboptions, the situation is further complicated by the | 511 | The same applies when you're using the scripting API, where you should avoid using |
| 507 | need to escape special characters. To work this around, the path can be | 512 | ``mp.command``, and instead prefer using "separate parameter" APIs, such as |
| 508 | additionally wrapped in the fixed-length syntax, e.g. ``%n%string_of_length_n`` | 513 | ``mp.commandv`` and ``mp.command_native``. |
| 509 | (see above). | 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 ``~``. | 536 | Be sure that your scripts can handle these "no config" scenarios. |
| 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: | ||
| 516 | 537 | ||
| 517 | ================ =============================================================== | 538 | ================ =============================================================== |
| 518 | Name Meaning | 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 | the path of the existing file/dir is returned. Otherwise this | 544 | the path of the existing file/dir is returned. Otherwise this |
| 522 | is equivalent to ``~~home/``. | 545 | is equivalent to ``~~home/``. |
| 523 | Note that if --no-config is used ``~~/foobar`` will resolve to | 546 | ``~~home/`` mpv's config dir (for example ``~/.config/mpv/``). |
| 524 | ``foobar`` which can be unexpected. | 547 | ``~~global/`` The global config path (such as ``/etc/mpv``), if available |
| 525 | ``~/`` user home directory root (similar to shell, ``$HOME``) | 548 | (not on win32). |
| 526 | ``~~home/`` mpv config dir (for example ``~/.config/mpv/``) | 549 | ``~~osxbundle/`` The macOS bundle resource path (macOS only). |
| 527 | ``~~global/`` the global config path, if available (not on win32) | 550 | ``~~desktop/`` The path to the desktop (win32, macOS). |
| 528 | ``~~osxbundle/`` the macOS bundle resource path (macOS only) | 551 | ``~~exe_dir/`` The path to the directory containing ``mpv.exe`` (for config |
| 529 | ``~~desktop/`` the path to the desktop (win32, macOS) | 552 | file purposes, ``$MPV_HOME`` will override this) (win32 only). |
| 530 | ``~~exe_dir/`` win32 only: the path to the directory containing the exe (for | 553 | ``~~cache/`` The path to application cache data (``~/.cache/mpv/``). |
| 531 | config file purposes; ``$MPV_HOME`` overrides it) | ||
| 532 | ``~~cache/`` the path to application cache data (``~/.cache/mpv/``) | ||
| 533 | On some platforms, this will be the same as ``~~home/``. | 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 | On some platforms, this will be the same as ``~~home/``. | 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 | ||