Using SageTube
The tabs
Five, in the order you move through them:
| Tab | What it is |
|---|---|
| Feed | Your subscriptions and their recent uploads. Opens here. |
| Search | YouTube search, as a grid of cards. |
| Browse | A channel or playlist by URL — Videos / Shorts / Live for a channel. |
| Downloads | The full yt-dlp downloader inherited from YTSage. |
| Watch | The player and the play queue. |
Watch is last on purpose: it is where the other tabs send you, not somewhere you start. Every card has Play, Queue and a Download button that opens the Downloads tab with the video ready to analyse.
The Feed
Two modes, chosen with the selector at the top left:
- Local subscriptions — subscribe to channels from Browse, and SageTube aggregates their recent uploads itself. No account, no cookies.
- YouTube account — your real signed-in subscription feed. Needs cookies, and is disabled until you have them.
Opening the tab refreshes it, but conservatively: a refresh is one yt-dlp
run per subscribed channel, so only channels not seen for
feed.auto_refresh_on_open_minutes (default 30) are fetched, at most eight per
visit, and at most once per interval per session. The cached feed is on screen
immediately either way. The Refresh button always does the lot.
Set feed.auto_refresh_on_open_minutes to 0 to switch automatic refreshing
off entirely.
Signing in with cookies
The account button in the top-right corner of the tab bar shows whether SageTube is using an account, and opens the cookie settings. The Feed offers the same thing beside its mode selector when you have not signed in.
Cookies are read from a browser profile (--cookies-from-browser) or from a
cookies.txt file. They enable the account feed, age-restricted and
members-only videos, and premium formats. Changes take effect immediately —
anything playing reloads at its current position.
Player keys and mouse
The player takes focus when you click the video. Bindings work whenever the player or one of its controls has focus, so they never interfere with typing in the Search box or the Downloads URL field.
| Key | Action | Key | Action |
|---|---|---|---|
Space, K |
Play / pause | ↑ / ↓ |
Volume ±5 |
← / → |
Seek ∓5 s | M |
Mute |
J / L |
Seek ∓10 s | C |
Subtitles on / off |
Shift+← / → |
Seek ∓1 s | [ / ] |
Speed ∓0.25× |
, / . |
Frame back / forward | Backspace |
Normal speed |
0–9 |
Jump to 0–90 % | N / P |
Next / previous in queue |
Home / End |
Start / end | Ctrl+→ / ← |
Next / previous |
F |
Fullscreen | S |
Screenshot |
F11 toggles fullscreen and Escape leaves it from anywhere in the
window, not just the player — useful because fullscreen hides the tab bar.
| Mouse | Action |
|---|---|
| Click | Play / pause |
| Double-click | Fullscreen |
| Wheel | Volume |
Ctrl + wheel |
Seek ±5 s |
| Right-click | Menu — speed, quality, subtitles, copy link, open in browser |
In fullscreen the controls and the pointer hide after a few idle seconds and come back on any movement. In a window they never hide, so nothing shifts under the cursor.
Settings worth knowing
Everything below lives in the config file — see Building for where that is on each platform.
| Key | Default | What it does |
|---|---|---|
player.hwdec |
auto |
auto picks a per-platform decoder list ending in software. Set no to force software decoding when diagnosing playback. |
player.default_quality |
1080 |
Maximum height the player requests. Also the quality selector in the control bar. |
player.resume |
auto |
Resume where you left off. off always starts at the beginning. |
feed.per_channel_items |
15 |
Videos fetched per channel on a refresh. |
feed.auto_refresh_on_open_minutes |
30 |
Staleness before opening the Feed refreshes a channel. 0 disables. |
check_app_updates |
false |
Check this repository's releases on startup. |
check_beta_updates |
false |
Include pre-releases in that check. |
Updates are checked against this repository, not upstream YTSage — see Tracking-upstream for why that distinction matters. The yt-dlp, Deno and ffmpeg updaters are separate and track their own projects.
Language
The interface is translated into fourteen languages, but the strings SageTube added — the tab names, feed, cards, player and account text — exist only in English so far. A non-English interface shows English for those and its own language for everything inherited from YTSage.