quality

package
v0.0.0-...-d0fda0e Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: GPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package quality contains target-quality search and CVVDP helpers.

Index

Constants

View Source 
const (
	MinSVTCRF float32 = 1.0
	MaxSVTCRF float32 = 70.0

	DefaultSearchMin float32 = 4.25
	DefaultSearchMax float32 = 63.75
)
View Source 
const (
	SSIMU2Target    float32 = 67.4
	SSIMU2Tolerance float32 = 7.5
)

SSIMU2 target band, calibrated against the shipped CVVDP band on the 1080p SDR test corpus. At the 9.55 JOD center, the measured corpus median is 67.4 SSIMU2 with a 37.5 points/JOD local exchange rate, so 67.4 +/- 7.5 preserves the 0.20 JOD half-width. See docs/PERFORMANCE_TESTING.md. These are mean-pooled per-frame scores (mean is the tightest pooling at constant CVVDP; percentiles amplify content-dependent worst-frame variance).

View Source 
const (
	JODAnchorTarget    float32 = 9.55
	JODAnchorTolerance float32 = 0.20
)

JODAnchor ties the SSIMU2 scale to the CVVDP quality policy: SSIMU2Target corresponds to JODAnchorTarget on the shipped display model, and per-title calibration measures each title's offset from that corpus-level anchor (grainy content sits several points lower at equal JOD, clean digital higher -- per-title sd ~0.13 JOD, which a global target cannot absorb: the 2026-07-10 pilot A/B over-encoded a grainy clip +32% in size).

View Source 
const DisplayModelKey = "reel"

Variables

This section is empty.

Functions

func EnsureDisplayModel 

func EnsureDisplayModel(workDir string, inf *video.Info, overridePath string) (string, error)

func FormatCRF 

func FormatCRF(crf float32) string

FormatCRF formats a CRF exactly enough for SVT-AV1 quarter-step values.

func InterpolateCRF 

func InterpolateCRF(probes []Probe, target float32) float32

InterpolateCRF linearly interpolates a CRF for the target score using the pair of adjacent probes (ordered by score) whose scores bracket the target. If the target falls outside all probe scores, the nearest segment extrapolates, matching the prior linear behavior at two probes.

func IsQuarterCRF 

func IsQuarterCRF(crf float32) bool

IsQuarterCRF reports whether crf is on SVT-AV1's quarter-step grid.

func OverRate 

func OverRate(ctx SearchContext, p Probe) bool

OverRate reports whether a probe's bitrate exceeds the cap, on chunk average or on its worst one-second window. Encodes run with the cap active, so an over-rate probe means the rate regulator failed to hold at that CRF: the probe is unusable regardless of score, and its score is distorted by regulator thrash. Decoders chew seconds, not chunk averages, hence the peak gate; observed stutter on hardware provisioned for the signaled level came from single-second spikes inside chunks whose averages honored the cap. The slack keeps legitimately regulated probes that land at the cap from being rejected as noise, with the peak gate slightly looser for single-second granularity.

func ParseCRF 

func ParseCRF(s string) (float32, error)

ParseCRF parses and validates a fixed CRF value.

func ParseCRFSearchRange 

func ParseCRFSearchRange(s string) (float32, float32, error)

ParseCRFSearchRange parses and validates a target-quality CRF search range.

func ParseRange 

func ParseRange(s, name string) (float32, float32, error)

ParseRange parses LOW-HIGH into two floats.

func ParseTargetQualityRange 

func ParseTargetQualityRange(s string) (low, high, target, tolerance float32, err error)

ParseTargetQualityRange parses a CVVDP JOD target range.

func RoundCRFToQuarter 

func RoundCRFToQuarter(crf float32) float32

RoundCRFToQuarter rounds a CRF to SVT-AV1's quarter-step grid.

func SSIMU2FromJOD 

func SSIMU2FromJOD(jod float32) float32

SSIMU2FromJOD maps a CVVDP JOD score onto the corpus-anchored SSIMU2 scale.

func ValidateCRF 

func ValidateCRF(crf float32) error

ValidateCRF checks a fixed CRF against SVT-AV1 git HEAD's supported range.

func VshipBuildEnabled 

func VshipBuildEnabled() bool

Types

type CVVDPOptions 

type CVVDPOptions struct {
	SourcePath string
	ProbePath  string
	Info       *video.Info
	Chunk      chunk.Chunk
	CropRect   *video.CropRect
	Width      uint32
	Height     uint32
	Denoise    string // Experimental libavfilter graph applied to reference frames
	// Reference optionally supplies the chunk's reference frames already
	// decoded, cropped, and denoise-filtered. When nil the source is decoded
	// and filtered here. See the target-quality reference cache: re-filtering
	// the reference for every probe dominated denoised 4K wall time.
	Reference video.FrameReader
	Processor *VshipProcessor
}

type CVVDPResult 

type CVVDPResult struct {
	Score         float32
	Frames        int
	MetricSeconds float64
}

func ComputeChunkCVVDP 

func ComputeChunkCVVDP(ctx context.Context, opts CVVDPOptions) (CVVDPResult, error)

A split Open-before-pool-checkout / Compute-after variant (setup hoist, ring depth 3) was tested and rejected 2026-07-02: wall gain was within run-to-run noise, so the simpler single-function pass stays. See docs/PERFORMANCE_TESTING.md.

func ComputeChunkDenoiseCeiling 

func ComputeChunkDenoiseCeiling(ctx context.Context, opts DenoiseCeilingOptions) (CVVDPResult, error)

ComputeChunkDenoiseCeiling scores the denoised source against the unfiltered source for one chunk. Target-quality mode scores probes against the denoised reference, so its per-chunk scores overstate delivered quality by whatever the denoiser itself removed; this measures that honestly as the best score any encode of the denoised source could reach.

type ChunkScoreRequest 

type ChunkScoreRequest struct {
	SourcePath string
	ProbePath  string
	Info       *video.Info
	Chunk      chunk.Chunk
	CropRect   *video.CropRect
	Width      uint32
	Height     uint32
	// Denoise is the experimental libavfilter graph the encoder ran the source
	// through. The reference frames must go through the same graph, otherwise
	// the metric would score the encode against pixels it never saw.
	Denoise string
	// Reference optionally supplies the chunk's reference frames already
	// decoded, cropped, and filtered, bypassing the decode+filter pass here.
	Reference video.FrameReader
}

ChunkScoreRequest describes one whole-chunk probe scoring job, independent of which metric performs it.

type ChunkScorer 

type ChunkScorer interface {
	ScoreChunk(ctx context.Context, req ChunkScoreRequest) (score float32, metricSeconds float64, err error)
	Close() error
}

ChunkScorer scores whole chunks with one metric. Implementations own a GPU handler and are not safe for concurrent use; the target-quality encoder keeps one scorer per metric worker (see the MITIGATE_MALLOC_ASYNC note in target_quality.go).

func NewChunkScorer 

func NewChunkScorer(kind MetricKind, width, height uint32, inf *video.Info, displayPath string) (ChunkScorer, error)

NewChunkScorer builds a scorer for the metric kind. displayPath is only consulted for CVVDP (SSIMU2 has no display model).

type DenoiseCeilingOptions 

type DenoiseCeilingOptions struct {
	SourcePath string
	Info       *video.Info
	Chunk      chunk.Chunk
	CropRect   *video.CropRect
	Width      uint32
	Height     uint32
	Denoise    string
	Processor  *VshipProcessor
}

DenoiseCeilingOptions describes a denoise-ceiling measurement: CVVDP of the denoised source against the unfiltered source, with no encode in between.

type FramePlanes 

type FramePlanes struct {
	Planes  [3]*byte
	Strides [3]int64
}

func PlanesFromYUV420P10 

func PlanesFromYUV420P10(buf []byte, width, height uint32) (FramePlanes, error)

type MetricKind 

type MetricKind string

MetricKind selects the perceptual metric that scores target-quality probes. 

const (
	MetricCVVDP  MetricKind = "cvvdp"
	MetricSSIMU2 MetricKind = "ssimulacra2"
)

func ProbeMetricForSource 

func ProbeMetricForSource(inf *video.Info) MetricKind

ProbeMetricForSource picks the probe metric for a source. SDR at or below 1080p uses SSIMULACRA2: CVVDP pays its display-model resize to a 4K raster even for 1080p input, making 1080p metric-bound (85-91% of encode-phase wall), while SSIMU2 runs ~8.5x faster on the same libvship and a fixed SSIMU2 target holds the CVVDP band to ~sd 0.10 JOD. HDR and >1080p keep CVVDP: SSIMU2 has no display/luminance model, and 4K is encode-bound so a faster metric buys little there. Source dimensions (not post-crop output) keep the choice stable across crop detection.

func (MetricKind) DefaultSlopePerCRF 

func (k MetricKind) DefaultSlopePerCRF() float32

DefaultSlopePerCRF is the no-information score-per-CRF slope used until measured slopes accumulate: the long-standing calibrated 0.025 JOD/CRF (see target_quality.go) in the metric's units. For SSIMU2 that is 0.9375 pts/CRF, matching the measured clean-content SSIMU2 slope (~0.9-1.0).

func (MetricKind) ScoreScale 

func (k MetricKind) ScoreScale() float32

ScoreScale converts the calibrated CVVDP/JOD search constants into the metric's units: 1 for CVVDP, 37.5 for SSIMU2 (the measured pts/JOD exchange rate). Every score-denominated search constant multiplies by this so the search behaves identically in perceptual terms regardless of probe metric.

func (MetricKind) SlopeClamp 

func (k MetricKind) SlopeClamp() (min, max float32)

SlopeClamp bounds measured probe slopes admitted into the learned-slope median, rejecting noise-dominated pairs: the original calibrated 0.005-0.2 JOD/CRF window in the metric's units.

type Probe 

type Probe struct {
	CRF           float32 `json:"crf"`
	Score         float32 `json:"score"`
	Size          uint64  `json:"size"`
	PeakBps       float64 `json:"peak_bps,omitempty"`
	EncodeSeconds float64 `json:"encode_seconds,omitempty"`
	MetricSeconds float64 `json:"metric_seconds,omitempty"`
	Frames        int     `json:"frames,omitempty"`
}

Probe records one target-quality probe encode and its whole-chunk metric result. Every probe encodes and scores the entire chunk, so Score is exact for the selected metric and the probe IVF can be reused verbatim as the final chunk. The old sampled worst-window proxy was removed because it was systematically pessimistic and over-encoded; see docs/PERFORMANCE_TESTING.md.

type SSIMU2Options 

type SSIMU2Options struct {
	SourcePath string
	ProbePath  string
	Info       *video.Info
	Chunk      chunk.Chunk
	CropRect   *video.CropRect
	Width      uint32
	Height     uint32
	Denoise    string // Experimental libavfilter graph applied to reference frames
	// Reference optionally supplies the chunk's reference frames already
	// decoded, cropped, and denoise-filtered; see CVVDPOptions.Reference.
	Reference video.FrameReader
	Processor *SSIMU2Processor
}

type SSIMU2Processor 

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

SSIMU2Processor is a SSIMU2 scorer backed by VSHIP. Unlike CVVDP, SSIMU2 is stateless per frame pair, so there is no Reset method.

func NewSSIMU2Processor 

func NewSSIMU2Processor(width, height uint32, inf *video.Info) (*SSIMU2Processor, error)

func (*SSIMU2Processor) Close 

func (p *SSIMU2Processor) Close() error

func (*SSIMU2Processor) ComputeSSIMU2 

func (p *SSIMU2Processor) ComputeSSIMU2(src, dist FramePlanes) (float64, error)

type SSIMU2Result 

type SSIMU2Result struct {
	PerFrame      []float64
	Frames        int
	MetricSeconds float64
	Mean          float64
	Min           float64
	P5            float64
	P10           float64
}

func ComputeChunkSSIMU2 

func ComputeChunkSSIMU2(ctx context.Context, opts SSIMU2Options) (SSIMU2Result, error)

ComputeChunkSSIMU2 mirrors ComputeChunkCVVDP's decode-producer/GPU-consumer pipeline (see cvvdp.go): decode runs on a producer goroutine so CPU frame decode overlaps GPU metric compute, with two buffer pairs rotating between producer and consumer, and all GPU calls on this goroutine. Unlike CVVDP, SSIMU2 is stateless per frame pair -- there is no handler Reset and no running accumulation -- so this collects a per-frame score slice instead of a single final score.

type SearchContext 

type SearchContext struct {
	Metric     MetricKind // zero value means CVVDP
	Target     float32
	Tolerance  float32
	CRFMin     float32
	CRFMax     float32
	MaxProbes  int
	InitialCRF float32
	JODPerCRF  float32 // score units per CRF step
	MaxRateBps float64 // bitstream cap; probes exceeding it cannot be selected (0 disables)
	FPS        float64 // frames per second, used to compute probe bitrate
}

SearchContext configures per-chunk target-quality search. Target, Tolerance, and JODPerCRF are denominated in the probe metric's units (CVVDP JOD or SSIMU2 points; Metric's ScoreScale converts the calibrated JOD constants).

type SearchState 

type SearchState struct {
	Probes     []Probe    `json:"probes"`
	SearchMin  float32    `json:"search_min"`
	SearchMax  float32    `json:"search_max"`
	Round      int        `json:"round"`
	StopReason StopReason `json:"stop_reason,omitempty"`
	// contains filtered or unexported fields
}

SearchState tracks target-quality search for one chunk.

func NewSearchState 

func NewSearchState(ctx SearchContext) *SearchState

func (*SearchState) AddProbe 

func (s *SearchState) AddProbe(ctx SearchContext, probe Probe)

func (*SearchState) BestProbe 

func (s *SearchState) BestProbe(ctx SearchContext) (Probe, bool)

func (*SearchState) NextCRF 

func (s *SearchState) NextCRF(ctx SearchContext) (float32, bool)

type StopReason 

type StopReason string
const (
	StopNone          StopReason = ""
	StopConverged     StopReason = "converged"
	StopBoundsCrossed StopReason = "bounds_crossed"
	StopMonotonicity  StopReason = "monotonicity_guard"
	StopMaxProbes     StopReason = "max_probes"
	StopNoCandidates  StopReason = "no_candidates"
	// StopRateCapped: the bitstream cap bounded the search from below and no
	// rate-legal probe reached the band. Intended behavior on chunks where
	// the cap binds (heavy grain), not a search failure; see capFrontierCRF.
	StopRateCapped StopReason = "rate_capped"
)

type VshipProcessor 

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

func NewVshipProcessor 

func NewVshipProcessor(width, height uint32, inf *video.Info, displayPath string) (*VshipProcessor, error)

func (*VshipProcessor) Close 

func (p *VshipProcessor) Close() error

func (*VshipProcessor) ComputeCVVDP 

func (p *VshipProcessor) ComputeCVVDP(src, dist FramePlanes) (float32, error)

func (*VshipProcessor) ResetCVVDP 

func (p *VshipProcessor) ResetCVVDP() error

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.