VacuumTube is an unofficial wrapper of YouTube Leanback (the console and Smart TV version of YouTube) for the desktop, with a built-in adblocker and minor enhancements.
It is not a custom client, YouTube Leanback is an official interface. This project simply encompasses it and makes it usable as a standalone desktop application.
YouTube Leanback is just an HTML5 app, and so you can just use it in your browser by going to https://www.youtube.com/tv, but they intentionally block browsers unless it's one of their console or TV apps.
You can technically bypass this by spoofing your user agent, but it isn't the same experience you'd get on a console or TV as it doesn't support controllers outside of the official app, and it's just a much more involved process to get it working.
VacuumTube solves all of this by wrapping it with Electron, pretending to be the YouTube app, implementing controller and touch support, and overall making it a much better experience than just spoofing your user agent.
If there's anything that you think makes it look lazy or half-baked, open an issue! The goal is to make it feel as official as possible, while also providing niceties like ad blocking, DeArrow and userstyles.
If you don't know the difference, pick the Installer.
- Installer
- Portable ZIP:
Note that macOS builds are not yet signed, so they do not auto-update. For now, please periodically check for updates.
In most cases, you very likely want to use the Flatpak, which works across all distributions and common architectures.
Otherwise, you can use a distribution package or a portable one. If you don't know the difference, you likely want amd64.
- amd64 / x86_64
- Arm® 64 / aarch64
VacuumTube has some settings that you can change, which are located directly in the YouTube settings. They can also be opened by pressing Ctrl+O on your keyboard or R3 on your controller.
- Ad Block
- Seamlessly blocks video and feed ads, not subject to YouTube's methods of preventing blockers
- SponsorBlock
- Automatically skips sponsored segments in videos based on a community-contributed database
- DeArrow
- Replaces titles and thumbnails with more accurate, less sensationalized versions from a public crowdsourced database
- Return Dislikes
- Uses community data from the Return YouTube Dislike API to show rough dislike counts
- Remove Super Resolution
- Removes "Super resolution" (AI upscaled) qualities from low quality videos
- Hide Shorts
- Hides YouTube Shorts from the homepage
- Filter Video Codecs
- Allows you to block specific video codecs, forcing YouTube to pick an alternative. Similiar to h264ify, but more powerful
- Hardware Decoding
- Uses your GPU to decode videos when possible
- Wayland HDR (Linux)
- Enables HDR on Wayland (Linux) platforms, but can cause desaturated colors on unsupported platforms. Requires up to date drivers and a compatible Wayland compositor. See HDR - Arch Wiki
- Low Memory Mode
- Tells YouTube to enable it's low memory mode
- Fullscreen
- Enables fullscreen, and makes VacuumTube always launch in fullscreen
- No Window Decorations
- Disables window decorations, including the title bar and window border
- Keep on Top
- Enables Keep on Top, and makes VacuumTube launch with the window pinned on top of every other window
- Pause on Blur
- Pause current video when VacuumTube loses focus (e.g. tabbing out or minimizing the window)
- Custom CSS (Userstyles)
- Enables injection of custom CSS styles. See the section below for more information
- Touch Overlay
- Enables on-screen touch controls for easier navigation when touch input is detected
- Controller Support
- Enables support for game controllers, including navigation and video playback controls. Requires an external controller, such as an Xbox controller. Can be turned off to avoid conflicting with apps like JoyToKey
VacuumTube exposes a few extra input mappings for actions that may be desired on a desktop:
Ctrl+OorR3- Open VacuumTube Settings
Ctrl+Shift+C- Copy current video URL to clipboard
Shift+Enter- Simulate long-press of the Enter key
Right Click- Go back
+orStart- Increase volume
-orSelect- Decrease volume
MorL3- Toggle mute
C- Toggle captions
You can apply custom styles to VacuumTube by first enabling it in the settings, and then creating .css files in the userstyles folder. They can then be managed in VacuumTube settings. You can access the developer tools by pressing Ctrl+Shift+I, which are extremely helpful when writing custom CSS.
The userstyles folder is located in the config folder mentioned below.
--version/-v- Prints current version and exits
--portable/-p- Operates VacuumTube in portable mode, setting data directory to the one you specify, or defaulting to
datain the executable directory (you can also createportable.txtin the executable directory, which works in the same way)
- Operates VacuumTube in portable mode, setting data directory to the one you specify, or defaulting to
--fullscreen- Forces VacuumTube to open in fullscreen
--no-window-decorations- Opens VacuumTube with hidden window decorations
enable-devtools- Opens VacuumTube with the Chromium developer tools open
--debug-gpu- Opens chrome://gpu in VacuumTube, helpful for debugging issues
[url]- Opens a specific YouTube URL within Leanback. You'll be prompted to choose an account before the URL is opened.
- The
https://part is optional - The
youtube.com/also is optional - The smallest form is pure query parameters, like
v=Something vacuumtube 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --fullscreenvacuumtube --fullscreen 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'vacuumtube --fullscreen 'youtube.com/watch?v=dQw4w9WgXcQ'vacuumtube --fullscreen 'watch?v=dQw4w9WgXcQ'vacuumtube --fullscreen 'v=dQw4w9WgXcQ'
You can provide extra command line flags to Chromium via the flags.txt file located in the config folder.
For example, putting --disable-gpu into the flags.txt file will cause VacuumTube to run with the GPU disabled. You can find more flags by searching for Chromium command line flags, but you likely won't need to mess with this.
Your config folder is located at:
- Windows:
%APPDATA%\VacuumTube\ - macOS:
~/Library/Application Support/VacuumTube/ - Linux:
~/.config/VacuumTube/ - Linux (Flatpak):
~/.var/app/rocks.shy.VacuumTube/config/VacuumTube/ - Portable (Default):
(executable directory)\data\
Builds will be created in the dist/ folder
git clone https://github.com/shy1132/VacuumTube
cd VacuumTube
# Install Dependencies
npm i
# Run without packaging
npm run start
# Or package builds for your operating system
npm run windows:build
npm run mac:build
npm run linux:build(-unpacked,-appimage)