MPVPAPER(1)

NAME
mpvpaper - video wallpaper player using mpv for wlroots

SYNOPSIS
mpvpaper [options] <output> <url|path filename>

DESCRIPTION

mpvpaper is a wallpaper program for wlroots based Wayland compositors, such as Sway. That allows you to play videos with mpv as your wallpaper.

OPTIONS

-h, --help
    Displays usage options

-d, --help-output
    Displays all available <output> and quits

-v, --verbose
    Be more verbose (-vv for higher verbosity)

-f, --fork
    Forks mpvpaper so you can close the terminal

-p, --auto-pause <FULL|MAX>
    Automagically* pause mpv when the wallpaper is hidden Reduces CPU usage seamlessly by pausing mpvpaper

-s, --auto-stop
    Automagically* stop mpv when the wallpaper is hidden Reduces CPU/RAM usage more abruptly by running a holder program

-a, --auto-mode
    Extend auto-pause/stop to trigger when any window is <FULL> (fullscreen) or <MAX> (fullscreen/maximized)

-n, --slideshow <seconds>
    Slideshow mode plays the next video in a playlist every <seconds> And passes mpv(1) options "loop loop-playlist" for convenience

-l, --layer <layer>
    Specifies shell surface <layer> to run on (default: background)

-o, --mpv-options <"options">
    Forwards mpv(1) <"options"> Must be enclosed in quotes "" if multiple options are passed

EXAMPLES
Simple example:
    $ mpvpaper DP-2 /path/to/video
You can select the output with either a connection or identifier names:
    $ mpvpaper 'DP-2 DP-1 HDMI-A-1' /path/to/video
    $ mpvpaper 'Acer Technologies Acer H236HL LX1AA12341234' /path/to/video
To play the same video on all outputs:
    $ mpvpaper ALL /path/to/video
Save resources like CPU/RAM usage with --auto-stop and --auto-mode:
    $ mpvpaper --auto-stop --auto-mode FULL DP-1 /path/to/video
Forward mpv(1) options by passing --mpv-options or -o like so:
    $ mpvpaper -o "no-audio --loop-playlist shuffle" HDMI-A-1 www.url/to/playlist
You can also control mpvpaper just like mpv in the terminal with keyboard bindings. But if you would like to control mpvpaper while it's forked, you could use a mpv(1) input-ipc-server like this:
    $ mpvpaper -o "input-ipc-server=/tmp/mpv-socket-DP-1" DP-1 /path/to/video
Then input commands with socat(1). For example, toggle pause:
    $ echo 'cycle pause' | socat - /tmp/mpv-socket-DP-1
For more mpv(1) commands read: <https://mpv.io/manual/master/#command-interface>

FILES
The following files, also know as "watch lists", contain lists of program names that, if found running with pidof(1), will cause mpvpaper to pause/stop and must be created manually**
    ~/.config/mpvpaper/pauselist
        List of program names that will cause mpvpaper to pause
    ~/.config/mpvpaper/stoplist
        List of program names that will cause mpvpaper to stop
    Add programs that can be found with the pidof(1) command into the list and separate by spaces or newlines.
    For example: "firefox steam obs" or:
         "firefox
          steam
          obs"

NOTES
*Limitations of automagic:

    mpvpaper manipulates a feature of Wayland called a "surface frame callback"

    This feature of Wayland allows mpvpaper to draw/render only when it makes sense to do so. And one reason mpvpaper might not draw/render is if it's "hidden". This is the magic behind the automagic pause/stop options.

    Whatever "hidden" means is up to compositor. As for Sway, "hidden" is if there is a fullscreen window in the way of the wallpaper. mpvpaper will still draw/render even if there is a normal window blocking the wallpaper view entirely.

    This feature is at best a hack that works on some compositors. Usability of these auto options will vary and may not work as intended or at all. That's why it's heavily recommended to also use the --auto-mode option to extend the usability of the auto options to check for fullscreen/maximized windows.

    If none of the auto options work due to compositor support or odd quirks, other features like the "watch lists" mentioned above should be used instead.
**More on lists:
    • mpvpaper will automatically resume only after all the programs in the watch lists are no longer running • If there are programs running from both lists, stopping will always win out • Programs added into a list at runtime will be ignored, unless restarted or "stopped"
Extra notes:
    • When mpvpaper is resuming after "stopping", mpvpaper should begin where it left off. Both in terms of time position and playlist position (if not shuffled)

    • There is a small time delay (1-2 secs.) with the automagic options as it uses time to calculate when to act

    • mpv user configs are loaded by default, override with --mpv-options

AUTHOR
Created by GhostNaN Based on swaybg Inspired by scoopta's glpaper Code Repository: <https://github.com/GhostNaN/mpvpaper/>

SEE ALSO

mpv(1)