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 a free key at store.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	When true, returns only hearing-impaired subtitles. Sources that do not flag hearing-impaired subtitles return nothing.
source	source	Subtitle providers to query by codename (all for every live source your key can use; default charlie).
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 store.wyzie.io/redeem.
refresh	refresh	Bypass cache and fetch fresh results from sources.
limit	limit	Results per page (1 to 200). Without it every result comes back at once.
page	page	Page to return, starting at 1. Only used together with `limit`.
sort	sort	`"downloads"`: most downloaded first; results without a count go last.

The package also ships lightweight TMDB helpers (TMDB Search tab above): searchTmdb, getTvDetails, and getSeasonDetails for quickly finding IDs and episode lists before hitting /search. getSources returns the codenames of the live sources (a source paused by its health checks is left out until it recovers), and getSourcesInfo returns the full /sources response with tiers, and, given a key, which sources that key can use. getStatus returns the Status API report. withDownloadOptions adds download options (WebVTT output, timing fixes, a second language, and more) to a result's url.

Errors#

searchSubtitles resolves to an empty array when nothing matches. Any other refusal from the API rejects with a WyzieError (exported by the package) that carries:

status: the HTTP status (401 no key, 402 Pro balance used up, 403 invalid key or key on hold, 429 daily limit reached, 503 every requested source paused or a brief outage)
apiMessage and details: the API's own message, e.g. "Key on hold"
body: the full JSON error, with extras such as topup, reset_at, reinstate, or offline (the paused sources)

parseToVTT, the TMDB helpers, getSources, getSourcesInfo, getLanguages and getStatus reject with a WyzieError the same way. Invalid parameters (no ID, or a season without an episode) and network failures reject with a plain Error. parseToVTT asks the server for WebVTT on Wyzie download links (every format converts), converts other SRT itself, and returns files that are already WebVTT unchanged. withDownloadOptions adds download options to a result's url; a Pro-only option on a free key makes the download reject with a 403 "Paid feature".

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 /sources endpoint.
DownloadOptions: Options for withDownloadOptions: to, offset, fps, plain, and (Pro) sdh, clean, dual.
SyncParams / SyncResult: Input and result of syncSubtitle (Wyzie Synced, Pro keys): which subtitle (a result, its url, or tmdb_id/imdb_id with language), the speech detectSpeech found or the media file, and the synced download link with its offset, fps and confidence. See Wyzie Synced.
StatusReport / SourceStatus / UptimeWindows / DayUptime: Result of getStatus: StatusReport (overall status, uptime windows and history, per-source SourceStatus) plus its UptimeWindows and DayUptime pieces. See the Status API.
TmdbSearchResult / TvDetails / SeasonSummary / SeasonDetails / EpisodeDetails: Results of the TMDB helpers: TmdbSearchResult (searchTmdb), TvDetails and SeasonSummary (getTvDetails), SeasonDetails and EpisodeDetails (getSeasonDetails).
ConfigurationOptions: The object configure takes: baseUrl and a default key.

Our types are very simple and well-documented. See src/types.ts in the wyzie-lib repository.

Configuration#

One user asked on Github for a configurable API hostname 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',
});

Sources

Direct Fetching

Donations