invidtui

README

invidtui

invidtui is an invidious client, which fetches data from invidious instances and displays a user interface in the terminal(TUI), and allows for selecting and playing Youtube audio and video.

Currently, it is tested on Linux and Windows, and it should work on MacOS.

Features

• Play audio or video
• Control the video resolution
• Ability to open, view, edit and save m3u8 playlists
• Automatically queries the invidious API and selects the best instance
• Search for and browse videos, playlists and channels, with history support
• Authentication with invidious and management of user feed, playlists and subscriptions

Requirements

• MPV
• Youtube-dl/yt-dlp
• FFMpeg
• mpv-mpris (optional, for MPRIS support)

Installation

You can install the package either via the following command:
go install github.com/darkhz/invidtui@latest

or check the Releases page and download the binary that matches your OS and architecture.

Usage

invidtui [<flags>]

Flags:
   --close-instances        Close all currently running instances.
   --force-instance         Force load media from specified invidious instance. (default "")
   --mpv-path               Specify path to the mpv executable. (default "mpv")
   --num-retries            Set the number of retries for connecting to the socket. (default 100)
   --search-channel         Search for a channel.
   --search-playlist        Search for a playlist.
   --search-video           Search for a video.
   --token                  Specify an authorization token.
   --token-link             Display a link to the token generation page.
   --use-current-instance   Use the current invidious instance to retrieve media.
   --video-res              Set the default video resolution. (default "720p")
   --ytdl-path              Specify path to youtube-dl executable or its forks (yt-dlp, yt-dtlp_x86) (default "youtube-dl")

• The close-instances option should mainly be used if another invidtui instance may be using the socket, if there was an application crash, or if an error pops up like this: Error: Socket exists at /home/test/.config/invidtui/socket, is another instance running?.

• The use-current-instance option can be used in cases where a playlist file has to be loaded, but the URLs in the playlist point to a slow invidious instance. The playlist media can instead be retrieved from a fast instance (automatically selected by invidtui).

• While specifying the force-instance option, it is recommended to input just the instance name, remove the "https://" prefix if present. If the instance url is not valid, invidtui will automatically choose another valid instance.

• The search-channel, search-playlist and search-video options are meant to be used individually. Make sure the search queries are properly quoted.

• The token and token-link options have to be used along with the force-instance option.

Authentication

In order to use authentication-based features, like viewing and managing user feed, playlists and subscriptions, an account needs to be registered with a specific Invidious instance and a SID/token has to be generated and used. Authentication can be done either via the dashboard or the command-line.

A SID is a base64 encoded text, that is automatically generated when you register an account with an invidious instance. To get your SID, you can go to your instance's token manager (for example https://y.com.sb/token_manager) and copy the text that is on top of a red background. This is currently the recommended authentication method.

A token is a JSON text, that has to be explicitly generated after verification from the instance. To get your token, either :

• Copy and navigate to the link shown in the dashboard if you are authenticating within invidtui, or ,
• If authenticating via the command-line, type invidtui --force-instance <instance name> --token-link, copy and navigate to the displayed link.

Once the page loads, press 'OK' and wait for the page to stop loading. Then copy the session token displayed on the webpage.

Once the SID/token is obtained, do either of the following methods to complete authentication:

• If authenticating via the dashboard, paste the copied text into the input box and press Enter. If the token is valid, feed, playlists and subscriptions should be displayed.
• If authenticating via the command-line, type invidtui --force-instance <instance name> --token <copied text>.

The token should be saved in your config directory. You can then type invidtui --force-instance <instance name and the saved token associated with the instance will be automatically loaded.

The above mentioned steps can be performed for multiple invidious instances.

Configuration file

Generally, invidtui will work out-of-the-box, with no configuration required.

In case you need to specify settings without using command-line options, a config file can be used.

Typing invidtui --help will show you the location of the config file.
Config file definitions are in the form of a simple name=value or name value pair.

For example:

video-res=720p
mpv-path=/home/user/mycustompath/mpv
ytdl-path=/home/user/mycustompath/ytdl
num-retries=10
use-current-instance
force-instance=invidious.snopyta.org

Keybindings

Application

Ctrl+Z
Suspend

Ctrl+D
Open dashboard

q
Quit

Dashboard

c This control works on the playlist page.
Creates a new playlist.

e This control works on the playlist page.
Edits the selected playlist properties.

_ This control works on the playlist and subscription pages.
If pressed on a playlist, the playlist will be deleted.
If pressed on a channel, the channel will be unsubscribed from.

Ctrl+d This control works across all dashboard pages.
Reloads the page.

Search

/
Show search input. To search a channel from the main screen immediately instead of loading it first, press Alt+/.

Ctrl + e
Switch between search modes (video, playlist, channel)

,
Show search parameters popup

Search parameters popup

Tab
Move one field forward. Press Shift+Tab to move one field backward

The "Sort By", "Duration" and "Date fields are dropdown lists, select any one parameter from each list.
The "Region" field is an inputbox, which accepts a ISO 3166 country code (default is "US").
The rest of the fields are checkboxes, which can be checked/unchecked to set the search features.
Press the Search button to restart the search with the search parameters, Cancel button to exit the popup

Playlist Queue

p
Open playlist queue. This control will work across all pages.

Ctrl+o
Open saved playlist. This control will work across all pages.

Ctrl+a
Append from a playlist file to the playlist queue

Ctrl+s
Save current playlist queue

Shift+m
Move an item in playlist queue. To cancel a move, just press Enter in the same position the move operation was started.

d
Delete an item in playlist queue

Player

Note: These controls will work across all pages (search, playlist or channel pages)

Space
Pause/unpause

=
Increase volume

Ctrl+h
Open play history. Use / to filter history entries, a and v to load media, and i and u to load playlists and channels respectively (see Page-based keybindings).

-
Decrease volume

Right
Seek forward

Left
Seek backward

<
Switch to previous track

>
Switch to next track

s
Cycle shuffle mode (shuffle-playlist)

m
Cycle mute mode

l
Cycle repeat modes (repeat-file, repeat-playlist)

Shift+s
Stop player

Page-based Keybindings

i
This control works on the search, channel and dashboard playlist pages.
Fetches the Youtube playlist contents from the currently selected entry and displays it in a separate playlist page.
In case you have exited this page, you can come back to it by pressing Alt+i instead of reloading the playlist again.

u
This control works on the search page and dashboard subscription page.
Fetches only videos from a Youtube channel (from the currently selected entry) and displays it in a separate channel video page.
Shift+u fetches only playlists from a Youtube channel and displays it in a separate channel playlist page. In case you have exited
this page, you can come back to it by pressing Alt+u instead of reloading the channel again.

+
This control works on the search, playlist, channel and dashboard feed pages,
only if the user is authenticated with an invidious instance.
If pressed on a video, a popup will be displayed to select which user playlist to save the video to.
If pressed on a channel (for example in the channel search page or while viewing a channel),
the selected channel will be subscribed to.

; This control works on the search, playlist, channel and dashboard feed and playlist pages.
Shows a popup containing the selected video/playlist/channel's Invidious and Youtube links.

Shift + c
This control works on the search page, playlist, channel video and dashboard feed pages.
Fetches and displays comments for the selected video.
Press Space to show/hide comment trees.

Enter
This control works on the search, playlist, channel video, channel playlist and dashboard feed pages.
Fetches more results.

Tab
This control works on the channel and dashboard pages.
Switches the channel/dashboard page being shown.

/
This control works on the search and channel search pages.
Refer to the search keybindings above.

a
This control works on the search, playlist, channel video, channel playlist pages, play history popup and the dashboard feed and playlist pages.
Fetches audio of the currently selected entry and adds it to the playlist.
If the selected entry is a playlist, all the playlist contents will be loaded into
the playlist queue as audio. To immediately play after adding to playlist, press Shift+a.

v
This control works on the search, playlist, channel video, channel playlist pages, play history popup and the dashboard feed and playlist pages.
Fetches video of the currently selected entry and adds it to the playlist.
If the selected entry is a playlist, all the playlist contents will be loaded into
the playlist queue as video. To immediately play after adding to playlist, press Shift+v.

Ctrl+x
Cancel the fetching of playlist or channel contents (in case it takes a long time,
due to slow network speeds for example).

Esc
Exit the current page.

Additional Notes

• Since Youtube video titles may have many unicode characters (emojis for example), it is recommended to install noto-fonts and its variants (noto-fonts-emoji for example). Refer to your distro's documentation on how to install them. On Arch Linux for instance, you can install the fonts using pacman: pacman -S noto-fonts noto-fonts-emoji noto-fonts-extra
  

• For the video mode, only MP4 videos will be played, and currently there is no way to modify this behavior. This will change in later versions.

• On Windows, using invidtui in Powershell/CMD will work, but use Windows Terminal for best results.

• For certain videos where the duration is shown as "00:00", but the published date is greater than 0s, it is most likely that the video is a live stream. Due to certain inconsistencies with the invidious API, such videos are not shown as live streams in the search results, but will show when playing.

• Since invidtui relies on specially crafted URLs to load and display media properly, it is not recommended to edit the autogenerated playlist.

• MPRIS support can be enabled by installing mpv-mpris.