Invidious

https://docs.invidious.io
Admin
Invidious is a free and open-source alternative frontend for YouTube, offering a privacy-focused way...
Tokens:46,377
Snippets:453
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Enable and Start vnStat Service

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Enable the vnStat service to start on boot and start it immediately.

```bash
systemctl enable --now vnstat
```

--------------------------------

### Complete docker-compose.yml for Multi-Instance Setup

Source: https://docs.invidious.io/improve-public-instance

This is a comprehensive example of a docker-compose.yml file for running multiple Invidious instances with a dedicated refresh service and database configuration.

```yaml
version: "3"
services:
    invidious:
        image: quay.io/invidious/invidious:latest
        deploy:
            replicas: 6
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                channel_threads: 0
                feed_threads: 0
                db:
                    dbname: invidious
                    user: kemal
                    password: kemal
                    host: invidious-db
                    port: 5432
                check_tables: true
                use_pubsub_feeds: true
                use_innertube_for_captions: true
                external_port: 443
                domain: mydomain.com
                https_only: true
                statistics_enabled: true
                hmac_key: "CHANGE_ME!!"
                jobs:
                  clear_expired_items:
                    enabled: false
                  refresh_channels:
                    enabled: false
                  refresh_feeds:
                    enabled: false
        healthcheck:
            test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
            interval: 30s
            timeout: 5s
            retries: 2
        logging:
            options:
                max-size: "1G"
                max-file: "4"
        depends_on:
           - invidious-db


    invidious-refresh:
        image: quay.io/invidious/invidious:latest
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                db:

```

--------------------------------

### Start Invidious Application

Source: https://docs.invidious.io/community-installation-guide

This command starts the entire Invidious application, including the database and companion containers. Generated units are automatically started and do not need to be enabled with `systemctl --user enable`.

```bash
systemctl --user start invidious
```

--------------------------------

### Setup Invidious on Proxmox VM/LXC

Source: https://docs.invidious.io/community-installation-guide

Run this script with sudo privileges or as root to set up Invidious. It clones the necessary repository, makes the setup script executable, and then executes it. Ensure your domain is configured and reachable before running.

```bash
mkdir -p ~/invidious-podman && cd "$_" && git clone "https://github.com/SimplyProgrammer/Invidious-podman-LXC-VM.git" . && chmod 755 setup-invidious.sh && ./setup-invidious.sh

```

--------------------------------

### Start and enable Podman pod service

Source: https://docs.invidious.io/community-installation-guide

Reloads the systemd user daemon and then enables and starts the 'pod-videos.service'. This ensures the Invidious pod starts automatically on login.

```bash
systemctl --user daemon-reload
systemctl --user enable --now pod-videos.service

```

--------------------------------

### Apply Docker Compose Configuration

Source: https://docs.invidious.io/improve-public-instance

Run these commands to stop existing containers and then start the new multi-process Invidious setup with NGINX.

```bash
docker compose down
docker compose up
```

--------------------------------

### Install vnStat on Debian/Ubuntu

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Install the vnStat network monitoring tool on Debian or Ubuntu systems using apt.

```bash
apt install vnstat
```

--------------------------------

### Example Docker Compose File with http3-ytproxy

Source: https://docs.invidious.io/improve-public-instance

This is a comprehensive example of a docker-compose.yml file that includes the Invidious services, a database, NGINX, and the http3-ytproxy service.

```yaml
version: "3"
services:
    invidious:
        image: quay.io/invidious/invidious:latest
        deploy:
            replicas: 6
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                channel_threads: 0
                feed_threads: 0
                db:
                    dbname: invidious
                    user: kemal
                    password: kemal
                    host: invidious-db
                    port: 5432
                check_tables: true
                # external_port:
                # domain:
                # https_only: false
                # statistics_enabled: false
                hmac_key: "CHANGE_ME!!"
        healthcheck:
            test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
            interval: 30s
            timeout: 5s
            retries: 2
        logging:
            options:
                max-size: "1G"
                max-file: "4"
        depends_on:
           - invidious-db

    invidious-refresh:
        image: quay.io/invidious/invidious:latest
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                db:
                    dbname: invidious
                    user: kemal
                    password: kemal
                    host: invidious-db
                    port: 5432
                    check_tables: true
                # external_port:
                # domain:
                # https_only: false
                # statistics_enabled: false
                hmac_key: "CHANGE_ME!!"
        healthcheck:
            test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
            interval: 30s
            timeout: 5s
            retries: 2
        logging:
            options:
                max-size: "1G"
                max-file: "4"
        depends_on:
           - invidious-db 

    nginx:
        image: nginx:latest
        restart: unless-stopped
        volumes:
            - ./nginx.conf:/etc/nginx/nginx.conf:ro
        depends_on:
            - invidious
        ports:
            - "127.0.0.1:3000:3000"

    http3-ytproxy:
        image: 1337kavin/ytproxy:latest
        restart: unless-stopped
        user: 33:33
        network_mode: "host"
        environment:

```

--------------------------------

### Set Up Invidious Companion

Source: https://docs.invidious.io/installation

Install, compile, and configure the Invidious companion service.

```bash
# wget from a binary release
# https://github.com/iv-org/invidious-companion/releases/tag/release-master

wget https://github.com/iv-org/invidious-companion/releases/download/release-master/invidious_companion-x86_64-unknown-linux-gnu.tar.gz

# or compile it using https://docs.deno.com/runtime/
git clone https://github.com/iv-org/invidious-companion.git
deno task compile

# launch it manually
SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG ./invidious_companion

See more docs about the environment variables: https://github.com/iv-org/invidious-companion/wiki/Environment-variables

sudo wget https://github.com/iv-org/invidious-companion/raw/refs/heads/master/invidious-companion.service -O /etc/systemd/system/invidious-companion.service
sudo systemctl enable --now invidious-companion.service
```

--------------------------------

### Example NGINX configuration with proxy protocol

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

This is a simplified example of a final NGINX configuration that includes listening on both the standard HTTPS port and an additional port with proxy protocol enabled.

```nginx
http {
    server {
        listen 443 ssl http2;
        listen 8443 ssl http2 proxy_protocol;
        set_real_ip_from PUBLIC_IPV4_ADDRESS_OF_PROXY_SERVER/32;
        real_ip_header proxy_protocol;
    }
}
```

--------------------------------

### Run Development Docker Compose

Source: https://docs.invidious.io/installation

Build and start the development environment from source.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
docker-compose up
```

--------------------------------

### Install System Dependencies

Source: https://docs.invidious.io/installation

Install required packages for Invidious on various Linux distributions.

```bash
sudo pacman -S base-devel librsvg postgresql ttf-opensans
```

```bash
sudo 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
```

```bash
sudo dnf install -y openssl-devel libevent-devel libxml2-devel libyaml-devel gmp-devel readline-devel postgresql-devel librsvg2-devel sqlite-devel zlib-devel gcc  open-sans-fonts
```

--------------------------------

### Scope Format Example

Source: https://docs.invidious.io/api/authenticated-endpoints

Defines the format for specifying scopes when authorizing a token. Methods can include GET, POST, PUT, DELETE, PATCH.

```plaintext
METHOD1;METHOD2...:ENDPOINT(*)?

Where METHOD can be one of GET, POST, PUT, DELETE, PATCH.
An ENDPOINT can be any of the documented endpoints below.
Examples:
  * POST:playlists*: authorizes POST methods to _any_ endpoint under /api/v1/auth/playlists (/api/v1/auth/playlists, /api/v1/playlists/:id/videos, etc.)
  * :playlists/*: authorizes _any_ method to endpoints under /api/v1/auth/playlists/ (/api/v1/auth/playlists/:id, /api/v1/playlists/:id/videos, etc.)
  * GET:playlists/IVPAAAAAAA: authorizes GET only to playlist IVPAAAAAAA.
  * :preferences: authorizes _any_ method to /api/v1/auth/preferences
  * GET;POST:preferences: authorizes GET or POST to /api/v1/auth/preferences
```

--------------------------------

### Install Podman on RHEL-based systems

Source: https://docs.invidious.io/community-installation-guide

Installs the Podman package on RHEL-based systems using DNF. This is a prerequisite for managing containers.

```bash
sudo dnf install podman

```

--------------------------------

### ImageMagick Installation with librsvg

Source: https://docs.invidious.io/captcha-bug

Steps to manually compile and install ImageMagick with librsvg support to fix CAPTCHA rendering issues. This involves purging the existing installation, downloading the source, configuring with rsvg support, compiling, and installing.

```bash
$ sudo apt purge imagemagick
$ cd /tmp
# check for new releases: https://github.com/ImageMagick/ImageMagick6/releases
$ wget https://github.com/ImageMagick/ImageMagick6/archive/6.9.11-19.tar.gz
$ tar -xvf 6.9.10-24.tar.gz
$ cd ImageMagick6-6.9.10-24
$ ./configure --with-rsvg
$ make
$ sudo make install

```

--------------------------------

### Configure Systemd Service

Source: https://docs.invidious.io/installation

Install and enable the systemd service file for Invidious.

```bash
cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service
```

--------------------------------

### Update Manual Installation

Source: https://docs.invidious.io/installation

Steps to update the source code via git, rebuild the binary, and restart the systemd service.

```bash
sudo su - invidious
cd invidious
git pull
make
exit
systemctl restart invidious.service
```

--------------------------------

### Apache Alt-Svc Header Configuration

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Example of how to add the Alt-Svc header in Apache configuration.

```apache
Header set alt-svc 'h2="original.yourdomain.com:443"; ma=86400'

```

--------------------------------

### Caddy Alt-Svc Header Configuration

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Example of how to add the Alt-Svc header in Caddy configuration.

```caddy
header alt-svc h2="original.yourdomain.com:443"; ma=86400

```

--------------------------------

### Run Production Docker Compose

Source: https://docs.invidious.io/installation

Start the production container stack in detached mode.

```bash
docker compose up -d
```

--------------------------------

### NGINX Alt-Svc Header Configuration

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Example of how to add the Alt-Svc header in NGINX configuration.

```nginx
add_header alt-svc 'h2="original.yourdomain.com:443"; ma=86400';

```

--------------------------------

### Update Docker Installation

Source: https://docs.invidious.io/installation

Commands to pull the latest images, restart containers, and remove unused images.

```bash
docker-compose pull
docker-compose up -d
docker image prune -f
```

--------------------------------

### Traefik Alt-Svc Header Configuration

Source: https://docs.invidious.io/hide-instance-behind-proxy-server

Example of how to add the Alt-Svc header in Traefik configuration.

```traefik
traefik.http.middlewares.altsvc.headers.customresponseheaders.alt-svc=h2="original.yourdomain.com:443"; ma=86400

```

--------------------------------

### Clone Invidious repository

Source: https://docs.invidious.io/community-installation-guide

Clones the Invidious repository to a specified path. This is necessary to access configuration files and scripts required for setup.

```bash
cd <INV-PATH>
git clone https://github.com/iv-org/invidious.git

```

--------------------------------

### Create Invidious User and Clone Repository

Source: https://docs.invidious.io/installation

Set up a dedicated system user and download the Invidious source code.

```bash
sudo useradd -m invidious
sudo su - invidious
git clone https://github.com/iv-org/invidious
exit
```

--------------------------------

### Configure PostgreSQL Database

Source: https://docs.invidious.io/installation

Initialize the PostgreSQL service and create the database user and schema for Invidious.

```bash
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
```

--------------------------------

### Download and Configure Invidious config.yml

Source: https://docs.invidious.io/community-installation-guide

This command downloads the example Invidious configuration file. You must edit this file to match your environment, ensuring `invidious_companion` and `invidious_companion_key` are set, and that `hmac_key` is configured.

```bash
curl -o "$HOME"/.config/containers/systemd/invidious/config.yml https://raw.githubusercontent.com/iv-org/invidious/refs/heads/master/config/config.example.yml
```

--------------------------------

### Check ImageMagick SVG Support

Source: https://docs.invidious.io/captcha-bug

Verify if your ImageMagick installation supports SVG with librsvg. A correct installation will show RSVG versions.

```bash
convert -list format
```

--------------------------------

### Build and Configure Invidious

Source: https://docs.invidious.io/installation

Compile the application, configure the YAML settings, and run database migrations.

```bash
sudo su - invidious
cd invidious
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml

# edit config.yaml to include invidious companion

edit config/config.yaml

add:
invidious_companion:
  # URL used for the internal communication between invidious and invidious companion
  - private_url: "http://localhost:8282/companion"
# IT is NOT recommended to use the same key as HMAC KEY. Generate a new key!
invidious_companion_key: "CHANGE_ME!!"

# Deploy the database
./invidious --migrate

exit
```

--------------------------------

### GET /api/v1/popular

Source: https://docs.invidious.io/api

Retrieves popular videos.

```APIDOC
## GET /api/v1/popular

### Description
Retrieves a list of popular videos.

### Method
GET

### Endpoint
/api/v1/popular
```

--------------------------------

### Run the IPv6 Rotator Script

Source: https://docs.invidious.io/ipv6-rotator

Execute the smart-ipv6-rotator script for the first time to test its functionality. Replace YOURIPV6SUBNET with your server's actual IPv6 subnet. Do not use sudo if you are already root.

```bash
sudo python smart-ipv6-rotator.py run --ipv6range=YOURIPV6SUBNET/64
```

--------------------------------

### GET /api/v1/trending

Source: https://docs.invidious.io/api

Retrieves trending videos.

```APIDOC
## GET /api/v1/trending

### Description
Retrieves a list of currently trending videos.

### Method
GET

### Endpoint
/api/v1/trending

### Parameters
#### Query Parameters
- **type** (String) - Optional - "music", "gaming", "movies", or "default".
- **region** (String) - Optional - ISO 3166 country code (default: "US").
```

--------------------------------

### Initialize Invidious Database Manually

Source: https://docs.invidious.io/community-installation-guide

This script starts the database container, executes a series of SQL initialization commands within the container, and then cleans up by removing curl. This is a manual step for database initialization if `check_tables` in `config.yml` is not sufficient.

```bash
# Start the database container
systemctl --user start invidious-db

# Enter the container, install curl, initialize the database, uninstall curl
podman exec invidious-db \
  sh -c \
  '\
        apt-get update
        apt-get install --assume-yes --no-install-recommends curl

        for initdb in channels videos channel_videos users session_ids nonces annotations playlists playlist_videos
        do
          curl -s https://raw.githubusercontent.com/iv-org/invidious/refs/heads/master/config/sql/$initdb.sql | psql postgresql://$POSTGRES_USER:$POSTGRES_PASSWORD@invidious-db/$POSTGRES_DB
        done
        apt-get --assume-yes purge curl
        '

```

--------------------------------

### GET /api/v1/search/suggestions

Source: https://docs.invidious.io/api

Retrieves search suggestions for a query.

```APIDOC
## GET /api/v1/search/suggestions

### Description
Retrieves search suggestions based on a query string.

### Method
GET

### Endpoint
/api/v1/search/suggestions

### Parameters
#### Query Parameters
- **q** (String) - Required - The search query.
```

--------------------------------

### GET /api/v1/clips Parameters

Source: https://docs.invidious.io/api

Required ID parameter for the clip.

```text
id: string
```

--------------------------------

### GET /api/v1/resolveurl Parameters

Source: https://docs.invidious.io/api

Required URL parameter to resolve.

```text
url: URL
```

--------------------------------

### Create Podman PostgreSQL Container

Source: https://docs.invidious.io/community-installation-guide

Creates and configures a PostgreSQL container within the 'videos' pod. It mounts persistent data, initialization scripts, and sets environment variables for database connection.

```bash
podman create --rm \
--pod videos \
--name postgres \
--label "io.containers.autoupdate=registry" \
--health-cmd='pg_isready -U $POSTGRES_USER -d $POSTGRES_DB' \
-v postgresdata:/var/lib/postgresql/data \
-v <INV-PATH>/invidious/config/sql:/config/sql:z \
-v <INV-PATH>/invidious/docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh:z \
-e POSTGRES_DB=invidious \
-e POSTGRES_USER=kemal \
-e POSTGRES_PASSWORD=kemal \
docker.io/library/postgres:14

```

--------------------------------

### GET /api/v1/search/suggestions

Source: https://docs.invidious.io/api

Provides search query autocomplete suggestions.

```json
{
    "query": String,
    "suggestions": Array(String)
}
```

```text
q: String
```

--------------------------------

### Configure http3-ytproxy for Faster Playback

Source: https://docs.invidious.io/improve-public-instance

Use this configuration to enable http3-ytproxy for faster video playback. Ensure the DISABLE_WEBP environment variable is set to 1 and the volume is correctly mapped.

```yaml
DISABLE_WEBP: 1
volumes:
   - /opt/http3-ytproxy:/app/socket
```

--------------------------------

### GET /api/v1/popular

Source: https://docs.invidious.io/api

Retrieves a list of popular short videos.

```json
[
    {
        "type": "shortVideo",
        "title": String,
        "videoId": String,
        "videoThumbnails": [
            {
            "quality": String,
            "url": String,
            "width": Int32,
            "height": Int32
            }
        ],

        "lengthSeconds": Int32,
        "viewCount": Int64,

        "author": String,
        "authorId": String,
        "authorUrl": String,

        "published": Int64,
        "publishedText": String
    }
]
```

--------------------------------

### Create and Set Permissions for http3-ytproxy Directory

Source: https://docs.invidious.io/improve-public-instance

Create a directory for the http3-ytproxy service and ensure it has the correct ownership for the NGINX user. Replace '33:33' if your NGINX user/group IDs differ.

```bash
mkdir /opt/http3-ytproxy
chown 33:33 -R /opt/http3-ytproxy
```

--------------------------------

### GET /api/v1/clips

Source: https://docs.invidious.io/api

Retrieves clip information for a specific video ID.

```APIDOC
## GET /api/v1/clips

### Description
Retrieves clip metadata for a given video ID.

### Method
GET

### Endpoint
/api/v1/clips

### Parameters
#### Query Parameters
- **id** (String) - Required - The video ID.

### Response
#### Success Response (200)
- **startTime** (Float64) - Start time in seconds
- **endTime** (Float64) - End time in seconds
- **clipTitle** (String) - Title of the clip
- **video** (Object) - Video object
```

--------------------------------

### GET /api/v1/resolveurl

Source: https://docs.invidious.io/api

Resolves a URL to its corresponding Invidious resource ID.

```APIDOC
## GET /api/v1/resolveurl

### Description
Resolves a provided URL to identify the resource type and ID.

### Method
GET

### Endpoint
/api/v1/resolveurl

### Parameters
#### Query Parameters
- **url** (URL) - Required - The URL to resolve.

### Response
#### Success Response (200)
- **pageType** (String) - The type of page resolved
- **browseId** (String) - Optional - Browse ID
- **videoId** (String) - Optional - Video ID
```

--------------------------------

### Configure Invidious Companion Proxy

Source: https://docs.invidious.io/youtube-errors-explained

Example configuration for setting up a proxy within the Invidious companion. This is useful for bypassing IP-based restrictions from YouTube.

```toml
proxy = "socks5://127.0.0.1:9050"

```

--------------------------------

### GET /api/v1/mixes/:rdid

Source: https://docs.invidious.io/api

Retrieves details for a specific mix by its ID.

```APIDOC
## GET /api/v1/mixes/:rdid

### Description
Retrieves metadata and video list for a specific mix.

### Method
GET

### Endpoint
/api/v1/mixes/:rdid

### Parameters
#### Path Parameters
- **rdid** (String) - Required - The mix ID.

### Response
#### Success Response (200)
- **title** (String) - Mix title
- **mixId** (String) - Mix ID
- **videos** (Array) - List of videos in the mix
```

--------------------------------

### GET /api/v1/playlists/:plid

Source: https://docs.invidious.io/api

Retrieves details for a specific playlist by its ID.

```APIDOC
## GET /api/v1/playlists/:plid

### Description
Retrieves metadata and video list for a specific playlist.

### Method
GET

### Endpoint
/api/v1/playlists/:plid

### Parameters
#### Path Parameters
- **plid** (String) - Required - The playlist ID.

#### Query Parameters
- **page** (Int32) - Optional - Page number for pagination.

### Response
#### Success Response (200)
- **title** (String) - Playlist title
- **playlistId** (String) - Playlist ID
- **author** (String) - Author name
- **authorId** (String) - Author ID
- **videoCount** (Int32) - Total number of videos
- **videos** (Array) - List of videos in the playlist
```

--------------------------------

### Create Docker Network for Gluetun

Source: https://docs.invidious.io/gluetun

Create a custom Docker network for Gluetun to use. Avoids conflicts with default subnets.

```bash
docker network create --subnet=172.80.0.0/16 gluetun_network

```

--------------------------------

### GET /api/v1/resolveurl Schema

Source: https://docs.invidious.io/api

Returns the resolved metadata for a given URL.

```json
{
  browseId?: String,
  ucid?: String,
  videoId?: String,
  playlistId?: String,
  startTimeSeconds?: String,
  postId?: String,
  params?: String,
  pageType: string
}
```

--------------------------------

### GET /api/v1/search

Source: https://docs.invidious.io/api

Performs a search for videos, playlists, channels, or hashtags.

```APIDOC
## GET /api/v1/search

### Description
Searches for content based on the provided query and filters.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **q** (String) - Required - The search query.
- **page** (Int32) - Optional - Page number.
- **sort** (String) - Optional - "relevance" or "views".
- **date** (String) - Optional - "hour", "today", "week", "month", or "year".
- **duration** (String) - Optional - "short", "long", or "medium".
- **type** (String) - Optional - "video", "playlist", "channel", "movie", "show", or "all" (default: all).
- **features** (String) - Optional - Comma-separated features (e.g., "hd,subtitles").
- **region** (String) - Optional - ISO 3166 country code (default: "US").
```

--------------------------------

### Clone Invidious Repository

Source: https://docs.invidious.io/installation

Initial step to download the source code from GitHub.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
```

--------------------------------

### GET /api/v1/captions/:id

Source: https://docs.invidious.io/api

Retrieves captions for a specific video ID.

```APIDOC
## GET /api/v1/captions/:id

### Description
Retrieves available captions for a video. Providing a label returns the captions in WebVTT format.

### Method
GET

### Endpoint
/api/v1/captions/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The video ID.

#### Query Parameters
- **label** (String) - Optional - Caption label.
- **lang** (String) - Optional - ISO language code.
- **tlang** (String) - Optional - Target language for auto-translation.
- **region** (String) - Optional - ISO 3166 country code (default: "US").
```

--------------------------------

### GET /api/v1/comments/:id

Source: https://docs.invidious.io/api

Retrieves comments for a specific video ID.

```APIDOC
## GET /api/v1/comments/:id

### Description
Retrieves the comments for a given video ID.

### Method
GET

### Endpoint
/api/v1/comments/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The video ID.

#### Query Parameters
- **sort_by** (String) - Optional - "top" or "new" (default: top).
- **source** (String) - Optional - "youtube" or "reddit" (default: youtube).
- **continuation** (String) - Optional - Continuation token for pagination.
```

--------------------------------

### Create Podman Pod for Invidious

Source: https://docs.invidious.io/community-installation-guide

Creates a Podman pod named 'videos' to group related containers. It exposes port 3000 for Invidious access.

```bash
podman pod create --name videos -p 3000:3000

```

--------------------------------

### GET /api/v1/stats Schema

Source: https://docs.invidious.io/api

Represents the structure of the response for the statistics endpoint.

```json
{
  "version": String,
  "software": {
    "name": "invidious",
    "version": String,
    "branch": String
  },
  "openRegistrations": Bool,
  "usage": {
    "users": {
      "total": Int32,
      "activeHalfyear": Int32,
      "activeMonth": Int32
    }
  },
  "metadata": {
    "updatedAt": Int64,
    "lastChannelRefreshedAt": Int64
  },
  "playback": {
    "totalRequests": Int32?
    "successfulRequests": Int32?
    "ratio": Float32?
  }
}
```

--------------------------------

### Generate systemd service for Podman pod

Source: https://docs.invidious.io/community-installation-guide

Generates a systemd service file for the 'videos' pod and places it in the user's systemd configuration directory. This allows systemd to manage the pod's lifecycle.

```bash
cd ~
cp $(podman generate systemd --new --files --name videos) .config/systemd/user

```

--------------------------------

### Get Subscriptions

Source: https://docs.invidious.io/api/authenticated-endpoints

Retrieves a list of channels the authenticated user is subscribed to.

```APIDOC
## GET /api/v1/auth/subscriptions

### Description
Get user's subscriptions.

### Method
GET

### Endpoint
/api/v1/auth/subscriptions

### Response
#### Success Response (200)
- **author** (String) - The name of the subscribed channel.
- **authorId** (String) - The unique ID of the subscribed channel.

#### Response Example
```json
[
    {
        "author": "Example Channel",
        "authorId": "UCexampleId"
    }
]
```
```

--------------------------------

### Configure docker-compose.yml

Source: https://docs.invidious.io/installation

Define the Invidious, companion, and database services with their respective environment variables and volumes.

```yaml
services:
  invidious:
    image: quay.io/invidious/invidious:latest
    restart: unless-stopped
    # Remove "127.0.0.1:" if used from an external IP
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      # Please read the following file for a comprehensive list of all available
      # configuration options and their associated syntax:
      # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
      INVIDIOUS_CONFIG: |
        db:
          dbname: invidious
          user: kemal
          password: kemal
          host: invidious-db
          port: 5432
        check_tables: true
        invidious_companion:
        # URL used for the internal communication between invidious and invidious companion
        # There is no need to change that except if Invidious companion does not run on the same docker compose file.
        - private_url: "http://companion:8282/companion"
        # IT is NOT recommended to use the same key as HMAC KEY. Generate a new key!
        # Use the key generated in the 2nd step
        invidious_companion_key: "CHANGE_ME!!"
        # external_port:
        # domain:
        # https_only: false
        # statistics_enabled: false
        # Use the key generated in the 1st step
        hmac_key: "CHANGE_ME!!"
    healthcheck:
      test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
      interval: 30s
      timeout: 5s
      retries: 2
    logging:
      options:
        max-size: "1G"
        max-file: "4"
    depends_on:
      - invidious-db

  companion:
    image: quay.io/invidious/invidious-companion:latest
    # Please read the following file for a comprehensive list of all available
    # environment variables and their associated syntax:
    # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
    environment:
    # Use the key generated in the 2nd step
       - SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG
    restart: unless-stopped
    # Uncomment only if you have configured "public_url" for Invidious companion
    # Or if you want to use Invidious companion as an API in your program.
    # Remove "127.0.0.1:" if used from an external IP
    #ports:
    #  - "127.0.0.1:8282:8282"
    logging:
      options:
        max-size: "1G"
        max-file: "4"
    cap_drop:
      - ALL
    read_only: true
    # cache for youtube library
    volumes:
      - companioncache:/var/tmp/youtubei.js:rw
    security_opt:
      - no-new-privileges:true

  invidious-db:
    image: docker.io/library/postgres:14
    restart: unless-stopped
    volumes:
      - postgresdata:/var/lib/postgresql/data
      - ./config/sql:/config/sql
      - ./docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh
    environment:
      POSTGRES_DB: invidious
      POSTGRES_USER: kemal
      POSTGRES_PASSWORD: kemal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]

volumes:
  postgresdata:
  companioncache:
```

--------------------------------

### Get User Preferences

Source: https://docs.invidious.io/api/authenticated-endpoints

Retrieves the current preferences for the authenticated user.

```APIDOC
## GET /api/v1/auth/preferences

### Description
Get preferences for authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/preferences

### Response
#### Success Response (200)
- **annotations** (Boolean) - Whether annotations are enabled.
- **annotations_subscribed** (Boolean) - Whether to show subscribed annotations.
- **autoplay** (Boolean) - Whether autoplay is enabled.
- **captions** (Array[String]) - Preferred caption languages.
- **comments** (Array[String]) - Preferred comment sources.
- **continue** (Boolean) - Whether to continue playback.
- **continue_autoplay** (Boolean) - Whether to autoplay the next video.
- **dark_mode** (String) - The theme setting (`light` or `dark`).
- **latest_only** (Boolean) - Whether to only show the latest videos.
- **listen** (Boolean) - Whether to enable listen mode.
- **local** (Boolean) - Whether to use local settings.
- **locale** (String) - The user's locale.
- **max_results** (Int32) - Maximum number of results to display.
- **notifications_only** (Boolean) - Whether to only show notifications.
- **player_style** (String) - The preferred player style.
- **quality** (String) - The default video quality.
- **default_home** (String) - The default content for the home page.
- **feed_menu** (Array[String]) - The items to display in the feed menu.
- **related_videos** (Boolean) - Whether to show related videos.
- **sort** (String) - The default sorting order for feeds.
- **speed** (Float) - The default playback speed.
- **thin_mode** (Boolean) - Whether to enable thin mode.
- **unseen_only** (Boolean) - Whether to only show unseen videos.
- **video_loop** (Boolean) - Whether to loop videos.
- **volume** (Int32) - The default volume level.

#### Response Example
```json
{
    "annotations": false,
    "annotations_subscribed": false,
    "autoplay": false,
    "captions": ["en"],
    "comments": ["youtube"],
    "continue": false,
    "continue_autoplay": true,
    "dark_mode": "light",
    "latest_only": false,
    "listen": false,
    "local": false,
    "locale": "en-US",
    "max_results": 40,
    "notifications_only": false,
    "player_style": "invidious",
    "quality": "hd720",
    "default_home": "Popular",
    "feed_menu": ["Trending", "Playlists"],
    "related_videos": true,
    "sort": "published",
    "speed": 1.0,
    "thin_mode": false,
    "unseen_only": false,
    "video_loop": false,
    "volume": 100
}
```
```

--------------------------------

### Prepare for next release

Source: https://docs.invidious.io/create-new-invidious-release

Commands to commit changes after updating the version string for development.

```bash
git add CHANGELOG.md shard.yml
git commit -S -m "Prepare for next release"
git push origin master
```

--------------------------------

### Run Invidious

Source: https://docs.invidious.io/installation

Command to execute the Invidious binary directly.

```bash
./invidious
```

--------------------------------

### Set up PostgreSQL Database for Invidious

Source: https://docs.invidious.io/improve-public-instance

This Docker Compose snippet configures a PostgreSQL database for Invidious. It includes persistent storage, configuration file mounting, and initialization scripts.

```yaml
invidious-db:
    image: docker.io/library/postgres:14
    restart: unless-stopped
    volumes:
      - postgresdata:/var/lib/postgresql/data
      - ./config/sql:/config/sql
      - ./docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh
    environment:
        POSTGRES_DB: invidious
        POSTGRES_USER: kemal
        POSTGRES_PASSWORD: kemal
    healthcheck:
        test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]

volumes:
    postgresdata:
```

--------------------------------

### GET /api/v1/hashtag/:tag

Source: https://docs.invidious.io/api

Retrieves video results associated with a specific hashtag.

```APIDOC
## GET /api/v1/hashtag/:tag

### Description
Retrieves a list of videos associated with a given hashtag.

### Method
GET

### Endpoint
/api/v1/hashtag/:tag

### Parameters
#### Path Parameters
- **tag** (String) - Required - The hashtag string.

#### Query Parameters
- **page** (Int32) - Optional - Page number for pagination.

### Response
#### Success Response (200)
- **results** (Array) - List of video objects
```

--------------------------------

### Generate Secret Keys

Source: https://docs.invidious.io/installation

Create HMAC and companion keys using pwgen for secure configuration.

```bash
pwgen 16 1 # 1st step for Invidious (HMAC_KEY)
pwgen 16 1 # 2nd step for Invidious companion (invidious_companion_key)
```

--------------------------------

### GET /api/v1/playlists/:plid Parameters

Source: https://docs.invidious.io/api

Optional pagination parameter for playlist requests.

```text
page: Int32
```

--------------------------------

### Caddy Reverse Proxy Configuration

Source: https://docs.invidious.io/companion-caddy

Use this configuration to set up Caddy as a reverse proxy. Ensure you replace `<server_name>` with your domain. This setup directs traffic for `/companion/*` to `localhost:8282` and all other traffic to `localhost:3000`, while disabling logs.

```caddyfile
https://<server_name> {

  reverse_proxy /companion/* localhost:8282
  reverse_proxy localhost:3000

  log {
      output discard
  }
}

```

--------------------------------

### Create a release branch

Source: https://docs.invidious.io/create-new-invidious-release

Command to initialize a new release branch based on the master branch.

```bash
git checkout -b release-vX.Y.Z
```

--------------------------------

### Create Podman Invidious Container

Source: https://docs.invidious.io/community-installation-guide

Creates the Invidious application container within the 'videos' pod. It mounts the configuration file and sets up health checks.

```bash
podman create --rm \
--pod videos \
--name invidious \
--label "io.containers.autoupdate=registry" \
--health-cmd="wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1" \
--health-interval=30s \
--health-timeout=5s \
--health-retries=2 \
-v <INV-PATH>/config.yml:/invidious/config/config.yml:z,U \
quay.io/invidious/invidious:latest

```

--------------------------------

### Schedule Weekly Database Maintenance with Cron

Source: https://docs.invidious.io/db-maintenance

Set up a weekly cron job to automatically delete expired nonces and truncate the videos table. Redirecting output to /dev/null prevents cron from sending emails.

```bash
@weekly psql invidious -c "DELETE FROM nonces * WHERE expire < current_timestamp" > /dev/null
@weekly psql invidious -c "TRUNCATE TABLE videos" > /dev/null

```

--------------------------------

### Configure Invidious companion public URL

Source: https://docs.invidious.io/installation

Set the public_url for the invidious_companion parameter in config.yaml to enable direct video stream serving.

```yaml
https://MYINVIDIOUSDOMAIN/companion
https://COMPANION.MYINVIDIOUSDOMAIN/companion
```

--------------------------------

### GET /api/v1/trending

Source: https://docs.invidious.io/api

Retrieves current trending videos. Filterable by category type and region.

```json
[
  {
    "title": String,
    "videoId": String,
    "videoThumbnails": [
      {
        "quality": String,
        "url": String,
        "width": Int32,
        "height": Int32
      }
    ],

    "lengthSeconds": Int32,
    "viewCount": Int64,

    "author": String,
    "authorId": String,
    "authorUrl": String,

    "published": Int64,
    "publishedText": String,
    "description": String,
    "descriptionHtml": String,

    "liveNow": Bool,
    "paid": Bool,
    "premium": Bool
  }
]
```

```text
type: "music", "gaming", "movies", "default"
region: ISO 3166 country code (default: "US")
```

--------------------------------

### Bash script for manual user registration

Source: https://docs.invidious.io/register-user

This script automates the manual registration of users. It starts a local Invidious instance, prompts for user ID and password, checks for existing users, and attempts to register the new user. It is vulnerable to SQL injection and should only be used with trusted inputs.

```bash
#!/usr/bin/env bash
set -e

systemctl start podman-invidious_register

CONTINUE='y'
while [ "$CONTINUE" = 'y' ]; do
    read -rp 'User ID: ' ID
    if [ "$(su postgres -c \"psql invidious -c \\\"SELECT email FROM users WHERE email = '"'$ID'"\\\"\\\";\" | tail -n 2 | head -n 1)\"" != '(0 rows)' ]; then
        echo 'Error: User ID is already taken'
        continue
    fi

    read -rsp 'Password: ' PASSWORD

    curl -L 'http://localhost:21742/login' --form-string "email=$ID" --form-string "password=$PASSWORD" -F 'action=signin' >/dev/null

    read -rp 'Register more accounts? [y/N] ' CONTINUE
done

systemctl stop podman-invidious_register


```

--------------------------------

### Configure NGINX as a Load Balancer

Source: https://docs.invidious.io/improve-public-instance

Create an 'nginx.conf' file to set up NGINX as a reverse proxy. It listens on port 3000 and forwards requests to the Invidious service.

```nginx
user www-data;
events {
     worker_connections 1000;
}
http {
     server {
         listen 3000;
         listen [::]:3000;
         access_log off;
         location / {
             resolver 127.0.0.11;
             set $backend "invidious";
             proxy_pass http://$backend:3000;
             proxy_http_version 1.1; # to keep alive
             proxy_set_header Connection ""; # to keep alive
         }
     }
}

```

--------------------------------

### GET /api/v1/annotations/:id

Source: https://docs.invidious.io/api

Retrieves annotation data for a video from YouTube or the Internet Archive.

```APIDOC
## GET /api/v1/annotations/:id

### Description
Retrieves annotation XML for a video from YouTube or legacy data from the Internet Archive.

### Method
GET

### Endpoint
/api/v1/annotations/:id

### Parameters
#### Path Parameters
- **id** (String) - Required - The video ID.

#### Query Parameters
- **source** (String) - Optional - Source of annotations: "archive" or "youtube" (default: "archive").
- **hl** (String) - Optional - Language code for translating fields.
```

--------------------------------

### Configure Logrotate

Source: https://docs.invidious.io/installation

Creates a logrotate configuration file to manage the Invidious log file size and rotation frequency.

```bash
echo "/home/invidious/invidious/invidious.log {
rotate 4
weekly
notifempty
missingok
compress
minsize 1048576
}" | tee /etc/logrotate.d/invidious.logrotate
chmod 0644 /etc/logrotate.d/invidious.logrotate
```
Tokens:
Raw