mpv

Mpv is based on the MPlayer and mplayer2 projects which it greatly improves. It supports a wide variety of video file formats, audio and video codecs, and subtitle types. Special input URL types are available to read input from a variety of sources other than disk files. Depending on platform, a variety of different video and audio output methods are supported.

wikipedia.org/wiki/Mpv_(media_player)

How to use this AppJail

General usage

You can obtain the AppJail from the releases section of this repository. However, to go beyond a simple download and be able to update it conveniently from the console, the simplest complementary tool for our purposes is sysutils/bin, a binary manager:

$ doas pkg install -y bin

Install the latest version of this AppJail by running the following command:

$ mkdir -p ~/bin
$ bin install https://github.com/appjail-makejails/mpv

Or update it if it is already installed:

$ bin update mpv.appjail

Assuming ~/bin is in your PATH, you can run the AppJail simply by using the following command:

$ mpv.appjail

Remember that when running an AppJail in portable mode, you must install the key used to verify the binary:

$ cat << "EOF" | doas x11appjail trust dtxdf@disroot.org -
untrusted comment: dtxdf@disroot.org (x11appjail) public key
RWSZbdqRaZVSgICvhui+nrVbXbWw25jyZx/3lhaPzSmVi1Pgvk2DAB1h
EOF
$ x11appjail trusted
KEY                                                                   COMMENT
37e1a7da5478a29ec3d38ecb14919b107beab67cc0de0b473b5b018f018e1ccb.pub  dtxdf@disroot.org (x11appjail) public key

A system-wide installation requires only root access; the key is not necessary. However, it is strongly recommended to verify the binary before installation, making it necessary to install the key anyway.

$ x11appjail verify ~/bin/mpv.appjail
Signature Verified
$ doas ~/bin/mpv.appjail --install
$ x11appjail run mpv

An AppJail creates the jail only if it does not already exist or if the AppJail detects a valid change in its checksum (e.g.: after an update). This means that updates to the OCI image used by the AppJail are only checked at the creation time. If you need to update the OCI image, simply destroy the jail:

$ x11appjail destroy-jail mpv

Once you run the AppJail again, the OCI image is pulled again only if it is newer than the one on your system.

D-Bus

To achieve better integration with the desktop environment, the host's D-Bus is shared via xdg-dbus-proxy(1). By default, the system bus is not shared and the session bus is filtered. This happens transparently and you don't need to do anything. However, you can modify the behavior by creating user attributes that affect how AppJail interprets them when starting the D-Bus proxy.

$ x11appjail attr put mpv:default.dbus-user.talk.notifications "org.freedesktop.Notifications"

By defining this attribute, notifications will work as if they were running on your host. Note that this is just an example, and the application running within the jail may or may not use notifications.

Both the session bus and the system bus can be completely disabled by simply setting <appname>:<profile>.dbus-user or <appname>:<profile>.dbus-system to none. The system bus is usually disabled by default, as in most cases only the session bus is needed.

$ x11appjail attr put mpv:default.dbus-user none

Note that if you have already started the AppJail, in order for the changes to take effect, you must destroy the jail and then run the AppJail again.

$ x11appjail destroy-jail mpv

Examples

If you run this AppJail specifying an existing regular file on the host, it will be transferred internally via stdin to the mpv(1) process:

$ ~/bin/mpv.appjail /path/to/file

The last argument is always used as the file. However, this AppJail handles the concept of a URL. For example, the equivalent of the previous command is as follows:

$ ~/bin/mpv.appjail file:///path/to/file

If you specify a URL using another scheme, this AppJail also detects it and uses it as-is. This means that, for example, you can open a remote image using a protocol supported by mpv(1):

$ ~/bin/mpv.appjail https://www.w3schools.com/html/mov_bbb.mp4
$ # Or if you have been installed this AppJail:
$ x11appjail run mpv https://www.w3schools.com/html/mov_bbb.mp4

A special form is jail://, which means the specified path resides within the jail.

$ x11appjail transfer /path/to/my.mp4 mpv:my.mp4
$ ~/bin/mpv.appjail jail://my.mp4

Since specifying a file as the first positional argument (as in the first example) uses standard input, the file is transferred via streaming. This can cause issues with the MP4 format, making direct file transfer the recommended method.

User Permissions

By default, the jail lacks the necessary devices for sound, the webcam, hardware acceleration, etc., to work as expected. To achieve this, the system operator must grant the user certain permissions, and the user must allow the jail to be created with the specific permissions required for that session. This is implemented using attributes:

$ UID=$(id -u)
$ doas x11appjail sys-attr users.${UID}.perms "enable_3d sound"

The previous command assumes that the shell process is running with unprivileged user rights and can use doas(1) to elevate privileges and execute the sys-attr command. This command will create the attribute based on the shell process's UID, with enable_3d and sound permissions. The user-side counterpart is as follows:

$ x11appjail attr put mpv:default.allow.enable_3d
$ x11appjail attr put mpv:default.allow.sound

Although the user can create other attributes corresponding to actual permissions, such as usb or webcam, these are completely ignored if the system operator does not assign them.

If the jail has already been created, it must be destroyed for the changes to take effect.

$ x11appjail destroy-jail mpv

When you run this AppJail again, the devices will appear inside the jail, and sound and hardware acceleration will work as expected.

Fonts

The OCI image containing all the necessary files does not install any fonts other than those essential for the application. However, this AppJail has the capability to mount system fonts in read-only mode, an operation that consumes no space.

$ doas x11appjail sys-attr put mount.system-fonts

If the jail has already been created, it must be destroyed for the changes to take effect.

$ x11appjail destroy-jail mpv

Once the jail is recreated, the process may take some time to generate the font cache, depending on how many fonts you have on the system.

Networking

Virtual networks are the recommended option for network connectivity. They offer granular control and allow for further isolation of the jail. However, this requires configuring and installing appjail(1) as specified in the "Getting Started" guide.

$ doas x11appjail sys-attr put network.mode virtualnet

If you are not concerned about the complete lack of network-level isolation, you can inherit the host's network stack.

$ doas x11appjail sys-attr put network.mode inherit

If the jail has already been created, it must be destroyed for the changes to take effect.

$ x11appjail destroy-jail mpv

Once the jail has been recreated, you can check network connectivity by executing the following command:

$ x11appjail run-cmd mpv ping -c4 1.1.1.1
PING 1.1.1.1 (1.1.1.1): 56 data bytes
64 bytes from 1.1.1.1: icmp_seq=0 ttl=51 time=36.769 ms
64 bytes from 1.1.1.1: icmp_seq=1 ttl=51 time=36.617 ms
64 bytes from 1.1.1.1: icmp_seq=2 ttl=51 time=44.956 ms
64 bytes from 1.1.1.1: icmp_seq=3 ttl=51 time=36.360 ms

--- 1.1.1.1 ping statistics ---
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 36.360/38.675/44.956/3.629 ms

The above assumes that the jail is allowed to connect to 1.1.1.1 and send ICMP packets.

Hardware Decoding

For hardware decoding to work as intended, you must use the appropriate driver for your GPU. The default OCI image (latest) does not install any drivers beyond those already included in the base image. For Intel cards, use the OCI image with the -intel suffix, and for Nvidia cards, use the one with the -nvidia suffix.

$ doas x11appjail sys-attr put mpv:default.oci.tag 15.1-intel

If the jail has already been created, it must be destroyed for the changes to take effect.

$ x11appjail destroy-jail mpv

Attributes

User Attributes

Name	Description
<appname>:<profile>.dbus-system	Configure the system bus mode. There are three modes: 1. filter: Enables filtering. 2. unfiltered: Disables filtering. This mode is insecure and is recommended only for development. 3. none: Completely disables the session bus. This is the default mode unless explicitly stated otherwise.
<appname>:<profile>.dbus-system.<policy>.*	Apply a policy or rule to the system bus, where <type> can be own, call, talk, see, and broadcast. See xdg-dbus-proxy(1) for details.
<appname>:<profile>.dbus-user	Configure the session bus mode. There are three modes: 1. filter: Enables filtering. This is the default mode unless explicitly stated otherwise. 2. unfiltered: Disables filtering. This mode is insecure and is recommended only for development. 3. none: Completely disables the session bus.
<appname>:<profile>.dbus-user.<policy>.*	Apply a policy or rule to the session bus, where <type> can be own, call, talk, see, and broadcast. See xdg-dbus-proxy(1) for details.
<appname>:<profile>.allow.enable_3d	This permission will execute the application using VirtualGL and make hardware acceleration-related devices visible.
<appname>:<profile>.jail.ephemeral	Mark the jail as ephemeral. See ephemeral option in appjail-quick(1) for details. Although the jail may be destroyed, its data is preserved in the user directory (see ${X11APPJAIL_USERDIR} in x11appjail-spec(5)).
<appname>:<profile>.dbus-user.ignore.own.mpris	If this attribute exists, org.mpris.MediaPlayer2.mpv will not be applied in the own policy.
<appname>:<profile>.allow.sound	This permission will make sound-related devices visible.
<appname>:<profile>.allow.usb	This permission will make usb-related devices visible.
<appname>:<profile>.virtualgl.display	If the user has the enable_3d permission, this specifies the display or EGL device to be used for 3D rendering. Since using EGL is the only logical choice for this project, the default value is egl. In multi-GPU environments, it is possible to specify a particular device.
<appname>:<profile>.allow.webcam	This permission will make webcam-related devices visible.

System Attributes

Name	Description
<appname>:<profile>.labels	A space-separated list of label names.
network.mode	Network mode. Default is none. There are three modes: 1. virtualnet: This option is recommended, as it provides isolation and allows a more fine-grained control. It's necessary to install and configure AppJail on the host, as specified in the "Getting Started" guide. 2. inherit: This mode does not provide network isolation. From a networking perspective, it is exactly the same as running the application on the host. 3. none: Completely disable the network stack.
oci.from	Location of OCI image.
oci.pull-policy	Pull policy. Default is newer. See --pull in buildah-from(1) for details.
oci.tag	OCI image tag.
<appname>:<profile>.labels.<label>	The value of the label.
<appname>:<profile>.network.mode	Same as network.mode, but by application. It takes precedence when defined.
<appname>:<profile>.oci.from	Same as oci.from, but by application. It takes precedence when defined.
<appname>:<profile>.oci.pull-policy	Same as oci.pull-policy, but by application. It takes precedence when defined.
<appname>:<profile>.oci.tag	Same as oci.tag, but by application. It takes precedence when defined.
users.<uid>.perms	A space-separated list of "permissions" granted to a specific user. The implemented "permissions" are presented below: * enable_3d * webcam * usb * sound For a description of any of them, consult ${X11APPJAIL_APPNAME}:${X11APPJAIL_PROFILE}.allow.<permission> in the "User Attributes" section.
network.security-group.tables	If network.mode is set to virtualnet, this attribute specifies a space-separated list of pf(4) tables to which the jail will be added using Security Group hooks. If you are going to add additional labels related to Security Groups, do not include security-group:1, as this attribute already include it. See also: https://github.com/DtxdF/AppJail/wiki/filter
mount.system-fonts	Read-only mounts the fonts system inside the jail, configure Fontconfig, and rebuild the font cache.
network.virtualnet	Specify the virtual network to be used when network.mode is set to virtualnet. If not specified, no virtual network is defined, so the default one is used.

OCI Configuration

build:
  variants:
    - tag: 15.1
      containerfile: Containerfile
      aliases: ["latest"]
      default: true
      args:
        FREEBSD_RELEASE: "15.1"
        NO_PKGCLEAN: "1"
      cache_dirs: ["pkgcache0:/var/cache/pkg"]
    - tag: 15.1-intel
      containerfile: Containerfile
      args:
        FREEBSD_RELEASE: "15.1"
        NO_PKGCLEAN: "1"
        DRIVER: "intel"
      cache_dirs: ["pkgcache0:/var/cache/pkg"]
    - tag: 15.1-nvidia
      containerfile: Containerfile
      args:
        FREEBSD_RELEASE: "15.1"
        NO_PKGCLEAN: "1"
        DRIVER: "nvidia"
      cache_dirs: ["pkgcache0:/var/cache/pkg"]

Notes

1. The file is read with the privileges of the calling process; therefore, if that process lacks permission to read the file, a "Permission Denied" error will occur, just as it would with a regular program.
2. If the last argument is --, the arguments are passed as-is, without transferring any file via stdin.