YouTube Helper Server

This is the server for a simple self-hosted client/server setup for YouTube subscriptions.

This image displays the official TUI Client.

This project started in July 2025 because I got tired of using YouTube's official UI.

---

Installation: Linux

This assumes you would like to use Discord for error reporting and info logs.

1. Clone this repository into a directory somewhere on your server, then cd to it.

2. Install dependencies:

   • Deno
     • Can be installed via pacman on Arch Linux
   • yt-dlp
     • This project currently assumes you install the linux binary version, not via a package manager.
   • FFmpeg
   • PostgreSQL

3. Install Deno packages:

   • deno install

4. Create config files

   • cp -r config.example config
   • cd config
   • Edit config.json
     • Replace DISCORD_WEBHOOK_FOR_ERRORS with a Discord webhook you'd like to use to report errors to yourself.
     • Replace DISCORD_WEBHOOK_FOR_INFO_LOGS with a Discord webhook you'd like to use for informational messages.
     • Replace INSERT_AUTHORIZATION_TOKEN_HERE with an authorization token. Probably use a randomized value and keep this safe, you will need this to set up a client.
     • Replace INSERT_YOUR_DISCORD_USER_ID_HERE with your Discord user ID. You will be pinged when an error occurs.
     • Set the port to the port you wish to use.
   • cp .env.example .env
   • Edit .env
     • Replace INSERT_YOUR_PGSQL_DB_URL_HERE with the URL you wish to use for your database
   • Add subscriptions to subscriptions.json
     • The format for the keys of the subscriptions object is yt://CHANNEL_ID/@username
     • For each, you can either set it to an empty object (: {}), which will use the default configuration, or add one or more overrides to set channel-specific settings, in the same format as the default configuration object.
     • As an example, the valid channel @rossmanngroup is in the file by default. This is used as an example for the format of the config file, and no promotion is intended.
     • Odysee format: odysee://CLAIMID/@username
     • Peertube format: peertube://hostname.tld/username
   • If you wish to allow videos that require login, export a cookies.txt to cookies.txt.
     • This can be done via browser extension
       • One option for Chrome: Get cookies.txt LOCALLY
       • One option for Firefox: cookies.txt
       • Please be careful with what you install. Extension impersonators are a known problem with obtaining cookies.txt.

5. Migrate, then install the database

   • deno task db:deploy
   • deno task db:generate

Running

Start the server with:

deno run ./index.ts

I typically run this with PM2. However, there are any number of ways to daemonize a deno project. It can also be configured with a reverse-proxy like nginx to forward requests to the server to the desired port. It should be configured so that a hostname you control can reach the backend port.

Client

Once you have configured this, you should configure a supported client.

Currently, the only supported client is:

• YouTube Helper Client

Contributing

Official development for this program, including test running, etc. happens on a Forgejo instance which is not open to public account-creation.

Instead, contributions may be proposed (and issues reported) on Codeberg. Please be aware that this Codeberg repo does not support automated CI. You should ensure that your code compiles and is correctly styled before opening a pull request:

• Run deno run lint to format the code and ensure it is free of certain code smells. There should be no errors.
• Run deno run typecheck to ensure that the TypeScript compiles completely. There should be no errors.

Need to make changes to the database schema? Run deno task db:migrate to create a SQL migration.

In this repo, the deno.lock file should not be committed.

AI-generated contributions will not be accepted.