Version bump to 0.3.0 and README update

README.md

@@ -44,17 +44,16 @@ See the [Files section](https://mpv.io/manual/master/#files) in mpv's manual for
 
 In this file you may set the following options:
 ```ini
-# Output filename template, with path
-output_template=/home/amm/mpv_screenshots/%f %p %D%U.%x
-# Possible substitutions
-# %f - Original filename without extension - "A.Video.2017"
-# %X - Original extension - "mkv"
-# %x - Output extension   - "png"
-# %u - Unique - "", "_1", "_2", ...
-# %U - Unique - "", " 1", " 2", ...
-# %p - Current time - 00.03.50.423
-# %P - Current time without decimals - 00.03.50
-# %D - Crop size - 200x300, 123x450, full
+# The template for screenshot filenames. See below for explanation of the property expansion!
+# Can be an absolute or relative path (though relative paths are mostly untested)
+output_template=/home/amm/mpv_screenshots/${filename} ${#pos:%02h.%02m.%06.3s} ${!full:${crop_w}x${crop_h} ${%unique:%03d}}.png
+# The above template would expand to something like "Sintel.2010.1080p 00.05.40.500 200x400 001.png".
+# or just "Sintel.2010.1080p 00.05.40.500.png" for the full-size screenshots (if kept).
+# The template checks if 'full' is falsey, in which case it will expand the crop size and sequence number.
+
+# Whether to try and create missing directories when saving screenshots
+# (All directories will be created, not just the last section)
+create_directories=yes|no
 
 # Whether to keep the original full-size screenshot or not
 keep_original=yes|no
@@ -68,6 +67,78 @@ With `disable_keybind=yes`, you can add your own keybind to [`input.conf`](https
 shift+alt+s script-binding crop-screenshot
 ```
 
+## Property expansion
+
+This script's `output_template` mimics mpv's own [property expansion](https://mpv.io/manual/master/#property-expansion), but is not a 1:1 match. With it you can flexibly specify filenames and use lightweight logic (fallback expressions).  
+(This script does not handle `$$`, `$}` or `$>` in any special way, as there is no need to do so.)  
+The script provides a couple of properties, but you may also access all of [mpv's properties](https://mpv.io/manual/master/#property-list) by prefixing the property name with `mpv/`, eg. `${mpv/media-title}`.
+
+Tricky examples of the property expansion:
+
+`${#pos:%.3S}` will expand into the current second in the file, eg. `4213.310`.  
+`${&-:%Y}/${&-:%Y-%m}/${&-:%Y-%m-%d}/` store your screenshots into a subdirectory like `2017/2017-11/2017-11-26`.  
+`${?mpv/sid:SID:${mpv/sid}}` will expand into `SID:1` if the first subtitle track is active.  
+`${?mpv/sub-visibility:with subs}${!mpv/sub-visibility:without subs}` will expand into `with/without subs` depending on if they're visible.  
+
+**The following expansions are available:**
+
+`${NAME}`  
+  Expands to the value of property `NAME`, or in case the value is not found, an empty string
+
+`${NAME:STR}`  
+  Expands to the value of property `NAME`, or in case the value is not found, to the fallback `STR`, which is recursively expanded
+
+`${?NAME:STR}`  
+  If `NAME` is truthy (exists, not `nil`, `false` or `0`), recursively expand to `STR`
+
+`${!NAME:STR}`  
+  If `NAME` is falsey (doesn't exist, `nil`, `false`, or `0`), recursively expand to `STR`
+
+`${~NAME:STR}`  
+  Recursively expand to `STR` if `NAME` exists (but may be otherwise falsey, eg. `0`)
+
+`${%NAME:FORMAT}`  
+  Format `NAME` according to `FORMAT` using Lua's [`string.format()`](http://www.lua.org/manual/5.1/manual.html#pdf-string.format), which is practically `printf()`. Handy for formatting numbers, but could be used to pad strings as well.
+
+`${#NAME:TIMEFORMAT}`  
+  Format `NAME` (expected to be a `number`) into a timestamp using the given `TIMEFORMAT`. You may also leave the `:TIMEFORMAT` off, in which case the default `%02h.%02m.%02.3s` will be used.
+  The `TIMEFORMAT` can use the following format characters:
+
+  *  `%h` - hours, integer
+  *  `%m` - minutes, integer
+  *  `%s` - seconds, float
+  *  `%S` - raw seconds (hours and minutes included), float
+  *  `%M` - milliseconds (0-999), integer
+
+  You may use format specifiers to pad or truncate the values, for example `%02h` will pad the hour with a zero and `%2.0s` will format the seconds as a two-digit decimal number.
+  Milliseconds are included as their own specifier in case you'd like to do `%02h-%02m-%02.0f-%03M` for `00-01-34-523`.
+
+`${&NAME:DATEFORMAT}`  
+  Format current date with the given `TIMEFORMAT` using Lua's [`os.date()`](https://www.lua.org/pil/22.1.html). You may also leave the `:DATEFORMAT` off, in which case the default `%Y-%m-%d %H-%M-%S` will be used.
+  (Due to lazy implementation, `NAME` can be anything)
+
+`${@NAME:STR}`  
+  Just like `${NAME:STR}`, but use [`mp.get_property_osd()`](https://mpv.io/manual/master/#lua-scripting-mp-get-property-osd(name-[,def])) when accessing mpv properties. This can be useful in getting more humand-readable output from properties.
+
+
+**The following script-specific properties are available:**
+
+| Name | Type | Notes |
+| ---- | ---- | ----- |
+| `filename` | `string` | Original filename with the extension stripped off |
+| `file_ext` | `string` | Original extension, dot included |
+| `path` | `string` | full source path - may be a network path, so beware |
+| `pos` | `number` | Current playback position (float), format it with `${#pos:TIMEFORMAT}`! |
+| `unique` | `number` | A sequence number. The script will choose the first available filename, starting with `unique` as 1 and counting up. Use with `${%...}` |
+| `full` | `boolean` | Flag to specify which filename is being expanded - the cropped (`false`) output or the intermediary full-size image (`true`). Use with `${?...}` and `${-...}` |
+| `crop_w` | `number` | Width of the crop |
+| `crop_h` | `number` | Height of the crop |
+| `crop_x` | `number` | Left edge of the crop |
+| `crop_y` | `number` | Top edge of the crop |
+| `crop_x2` | `number` | Right edge of the crop |
+| `crop_y2` | `number` | Bottom edge of the crop |
+
+
 ## Development
 
 Included in the repository is the `concat_files.py` tool I use for automatically concatenating files upon their change, and also mapping changes to the output file back to the source files. It's really handy on stack traces when mpv gives you a line and column on the output file - no need to hunt down the right place in the source files!

version.txt

@@ -1 +1 @@
-0.2.0
+0.3.0