Kaleidoscribe

Kaleidoscribe is a web-based alternative YouTube client that allows you to subscribe to channels and playlists without a Google/YouTube account. It crawls the YouTube website in the background to give you a relatively up-to-date view of your customized subscription feed.

The application has rudimentary user management and allows you to keep an unlimited number of accounts, each with independent subscriptions, in one installation. It can also be run in single-user mode if desired.

For understandable reasons, Google/YouTube has no interest in letting projects like this work smoothly, so the main limitation is scheduling pull-based feed updates without running into YouTube's rate limiting. As a result, you can expect to see new videos a lot more slowly compared to YouTube's native subscription feed. The update frequencies are adapted on a per-channel basis depending on how often they upload, but generally speaking individual channels are not updated more often than once or twice per day.

As a result, this project is probably only worth it for people who are dead set to avoid having a Google account, but also want a personalized YouTube experience. I'm hoping that Google won't take active steps to kill it off unless it becomes too popular.

Project website: https://fietkau.software/kaleidoscribe

Requirements

A Kaleidoscribe installation requires a reasonably recent Python 3 environment. I have run it successfully on Python 3.6. Beyond the standard library, it requires the modules flask, PIL/pillow, requests and scrypt. If a required module is missing, it will tell you when you try to run it.

You can run Kaleidoscribe through Flask's local development server for testing and configuration, but a long-term installation will need a proper WSGI server. I personally use Apache 2.4 with the wsgi module.

In addition to a WSGI-capable web server, Kaleidoscribe relies on background tasks getting handled behind the scenes. This can be done either through a persistent system service/daemon or through scheduled calls from something like cron. More on both possibilities in the “Server installation” section.

The web frontend requires a modern browser with JavaScript enabled.

Introduction

To get started, you can simply put the files anywhere you want and then run kaleidoscribe.py. If your Python environment lacks any required modules, that will be the first thing you find out. The script will also perform a few environmental checks and let you know if the database directory needs to be made writable. When you get the Usage text after running the script, the basic preconditions are met.

Next you should run kaleidoscribe.py --interactive to get a local Flask server. It'll tell you the URL to connect to in your web browser, where you should see a login form. Now is a good time to check out config.py, where you can adjust the administrative configuration of your Kaleidoscribe installation. The configuration file contains detailed explanations for each setting, so please do not be intimidated by its length and make sure to read about what you are modifying. Take a look at the first few settings and decide whether you want to enable single user mode or user account registration, either one will allow you to proceed. If you enable account registration, after restarting the Flask server you should see a registration form that you can use to create an account. If you enabled single user mode, you will see your empty subscription feed right away.

Once you are in your Kaleidoscribe installation, you can click the gear in the left-hand menu to access your settings. There is a search bar at the top that you can use to perform a keyword search on YouTube, although only channels and playlists (the two things you can subscribe to) will show up in the results here. Search up a channel or two to subscribe to and click the button! Changes in YouTube's website design break the keyword search with some regularity, but if you find that it's not working, you should at least be able to put a channel ID (the one starting with “UC”) or a playlist ID (starting with “PL”) in the search field to get an opportunity to subscribe directly.

Further down the settings page you can adjust a few display options. If you are not using single user mode, this is also where you can change your password.

Click the topmost icon in the menu to navigate to your subscription feed. Depending on how quick you were, you may still see videos with missing thumbnails or durations. These get filled in via background tasks one by one and should improve as you refresh the page.

If you hover over a video, you should see three icons along the top of the thumbnail. You can use these to mark the video as watched, as to be watched later, or as discarded. Each option removes the video from your subscription feed. The “Watch later” list is a secondary page you can use to keep track of videos you still want to watch, and the “Watched” and “Not interested” histories are also accessible through the menu.

If you are satisfied with your first impression and would like to convert your testing environment into a permanent Kaleidoscribe instance, proceed to the following section.

Server Installation

Kaleidoscribe should be compatible with any WSGI-capable web server, although I have only tested it with Apache, where you will need the wsgi module (available in the libapache2-mod-wsgi-py3 package on a recent Ubuntu Linux). Create a virtual host for your Kaleidoscribe instance and configure it as necessary. My Apache configuration looks like this:

ServerName kaleidoscribe.example.com

WSGIDaemonProcess kaleidoscribe user=www-data group=www-data threads=5 home=/var/www/kaleidoscribe/
WSGIScriptAlias / /var/www/kaleidoscribe/kaleidoscribe.wsgi

<Directory /var/www/kaleidoscribe>
    WSGIProcessGroup kaleidoscribe
    WSGIApplicationGroup %{GLOBAL}
    WSGIScriptReloading On
    Require all granted
</Directory>

# Plus the normal stuff for logging, certs, etc...

Make sure the provided kaleidoscribe.wsgi file along with everything else can be found by the web server. Again, the user account running the web server needs to be able to write to the data and thumbnails subdirectories. Everything else can be read-only. If you want, you can copy over your local database from the previous section as well as any thumbnails that have already been downloaded. Enable the virtual host, follow any instructions your web server gives you, and you should have an accessible Kaleidoscribe installation.

In addition to the WSGI component, you now need to decide how you want to handle the Kaleidoscribe background process. Of the two options available, I use the persistent service mode as a systemd daemon. The service configuration file looks like this:

[Unit]
Description=Kaleidoscribe daemon
After=network.target

[Service]
User=www-data
ExecStart=/usr/bin/python3 -u /var/www/kaleidoscribe/kaleidoscribe.py --background

[Install]
WantedBy=multi-user.target

Note how the script is being started with the --background parameter, which makes it run persistently and handle background tasks as they arise. Running the background service under the same user account as the web server makes pragmatic sense to ensure they have the same access rights to the database.

If you want to avoid running it as a persistent service and would rather use cron or a similar service to call the script regularly, you can configure the script call in much the same way: use the same user account as the web server if possible, add a custom parameter. Though in this case, instead of --background it should be --background-and-terminate. This way, the script will perform any background tasks that are pending (with one second breaks in between) and then terminate itself when there is nothing more to do. I recommend setting it up so the background script gets called often, every few seconds ideally or every few minutes at most. If not, your users may spend a long time waiting for their feeds to update.

And with that you should have a fully functional Kaleidoscribe installation! If the frontend is working, you can keep an eye on the top right of the page. The application will alert you if there are any problems with the backend process.

License

Kaleidoscribe (c) 2019-2022 Julian Fietkau

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for details.