docs: document new user-data property

1 files changed, 20 insertions, 0 deletions

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 280e30cc8c..3613fb7dac 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -3256,6 +3256,26 @@ Property list
     (There is no way to ensure synchronization if two scripts try to update the
     same key at the same time.)
 
+``user-data`` (RW)
+    This is a recursive key/value map of arbitrary nodes shared between clients for
+    general use (i.e. scripts, IPC clients, host applications, etc).
+    The player itself does not use any data in it (although some builtin scripts may).
+    The property is not preserved across player restarts.
+
+    This is a more powerful replacement for ``shared-script-properties``.
+
+    Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be
+    read, written, or observed.
+
+    The top-level object itself cannot be written directly; write to sub-paths instead.
+
+    Lua scripting has helpers starting with ``utils.user_data_``.
+
+    Converting this property or its sub-properties to strings will give a JSON
+    representation. If converting a leaf-level object (i.e. not a map or array)
+    and not using raw mode, the underlying content will be given (e.g. strings will be
+    printed directly, rather than quoted and JSON-escaped).
+
 ``working-directory``
     The working directory of the mpv process. Can be useful for JSON IPC users,
     because the command line player usually works with relative paths.