anime-sdk

A Typescript SDK for searching anime and manga across multiple catalogue sources and content providers, normalizing them behind a single API, and resolving direct playable streams or page URLs (with subtitle tracks).

anime-sdk.hexxt.dev

What's in the box:

• Nine content providers (anime + manga) with live, non-mocked E2E tests.
• Three metadata providers — AniList, MAL (Jikan), Kitsu — with full enrichments (relations, characters, staff, recommendations, external links, per-episode streamingEpisodes with Jikan filler/recap flags).
• Unified URN ID space (provider:rawId) so you can swap a content provider without rewriting your call sites.
• Cross-source mapping via a four-step waterfall (cache → provider native lookup → MALSync/Anify/arm-server → fuzzy title match with year + catalogType discriminators and episode-count cross-check).
• A pluggable HTTP transport (curl fallback included), with built-in per-host rate limiting, exponential-backoff retry honouring Retry-After, and end-to-end AbortSignal propagation.
• Built-in downloads for anime (HLS → MP4) and manga (chapters → ZIP).
• An optional HTTP server with content + metadata + download routes, a header-forwarding /proxy (HMAC-signable + suffix-matched SSRF allowlist) and a GET /openapi.json spec for client codegen.

Providers

| ID | Site | Type | Languages | Subtitles | What it scrapes | | --------------- | ------------------- | ----- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | animeparadise | animeparadise.moe | Anime | sub | yes | REST API at api.animeparadise.moe; episode carries a signed streamLink token; streamed as multi-quality HLS via stream.animeparadise.moe. | | allmanga | allmanga.to | Anime | sub, dub | no | AllAnime GraphQL → AES-CTR tobeparsed payload → Mp4Upload extractor (with clock.json fallback for the wixmp/sharepoint sources). | | gogoanime | anineko.to | Anime | sub | no | Page scraping; vibeplayer embed → master.m3u8 via GenericHlsExtractor (sequential, stops on first success). | | goyabu | goyabu.io | Anime | pt-br (dub) | no | Pulls the Blogger token from playersData, then calls Google's batchexecute endpoint to recover the googlevideo.com URL. | | mangadex | mangadex.org | Manga | sub | no | Official JSON API at api.mangadex.org with cover art and high-quality page resolution. | | weebcentral | weebcentral.com | Manga | sub | no | Page scraping; extracts high-quality images with referer protection. | | mangapill | mangapill.com | Manga | sub | no | Page scraping; efficient extraction of chapter page lists and direct image sources. | | anikoto | anikototv.to | Anime | sub, dub | yes | Page scraping; uses anikotoapi.site for episodes, and megaplay.buzz for stream and subtitle extraction. | | megaplay | megaplay.buzz | Anime | sub, dub | yes | Uses AniList GraphQL for search and episodes, and resolves streams directly against MegaPlay's AniList mapping endpoints. |

Every provider has a live E2E test that searches, picks an episode/chapter, resolves the stream/pages, and captures a real video frame or verifies page links.

Metadata providers

| ID | Catalogue | Native ID shape | Enrichments | | --------- | --------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------- | | anilist | AniList GraphQL | anilist:21 | full metadata + relations + characters (with voice actors) + staff + recommendations + externalLinks + streamingEpisodes + browse | | mal | MyAnimeList | mal:anime:21 | filler/recap flags via Jikan episodes + relations + browse(top/popular/seasonal) | | kitsu | Kitsu JSON:API | kitsu:anime:1 | core metadata + cross-source mappings (AniList/MAL/AniDB/TVDB) |

Architecture

src/
├── transport/
│   ├── http.ts              HttpClient: rate-limit + retry + AbortSignal + pluggable transport
│   ├── transport.ts         HttpTransport interface; CurlFallbackTransport (default), FetchTransport
│   ├── rateLimiter.ts       Per-host token bucket with secondary burst window
│   ├── retry.ts             withRetry + Retry-After parser
│   ├── dom.ts               DOMParser registry (auto-registers linkedom in Node)
│   └── hlsUtils.ts          Rewrite m3u8 chunk URLs through a proxy
├── extractors/
│   ├── Mp4UploadExtractor   Direct mp4 from www.mp4upload.com
│   ├── BloggerExtractor     Google batchexecute → googlevideo URLs
│   ├── VidstreamingExtractor  Legacy Gogo encrypt-ajax flow
│   └── GenericHlsExtractor  Best-effort m3u8/mp4 scrape from an embed page
├── providers/
│   ├── BaseProvider         URN wrap/unwrap, concurrency cap, lookupByMapping hook, malsyncSites
│   ├── AllmangaProvider, AnikotoProvider, AnimeParadiseProvider, GogoanimeProvider,
│   ├── GoyabuProvider, MangadexProvider, MangapillProvider, MegaPlayProvider, WeebcentralProvider
├── meta/
│   ├── BaseMetadataProvider Episode picking + IContentUnit enrichment + absolute-episode rescue
│   ├── AnilistMeta, MalMeta, KitsuMeta
│   ├── MappingClient        cache → provider → MALSync/Anify/arm-server → fuzzy waterfall
│   └── similarity.ts        normalizeTitle, dice + token Jaccard + prefix composite
├── download/                Built-in HLS → MP4 and chapter → ZIP download helpers
├── server/index.ts          startServer: /search, /content, /stream, /tracks, /meta/*, /download/*, /proxy, /openapi.json, /health
├── types/index.ts           CallOptions, IMediaSearchResult, IMediaMetadata, IContentUnit, …
└── utils/
    ├── crypto.ts            AES-CBC + AES-CTR helpers
    ├── subtitles.ts         normalizeSubtitleEntries, proxifySubtitleUrl (with signSecret)
    └── urn.ts               buildUrn, unwrapUrn, strictUnwrapUrn, buildTypedUrn, parseTypedUrn

Unified URN IDs

Every id flowing in or out of the SDK has shape ${providerId}:${rawId}:

allmanga:5jzpRTJWnubrgHm5G          # media URN
allmanga:5jzpRTJWnubrgHm5G/1        # content-unit URN
anilist:21                          # meta URN (single ID namespace)
mal:anime:21                        # typed catalogue URN (anime/manga distinction)
kitsu:manga:13                      # typed catalogue URN

The first colon is the separator; raw IDs may themselves contain colons or slashes. Use strictUnwrapUrn when a URN must belong to a specific provider (the server enforces this on /meta/info).

A provider is just a class with search, fetchContentUnits, and resolveStream. fetchContentUnits is language-agnostic — it returns one unified list and each IContentUnit carries availableLanguages so the caller can pick at resolveStream time. Providers may optionally implement fetchUnitTracks(unitId, language?) to expose subtitle/quality metadata cheaply (no full stream resolution). Extractors are stateless and take a HttpClient, so you can mix and match (or use the extractors on their own).

Usage

import { HttpClient, AllmangaProvider, MangadexProvider } from 'anime-sdk';

const http = new HttpClient({ timeoutMs: 25_000 });

// Anime
const anime = new AllmangaProvider(http);
const shows = await anime.search('Frieren');
const eps = await anime.fetchContentUnits(shows[0].id);
const stream = await anime.resolveStream(eps[0].id, 'sub');

// Manga
const manga = new MangadexProvider(http);
const books = await manga.search('Frieren');
const chapters = await manga.fetchContentUnits(books[0].id);
const pages = await manga.resolveStream(chapters[0].id);

if (pages.type === 'manga') {
  console.log(pages.pages.imageUrls); // Array of high-res page URLs
}

Cross-source: metadata + content provider

The metadata layer lets you swap content providers without changing anything else. Mapping (AniList ID → AllManga raw ID) happens automatically:

import {
  HttpClient,
  AnilistMeta,
  MappingClient,
  AllmangaProvider,
  GogoanimeProvider,
} from 'anime-sdk';

const http = new HttpClient();
const mapping = new MappingClient(http);
const meta = new AnilistMeta(http, { mappingClient: mapping });

// Pull rich metadata from AniList (relations, characters, streamingEpisodes…)
const info = await meta.fetchMediaInfo('anilist:1');
console.log(info.title.english, info.streamingEpisodes?.[0].title);

// Resolve a stream on any content provider using the same AniList URN.
const allmanga = new AllmangaProvider(http);
const stream = await meta.resolveStream('anilist:1', 1, allmanga, 'sub');

// Or swap to a different content provider — no other changes.
const gogo = new GogoanimeProvider(http);
const stream2 = await meta.resolveStream('anilist:1', 1, gogo, 'sub');

Browse the catalogue

const trending = await meta.browse('trending', { catalogType: 'ANIME', perPage: 10 });
const seasonal = await meta.browse('seasonal', { season: 'FALL', year: 2024 });
const top = await meta.browse('top');

HTTP server with proxy + cache + metadata routes

import {
  HttpClient,
  startServer,
  AllmangaProvider,
  MangadexProvider,
  AnilistMeta,
  MalMeta,
} from 'anime-sdk';

const http = new HttpClient();
const store = new Map();
const cache = {
  get: (key) => store.get(key),
  set: (key, value) => void store.set(key, value),
};

startServer({
  providers: [new AllmangaProvider(http), new MangadexProvider(http)],
  metaProviders: [new AnilistMeta(http), new MalMeta(http)],
  port: 3000,
  proxy: true,
  proxySignSecret: process.env.PROXY_SECRET, // optional: signs /proxy URLs
  proxyAllowedHosts: ['wixstatic.com', 'allanime.day'], // optional SSRF allowlist
  cache,
});

Routes the server exposes:

| Route | Purpose | | ----------------------------- | -------------------------------------------------------------------------------------- | | GET /search | Search a content provider | | GET /content | Episode/chapter list for a media URN | | GET /stream | Resolve a playable stream for a unit URN | | GET /tracks | Cheap subtitle/quality list (501 if provider doesn't support it) | | GET /meta/search | Search a metadata catalogue | | GET /meta/info | Full IMediaMetadata for a meta URN | | GET /meta/content | Episode list for a meta URN, resolved via a content provider | | GET /meta/stream | Resolve a stream by metadata + episode number | | GET /meta/tracks | Cheap tracks for an episode (501 if provider doesn't support it) | | GET /meta/browse | Trending / popular / seasonal / top | | GET /download/video | Download an anime episode as MP4 | | GET /download/manga/page | Download a single manga page | | GET /download/manga/chapter | Download a manga chapter as a ZIP | | GET /proxy | CORS-friendly upstream proxy (header forwarding, HLS rewrite, optional HMAC signature) | | GET /openapi.json | OpenAPI 3.1 spec describing every route | | GET /health | Health + capability check |

Direct extractor use

Extractors work standalone — hand them an embed URL from any source and they'll return a list of IVideoPayload (or an empty array if they can't recover a direct stream).

import { HttpClient, BloggerExtractor } from 'anime-sdk';

const blogger = new BloggerExtractor(new HttpClient());
const streams = await blogger.extract('https://www.blogger.com/video.g?token=AD6v5dw…');

Cancellation

Every public method takes a CallOptions bag with an optional AbortSignal. It's threaded all the way down to fetch, the rate limiter (so a long queue can be drained on abort), and the retry loop.

const ac = new AbortController();
setTimeout(() => ac.abort(), 1500);
const results = await meta.search('frieren', { signal: ac.signal });

Tests

# Everything (unit + live e2e, ~60s total)
npx vitest run

# Just the live providers
npx vitest run tests/e2e

The E2E suite is intentionally not mocked. Each test:

1. Searches a popular title (Frieren for AllManga/Gogoanime, Naruto Clássico for Goyabu).
2. Picks a mainline entry, fetches episodes, resolves a stream.
3. Walks the candidate list via captureStreamScreenshot, which:

• probes a URL with a Range GET (Content-Type + MP4 ftyp magic) to tell embed pages from direct video bytes,
• scrapes embed HTML for an .m3u8/.mp4 URL when needed,
• downloads an HLS segment ~5s in and runs ffmpeg locally on it (PNG-wrapped segments are stripped before decoding), or
• hands plain MP4 URLs straight to ffmpeg with -user_agent/-referer,

4. Asserts the resulting PNG is >1KB before passing.

Screenshots land in scratch/screenshots/screenshot_<provider>.png. scratch/ is gitignored.

The tests are all real. See CLAUDE.md for the non-negotiable testing rules — short version: no mocked network requests, no fake/fixture data, no graceful skipping. A test must pass for real or be deleted.

Requirements

• Node 20+ (uses fetch, globalThis.crypto.subtle, top-level await in tests).
• ffmpeg on PATH for the E2E suite.

License

MIT

DMCA

anime-sdk does not host, store, or distribute any media content. It resolves publicly accessible URLs served by third-party sites. For copyright concerns about content on those sites, contact them directly. To report infringement in the SDK code or this repository, open an issue tagged legal.