@vkontakte/videoplayer-core 2.0.176-beta.0 → 2.0.176-dev.477f4c39b.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vkontakte/videoplayer-core",
-  "version": "2.0.176-beta.0",
+  "version": "2.0.176-dev.477f4c39b.0",
   "author": "vk.ru",
   "description": "Videoplayer core library based on the vk.ru platform",
   "homepage": "https://vk.ru",
@@ -42,6 +42,6 @@
     "**/*.d.ts"
   ],
   "dependencies": {
-    "@vkontakte/videoplayer-shared": "1.0.105-beta.0"
+    "@vkontakte/videoplayer-shared": "1.0.105-dev.477f4c39b.0"
   }
 }

package/types/index.d.ts

@@ -3,7 +3,12 @@ import type { IMpegSource, IDashSource, IHLSSource, IDashURLSource, IHLSLiveSour
 import type { VideoCodec } from "./player/types";
 import { VideoFormat, Surface, PredefinedQualityLimits, VideoCodecName } from "./player/types";
 import Player from "./player/Player";
-import type { IPlayer, IPlayerInfo, IPlayerEvents, IConfig, ISources, ICueSettings, IExternalTextTrack, ITextTrack, PlaybackRate, IVideoStream, IAudioStream } from "./player/types";
+import warmUpSources from "./utils/warmUpSources";
+import type { IWarmUp, IWarmUpTargets } from "./utils/warmUpSources";
+import prepareSources from "./utils/prepareSources";
+import type { IPreparedSources, IPrepareSourcesOptions } from "./utils/prepareSources";
+import type { IPreparedMedia } from "./utils/prepareMedia";
+import type { IPlayer, IPlayerInfo, IPlayerEvents, IConfig, ISources, ICueSettings, IExternalTextTrack, ITextTrack, PlaybackRate, IVideoStream, IAudioStream, StartEnd, HttpConnectionMetrics, HttpDownloadMetrics } from "./player/types";
 import { PlaybackState, ChromecastState, HttpConnectionType } from "./player/types";
 import type { IOptionalTuningConfig } from "./utils/tuningConfig";
 export { clientChecker, isMobile } from "./utils/ClientChecker";
@@ -15,5 +20,6 @@ import { Subscription, Observable, Subject, ValueSubject, VideoQuality } from "@
 * @deprecated
 */
 declare const SDK_VERSION: string;
-export type { IPlayer, IPlayerInfo, IPlayerEvents, IConfig, IOptionalTuningConfig, ILogEntry, ISources, IExternalTextTrack, ITextTrack, ISubscription, IUnsubscriber, IObservable, IEmitter, IValueObservable, IValue, IOperator, IListener, IMpegSource, IDashSource, IDashURLSource, IHLSSource, IHLSLiveSource, URLSource, RawSource, URLSourceWithSeek, ExactVideoQuality, IRange, ISeekRequest, ICueSettings, PlaybackRate, IVideoStream, IAudioStream };
-export { Player, PlaybackState, ChromecastState, HttpConnectionType, Surface, Subscription, VideoFormat, VideoQuality, Observable, Subject, ValueSubject, VERSION, SDK_VERSION, PredefinedQualityLimits, VideoCodec, VideoCodecName };
+export type { IPlayer, IPlayerInfo, IPlayerEvents, IConfig, IOptionalTuningConfig, ILogEntry, ISources, IExternalTextTrack, ITextTrack, ISubscription, IUnsubscriber, IObservable, IEmitter, IValueObservable, IValue, IOperator, IListener, IMpegSource, IDashSource, IDashURLSource, IHLSSource, IHLSLiveSource, URLSource, RawSource, URLSourceWithSeek, ExactVideoQuality, IRange, ISeekRequest, ICueSettings, PlaybackRate, IVideoStream, IAudioStream, StartEnd, HttpConnectionMetrics, HttpDownloadMetrics };
+export type { IWarmUp, IWarmUpTargets, IPreparedSources, IPrepareSourcesOptions, IPreparedMedia };
+export { Player, warmUpSources, prepareSources, PlaybackState, ChromecastState, HttpConnectionType, Surface, Subscription, VideoFormat, VideoQuality, Observable, Subject, ValueSubject, VERSION, SDK_VERSION, PredefinedQualityLimits, VideoCodec, VideoCodecName };

package/types/player/types.d.ts

@@ -1,3 +1,4 @@
+import type { IPreparedSources } from "../utils/prepareSources";
 import type { DebugData, IError, ILogEntry, IObservable, IRectangle, IValueObservable, IValueSubject, Kbps, Milliseconds, QualityLimits, Seconds, Subject, ValueSubject, VideoQuality } from "@vkontakte/videoplayer-shared";
 import type { dump } from "../utils/playbackTelemetry";
 export interface StartEnd<Unit extends number> {
@@ -558,6 +559,11 @@ export interface IConfig {
 	* Нужно ли recoverableError обрабатывать как ошибку провайдера или будет снаружи обрабатываться.
 	*/
 	handleNetworkRecoverableErrorAsProviderError?: boolean;
+	/**
+	* UVP-11502: манифест, запрошенный потребителем заранее — см. prepareSources.
+	* Не передан — плеер запрашивает манифест сам, как и раньше.
+	*/
+	preparedSources?: IPreparedSources;
 }
 export interface ISources {
 	[VideoFormat.MPEG]?: IMpegSource;

package/types/providers/DashProvider/baseDashProvider.d.ts

@@ -1,3 +1,4 @@
+import type { IPreparedSources } from "../../utils/prepareSources";
 import type { IAudioTrack, IDashURLSource, IHLSSource, IInternalTextTrack, IVideoTrack, VideoCodec } from "../../player/types";
 import type { IProviderSubscriptionInfo } from "./lib/types";
 import { ProviderState } from "./lib/types";
@@ -13,6 +14,7 @@ import StallsManager from "../utils/StallsManager";
 import { AbrManager } from "../utils/Abr/abrManager";
 import { ElementSizeManager } from "../utils/HTMLVideoElement/ElementSizeManager";
 type IParams = IProviderParams<IDashURLSource> & {
+	preparedSources?: IPreparedSources;
 	sourceHls?: IHLSSource;
 	forceVideoCodec?: VideoCodec;
 	isOnDemand?: boolean;

package/types/providers/DashProvider/lib/fetcher.d.ts

@@ -1,4 +1,5 @@
 import type { HttpConnectionType, HttpConnectionMetrics, HttpDownloadMetrics } from "../../../player/types";
+import type { IPreparedSources } from "../../../utils/prepareSources";
 import type ThroughputEstimator from "../../../utils/ThroughputEstimator";
 import type { Byte, IValueSubject, ISubject, Milliseconds, IRange, ITracer, IError } from "@vkontakte/videoplayer-shared";
 import { abortable } from "@vkontakte/videoplayer-shared";
@@ -30,6 +31,8 @@ export interface IParams {
 	cacheHitTtfbMaxMs?: Milliseconds;
 	preloadFirstSegment?: boolean;
 	maxQualityForFirstSegmentPreload?: ExactVideoQuality;
+	preparedSources?: IPreparedSources;
+	preparedSourcesTimeout?: Milliseconds;
 }
 export type Priority = "high" | "low" | "auto";
 export interface FetchParamsWithUrl extends FetchParams {
@@ -78,13 +81,17 @@ export declare class Fetcher {
 	private measureNonSegmentRequests;
 	private measureFastSamples;
 	private cacheHitTtfbMaxMs;
+	private preparedSources?;
+	private preparedMedia?;
+	private preparedMediaResolved?;
+	private preparedSourcesTimeout;
 	private preloadFirstSegment;
 	private maxQualityForFirstSegmentPreload;
 	private startupPhase;
 	private performanceObserver;
 	private pendingConnectionMetrics;
 	private handleExtendedNetworkErrorsSet;
-	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload }: IParams);
+	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload, preparedSources, preparedSourcesTimeout }: IParams);
 	private onHeadersReceived;
 	private setupPerformanceObserver;
 	private processPerformanceResourceTiming;
@@ -99,6 +106,20 @@ export declare class Fetcher {
 	private fetchByteRangeRepresentation;
 	private fetchTemplateRepresentation;
 	private isLikelyCacheHitByTtfb;
+	/**
+	* Ответ на манифест, запрошенный до создания плеера. Отдаётся один раз и только на тот же URL:
+	* разойдётся адрес — значит подготовка выбрала другой формат, и запрос идёт обычным путём.
+	*/
+	private takePrepared;
+	/**
+	* Байты, скачанные до создания плеера. Отдаются по тому же URL и только на вложенный диапазон:
+	* подготовка тянет файл с нуля, поэтому смещения запроса совпадают с индексами в её буфере.
+	*/
+	private takePreparedMedia;
+	/**
+	* Плеер выбрал другую репрезентацию: держать чужую загрузку дальше значит отнимать у него полосу.
+	*/
+	private releasePreparedMedia;
 	private doFetch;
 	private unsubscribeAbortSubscription;
 }

package/types/providers/DashProvider/lib/player.d.ts

@@ -1,3 +1,4 @@
+import type { IPreparedSources } from "../../../utils/prepareSources";
 import type { IHLSSource, HttpConnectionType, HttpConnectionMetrics, HttpDownloadMetrics, VideoCodec } from "../../../player/types";
 import { LiveStreamStatus } from "./types";
 import type { CommonInit, Manifest, Representation, Segment, TextRepresentation } from "../../utils/parsers/types";
@@ -18,6 +19,8 @@ export interface Params {
 	throughputEstimator: ThroughputEstimator;
 	tuning: ITuningConfig;
 	compatibilityMode?: boolean;
+	preparedSources?: IPreparedSources;
+	preparedSourcesTimeout?: Milliseconds;
 	forceVideoCodec?: VideoCodec;
 	tracer: ITracer;
 	isOnDemand: boolean;

package/types/providers/DashProviderVirtual/baseDashProvider.d.ts

@@ -1,3 +1,4 @@
+import type { IPreparedSources } from "../../utils/prepareSources";
 import type { IAudioTrack, IDashURLSource, IHLSSource, IInternalTextTrack, IVideoTrack, VideoCodec } from "../../player/types";
 import type { IProviderSubscriptionInfo } from "./lib/types";
 import { ProviderState } from "./lib/types";
@@ -13,6 +14,7 @@ import { ElementSizeManager } from "../utils/HTMLVideoElement/ElementSizeManager
 import type { BasePlayer } from "./lib/player/basePlayer";
 import { AbrManager } from "../utils/Abr/abrManager";
 type IParams = IProviderParams<IDashURLSource> & {
+	preparedSources?: IPreparedSources;
 	sourceHls?: IHLSSource;
 	forceVideoCodec?: VideoCodec;
 	isOnDemand?: boolean;

package/types/providers/DashProviderVirtual/lib/fetcher.d.ts

@@ -1,3 +1,4 @@
+import type { IPreparedSources } from "../../../utils/prepareSources";
 import type { HttpConnectionType, HttpConnectionMetrics, HttpDownloadMetrics } from "../../../player/types";
 import type ThroughputEstimator from "../../../utils/ThroughputEstimator";
 import type { Byte, IError, IRange, ISubject, ITracer, IValueSubject, Milliseconds } from "@vkontakte/videoplayer-shared";
@@ -21,6 +22,8 @@ export interface IParams {
 	throughputEstimator?: ThroughputEstimator;
 	requestQuic: boolean;
 	compatibilityMode?: boolean;
+	preparedSources?: IPreparedSources;
+	preparedSourcesTimeout?: Milliseconds;
 	tracer: ITracer;
 	useEnableSubtitlesParam?: boolean;
 	handleExtendedNetworkErrorsSet?: boolean;
@@ -77,13 +80,17 @@ export declare class Fetcher {
 	private measureNonSegmentRequests;
 	private measureFastSamples;
 	private cacheHitTtfbMaxMs;
+	private preparedSources?;
+	private preparedMedia?;
+	private preparedMediaResolved?;
+	private preparedSourcesTimeout;
 	private preloadFirstSegment;
 	private maxQualityForFirstSegmentPreload;
 	private startupPhase;
 	private performanceObserver;
 	private pendingConnectionMetrics;
 	private handleExtendedNetworkErrorsSet;
-	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preloadFirstSegment, maxQualityForFirstSegmentPreload }: IParams);
+	constructor({ throughputEstimator, requestQuic, tracer, compatibilityMode, useEnableSubtitlesParam, handleExtendedNetworkErrorsSet, useUrlCacheMechanism, measureNonSegmentRequests, measureFastSamples, cacheHitTtfbMaxMs, preparedSources, preparedSourcesTimeout, preloadFirstSegment, maxQualityForFirstSegmentPreload }: IParams);
 	private onHeadersReceived;
 	private setupPerformanceObserver;
 	private processResourceTiming;
@@ -98,5 +105,19 @@ export declare class Fetcher {
 	private fetchByteRangeRepresentation;
 	private fetchTemplateRepresentation;
 	private isLikelyCacheHitByTtfb;
+	/**
+	* Ответ на манифест, запрошенный до создания плеера. Отдаётся один раз и только на тот же URL:
+	* разойдётся адрес — значит подготовка выбрала другой формат, и запрос идёт обычным путём.
+	*/
+	private takePrepared;
+	/**
+	* Байты, скачанные до создания плеера. Отдаются по тому же URL и только на вложенный диапазон:
+	* подготовка тянет файл с нуля, поэтому смещения запроса совпадают с индексами в её буфере.
+	*/
+	private takePreparedMedia;
+	/**
+	* Плеер выбрал другую репрезентацию: держать чужую загрузку дальше значит отнимать у него полосу.
+	*/
+	private releasePreparedMedia;
 	private doFetch;
 }

package/types/providers/DashProviderVirtual/lib/player/types.d.ts

@@ -1,3 +1,5 @@
+import type { Milliseconds } from "@vkontakte/videoplayer-shared";
+import type { IPreparedSources } from "../../../../utils/prepareSources";
 import type ThroughputEstimator from "../../../../utils/ThroughputEstimator";
 import type { ITuningConfig } from "../../../../utils/tuningConfig";
 import type { VideoCodec } from "../../../../player/types";
@@ -12,6 +14,8 @@ export interface Params {
 	throughputEstimator: ThroughputEstimator;
 	tuning: ITuningConfig;
 	compatibilityMode?: boolean;
+	preparedSources?: IPreparedSources;
+	preparedSourcesTimeout?: Milliseconds;
 	forceVideoCodec?: VideoCodec;
 	tracer: ITracer;
 	isOnDemand?: boolean;

package/types/providers/ProviderContainer/index.d.ts

@@ -5,6 +5,7 @@ import type { IError, ISubject, IValueSubject, IRectangle } from "@vkontakte/vid
 import { ValueSubject } from "@vkontakte/videoplayer-shared";
 import type { IDesiredState, IProviderDependencies, IProviderOutput } from "../types";
 import type { IProviderContainer, IProviderEntry } from "./types";
+import type { IPreparedSources } from "../../utils/prepareSources";
 interface IParams extends IProviderDependencies {
 	container: HTMLElement;
 	sources: ISources;
@@ -16,6 +17,7 @@ interface IParams extends IProviderDependencies {
 	panelSize?: IRectangle;
 	skipVideoElVolumeSync$: ValueSubject<boolean>;
 	handleNetworkRecoverableErrorAsProviderError?: boolean;
+	preparedSources?: IPreparedSources;
 }
 export default class ProviderContainer implements IProviderContainer {
 	current$: IValueSubject<IProviderEntry>;

package/types/providers/ProviderContainer/utils/selectFormats.d.ts

@@ -0,0 +1,10 @@
+import type { ISources, VideoFormat } from "../../../player/types";
+import type { ITuningConfig } from "../../../utils/tuningConfig";
+/**
+* Порядок форматов для экрана: платформенный приоритет, пересечённый с тем, что реально отдал API,
+* с учётом принудительного формата и списка нежелательных.
+*
+* Вынесено из ProviderContainer, потому что тот же порядок нужен подготовке источников снаружи
+* плеера: она обязана выбрать тот же формат, иначе прогретый запрос уйдёт не за тем манифестом.
+*/
+export declare const selectScreenFormats: (sources: ISources, tuning: ITuningConfig) => VideoFormat[];

package/types/providers/utils/initialByteRange.d.ts

@@ -0,0 +1,22 @@
+import type { Byte, IRange } from "@vkontakte/videoplayer-shared";
+import type { ByteRangeSegmentReference } from "./parsers/types";
+export interface IInitialByteRange {
+	range: IRange<Byte>;
+	/** Index попал в тот же запрос — значит второй round-trip за ним не нужен. */
+	indexLoadedWithInit: boolean;
+}
+interface IOptions {
+	/** Тянуть ли следом первый сегмент (UVP-10107): длина известна из манифеста. */
+	withFirstSegment: boolean;
+	/** Нижняя граница хвоста: подготовка снаружи добирает диапазон до своего потолка. */
+	minBytes?: Byte;
+}
+/**
+* Диапазон первого запроса к медиа: init, при удачной раскладке index следом за ним, и — если
+* просили — первый сегмент.
+*
+* Вынесено из фетчеров, потому что тот же диапазон считает подготовка источников снаружи плеера:
+* разойдись эти расчёты на байт, и подготовленный ответ не подойдёт под запрос плеера.
+*/
+export declare const initialByteRange: ({ initRange, indexRange, firstSegmentLength }: Pick<ByteRangeSegmentReference, "initRange" | "indexRange" | "firstSegmentLength">, { withFirstSegment, minBytes }: IOptions) => IInitialByteRange;
+export {};

package/types/utils/ThroughputEstimator.d.ts

@@ -23,8 +23,13 @@ declare class ThroughputEstimator {
 	addRawRtt(time: Milliseconds): void;
 	private sanityCheck;
 	get throughputVariance$(): IValueSubject<number>;
-	private static loadStored;
+	static loadStored(key: string, legacyKey: string, tuning: ITuningConfig["throughputEstimator"]): number | undefined;
 	private static writeStored;
 	private static validateStored;
 }
+/**
+* Стартовая оценка сети без создания оценщика: подготовка источников выбирает качество до того,
+* как появится плеер, и обязана взять ровно то значение, с которого он стартует.
+*/
+export declare const initialThroughputEstimation: (tuning: ITuningConfig["throughputEstimator"]) => Kbps;
 export default ThroughputEstimator;

package/types/utils/prepareMedia.d.ts

@@ -0,0 +1,40 @@
+import type { Byte, IRange, IRectangle, Milliseconds } from "@vkontakte/videoplayer-shared";
+import type { ExactVideoQuality } from "@vkontakte/videoplayer-shared";
+import type { ITuningConfig } from "./tuningConfig";
+/** Замер подготовительной загрузки: плеер стартует не с дефолтной гипотезы, а со свежего сэмпла. */
+export interface IPreparedMediaMetrics {
+	bytes: Byte;
+	duration: Milliseconds;
+	rtt: Milliseconds;
+}
+export interface IPreparedMedia {
+	/** URL репрезентации без диапазона: плеер запросит его же, диапазон он приложит свой. */
+	readonly url: string;
+	/** Срез уже доехавших байт. `undefined` — диапазон не наш, не дождались или подготовку порвали. */
+	take: (range: IRange<Byte>, timeout: Milliseconds) => Promise<ArrayBuffer | undefined>;
+	/** Отдаётся один раз: второй вызов вернёт `undefined`, чтобы сэмпл не учли дважды. */
+	takeMetrics: () => IPreparedMediaMetrics | undefined;
+	/** Рвёт поток и освобождает буфер. Идемпотентно. */
+	destroy: () => void;
+}
+export interface IPrepareMediaOptions {
+	manifestText: string;
+	manifestUrl: string;
+	tuning: ITuningConfig;
+	/** В режиме совместимости диапазон уходит заголовком, а не параметром URL. */
+	compatibilityMode?: boolean;
+	/** Куда встанет плеер. Нет подсказки — качество ограничивается потолком предзагрузки. */
+	container?: IRectangle;
+	/** Качество, выбранное пользователем: тогда гадать не нужно вовсе. */
+	quality?: ExactVideoQuality;
+}
+/**
+* Догружает начало медиа выбранной репрезентации: init, index и столько сегментов, сколько влезает
+* в потолок предзагрузки, — одним байтовым диапазоном от нуля файла.
+*
+* Репрезентация выбирается тем же `selectTrackByRules`, что и в плеере, на той же сохранённой
+* оценке сети; диапазон считает та же `initialByteRange`, что и фетчер. Разойдись любое из двух —
+* плеер запросит не тот адрес, и подготовка пропадёт впустую.
+*/
+declare const _default: (options: IPrepareMediaOptions, signal: AbortSignal) => Promise<IPreparedMedia | undefined>;
+export default _default;

package/types/utils/prepareSources.d.ts

@@ -0,0 +1,55 @@
+import type { ISources } from "../player/types";
+import { VideoFormat } from "../player/types";
+import type { IPreparedMedia } from "./prepareMedia";
+import type { IOptionalTuningConfig } from "./tuningConfig";
+import type { ExactVideoQuality, IRectangle } from "@vkontakte/videoplayer-shared";
+export interface IPreparedSources {
+	/** URL, ради которого всё затевалось: плеер возьмёт ответ, только если запросит ровно его. */
+	readonly url: string;
+	readonly format: VideoFormat;
+	/** Ответ на запрос манифеста. Тело не вычитано — его прочитает плеер. */
+	readonly response: Promise<Response | undefined>;
+	/**
+	* Начало медиа выбранной репрезентации. Появляется только под `usePreparedFirstSegments` и только
+	* после разбора манифеста, поэтому это второй промис, а не поле готового объекта.
+	*/
+	readonly media?: Promise<IPreparedMedia | undefined>;
+	/**
+	* Владение перешло плееру: снимает самоотмену по TTL. Дальше хэндл живёт столько, сколько живёт
+	* фетчер, и умирает вместе с ним.
+	*/
+	take: () => void;
+	/** Рвёт обе стадии и освобождает буфер. Идемпотентно. */
+	destroy: () => void;
+}
+export interface IPrepareSourcesOptions {
+	/** Конфиг плеера потребителя: недостающее добирается дефолтами, как это сделает сам плеер. */
+	tuning?: IOptionalTuningConfig;
+	/**
+	* Хэндл прошлой подготовки того же видео. Потребитель зовёт подготовку и до загрузки конфига
+	* плеера, и после: сошёлся URL — отдаём прежний запрос, разошёлся — прежний отменяем и идём
+	* заново. Иначе конфиг, меняющий URL или формат, тихо обесценил бы подготовку.
+	*/
+	previous?: IPreparedSources;
+	/**
+	* Размер места, куда встанет плеер. Без него выбор качества опирается на одну оценку сети,
+	* поэтому ограничивается потолком предзагрузки.
+	*/
+	container?: IRectangle;
+	/** Качество, выбранное пользователем ранее: с ним подготовка не гадает вовсе. */
+	quality?: ExactVideoQuality;
+}
+/**
+* Запрашивает манифест до создания плеера — как только потребителю стали известны источники.
+*
+* Смысл в запасе: между ответом API со ссылками и первым запросом плеера проходят сотни
+* миллисекунд, и в них укладывается DNS, TCP, TLS и сама загрузка манифеста. Выбор формата
+* и достройка URL повторяют логику плеера, поэтому подготовленный ответ подходит ему как есть;
+* разойдутся — плеер сходит за манифестом сам.
+*
+* Под `usePreparedFirstSegments` следом догружается начало медиа. У этой стадии, в отличие от
+* манифеста, висит открытый поток и растущий буфер, поэтому у хэндла есть и самоотмена по TTL:
+* потребитель обязан звать `destroy` на всех выходах, но выход бывает и молчаливым.
+*/
+declare const _default: (sources: ISources, options?: IPrepareSourcesOptions) => IPreparedSources | undefined;
+export default _default;

package/types/utils/tuningConfig.d.ts

@@ -475,6 +475,43 @@ export type ITuningConfig = {
 	*/
 	useUrlCacheMechanism?: boolean;
 	/**
+	* Прогревать ли соединение к хостам раздачи. **Сам SDK этот флаг не читает** — прогрев живёт
+	* в `warmUpSources`, а зовёт её потребитель: внутри SDK запаса времени до первого запроса нет.
+	* Флаг лежит здесь, чтобы раскаткой управлял тот же ключ конфига плеера, что и остальными
+	* экспериментами, а не отдельная ручка на каждом потребителе.
+	*/
+	usePreconnectSources?: boolean;
+	/**
+	* Запрашивать ли манифест до создания плеера. **Сам SDK этот флаг не читает** — подготовку
+	* зовёт потребитель через `prepareSources`, потому что запас времени есть только у него.
+	* Флаг лежит здесь, чтобы раскаткой управлял ключ конфига плеера, а не ручка на потребителе.
+	*/
+	usePreparedSources?: boolean;
+	/**
+	* Сколько ждать манифест, запрошенный потребителем заранее (`prepareSources`), прежде чем
+	* идти за ним самому. Ноль ожидания не отменяет подготовку — он делает её бесполезной,
+	* поэтому предел нужен только как страховка от зависшего запроса снаружи.
+	*/
+	preparedSourcesTimeout: Milliseconds;
+	/**
+	* Догружать ли вслед за манифестом начало медиа выбранной репрезентации — init, index и первые
+	* сегменты одним байтовым диапазоном. Качество выбирается тем же `selectTrackByRules`, что и в
+	* плеере, на той же сохранённой оценке сети. Читает флаг не SDK, а потребитель: подготовку зовёт
+	* он, и только у него есть запас времени до создания плеера.
+	*/
+	usePreparedFirstSegments?: boolean;
+	/**
+	* Потолок предзагрузки медиа в байтах. Ограничивает и трафик несостоявшегося просмотра, и память:
+	* скачанное держится в буфере, пока его не заберёт плеер.
+	*/
+	preparedFirstSegmentsMaxBytes: Byte;
+	/**
+	* Сколько подготовка живёт, если её никто не забрал. Потребитель обязан звать `destroy` на всех
+	* выходах, но выход бывает и молчаливым — вкладку закрыли, плеер так и не создали. Без предела
+	* открытый поток и накопленный буфер пережили бы сам просмотр.
+	*/
+	preparedSourcesTtl: Milliseconds;
+	/**
 	* Очищаем кэш урлов при падение провайдера.
 	*/
 	dropUrlCacheWhenProviderCrashed?: boolean;

package/types/utils/warmUpSources.d.ts

@@ -0,0 +1,21 @@
+import type { ISources } from "../player/types";
+export interface IWarmUpTargets {
+	preconnect: string[];
+	dnsPrefetch: string[];
+}
+export interface IWarmUp {
+	applied: IWarmUpTargets;
+	destroy: () => void;
+}
+interface IOptions {
+	failoverHosts?: string[];
+}
+/**
+* Прогрев соединения к хостам раздачи по готовым `sources` — до того, как создан плеер.
+*
+* Экономия равна запасу времени до первого запроса, поэтому звать имеет смысл там, где `sources`
+* появились сильно раньше плеера: сразу после ответа API у потребителя. Сам SDK прогрев не вызывает,
+* а флаг `tuning.usePreconnectSources` нужен потребителю, чтобы раскаткой управлял конфиг плеера.
+*/
+declare const _default: (sources: ISources, { failoverHosts }?: IOptions) => IWarmUp;
+export default _default;