@hallelx/tytube 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,488 @@
+interface RawCaptionTrack {
+    baseUrl: string;
+    name?: {
+        simpleText?: string;
+        runs?: Array<{
+            text: string;
+        }>;
+    };
+    vssId?: string;
+    languageCode?: string;
+}
+declare class Caption {
+    readonly url: string;
+    readonly name: string;
+    readonly code: string;
+    constructor(track: RawCaptionTrack);
+    xmlCaptions(): Promise<string>;
+    jsonCaptions(): Promise<unknown>;
+    generateSrtCaptions(): Promise<string>;
+    static floatToSrtTimeFormat(d: number): string;
+    static xmlCaptionToSrt(xml: string): string;
+    /**
+     * Write the caption track to disk as SRT or XML.
+     * Returns the absolute path of the written file.
+     */
+    download(title: string, opts?: {
+        srt?: boolean;
+        outputPath?: string;
+        filenamePrefix?: string;
+    }): Promise<string>;
+    toString(): string;
+}
+
+declare class PytubeError extends Error {
+    constructor(message?: string);
+}
+declare class MaxRetriesExceeded extends PytubeError {
+    constructor(message?: string);
+}
+declare class HTMLParseError extends PytubeError {
+    constructor(message?: string);
+}
+declare class ExtractError extends PytubeError {
+    constructor(message?: string);
+}
+declare class RegexMatchError extends ExtractError {
+    readonly caller: string;
+    readonly pattern: string | RegExp;
+    constructor(caller: string, pattern: string | RegExp);
+}
+declare class VideoUnavailable extends PytubeError {
+    readonly videoId: string;
+    constructor(videoId: string, message?: string);
+}
+declare class AgeRestrictedError extends VideoUnavailable {
+    constructor(videoId: string);
+}
+declare class LiveStreamError extends VideoUnavailable {
+    constructor(videoId: string);
+}
+declare class VideoPrivate extends VideoUnavailable {
+    constructor(videoId: string);
+}
+declare class RecordingUnavailable extends VideoUnavailable {
+    constructor(videoId: string);
+}
+declare class MembersOnly extends VideoUnavailable {
+    constructor(videoId: string);
+}
+declare class VideoRegionBlocked extends VideoUnavailable {
+    constructor(videoId: string);
+}
+
+interface MetadataRow {
+    title?: {
+        simpleText?: string;
+    };
+    contents?: Array<{
+        simpleText?: string;
+        runs?: Array<{
+            text: string;
+        }>;
+    }>;
+    hasDividerLine?: boolean;
+}
+declare class YouTubeMetadata implements Iterable<Record<string, string>> {
+    private readonly raw;
+    private readonly groups;
+    constructor(rawRows: MetadataRow[]);
+    get rawMetadata(): MetadataRow[];
+    get metadata(): Record<string, string>[];
+    at(index: number): Record<string, string> | undefined;
+    [Symbol.iterator](): Iterator<Record<string, string>>;
+    toJSON(): Record<string, string>[];
+    toString(): string;
+}
+
+interface StreamFormat {
+    itag: number;
+    url?: string;
+    signatureCipher?: string;
+    cipher?: string;
+    s?: string;
+    type?: string;
+    is_otf?: boolean;
+    mimeType?: string;
+    bitrate?: number;
+    contentLength?: string;
+    width?: number;
+    height?: number;
+    fps?: number;
+    qualityLabel?: string;
+    audioQuality?: string;
+    averageBitrate?: number;
+    approxDurationMs?: string;
+    [key: string]: unknown;
+}
+
+interface SharedState {
+    title: string | null;
+    duration: number | null;
+    onProgress?: (stream: Stream, chunk: Uint8Array, bytesRemaining: number) => void;
+    onComplete?: (stream: Stream, filePath: string | null) => void;
+}
+interface DownloadOptions {
+    outputPath?: string;
+    filename?: string;
+    filenamePrefix?: string;
+    skipExisting?: boolean;
+    timeoutMs?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+}
+declare class Stream {
+    readonly itag: number;
+    url: string;
+    readonly mimeType: string;
+    readonly codecs: string[];
+    readonly type: string;
+    readonly subtype: string;
+    readonly videoCodec: string | null;
+    readonly audioCodec: string | null;
+    readonly isOtf: boolean;
+    readonly bitrate: number | null;
+    readonly fps: number | null;
+    readonly resolution: string | null;
+    readonly abr: string | null;
+    readonly isDash: boolean;
+    readonly is3d: boolean;
+    readonly isHdr: boolean;
+    readonly isLive: boolean;
+    private cachedFilesize;
+    private readonly state;
+    constructor(raw: StreamFormat, state: SharedState);
+    get isAdaptive(): boolean;
+    get isProgressive(): boolean;
+    get includesAudioTrack(): boolean;
+    get includesVideoTrack(): boolean;
+    private parseCodecs;
+    get title(): string;
+    filesize(): Promise<number>;
+    filesizeApprox(): Promise<number>;
+    get expiration(): Date | null;
+    get defaultFilename(): string;
+    /** Compute the absolute output path the download will be written to. */
+    getFilePath(opts?: DownloadOptions): Promise<string>;
+    existsAtPath(filePath: string): Promise<boolean>;
+    /**
+     * Download the stream to the local filesystem and return the absolute path.
+     * Throws if no filesystem is available (e.g., browser); use streamChunks() instead.
+     */
+    download(opts?: DownloadOptions): Promise<string>;
+    /**
+     * Stream the media as raw chunks. Browser-friendly alternative to download().
+     * Caller is responsible for collecting the chunks (write to a Blob, sink, etc.).
+     */
+    streamChunks(opts?: DownloadOptions): AsyncGenerator<Uint8Array>;
+    private fireOnProgress;
+    private fireOnComplete;
+    toString(): string;
+}
+
+type StreamPredicate = (s: Stream) => boolean;
+interface FilterCriteria {
+    fps?: number;
+    res?: string | string[];
+    resolution?: string | string[];
+    mimeType?: string;
+    type?: string;
+    subtype?: string;
+    fileExtension?: string;
+    abr?: string;
+    bitrate?: string;
+    videoCodec?: string;
+    audioCodec?: string;
+    onlyAudio?: boolean;
+    onlyVideo?: boolean;
+    progressive?: boolean;
+    adaptive?: boolean;
+    isDash?: boolean;
+    customFilters?: StreamPredicate[];
+}
+declare class StreamQuery implements Iterable<Stream> {
+    readonly fmtStreams: Stream[];
+    private readonly itagIndex;
+    constructor(fmtStreams: Stream[]);
+    filter(criteria?: FilterCriteria): StreamQuery;
+    private applyFilters;
+    /**
+     * Sort by an attribute. Filters out streams that don't have it. For string
+     * attributes (e.g., "720p"), sorts by the embedded integer.
+     */
+    orderBy(attribute: keyof Stream): StreamQuery;
+    desc(): StreamQuery;
+    asc(): StreamQuery;
+    getByItag(itag: number): Stream | undefined;
+    getByResolution(resolution: string): Stream | undefined;
+    getLowestResolution(): Stream | undefined;
+    getHighestResolution(): Stream | undefined;
+    getAudioOnly(subtype?: string): Stream | undefined;
+    otf(isOtf?: boolean): StreamQuery;
+    first(): Stream | undefined;
+    last(): Stream | undefined;
+    get length(): number;
+    at(index: number): Stream | undefined;
+    toArray(): Stream[];
+    [Symbol.iterator](): Iterator<Stream>;
+}
+declare class CaptionQuery implements Iterable<Caption> {
+    private readonly index;
+    constructor(captions: Caption[]);
+    get(langCode: string): Caption | undefined;
+    has(langCode: string): boolean;
+    get length(): number;
+    toArray(): Caption[];
+    [Symbol.iterator](): Iterator<Caption>;
+}
+
+interface YouTubeOptions {
+    onProgress?: SharedState['onProgress'];
+    onComplete?: SharedState['onComplete'];
+    useOauth?: boolean;
+    allowOauthCache?: boolean;
+}
+interface YtVideoDetails {
+    videoId?: string;
+    title?: string;
+    lengthSeconds?: string;
+    author?: string;
+    shortDescription?: string;
+    averageRating?: number;
+    viewCount?: string;
+    channelId?: string;
+    thumbnail?: {
+        thumbnails?: Array<{
+            url: string;
+        }>;
+    };
+    keywords?: string[];
+}
+interface YtCaptionTrackRaw {
+    baseUrl: string;
+    name?: {
+        simpleText?: string;
+        runs?: Array<{
+            text: string;
+        }>;
+    };
+    vssId?: string;
+    languageCode?: string;
+}
+interface PlayerResponse {
+    videoDetails?: YtVideoDetails;
+    playabilityStatus?: {
+        status?: string;
+        reason?: string;
+        messages?: string[];
+        liveStreamability?: unknown;
+    };
+    streamingData?: {
+        formats?: StreamFormat[];
+        adaptiveFormats?: StreamFormat[];
+    };
+    captions?: {
+        playerCaptionsTracklistRenderer?: {
+            captionTracks?: YtCaptionTrackRaw[];
+        };
+    };
+}
+declare class YouTube {
+    readonly videoId: string;
+    readonly watchUrl: string;
+    readonly embedUrl: string;
+    readonly useOauth: boolean;
+    readonly allowOauthCache: boolean;
+    readonly state: SharedState;
+    private cachedJs;
+    private cachedJsUrl;
+    private cachedVidInfo;
+    private cachedWatchHtml;
+    private cachedEmbedHtml;
+    private cachedAgeRestricted;
+    private cachedFmtStreams;
+    private cachedInitialData;
+    private cachedMetadata;
+    private cachedTitle;
+    private cachedAuthor;
+    private cachedPublishDate;
+    constructor(url: string, opts?: YouTubeOptions);
+    static fromId(videoId: string): YouTube;
+    watchHtml(): Promise<string>;
+    embedHtml(): Promise<string>;
+    ageRestricted(): Promise<boolean>;
+    jsUrl(): Promise<string>;
+    js(): Promise<string>;
+    initialData(): Promise<unknown>;
+    /**
+     * Resolve the player response containing videoDetails + streamingData.
+     *
+     * Strategy (late-2025 reality):
+     *   1. Primary: scrape `ytInitialPlayerResponse` from the watch HTML. This is
+     *      the same payload a browser sees and contains streamingData + captions.
+     *   2. Fallback: InnerTube /player endpoint (useful for age-gate bypass, but
+     *      currently rate-limited by YouTube's "Sign in to confirm you're not a
+     *      bot" check for server-side IPs).
+     *
+     * If the primary path returns a useful response we never touch InnerTube,
+     * which avoids the bot-detection entirely for normal public videos.
+     */
+    vidInfo(): Promise<PlayerResponse>;
+    streamingData(): Promise<NonNullable<PlayerResponse['streamingData']>>;
+    checkAvailability(): Promise<void>;
+    bypassAgeGate(): Promise<void>;
+    fmtStreams(): Promise<Stream[]>;
+    streams(): Promise<StreamQuery>;
+    captionTracks(): Promise<Caption[]>;
+    captions(): Promise<CaptionQuery>;
+    title(): Promise<string>;
+    description(): Promise<string | null>;
+    length(): Promise<number>;
+    views(): Promise<number>;
+    rating(): Promise<number | null>;
+    author(): Promise<string>;
+    keywords(): Promise<string[]>;
+    channelId(): Promise<string | null>;
+    channelUrl(): Promise<string>;
+    thumbnailUrl(): Promise<string>;
+    publishDate(): Promise<Date | null>;
+    metadata(): Promise<YouTubeMetadata>;
+    /**
+     * Fetch and cache everything needed for synchronous metadata access.
+     * After this resolves, the *Sync getters and the `streams` getter return
+     * results immediately without further network I/O.
+     */
+    prefetch(): Promise<void>;
+    get titleSync(): string;
+    get authorSync(): string;
+    get streamsSync(): StreamQuery;
+    registerOnProgressCallback(fn: SharedState['onProgress']): void;
+    registerOnCompleteCallback(fn: SharedState['onComplete']): void;
+    toString(): string;
+    equals(other: unknown): boolean;
+}
+
+interface ContinuationRequest {
+    url: string;
+    headers: Record<string, string>;
+    data: Record<string, unknown>;
+}
+declare class Playlist implements AsyncIterable<YouTube> {
+    protected readonly inputUrl: string;
+    private cachedHtml;
+    private cachedYtcfg;
+    private cachedInitialData;
+    private cachedSidebar;
+    private cachedPlaylistId;
+    private cachedVideoUrls;
+    constructor(url: string);
+    get playlistId(): string;
+    get playlistUrl(): string;
+    html(): Promise<string>;
+    ytcfg(): Promise<Record<string, unknown>>;
+    initialData(): Promise<Record<string, unknown>>;
+    sidebarInfo(): Promise<unknown[]>;
+    ytApiKey(): Promise<string>;
+    protected paginate(untilWatchId?: string): AsyncGenerator<string[]>;
+    protected buildContinuationRequest(continuation: string): Promise<ContinuationRequest>;
+    protected static extractVideos(rawJson: string): [string[], string | null];
+    videoUrls(): Promise<string[]>;
+    videos(): AsyncGenerator<YouTube>;
+    length(): Promise<number>;
+    [Symbol.asyncIterator](): AsyncIterator<YouTube>;
+    title(): Promise<string | null>;
+    description(): Promise<string | null>;
+    owner(): Promise<string | null>;
+    ownerId(): Promise<string | null>;
+    ownerUrl(): Promise<string | null>;
+}
+
+declare class Channel extends Playlist {
+    readonly channelUri: string;
+    readonly channelUrl: string;
+    readonly videosUrl: string;
+    readonly playlistsUrl: string;
+    readonly communityUrl: string;
+    readonly featuredChannelsUrl: string;
+    readonly aboutUrl: string;
+    private cachedVideosHtml;
+    constructor(url: string);
+    html(): Promise<string>;
+    channelName(): Promise<string | null>;
+    channelId(): Promise<string | null>;
+    vanityUrl(): Promise<string | null>;
+    protected static extractVideos(rawJson: string): [string[], string | null];
+}
+
+declare class Search {
+    readonly query: string;
+    private readonly innertube;
+    private cachedResults;
+    private currentContinuation;
+    private initialResults;
+    constructor(query: string);
+    results(): Promise<YouTube[]>;
+    /** Fetch the next page of results and append to the cached results array. */
+    getNextResults(): Promise<void>;
+    completionSuggestions(): Promise<string[] | null>;
+    fetchAndParse(continuation?: string): Promise<[YouTube[], string | null]>;
+}
+
+interface InnerTubeClientConfig {
+    context: {
+        client: Record<string, unknown>;
+    };
+    header: Record<string, string>;
+    apiKey: string;
+}
+declare const DEFAULT_CLIENTS: Record<string, InnerTubeClientConfig>;
+type InnerTubeClientName = keyof typeof DEFAULT_CLIENTS;
+interface InnerTubeOptions {
+    client?: InnerTubeClientName;
+    useOauth?: boolean;
+    onAuthPrompt?: (verificationUrl: string, userCode: string) => Promise<void>;
+}
+declare class InnerTube {
+    private readonly context;
+    private readonly header;
+    private readonly apiKey;
+    private readonly useOauth;
+    private readonly onAuthPrompt?;
+    private accessToken;
+    private refreshToken;
+    private expires;
+    constructor(opts?: InnerTubeOptions);
+    get baseUrl(): string;
+    private baseData;
+    private endpointUrl;
+    private callApi;
+    player<T = unknown>(videoId: string): Promise<T>;
+    search<T = unknown>(searchQuery: string, continuation?: string): Promise<T>;
+    browse<T = unknown>(continuation: string): Promise<T>;
+    verifyAge<T = unknown>(videoId: string): Promise<T>;
+    getTranscript<T = unknown>(videoId: string): Promise<T>;
+    private refreshBearerToken;
+    private fetchBearerToken;
+}
+
+interface ItagInfo {
+    resolution: string | null;
+    abr: string | null;
+}
+interface FormatProfile {
+    resolution: string | null;
+    abr: string | null;
+    isLive: boolean;
+    is3d: boolean;
+    isHdr: boolean;
+    isDash: boolean;
+}
+declare const PROGRESSIVE_VIDEO: Record<number, ItagInfo>;
+declare const DASH_VIDEO: Record<number, ItagInfo>;
+declare const DASH_AUDIO: Record<number, ItagInfo>;
+declare const ITAGS: Record<number, ItagInfo>;
+declare function getFormatProfile(itag: number | string): FormatProfile;
+
+declare const VERSION = "0.1.1";
+
+export { AgeRestrictedError, Caption, CaptionQuery, Channel, DASH_AUDIO, DASH_VIDEO, type DownloadOptions, ExtractError, type FilterCriteria, type FormatProfile, HTMLParseError, ITAGS, InnerTube, type InnerTubeClientName, type InnerTubeOptions, type ItagInfo, LiveStreamError, MaxRetriesExceeded, MembersOnly, PROGRESSIVE_VIDEO, Playlist, PytubeError, type RawCaptionTrack, RecordingUnavailable, RegexMatchError, Search, type SharedState, Stream, type StreamPredicate, StreamQuery, VERSION, VideoPrivate, VideoRegionBlocked, VideoUnavailable, YouTube, YouTubeMetadata, type YouTubeOptions, getFormatProfile };