peertube-viewer-rs

peertube-viewer-rs is a small utility to enable you to browse videos available on any PeerTube instances, without having to launch a web browser. It is heavily inspired from youtube-viewer.

Usage

Here is a screenshot of a basic usage of peertube-viewer-rs. When launching you are prompted with a search input. Once a search is done, you can either select one of the results by writing the corresponding number or do another search by typing anything else. When you chose to play a video, it will be launched in a video player (mpv by default)

peertube-viewer-rs interface

peertube-viewer and peertube-viewer-rs

peertube-viewer-rs is a rewrite in rust of peertube-viewer. Though the implementation language doesn't matter for the end user, the name has been changed since breaking changes have been introduced, mainly in the configuration.

cli interface

This section describes the cli interface for peertube-viewer-rs The interface features :

searching videos
launching videos
extracting video information

To learn how to use it see :

Usage

When launching peertube-viewer-rs you will be prompted to enter a search. search_prompt

You can then enter a search and will be displayed the results with:

the name of the video
the name of the channel
the host instance
the duration of the video
the view count of the video
the time since the video was posted
a nsfw tag for video tagged as such

The white/bold results are those that you have already been watched. select_prompt

You can either play one of the results by typing its ID or get more results with :n next

At any moment you can quit with :q

Here is a list of all the command that can be ran during a session:

:q quit (ctrl-D and ctrl-C have the same effect)
:n get more results for the same search or get more trending results when browsing trending
:p go back to the previous results (the opposite of :n)
:trending start browsing trending results
:channels <query> search channels by name
:chandle list videos from a channel
:info <id> give information on the current item (channel or video)
:comments <id> Lists the comments of a video
:browser <id> Open an item in the browser
:help get help

Command line arguments

This section documents all the command line arguments available.

Options

-c, --config <config-file> Sets a custom config file location. The default is $XDG_CONFIG_HOME/peertube-viewer-rs/config.toml or $HOME/.config/peertube-viewer-rs/config.toml
--search-engine <api> search engine to be used to used (default is sepiasearch.org)
-i, --instance <instance> instance to be browsed. The search will be made using this instance, and all API request will go through this instance.
-p, --player <player> player to play the videos with
--chandle <handle> list the videos of a channel from its handle (ex: mychannel@myinstance.com)
--player-args <player-args>... arguments to be passed to the player
--torrent-downloader <torrent-downloader> choose the torrent software to download the videos with
--torrent-downloader-args <torrent-downloader-arguments> arguments to be passed to the torrent downloader

The videos are played with the command: player <player-args> <url>. This is the same with the torrent when --use-torrent is specified.

flags

-s, --select-quality When playing a video with this option, the user will be prompted to chose the video quality
-t, --trending will start browsing trendings videos. If an initial query is passed with it, it will be ignored
--channels Search channels instead of videos
--local Only browse videos hosted on the instance you are connected to
--tag-nsfw Tag nsfw results. This is the default behavior. This flag is only useful to override the config file
--block-nsfw Block nsfw search results
--let-nsfw Don't tag nsfw results
--print-default-config prints the default confing to stdout and exit This is useful to get started on a config file. See configuration for more details
--print-full-example-config print an example of all possible config options and exit
--use-torrent will download the video via the torrent downloader instead of playing it. This requires a torrent downloader to be set (either via the corresponding option or in the configuration file)
--use-raw-urls the url to the video file will be passed to the player instead of the url to the web interface to watch it. It may be necessary for players without native support for PeerTube such as vlc. Some players (ex : mpv) may be able to show the video title in their interface if this option isn't used.
--color force coloring of output if it is disabled in the config file
--no-color remove coloring of output
-h, --help Prints help information
-V, --version Prints version information

Initial query

It is possible to launch peertube-viewer-rs with a query.

For example, peertube-viewer-rs mastodon will launch peertube-viewer-rs and immediately search for mastodon. It is also possible to set the instance that way: peertube-viewer-rs https://skeptikon.fr mastodon will search for mastodon videos on the instance skeptikon.fr.

You can also play a single video with its url: peertube-viewer-rs https://peertube.social/videos/watch/baf47864-08d8-483f-8518-9a973f99aac8 will play the video.

Fancy features

peertube-viewer comes with a bunch of fancy but not really necessary features:

autocompletion the build systems automatically creates autocompletion for a few shells, available in ./completions
preloading peertube-viewer-rs is capable of preloading some info in advance. For example when typing :n, the search happens before you type ENTER, the same happens for video information when typing a video id. This makes peertube-viewer-rs much snappier.

Configuration

The config file for peertube-viewer-rs can be placed

Platform	Location
Linux	`$XDG_CONFIG_HOME/peertube-viewer-rs/config.toml` or `$HOME`/.config/peertube-viewer-rs/config.toml
macOS	`$HOME`/Library/Preferences/peertube-viewer-rs/config.toml
Windows	`{FOLDERID_RoamingAppData}\peertube-viewer-rs\config.toml`

Syntax

The config file is written in TOML An example of config file with all configuration option showed is available lower or can be obtained with peertube-viewer-rs --print-full-example-config

Format

[general]
- nsfw behavior for nsfw content
- colors coloring of the output
- select-quality regarding quality selection
- edit-mode to set the input mode to vi style keybindings
- browser set the browser to be used
- user-agent set the user agent to be used
[player]
- command video player command
- args video player arguments
- use-raw-urls see command line arguments
- prefer-hls prefer hls streams to static files
[instances]
- search-engine search engine to be used
- main main instance to browse
- blocklist instance blocklist
- allowlist instance blocklist
[torrent]
- command torrent downloader command
- args torrent downloader arguments

General

Configuration for peertube-viewer-rs general behavior

nsfw

Set the behavior for nsfw content. It can be:

"block": block all nsfw content
"tag": the default, add a red nsfw tag next to the video
"let": treat nsfw content the same

This relies on the videos being properly tagged by the instance.

colors

Set whether output should be colored options:

"enable": the default
"disable"

select-quality

Set whether the --select-quality flag is enabled by default

true
false: the default

edit-mode

Set the editing mode. This allows the use of either vi or emacs keybinds. If you don't know what it is you don't need to worry about this option.

"emacs": the default
"vi"

browser

Set the browser to use when opening items with the :browser command. If this variable isn't set, the BROWSER environment variable is used. If the environment variable isn't available, Firefox is the default

user-agent

Set the User-Agent string to be used when making http requests. If can be a string, which will be used as is, or a boolean (false means remove the User-Agent header).

Defaults to: peertube-viewer-rs/<version>

Example:

[general]
nsfw = "block"
colors = "enable"
select-quality = true
edit-mode = "vi"
browser = "qutebrowser"
user-agent = false

Player

Configuration for the player

The videos are played with the command: player <player-args> <url>.

command

Sets the command for the player, it is expected to be a string

args

Sets the arguments for the player, it is expected to be an array of strings

use-raw-urls

Set whether the --use-raw-urls flag is enabled by default

true
false: the default

prefer-hls

Peertube has support for live streaming. Some regular videos are also made available through hls.

This settings tells peertube-viewer which one it should prefer if both are available.

false
true: the default

Note: this option doesn't do anything if either select-quality is true or if use-raw-urls is false

Example:

[player]
command = "vlc"
args = ["--no-audio", "-f"]
use-raw-urls = true
prefer-hls = false

Torrent

Sets the command for the torrent downloader, it is expected to be a string

args

Sets the arguments for the torrent downloader, it is expected to be an array of strings

Example:

[player]
command = "transmission-remote"
args = ["-a"]

instances

Instance settings

search-engine

The search engine to be used (sepiasearch.org is the default)

main

The main instance to be connected to, it is expected to be a string. It is incompatible with the search-engine option. The difference with the search engine option is that all API requests will be made through the same instance.

blocklist-allowlist

blocklist: an array of strings of instances to be blocked
allowlist: an array of strings of instances to be allowed

Both can't be present at the same time. When blocklist is present, no video from the instances listed will be shown. When allowlist is present, only videos from the instances listed will be shown.

Full configuration

This is an example of all configuration options that can be set

[general]

# available options: block, tag(add a nswf tag to search results), let(do nothing)
# default is tag
nsfw = "block"

# enable or disable, defaults to enable
colors = "disable"

# can be true or false
select-quality = true

# can be emacs or vi, defaults to emacs
edit-mode = "vi"

# If this option isn't present, the "BROWSER" environment variable is used
# If it isn't set, the default is Firefox
browser = "qutebrowser"

# Change the User-Agent used for requests
# Defaults to peertube-viewer-rs/<verion>
# false instead of a string removes the user agent
user-agent = "Mozilla/5.0 (X11; Linux x86_64; rv:79.0) Gecko/20100101 Firefox/79.0"

[player]
command = "mpv"
args = ["--volume=30"]

# can be true or false
use-raw-urls = true

# can be true or false
# When use-raw-urls is true and this is true, peertube-viewer will prioritize hls
# versions of videos instead of the static files for a given resolution
# This option is overrided to false when select-quality is given
prefer-hls = false

[instances]
main = "skeptikon.fr"

# peertube-viewer supports using sepiasearch
# search-engine = "sepiasearch.org"

# allowlist = ["video.ploud.fr"]
blocklist = ["peertube.social"]

[torrent]
command = "transmission-remote"
args = ["-a"]

Installation

peertube-viewer-rs is available on the AUR:

Releases

The download for the latest releases can be found on the download page of the project: Download

Releases can be found in the release page of the project: releases

Building from source

Building from source is rather easy, a rust toolchain newer than v1.81 is required.

For a debug build (faster to compile), run cargo build.

For a release build, run cargo build --release --locked.

Once compiled, the executable is located at target/release/peertube-viewer-rs. Completion for a variety of shells is also available in completions/. A manpage is available in the file peertube-viewer-rs.1.

Changelog

1.8.7

Update dependencies fixing RUSTSEC-2024-0421
Bump MSRV to version 1.81

1.8.6

Update dependencies, fixing an incompatibility with rust 1.80

1.8.5

Upgrade dependencies, fixing RUSTSEC-2022-0013 and RUSTSEC-2023-0052

1.8.4

Migrate away from chrono to use time directly
Update dependencies, including Clap to version 3
Fix weird behaviors with --channels
Remove error warning when default config is missing

1.8.3

Update dependencies

1.8.2

Fix error when using a local channel url with the configuration being set to a search engine
Add support for short frontend urls

1.8.1

Update all dependencies
Fix some warnings
Reduce the size of the binary by removing a dependency

1.8.0

Add support for using sepia search
Add support for livestreams
Add support for giving a link to a channel in the cli args
Fix some bugs

1.7.3

Support for HLS videos with the --use-raw-url option

1.7.2

User agent configuration
Fix multiple panics
Avoids being stuck in selecting a resolution with no option when no option is available

1.7.1

add :help menu

1.7.0

Syntax highlighting in the prompt
Tab completion in the prompt
Halved compile times
Halved binary size

1.6.3

Some internal changes
Better error messages

A total result count is now displayed for the current search.
Videos from blacklisted instances are now displayed as blocked (the title and other info isn't shown). Information can be obtained by typing its ID. You will be prompted to check if you are sure you want to play it before playing the video.
video information is now displayed before the prompt for quality selection

1.2.1

Small bug fixes in the configuration.

1.2.0

UI improvements:

COLORS!
More info displayed in search results:
- channel
- host instance
- view count
Switched to elapsed time since publication instead of full date in the search results

1.1.1

Bug fixes:

Playing the last search result caused a new search to be launched instead of playing the video

1.1.0

Add commands :n and :p

1.0.0

Initial release, features searching and playing videos.