git.sr.ht/~greenfoo/govidious
Package govidious implements a wrapper over the Invidious REST API v1, which is described in these documents: For each of the endpoints listed in those links, this module provides an API function which: Takes as many input arguments as needed depending on the endpoint. For example, the "/api/v1/stat" endpoint is represented by the "Stat()" API function which takes no arguments, while the "/api/v1/search" endpoint is represented by the "Search()" API function which takes many arguments (search query, date, duration, ...). Returns a structure that matches the JSON response associated to each endpoint. In order to use this package first create a new "InvidiousV1" instance using the "New()" function: ...then, simply call, on that object, the desired API function(s): For example, to get the URL of the most watched video featuring "kittens playing golf", you would do this: Notice that both URLs ("youtubeUrl" and "invidiousUrl") can be used on a web browser to actually watch the video. The main difference is that: Using "youtubeUrl" establishes a direct connection with YouTube servers. Using "invidiousUrl" might or might not establish a direct connection with YouTube servers, depending on how the Invidious server is configured. If you don't want to leave any trace of YouTube servers, make sure you use "InvidiousUrl" on an Invidious server configured to proxy video files. Another thing you can do with this URL ("youtubeUrl" or "invidiousUrl") is to use the "mpv" player to start watching the video directly, without needing a web browser. Under the hood, "mpv" uses "youtube-dl" (another program) to parse the web page, find the URL of the video file (which might change depending on the options you call "mpv" with, such as the desired quality) and download it. Well... the good news is that you don't need "mpv" nor "youtube-dl" to do all of this as the Invidious API can also be used to find out the URL of the video file once you have the "videoId". First, you obtain all the associated data of the desired video: ...then you inspect the returned structure to find the URL of the video with the desired quality level: There are many other things you can do with this package, such as listing all the videos from a given channel, retrieving the subtitles associated to a video, etc... Check the documentation of each function (and the name of the fields of the structures they return) for more details.
Readme
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.
For a more detailed package/API description, check the module embedded documentation, which you can obtain in two ways:
You can print it to stdout by running this command:
$ go doc -all
...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.
This is GPLv3 software. Check file "LICENSE" inside this same folder.
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:
-run <function_name> option.-verbose option to better understand what
the problem might be."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.
Several reasons:
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.
No need to sign in to watch age restricted videos.
Depending on where the Invidious instance is located, you will also be able to watch geo-restricted videos.
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
Why is it "better" to run my own instance instead of using a public one? Several reasons:
Avoid centralization. The more instances there are, the harder they are to censor.
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.
FAQs
Package govidious implements a wrapper over the Invidious REST API v1, which is described in these documents: For each of the endpoints listed in those links, this module provides an API function which: Takes as many input arguments as needed depending on the endpoint. For example, the "/api/v1/stat" endpoint is represented by the "Stat()" API function which takes no arguments, while the "/api/v1/search" endpoint is represented by the "Search()" API function which takes many arguments (search query, date, duration, ...). Returns a structure that matches the JSON response associated to each endpoint. In order to use this package first create a new "InvidiousV1" instance using the "New()" function: ...then, simply call, on that object, the desired API function(s): For example, to get the URL of the most watched video featuring "kittens playing golf", you would do this: Notice that both URLs ("youtubeUrl" and "invidiousUrl") can be used on a web browser to actually watch the video. The main difference is that: Using "youtubeUrl" establishes a direct connection with YouTube servers. Using "invidiousUrl" might or might not establish a direct connection with YouTube servers, depending on how the Invidious server is configured. If you don't want to leave any trace of YouTube servers, make sure you use "InvidiousUrl" on an Invidious server configured to proxy video files. Another thing you can do with this URL ("youtubeUrl" or "invidiousUrl") is to use the "mpv" player to start watching the video directly, without needing a web browser. Under the hood, "mpv" uses "youtube-dl" (another program) to parse the web page, find the URL of the video file (which might change depending on the options you call "mpv" with, such as the desired quality) and download it. Well... the good news is that you don't need "mpv" nor "youtube-dl" to do all of this as the Invidious API can also be used to find out the URL of the video file once you have the "videoId". First, you obtain all the associated data of the desired video: ...then you inspect the returned structure to find the URL of the video with the desired quality level: There are many other things you can do with this package, such as listing all the videos from a given channel, retrieving the subtitles associated to a video, etc... Check the documentation of each function (and the name of the fields of the structures they return) for more details.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.
Security News
Researchers have demonstrated that teams of LLM agents can exploit zero-day vulnerabilities with a 53% success rate, and the costs of using AI to do so are rapidly becoming more affordable than hiring a human penetration tester.