Documentation
¶
Overview ¶
Package format defines WaxTap's stream-format model and the rules for picking an audio source from a candidate list.
The package keeps YouTube details at the edge. The youtube package fills Format values from player responses, while this package owns comparison and selection. A Format is only a candidate; signed media URLs and expiry metadata live in youtube.ResolvedStream.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoMatch = errors.New("format: no matching audio format")
ErrNoMatch reports that selection found no audio candidate satisfying the request. Selector-specific errors wrap it, so callers should check with errors.Is.
Functions ¶
func BestForTarget ¶
func BestForTarget(candidates []Format, policy SourcePolicy, target Target) (int, error)
BestForTarget chooses the source audio for a transcode target and returns its index in candidates. It is the BestAudio path:
- zero Target or a lossless target: use normal best-audio ranking
- MinimizeLoss: prefer a source in the target codec family
- BestNative: ignore the target codec and use normal best-audio ranking
- PreferCodec: prefer the policy codec family
Codec preference sits below original-track selection, so it never chooses a dubbed track over the original for codec compatibility. When no candidate matches the preferred codec, selection falls back to normal ranking. It returns ErrNoMatch only when there are no selectable audio candidates.
Types ¶
type AudioSelector ¶
type AudioSelector struct {
// contains filtered or unexported fields
}
AudioSelector picks one Format from a candidate list. The zero value selects the best available audio (equivalent to BestAudio()).
The selector stores caller intent; concrete selection is performed by the extraction/download pipeline.
func BestAudio ¶
func BestAudio() AudioSelector
BestAudio selects the best audio stream, preferring the original track, non-DRC audio, then higher effective bitrate.
func Codec ¶
func Codec(codec string) AudioSelector
Codec selects the best stream whose codec matches (e.g. "opus", "aac").
func (AudioSelector) Select ¶
func (s AudioSelector) Select(candidates []Format, policy SourcePolicy, target Target) (int, error)
Select resolves an AudioSelector against candidates and returns the chosen index. The index matters because an itag can repeat across language and DRC variants.
Itag and Codec first filter to matching audio candidates, then use normal audio ranking within that set. BestAudio, including the zero selector, delegates to BestForTarget so SourcePolicy and Target can influence the source. Select returns ErrNoMatch when no audio candidate satisfies the selector.
func (AudioSelector) String ¶
func (s AudioSelector) String() string
type AudioTrack ¶
AudioTrack holds the raw audioTrack metadata YouTube attaches to dubbed or multi-language renditions.
type Format ¶
type Format struct {
Itag int
// Codec / container.
MIMEType string // raw mimeType, e.g. `audio/webm; codecs="opus"`
Codec string // normalized codec id, e.g. "opus", "mp4a.40.2"
Extension string // canonical file extension without dot, e.g. "webm", "m4a"
// Audio characteristics.
Bitrate int // declared / peak bits per second
AverageBitrate int // average bits per second (preferred for comparison)
SampleRate int // Hz
Channels int
// Multi-language / dubbed audio metadata.
Language string // audioTrack language tag, "" if single-track
AudioTrack *AudioTrack // raw audioTrack metadata, nil if none
// Tri-state quality hints (YouTube is inconsistent about exposing these).
IsDRC Tri // dynamic-range-compressed rendition
IsOriginal Tri // original (non-dubbed) audio
// Size / length when known (0 == unknown).
ContentLength int64
Duration time.Duration
}
Format describes a playable stream candidate. Most WaxTap callers deal with audio, but video formats can appear in unfiltered player responses and are excluded by audio selectors.
func (Format) EffectiveBitrate ¶
EffectiveBitrate returns AverageBitrate when known, else the declared Bitrate. It is the value selectors compare on.
type SourcePolicy ¶
type SourcePolicy struct {
// contains filtered or unexported fields
}
SourcePolicy controls the source-stream tradeoff when a transcode target is set. The zero value is MinimizeLoss().
func BestNative ¶
func BestNative() SourcePolicy
BestNative ignores target codec matching and uses normal best-audio ranking.
func MinimizeLoss ¶
func MinimizeLoss() SourcePolicy
MinimizeLoss prefers a source in the target codec family, avoiding a cross-codec transcode when possible.
func PreferCodec ¶
func PreferCodec(codec string) SourcePolicy
PreferCodec prefers a source in the named codec family when policy is active.
func (SourcePolicy) String ¶
func (p SourcePolicy) String() string
type Target ¶
type Target struct {
// Codec is the normalized output codec id, such as "aac" or "opus".
// MinimizeLoss uses it only when a YouTube source may exist in the same
// family. Leave it empty for targets with no native source equivalent, such
// as MP3.
Codec string
// Lossless is true for FLAC, ALAC, and WAV targets. Since these preserve the
// decoded samples, source codec matching does not help.
Lossless bool
}
Target describes the transcode output BestForTarget is selecting for. A zero Target means keep or copy the source, so normal best-audio ranking applies.
Source Files