From d302fe0de55aeb40e398d1b162f9636eaf07530c Mon Sep 17 00:00:00 2001
From: nanahi <130121847+na-na-hi@users.noreply.github.com>
Date: Fri, 2 Aug 2024 01:26:49 -0400
Subject: [PATCH] DOCS/man/input: reserve user-data/osc and user-data/mpv
 sub-paths

Currently user-data/osc is used for interpolation between the osc and
other internal scripts. Reserve this sub-path and also user-data/mpv
to make sure external scripts can only use these values as directed.
New internal uses of user-data should use user-data/mpv instead.
---
 DOCS/interface-changes/user-data-subpath.txt | 1 +
 DOCS/man/input.rst                           | 6 ++++++
 2 files changed, 7 insertions(+)
 create mode 100644 DOCS/interface-changes/user-data-subpath.txt

diff --git a/DOCS/interface-changes/user-data-subpath.txt b/DOCS/interface-changes/user-data-subpath.txt
new file mode 100644
index 0000000000..160d9fb0fe
--- /dev/null
+++ b/DOCS/interface-changes/user-data-subpath.txt
@@ -0,0 +1 @@
+reserve `user-data/osc` and `user-data/mpv` sub-paths for internal use
diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index 0b279f1c1c..8ddd196ad9 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -3549,6 +3549,12 @@ Property list
     The player itself does not use any data in it (although some builtin scripts may).
     The property is not preserved across player restarts.
 
+    The following sub-paths are reserved for internal uses or have special semantics:
+    ``user-data/osc``, ``user-data/mpv``. Unless noted otherwise, the semantics of
+    any properties under these sub-paths can change at any time and may not be relied
+    upon, and writing to these properties may prevent builtin scripts from working
+    properly.
+
     Sub-paths can be accessed directly; e.g. ``user-data/my-script/state/a`` can be
     read, written, or observed.