manpage: add section about using mpv from programs and scripts

Give an overview over the various methods. I feel like I've written text
like this over and over again (compatibility.rst and
interface-changes.rst for example duplicate the list of mpv API
abstractions), but such is life in hell.

Use this in particular to strongly suggest not to parse terminal output.
This suggestion got lost or de-emphasized at some point (maybe when
removing MPlayer and "slave mode" references). Some of this text is
still there, but it can be considered "fine print" at best, that nobody
will see. Now we have it in a more prominent place. This is especially
important since MPlayer-style use of mpv still seems to be prevalent,
see for example #7153.

1 files changed, 45 insertions, 0 deletions

diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 13e72dbfef..3eb46ebdff 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -636,6 +636,51 @@ and ``extension`` for the extension of the path of the currently played file
 
 This feature is very limited, and there are no other auto profiles.
 
+Using mpv from other programs or scripts
+========================================
+
+There are three choices for using mpv from other programs or scripts:
+
+    1. Calling it as UNIX process. If you do this, *do not parse terminal output*.
+       The terminal output is intended for humans, and may change any time. In
+       addition, terminal behavior itself may change any time. Compatibility
+       cannot be guaranteed.
+
+       Your code should work even if you pass ``--no-terminal``. Do not attempt
+       to simulate user input by sending terminal control codes to mpv's stdin.
+       If you need interactive control, using ``--input-ipc-server`` is
+       recommended. This gives you access to the `JSON IPC`_  over unix domain
+       sockets (or named pipes on Windows).
+
+       Depending on what you do, passing ``--no-config`` or ``--config-dir`` may
+       be a good idea to avoid conflicts with the normal mpv user configuration
+       intended for CLI playback.
+
+       Using ``--input-ipc-server`` is also suitable for purposes like remote
+       control (however, the IPC protocol itself is not "secure" and not
+       intended to be so).
+
+    2. Using libmpv. This is generally recommended when mpv is used as playback
+       backend for a completely different application. The provided C API is
+       very close to CLI mechanisms and the scripting API.
+
+       Note that even though libmpv has different defaults, it can be configured
+       to work exactly like the CLI player (except command line parsing is
+       unavailable).
+
+       See `EMBEDDING INTO OTHER PROGRAMS (LIBMPV)`_.
+
+    3. As a user script (`LUA SCRIPTING`_, `JAVASCRIPT`_, `C PLUGINS`_). This is
+       recommended when the goal is to "enhance" the CLI player. Scripts get
+       access to the entire client API of mpv.
+
+       This is the standard way to create third-party extensions for the player.
+
+All these access the client API, which is the sum of the various mechanisms
+provided by the player core, as documented here: `OPTIONS`_,
+`List of Input Commands`_, `Properties`_, `List of events`_ (also see C API),
+`Hooks`_.
+
 TAKING SCREENSHOTS
 ==================