@hallelx/youtube-transcript 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,344 @@
+declare class InvalidProxyConfig extends Error {
+    constructor(message: string);
+}
+declare abstract class ProxyConfig {
+    abstract get httpUrl(): string | undefined;
+    abstract get httpsUrl(): string | undefined;
+    get preventKeepingConnectionsAlive(): boolean;
+    get retriesWhenBlocked(): number;
+}
+
+interface FetchedTranscriptSnippet {
+    text: string;
+    start: number;
+    duration: number;
+}
+interface FetchedTranscriptInit {
+    snippets: FetchedTranscriptSnippet[];
+    videoId: string;
+    language: string;
+    languageCode: string;
+    isGenerated: boolean;
+}
+declare class FetchedTranscript {
+    readonly snippets: FetchedTranscriptSnippet[];
+    readonly videoId: string;
+    readonly language: string;
+    readonly languageCode: string;
+    readonly isGenerated: boolean;
+    constructor(init: FetchedTranscriptInit);
+    [Symbol.iterator](): IterableIterator<FetchedTranscriptSnippet>;
+    get length(): number;
+    toRawData(): Array<{
+        text: string;
+        start: number;
+        duration: number;
+    }>;
+}
+
+type FetchFn = typeof fetch;
+interface HttpClientOptions {
+    proxyConfig?: ProxyConfig;
+    fetchFn?: FetchFn;
+}
+declare class HttpClient {
+    private readonly _proxyConfig?;
+    private readonly _userFetch?;
+    private readonly _cookies;
+    private _undiciDispatcher;
+    private _undiciLoaded;
+    constructor(options?: HttpClientOptions);
+    setCookie(name: string, value: string, domain: string): void;
+    get(url: string): Promise<Response>;
+    post(url: string, jsonBody: unknown): Promise<Response>;
+    private _fetch;
+    private _getUndiciDispatcher;
+}
+
+interface TranslationLanguage {
+    language: string;
+    languageCode: string;
+}
+interface TranscriptFetchOptions {
+    preserveFormatting?: boolean;
+}
+declare class Transcript {
+    readonly videoId: string;
+    readonly language: string;
+    readonly languageCode: string;
+    readonly isGenerated: boolean;
+    readonly translationLanguages: readonly TranslationLanguage[];
+    private readonly _httpClient;
+    private readonly _url;
+    private readonly _translationLanguagesByCode;
+    constructor(httpClient: HttpClient, videoId: string, url: string, language: string, languageCode: string, isGenerated: boolean, translationLanguages: readonly TranslationLanguage[]);
+    get isTranslatable(): boolean;
+    fetch(options?: TranscriptFetchOptions): Promise<FetchedTranscript>;
+    translate(languageCode: string): Transcript;
+    toString(): string;
+}
+
+interface RawCaptionTrack {
+    baseUrl: string;
+    name: {
+        runs: Array<{
+            text: string;
+        }>;
+    };
+    languageCode: string;
+    isTranslatable?: boolean;
+    kind?: string;
+}
+interface RawTranslationLanguage {
+    languageCode: string;
+    languageName: {
+        runs: Array<{
+            text: string;
+        }>;
+    };
+}
+interface CaptionsJson {
+    captionTracks: RawCaptionTrack[];
+    translationLanguages?: RawTranslationLanguage[];
+}
+declare class TranscriptList implements Iterable<Transcript> {
+    readonly videoId: string;
+    private readonly _manuallyCreated;
+    private readonly _generated;
+    private readonly _translationLanguages;
+    constructor(videoId: string, manuallyCreated: Map<string, Transcript>, generated: Map<string, Transcript>, translationLanguages: readonly TranslationLanguage[]);
+    static build(httpClient: HttpClient, videoId: string, captionsJson: CaptionsJson): TranscriptList;
+    [Symbol.iterator](): IterableIterator<Transcript>;
+    findTranscript(languageCodes: Iterable<string>): Transcript;
+    findGeneratedTranscript(languageCodes: Iterable<string>): Transcript;
+    findManuallyCreatedTranscript(languageCodes: Iterable<string>): Transcript;
+    private _findTranscript;
+    toString(): string;
+}
+
+interface YouTubeTranscriptApiOptions {
+    proxyConfig?: ProxyConfig;
+    fetchFn?: FetchFn;
+}
+interface FetchOptions {
+    languages?: Iterable<string>;
+    preserveFormatting?: boolean;
+}
+declare class YouTubeTranscriptApi {
+    private readonly _httpClient;
+    private readonly _fetcher;
+    constructor(options?: YouTubeTranscriptApiOptions);
+    list(videoId: string): Promise<TranscriptList>;
+    fetch(videoId: string, options?: FetchOptions): Promise<FetchedTranscript>;
+}
+
+declare class TranscriptListFetcher {
+    private readonly _httpClient;
+    private readonly _proxyConfig;
+    constructor(httpClient: HttpClient, proxyConfig: ProxyConfig | undefined);
+    fetch(videoId: string): Promise<TranscriptList>;
+    private _fetchCaptionsJson;
+    private _extractInnertubeApiKey;
+    private _extractCaptionsJson;
+    private _assertPlayability;
+    private _createConsentCookie;
+    private _fetchVideoHtml;
+    private _fetchHtml;
+    private _fetchInnertubeData;
+}
+
+declare class TranscriptParser {
+    private readonly _htmlRegex;
+    constructor(preserveFormatting?: boolean);
+    parse(rawData: string): FetchedTranscriptSnippet[];
+}
+
+interface GenericProxyConfigOptions {
+    httpUrl?: string;
+    httpsUrl?: string;
+}
+declare class GenericProxyConfig extends ProxyConfig {
+    protected readonly _httpUrl?: string;
+    protected readonly _httpsUrl?: string;
+    constructor(options?: GenericProxyConfigOptions);
+    get httpUrl(): string | undefined;
+    get httpsUrl(): string | undefined;
+}
+
+interface WebshareProxyConfigOptions {
+    proxyUsername: string;
+    proxyPassword: string;
+    filterIpLocations?: string[];
+    retriesWhenBlocked?: number;
+    domainName?: string;
+    proxyPort?: number;
+}
+declare class WebshareProxyConfig extends GenericProxyConfig {
+    readonly proxyUsername: string;
+    readonly proxyPassword: string;
+    readonly domainName: string;
+    readonly proxyPort: number;
+    private readonly _filterIpLocations;
+    private readonly _retriesWhenBlocked;
+    constructor(options: WebshareProxyConfigOptions);
+    get url(): string;
+    get httpUrl(): string;
+    get httpsUrl(): string;
+    get preventKeepingConnectionsAlive(): boolean;
+    get retriesWhenBlocked(): number;
+}
+
+declare abstract class Formatter {
+    abstract formatTranscript(transcript: FetchedTranscript, options?: Record<string, unknown>): string;
+    abstract formatTranscripts(transcripts: FetchedTranscript[], options?: Record<string, unknown>): string;
+}
+
+interface JsonFormatterOptions {
+    indent?: number | string;
+}
+declare class JSONFormatter extends Formatter {
+    formatTranscript(transcript: FetchedTranscript, options?: JsonFormatterOptions): string;
+    formatTranscripts(transcripts: FetchedTranscript[], options?: JsonFormatterOptions): string;
+}
+
+/**
+ * Pretty-prints a transcript using JSON.stringify with two-space indentation.
+ *
+ * Note: this differs from the Python upstream, which uses Python's `pprint`
+ * module (producing Python-repr style output). The TypeScript port uses
+ * indented JSON for the same human-readable purpose.
+ */
+declare class PrettyPrintFormatter extends Formatter {
+    formatTranscript(transcript: FetchedTranscript): string;
+    formatTranscripts(transcripts: FetchedTranscript[]): string;
+}
+
+declare class TextFormatter extends Formatter {
+    formatTranscript(transcript: FetchedTranscript): string;
+    formatTranscripts(transcripts: FetchedTranscript[]): string;
+}
+
+declare abstract class TextBasedFormatter extends TextFormatter {
+    protected abstract _formatTimestamp(hours: number, mins: number, secs: number, ms: number): string;
+    protected abstract _formatTranscriptHeader(lines: string[]): string;
+    protected abstract _formatTranscriptHelper(i: number, timeText: string, snippet: FetchedTranscriptSnippet): string;
+    protected _secondsToTimestamp(time: number): string;
+    formatTranscript(transcript: FetchedTranscript): string;
+}
+
+declare class SRTFormatter extends TextBasedFormatter {
+    protected _formatTimestamp(hours: number, mins: number, secs: number, ms: number): string;
+    protected _formatTranscriptHeader(lines: string[]): string;
+    protected _formatTranscriptHelper(i: number, timeText: string, snippet: FetchedTranscriptSnippet): string;
+}
+
+declare class WebVTTFormatter extends TextBasedFormatter {
+    protected _formatTimestamp(hours: number, mins: number, secs: number, ms: number): string;
+    protected _formatTranscriptHeader(lines: string[]): string;
+    protected _formatTranscriptHelper(_i: number, timeText: string, snippet: FetchedTranscriptSnippet): string;
+}
+
+type FormatterType = 'json' | 'pretty' | 'text' | 'webvtt' | 'srt';
+declare class UnknownFormatterType extends Error {
+    constructor(formatterType: string);
+}
+declare class FormatterLoader {
+    static readonly TYPES: Record<FormatterType, new () => Formatter>;
+    load(formatterType?: FormatterType | string): Formatter;
+}
+
+declare class YouTubeTranscriptApiException extends Error {
+    constructor(message?: string);
+}
+declare class CookieError extends YouTubeTranscriptApiException {
+}
+declare class CookiePathInvalid extends CookieError {
+    constructor(cookiePath: string);
+}
+declare class CookieInvalid extends CookieError {
+    constructor(cookiePath: string);
+}
+declare class CouldNotRetrieveTranscript extends YouTubeTranscriptApiException {
+    readonly videoId: string;
+    protected static CAUSE_MESSAGE: string;
+    constructor(videoId: string);
+    protected buildErrorMessage(): string;
+    get cause(): string;
+    toString(): string;
+}
+declare class YouTubeDataUnparsable extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class YouTubeRequestFailed extends CouldNotRetrieveTranscript {
+    reason: string;
+    protected static CAUSE_MESSAGE: string;
+    constructor(videoId: string, httpError: Error | string);
+    get cause(): string;
+}
+declare class VideoUnplayable extends CouldNotRetrieveTranscript {
+    reason: string | null;
+    subReasons: string[];
+    protected static CAUSE_MESSAGE: string;
+    protected static SUBREASON_MESSAGE: string;
+    private _initialized;
+    constructor(videoId: string, reason: string | null, subReasons: string[]);
+    get cause(): string;
+}
+declare class VideoUnavailable extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class InvalidVideoId extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class RequestBlocked extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+    protected static WITH_GENERIC_PROXY_CAUSE_MESSAGE: string;
+    protected static WITH_WEBSHARE_PROXY_CAUSE_MESSAGE: string;
+    private _proxyConfig;
+    withProxyConfig(proxyConfig: object | null | undefined): this;
+    get cause(): string;
+}
+declare class IpBlocked extends RequestBlocked {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class TranscriptsDisabled extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class AgeRestricted extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class NotTranslatable extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class TranslationLanguageNotAvailable extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class FailedToCreateConsentCookie extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+declare class NoTranscriptFound extends CouldNotRetrieveTranscript {
+    private _requestedLanguageCodes;
+    private _transcriptData;
+    private _initialized;
+    protected static CAUSE_MESSAGE: string;
+    constructor(videoId: string, requestedLanguageCodes: Iterable<string>, transcriptData: {
+        toString(): string;
+    });
+    get cause(): string;
+}
+declare class PoTokenRequired extends CouldNotRetrieveTranscript {
+    protected static CAUSE_MESSAGE: string;
+}
+
+declare const WATCH_URL_TEMPLATE = "https://www.youtube.com/watch?v={video_id}";
+declare const INNERTUBE_API_URL_TEMPLATE = "https://www.youtube.com/youtubei/v1/player?key={api_key}";
+declare const INNERTUBE_CONTEXT: {
+    readonly client: {
+        readonly clientName: "ANDROID";
+        readonly clientVersion: "20.10.38";
+    };
+};
+declare function watchUrl(videoId: string): string;
+declare function innertubeApiUrl(apiKey: string): string;
+
+export { AgeRestricted, type CaptionsJson, CookieError, CookieInvalid, CookiePathInvalid, CouldNotRetrieveTranscript, FailedToCreateConsentCookie, type FetchFn, type FetchOptions, FetchedTranscript, type FetchedTranscriptInit, type FetchedTranscriptSnippet, Formatter, FormatterLoader, type FormatterType, GenericProxyConfig, type GenericProxyConfigOptions, HttpClient, type HttpClientOptions, INNERTUBE_API_URL_TEMPLATE, INNERTUBE_CONTEXT, InvalidProxyConfig, InvalidVideoId, IpBlocked, JSONFormatter, type JsonFormatterOptions, NoTranscriptFound, NotTranslatable, PoTokenRequired, PrettyPrintFormatter, ProxyConfig, RequestBlocked, SRTFormatter, TextBasedFormatter, TextFormatter, Transcript, type TranscriptFetchOptions, TranscriptList, TranscriptListFetcher, TranscriptParser, TranscriptsDisabled, type TranslationLanguage, TranslationLanguageNotAvailable, UnknownFormatterType, VideoUnavailable, VideoUnplayable, WATCH_URL_TEMPLATE, WebVTTFormatter, WebshareProxyConfig, type WebshareProxyConfigOptions, YouTubeDataUnparsable, YouTubeRequestFailed, YouTubeTranscriptApi, YouTubeTranscriptApiException, type YouTubeTranscriptApiOptions, innertubeApiUrl, watchUrl };