@media-engine/providers 1.0.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Media Engine contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Media Engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,79 +2,66 @@
 
 **English** | [Русский](https://github.com/Yaneart/media-engine/blob/main/packages/providers/README.ru.md)
 
-Ready-to-use data sources for Media Engine.
+Ready-to-use data sources for Media Engine. Install this package when you want to search real public
+catalogs without writing provider adapters yourself.
 
-Install this package when you do not want to write your own provider adapters.
+## Install
 
 ```bash
 npm install @media-engine/core @media-engine/providers
 ```
 
-## A small setup
+The built-in providers do not need your API keys.
+
+## Search metadata
 
 ```ts
 import { MediaEngine } from "@media-engine/core";
 import {
   aniListProvider,
-  ddbbStreamingProvider,
-  flixHqStreamingProvider,
+  cinemetaProvider,
   kinobdProvider,
-  kinobdStreamingProvider,
   shikimoriProvider,
-  tvMazeProvider,
 } from "@media-engine/providers";
 
 const media = new MediaEngine({
-  providers: [kinobdProvider(), shikimoriProvider(), aniListProvider(), tvMazeProvider()],
+  providers: [
+    kinobdProvider(),
+    cinemetaProvider(),
+    shikimoriProvider(),
+    aniListProvider(),
+  ],
 });
 
 const result = await media.search({ title: "One Piece" });
 ```
 
-Add only the providers that make sense for your application. Media Engine will call compatible ones and merge matching answers.
-
-## Available metadata sources
-
-- `kinobdProvider()` — localized movie and series data;
-- `cinemetaProvider()` — IMDb-linked movie and series data;
-- `shikimoriProvider()` — anime search and details;
-- `aniListProvider()` — international anime titles, popularity, and artwork;
-- `tvMazeProvider()` — fallback IMDb-backed series identities and localized aliases;
-- `wikidataProvider()` — fallback structured identity and metadata enrichment;
-- `imdbDatasetProvider()` — local IMDb data supplied as small in-memory TSV fixtures or through an application-owned indexed storage adapter.
-
-None of these built-in providers needs your API key. TMDB IDs may appear in results, but this package does not call the TMDB API.
+Connect only the sources your application needs. The engine calls suitable providers and merges
+matching results for you.
 
-TVmaze data is licensed under CC BY-SA. The provider keeps a TVmaze show URL in source attribution; applications using TVmaze data should preserve and render that link. See the [TVmaze API licensing terms](https://www.tvmaze.com/api#licensing).
+Available metadata providers:
 
-Wikidata fallback discovery loads at most three title-relevant entities through a selected-property query and caches entity/IMDb mappings for six hours in a 256-entry process-local LRU by default. `entityLimit` is bounded to 1–10, `cacheTtlMs` to 0–7 days, and `cacheMaxEntries` to 2–2048; a zero TTL disables this provider-local cache.
+- `kinobdProvider()` and `cinemetaProvider()` for movies and series;
+- `shikimoriProvider()` and `aniListProvider()` for anime;
+- `tvMazeProvider()` and `wikidataProvider()` as additional identity sources;
+- `imdbDatasetProvider()` for an IMDb dataset managed by your application.
 
-The backward-compatible IMDb TSV adapter parses the complete input into memory and is intended for small datasets and fixtures. Full-dataset integrations can inject the exported synchronous/asynchronous `ImdbDatasetStorage` contract, including a direct ID lookup and bounded normalized title search, without adding a database dependency for other package users.
+TVmaze data requires attribution. Keep and display the TVmaze source link included in a result. See
+the [TVmaze API license](https://www.tvmaze.com/api#licensing).
 
-An included persisted adapter can stream plain or gzip IMDb TSV files into a versioned, atomically replaced SQLite/FTS index. `buildImdbDatasetSqliteIndex()` creates it and `openImdbDatasetSqliteStorage()` opens it read-only for `imdbDatasetProvider({ storage })`. This optional path lazily uses built-in `node:sqlite` and requires Node.js 22.13 or newer; importing the package or using the small in-memory adapter keeps the Node.js 20 baseline.
+The optional SQLite-backed IMDb dataset tools need Node.js 22.13 or newer. Everything else in the
+package keeps the normal Node.js 20 baseline.
 
-Expected upstream failures are reported as typed `ProviderError` values, and shared HTTP errors expose their originating status through `getProviderHttpStatus`. An untyped Cinemeta IMDb lookup returns `null` only after both movie and series candidates confirm absence; a temporary branch outage remains retryable unless the other branch returned usable details. AniList similarly distinguishes GraphQL rate limits and server outages from validation errors or malformed payloads, allowing Media Engine to avoid caching incomplete metadata as a healthy response.
-
-Shared `fetchJson` calls stream at most 4 MiB by default before parsing and accept a positive `maxResponseBytes` override for provider-specific limits. A declared or chunked oversized body is cancelled and reported as the non-retryable `PROVIDER_RESPONSE_TOO_LARGE`; malformed JSON within the limit remains `PROVIDER_INVALID_RESPONSE`.
-
-Low-level adapters may supply a `ProviderHttpScheduler` through `FetchJsonOptions.scheduler` when
-they need deterministic control of retry and total-timeout timers, especially in tests. Normal
-provider calls omit it and use the platform timers.
-
-## Player sources
-
-- `kinobdStreamingProvider()` — movie, series, and anime player options;
-- `flixHqStreamingProvider()` — international movie and selected series-episode options;
-- `ddbbStreamingProvider()` — opt-in Kinopoisk/IMDb lookup through an independent DDBB player route;
-- `aniLibertyStreamingProvider()` — opt-in exact title/year anime lookup with direct HLS episodes;
-- `experimentalStreamingProvider()` — data configured by your own application, useful in tests and UI work.
+## Find player options
 
 ```ts
+import {
+  flixHqStreamingProvider,
+  kinobdStreamingProvider,
+} from "@media-engine/providers";
+
 const media = new MediaEngine({
-  streamingProviders: [
-    kinobdStreamingProvider(),
-    flixHqStreamingProvider(),
-  ],
+  streamingProviders: [kinobdStreamingProvider(), flixHqStreamingProvider()],
 });
 
 const result = await media.getAvailability({
@@ -85,87 +72,38 @@ const result = await media.getAvailability({
 });
 ```
 
-These are third-party player targets, not videos hosted by Media Engine. Availability depends on the upstream source and the user's environment.
-
-The repository API enables `ddbbStreamingProvider()` after its repeated reliability/diversity
-checkpoint; direct package consumers still choose their own provider list explicitly. It accepts
-only Kinopoisk or IMDb IDs, returns generic movie/series/anime embeds, and does not claim exact
-season/episode mapping. Its diversity-first mapping keeps one main option per returned player before
-adding unique translation URLs. Missing nullable players produce no result; confirmed 404/410 or
-stable deletion markers are removed, while transient validation failures remain `unknown`.
+The package also exports `ddbbStreamingProvider()`, `aniLibertyStreamingProvider()`,
+`filmixStreamingProvider()`, `veoVeoStreamingProvider()`, `videoHubStreamingProvider()`,
+`rutubeStreamingProvider()`, and
+`experimentalStreamingProvider()`.
+Add them explicitly when they fit your application. Filmix guest mode is capped at 480p and filters
+known copyright/service placeholder videos. A user-owned device token raises the cap to 720p.
+Authenticated mode requires an HTTPS `baseUrl` unless the application explicitly enables
+`allowInsecureHttpToken` for a local compatibility test. That override sends the token without TLS
+and must not be used in a public deployment. Returned CDN video URLs use HTTPS. VeoVeo uses DDBB only to resolve its
+public content ID, discards the iframe token, and returns direct signed HTTPS HLS. VideoHUB uses a Kinopoisk ID and returns
+short-lived direct MP4 qualities for movies or one exact series episode. Its links are bound to the
+playback User-Agent and may also be bound to the requesting public IP. Pass the playback client's
+exact User-Agent as `MediaEngineOperationOptions.playbackUserAgent`; the required value is retained
+in each option's `access.headers` for non-browser clients.
+Rutube performs a bounded exact title/year movie search and returns only Rutube's documented public
+embed player. It does not expose or proxy Rutube media URLs and intentionally skips series.
+
+These providers return third-party links or streams. Media Engine does not host the video, and an
+external player may be unavailable in some countries, networks, or browsers.
+
+## Discover torrent releases
+
+Torrent providers are always opt-in:
 
 ```ts
-const media = new MediaEngine({
-  streamingProviders: [
-    kinobdStreamingProvider(),
-    flixHqStreamingProvider(),
-    ddbbStreamingProvider(), // explicit opt-in
-    aniLibertyStreamingProvider(), // explicit opt-in
-  ],
-});
-```
-
-The repository API also enables `aniLibertyStreamingProvider()` after that checkpoint. Because
-AniLiberty does not publish MAL, AniList, or Shikimori IDs for releases, the adapter requires both
-title and year, accepts only one exact normalized match, and revalidates the loaded release before
-returning streams. It supports generic episode maps and exact `absoluteEpisodeNumber` queries, but
-does not guess season/episode mappings. Each safe first-party 480p/720p/1080p URL is returned as
-direct HLS; release geo and copyright blocks are preserved as normalized availability states.
-
-Live player validation removes an option only after HTTP 404/410 or a stable deletion marker. Rate limits, server errors, network failures, and validation timeouts keep the discovered option with `availability: "unknown"`, allowing the engine to expose the degradation and retry it instead of caching a transiently reduced result.
-
-KinoBD bounds one availability lookup to 24 child HTTP attempts by default and validates at most eight discovered players through three workers. Public tuning remains bounded (`childRequestLimit` up to 64, `playerValidationLimit` up to 16, and `playerValidationConcurrency` up to 4). Nested iframe validation starts only when the fixed provider deadline can still grant a full validation window. `onPlayerAudit` receives additive `metrics` for discovered and validated players, limit/budget skips, transient unknown results, confirmed removals, and consumed child requests.
-
-FlixHQ site navigation cannot leave its configured origin, including through redirects. External player and subtitle checks resolve every A/AAAA answer, reject private, local, reserved, multicast, or mixed public/private destinations, validate every bounded redirect hop, and pin the connection to the approved address. A custom provider `fetch` is an explicit trusted transport injection intended for controlled tests or self-hosted environments; it is responsible for equivalent network policy.
-
-DDBB caps its JSON response, output option count, live validation count, validation concurrency,
-validation body size, and per-player timeout. Its default transport applies the same hardened DNS,
-redirect, and connection-pinning policy to the DDBB endpoint and returned players. A custom `fetch`
-is the same explicit trusted test/self-hosted boundary used by the other streaming providers. Options
-beyond the bounded validation count remain visible with `availability: "unknown"`; they are never
-presented as successfully checked. Alloha is represented by one main option because voiceovers can
-be switched inside that player; if no main iframe exists, at most one safe translation URL becomes
-the entry point. Other player families keep their distinct translation options.
-
-AniLiberty bounds search candidates, release episodes, JSON bytes, retries, and total provider time
-through the shared engine/provider controls. Its default transport uses the hardened DNS, redirect,
-and connection-pinning policy for API calls. Direct HLS targets still pass the shared browser-facing
-output URL policy; playback network policy remains the consuming application's responsibility.
-
-Before built-in providers expose artwork, player, or subtitle URLs, one output policy accepts only HTTP(S) targets without credentials, raw control characters, or literal local/private/reserved addresses. Valid paths and CDN query parameters, including expiring signatures, are preserved. This browser-facing check does not replace DNS validation or an application-owned media proxy.
-
-## Torrent discovery sources
-
-`ytsTorrentProvider()` is an opt-in no-key movie source. It resolves an exact IMDb identity or one
-exact title/year match and returns normalized 720p/1080p/2160p-style magnet candidates with size,
-release metadata, and best-effort peer counts.
-
-`jacRedTorrentProvider()` is an opt-in no-key Russian/multilingual source for exact title/year
-movie, series, and anime lookup. It can filter a requested season, but intentionally returns no
-result for exact ordinary or absolute episode queries. Returned title, year, category, season,
-info hash, source URL, release metadata, and peer fields are bounded and revalidated. Each result
-also retains the bounded JacRed tracker ID as `catalogSource`; known values receive labels such as
-BitRu, RuTracker, RuTor, Kinozal, NNM-Club, and Knaben without implying a guaranteed audio
-language. Its
-`baseUrl` and `searchPath` are configurable because the live first-party route and published route
-currently differ.
-
-`bitsearchTorrentProvider()` is an opt-in no-key broad international source. It requires title and
-year, pins movie/TV/anime categories, and revalidates the exact release title, explicit year, media
-type, requested season, and requested ordinary or absolute episode before returning a candidate.
-It consumes only the documented bounded search response, remembers an exhausted anonymous quota
-from `X-RateLimit-*`, and emits one canonical magnet per validated info hash. The public anonymous
-tier is currently limited to 200 requests/day per IP, so applications should keep engine caching
-enabled and avoid speculative calls.
-
-`magnetzTorrentProvider()` is an opt-in no-key international meta-search source. It performs one
-bounded first-page search request, then revalidates exact title, year, season, and ordinary or
-absolute episode markers locally. It never fans out into per-result detail calls. The adapter emits
-one canonical magnet per validated info hash, preserves reported peer state and source attribution,
-and spaces request starts by one second because the live service has returned short burst 429s even
-while its rate-limit header still reported capacity.
+import {
+  bitsearchTorrentProvider,
+  jacRedTorrentProvider,
+  magnetzTorrentProvider,
+  ytsTorrentProvider,
+} from "@media-engine/providers";
 
-```ts
 const media = new MediaEngine({
   torrentProviders: [
     ytsTorrentProvider(),
@@ -173,15 +111,9 @@ const media = new MediaEngine({
     bitsearchTorrentProvider(),
     magnetzTorrentProvider(),
   ],
-  providerTimeouts: {
-    "yts-torrent": 15_000,
-    "jacred-torrent": 20_000,
-    "bitsearch-torrent": 15_000,
-    "magnetz-torrent": 15_000,
-  },
 });
 
-const torrents = await media.discoverTorrents({
+const result = await media.discoverTorrents({
   type: "movie",
   title: "Inception",
   year: 2010,
@@ -189,13 +121,12 @@ const torrents = await media.discoverTorrents({
 });
 ```
 
-The provider does not download torrent metadata, contact trackers, join a swarm, or play video.
-The completed multi-source checkpoint kept repository API defaults empty: Bitsearch has a small
-anonymous daily quota, Magnetz exposes burst-sensitive limits, and JacRed still has an occasional
-long timeout tail. Applications can opt into any subset explicitly and monitor it with
-`pnpm smoke:torrents`; package consumers remain in control of their own request budget.
+Discovery only returns normalized candidates and their handoff data. It does not download torrent
+metadata, contact trackers, join a swarm, or play a file.
 
-Provider options, limitations, and safety rules are summarized in the [provider guide](https://github.com/Yaneart/media-engine/blob/main/docs/providers.md).
+Public sources can change, rate-limit requests, or go offline. Keep engine caching enabled and
+expect occasional partial results. Provider-specific settings and safety boundaries are described in
+the [provider guide](https://github.com/Yaneart/media-engine/blob/main/docs/providers.md).
 
 ## License
 

package/README.ru.md

@@ -2,172 +2,111 @@
 
 [English](https://github.com/Yaneart/media-engine/blob/main/packages/providers/README.md) | **Русский**
 
-Готовые источники данных для Media Engine.
+Это готовые источники данных для Media Engine. Установите пакет, если хотите искать в реальных
+публичных каталогах и не писать адаптеры самостоятельно.
 
-Установите этот пакет, если не хотите писать собственные адаптеры провайдеров.
+## Установка
 
 ```bash
 npm install @media-engine/core @media-engine/providers
 ```
 
-## Небольшой пример
+Для встроенных провайдеров ваши API-ключи не нужны.
+
+## Поиск метаданных
 
 ```ts
 import { MediaEngine } from "@media-engine/core";
 import {
   aniListProvider,
-  ddbbStreamingProvider,
-  flixHqStreamingProvider,
+  cinemetaProvider,
   kinobdProvider,
-  kinobdStreamingProvider,
   shikimoriProvider,
-  tvMazeProvider,
 } from "@media-engine/providers";
 
 const media = new MediaEngine({
-  providers: [kinobdProvider(), shikimoriProvider(), aniListProvider(), tvMazeProvider()],
+  providers: [
+    kinobdProvider(),
+    cinemetaProvider(),
+    shikimoriProvider(),
+    aniListProvider(),
+  ],
 });
 
 const result = await media.search({ title: "Ван-Пис" });
 ```
 
-Подключайте только те провайдеры, которые нужны вашему приложению. Media Engine сам вызовет подходящие и объединит совпадающие ответы.
-
-## Провайдеры метаданных
-
-- `kinobdProvider()` — локализованные данные фильмов и сериалов;
-- `cinemetaProvider()` — данные фильмов и сериалов, связанные с IMDb;
-- `shikimoriProvider()` — поиск и детали аниме;
-- `aniListProvider()` — международные названия аниме, популярность и изображения;
-- `tvMazeProvider()` — резервные IMDb identity сериалов и локализованные aliases;
-- `wikidataProvider()` — резервная проверка identity и обогащение открытыми структурированными данными;
-- `imdbDatasetProvider()` — локальные данные IMDb в виде небольших in-memory TSV fixtures или через индексированный storage adapter приложения.
-
-Для встроенных провайдеров не нужен ваш API-ключ. TMDB ID может встретиться в результате, но сам пакет не обращается к TMDB API.
+Подключайте только те источники, которые нужны вашему приложению. Движок сам вызовет подходящие
+провайдеры и объединит совпадающие результаты.
 
-Данные TVmaze распространяются по лицензии CC BY-SA. Провайдер сохраняет ссылку на страницу сериала TVmaze в source attribution; приложению следует сохранять и показывать эту ссылку. См. [условия API TVmaze](https://www.tvmaze.com/api#licensing).
+Готовые провайдеры метаданных:
 
-Резервный поиск Wikidata загружает не больше трёх релевантных title entities через selected-property запрос и по умолчанию кеширует entity/IMDb mappings на шесть часов в process-local LRU на 256 записей. `entityLimit` ограничен диапазоном 1–10, `cacheTtlMs` — 0–7 дней, `cacheMaxEntries` — 2–2048; нулевой TTL отключает локальный cache провайдера.
+- `kinobdProvider()` и `cinemetaProvider()` для фильмов и сериалов;
+- `shikimoriProvider()` и `aniListProvider()` для аниме;
+- `tvMazeProvider()` и `wikidataProvider()` как дополнительные источники идентичности;
+- `imdbDatasetProvider()` для IMDb-датасета, которым управляет ваше приложение.
 
-Backward-compatible IMDb TSV adapter полностью разбирает входные строки в память и предназначен для небольших наборов и fixtures. Для полного датасета приложение может передать экспортируемый синхронный/асинхронный контракт `ImdbDatasetStorage` с прямым ID lookup и ограниченным поиском по нормализованному title; другим пользователям пакета database dependency не добавляется.
+Данные TVmaze требуют указания источника. Сохраняйте и показывайте ссылку TVmaze, которая приходит
+в результате. Подробности есть в [лицензии API TVmaze](https://www.tvmaze.com/api#licensing).
 
-Встроенный persisted adapter может потоково собрать plain или gzip IMDb TSV в версионированный SQLite/FTS index с атомарной заменой. `buildImdbDatasetSqliteIndex()` создаёт индекс, а `openImdbDatasetSqliteStorage()` открывает его read-only для `imdbDatasetProvider({ storage })`. Этот опциональный путь лениво использует встроенный `node:sqlite` и требует Node.js 22.13 или новее; импорт пакета и небольшой in-memory adapter сохраняют базовую совместимость с Node.js 20.
+Опциональные инструменты для SQLite-индекса IMDb требуют Node.js 22.13 или новее. Для остального
+пакета достаточно Node.js 20.
 
-Ожидаемые сбои внешних источников возвращаются как типизированные `ProviderError`, а исходный HTTP status доступен через `getProviderHttpStatus`. Cinemeta при IMDb-запросе без типа возвращает `null`, только когда отсутствие подтверждено и для фильма, и для сериала; временный сбой одной ветки остаётся retryable, если другая ветка не вернула пригодные детали. AniList также отличает GraphQL rate limit и сбой сервера от ошибок валидации или некорректного ответа, поэтому Media Engine не кеширует неполные метаданные как здоровый результат.
-
-Общий `fetchJson` по умолчанию читает потоково не больше 4 МиБ перед разбором JSON и принимает положительный `maxResponseBytes` для индивидуального лимита провайдера. Объявленное или фактическое превышение отменяет body и возвращает non-retryable `PROVIDER_RESPONSE_TOO_LARGE`; некорректный JSON в пределах лимита остаётся `PROVIDER_INVALID_RESPONSE`.
-
-Низкоуровневые адаптеры могут передать `ProviderHttpScheduler` через
-`FetchJsonOptions.scheduler`, когда нужен детерминированный контроль retry- и total-timeout
-таймеров, прежде всего в тестах. Обычные provider-вызовы не задают его и используют системные
-таймеры.
-
-## Провайдеры плееров
-
-- `kinobdStreamingProvider()` — варианты плееров для фильмов, сериалов и аниме;
-- `flixHqStreamingProvider()` — международные варианты для фильмов и выбранных эпизодов сериалов;
-- `ddbbStreamingProvider()` — opt-in поиск по Kinopoisk/IMDb через независимый маршрут DDBB;
-- `aniLibertyStreamingProvider()` — opt-in точный поиск аниме по названию/году с прямыми HLS-сериями;
-- `experimentalStreamingProvider()` — данные, настроенные вашим приложением для тестов и разработки интерфейса.
+## Поиск вариантов просмотра
 
 ```ts
+import {
+  flixHqStreamingProvider,
+  kinobdStreamingProvider,
+} from "@media-engine/providers";
+
 const media = new MediaEngine({
-  streamingProviders: [
-    kinobdStreamingProvider(),
-    flixHqStreamingProvider(),
-  ],
+  streamingProviders: [kinobdStreamingProvider(), flixHqStreamingProvider()],
 });
 
 const result = await media.getAvailability({
   type: "series",
-  title: "Game of Thrones",
+  title: "Игра престолов",
   seasonNumber: 1,
   episodeNumber: 1,
 });
 ```
 
-Это ссылки на сторонние плееры, а не видео, размещённые Media Engine. Доступность зависит от внешнего источника и окружения пользователя.
-
-API репозитория включает `ddbbStreamingProvider()` после повторного reliability/diversity
-checkpoint; прямые пользователи пакета по-прежнему явно выбирают собственный список провайдеров. Он
-принимает только ID Kinopoisk или IMDb, возвращает общие embed-плееры для фильмов/сериалов/anime и не
-заявляет точное сопоставление сезона/эпизода. Diversity-first mapping сначала сохраняет по одному
-основному варианту каждого возвращённого плеера, а затем добавляет уникальные translation URL.
-Nullable отсутствующие плееры дают пустой результат; подтверждённые 404/410 и устойчивые deletion
-markers удаляются, а transient ошибки проверки сохраняются как `unknown`.
+Пакет также экспортирует `ddbbStreamingProvider()`, `aniLibertyStreamingProvider()`,
+`filmixStreamingProvider()`, `veoVeoStreamingProvider()`, `videoHubStreamingProvider()`,
+`rutubeStreamingProvider()` и
+`experimentalStreamingProvider()`.
+Подключайте их явно, если они
+подходят вашему приложению. Гостевой режим Filmix ограничен 480p и отбрасывает известные заглушки о
+блокировке и служебные видео. Собственный device token повышает предел до 720p. Для авторизации
+обязателен HTTPS `baseUrl`, если приложение явно не включило `allowInsecureHttpToken` для локальной
+проверки совместимости. Этот режим отправляет токен без TLS и не должен использоваться в публичном
+развёртывании. Ссылки на видео CDN используют HTTPS. VeoVeo использует DDBB только для получения публичного
+content ID, отбрасывает iframe-токен и возвращает прямой подписанный HTTPS HLS.
+VideoHUB ищет по ID Кинопоиска, а для сериала требует точный сезон и серию. Он возвращает
+короткоживущие прямые MP4 в нескольких качествах. Ссылки привязаны к User-Agent проигрывающего
+клиента и могут быть привязаны к внешнему IP. Передавайте точный User-Agent клиента через
+`MediaEngineOperationOptions.playbackUserAgent`; для небраузерных клиентов нужное значение также
+сохраняется в `access.headers` каждого варианта.
+Rutube выполняет ограниченный точный поиск фильма по названию и году и возвращает только
+официальный публичный embed-плеер Rutube. Прямые media-URL не извлекаются и не проксируются;
+сериалы намеренно не поддерживаются.
+
+Эти провайдеры возвращают сторонние ссылки или потоки. Media Engine не хранит видео, а внешний
+плеер может быть недоступен в конкретной стране, сети или браузере.
+
+## Поиск torrent-раздач
+
+Torrent-провайдеры всегда подключаются явно:
 
 ```ts
-const media = new MediaEngine({
-  streamingProviders: [
-    kinobdStreamingProvider(),
-    flixHqStreamingProvider(),
-    ddbbStreamingProvider(), // явное opt-in подключение
-    aniLibertyStreamingProvider(), // явное opt-in подключение
-  ],
-});
-```
-
-После того же checkpoint API репозитория включает и `aniLibertyStreamingProvider()`. AniLiberty не
-публикует для релизов MAL, AniList или Shikimori ID, поэтому адаптер требует одновременно название и
-год, принимает только одно точное нормализованное совпадение и повторно проверяет загруженный релиз
-перед возвратом потоков. Он поддерживает общую карту серий и точный `absoluteEpisodeNumber`, но не
-угадывает season/episode. Каждый безопасный first-party URL 480p/720p/1080p возвращается как прямой
-HLS, а географическая и copyright-блокировка релиза сохраняются в availability status.
-
-Live-проверка удаляет вариант плеера только после HTTP 404/410 или устойчивого маркера удаления. Rate limit, ошибка сервера, сетевой сбой или timeout проверки сохраняют найденный вариант с `availability: "unknown"`, чтобы engine показал деградацию и повторил проверку вместо кеширования временно урезанного результата.
-
-KinoBD по умолчанию ограничивает один availability lookup 24 дочерними HTTP-попытками и проверяет не больше восьми найденных плееров тремя workers. Публичная настройка также ограничена сверху (`childRequestLimit` до 64, `playerValidationLimit` до 16 и `playerValidationConcurrency` до 4). Вложенная iframe-проверка начинается, только если фиксированный deadline провайдера ещё позволяет выделить полное окно validation. Callback `onPlayerAudit` получает дополнительные `metrics`: найденные и проверенные плееры, пропуски по limit/budget, transient unknown, подтверждённые удаления и использованные дочерние запросы.
-
-Навигация по FlixHQ не может покинуть настроенный origin, в том числе через redirects. Для внешних player/subtitle проверяются все A/AAAA-адреса, отклоняются private, local, reserved, multicast и смешанные public/private назначения, каждый ограниченный redirect hop валидируется, а соединение закрепляется за проверенным адресом. Пользовательский provider `fetch` считается явно доверенной transport-инъекцией для контролируемых тестов или self-hosted окружений и должен обеспечивать эквивалентную сетевую политику.
-
-DDBB ограничивает размер JSON-ответа, количество output options и live validations, concurrency,
-размер validation body и timeout каждого плеера. Его default transport применяет ту же hardened
-политику DNS, redirects и connection pinning к endpoint DDBB и возвращённым плеерам. Пользовательский
-`fetch` остаётся явной доверенной границей для тестов/self-hosted окружений. Варианты за пределом
-ограниченного числа проверок остаются видимыми со статусом `availability: "unknown"` и никогда не
-показываются как успешно проверенные. Alloha представлен одним main option, потому что озвучку
-можно переключить внутри самого плеера; при отсутствии main iframe точкой входа становится не
-больше одного безопасного translation URL. Остальные семейства плееров сохраняют отдельные
-варианты переводов.
-
-AniLiberty ограничивает число search-кандидатов и эпизодов релиза, размер JSON, retry и общее время
-провайдера через общие engine/provider-механизмы. Default transport применяет hardened DNS,
-redirect и connection-pinning политику к API-вызовам. Прямые HLS-цели проходят общую browser-facing
-проверку URL; playback network policy остаётся ответственностью потребляющего приложения.
-
-Перед публикацией artwork, player или subtitle URL встроенные провайдеры применяют одну output-политику: разрешены только HTTP(S)-цели без credentials, исходных управляющих символов и literal local/private/reserved адресов. Валидные пути и CDN query-параметры, включая временные подписи, сохраняются. Эта browser-facing проверка не заменяет DNS-валидацию или media proxy приложения.
-
-## Источники torrent discovery
-
-`ytsTorrentProvider()` — явно подключаемый no-key источник фильмов. Он принимает точный IMDb ID или
-одно точное совпадение названия и года и возвращает нормализованные magnet-кандидаты вроде
-720p/1080p/2160p с размером, сведениями о релизе и best-effort счётчиками пиров.
-
-`jacRedTorrentProvider()` — явно подключаемый no-key русскоязычный/мультиязычный источник для
-точного поиска фильмов, сериалов и аниме по названию и году. Он умеет фильтровать указанный сезон,
-но намеренно не отвечает на запрос конкретной обычной или абсолютной серии. Название, год,
-категория, сезон, info hash, source URL, сведения о релизе и счётчики пиров ограничиваются и
-перепроверяются. Каждый результат также сохраняет ограниченный tracker ID JacRed в
-`catalogSource`; известные значения получают подписи BitRu, RuTracker, RuTor, Kinozal, NNM-Club и
-Knaben без ложной гарантии языка аудиодорожки. `baseUrl` и `searchPath` настраиваются, потому что фактический first-party маршрут
-сейчас отличается от опубликованного.
-
-`bitsearchTorrentProvider()` — явно подключаемый no-key источник с широким международным каталогом.
-Он требует название и год, закрепляет категории movie/TV/anime и перед возвратом кандидата заново
-проверяет точное название релиза, явно указанный год, тип медиа, запрошенный сезон и обычный или
-абсолютный номер эпизода. Провайдер читает только ограниченный search-ответ, запоминает исчерпание
-анонимной квоты из `X-RateLimit-*` и создаёт один канонический magnet на проверенный info hash.
-Публичная анонимная квота сейчас составляет 200 запросов в сутки на IP, поэтому приложению следует
-оставлять engine cache включённым и не выполнять speculative-вызовы.
-
-`magnetzTorrentProvider()` — явно подключаемый no-key международный meta-search источник. Он делает
-один ограниченный запрос первой страницы, затем локально перепроверяет точное название, год, сезон
-и маркеры обычного или абсолютного эпизода. Провайдер не запускает отдельные detail-запросы для
-каждого результата, создаёт один канонический magnet на проверенный info hash, сохраняет фактические
-peer-счётчики и attribution и выдерживает секунду между началами запросов: live-сервис возвращал
-короткие burst-429 даже при ненулевом остатке в rate-limit header.
+import {
+  bitsearchTorrentProvider,
+  jacRedTorrentProvider,
+  magnetzTorrentProvider,
+  ytsTorrentProvider,
+} from "@media-engine/providers";
 
-```ts
 const media = new MediaEngine({
   torrentProviders: [
     ytsTorrentProvider(),
@@ -175,29 +114,23 @@ const media = new MediaEngine({
     bitsearchTorrentProvider(),
     magnetzTorrentProvider(),
   ],
-  providerTimeouts: {
-    "yts-torrent": 15_000,
-    "jacred-torrent": 20_000,
-    "bitsearch-torrent": 15_000,
-    "magnetz-torrent": 15_000,
-  },
 });
 
-const torrents = await media.discoverTorrents({
+const result = await media.discoverTorrents({
   type: "movie",
-  title: "Inception",
+  title: "Начало",
   year: 2010,
   ids: { imdb: "tt1375666" },
 });
 ```
 
-Провайдер не загружает torrent metadata, не обращается к trackers, не подключается к swarm и не
-воспроизводит видео. После общего multi-source checkpoint torrent-провайдеры остались выключенными
-в API defaults: у Bitsearch небольшая суточная анонимная квота, Magnetz чувствителен к burst-нагрузке,
-а у JacRed сохраняется редкий длинный timeout tail. Приложение явно выбирает нужное подмножество и
-может контролировать его командой `pnpm smoke:torrents`, сохраняя собственный request budget.
+Поиск только возвращает список кандидатов и данные для дальнейшей передачи. Он не загружает
+torrent metadata, не обращается к trackers, не подключается к раздаче и не воспроизводит файл.
 
-Настройки, ограничения и правила безопасности кратко описаны в [документации провайдеров](https://github.com/Yaneart/media-engine/blob/main/docs/providers.md).
+Публичные источники могут меняться, ограничивать запросы или временно не работать. Оставляйте кэш
+движка включённым и будьте готовы к частичным результатам. Настройки и границы безопасности каждого
+источника описаны в
+[документации провайдеров](https://github.com/Yaneart/media-engine/blob/main/docs/providers.md).
 
 ## Лицензия