Wyzie

https://docs.wyzie.io
Admin
Wyzie is an open-sourced toolset for scraping subtitles with a free API, NPM package, and proxy...
Tokens:7,678
Snippets:74
Trust Score:3.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Enable and Start i6.shark Service

Source: https://docs.wyzie.io/i6shark/hosting

Reload the systemd daemon, then enable and start the i6.shark service. This makes the service active and ensures it starts on boot.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now i6shark
```

--------------------------------

### Install Dependencies with pnpm

Source: https://docs.wyzie.io/proxy/hosting

Install all necessary project dependencies using pnpm after cloning the repository.

```bash
pnpm install
```

--------------------------------

### Install Wyzie NPM Package

Source: https://docs.wyzie.io/subs/usage/package

Install the Wyzie Subs NPM package using npm, pnpm, or yarn.

```bash
npm install wyzie-lib
```

--------------------------------

### Building a Custom Server-Side Proxy

Source: https://docs.wyzie.io/subs/intro

Provides an example of a simple Node.js backend proxy using Express and `fetch` to forward subtitle requests to the Wyzie API. Ensure your API key is stored securely as an environment variable (`WYZIE_API_KEY`).

```javascript
// Example: a simple proxy endpoint
const API_KEY = process.env.WYZIE_API_KEY;

app.get("/subtitles", async (req, res) => {
  const params = new URLSearchParams(req.query);
  params.set("key", API_KEY);
  const response = await fetch(`https://sub.wyzie.io/search?${params}`);
  res.json(await response.json());
});
```

--------------------------------

### Check i6.shark Service Status

Source: https://docs.wyzie.io/i6shark/hosting

Verify the status of the i6.shark service to ensure it is running correctly after being enabled and started.

```bash
sudo systemctl status i6shark
```

--------------------------------

### Get Sources

Source: https://docs.wyzie.io/subs/usage/package

Fetches the list of currently enabled subtitle sources that can be queried.

```APIDOC
## Get Sources

### Description
Fetches the list of currently enabled subtitle sources.

### Method
`getSources` (function)

### Parameters
None

### Request Example
```javascript
import { getSources } from "wyzie-lib";

const sources = await getSources();
console.log(sources);
```

### Response
#### Success Response (SourcesResponse)
- **sources** (Array<string>) - A list of enabled subtitle provider names.

#### Response Example
```json
{
  "sources": ["OpenSubtitles", "Podnapisi", "Subscene"]
}
```
```

--------------------------------

### API Request Parameters

Source: https://docs.wyzie.io/subs/usage/direct

These are examples of query parameters that can be appended to API requests to filter and specify subtitle search criteria. An API key is always required.

```url
/search?id=tt3659388
```

```url
/search?id=tt0121955&season=1&episode=1
```

```url
/search?id=tt3659388&language=en,es
```

```url
/search?id=tt3659388&format=srt,ass
```

```url
/search?id=tt3659388&hi=true
```

```url
/search?id=tt3659388&encoding=utf-8,latin-1
```

```url
/search?id=tt3659388&source=subdl,podnapisi
```

```url
/search?id=tt3659388&release=martian,1080p
```

```url
/search?id=tt3659388&file=proper
```

```url
/search?id=tt3659388&origin=WEB,BLURAY
```

```url
/search?id=tt3659388&key=YOUR_KEY
```

```url
/search?id=tt3659388&refresh=true
```

--------------------------------

### Fetch Enabled Sources

Source: https://docs.wyzie.io/subs/sources

Programmatically fetch the list of currently enabled subtitle sources. This GET request returns a JSON object containing an array of source names.

```http
GET /sources
```

```json
{
  "sources": ["subdl", "subf2m", "opensubtitles", "podnapisi", "animetosho", "gestdown", "jimaku", "kitsunekko", "yify", "ajatttools"]
}
```

--------------------------------

### Example API Response Structure

Source: https://docs.wyzie.io/subs/usage/direct

This JSON object represents the data returned by a successful API request for subtitle information. It includes details about the subtitle file, its media, and source.

```json
{
  "id": "1955024019",
  "url": "https://sub.wyzie.io/c/198e0c4d/id/1955024019?format=srt&encoding=UTF-8",
  "flagUrl": "https://flagsapi.com/US/flat/24.png",
  "format": "srt",
  "encoding": "UTF-8",
  "display": "English",
  "language": "en",
  "media": "The Martian",
  "isHearingImpaired": false,
  "source": "opensubtitles",
  "release": "The.Martian.2015.1080p.WEB-DL",
  "releases": ["The.Martian.2015.1080p.WEB-DL"],
  "fileName": "the.martian.2015.1080p.web-dl.srt",
  "origin": "WEB-DL",
  "matchedRelease": "The.Martian.2015.1080p.WEB-DL",
  "matchedFilter": "martian"
}
```

--------------------------------

### Build i6.shark Application

Source: https://docs.wyzie.io/i6shark/hosting

Compile the i6.shark application using the Go build command. This creates an executable file named 'i6shark'.

```bash
cd /opt/i6.shark
sudo go build -o i6shark ./src
```

--------------------------------

### Configure i6.shark Constants

Source: https://docs.wyzie.io/i6shark/hosting

Edit the constants in `src/consts.go` to match your server's configuration, including SharedSecret, IPv6Prefix, and Interface. Use nano or your preferred editor.

```go
const (
  SharedSecret = "your-shared-secret-here"  // Secret between client & server
  Version      = "3.1"                      // Version of the script
  IPv6Prefix   = "xxxx:xxxx:xxxx"            // Your /48 prefix
  IPv6Subnet   = "6000"                      // Subnet within your /48
  Interface    = "ens3"                       // Network interface
  ListenPort   = 80                           // Proxy server port
  ListenHost   = "0.0.0.0"                    // Listen on all interfaces
  Debug        = false                        // Enable debug output
)
```

--------------------------------

### Clone i6.shark Repository

Source: https://docs.wyzie.io/i6shark/hosting

Clone the i6.shark repository to the specified directory and navigate into it. Ensure you have sudo privileges.

```bash
sudo git clone https://github.com/wyziedevs/i6.shark.git /opt/i6.shark
cd /opt/i6.shark
```

--------------------------------

### NPM Package: Global Configuration with API Key

Source: https://docs.wyzie.io/subs/usage/api-keys

Configure the `wyzie-lib` globally with your API key using the `configure` function. This ensures all subsequent requests automatically include the key.

```javascript
import { configure, searchSubtitles } from "wyzie-lib";
 
configure({
  baseUrl: "https://sub.wyzie.io",
  key: "YOUR_KEY",
});

// key is now included in every request
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
});
```

--------------------------------

### Build Wyzie Proxy

Source: https://docs.wyzie.io/proxy/hosting

Build the Wyzie Proxy project. The output will be in the /.output/server folder. For Cloudflare Workers, copy index.mjs.

```bash
pnpm build
```

--------------------------------

### Create i6.shark Systemd Service

Source: https://docs.wyzie.io/i6shark/hosting

Create a systemd service file for i6.shark to manage its lifecycle. This ensures the proxy runs automatically on boot and restarts if it crashes.

```bash
sudo tee /etc/systemd/system/i6shark.service >/dev/null <<'EOF'
[Unit]
Description=i6.shark IPv6 proxy
After=network-online.target
Wants=network-online.target
 
[Service]
WorkingDirectory=/opt/i6.shark
ExecStart=/opt/i6.shark/i6shark
Restart=always
RestartSec=3
User=root
AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_NET_ADMIN
 
[Install]
WantedBy=multi-user.target
EOF
```

--------------------------------

### NPM Package Usage with API Key

Source: https://docs.wyzie.io/subs/usage/api-keys

You can pass the API key directly in the `searchSubtitles` function or configure it globally using `configure`.

```APIDOC
## NPM Package Usage with API Key

Pass `key` alongside your other search parameters:

### Request Example (Direct)
```javascript
import { searchSubtitles } from "wyzie-lib";
 
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
  key: "YOUR_KEY",
});
```

Or set it once globally with `configure` so every request includes it automatically:

### Request Example (Global Configuration)
```javascript
import { configure, searchSubtitles } from "wyzie-lib";
 
configure({
  baseUrl: "https://sub.wyzie.io",
  key: "YOUR_KEY",
});
 
// key is now included in every request
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
});
```
```

--------------------------------

### Configuration

Source: https://docs.wyzie.io/subs/usage/package

Allows configuring the base URL for API requests and setting a default API key.

```APIDOC
## Configuration

### Description
Configures the API hostname and default API key for the package.

### Method
`configure` (function)

### Parameters
- **options** (object) - Configuration options.
  - **baseUrl** (string) - Optional - The custom API hostname to use for requests.
  - **key** (string) - Optional - The default API key to use for requests. Can be overridden in individual calls.

### Request Example
```javascript
import { configure, searchSubtitles } from 'wyzie-lib';

configure({
  baseUrl: 'https://my-custom-subtitle-scraper.com',
  key: 'YOUR_DEFAULT_KEY',
});

const subtitles = await searchSubtitles({
  tmdb_id: 123456,
  language: "en"
});
```
```

--------------------------------

### NPM Package: Search with API Key

Source: https://docs.wyzie.io/subs/usage/api-keys

Pass the `key` parameter directly within the `searchSubtitles` function options when using the `wyzie-lib` NPM package.

```javascript
import { searchSubtitles } from "wyzie-lib";
 
const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
  key: "YOUR_KEY",
});
```

--------------------------------

### Direct Fetching with API Key

Source: https://docs.wyzie.io/subs/usage/api-keys

Append `&key=YOUR_KEY` to your direct API requests for authentication and usage tracking.

```url
https://sub.wyzie.io/search?id=tt3659388&key=YOUR_KEY
https://sub.wyzie.io/search?id=286217&language=en&key=YOUR_KEY
https://sub.wyzie.io/search?id=tt0121955&season=1&episode=1&key=YOUR_KEY
```

--------------------------------

### Specify Subtitle Sources

Source: https://docs.wyzie.io/subs/sources

Use the 'source' parameter to specify which provider(s) to query. Multiple sources can be specified as a comma-separated list. Defaults to 'opensubtitles' if not specified.

```bash
/search?id=tt3659388&source=subdl&key=YOUR_KEY
```

```bash
/search?id=tt3659388&source=subdl,subf2m&key=YOUR_KEY
```

```bash
/search?id=tt3659388&source=all&key=YOUR_KEY
```

--------------------------------

### Direct Fetching API

Source: https://docs.wyzie.io/subs/usage/direct

This section details the parameters available for directly fetching Wyzie Subs data. An API key is required for all requests.

```APIDOC
## Direct Fetching API

### Description
This API allows direct fetching of Wyzie Subs data. An API key is required for all requests. You can obtain a free key at sub.wyzie.io/redeem.

### Parameters

#### Query Parameters

- **id** (string) - Required - TMDB or IMDB ID of the show or movie. For IMDB IDs, include the 'tt' prefix.
- **season** (integer) - Optional - Season number for TV searches. Must be provided with `episode`.
- **episode** (integer) - Optional - Episode number for TV searches. Must be provided with `season`.
- **language** (string) - Optional - Comma-separated ISO 639-1 codes for language filtering (e.g., `en,es`).
- **format** (string) - Optional - Comma-separated subtitle formats to return (e.g., `srt,ass`).
- **hi** (boolean) - Optional - If `true`, prefers hearing-impaired subtitles.
- **encoding** (string) - Optional - Comma-separated character encoding filters (e.g., `utf-8,latin-1`).
- **source** (string) - Optional - Comma-separated subtitle providers to query (e.g., `subdl,podnapisi`). `all` queries every enabled source. Defaults to `opensubtitles`.
- **release** (string) - Optional - Comma-separated release or scene name filters (e.g., `martian,1080p`).
- **file** (string) - Optional - Filename filters (aliases: `file`, `filename`, `fileName`).
- **origin** (string) - Optional - Comma-separated content origin filters (e.g., `WEB,BLURAY`).
- **key** (string) - Required - Your API key.
- **refresh** (boolean) - Optional - If `true`, bypasses cache and fetches fresh results.

### Response

#### Success Response (200)

- **id** (string) - The ID of the subtitle file.
- **url** (string) - The URL to the subtitle file.
- **flagUrl** (string) - URL to the flag of the language's locale.
- **format** (string) - The format of the subtitle file.
- **encoding** (string) - The character encoding of the subtitle file.
- **display** (string) - The language of the subtitle, capitalized.
- **language** (string) - The ISO 639-1 code of the language.
- **media** (string) - The name of the media that the subtitles are for.
- **isHearingImpaired** (boolean) - True if the subtitle is hearing impaired accessible.
- **source** (string) - Which source the subtitle was scraped from.
- **release** (string) - Primary release name.
- **releases** (array of strings) - Other release names compatible with the subtitle.
- **fileName** (string) - Original filename when available.
- **downloadCount** (integer) - Number of downloads on the source platform (if available).
- **origin** (string) - Content origin (e.g., WEB, BluRay, DVD).
- **matchedRelease** (string) - Release value that matched your filter (if provided).
- **matchedFilter** (string) - The user-supplied filter that matched (if provided).

### Request Example

```
GET /search?id=tt3659388&season=1&episode=1&language=en,es&format=srt&hi=true&encoding=utf-8&source=opensubtitles&release=martian&file=proper&origin=WEB&key=YOUR_KEY&refresh=true
```

### Response Example

```json
{
  "id": "1955024019",
  "url": "https://sub.wyzie.io/c/198e0c4d/id/1955024019?format=srt&encoding=UTF-8",
  "flagUrl": "https://flagsapi.com/US/flat/24.png",
  "format": "srt",
  "encoding": "UTF-8",
  "display": "English",
  "language": "en",
  "media": "The Martian",
  "isHearingImpaired": false,
  "source": "opensubtitles",
  "release": "The.Martian.2015.1080p.WEB-DL",
  "releases": ["The.Martian.2015.1080p.WEB-DL"],
  "fileName": "the.martian.2015.1080p.web-dl.srt",
  "origin": "WEB-DL",
  "matchedRelease": "The.Martian.2015.1080p.WEB-DL",
  "matchedFilter": "martian"
}
```
```

--------------------------------

### Direct Fetching with API Key

Source: https://docs.wyzie.io/subs/usage/api-keys

Append `&key=YOUR_KEY` to your direct fetching API requests to authenticate.

```APIDOC
## Direct Fetching with API Key

Append `&key=YOUR_KEY` to every API request.

### Request Example
```
https://sub.wyzie.io/search?id=tt3659388&key=YOUR_KEY
https://sub.wyzie.io/search?id=286217&language=en&key=YOUR_KEY
https://sub.wyzie.io/search?id=tt0121955&season=1&episode=1&key=YOUR_KEY
```
```

--------------------------------

### Fetch Subtitles with Wyzie Package

Source: https://docs.wyzie.io/subs/usage/package

Search for subtitles using the `searchSubtitles` function. An API key is required and can be passed via the `key` parameter. Ensure you have the necessary parameters like `tmdb_id` or `imdb_id`.

```typescript
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);
```

--------------------------------

### Clone Wyzie Proxy Repository

Source: https://docs.wyzie.io/proxy/hosting

Use this command to clone the Wyzie Proxy repository from GitHub.

```bash
git clone https://github.com/wyziedevs/wyzie-proxy.git
```

--------------------------------

### Fetch Enabled Sources

Source: https://docs.wyzie.io/subs/sources

Programmatically retrieve a list of all currently enabled subtitle sources.

```APIDOC
## GET /sources

### Description
Fetches a list of all subtitle sources that are currently enabled and available for querying.

### Method
GET

### Endpoint
/sources

### Response
#### Success Response (200)
- **sources** (array) - A list of strings, where each string is the identifier of an enabled source.

### Response Example
{
  "sources": ["subdl", "subf2m", "opensubtitles", "podnapisi", "animetosho", "gestdown", "jimaku", "kitsunekko", "yify", "ajatttools"]
}
```

--------------------------------

### Add Daily Restart Cron Job

Source: https://docs.wyzie.io/i6shark/hosting

Optionally, add a cron job to restart the i6.shark service daily at a random time between 00:00 and 23:59. This helps maintain stability.

```bash
(sudo crontab -l 2>/dev/null; echo "$(shuf -i 0-59 -n 1) $(shuf -i 0-23 -n 1) * * * systemctl restart i6shark") | sudo crontab -
```

--------------------------------

### Fetching Subtitles

Source: https://docs.wyzie.io/subs/usage/package

Demonstrates how to search for subtitles using various criteria like TMDB ID, language, format, and release information. An API key is required for all requests.

```APIDOC
## Fetching Subtitles

### Description
Searches for subtitles based on provided criteria. Requires an API key.

### Method
`searchSubtitles` (function)

### Parameters
- **tmdb_id** (number) - Required if `imdb_id` is not provided - TMDB ID of the movie or TV show.
- **imdb_id** (string) - Required if `tmdb_id` is not provided - IMDB ID of the movie or TV show.
- **format** (string[]) - Optional - File formats to return (e.g., `srt`, `ass`). Accepts a list.
- **season** (number) - Optional - Season number (requires episode).
- **episode** (number) - Optional - Episode number (requires season).
- **language** (string[]) - Optional - ISO 639-1 codes for subtitle language. Accepts a list.
- **encoding** (string) - Optional - Character encoding filter (e.g., `utf-8`, `latin-1`).
- **hi** (boolean) - Optional - Boolean for hearing-impaired subtitles.
- **source** (string[]) - Optional - Subtitle providers to query (`all` for every enabled source).
- **release** (string[]) - Optional - Release/scene filters (accepts a list).
- **filename** (string) - Optional - Filename filters; aliases `file` and `fileName` are supported.
- **origin** (string[]) - Optional - Content origin filter (e.g., `WEB`, `BLURAY`, `DVD`).
- **key** (string) - Required - Your API key. Get one free at sub.wyzie.io/redeem.
- **refresh** (boolean) - Optional - Bypass cache and fetch fresh results from sources.

### Request Example
```javascript
import { searchSubtitles } from "wyzie-lib";

const data = await searchSubtitles({
  tmdb_id: 286217,
  format: ["srt"],
  language: ["en"],
  release: ["web-dl", "1080p"],
  origin: ["WEB"],
  key: "YOUR_KEY",
});

console.log(data[0].url);
```

### Response
#### Success Response (Array of SubtitleData)
- **url** (string) - The direct URL to the subtitle file.
- **provider** (string) - The source provider of the subtitle.
- **lang** (string) - The language code of the subtitle.
- **format** (string) - The file format of the subtitle (e.g., srt, ass).
- **filename** (string) - The original filename of the subtitle.
- **filesize** (number) - The size of the subtitle file in bytes.
- **fps** (number) - Frames per second of the video the subtitle is for.
- **release** (string) - The release group or tag associated with the subtitle.
- **rating** (number) - The rating of the subtitle.
- **votes** (number) - The number of votes the subtitle has received.
- **from_cache** (boolean) - Indicates if the data was served from cache.
- **cached_at** (string) - Timestamp when the data was cached.
- **created_at** (string) - Timestamp when the subtitle was uploaded.

#### Response Example
```json
[
  {
    "url": "https://example.com/subtitle.srt",
    "provider": "OpenSubtitles",
    "lang": "en",
    "format": "srt",
    "filename": "Movie.Title.2023.1080p.WEB-DL.srt",
    "filesize": 123456,
    "fps": 23.976,
    "release": "WEB-DL",
    "rating": 8.5,
    "votes": 150,
    "from_cache": false,
    "cached_at": "2023-10-27T10:00:00Z",
    "created_at": "2023-10-26T08:00:00Z"
  }
]
```
```

--------------------------------

### Configure Wyzie Package with Custom Hostname

Source: https://docs.wyzie.io/subs/usage/package

Configure the Wyzie package to use a custom API hostname and API key. This allows you to point the package to a different backend service.

```typescript
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"
});
```

--------------------------------

### Proxying Requests with Cloudflare Workers

Source: https://docs.wyzie.io/subs/intro

Illustrates how a Cloudflare Worker can proxy client requests to the Wyzie API, automatically appending the API key server-side. Set your API key as the `NITRO_API_TOKEN` environment variable in your worker.

```text
Client → your-worker.workers.dev/search?id=286217 → sub.wyzie.io/search?id=286217&key=YOUR_KEY
```

--------------------------------

### VTT Parser

Source: https://docs.wyzie.io/subs/usage/package

Parses subtitle data into VTT format. This is a utility function provided by the package.

```APIDOC
## VTT Parser

### Description
Parses subtitle data into VTT format.

### Method
`parseToVTT` (function)

### Parameters
- **subtitleData** (SubtitleData[]) - Required - An array of subtitle data objects obtained from `searchSubtitles`.

### Request Example
```javascript
import { searchSubtitles, parseToVTT } from "wyzie-lib";

const data = await searchSubtitles({
  tmdb_id: 286217,
  language: ["en"],
  key: "YOUR_KEY",
});

const vttContent = parseToVTT(data);
console.log(vttContent);
```

### Response
#### Success Response (string)
- **vttContent** (string) - The subtitle data formatted as a VTT string.

#### Response Example
```
WEBVTT

00:00:01.000 --> 00:00:05.000
This is the first subtitle line.

00:00:06.000 --> 00:00:10.000
This is the second subtitle line.
```
```
Tokens:
Raw