noctuid / mpv-btfs-stream

Stream torrents in mpv using btfs

About

This plugin uses btfs to allow mpv to stream torrent files directly. It will automatically unmount/cleanup once the mpv instance is closed (by default).

This script will detect magnet: links and torrent files/urls ending in torrent passed to mpv by default. If the torrent file does not end in torrent, you can prefix the path with btfs://. Example mpv commands would be mpv "magnet:..."~ and ~mpv /path/to/file.torrent.

Unlike using btfs directly, this script automatically handles mounting, playing, and unmounting for you.

Requirements

• btfs
• on linux (or maybe similar)
• basic shell utilities (e.g. bash, sleep, mkdir, rmdir, fusermount, nohup)
• Optionally webtorrent-cli

If webtorrent-cli is installed:

• The directory the torrent is mounted to will be named as the info hash instead of the time. This means the same torrent will always use the same directory. This could be useful if you wanted to open/close mpv several times for a torrent without having to redownload it each time (if you set the unmount setting to false). This also allows resuming playback at the same position regardless of the unmount setting.

Installation Instructions

Clone this repo into the mpv scripts directory (e.g. git clone <url> ~/.config/mpv/scripts/btfs-stream). You must put this whole directory in the scripts directory not just the lua file.

Comparison with btfs-hook

I was not aware that someone had already made a plugin for btfs when I made this (two versions actually). As far as I can tell, this script is both much simpler (no complex shell script execution) and more customizable (the other script has no settings).

Comparison with MPV Webtorrent Hook

This plugin is in alternative to mpv-webtorrent-hook that was created since btfs is much easier to work with from an mpv script.

Both

• Allow using a normal mpv call to play a torrent: mpv <torrent identifier>
• Correctly show video title (i.e. file name not magnet link)
• Can play torrents that contain multiple media files (including images or archives of images)
• Will remember the last viewed media file in a torrent (though btfs-stream requires no extra code to do this; mpv does it automatically when playing a directory)

Advantages of btfs-stream

• Btfs allows the script to be much simpler since it is not necessary to parse any output (edge cases and problems are less likely, e.g. webtorrent script previously broke when webtorrent output changed)

Major disadvantages

• Btfs is much slower. Once the video is playing, playback seems fine most of the time, but with btfs, it takes much longer for the video to actually start playing (e.g. 5 seconds with webtorrent-cli vs. 20 for btfs).
• It may take a few seconds in some cases for mpv to quit

Minor disadvantages

• The download speed will not be shown while waiting for the video to play
• Not all webtorrent torrent identifiers are supported (i.e. info hash). Btfs only supports playing magnet links and torrent files by default. It would be possible to add support for playing webtorrent://<info-hash>, but this isn’t really that useful, so I haven’t done it.

If you want to normally use webtorrent-hook but be able to open some torrents with btfs (maybe there are some complex nested torrents webtorrent doesn’t handle well?), you can install both plugins and set the btfs-stream only_handle_prefixed_files option to yes. Then prefix the torrent path or magnet link with btfs:// when you want to use btfs-stream.

Configuration

In ~/.config/mpv/script-opts/btfs-stream.conf, you can change the following settings:

• base_mount_directory - base directory to mount torrents in (default: /tmp/mpv-btfs)
• unmount - whether to unmount the torrent directory after closing mpv (video files will be gone unless you have --keep in btfs_flags); if no, you will need to manually call btfs unmount <path> to unmount (default: yes)
• only_handle_prefixed_file - whether to handle all magnet links/torrents or only those prefixed with btfs:// (default: no)
• btfs_data_directory - btfs data directory (where videos will remain if --keep is used); the script will run mpv’s expand-path command on the string first so that mpv path abbreviations such as ~/ and ~~/ can be used; empty means use btfs default (default: “”)
• btfs_flags - json array of flags to pass to btfs when mounting; should not include --data-directory (use the dedicated option btfs_data_directory instead); example: ["--keep", "--utp-only"] (default: none)