git.sr.ht/~greenfoo/govidious

Description

This is a Go module (ie. "library") that provides a wrapper over the Invidious REST API v1.

WARNING: WHILE THIS BANNER IS PRESENT, THIS REPOSITORY DOES NOT IMPLEMENT THE WHOLE INVIDIOUS API AND YOU PROBABLY WANT TO WAIT BEFORE START USING IT.

It lets you access the Invidious API directly from Go to search for videos, get their URL, etc... like this:

import "git.sr.ht/~greenfoo/govidious"           // <--- Tell Go you are going to use this module
...
g := govidious.New(INVIDIOUS_SERVER, nil)        // <--- Specify the URL of an Invidious server
queryResults, _ := g.Search("Rick Asley")        // <--- Query the Invidious server

for _, videoEntry := range queryResults.Videos { // <--- Process the results
    fmt.Println(videoEntry.Title)
}

If you don't know what an "Invidious server" is, jump to the latest section of this README, called "About Invidious". Then come back and keep reading from here.

Documentation

For a more detailed package/API description, check the module embedded documentation, which you can obtain in two ways:

1. You can print it to stdout by running this command:

   $ go doc -all
   

2. ...Or you can serve it in HTML form in "http://localhost:6060" by running this other command:

   $ godoc
   

There is also a "example_test.go" file that shows how some of the APIs are meant to be used.

License

This is GPLv3 software. Check file "LICENSE" inside this same folder.

Hacking

If you want to contribute to this repository, please make sure you run all the tests before sending your patch, like this:

$ go test -server <URL of Indivious server>

...where <URL of Indivious server> is the IP/URL of an Indivious server that has been configured to expose the REST API.

Note that, depending on several items that will be discussed next, not all tests are required to end successfully. The rule is that the same number of tests must end successfully before and after applying your patch.

Things you have to be aware of:

• Problems with public servers:
  • Not all public servers are configured to expose the REST API.
  • Public servers configured to expose the REST API might not expose all the expected APIs (for example, the "Stats" endpoint is usually disabled)
  • Public servers tend to be rate limited, thus running the whole test suit at once might fail. In that case, try running each individual test function by adding the -run <function_name> option.
• Because of all the previous items, it is recommended to use your own (private) Invidious server instead of a public one (see section "Running your own Invidious instance" at the end of this README to find out how to do it).
• The YouTube HTML code (which Invidious parses) changes very frequently. This means any of the Invidious REST endpoints might break for a few days (until Invidious developers fix it) at any point in time.
• When one API fails, add the -verbose option to better understand what the problem might be.

About Invidious

What is Invidious?

"Invidious", in case you don't already know, is an alternative front-end to YouTube. In other words: you can watch YouTube videos by either going directly to "www.youtube.com" or to any of the existing "Invidious" instances deployed all over the world (see here)

Invidious is an open source project (hosted here), so you can (and, in fact, are encouraged) to run it on your own server.

Why would I want to access an Invidious server instead of the original YouTube server?

Several reasons:

1. Avoid the (direct) Google tracking that takes place every time you visit a YouTube page.

   Note: On the most simple configuration, Invidious simply removes the Javascript tracking and gives you a direct link to the (YouTube) hosted video, thus Google will still be able to know which videos are being served to your IP. However, it is also true that Invidious can be configured to proxy the videos itself, so that you never interact with Google/YouTube servers, which is great... but remember this needs to be explicitely configured.

2. No need to sign in to watch age restricted videos.

3. Depending on where the Invidious instance is located, you will also be able to watch geo-restricted videos.

4. Invidious servers can be configured to expose a public REST API, which is something that requires an account in the case of YouTube servers. This makes it possible to create tools that communicate with the Invidious server to "navigate" the YouTube database (search for videos, check their comments, etc...)

You can see what others think about Invidious here: https://news.ycombinator.com/item?id=21535562

Running your own Invidious instance

Why is it "better" to run my own instance instead of using a public one? Several reasons:

1. Avoid centralization. The more instances there are, the harder they are to censor.

2. Privacy. Maybe you don't (and, in fact, you shouldn't!) trust public instances (they might, for example, log your queries).

This doesn't mean it is "bad" to use public instances. It only means that it is "better" to run your own.

Note, however, that the IP that your instance uses might become "blocked" by YouTube if it is abused (for example, if you publish the IP of your instance and many people start using it).

In order to run your own instance follow these instructions

From all the alternatives described in the previous link, using docker is the easiest one:

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

...and the instance will be ready on http://localhost:3000 (for either direclty accessing it from your webbrowser or using it as the REST API URL)

Notice that before running "docker-compose up" you might want to edit file "docker-compose.yml", in particular section "INVIDIOUS_CONFIG" where you can add/change any of the configuration parameters described here.