haeaeae/silo-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2dedf3ff26e488dce37d5ef81d7cdce2d9ec80e5
silo-server/internal/playback/protocol_v3.go
T
CoffeeKnyteandQuick 9281ae61d9 fix(playback): transcode H.264 sources with conflicting in-band PPS 
H.264 streams that redefine the same pic_parameter_set_id in-band with
different content cannot be safely stream-copied into an avc1/fMP4 HLS
segment: the avcC advertises a single parameter set, so VideoToolbox
(Safari/Chrome on macOS) decodes with the wrong PPS and desyncs mid-GOP,
surfacing as PIPELINE_ERROR_DECODE / kVTVideoDecoderBadDataErr (-12909).

At playback start, a bitstream scan (DetectMultiplePPSH264) runs for H.264
files on the probe-ensure path, grouping in-band PPS by id and flagging any
id carrying more than one distinct definition. The result is a runtime-only
flag (VideoTrack.MultiplePPS, json:"-") memoized per process — never written
to the database, no schema change, recomputed on the first play after a
restart.

The v3 planner and legacy resolver disqualify a copy-unsafe source from the
video stream-copy / remux ladder, routing it to a real transcode. Direct
play of the original container is left intact: decoders that reparse in-band
parameter sets (ExoPlayer, VLC, native) handle the source fine.

Part of #135.
2026-07-29 09:49:34 -04:00

865 lines
36 KiB
Go
Raw Blame History

package playback
import (
"errors"
"fmt"
"math"
"regexp"
"slices"
"strings"
"time"
)
const (
ProtocolV3 = 3
FeaturePlaybackPlanV3 = "playback_plan_v3"
FeatureMedia3Only = "media3_only"
FeatureDetailedDecodeV3 = "detailed_decode_capabilities"
FeatureLayoutPassthrough = "layout_aware_passthrough"
FeatureClientVideoTransforms = "client_video_transformations_v1"
FeatureRouteDiagnostics = "playback_route_diagnostics"
FeatureDeviceQuirksV3 = "device_quirks_v1"
FeatureSeekReanchorV3 = "seek_reanchor_v1"
FeatureDirectStreamResumeV3 = "direct_stream_resume_v1"
FeaturePlanSourceDurationV3 = "plan_source_duration_v1"
PlanRecipeVersionV3 = "v3.2"
ClientDV7ToDV81V3 = "client_dv7_to_dv81"
ClientDV7ToHDR10V3 = "client_dv7_to_hdr10"
ClientDVTransformVersionV3 = "1"
ClientDV8HDR10PlusSanitizerV3 = "client_dv8_hdr10plus_sanitizer_v1"
ClientPostResumeRecoveryV3 = "client_post_resume_video_recovery_v1"
ClientSurfaceRecoveryV3 = "client_surface_recovery_v1"
DeviceQuirkRegistryRevisionV3 = "2026-07-13.1"
)
// ServerFeaturesV3 returns the complete feature set advertised by protocol-v3
// capability and decision responses. A fresh slice prevents callers from
// mutating the shared contract.
func ServerFeaturesV3() []string {
return []string{
FeaturePlaybackPlanV3,
FeatureMedia3Only,
FeatureDetailedDecodeV3,
FeatureLayoutPassthrough,
FeatureRouteDiagnostics,
FeatureDeviceQuirksV3,
FeatureSeekReanchorV3,
FeatureDirectStreamResumeV3,
// Advertised so a client can tell "this server does not populate
// source.duration_seconds" apart from "this server knows the runtime
// is genuinely unknown". Without the distinction both look like an
// absent field, and a client cannot decide whether its own catalog
// fallback is still required.
FeaturePlanSourceDurationV3,
}
}
type DecisionOutcomeV3 string
const (
OutcomePlayableV3 DecisionOutcomeV3 = "playable"
OutcomeAdaptationUnavailableV3 DecisionOutcomeV3 = "adaptation_unavailable"
)
type DeliveryV3 string
const (
DeliveryOriginalHTTPV3 DeliveryV3 = "original_http"
DeliveryRemuxHLSV3 DeliveryV3 = "server_remux_hls"
DeliveryRemuxProgressiveV3 DeliveryV3 = "server_remux_progressive"
DeliveryTranscodeHLSV3 DeliveryV3 = "server_transcode_hls"
)
func (d DeliveryV3) KotlinName() string {
switch d {
case DeliveryOriginalHTTPV3:
return "ORIGINAL_HTTP"
case DeliveryRemuxHLSV3:
return "SERVER_REMUX_HLS"
case DeliveryRemuxProgressiveV3:
return "SERVER_REMUX_PROGRESSIVE"
case DeliveryTranscodeHLSV3:
return "SERVER_TRANSCODE_HLS"
default:
return strings.ToUpper(string(d))
}
}
type EngineV3 string
const (
EngineMedia3DirectV3 EngineV3 = "media3_direct"
EngineMedia3ProgressiveRemuxV3 EngineV3 = "media3_progressive_remux"
EngineMedia3HLSV3 EngineV3 = "media3_hls"
)
type StreamProtocolV3 string
const (
StreamHTTPProgressiveV3 StreamProtocolV3 = "http_progressive"
StreamHLSV3 StreamProtocolV3 = "hls"
)
func (p StreamProtocolV3) KotlinName() string {
switch p {
case StreamHTTPProgressiveV3:
return "HTTP_PROGRESSIVE"
case StreamHLSV3:
return "HLS"
default:
return strings.ToUpper(string(p))
}
}
type HeaderRefreshModeV3 string
const (
HeaderRefreshNoneV3 HeaderRefreshModeV3 = "none"
HeaderRefreshSessionV3 HeaderRefreshModeV3 = "session"
)
type SubtitleModeV3 string
const (
SubtitleOffV3 SubtitleModeV3 = "off"
SubtitleRenderV3 SubtitleModeV3 = "render"
SubtitleConvertV3 SubtitleModeV3 = "convert"
SubtitleBurnInV3 SubtitleModeV3 = "burn_in"
)
func (m SubtitleModeV3) KotlinName() string {
switch m {
case SubtitleOffV3:
return "OFF"
case SubtitleRenderV3:
return "RENDER"
case SubtitleConvertV3:
return "CONVERT"
case SubtitleBurnInV3:
return "BURN_IN"
default:
return strings.ToUpper(string(m))
}
}
type SubtitleFidelityV3 string
const (
SubtitleFidelityPreserveV3 SubtitleFidelityV3 = "preserve"
SubtitleFidelityCompatibleV3 SubtitleFidelityV3 = "compatible"
)
type EnhancementLayerV3 string
const (
EnhancementNoneV3 EnhancementLayerV3 = "none"
EnhancementMELV3 EnhancementLayerV3 = "mel"
EnhancementFELV3 EnhancementLayerV3 = "fel"
EnhancementUnknownV3 EnhancementLayerV3 = "unknown"
)
type HDRCapabilitiesV3 struct {
HDR10 bool `json:"hdr10"`
HDR10Plus bool `json:"hdr10_plus"`
HLG bool `json:"hlg"`
DolbyVisionProfiles []int `json:"dolby_vision_profiles"`
}
type AudioPassthroughV3 struct {
PassthroughCodecs []string `json:"passthrough_codecs"`
SpatializerEnabled bool `json:"spatializer_enabled"`
MaxChannels int `json:"max_channels"`
Entries []AudioPassthroughEntryV3 `json:"entries,omitempty"`
}
type AudioPassthroughEntryV3 struct {
Codec string `json:"codec"`
ChannelCounts []int `json:"channel_counts,omitempty"`
Layouts []string `json:"layouts,omitempty"`
}
type VideoDecodeCapabilityV3 struct {
Codec string `json:"codec"`
DecoderName string `json:"decoder_name,omitempty"`
Profiles []string `json:"profiles,omitempty"`
Levels []int `json:"levels,omitempty"`
BitDepths []int `json:"bit_depths,omitempty"`
MaxWidth int `json:"max_width,omitempty"`
MaxHeight int `json:"max_height,omitempty"`
MaxFrameRate float64 `json:"max_frame_rate,omitempty"`
MaxBitrateKbps int `json:"max_bitrate_kbps,omitempty"`
Hardware bool `json:"hardware"`
}
type ClientCodecCapabilitiesV3 struct {
CodecsVideo []string `json:"codecs_video"`
CodecsVideoHardware []string `json:"codecs_video_hardware"`
CodecsAudio []string `json:"codecs_audio"`
Containers []string `json:"containers"`
MaxResolution string `json:"max_resolution,omitempty"`
HDR bool `json:"hdr"`
HDRDetails *HDRCapabilitiesV3 `json:"hdr_details,omitempty"`
AudioPassthrough *AudioPassthroughV3 `json:"audio_passthrough,omitempty"`
VideoDecode []VideoDecodeCapabilityV3 `json:"video_decode,omitempty"`
}
type DeviceContextV3 struct {
Manufacturer string `json:"manufacturer,omitempty"`
Model string `json:"model,omitempty"`
Brand string `json:"brand,omitempty"`
Device string `json:"device,omitempty"`
Product string `json:"product,omitempty"`
SoCManufacturer string `json:"soc_manufacturer,omitempty"`
SoCModel string `json:"soc_model,omitempty"`
BuildID string `json:"build_id,omitempty"`
BuildDisplay string `json:"build_display,omitempty"`
SecurityPatch string `json:"security_patch,omitempty"`
SDKInt int `json:"sdk_int,omitempty"`
ABIs []string `json:"abis,omitempty"`
}
type OutputContextV3 struct {
HDRDetails *HDRCapabilitiesV3 `json:"hdr_details,omitempty"`
AudioPassthrough *AudioPassthroughV3 `json:"audio_passthrough,omitempty"`
CurrentSink string `json:"current_sink,omitempty"`
SinkType string `json:"sink_type,omitempty"`
OutputRouteGeneration int64 `json:"output_route_generation"`
}
type EngineSubtitleCapabilitiesV3 struct {
EmbeddedText bool `json:"embedded_text"`
SidecarText bool `json:"sidecar_text"`
ASSStyling bool `json:"ass_styling"`
EmbeddedBitmap bool `json:"embedded_bitmap"`
SidecarBitmap bool `json:"sidecar_bitmap"`
FontAttachments bool `json:"font_attachments"`
}
type EngineCapabilityV3 struct {
Enabled bool `json:"enabled"`
SupportedOnDevice bool `json:"supported_on_device"`
FailureReason string `json:"failure_reason,omitempty"`
Containers []string `json:"containers"`
VideoCodecs []string `json:"video_codecs"`
AudioDecodeCodecs []string `json:"audio_decode_codecs"`
AudioPassthroughCodecs []string `json:"audio_passthrough_codecs"`
MaxChannels *int `json:"max_channels,omitempty"`
HDRDetails *HDRCapabilitiesV3 `json:"hdr_details,omitempty"`
Subtitles EngineSubtitleCapabilitiesV3 `json:"subtitles"`
Features []string `json:"features"`
AuthHeaderRefresh bool `json:"auth_header_refresh"`
ValidatedClaims []string `json:"validated_claims"`
Transformations []TransformationV3 `json:"transformations"`
}
type ClientPlaybackContextV3 struct {
ProtocolVersion int `json:"protocol_version"`
Features []string `json:"features"`
Platform string `json:"platform"`
FormFactor string `json:"form_factor"`
AppVersion string `json:"app_version"`
Device DeviceContextV3 `json:"device"`
Output OutputContextV3 `json:"output"`
Engines map[string]EngineCapabilityV3 `json:"engines"`
}
type StartRequestV3 struct {
ProtocolVersion int `json:"protocol_version"`
ClientFeatures []string `json:"client_features"`
FileID int `json:"file_id"`
ProfileID string `json:"profile_id"`
PlaybackAttemptID string `json:"playback_attempt_id"`
QualityPreference string `json:"quality_preference"`
SubtitleFidelityPreference SubtitleFidelityV3 `json:"subtitle_fidelity_preference"`
StartPosition *float64 `json:"start_position,omitempty"`
AudioTrackID string `json:"audio_track_id,omitempty"`
AudioTrackIndex *int `json:"audio_track_index,omitempty"`
SubtitleTrackID string `json:"subtitle_track_id,omitempty"`
SubtitleTrackIndex *int `json:"subtitle_track_index,omitempty"`
OutputRouteGeneration int64 `json:"output_route_generation"`
Metered bool `json:"metered"`
BandwidthEstimateKbps *int `json:"bandwidth_estimate_kbps,omitempty"`
BandwidthCapKbps *int `json:"bandwidth_cap_kbps,omitempty"`
Capabilities ClientCodecCapabilitiesV3 `json:"client_capabilities"`
ClientPlaybackContext ClientPlaybackContextV3 `json:"client_playback_context"`
}
type TrackIdentityV3 struct {
ID string `json:"id"`
Index *int `json:"index,omitempty"`
}
type SelectedTracksV3 struct {
Audio *TrackIdentityV3 `json:"audio,omitempty"`
Subtitle *TrackIdentityV3 `json:"subtitle,omitempty"`
}
type FailureV3 struct {
Classification string `json:"classification"`
Message string `json:"message,omitempty"`
DecoderName string `json:"decoder_name,omitempty"`
}
type ReplanOperationV3 string
const (
ReplanOperationFailureRecoveryV3 ReplanOperationV3 = "failure_recovery"
ReplanOperationSeekReanchorV3 ReplanOperationV3 = "seek_reanchor"
ReplanOperationSeekFailureRecoveryV3 ReplanOperationV3 = "seek_failure_recovery"
)
type ReplanRequestV3 struct {
ProtocolVersion int `json:"protocol_version"`
Operation ReplanOperationV3 `json:"operation,omitempty"`
PlaybackAttemptID string `json:"playback_attempt_id"`
ReplanRequestID string `json:"replan_request_id"`
FailedPlanID string `json:"failed_plan_id"`
PlanAttemptID string `json:"plan_attempt_id"`
PlanAttemptKey string `json:"plan_attempt_key"`
AttemptedPlanKeys []string `json:"attempted_plan_keys"`
AttemptCount int `json:"attempt_count"`
QualityPreference string `json:"quality_preference"`
PositionSeconds float64 `json:"position_seconds"`
OutputRouteGeneration int64 `json:"output_route_generation"`
Metered bool `json:"metered"`
BandwidthEstimateKbps *int `json:"bandwidth_estimate_kbps,omitempty"`
BandwidthCapKbps *int `json:"bandwidth_cap_kbps,omitempty"`
SelectedTracks SelectedTracksV3 `json:"selected_tracks"`
Failure FailureV3 `json:"failure"`
Capabilities ClientCodecCapabilitiesV3 `json:"client_capabilities"`
ClientPlaybackContext ClientPlaybackContextV3 `json:"client_playback_context"`
}
const (
RouteEventPlanSelectedV3 = "plan_selected"
RouteEventPlanInvalidatedV3 = "plan_invalidated"
RouteEventPlanFailedV3 = "plan_failed"
RouteEventFirstFrameV3 = "first_frame"
RouteEventTerminalV3 = "terminal"
RouteEventStoppedV3 = "stopped"
RouteEventRuntimeCorrectionAppliedV3 = "runtime_correction_applied"
RouteEventRuntimeCorrectionSucceededV3 = "runtime_correction_succeeded"
RouteEventRuntimeCorrectionFailedV3 = "runtime_correction_failed"
RouteEventSeekReanchorRequestedV3 = "seek_reanchor_requested"
RouteEventSeekReanchoredV3 = "seek_reanchored"
)
var routeEventNamesV3 = []string{
RouteEventPlanSelectedV3,
RouteEventPlanInvalidatedV3,
RouteEventPlanFailedV3,
RouteEventFirstFrameV3,
RouteEventTerminalV3,
RouteEventStoppedV3,
RouteEventRuntimeCorrectionAppliedV3,
RouteEventRuntimeCorrectionSucceededV3,
RouteEventRuntimeCorrectionFailedV3,
RouteEventSeekReanchorRequestedV3,
RouteEventSeekReanchoredV3,
}
// RouteEventNamesV3 returns the complete protocol-v3 telemetry event contract.
func RouteEventNamesV3() []string {
return append([]string(nil), routeEventNamesV3...)
}
// ValidRouteEventNameV3 reports whether name is part of the protocol-v3
// telemetry contract shared by handlers, persistence, and clients.
func ValidRouteEventNameV3(name string) bool {
return slices.Contains(routeEventNamesV3, name)
}
// EffectiveOperation keeps clients which predate the explicit operation field
// on the ordinary failure-recovery path. Seek operations are deliberately
// opt-in because both pin the current media version and user intent; an exact
// reanchor also preserves the current route instead of walking the ladder.
func (r ReplanRequestV3) EffectiveOperation() ReplanOperationV3 {
if r.Operation == "" {
return ReplanOperationFailureRecoveryV3
}
return r.Operation
}
type RouteEventV3 struct {
ProtocolVersion int `json:"protocol_version"`
PlaybackAttemptID string `json:"playback_attempt_id"`
SessionID string `json:"session_id,omitempty"`
PlanID string `json:"plan_id,omitempty"`
PlanAttemptID string `json:"plan_attempt_id,omitempty"`
PlanAttemptKey string `json:"plan_attempt_key,omitempty"`
Event string `json:"event"`
FailureClassification string `json:"failure_classification,omitempty"`
FallbackReason string `json:"fallback_reason,omitempty"`
AppliedQuirkIDs []string `json:"applied_quirk_ids,omitempty"`
QuirkRegistryRevision string `json:"quirk_registry_revision,omitempty"`
OutputRouteGeneration int64 `json:"output_route_generation"`
Diagnostics map[string]string `json:"diagnostics"`
}
type StreamV3 struct {
URL string `json:"url"`
Protocol StreamProtocolV3 `json:"protocol"`
Container string `json:"container,omitempty"`
MIMEType string `json:"mime_type,omitempty"`
Headers map[string]string `json:"headers"`
HeaderRefresh HeaderRefreshModeV3 `json:"header_refresh"`
HeaderRefreshURL string `json:"header_refresh_url,omitempty"`
}
type TimelineV3 struct {
SourceStartSeconds float64 `json:"source_start_seconds"`
StreamOriginSeconds float64 `json:"stream_origin_seconds"`
PlayerStartSeconds float64 `json:"player_start_seconds"`
TimelineOffsetSeconds float64 `json:"timeline_offset_seconds"`
SeekWindowStartSeconds *float64 `json:"seek_window_start_seconds,omitempty"`
SeekWindowEndSeconds *float64 `json:"seek_window_end_seconds,omitempty"`
CanSeekAnywhere bool `json:"can_seek_anywhere"`
SeekRestoration string `json:"seek_restoration"`
}
type EffectiveRecipeV3 struct {
VideoCodec string `json:"video_codec,omitempty"`
AudioCodec string `json:"audio_codec,omitempty"`
Width *int `json:"width,omitempty"`
Height *int `json:"height,omitempty"`
FrameRate *float64 `json:"frame_rate,omitempty"`
BitrateKbps *int `json:"bitrate_kbps,omitempty"`
DynamicRange string `json:"dynamic_range,omitempty"`
AudioChannels *int `json:"audio_channels,omitempty"`
AudioLayout string `json:"audio_layout,omitempty"`
}
type SourceDescriptorV3 struct {
MediaFileID int `json:"media_file_id"`
// DurationSeconds is the full runtime of this source, independent of where
// the delivery's timeline is anchored: never `total - source_start`, and
// never adjusted by timeline_offset_seconds.
//
// Absent means the server does not know the runtime. It is omitted rather
// than sent as null: clients that coerce null to a numeric default would
// read it as zero, which is the value this field exists to stop them
// inventing. A client must not substitute the playback engine's reported
// duration for it — on an HLS copy remux the engine reports the length
// produced so far, not the runtime.
DurationSeconds *float64 `json:"duration_seconds,omitempty"`
Container string `json:"container,omitempty"`
VideoCodec string `json:"video_codec,omitempty"`
VideoProfile string `json:"video_profile,omitempty"`
VideoLevel int `json:"video_level,omitempty"`
BitDepth int `json:"bit_depth,omitempty"`
ColorRange string `json:"color_range,omitempty"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
FrameRate float64 `json:"frame_rate,omitempty"`
BitrateKbps int `json:"bitrate_kbps,omitempty"`
DynamicRange string `json:"dynamic_range,omitempty"`
HDR10Plus bool `json:"hdr10_plus"`
DVProfile int `json:"dolby_vision_profile,omitempty"`
DVBLCompatID int `json:"dv_bl_compat_id,omitempty"`
DVEnhancementLayer EnhancementLayerV3 `json:"dv_enhancement_layer"`
AudioCodec string `json:"audio_codec,omitempty"`
AudioChannels int `json:"audio_channels,omitempty"`
AudioLayout string `json:"audio_layout,omitempty"`
// VideoCopyUnsafe marks a source whose video stream cannot be safely
// stream-copied into an avc1/fMP4 segment (H.264 with conflicting in-band
// PPS). Copy/remux routes are disqualified for it; a real encode is used.
VideoCopyUnsafe bool `json:"video_copy_unsafe,omitempty"`
}
type VideoClaimsV3 struct {
HDR10 bool `json:"hdr10"`
HDR10Plus bool `json:"hdr10_plus"`
HLG bool `json:"hlg"`
DolbyVision bool `json:"dolby_vision"`
DolbyVisionReason string `json:"dolby_vision_reason,omitempty"`
}
type AudioClaimsV3 struct {
Codec string `json:"codec,omitempty"`
Passthrough bool `json:"passthrough"`
AtmosPreserved bool `json:"atmos_preserved"`
DTSVariant string `json:"dts_variant,omitempty"`
Reason string `json:"reason,omitempty"`
}
type SubtitleClaimsV3 struct {
ASSStylingPreserved bool `json:"ass_styling_preserved"`
BitmapOverlay bool `json:"bitmap_overlay"`
BitmapSidecar bool `json:"bitmap_sidecar"`
Reason string `json:"reason,omitempty"`
}
type ValidationClaimsV3 struct {
Video VideoClaimsV3 `json:"video"`
Audio AudioClaimsV3 `json:"audio"`
Subtitles SubtitleClaimsV3 `json:"subtitles"`
}
type SubtitleArtifactV3 struct {
URL string `json:"url"`
MIMEType string `json:"mime_type"`
Format string `json:"format"`
TimingOriginSeconds float64 `json:"timing_origin_seconds"`
}
type SubtitleDecisionV3 struct {
Mode SubtitleModeV3 `json:"mode"`
TrackID string `json:"track_id,omitempty"`
Artifact *SubtitleArtifactV3 `json:"artifact,omitempty"`
}
type TransformationV3 struct {
Name string `json:"name"`
Executor string `json:"executor"`
RecipeVersion string `json:"recipe_version"`
ValidatedClaims []string `json:"validated_claims"`
}
type AppliedQuirkV3 struct {
ID string `json:"id"`
RegistryRevision string `json:"registry_revision"`
Action string `json:"action"`
Reason string `json:"reason,omitempty"`
}
type DegradationWarningV3 struct {
Code string `json:"code"`
Message string `json:"message"`
}
type PlanV3 struct {
ProtocolVersion int `json:"protocol_version"`
PlanID string `json:"plan_id"`
SessionID string `json:"session_id,omitempty"`
ExpiresAt string `json:"expires_at,omitempty"`
Delivery DeliveryV3 `json:"delivery"`
Engine EngineV3 `json:"engine"`
Stream StreamV3 `json:"stream"`
Timeline TimelineV3 `json:"timeline"`
SelectedTracks SelectedTracksV3 `json:"selected_tracks"`
EffectiveRecipe EffectiveRecipeV3 `json:"effective_recipe"`
Claims ValidationClaimsV3 `json:"claims"`
Subtitle SubtitleDecisionV3 `json:"subtitle"`
Transformations []TransformationV3 `json:"transformations"`
AppliedQuirks []AppliedQuirkV3 `json:"applied_quirks"`
RuntimeCorrections []string `json:"runtime_corrections"`
DegradationWarnings []DegradationWarningV3 `json:"degradation_warnings"`
DecisionReason string `json:"decision_reason"`
RequestedMediaFileID int `json:"requested_media_file_id"`
EffectiveMediaFileID int `json:"effective_media_file_id"`
Source SourceDescriptorV3 `json:"source"`
SubtitleFidelityPolicy string `json:"subtitle_fidelity_policy"`
}
type TerminalV3 struct {
Reason string `json:"reason"`
Message string `json:"message"`
Retryable bool `json:"retryable"`
}
type DecisionResponseV3 struct {
ProtocolVersion int `json:"protocol_version,omitempty"`
ServerFeatures []string `json:"server_features"`
Outcome DecisionOutcomeV3 `json:"outcome,omitempty"`
SessionID string `json:"session_id,omitempty"`
PlaybackPlan *PlanV3 `json:"playback_plan,omitempty"`
Terminal *TerminalV3 `json:"terminal,omitempty"`
}
type CapabilityResponseV3 struct {
Enabled bool `json:"enabled"`
ProtocolVersions []int `json:"protocol_versions"`
Features []string `json:"features"`
Deliveries []DeliveryV3 `json:"deliveries"`
Transformations []TransformationV3 `json:"transformations"`
Reason string `json:"reason,omitempty"`
}
var boundedIdentifierV3 = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$`)
func (r *StartRequestV3) NormalizeAndValidate() ([]DegradationWarningV3, error) {
if r.ProtocolVersion != ProtocolV3 {
return nil, fmt.Errorf("protocol_version must be %d", ProtocolV3)
}
if r.FileID <= 0 || strings.TrimSpace(r.ProfileID) == "" {
return nil, errors.New("file_id and profile_id are required")
}
if !boundedIdentifierV3.MatchString(r.PlaybackAttemptID) {
return nil, errors.New("playback_attempt_id is invalid")
}
if r.OutputRouteGeneration < 0 || r.ClientPlaybackContext.Output.OutputRouteGeneration != r.OutputRouteGeneration {
return nil, errors.New("output_route_generation is invalid or inconsistent")
}
if r.ClientPlaybackContext.ProtocolVersion != ProtocolV3 {
return nil, errors.New("client_playback_context.protocol_version must be 3")
}
if r.StartPosition != nil && (!isFiniteV3(*r.StartPosition) || *r.StartPosition < 0 || *r.StartPosition > 31_536_000) {
return nil, errors.New("start_position is outside the supported range")
}
if err := validateOptionalBoundedIntV3(r.BandwidthEstimateKbps, 100, 1_000_000, "bandwidth_estimate_kbps"); err != nil {
return nil, err
}
if err := validateOptionalBoundedIntV3(r.BandwidthCapKbps, 100, 1_000_000, "bandwidth_cap_kbps"); err != nil {
return nil, err
}
if r.SubtitleFidelityPreference != SubtitleFidelityPreserveV3 && r.SubtitleFidelityPreference != SubtitleFidelityCompatibleV3 {
return nil, errors.New("subtitle_fidelity_preference is invalid")
}
if len(r.ClientFeatures) > 64 {
return nil, errors.New("client_features exceeds supported size")
}
for _, feature := range r.ClientFeatures {
if len(feature) > 128 {
return nil, errors.New("client feature exceeds supported size")
}
}
if err := validateCapabilitiesV3(&r.Capabilities, &r.ClientPlaybackContext, r.ClientFeatures); err != nil {
return nil, err
}
if err := validateTrackPairV3(r.FileID, "audio", r.AudioTrackID, r.AudioTrackIndex); err != nil {
return nil, err
}
if err := validateTrackPairV3(r.FileID, "subtitle", r.SubtitleTrackID, r.SubtitleTrackIndex); err != nil {
return nil, err
}
quality, changed := NormalizeQualityV3(r.QualityPreference)
r.QualityPreference = quality
if changed {
return []DegradationWarningV3{{Code: "quality_preference_normalized", Message: "Unknown quality preference was normalized to auto."}}, nil
}
return nil, nil
}
func NormalizeQualityV3(value string) (string, bool) {
switch strings.ToLower(strings.TrimSpace(value)) {
case "", "auto":
return "auto", false
case "original", "source", "max":
return "original", false
case "2160p", "4k", "uhd":
return "2160p", false
case "1080p", "fhd":
return "1080p", false
case "720p", "hd":
return "720p", false
case "480p", "sd":
return "480p", false
default:
return "auto", true
}
}
func (r ReplanRequestV3) Validate() error {
if r.ProtocolVersion != ProtocolV3 || !boundedIdentifierV3.MatchString(r.PlaybackAttemptID) || !boundedIdentifierV3.MatchString(r.ReplanRequestID) {
return errors.New("invalid replan identity")
}
if len(r.FailedPlanID) < 8 || len(r.FailedPlanID) > 128 || len(r.PlanAttemptID) < 8 || len(r.PlanAttemptID) > 128 || len(r.PlanAttemptKey) < 8 || len(r.PlanAttemptKey) > 128 || !strings.HasPrefix(r.PlanAttemptKey, "v3:") || r.AttemptCount < 1 || r.AttemptCount > 8 {
return errors.New("invalid replan attempt")
}
if r.OutputRouteGeneration < 0 || r.ClientPlaybackContext.Output.OutputRouteGeneration != r.OutputRouteGeneration {
return errors.New("invalid output route generation")
}
if len(r.AttemptedPlanKeys) > 16 || len(r.Failure.Classification) > 64 || len(r.Failure.Message) > 512 || len(r.Failure.DecoderName) > 128 || !isFiniteV3(r.PositionSeconds) || r.PositionSeconds < 0 || r.PositionSeconds > 31_536_000 {
return errors.New("replan bounds exceeded")
}
if err := validateOptionalBoundedIntV3(r.BandwidthEstimateKbps, 100, 1_000_000, "bandwidth_estimate_kbps"); err != nil {
return err
}
if err := validateOptionalBoundedIntV3(r.BandwidthCapKbps, 100, 1_000_000, "bandwidth_cap_kbps"); err != nil {
return err
}
if err := validateSelectedTrackIdentityV3("audio", r.SelectedTracks.Audio); err != nil {
return err
}
if err := validateSelectedTrackIdentityV3("subtitle", r.SelectedTracks.Subtitle); err != nil {
return err
}
switch r.EffectiveOperation() {
case ReplanOperationFailureRecoveryV3, ReplanOperationSeekFailureRecoveryV3:
if r.Failure.Classification == "" {
return errors.New("failure recovery requires a failure classification")
}
case ReplanOperationSeekReanchorV3:
// An exact seek reanchor is a timeline operation, not a failed recipe.
// Classification remains accepted for older callers but is not required
// and never selects seek semantics.
default:
return errors.New("invalid replan operation")
}
for _, key := range r.AttemptedPlanKeys {
if len(key) > 128 || !strings.HasPrefix(key, "v3:") {
return errors.New("invalid attempted plan key")
}
}
return validateCapabilitiesV3(&r.Capabilities, &r.ClientPlaybackContext, nil)
}
func validateSelectedTrackIdentityV3(kind string, track *TrackIdentityV3) error {
if track == nil {
return nil
}
if len(track.ID) > 128 {
return fmt.Errorf("%s track id exceeds supported size", kind)
}
if track.Index != nil && (*track.Index < 0 || *track.Index > 10_000) {
return fmt.Errorf("%s track index is invalid", kind)
}
return nil
}
// validateCapabilitiesV3 validates and normalizes the shared capability
// payload. topLevelFeatures carries the request's client_features when the
// request type has one (replans do not); feature checks accept either
// location, matching the planner's dual-source reads.
func validateCapabilitiesV3(c *ClientCodecCapabilitiesV3, ctx *ClientPlaybackContextV3, topLevelFeatures []string) error {
if len(c.CodecsVideo) > 64 || len(c.CodecsVideoHardware) > 64 || len(c.CodecsAudio) > 64 || len(c.Containers) > 64 || len(c.VideoDecode) > 64 || len(ctx.Features) > 64 || len(ctx.Engines) > 16 || len(ctx.Device.ABIs) > 16 || len(ctx.Platform) > 32 || len(ctx.FormFactor) > 32 || len(ctx.AppVersion) > 64 {
return errors.New("capability list exceeds supported size")
}
deviceValues := []string{
ctx.Device.Manufacturer, ctx.Device.Model, ctx.Device.Brand, ctx.Device.Device,
ctx.Device.Product, ctx.Device.SoCManufacturer, ctx.Device.SoCModel, ctx.Device.BuildID,
ctx.Device.BuildDisplay, ctx.Device.SecurityPatch, ctx.Output.CurrentSink, ctx.Output.SinkType,
}
for _, value := range deviceValues {
if len(value) > 128 {
return errors.New("device capability value exceeds supported size")
}
}
for _, values := range [][]string{c.CodecsVideo, c.CodecsVideoHardware, c.CodecsAudio, c.Containers, ctx.Features} {
for i := range values {
values[i] = strings.ToLower(strings.TrimSpace(values[i]))
if len(values[i]) > 128 {
return errors.New("capability value exceeds supported size")
}
}
}
for i := range c.VideoDecode {
c.VideoDecode[i].Codec = strings.ToLower(strings.TrimSpace(c.VideoDecode[i].Codec))
if c.VideoDecode[i].Codec == "" || len(c.VideoDecode[i].DecoderName) > 128 || c.VideoDecode[i].MaxWidth < 0 || c.VideoDecode[i].MaxHeight < 0 || c.VideoDecode[i].MaxFrameRate < 0 || c.VideoDecode[i].MaxBitrateKbps < 0 {
return errors.New("invalid detailed video capability")
}
if len(c.VideoDecode[i].Profiles) > 64 || len(c.VideoDecode[i].Levels) > 64 || len(c.VideoDecode[i].BitDepths) > 64 {
return errors.New("detailed video capability exceeds supported size")
}
for _, profile := range c.VideoDecode[i].Profiles {
if len(profile) > 64 {
return errors.New("detailed video capability value exceeds supported size")
}
}
}
for _, hdr := range []*HDRCapabilitiesV3{c.HDRDetails, ctx.Output.HDRDetails} {
if hdr != nil && len(hdr.DolbyVisionProfiles) > 16 {
return errors.New("dolby vision profile list exceeds supported size")
}
}
for name, engine := range ctx.Engines {
if len(name) > 64 || len(engine.Containers) > 64 || len(engine.VideoCodecs) > 64 || len(engine.AudioDecodeCodecs) > 64 || len(engine.AudioPassthroughCodecs) > 64 || len(engine.Features) > 64 || len(engine.ValidatedClaims) > 64 || len(engine.Transformations) > 16 {
return errors.New("engine capability exceeds supported size")
}
if engine.HDRDetails != nil && len(engine.HDRDetails.DolbyVisionProfiles) > 16 {
return errors.New("dolby vision profile list exceeds supported size")
}
for _, values := range [][]string{engine.Containers, engine.VideoCodecs, engine.AudioDecodeCodecs, engine.AudioPassthroughCodecs, engine.Features, engine.ValidatedClaims} {
for _, value := range values {
if len(value) > 64 {
return errors.New("engine capability value exceeds supported size")
}
}
}
seenTransformations := make(map[string]struct{}, len(engine.Transformations))
for i := range engine.Transformations {
transformation := &engine.Transformations[i]
transformation.Name = strings.ToLower(strings.TrimSpace(transformation.Name))
transformation.Executor = strings.ToLower(strings.TrimSpace(transformation.Executor))
transformation.RecipeVersion = strings.TrimSpace(transformation.RecipeVersion)
if transformation.Name == "" || len(transformation.Name) > 64 ||
(transformation.Executor != "client" && transformation.Executor != "server") ||
transformation.RecipeVersion == "" || len(transformation.RecipeVersion) > 32 ||
len(transformation.ValidatedClaims) > 32 {
return errors.New("invalid engine transformation capability")
}
if transformation.Executor == "client" {
if !engine.Enabled || !engine.SupportedOnDevice ||
(!HasFeatureV3(ctx.Features, FeatureClientVideoTransforms) && !HasFeatureV3(topLevelFeatures, FeatureClientVideoTransforms)) {
return errors.New("client transformation capability is not enabled")
}
}
key := transformation.Executor + ":" + transformation.Name + ":" + transformation.RecipeVersion
if _, exists := seenTransformations[key]; exists {
return errors.New("duplicate engine transformation capability")
}
seenTransformations[key] = struct{}{}
for _, claim := range transformation.ValidatedClaims {
if len(claim) > 128 {
return errors.New("transformation claim exceeds supported size")
}
}
}
ctx.Engines[name] = engine
}
for _, abi := range ctx.Device.ABIs {
if len(abi) > 64 {
return errors.New("device ABI exceeds supported size")
}
}
for _, passthrough := range []*AudioPassthroughV3{c.AudioPassthrough, ctx.Output.AudioPassthrough} {
if passthrough == nil {
continue
}
if len(passthrough.PassthroughCodecs) > 64 || len(passthrough.Entries) > 64 || passthrough.MaxChannels < 0 || passthrough.MaxChannels > 64 {
return errors.New("audio passthrough capability exceeds supported size")
}
for _, entry := range passthrough.Entries {
if len(entry.Codec) > 64 || len(entry.ChannelCounts) > 32 || len(entry.Layouts) > 32 {
return errors.New("audio passthrough entry exceeds supported size")
}
}
}
return nil
}
func validateTrackPairV3(fileID int, kind, id string, index *int) error {
if len(id) > 128 {
return fmt.Errorf("%s_track_id exceeds supported size", kind)
}
if index != nil && (*index < 0 || *index > 10_000) {
return fmt.Errorf("%s_track_index is invalid", kind)
}
if id == "" || index == nil {
return nil
}
want := TrackIDV3(fileID, kind, *index)
if id != want {
return fmt.Errorf("%s track id and index disagree", kind)
}
return nil
}
func validateOptionalBoundedIntV3(v *int, min, max int, name string) error {
if v != nil && (*v < min || *v > max) {
return fmt.Errorf("%s is outside the supported range", name)
}
return nil
}
func isFiniteV3(v float64) bool { return !math.IsNaN(v) && !math.IsInf(v, 0) }
func HasFeatureV3(features []string, wanted string) bool {
return slices.ContainsFunc(features, func(v string) bool { return strings.EqualFold(strings.TrimSpace(v), wanted) })
}
func NewTerminalResponseV3(reason, message string, retryable bool) DecisionResponseV3 {
return DecisionResponseV3{
ProtocolVersion: ProtocolV3,
ServerFeatures: ServerFeaturesV3(),
Outcome: OutcomeAdaptationUnavailableV3,
Terminal: &TerminalV3{Reason: reason, Message: message, Retryable: retryable},
}
}
func DisabledResponseV3() DecisionResponseV3 {
return DecisionResponseV3{ProtocolVersion: ProtocolV3, ServerFeatures: []string{}}
}
func NewPlanExpiryV3(now time.Time) string { return now.Add(MaxTokenTTL).UTC().Format(time.RFC3339) }
Reference in New Issue View Git Blame Copy Permalink