Wyzie Subs
Using the Wyzie NPM Package#
The Wyzie Subs NPM package provides a simple and easy-to-use interface for searching and fetching subtitles.
Installation#
bash npm install wyzie-lib An API key is required for all requests. Get your free key at sub.wyzie.io/redeem and pass it via the key parameter. See the API Keys page for details.
Usage#
import { type SubtitleData, searchSubtitles, parseToVTT } from "wyzie-lib";
const data: SubtitleData[] = await searchSubtitles({
tmdb_id: 286217,
format: ["srt"],
language: ["en"],
release: ["web-dl", "1080p"],
origin: ["WEB"],
key: "YOUR_KEY",
});
console.log(data[0].url);Parameters#
For more information (or if you are stuck), please visit the Wyzie Subs homepage.
| Parameter | Name | Description |
|---|---|---|
| tmdb_id | TmdbId | TMDB ID of the movie or TV show (tmdb_id or imdb_id is required). |
| imdb_id | ImdbId | IMDB ID of the movie or TV show (imdb_id or tmdb_id is required). |
| format | format | File formats to return (e.g., srt, ass). Accepts a list. |
| season | season | Season number (requires episode). |
| episode | episode | Episode number (requires season). |
| language | language | ISO 639-1 codes for subtitle language. Accepts a list. |
| encoding | encoding | Character encoding filter (e.g., utf-8, latin-1). |
| hi | isHearingImpaired | Boolean for hearing-impaired subtitles. |
| source | source | Subtitle providers to query (all for every enabled source). |
| release | release | Release/scene filters (accepts a list). |
| filename | filename/file | Filename filters; aliases file and fileName are supported. |
| origin | origin | Content origin filter (e.g., WEB, BLURAY, DVD). |
| key | key | Your API key (required). Get one free at sub.wyzie.io/redeem. |
| refresh | refresh | Bypass cache and fetch fresh results from sources. |
The package also ships lightweight TMDB helpers: searchTmdb, getTvDetails, and getSeasonDetails for quickly finding IDs before hitting /search. Additionally, getSources can be used to fetch the list of currently enabled subtitle sources.
Types#
- SearchSubtitlesParams: All valid parameters recognized by the API.
- QueryParams: All parameters (optional and required) available for the wyzie-subs API.
- SubtitleData: All returned values from the API with their respective types.
- SourcesResponse: Response type from the
/sourcesendpoint.
Our types are very simple and well-documented. Check out the types.ts file here.
Configuration#
One user asked on Github for a configurable API hostname (AKA you can change the url the package will request) and I was like bruh that sounds like a good idea so below is the usage. Love ya guys!
import { configure, searchSubtitles, parseToVTT } from 'wyzie-lib';
configure({
baseUrl: 'https://my-custom-subtitle-scraper.com',
key: 'YOUR_KEY',
});
const subtitles = await searchSubtitles({
tmdb_id: 123456,
language: "en"
});