youtube

type AttemptID string

type Availability uint8

type ChannelRef struct {
	// ID is the UC channel ID when directly available (a bare ID or a /channel/
	// URL); a pure UC-to-UU transform yields the uploads playlist.
	ID string
	// URL is the canonical channel URL to resolve when ID is empty (a handle or a
	// /c/ or /user/ vanity name).
	URL string
}

type Chapter struct {
	Title string        // chapter title
	Start time.Duration // chapter start offset
	// End is the chapter's end offset, derived from the next chapter's start (or
	// the video duration for the last chapter). It is zero when the chapter is
	// open-ended: the last chapter of a video whose duration is unknown or not
	// past the chapter start.
	End time.Duration
}

type Client struct {
	// contains filtered or unexported fields
}

type ClientProfile struct {
	Name          string // internal name, e.g. "ANDROID_VR"
	InnerTubeName string // InnerTube context clientName, e.g. "ANDROID_VR"
	InnerTubeID   int    // drives X-Youtube-Client-Name (never hardcoded)
	Version       string // InnerTube client version
	APIKey        string // optional InnerTube API key
	UserAgent     string // request User-Agent

	// Device and OS fields sent in the InnerTube client context. Mobile and VR
	// clients need these populated; sparse identities are more likely to hit the
	// bot-check path. Zero values are omitted from the request.
	DeviceMake        string
	DeviceModel       string // client device model
	OSName            string // client operating-system name
	OSVersion         string // client operating-system version
	AndroidSDKVersion int    // Android SDK level, or 0 when not applicable

	// RequiresPOTokens lists the PO-token scopes this client must supply: a
	// player-scope token in the /player body, a GVS token on the stream URL,
	// or both. Empty means none. NewClientProfile clones and canonicalizes
	// the slice.
	RequiresPOTokens  []potoken.Scope
	SupportsCookies   bool // whether cookie-backed sessions are supported
	SupportsPlaylists bool // whether the profile can browse playlists

	// NeedsSignatureTimestamp indicates that /player requests for this profile
	// must include the signature timestamp from base.js. Profiles that return
	// direct URLs should leave it false to avoid loading base.js during extraction.
	NeedsSignatureTimestamp bool

	// EmbedURL is sent as context.thirdParty.embedUrl on /player requests, where
	// WEB_EMBEDDED_PLAYER needs a third-party embed origin (not youtube.com) or it
	// returns a playability ERROR.
	EmbedURL string
	// contains filtered or unexported fields
}

type Config struct {
	// HTTP is the retrying HTTP client. If nil, a default httpx.Client is used.
	HTTP *httpx.Client
	// Logger receives debug logs. If nil, logging is discarded.
	Logger *slog.Logger
	// Profiles overrides the client strategy chain. If empty, DefaultProfiles().
	Profiles []ClientProfile
	// ChromeMajor overrides the emulated Chrome major for built-in WEB-family
	// identities. It applies to the default profile chain and to built-in WEB
	// requests used for discovery and fallbacks. Zero selects the built-in
	// default. Caller-supplied Profiles are unchanged.
	ChromeMajor int
	// Resolver resolves candidate formats into playable URLs. If nil, New builds
	// a default base.js/goja resolver over the same HTTP client. Metadata
	// extraction does not need one; stream resolution (Resolve) does.
	Resolver resolver.Resolver
	// POTokenProvider supplies PO tokens when a profile requires one. WaxTap may
	// call it during extraction for a player-scope token and during resolution for
	// a GVS-scope stream token. Nil means no provider is configured.
	POTokenProvider potoken.Provider
	// PlayerContextProvider supplies an attested WEB /player streaming context,
	// enabling the opt-in WEB SABR audio path (see Client.ExtractWebContext). Nil
	// leaves WaxTap on its default extraction chain.
	PlayerContextProvider potoken.PlayerContextProvider
	// WebContextTimeout bounds each PlayerContextProvider call, both the initial
	// extraction and a mid-stream reload's re-fetch, so a hung provider cannot
	// hang a download. Zero adds no bound.
	WebContextTimeout time.Duration
	// Session is an externally supplied guest identity the Client adopts verbatim,
	// skipping its own homepage bootstrap. It is pre-resolved: its cookies are
	// seeded at New and its visitorData is used for every extraction. Use it for
	// byte-exact session coherence with a PO-token minter. The caller must select
	// a uniform client chain (the facade enforces this); nil leaves the built-in
	// bootstrap in place.
	Session *potoken.Session
	// SessionProvider resolves an external guest identity lazily, at most once per
	// Client (cached on success). It is the pull-based form of Session. At most one
	// of Session / SessionProvider may be set.
	SessionProvider potoken.SessionProvider
	// ResolveTimeout bounds each cipher JS execution during resolution. Zero
	// uses the resolver default.
	ResolveTimeout time.Duration
	// CacheDir is the base directory for on-disk caches. When set, and when
	// DisableDiskCache is false, the default resolver stores base.js source under
	// CacheDir/players. Empty leaves the resolver memory-only. Ignored when a
	// Resolver is injected.
	CacheDir string
	// DisableDiskCache turns off the on-disk base.js source cache even when
	// CacheDir is set.
	DisableDiskCache bool
	// HL (host language, e.g. "en") and GL (content region, e.g. "US") set the
	// InnerTube locale. Empty defaults to en / US. These are localization hints:
	// geo-restricted availability is still governed by the request IP.
	HL string
	GL string // content-region hint
}

type EnumOptions struct {
	// MaxItems caps the returned entries; <= 0 lists every entry.
	MaxItems int
	// OnPage reports the running entry count after each successfully appended page.
	OnPage func(count int)
	// Skip omits matching entries but keeps paging, for an archive cursor over an
	// arbitrary playlist. It is applied before the MaxItems cap so the cap counts
	// unseen entries, and skipped entries still advance the index so
	// PlaylistEntry.Index stays the true playlist position.
	Skip func(id string) bool
	// Stop halts pagination at the first matching entry (excluding it and every
	// entry after it) and leaves Playlist.Continuation empty. It is only correct on
	// an append-only newest-first feed (a channel uploads playlist); a curated PL
	// can insert entries anywhere, so Stop on one would drop items. Use Skip for the
	// general case. Stop is checked before Skip.
	Stop func(id string) bool
	// ChannelID, when set, is stamped onto every entry. A channel-feed enumeration
	// already knows the uploader, so no per-video Enrich is needed.
	ChannelID string
}

type Extraction struct {
	// contains filtered or unexported fields
}

type LiveStatus uint8

type MediaPlan struct {
	Direct *ResolvedStream // direct signed-URL stream
	SABR   *SABRStream     // SABR-backed stream
}

type Playlist struct {
	ID           string          // YouTube playlist ID
	Title        string          // playlist title
	Author       string          // playlist owner name
	Entries      []PlaylistEntry // entries in playlist order
	Errors       []error         // per-entry failures (partial enumeration is not fatal)
	Continuation string          // opaque token for the next page; "" when exhausted
}

type PlaylistEntry struct {
	VideoID   string        // YouTube video ID
	Title     string        // entry title
	Author    string        // channel or uploader name
	ChannelID string        // uploader's channel ID (UC), or "" when not resolved at enumerate time
	Duration  time.Duration // video duration, or 0 when unknown
	Index     int           // 0-based position within the playlist
}

type ResolvedStream struct {
	URL           string      // signed media URL; empty for SABR streams
	ExpiresAt     time.Time   // URL expiry, or zero when unknown
	ContentLength int64       // bytes, or 0 when unknown
	Headers       http.Header // headers required when fetching URL
	// IsSABR reports whether the stream must be fetched through SABR.
	IsSABR bool
}

type SABRStream struct {
	// contains filtered or unexported fields
}

type SABRStreamInfo struct {
	ContentLength int64  // bytes, or 0 when unknown
	ContentType   string // MIME type reported by the SABR response
}

type Thumbnail struct {
	URL    string // image URL
	Width  int    // pixel width, or 0 when unknown
	Height int    // pixel height, or 0 when unknown
}

type Video struct {
	ID          string        // YouTube video ID (canonical, stable identity anchor)
	URL         string        // canonical watch URL (https://www.youtube.com/watch?v=<ID>)
	Title       string        // video title
	Author      string        // channel / uploader name
	ChannelID   string        // YouTube channel ID (canonical UC identity anchor)
	Duration    time.Duration // video duration, or 0 when unknown
	PublishDate time.Time     // publication date, or zero when unknown
	Description string        // video description

	Thumbnails []Thumbnail // cover-art candidates, largest first
	Chapters   []Chapter   // chapter markers in playback order

	Formats []format.Format // candidate audio (and incidental video) formats

	// LiveStatus reports the broadcast state. On a Video returned by extraction it
	// is LiveNone or LiveWasLive (a completed VOD): currently-live and upcoming
	// videos are rejected earlier and surface as ErrLiveContent / ErrLiveNotStarted
	// sentinels instead of a Video.
	LiveStatus LiveStatus
	// Availability reports whether the video is publicly listed. It is set to
	// AvailabilityPublic or AvailabilityUnlisted only on a watch-page metadata pass
	// (the microformat that carries it is WEB-only); otherwise it is
	// AvailabilityUnknown. Restricted states (private, members-only, geo-blocked,
	// removed, age-gated) surface as availability sentinels, not a Video.
	Availability Availability
}

type WatchPageMeta struct {
	PublishDate time.Time // zero when the page carried none
	Chapters    []Chapter // nil when the video has no chapters
	Unlisted    bool      // the video is unlisted (link-only)
}