Invidious Switcher is a node.js module that automatically monitors Invidious instances and routes your requests through the best instance automatically.
Invidious Switcher is currently in beta. Once it is stable, the version will be increased to 1.0.0 and this notice will be removed. During this beta period, please report absolutely any weirdness, bugs, or feature requests. You can open a GitHub issue here (preferred), or talk to me on another service: https://cadence.moe/about/contact
- Simple methods provided for Invidious API endpoints
- Automatically routes requests through the best instance
- If an instance fails, the request will automatically be routed to a different instance
- Can automatically obtain an instance list from https://instances.invidio.us
- Can periodically monitor instances for availability (this is more advanced then instances/"health" — it actually checks if the instance is blocked)
- Beautiful logging
- Extremely customisable
npm install cloudrac3r/invidious-switcher
If you're currently looking at a fork, be sure to use the forker's username instead of cloudrac3r!
const {Switcher} = require("invidious-switcher")
const switcher = new Switcher("/path/to/config.json")
await switcher.waitForReady()
Promise.all([
switcher.requestVideo("dQw4w9WgXcQ"),
switcher.requestChannel("UC38IQsAvIsxxjztdMZQtwHA"),
switcher.requestChannelVideos("UC38IQsAvIsxxjztdMZQtwHA"),
switcher.requestChannelLatest("UC38IQsAvIsxxjztdMZQtwHA")
]).then(([video, channel, videos, latest]) => {
// :)
})
In the future I plan to turn this into an (optional) client/server architecture to centralise tracking in order to reduce load on instances. The server would do the actual tracking, and clients would just request the server's data without doing any tracking requests of their own.
Remember, just because something is written here, doesn't mean that you should use it, or even that it makes sense to use it.
If you think there might be several ways of doing something, the one closer to the top is probably more sensible.
Methods and properties that you probably shouldn't fiddle with are prefixed with a * in this documentation. Of course, it's JavaScript, and I can't stop you if want to.
const {Switcher, Tracker, Instance, Config} = require("invidious-switcher")
These are the different classes that make up invidious-switcher. You will normally only need to access Switcher.
Config is created by Switcher and manages settings for all the linked parts of invidious-switcher.
Config takes a filename to read settings from. If you do not provide a filename, it will read from /config.json. This file can contain single-line comments, which are stripped as the contents are read.
All documentation of the contents of the config file is in these comments. Open the file and take a look.
When passed a different filename, the settings are entirely replaced with the contents of that file, rather than merged with the defaults! Therefore, when using your own config, you must supply a complete file. You cannot supply a partial file to override the defaults.
It is likely that you will want to use some different settings. Even if you like the defaults, /config.json in this repo will change in later versions. This could cause unexpected behaviour in your application. Therefore, you should create and use your own config file whenever you use invidious-switcher.
Please copy /config.json from this repo into your application, modify it as needed, and load it from Switcher.
Some suggested config files for specific use cases are available in the /suggested_configs folder. If you would like to use a suggested config, simply copy it into your application as normal.
Switcher provides convenient access to the Invidious API. Your application will probably interact with this class the most.
After calling the constructor, Switcher must send some requests before it is usable. You can wait for it to be usable by either listening for the .events:ready event (will only be emitted once!), or by waiting for the promise returned by .waitForReady().
config:
- (missing): use the default config
- string: a filename to read the config from
- Config: a premade Config object to use
Returns a promise that resolves when the switcher is ready.
Request data from /api/v1/videos/{id}
This, and all the other request methods, will intelligently try instances one by one until one works, and then resolve with valid data. If all instances fail, the promise will reject.
Request data from /api/v1/channels/{id}
Request data from /api/v1/channels/{id}/videos
Request data from /api/v1/videos/{id}/latest
Request data from any endpoint from an instance. Again, this will intelligently try instances until one works.
The kind string describes what the request is for, e.g. "video", "channel", "playlist", or any string that describes what you're doing. This is used in logs and in the request kind blacklist (if the server says that the request is forbidden entirely, all further requests of that kind will be refused without trying). If you want the logs to look pretty, the string can be up to 7 characters.
- ready: boolean Whether the switcher is ready
- events: EventEmitter
- config: Config
- logger: Logger
- tracker: Tracker
Load, track, and select instances.
Return a created instance from the internal store.
Use all of the config settings to get the most suitable instance to use next.
Returns a list of all instances that are currently detected as working.
Out of all working instances, return the instance that is currently detected to respond the fastest. However, depending on your config settings, this may not be the most suitable instance to use next. Use .getNextInstance() to get the most suitable instance.
Force a recheck of all instances.
Force a recheck of a selection of instances as specified in the config.
Called automatically by the constructor. Fetches the instance list, checks all instances once, then emits .events:ready.
Called automatically by .init. Reads the instance list from config and adds each site to the internal instance store.
Called automatically by .init. Loads and imports data from the instance list fetch URL.
- config: Config
- logger: Logger
- events: EventEmitter
- interval: Interval
- currentlyChecking: boolean
- lastInstance: Instance
- *instances: Map<string, Instance>
Represents a single instance and its uptime history, and provides methods to retrieve that data as well as add to it by requesting from the instance.
Certain errors are detected as errors that won't be fixed in the future. For example, the /api/v1/videos/{id} endpoint on an instance being deliberately disabled. When these errors are encountered, the kind of request will be added to the instance's .blacklistedKinds. Future method calls for the same kind will reject without sending a request.
All options properties are optional.
site: the instance origin URL, for example https://invidio.us or http://localhost:3000
options:
- available: boolean
Set false and the instance will report not working without making any automatic requests or adding history records. Calling a request method directly still works like normal. - trackingMethod: string
A tracking method override for this instance:
home,stats,channelorvideo. - useCookies: boolean Enable an isolated cookie jar for this instance.
- headers: object Custom key-value headers for requests sent for this instance.
Is this instance "available" and offline? This function is called by Tracker to determine whether to check an instance or not.
Call a more specific check method depending on the global and instance method settings. None of these check methods should reject.
Request /feed/trending, detect errors, add to history, return whether it was successful.
Request /feed/trending, get the current version from the footer, detect errors, add to history, return the version string. Problems are rejected.
Like .checkHome but for /api/v1/stats.
Request /api/v1/videos/{id} and resolve data or reject errors. A history entry is added.
Like .requestVideo but returns a boolean and never rejects.
Request /api/v1/channels/{id} and resolve data or reject errors. A history entry is added.
Like .requestChannel but returns a boolean and never rejects.
Request /api/v1/channels/{id}/videos and resolve data or reject errors. A history entry is added.
Request /api/v1/channels/{id}/latest and resolve data or reject errors. A history entry is added.
Make a request to the instance API, detect errors, add a history entry, and return the result. This is used by other methods.
- config: Config
- logger: Logger
- site: string
The instance origin, e.g.https://invidio.usorhttp://localhost:3000 - options: object
- jar: CookieJar
- events: EventEmitter
- blacklistedKinds: Set
- available: boolean
- records: object[]