DOCS/input: document subprocess more clearly

- Make it clearer that playback_only affects subprocess' behavior when
  the playback of the current playlist entry terminates, rather than
  when mpv quits.
- Explain when status is positive and when it is negative.
- Replace "exited gracefully" in status' and error_string's
  documentation with "terminated normally" so it can't be misinterpreted
  as exiting successfully.
- Reword the playback_only warning
This commit is contained in:
Guido Cella 2022-02-18 18:30:31 +01:00 committed by avih
parent b89ca0c552
commit beac97ba07
1 changed files with 22 additions and 18 deletions

View File

@ -551,9 +551,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
``playback_only`` (``MPV_FORMAT_FLAG``) ``playback_only`` (``MPV_FORMAT_FLAG``)
Boolean indicating whether the process should be killed when playback Boolean indicating whether the process should be killed when playback
terminates (optional, default: true). If enabled, stopping playback of the current playlist entry terminates (optional, default: true). If
will automatically kill the process, and you can't start it outside of enabled, stopping playback will automatically kill the process, and you
playback. can't start it outside of playback.
``capture_size`` (``MPV_FORMAT_INT64``) ``capture_size`` (``MPV_FORMAT_INT64``)
Integer setting the maximum number of stdout plus stderr bytes that can Integer setting the maximum number of stdout plus stderr bytes that can
@ -600,12 +600,14 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
The command returns the following result (as ``MPV_FORMAT_NODE_MAP``): The command returns the following result (as ``MPV_FORMAT_NODE_MAP``):
``status`` (``MPV_FORMAT_INT64``) ``status`` (``MPV_FORMAT_INT64``)
The raw exit status of the process. It will be negative on error. The Typically this is the process exit code (0 or positive) if the process
meaning of negative values is undefined, other than meaning error (and terminates normally, or negative for other errors (failed to start,
does not correspond to OS low level exit status values). terminated by mpv, and others). The meaning of negative values is
undefined, other than meaning error (and does not correspond to OS low
level exit status values).
On Windows, it can happen that a negative return value is returned On Windows, it can happen that a negative return value is returned even
even if the process exits gracefully, because the win32 ``UINT`` exit if the process terminates normally, because the win32 ``UINT`` exit
code is assigned to an ``int`` variable before being set as ``int64_t`` code is assigned to an ``int`` variable before being set as ``int64_t``
field in the result map. This might be fixed later. field in the result map. This might be fixed later.
@ -616,9 +618,9 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
Same as ``stdout``, but for stderr. Same as ``stdout``, but for stderr.
``error_string`` (``MPV_FORMAT_STRING``) ``error_string`` (``MPV_FORMAT_STRING``)
Empty string if the process exited gracefully. The string ``killed`` if Empty string if the process terminated normally. The string ``killed``
the process was terminated in an unusual way. The string ``init`` if the if the process was terminated in an unusual way. The string ``init`` if
process could not be started. the process could not be started.
On Windows, ``killed`` is only returned when the process has been On Windows, ``killed`` is only returned when the process has been
killed by mpv as a result of ``playback_only`` being set to true. killed by mpv as a result of ``playback_only`` being set to true.
@ -633,17 +635,19 @@ Remember to quote string arguments in input.conf (see `Flat command syntax`_).
it was somehow killed or returned an error status has to be queried from it was somehow killed or returned an error status has to be queried from
the result value. the result value.
This command can be asynchronously aborted via API. This command can be asynchronously aborted via API. Also see `Asynchronous
command details`_. Only the ``run`` command can start processes in a truly
detached way.
In all cases, the subprocess will be terminated on player exit. Also see .. note:: The subprocess will always be terminated on player exit if it
`Asynchronous command details`_. Only the ``run`` command can start wasn't started in detached mode, even if ``playback_only`` is
processes in a truly detached way. false.
.. admonition:: Warning .. admonition:: Warning
Don't forget to set the ``playback_only`` field if you want the command Don't forget to set the ``playback_only`` field to false if you want
run while the player is in idle mode, or if you don't want that end of the command to run while the player is in idle mode, or if you don't
playback kills the command. want the end of playback to kill the command.
.. admonition:: Example .. admonition:: Example