format

package
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package format implements media-format selection.

Package format implements media-format selection.

Index

Constants

View Source 
const MaxMergeTracks = 16

MaxMergeTracks is the maximum number of format tracks that may be merged into one output product. It matches the selector parser and evaluator bound.

View Source 
const MaxNormalizedFormats = 4096

MaxNormalizedFormats is the maximum number of canonical formats accepted for one media entry. Product boundaries which inspect every candidate must use this value rather than inventing a lower, incompatible ceiling.

Variables

View Source 
var (
	// ErrMultiOutput indicates the selector yields multiple independent outputs
	// that the legacy flat []Selection API cannot represent.
	ErrMultiOutput = errors.New("selector yields multiple independent outputs")
	// ErrSelectorLimit indicates a syntactically valid selector exceeded a
	// bounded evaluation limit. Product callers categorize this as invalid_input
	// while still using errors.Is(err, ErrSelectorLimit) for the sentinel.
	ErrSelectorLimit = errors.New("format selector exceeds limit")
)
View Source 
var (
	ErrNoFormats      = errors.New("no downloadable formats")
	ErrInvalidHeaders = errors.New("invalid format HTTP headers")
	// ErrInvalidFormats indicates a formats list whose members violate the
	// structural contracts of the selector pipeline: a non-list formats field,
	// a non-object member, or a non-string/non-null format_id.
	ErrInvalidFormats = errors.New("invalid format list")
	// ErrFormatLimit indicates the format pipeline exceeded one of its bounded
	// inputs (entry count, per-ID bytes, or total normalized bytes).
	ErrFormatLimit = errors.New("format preparation exceeds limit")
)
View Source 
var (
	ErrInvalidSelector  = errors.New("invalid format selector")
	ErrNoMatch          = errors.New("no format matches selector")
	ErrFilterEvaluation = errors.New("format filter evaluation failed")
)
View Source 
var ErrInvalidPreference = errors.New("invalid format preference")

Functions

func CompatibleExtensionForSelections 

func CompatibleExtensionForSelections(tracks []Selection, preferences []string) string

CompatibleExtensionForSelections computes the merged output container for retained tracks using the same rules as planner metadata. preferences may be nil to use yt-dlp's default MP4/WebM pass.

func DefaultSelectorSpec 

func DefaultSelectorSpec(
	capabilities PlannerCapabilities,
	context DefaultSelectorContext,
	options Options,
) string

DefaultSelectorSpec returns the selector string the planner will evaluate for the default format request. It is pure: no FFmpeg probing, no stdout detection, no IO. Warning policy intentionally lives outside this function and is handled by the product layer that produced PlannerCapabilities.

preferBest follows yt-dlp's pinned rule: 

preferBest := capabilities.OutputToStdout
             || (context.IsLive && !context.LiveFromStart)

preferBest = preferBest || !capabilities.CanMergeFormats

compatibilityMode is true when allow_multiple_audio_streams is set or the legacy "format-spec" compat opt is on.

Returned string: 

preferBest            -> "best/bestvideo+bestaudio"
compatibilityMode      -> "bestvideo+bestaudio/best"
default (VOD merger)   -> "bestvideo*+bestaudio/best"

func MergeHeaders 

func MergeHeaders(values ...value.Value) (http.Header, error)

MergeHeaders validates and combines ordered metadata header collections. Later collections override earlier values.

Types

type Atom 

type Atom struct {
	OK    bool
	Best  bool
	Media AtomMedia
	Star  bool
	Index int // one-based; Canonical omits ".1"
	// contains filtered or unexported fields
}

Atom is the typed best/worst selector form.

func (Atom) Canonical 

func (atom Atom) Canonical() string

Canonical returns the long-form atom text. Index 1 is omitted.

type AtomMedia 

type AtomMedia uint8

AtomMedia selects which media-bearing formats an atom may match. 

const (
	// AtomMediaCombined is best/worst without a video/audio type.
	AtomMediaCombined AtomMedia = iota
	AtomMediaVideo
	AtomMediaAudio
)

type Choice 

type Choice struct {
	Terms []Term
}

Choice is the legacy slash-alternative merge group representation.

type DefaultSelectorContext 

type DefaultSelectorContext struct {
	IsLive           bool
	LiveFromStart    bool
	LegacyFormatSpec bool
}

DefaultSelectorContext describes the live context that influences the default selector recommendation. It mirrors the `_default_format_spec` inputs in yt-dlp's YoutubeDL.

type EvaluationOptions 

type EvaluationOptions struct {
	Availability FormatAvailability
}

EvaluationOptions bundles evaluator-only knobs that do not participate in canonical format preparation. They are passed explicitly to PlanWithOptions and PlanSelectWithEvaluationOptions so that:

  • the canonical Preparation/Options path stays free of evaluator concerns,
  • tests can exercise availability independently of sort/preference options,
  • later CLI wiring does not have to retro-fit availability into Options.

A zero-value EvaluationOptions means "every candidate is available", which matches Python's default `_check_formats` behaviour when no format-check or `allow_unplayable_formats` setting is supplied.

type Filter 

type Filter struct {
	Field    string
	Operator string
	Value    string
	// contains filtered or unexported fields
}

Filter is a bounded [field op value] selector predicate. Raw syntax ownership lives in unexported fields so the compiler can compile the original bracket body (including ?, quoting, and escapes) while retaining the exported legacy Field/Operator/Value surface for in-repo constructors.

type FormatAvailability 

type FormatAvailability interface {
	IsAvailable(format *value.Object) (bool, error)
}

FormatAvailability reports whether a candidate format object is currently selectable by the planner. It mirrors yt-dlp's lazy _check_formats gate while remaining externally injected: the format planner never performs IO, probing, or any external work itself; the caller supplies an implementation if and when such work is needed.

Implementations must be safe to invoke from a single goroutine; the planner never calls into FormatAvailability concurrently. They receive the canonical *value.Object owned by the Prepared instance and must not mutate it.

type FormatAvailabilityFunc 

type FormatAvailabilityFunc func(format *value.Object) (bool, error)

FormatAvailabilityFunc adapts a plain function to the FormatAvailability interface. The zero value is not meaningful; the canonical adapter pattern is to declare a small function literal at the call site: 

format.PlanWithOptions(selector, format.EvaluationOptions{
    Availability: format.FormatAvailabilityFunc(func(o *value.Object) (bool, error) {
        // ... external check ...
    }),
})

func (FormatAvailabilityFunc) IsAvailable 

func (fn FormatAvailabilityFunc) IsAvailable(format *value.Object) (bool, error)

IsAvailable implements FormatAvailability.

type FragmentEquivalence added in v0.2.1 

type FragmentEquivalence struct {
	Kind  string
	Value string
	Scope string
}

FragmentEquivalence is a bounded provider assertion that maps a selected representation's structural fragment keys to immutable bytes. Only provider-immutable and content-identity are accepted here. Strong remote validators require fresh response checking and are intentionally rejected until an adapter implements that contract.

type Options 

type Options struct {
	Sort                      []SortField
	SortForce                 bool
	PreferFreeFormats         bool
	PreferExtensions          []string
	AllowDRM                  bool
	AllowMultipleVideoStreams bool
	AllowMultipleAudioStreams bool
}

Options controls deterministic preference ordering. The zero value retains historical best/worst behaviour while rejecting confirmed DRM formats.

Sort carries the final ordered user sort list after CLI/config accumulation and reset processing. Repeated CLI -S flags append fields in occurrence order; --format-sort-reset clears previously accumulated user fields. The CLI exposes those operations, and the conformance boundary tests that Options.Sort order is preserved exactly.

PreferExtensions is retained for Go API compatibility. It is inserted at the extension position of the canonical tuple, after quality fields. It must not alter the pinned oracle when empty.

AllowMultipleVideoStreams and AllowMultipleAudioStreams mirror yt-dlp's `--allow-multiple-video-streams` / `--allow-multiple-audio-streams` flags. Both default to false, matching Python's pinned stream suppression behaviour.

type OutputPlan 

type OutputPlan struct {
	Tracks   []Selection
	Metadata value.Info
}

OutputPlan is one independent download product output. Tracks within a plan are merged when there is more than one.

Metadata is the planner-owned clone of the output's merged-format dictionary. It is independent of Prepared.Info() and the extractor-owned input info: mutating it never reaches back into the extractor or the planner. For a single-track output Metadata is a defensive clone of the selected canonical format object; for a merged output it follows the yt-dlp merged-format dictionary rules (requested_formats, format, format_id, ext, protocol, language, format_note, filesize_approx, tbr, single-video and single-audio field promotion).

func PlanSelect 

func PlanSelect(info value.Info, selector Selector) ([]OutputPlan, error)

PlanSelect evaluates a selector into independent output plans.

func PlanSelectWithEvaluationOptions 

func PlanSelectWithEvaluationOptions(
	info value.Info,
	selector Selector,
	formatOptions Options,
	evaluationOptions EvaluationOptions,
) ([]OutputPlan, error)

PlanSelectWithEvaluationOptions is the canonical planner entry point. It prepares the canonical view and evaluates the selector with the supplied evaluator-only options (currently: availability injection).

func PlanSelectWithOptions 

func PlanSelectWithOptions(info value.Info, selector Selector, options Options) ([]OutputPlan, error)

PlanSelectWithOptions canonicalizes formats then evaluates the selector AST.

func (OutputPlan) DestinationSuffix 

func (plan OutputPlan) DestinationSuffix(planIndex int) string

DestinationSuffix returns a bounded, collision-resistant multi-output label. planIndex is the stable one-based output ordinal within the selector result.

func (OutputPlan) PlanID 

func (plan OutputPlan) PlanID() string

PlanID returns a bounded label derived from the selected track IDs.

type PlannerCapabilities 

type PlannerCapabilities struct {
	CanMergeFormats bool
	OutputToStdout  bool
}

PlannerCapabilities describes the runtime capabilities the planner may rely on when picking its default selector. It is supplied by the product layer (CLI/FFmpeg probing is performed outside the format package and the resulting flags are injected here).

type Prepared 

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

Prepared is one canonical defensive format view shared by product metadata, listing, printing, JSON encoding, and selector evaluation.

func Prepare 

func Prepare(info value.Info, options Options) (Prepared, error)

Prepare clones and canonicalizes extractor format metadata without mutating the extractor-owned Info.

func (Prepared) Best 

func (prepared Prepared) Best() (Selection, error)

Best selects the first playable canonical format.

func (Prepared) Default 

func (prepared Prepared) Default() ([]Selection, error)

Default applies the default selector to the canonical prepared formats. It preserves the historical contract: one output plan, fail with ErrMultiOutput if multiple plans would be returned.

func (Prepared) DefaultWithContext 

func (prepared Prepared) DefaultWithContext(
	capabilities PlannerCapabilities,
	context DefaultSelectorContext,
	evaluationOptions EvaluationOptions,
) ([]OutputPlan, error)

DefaultWithContext computes the default selector via DefaultSelectorSpec and evaluates it. The selector depends on the injected runtime capabilities (merge availability, stdout destination) and live context; the function is pure with respect to those inputs.

func (Prepared) Info 

func (prepared Prepared) Info() value.Info

Info returns the canonical defensive metadata view owned by prepared.

func (Prepared) Plan 

func (prepared Prepared) Plan(selector Selector) ([]OutputPlan, error)

Plan delegates to PlanWithOptions with the zero EvaluationOptions.

func (Prepared) PlanWithOptions 

func (prepared Prepared) PlanWithOptions(selector Selector, evalOptions EvaluationOptions) ([]OutputPlan, error)

PlanWithOptions evaluates the selector against the canonical worst-to-best format view, applying the supplied EvaluationOptions (availability). It is the canonical planner entry point after Prepare; callers should prefer it over PlanSelectWithEvaluationOptions when they already hold a Prepared.

PlanWithOptions is pure: no filesystem access, no subprocess execution, no FFmpeg probing, no network requests, no HTTP availability probes. The availability interface is invoked at most once per canonical object per call, and only for candidates that would otherwise be selected.

func (Prepared) SyncInfo 

func (prepared Prepared) SyncInfo(info value.Info) Prepared

SyncInfo rebinds evaluation format objects to the current canonical Info after post-prepare mutations (metadata replace/parse or deferred enrichment) without re-running normalization.

type Selection 

type Selection struct {
	ID       string
	URL      string
	Ext      string
	Filesize int64
	Protocol string
	VCodec   string
	ACodec   string
	Width    int64
	Height   int64
	FPS      int64
	Language string
	TBR      float64
	Headers  http.Header
	// HTTPChunkSize requests bounded byte ranges for direct HTTP media. It is
	// extractor-authored and zero retains a single streaming request.
	HTTPChunkSize  int64
	HTTPChunkFixed bool
	// CredentialIsolated requires isolated no-redirect transport for media
	// fetches so ambient cookies, authorization, and referer cannot leak.
	CredentialIsolated bool
	// AssetPolicy identifies an extractor-owned URL policy that must be
	// enforced again by native manifest and fragment downloaders at every hop.
	AssetPolicy string
	// CredentialIsolatedReferer is an extractor-validated referer that may be
	// preserved only by the credential-isolated media transport. It is never
	// taken from ambient request headers.
	CredentialIsolatedReferer string
	// HostPolicy names an extractor-owned attributable-origin policy used by
	// credential-isolated native downloaders. Empty keeps the existing generic
	// credential boundary.
	HostPolicy string
	// NiconicoScoped applies the Niconico attributable host policy to every
	// manifest and fragment hop after the generic HLS dispatcher re-enters.
	NiconicoScoped bool
	MediaPolicy    string
	// AllowedHosts is an extractor-owned HLS trust boundary. When present, the
	// native HLS downloader applies it to the manifest, variants, segments,
	// encryption keys, and initialization maps.
	AllowedHosts []string
	// FragmentResumeIdentity and FragmentEquivalence are extractor-owned
	// non-secret evidence for finite HLS/DASH session reuse. They are never
	// inferred from URL, video ID, format ID, or itag. An absent descriptor
	// means the engine conservatively restarts the complete representation on
	// the next extraction/refresh.
	FragmentResumeIdentity string
	FragmentEquivalence    FragmentEquivalence
	// FragmentKeyIdentity is an optional provider-issued, non-secret identity
	// for an encrypted HLS key epoch. Its absence deliberately keeps encrypted
	// fragments non-resumable across refreshed key URLs.
	FragmentKeyIdentity string

	// YouTubePostLive selects the finite post-live DVR sequence downloader.
	// The discriminator is extractor-produced and never inferred from a URL.
	YouTubePostLive      bool
	YouTubeLiveFromStart bool
	YouTubeItag          int64
	YouTubeClient        string
	YouTubeSourceURL     string
	YouTubeVideoID       string
	YouTubeDrc           bool
	YouTubeAudioTrackID  string
	TargetDuration       float64
	// YouTubeSABR selects the finite-VOD SABR/UMP downloader.
	YouTubeSABR                bool
	YouTubeSABRTrack           string
	YouTubeSABRItag            int64
	YouTubeSABRLastModified    int64
	YouTubeSABRXTags           string
	YouTubeSABRServerURL       string
	YouTubeSABRUstreamerConfig string
	YouTubeSABRClientID        int64
	YouTubeSABRClientVersion   string
	YouTubeSABRUserAgent       string
	YouTubeSABRVisitorData     string
	YouTubeSABRDurationSec     int64
	YouTubeSABRVideoID         string
	YouTubeSABRClientName      string
	YouTubeSABRDrc             bool
	YouTubeSABRAudioTrackID    string
	LiveStartTimestamp         int64
	// contains filtered or unexported fields
}

func Best 

func Best(info value.Info) (Selection, error)

Best selects the first canonical format.

func Default 

func Default(info value.Info, options Options) ([]Selection, error)

Default applies yt-dlp-style best-quality selection: prefer a video-only and audio-only pair, then a single combined format. Explicit user selectors remain authoritative.

func Select 

func Select(info value.Info, selector Selector) ([]Selection, error)

func SelectWithOptions 

func SelectWithOptions(info value.Info, selector Selector, options Options) ([]Selection, error)

SelectWithOptions evaluates a selector into flat tracks for one output plan. It returns ErrMultiOutput when the selector requests multiple independent comma/all outputs that cannot be represented as a single merge.

func SelectionFromObject added in v0.2.3 

func SelectionFromObject(object *value.Object) (Selection, error)

SelectionFromObject validates and prepares one normalized format object. It is used by refresh coordinators that must compare every freshly extracted representation rather than re-running user preference selection.

func (Selection) NormalizedFormatIndex 

func (selection Selection) NormalizedFormatIndex() (int, bool)

NormalizedFormatIndex returns the selection's position in the canonical filtered and sorted format list.

func (Selection) SourceFormatIndex 

func (selection Selection) SourceFormatIndex() (int, bool)

SourceFormatIndex returns the original list index of the extractor-owned format this selection was prepared from. The second return value reports whether the index is known; selection paths that bypass prepareFormats (for example the legacy helper code) report false.

type Selector 

type Selector struct {
	Alternatives []Choice
	// contains filtered or unexported fields
}

Selector holds a parsed format selector AST. Legacy Alternatives may still be set by in-repo constructors; evaluation always normalizes to the AST.

func ParseSelector 

func ParseSelector(input string) (Selector, error)

ParseSelector parses a bounded yt-dlp format selector expression.

type SortField 

type SortField struct {
	Field         string
	Descending    bool
	Closest       bool
	Limit         *float64
	LimitText     string
	CombinedLimit string
}

SortField is compatible with common yt-dlp FIELD, +FIELD, FIELD:LIMIT, and FIELD~LIMIT forms. Descending means lower values win; Closest selects the value nearest Limit. CombinedLimit captures multi-colon limit text (such as `ext:mp4:m4a`) so the sorter can split it across subfields during expansion. LimitText preserves a non-numeric ordered-field limit such as `vcodec:vp9`; both are mutually exclusive with Limit.

func ParseSortField 

func ParseSortField(input string) (SortField, error)

ParseSortField parses one bounded user preference token. Combined-field limits (multiple colons such as `ext:mp4:m4a`) are accepted by storing the raw limit text in CombinedLimit; the sorter expands them when it expands the combined field.

func ParseSortFields 

func ParseSortFields(inputs []string) ([]SortField, error)

type SyntaxError 

type SyntaxError struct {
	Start   int
	End     int
	Message string
}

SyntaxError identifies the exact half-open byte range [Start, End) rejected by the parser in the original, untrimmed selector string.

func (*SyntaxError) Error 

func (err *SyntaxError) Error() string

func (*SyntaxError) Unwrap 

func (err *SyntaxError) Unwrap() error

type Term 

type Term struct {
	Name    string
	Atom    Atom
	Filters []Filter
}

Term is the legacy merge-term representation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.