NOTICE:

I accidentally merged into master. If you use a docker image, you probably should use the official iv-org docker image as catspeed currently does not work on docker. There is work to do to get it working with docker. It is on the backburner for now.

Most people will be fine using catspeed-cc/invidious master branch. Only use development if you want to test new features, and do not expect support for the development branch. If you have troubles, switch back to master.

Currently this repository is only for people who do a manual compile and install (without docker, not recommended)

You can check out the less stable development branch, git checkout development and git pull

---

Invidious

An open source alternative front-end to YouTube

Website  •  Instances list  •  FAQ  •  Documentation  •  Contribute  •  Donate

Donate to catspeed.cc  •  Get ProtonVPN

Chat with us:

Screenshots

Player	Preferences	Subscriptions

Features

Patches

• revert d9df90b5e3ab6f738907c1bfaf96f0407368d842
• add redis patch
• add proxy patch
• sig helper reconnect patch
• freshtokens (mooleshacat)
• csp hack patch (mooleshacat)
• uptime status (mooleshacat)
• loadavg status (mooleshacat)
• enable/disable catspeed branding (mooleshacat)
• enable/disable catspeed, invidious donate link (mooleshacat)
• custom status page, issue tracker, freetube help, donation links (mooleshacat)

User features

• Lightweight
• No ads
• No tracking
• No JavaScript required
• Light/Dark themes
• Customizable homepage
• Subscriptions independent from Google
• Notifications for all subscribed channels
• Audio-only mode (with background play on mobile)
• Support for Reddit comments
• Available in many languages, thanks to our translators

Data import/export

• Import subscriptions from YouTube, NewPipe and Freetube
• Import watch history from YouTube and NewPipe
• Export subscriptions to NewPipe and Freetube
• Import/Export Invidious user data

Technical features

• Embedded video support
• Developer API
• Does not use official YouTube APIs
• No Contributor License Agreement (CLA)

Support

• create a support ticket here https://gitea.catspeed.cc/catspeed-cc/invidious/issues
• please do not create tickets elsewhere.

Quick start

Using invidious:

• Select a public instance from the list and start watching videos right now!

Hosting invidious:

Note: You still require postgresql as only some things are using redis. You should notice an increase in speed when loading pages/feeds/videos. You should also notice a decrease in disk usage.

• Install redis-server & enable apt install -y redis-server ; systemctl enable redis-server ;
  • Compile and start Invidious
  • Check logs for Oct 13 20:20:11 catspeed invidious[1110061]: Connected to redis
  • check connections netstat -tlnpa | grep :6379 for established connections to :6379
• You still need postgresql
• You still need sighelper
• Invidious will automatically reload the tokens from the config file every 1 minute
• Follow the installation instructions

Notice to instance owners:

It appears the working solution currently is to use:

• sig helper
• po_token & visitor_data
• a VPN proxy (privoxy, proton-privoxy, etc.)

I personally use proton VPN, you can get it along with your email here: https://pr.tn/ref/04PN5S3WMGBG - if you want VPN only you can try to get it there or just go to https://protonvpn.com . You can get a working proton-privoxy from https://github.com/catspeed-cc/proton-privoxy .

I use one invidious instance, one sig helper, and one proton-privoxy per core. Each connection to nginx is routed to the least connected backend (currently I have 4) . If you only have 1 core, use 2 processes so you can restart one at a time, minimizing downtime. I hope this is helpful to instance owners having troubles.

Public and private instance owners: if you need help with anything, create an issue ticket here: https://gitea.catspeed.cc/catspeed-cc/invidious/issues - I do not mind, I will try and help best I can.

inv_sig_helper notes

You will need an installation of sig helper. https://github.com/catspeed-cc/inv_sig_helper or https://github.com/iv-org/inv_sig_helper will do fine. I personally set up miltiple sig helpers, one for each process. Sometimes it will crash and you need to make a crontab entry to restart inv_sig_helper and invidious. You will notice the processer usage and memory usage spike now and then. You can control that with service file cpu limits.

redis patch notes

You will need a default installation of redis-server apt install -y redis-server

You still need postgresql. If you've followed the installation instructions it should still be there. Do not uninstall it.

proxy patch notes

There is proxy support in this version. You may use privoxy, or any proxy. If you have proton vpn you can use https://github.com/catspeed-cc/proton-privoxy. The walterl fork https://github.com/walterl/proton-privoxy does not have a line in the config increasing the max connections or an installer script so maybe use mine.

Keep in mind especially on ProtonVPN if you restart a container, you will temporarily have 1 extra connection. So if you have 10 connections allowed, I would keep a few extra available in case a container needs restarting. I am not sure how long it takes for the stale connection to fix itself.

Restarting container (or changing servers) more than 1 time per hour can cause problems. Especially if you use 4-6 connections/containers.

I'll just leave this here https://pr.tn/ref/04PN5S3WMGBG

uptime & loadavg status notes

This branch has the uptime & loadavg patch from myself (mooleshacat) which if enabled in the config, will show the uptime and/or loadavg on the page. Please note, if everyone can see your uptime or loadavg, so could a theoretical attacker. This may or may not be a good idea, you be the judge.

csp hack patch notes

CSP hack changes the content security policy from "'self'" to "http://mydomain.com https://*.mydomain.com". If you get CSP errors, first thing is to make sure https_only is set correctly in invidious config. Only enable this if you have CSP errors when you inspect the video watch page (ctrl + shift + i) and https_only doesn't fix it.

freshtokens patch notes

This branch has the freshtokens patch from myself (mooleshacat) which if not disabled in config file will automatically generate identities for logged in users, as well as anonymous users. The challenge with anonymous users is having some kind of unique identifier to assign a user an identity. How this is currently implemented is there is an identity pool from which identities are picked. Provided the pool is large enough there should not be many identity collisions. Logged in users are assigned their own identities for each instance and will experience less problems. Busy instances will need larger pools, whereas private instances should be fine with smaller pools.

For now, the Docker image will not have these steps, I will have to add them in separately. If using docker, stay on master branch for now. If using manual install, you can try the development branch.

Manual dependency installation: Most important step when upgrading is installing dependencies. Currently the dependency installer script is not working, so you have to manually install dependencies:

• apt install libssl-dev libxml2-dev libyaml-dev libgmp-dev libreadline-dev postgresql librsvg2-bin libsqlite3-dev zlib1g-dev libpcre3-dev libevent-dev fonts-open-sans
• apt install htop git wget curl cpulimit redis-server - HTOP is not required but helpful :)
• systemctl enable --now postgresql
• sudo -i -u postgres
• psql -c "CREATE USER kemal WITH PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
• createdb -O kemal invidious
• exit
• curl -fsSL https://crystal-lang.org/install.sh | sudo bash
• adduser --system --shell /bin/bash --gecos 'User for installing and running invidious' --group --disabled-password --home /home/invidious invidious
• su - invidious
• cd ~
• curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
• nvm install v20.18.0
• nvm use v20.18.0
• git clone --recurse-submodules https://github.com/catspeed-cc/invidious
• cd invidious
• npm install
• cd submodules/youtube-po-token-generator
• node examples/one-shot.js
• If all goes well, you should see the mysterious tokens
• cd ../../ go back to invidious dir and make
• make -j1 if you have more cores, change 1 to number of cores - 1 or for a server that is in use, just use -j1 to prevent high load.

Configuration: Once installed, you will be able to control freshtokens with config variables. Currently they include:

• freshtokens_enabled - true/false - enables and disables freshtokens.
• freshtokens_show_ic_enabled - true/false - enables showing identity stats
• freshtokens_identserver_enabled - false/true - enables identity server (does nothing yet ...)
• freshtokens_identserver_address - "https://my.ident.server.com/ident/" - URL of identity server (does nothing yet ...)
• freshtokens_instanceid - "instance1" - a unique identifier for the instance
• freshtokens_user_expiry - 3600 - How often to expire/generate user identity
• freshtokens_anonpool_expiry: 21600 - How often to expire/generate anon identity
• freshtokens_anonpool_size: 500 - How many identities to generate

General notes: Identities will take time to generate. If you change the pool size higher, it may take time to generate the identities. If you ask too many identities of your server, it may not have the power to generate them. The user however will not see much effect from this. Hopefully you'd have enough identities for the users you have. In the stats, "igr" refers to the identity generation rate. The igr is a rate of change, which can be positive or negative. Positive means it is adding identities, while negative means identities are expiring. igr of 0/min simply means you are adding as many identities as are expiring. Currently catspeed is set to generate 2500 identities, with a 12 hour expiry (subject to change) - for reference, catspeed is a 4-core server with 4gb memory, which runs two invidious instances.

If you experience 403 session expired or other errors, try increasing the identity pool. If you can't generate enough identities within the expiry window, then try increasing the expiry window.

Once you finally reach the maximum identities, I would recommend switching VPN IP's because you will have accumulated enough errors to have gotten the IP temporarily banned. This typically is indicated by many "this helps protect our community" errors. A few of these is normal, but having every single user over 5 minutes getting this message signals you should either restart sig-helper, and/or try to change the VPN ip.

For public instances: If you are as busy as catspeed is blessed to be, you will need a identity pool of at least 2500 and I would even try for higher. I would start with an anon identity expiry of 6 hours, and depending on whether you can get up to the max identities, you can increase or decrease the identity pool and expiry. You can also adjust the expiry of identities of signed in users. I typically have a longer expiry for anon users, and a shorter expiry for signed in users.

Eventually I will make an "identity server" which can be set up on another server, specifically for generating identities. This will allow you to have a reverse proxy to a theoretically infinite number of identity servers.

For private instance owners: If you only have yourself and/or a few friends on your instance, you could probably get away with an identity pool of 500, expiring every 3 hours. I would set the user expiry to 900 seconds for privacy.

This patch is a temporary workaround until inv_sig_helper itself can get the tokens for us. unixfox (invidious dev) raised this idea to techmetx11 (inv_sig_helper dev) and they are working on an implementation that will eventually make this patch useless. This is OK, as it is only a patch and that setup would be better performance wise than my current implementations. You can read about it here iv-org/inv_sig_helper#10

branding, status link, freetube help link & donation link notes

You can change in the config:

• enable/disable catspeed branding
• enable/disable catspeed donation link (please think of cat :3c)
• enable/disable invidious donation link (please ... invidious :3c)
• enable/disable custom donation link
• custom donation link text & url
• custom issue tracker link text & url
• custom status page link text & url
• custom freetube help page link text & url

You need to restart the service for these to take effect.

gitea.catspeed.cc

The repository on GitHub is now a mirror of https://gitea.catspeed.cc/catspeed-cc/invidious. The repository is updated every 60 minutes if my virtual machine is on and there are changes. There is no need to clone the repository at gitea.catspeed.cc.

For support, you can not submit any tickets on github as I've closed the issue tickets page. You can however create an account and submit an issue ticket here https://gitea.catspeed.cc/catspeed-cc/invidious/issues

upgrading

So you noticed some recent commits to master, how do you update?

• Go into the git repo directory
• Checkout the version you want git checkout master
• Pull the new changes git pull
• Make the binary make -j<numcores> (replace with your number of cores minus 1)
• If the binary exists in a different location, copy the new one over top of it
• Backup your existing config file
• Either re-copy the config.example.yml (recommended) or carefully look for the new options and add them to your config.yml (not recommended)

Documentation

The full documentation can be accessed online at https://docs.invidious.io/

The documentation's source code is available in this repository: https://github.com/iv-org/documentation

Extensions

We highly recommend the use of Privacy Redirect, a browser extension that automatically redirects Youtube URLs to any Invidious instance and replaces embedded youtube videos on other websites with invidious.

The documentation contains a list of browser extensions that we recommended to use along with Invidious.

You can read more here: https://docs.invidious.io/applications/

Contribute

Code

1. Fork it ( https://github.com/iv-org/invidious/fork ).
2. Create your feature branch (git checkout -b my-new-feature).
3. Stage your files (git add .).
4. Commit your changes (git commit -am 'Add some feature').
5. Push to the branch (git push origin my-new-feature).
6. Create a new pull request ( https://github.com/iv-org/invidious/compare ).

Translations

We use Weblate to manage Invidious translations.

You can suggest new translations and/or correction here: https://hosted.weblate.org/engage/invidious/.

Creating an account is not required, but recommended, especially if you want to contribute regularly. Weblate also allows you to log-in with major SSO providers like Github, Gitlab, BitBucket, Google, ...

Projects using Invidious

A list of projects and extensions for or utilizing Invidious can be found in the documentation: https://docs.invidious.io/applications/

Liability

We take no responsibility for the use of our tool, or external instances provided by third parties. We strongly recommend you abide by the valid official regulations in your country. Furthermore, we refuse liability for any inappropriate use of Invidious, such as illegal downloading. This tool is provided to you in the spirit of free, open software.

You may view the LICENSE in which this software is provided to you here.

16. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.