Sign inDemoInstall

Package Overview
File Explorer

Install Socket

Protect your apps from supply chain attacks


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.


Version published


# Description

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

  > IT.**

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

    import ""           // <--- 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

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

# 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
  - 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 "" or to any of the existing "Invidious" instances deployed
all over the world ([see

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:

## 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

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

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

    git clone
    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](


Last updated on 12 Apr 2023

Did you know?

Socket installs a GitHub app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc