VacuumTube

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.

What exactly is this?

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.

Installing

Windows

If you don't know the difference, pick the Installer.

• Installer
• Portable ZIP:
  • x64 / amd64
  • Arm® 64

macOS

Note that macOS builds are not yet signed, so they do not auto-update. For now, please periodically check for updates.

• Apple Silicon / M-series
• Intel
• Universal

Linux

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
  • AppImage
  • Ubuntu/Debian/Mint (.deb)
  • tarball
• Arm® 64 / aarch64
  • AppImage
  • Ubuntu/Debian/Mint (.deb)
  • tarball

Settings

VacuumTube has some settings that you can change, which are located in the YouTube settings. They can also be opened by pressing Ctrl+O on your keyboard.

• Ad Block
  • Seamlessly blocks video and feed ads, not subject to YouTube's methods of preventing blockers
• SponsorBlock
  • Automatically skips sponsored (and/or other) 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
• Block Continue Watching
  • Blocks the "Video paused. Continue watching?" prompt that appears after being idle for a while
• Remove Super Resolution
  • Removes "Super resolution" (AI upscaled) qualities from low quality videos
• Hide Shorts
  • Hides YouTube Shorts from the homepage
• Guide Tabs
  • Allows you to choose which guide tabs are shown on the sidebar
• Unlock Resolution
  • Removes monitor resolution cap and allows you to watch videos at any resolution
• 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)
• Features
  • Contains extra experimental features that add extra functionality: Music Mode, Show Remaining Time, Ultrawide Support
• 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
• Device Discoverability
  • Allows VacuumTube to be discovered by the YouTube mobile app on devices within the same local network (DIAL)
• Automatic Updates
  • Download new versions in the background and install them when VacuumTube closes. When off, you can still check for updates from the About page

Extra Input Mappings

VacuumTube exposes a few extra input mappings for actions that may be desired on a desktop:

• Ctrl+O
  • 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
• + or Start
  • Increase volume
• - or Select
  • Decrease volume
• M or L3
  • Toggle mute
• D
  • Increase playback speed
• A
  • Decrease playback speed
• C
  • Toggle captions

Custom CSS (Userstyles)

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.

VacuumTube Flags

• --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 data in the executable directory (you can also create portable.txt in the executable directory, which works in the same way)
• --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] or --deeplink [url]
  • Opens a specific YouTube URL within Leanback. You'll be prompted to choose an account before the URL is opened.
  • If VacuumTube is already open, the URL is opened in the existing instance instead
  • The https:// part is optional
  • The youtube.com/ also is optional
  • youtu.be links work too
  • The smallest form is pure query parameters, like v=Something
  • vacuumtube 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --fullscreen
  • vacuumtube --fullscreen 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
  • vacuumtube --fullscreen 'youtube.com/watch?v=dQw4w9WgXcQ'
  • vacuumtube --fullscreen 'watch?v=dQw4w9WgXcQ'
  • vacuumtube --fullscreen 'v=dQw4w9WgXcQ'
  • vacuumtube --deeplink 'https://youtu.be/dQw4w9WgXcQ'
  • Note: flags VacuumTube doesn't know about (like Chromium flags) take the argument right after them as their value. To make sure a URL is always picked up, use --deeplink, put it after -- (e.g. vacuumtube --fullscreen -- 'v=dQw4w9WgXcQ'), or give other flags their value with = (e.g. --ozone-platform=wayland)

Chromium Flags

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.

Flags that take a value can be written as either --name=value or --name value (e.g. --ozone-platform=wayland or --ozone-platform wayland).

Config Folder

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\

Building from Source

You should always clone from the latest release tag, since latest commit may contain incomplete features and bugs.

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

# Run the automated tests
npm test

# Or package builds for your operating system
npm run windows:build
npm run mac:build
npm run linux:build(-unpacked,-appimage)