osc docs: Add documentation for OSC and rename some options

camelCase from some of the option names removed. If you were using those, you'll have to update them in your config.

2 files changed, 194 insertions, 6 deletions

diff --git a/DOCS/man/en/osc.rst b/DOCS/man/en/osc.rst
new file mode 100644
index 0000000000..8218699778
--- /dev/null
+++ b/DOCS/man/en/osc.rst
@@ -0,0 +1,188 @@
+ON SCREEN CONTROLLER
+====================
+
+The On Screen Controller (short: OSC) is a minimal GUI integrated with mpv to
+offer basic mouse-controllability. It is intended to make interaction easier
+for new users and to enable precise and direct seeking.
+
+Using the OSC
+-------------
+
+By default, the OSC will show up whenever the mouse is moved inside the
+player window and will hide if the mouse is not moved outside the OSC for
+0.5 seconds or if the mouse leaves the window.
+
+The Interface
+~~~~~~~~~~~~~
+
++------------------------------+-----------+--------------------------------+
+| playlist prev                |   title   |                  playlist next |
++-------+-----------+----------++------+---+-------+-----------+------------+
+| audio |           |           |      |           |           |            |
++-------+ skip back | seek back | play | seek frwd | skip frwd | fullscreen |
+| sub   |           |           |      |           |           |            |
++-------+-----------+-----------+------+-----------+-----------+------------+
+|                                 seekbar                                   |
++-----------------------------+--------------+------------------------------+
+| time passed                 | cache status |               time remaining |
++-----------------------------+--------------+------------------------------+
+
+
+playlist prev
+    =============   ================================================
+    left-click      play previous file in playlist
+    shift+L-click   show playlist
+    =============   ================================================
+
+title
+    | Displays current media-title or filename
+    =============   ================================================
+    left-click      show playlist position and length and full title
+    right-click     show filename
+    =============   ================================================
+
+playlist next
+    =============   ================================================
+    left-click      play next file in playlist
+    shift+L-click   show playlist
+    =============   ================================================
+
+audio and sub
+    | Displays selected track and amount of available tracks
+    =============   ================================================
+    left-click      cycle audio/sub tracks forward
+    right-click     cycle audio/sub tracks backwards
+    shift+L-click   show available audio/sub tracks
+    =============   ================================================
+
+skip back
+    =============   ================================================
+    left-click      go to beginning of chapter / previous chapter
+    shift+L-click   show chapters
+    =============   ================================================
+
+seek back
+    =============   ================================================
+    left-click      skip back  5 seconds
+    right-click     skip back 30 seconds
+    shift-L-click   skip back  1 frame
+    =============   ================================================
+
+play
+    =============   ================================================
+    left-click      toggle play/pause
+    =============   ================================================
+
+seek frwd
+    =============   ================================================
+    left-click      skip forward 10 seconds
+    right-click     skip forward 60 seconds
+    shift-L-click   skip forward  1 frame
+    =============   ================================================
+
+skip frwd
+    =============   ================================================
+    left-click      go to next chapter
+    shift+L-click   show chapters
+    =============   ================================================
+
+fullscreen
+    =============   ================================================
+    left-click      toggle fullscreen
+    =============   ================================================
+
+seekbar
+    | Indicates current playback position and position of chapters
+    =============   ================================================
+    left-click      seek to position
+    =============   ================================================
+
+time passed
+    | Shows current playback position timestamp
+    =============   ================================================
+    left-click      toggle displaying timecodes with milliseconds
+    =============   ================================================
+
+cache status
+    | Shows current cache fill status (only visible when below 48%)
+
+time remaining
+    | Shows remaining playback time timestamp
+    =============   ================================================
+    left-click      toggle between total and remaining time
+    =============   ================================================
+
+
+Configuration
+-------------
+
+The OSC offers limited configuration through a config file ``plugin_osc.conf``
+placed in mpv's user dir.
+
+Config Syntax
+~~~~~~~~~~~~~
+
+The config file must exactly follow the following syntax::
+
+    # this is a comment
+    parameter1=value1
+    parameter2=value2
+
+``#`` can only be used at the beginning of a line and there may be no
+spaces around the ``=`` or anywhere else.
+
+Configurable parameters
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``showwindowed``
+    | Default: yes
+    | Show OSC when windowed?
+
+``showfullscreen``
+    | Default: yes
+    | Show OSC when fullscreen?
+
+``scalewindowed``
+    | Default: 1
+    | Scaling of the controller when windowed
+
+``scalefullscreen``
+    | Default: 1
+    | Scaling of the controller when fullscreen
+
+``scaleforcedwindow``
+    | Default: 2
+    | Scaling of the controller when rendered on a forced (dummy) window
+
+``vidscale``
+    | Default: yes
+    | Scale the controller with the video?
+
+``valign``
+    | Default: 0.8
+    | Vertical alignment, -1 (top) to 1 (bottom)
+
+``halign``
+    | Default: 0
+    | Horizontal alignment, -1 (left) to 1 (right)
+
+``hidetimeout``
+    | Default: 500
+    | Duration in ms until the OSC hides if no mouse movement, negative value
+      disables auto-hide
+
+``fadeduration``
+    | Default: 200
+    | Duration of fade out in ms, 0 = no fade
+
+``deadzonesize``
+    | Default: 0
+    | Size of the deadzone. The deadzone is an area that makes the mouse act
+      like leaving the window. Movement there won't make the OSC show up and
+      it will hide immediately if the mouse enters it.
+
+``minmousemove``
+    | Default: 3
+    | Minimum amount of pixels the mouse has to move between ticks to make
+      the OSC show up
+
diff --git a/mpvcore/lua/osc.lua b/mpvcore/lua/osc.lua
index 19bd8c90fe..5df43b8e2e 100644
--- a/mpvcore/lua/osc.lua
+++ b/mpvcore/lua/osc.lua
@@ -10,11 +10,11 @@ local msg = require 'mp.msg'
 -- default user option values
 -- do not touch, change them in plugin_osc.conf
 local user_opts = {
-    showWindowed = true,                    -- show OSC when windowed?
-    showFullscreen = true,                  -- show OSC when fullscreen?
-    scaleWindowed = 1,                      -- scaling of the controller when windowed
-    scaleFullscreen = 1,                    -- scaling of the controller when fullscreen
-    scaleForcedWindow = 2,                  -- scaling of the controller when rendered on a forced (dummy) window
+    show-windowed = true,                    -- show OSC when windowed?
+    show-fullscreen = true,                  -- show OSC when fullscreen?
+    scale-windowed = 1,                      -- scaling of the controller when windowed
+    scale-fullscreen = 1,                    -- scaling of the controller when fullscreen
+    scale-forcedwindow = 2,                  -- scaling of the controller when rendered on a forced (dummy) window
     vidscale = true,                        -- scale the controller with the video?
     valign = 0.8,                           -- vertical alignment, -1 (top) to 1 (bottom)
     halign = 0,                             -- horizontal alignment, -1 (left) to 1 (right)
@@ -22,7 +22,7 @@ local user_opts = {
     fadeduration = 200,                     -- duration of fade out in ms, 0 = no fade
     deadzonesize = 0,                       -- size of deadzone
     minmousemove = 3,                       -- minimum amount of pixels the mouse has to move between ticks to make the OSC show up
-    iAmAProgrammer = false,                 -- use native mpv values and disable OSC internal playlist management (and some functions that depend on it)
+    iamaprogrammer = false,                 -- use native mpv values and disable OSC internal playlist management (and some functions that depend on it)
 }
 
 local osc_param = {