TOOLS: better documentation of lua scripts

3 files changed, 66 insertions, 0 deletions

diff --git a/TOOLS/lua/README.md b/TOOLS/lua/README.md
new file mode 100644
index 0000000000..fbe4bad267
--- /dev/null
+++ b/TOOLS/lua/README.md
@@ -0,0 +1,19 @@
+mpv lua scripts
+===============
+
+The lua scripts in this folder can be loaded on a one-time basis by
+adding the option
+
+    --lua=/path/to/script.lua
+
+to mpv's command line.
+
+Unless otherwise specified, they are also suitable for inclusion in
+the `~/.mpv/lua` directory where they will be loaded every time mpv
+starts, obviating the need to load them with the above `--lua=...`
+argument. This is acceptable as they do only basic argument parsing
+and key-binding registration, until those bound keys are actually
+pressed.  They should therefore not interfere with normal playback
+(unless you have a conflicting user-defined key-binding, in which
+case, you may want to modify either the `mp.add_key_binding()` calls
+in the scripts, or your keybinding).
diff --git a/TOOLS/lua/autocrop.lua b/TOOLS/lua/autocrop.lua
index 40dc6d1704..84c712e412 100644
--- a/TOOLS/lua/autocrop.lua
+++ b/TOOLS/lua/autocrop.lua
@@ -1,3 +1,31 @@
+-- This script uses the lavfi cropdetect filter to automatically
+-- insert a crop filter with appropriate parameters for the currently
+-- playing video.
+--
+-- It registers the key-binding "C" (shift+c), which when pressed,
+-- inserts the filter vf=lavfi=cropdetect. After 1 second, it then
+-- inserts the filter vf=crop=w:h:x:y, where w,h,x,y are determined
+-- from the vf-metadata gathered by cropdetect. The cropdetect filter
+-- is removed immediately after the crop filter is inserted as it is
+-- no longer needed.
+--
+-- If the "C" key is pressed again, the crop filter is removed
+-- restoring playback to its original state.
+--
+-- Since the crop parameters are determined from the 1 second of video
+-- between inserting the cropdetect and crop filters, the "C" key
+-- should be pressed at a position in the video where the crop region
+-- is unambiguous (i.e., not a black frame, black background title
+-- card, or dark scene).
+--
+-- The default delay between insertion of the cropdetect and
+-- crop filters may be overridden by adding
+--
+-- --lua-opts=autocrop.detect_seconds=<number of seconds>
+--
+-- to mpv's arguments. This may be desirable to allow cropdetect more
+-- time to collect data.
+
 script_name=string.gsub(mp.get_script_name(),"lua/","")
 cropdetect_label=string.format("%s-cropdetect",script_name)
 crop_label=string.format("%s-crop",script_name)
diff --git a/TOOLS/lua/drc-control.lua b/TOOLS/lua/drc-control.lua
index 71755d4dfb..f0a6ff2721 100644
--- a/TOOLS/lua/drc-control.lua
+++ b/TOOLS/lua/drc-control.lua
@@ -1,3 +1,22 @@
+-- This script enables live control of the dynamic range compression
+-- (drc) audio filter while the video is playing back. This can be
+-- useful to avoid having to stop and restart mpv to adjust filter
+-- parameters. See the entry for "drc" under the "AUDIO FILTERS"
+-- section of the man page for a complete description of the filter.
+--
+-- This script registers the key-binding "\" to toggle the filter between 
+--
+-- * off
+-- * method=1 (single-sample smoothing)
+-- * method=2 (multi-sample smoothing)
+--
+-- It registers the keybindings ctrl+9/ctrl+0 to decrease/increase the
+-- target ampltiude. These keys will insert the filter at the default
+-- target amplitude of 0.25 if it was not previously present.
+--
+-- OSD feedback of the current filter state is displayed on pressing
+-- each bound key.
+
 script_name=mp.get_script_name():gsub("lua/","",1)
 
 function print_state(params)