tubular

A modal terminal YouTube browser built with Rust and Ratatui. Search for videos, organize subscribed channels with overlapping tags, browse their feeds, and open a selected video in Terebi.

Requirements

• A recent stable Rust toolchain, including Cargo, to build and install.
• yt-dlp on PATH for searches, feeds, and full descriptions.
• curl on PATH for thumbnails.
• The Terebi CLI installed on PATH, together with its app bundle and streaming dependencies, for playback.

The default playback setup requires macOS 15+, since Terebi is a native macOS player. Install Terebi separately and follow its dependency/setup instructions; installing Tubular does not install the player.

A terminal with native image support can display thumbnails using its graphics protocol. Other terminals fall back to colored half-block characters.

Installation

From a checkout of this repository:

cargo install --path . --locked

Make sure Cargo's install directory (normally ~/.cargo/bin) is on your PATH.

To run directly from source instead:

cargo run --locked -- "rust programming"

Usage

tubular                       # Start without a query
tubular "rust programming"    # Search immediately
tubular --player /path/to/terebi "japanese podcast"
tubular --help

Tubular starts in normal mode, with or without a command-line query. Press i to type a search; Enter submits a changed query and returns to normal mode. Esc returns without submitting.

Selecting a video launches:

terebi --new-instance --url 'https://www.youtube.com/watch?v=VIDEO_ID'

Each selection opens an independent player instance without replacing existing playback. --player overrides the Terebi CLI executable; it is not a generic mpv/IINA adapter. Tubular reports launcher failures, while later streaming/playback errors appear in Terebi. Quitting Tubular leaves launched players running.

Controls

These are the default bindings. Overrides in [keys] replace an action's bindings; the live hints and ? reference show the configured keys.

Normal mode

Key	Action
j / k, ↓ / ↑	Select the next / previous video
Enter	Open the selected video in Terebi
g / Home, G / End	Select the first / last loaded video
i	Edit the search query
d	Open video info; press again for the full description, again to return to info
Esc	Close the preview; otherwise return to the previous view
-	Return to the previous view
+	Go forward after navigating back
c	Browse saved categories
u	Browse an individual saved channel
U (Shift-U)	Open the selected video's channel
s	Edit the selected channel's tags
S	Edit tags for all saved channels in the current category
Tab / Shift-Tab	Switch between visible views
r	Reload configuration and refresh the current view
?	Open / close the scrollable keybinding reference
q	Quit

Ctrl-C quits from any mode or popup.

The bottom bar shows essential actions for the current context. Press ? in normal mode—including selectors and previews—for the full reference. Scroll help with j / k, arrows, Ctrl-J / Ctrl-K, or PageDown / PageUp; ? or Esc closes it without changing the underlying view or dialog. In text fields, ? remains ordinary input. The overview title and action headings are bold; binding values, descriptions, and context labels remain normal weight.

Back and forward navigation restore cached videos, selection, and pagination, including replaced temporary tabs. Removed views are skipped; empty history leaves the current view unchanged. Opening a different view after going back discards the old forward branch. Esc first closes a dialog or leaves insert mode without navigating. Minus and plus remain ordinary text inside input fields.

The full-description view scrolls with ↓ / ↑, Ctrl-J / Ctrl-K, or PageDown / PageUp. Plain j / k still changes the selected video. The bold title, dimmed author/publication row, and description scroll together.

Text input

These shortcuts work in search, category/channel-filter, and new-tag fields:

Key	Action
Enter	Submit the search, browse the selected category/channel, or stage the new tag
Esc	Leave insert mode or abandon the new-tag name
Backspace	Delete one character
Option/Alt-Backspace or Ctrl-W	Delete the previous whitespace-delimited word
Cmd/Super-Backspace or Ctrl-U	Clear the line

If the terminal intercepts modified Backspace rather than transmitting it, use Ctrl-W / Ctrl-U or configure equivalent terminal key mappings. Input fields show a block cursor.

Category browser (c)

• Normal: j / k or arrow keys navigate; i enters filter mode; Enter browses the selected category; p toggles its persisted pin; Esc closes.
• Insert: type a case-insensitive substring to filter; arrow keys or Ctrl-J / Ctrl-K navigate matches; Enter browses; Esc returns to normal mode without clearing the filter.
• Reopening the browser clears its filter. No matches makes browsing and pinning a no-op.

Saved channels (u)

• Normal: j / k or arrow keys navigate; i enters filter mode; Enter opens the selected channel's videos; Esc closes.
• Insert: type a case-insensitive substring to filter; arrow keys or Ctrl-J / Ctrl-K navigate matches; Enter browses; Esc returns to normal mode without clearing the filter.
• The list includes registered channels, including untagged ones, and channels saved only in categories. Aliases of the same channel appear once, using a mapped handle when available; otherwise the saved channel identity is shown.
• Channels and unpinned categories share one temporary browsing tab. Choosing either replaces the previous temporary view; pinned category tabs stay visible. Revisiting or navigating back restores cached videos, selection, and pagination.
• Channel selection is single-choice and does not pin channels or change subscriptions. s still edits the selected video's channel tags; bulk S remains category-only.

Press U (Shift-U) on a video to browse its creator directly, including channels you have not saved. This replaces the current temporary browsing tab without adding a subscription. Channel IDs are preferred; a valid handle is used when an ID is unavailable. Missing channel metadata leaves the current view unchanged. Unsaved channel views survive configuration changes for the session; explicitly removing a saved subscription still removes its channel view.

Channel tags (s, or S for bulk editing)

• j / k or arrow keys navigate; Space toggles a tag.
• n prompts for a new tag name. Enter stages it checked and returns to the list.
• Enter in the main tag list saves the staged memberships. Esc cancels without writing.

Bulk editing applies the exact checked tag set to every saved channel in the current category, not only channels with loaded videos. Tags shared by every target start checked; mixed memberships start unchecked. Review the checked set before saving: unchecked tags are removed from all targets. Other channels, saved registrations, empty categories, pins, and comments are preserved.

Subscriptions and feeds

Configuration lives at:

$XDG_CONFIG_HOME/tubular/config.toml

If XDG_CONFIG_HOME is unset, empty, or relative, the fallback is ~/.config/tubular/config.toml. Edit the file directly and press r to reload, or save memberships from the tag dialog.

[settings]
pinned_categories = ["Favorites"]

[categories]
Creators = ["@jawed"]
Favorites = ["@jawed"]

[channels]
"@jawed" = "https://www.youtube.com/channel/UC4QobU6STFB0P71PMvOGN5A"

[categories] contains flat, overlapping tags. A channel can belong to several categories; there is no hierarchy or inheritance. [channels] maps readable handles to stable channel URLs or IDs. Saving a channel through the UI records its handle and mapping when metadata is available.

[settings] holds global options such as pinned_categories. The [settings], [channels], [categories], and [keys] sections can appear in any order; pin/unpin and tag edits preserve the existing section order, key overrides, and other preferences. For older configs, add [settings] immediately above pinned_categories. A top-level declaration is no longer accepted.

Category entries accept @handles, HTTPS YouTube channel URLs, or canonical UC… channel IDs. Mapped handles use their stable identity; unmapped handles work directly.

• Search and Feed are permanent tabs. Feed combines all [channels] registrations, including untagged channels, plus channels entered directly in categories, without duplicates.
• Browsing an unpinned category opens one temporary tab; choosing another replaces it. Pinned categories keep their own tabs, marked with a dimmed p.
• Removing a channel from a category does not unsubscribe it from Feed. To unsubscribe, remove its [channels] mappings and category references, then press r.
• Temporary tabs do not survive restarting; saved categories and pins do. Hidden views retain loaded rows, selection, and pagination during the session.

Bulk editing refuses to clear all tags when a target has no [channels] registration, preventing accidental unsubscription of category-only channels. If source memberships change while a bulk dialog is open, close and reopen it before saving.

Configurable keybindings

Print a complete default configuration, including every action and its default bindings:

tubular --default-config

This prints TOML to stdout and exits without reading or writing config, starting the TUI, or needing yt-dlp, Terebi, or a terminal. Copy the settings you want into your config; r reloads them.

[keys]
video.info.overview = "I"
video.info.description = "d"
video.info.hide = ["escape", "backspace"]
view.history.previous = ["-", "escape"]
view.history.next = "+"
video.play = ["enter", "ctrl+p"]

Each string or array replaces that action's default aliases; omitted actions keep their defaults, and [] disables an action. Dotted assignments, corresponding subtables such as [keys.video.info], and quoted action names are supported. Unknown actions, invalid chords, duplicate action declarations, and ambiguous bindings in the same context are rejected before saving.

Characters are case-sensitive (i differs from I). Named keys are case-insensitive: escape, enter, tab, space, arrows, home, end, pageup, pagedown, backspace, delete, and f1–f24. Combine modifiers with +, for example ctrl+j, alt+backspace, cmd+backspace, or shift+tab. control, option, and super are accepted aliases; + itself, or ctrl++, can be bound. The terminal must transmit the chord for it to work.

Using the same binding for overview and description preserves the default cycle. Distinct bindings, as above, open either view directly. Preview close takes precedence over history back; description scrolling takes precedence over video selection for shared bindings. View commands do not run inside text inputs or selectors; those have their own actions listed by --default-config.

Loading and previews

Search loads 20 results per page; Feed and category views request 20 uploads per channel per page. Individual channel views request only that channel's uploads, using the same pagination. Moving near the loaded end in normal mode fetches more asynchronously, preserving selection and existing rows. Insert mode and open popups pause automatic prefetch. Deep channel archives can get slower because yt-dlp offsets traverse earlier pages again.

Feed views merge newest-first using available upload dates. Older uploads wait while newer channel pages catch up; undated uploads appear when the feed is exhausted. Publication labels use YYYY-MM-DD; ~ marks an estimated UTC date, and Unknown means unavailable metadata.

Pane titles show animated spinners while content loads. Errors retain loaded rows and stop automatic retries; r refreshes the current view.

Video info shows a thumbnail, title, author/publication details, and a clipped description excerpt. Press d again to read the full description in the same popup. Thumbnails and full descriptions are cached in memory across selections and views: 64 full descriptions and eight inactive decoded thumbnails, plus the selected image. Caches last for the session; a successful refresh clears them. Preview loading, decoding, and image resizing run asynchronously.

Development

cargo fmt --check
cargo test --locked
cargo clippy --locked --all-targets -- -D warnings