Multiplicative is a suite of mpv extensions that adds a variety of useful features and improvements, with an emphasis on usability, consistency, and dynamism.

• Usability: All commands are invoked via a system of hierarchical mnemonic keybindings.
• Consistency: Commands have consistent, predictable names and aliases.
• Dynamism: Keybindings and command, function, and variable documentation is introspectable at runtime.

A major effort is made to keep the code clean, well-documented, and beautiful. For this reason, among others, Multiplicative is written in Fennel–a Lisp-like language that compiles to Lua–rather than Lua directly.

Right now, not much functionality is written, and the project has not received much testing other than by its primary author (me, modula t.). Thus it should be considered to be in “alpha” stages. Expect bugs–but if you find any that aren’t already known (usually noted with a FIX comment in the source, near the problematic functionality), please report them.

When writing keybindings, we sometimes use Emacs-style keybinding notation:

• C- - Ctrl+key.
• M- - Meta+key. On Linux and Windows, Meta is the Alt key, while on macOS, it’s Command.
• S- - Shift+key.
• s- - Super+key. On many keyboards, the Super key is printed with the Windows logo.

Examples:

• C-f - Hold Ctrl, tap f, then release Ctrl.
• M-. - Hold Alt, tap ., then release Alt.
• C-h k - Hold Ctrl, tap h, release Ctrl, then tap k.
• C-1 M-x foobar RET - Hold Ctrl, tap 1, release Ctrl, hold Alt, tap x, release Alt, type foobar, then tap Enter.

• Fennel REPL (: or M-:).
• “Frame” stepping for audio files (. and , when an audio file is playing).

• Copy path/URL to clipboard, including timestamp if the media is being played from YouTube (c).
• Directory jumping (N and P to jump to the next/previous playlist item in a different directory).
• Auto-copy screenshot path to clipboard when taking a screenshot (s, or S to screenshot without subtitles).
• Delete/trash current file (D, plus options delete-command, trash-command, and delete-by-trashing).
• Open the media’s directory contents in a new mpv instance (v).
• Open the media in your browser (B, plus option browser).
• Open the containing directory or URL of the media in your file manager or browser (M-., plus option file-manager).
• Better xscreensaver inhibition (only inhibit the screensaver if the media has audio (i.e. is not a gif) and is playing unmuted) that works with xscreensaver.
• Option to exit mpv 5 seconds after the end of the playlist (option pre-exit-pause-time).
• Option to log the date/time, path/URL, and title of played media (options record-history, history-log-filename, and history-exclusion-pattern).
• Lots of utility functions to make development easier.
• Convenience functions wrapping mpv’s Lua API.

These are the overall goals of this project. Obviously, not all of them are achieved yet.

• Really good UI.
  • Keyboard-focused, but not mouse-ignoring.
  • Displays all the information relevant to what you’re doing. If you’re changing an option, show the current value and the possible values. Display a short confirmation when the value is set.
  • Stay out of the way by default. If the user doesn’t ask for information, don’t waste screen space on it. “Only speak when spoken to” (or commanded to do so).
• Make mpv more Emacs-like.
  • “Self-documenting” - shouldn’t need to open a browser to know what an option does. Should be able to check what a keybinding does just by pressing C-h k and then the keybinding in question.
  • Interactive - Make it easy to perform actions while the program is running. In other words, provide commands for setting the options, with good completion for the names of options, and information about the possible values.
  • Organized - Support sub-keymaps. Help commands under C-h or f1, video adjustments under another key (rather than spread across the number keys), etc.
• Make mpv better as an image viewer. Have an “image mode” which (optionally) does the following:
  • Automatically pan the image to the top left (or top right) whenever the current file is changed… Since you probably want that if you’re reading manga or the like.
• Just in general, make mpv more convenient.
  • For example, the screensaver inhibition functionality - by default, mpv will prevent the screensaver if the media is being “played”, but it doesn’t differentiate between “playing” images (and image-like media like videos without sound) and actual media like audio and video. Multiplicative only inhibits the screensaver if the playing media has both audio and video.

See TODO.org for a list of ideas for features that could eventually be implemented.

To compile, install Fennel, and then run:

fennel --compile --metadata --require-as-include --globals '*' multiplicative.fnl >multiplicative.lua

Once compilation finishes, simply move multiplicative.lua into your mpv scripts/ directory to complete the installation.

In the future, releases of Multiplicative will be available as pre-compiled Lua so you won’t need to do this yourself.

Contributions to Multiplicative are welcome, but if you’re contributing code, please ensure:

• The existing code style is followed.
• Commit messages properly describe the change and its rationale.
• New functions or commands have a docstring, which:
  • Starts with a sentence that summarizes the command.
  • Describes the arguments, with their names in UPPERCASE.
  • Contains a “See also” line that references similar or related functions/commands/variables, if applicable.
  • Links to other functions, commands, or variables by surrounding them with a backtick (`) and apostrophe ('). Example: `foo'
  • Doesn’t go into implementation details that the user of the function doesn’t need to know about (put those in comments instead).
• Multiplicative’s wrappers for mpv functions are preferred unless they are ill-fitting due to speed, efficiency, or functionality concerns.

If you want to work on this code, your editor of choice likely has support for Fennel.

In general, though, Emacs is probably the best editor for Lisp-like languages, with the side benefit of also being the best editor full stop. If you’re writing Fennel in Emacs, you should use fennel-mode, preferably combined with LSP support such as that provided by Eglot, which is included with Emacs 28.1 and above. I also recommend adding the following configuration to your init.el:

(put 'cmd 'fennel-indent-function 'defun)

Other mpv scripts that are complementary or recommended, which you may also find useful.