playback

package
v0.8.0-alpha Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: AGPL-3.0 Imports: 4 Imported by: 0

Documentation

Overview

Package playback decides how a client plays a file: as it is (direct), rewrapped into HLS without touching the picture (remux), or converted (transcode). It is plain logic with no I/O: the server describes the file and the client, and gets back a decision, so every rule can be tested without FFmpeg or a real device. See docs/CLIENT-API.md.

Index

Constants

View Source
const (
	Direct    = "direct"
	Remux     = "remux"
	Transcode = "transcode"
)

Modes.

View Source
const (
	SubNone     = "none"     // no subtitle chosen
	SubEmbedded = "embedded" // inside the file; the player draws it
	SubSidecar  = "sidecar"  // a separate WebVTT file the player or app draws
	SubHLS      = "hls"      // a WebVTT rendition in the HLS master playlist
	SubBurn     = "burn"     // drawn into the picture by the server
)

How a subtitle track reaches the screen.

View Source
const (
	ReasonForced       = "forced"            // the client asked for a conversion
	ReasonDirectOff    = "direct-play-off"   // an administrator turned direct play off
	ReasonContainer    = "container"         // the player can't open this kind of file
	ReasonVideoCodec   = "video-codec"       // the player can't decode the picture
	ReasonVideoTag     = "video-tag"         // HEVC stored as hev1, which Apple players refuse
	ReasonVideoHeight  = "video-height"      // more lines than the client or the server allows
	ReasonVideoBitrate = "video-bitrate"     // more data than the client can take
	ReasonVideoDepth   = "video-depth"       // 10-bit picture on a client that can't show it
	ReasonVideoRange   = "video-range"       // HDR the display can't show
	ReasonInterlaced   = "interlaced"        // the player doesn't deinterlace
	ReasonAudioCodec   = "audio-codec"       // the player can't decode this sound
	ReasonAudioChans   = "audio-channels"    // more channels than the client takes
	ReasonAudioTrack   = "audio-track"       // the player can't switch tracks inside a file
	ReasonSubtitle     = "subtitle"          // this subtitle needs HLS or burning in
	ReasonNoVideo      = "no-video"          // nothing to decide on (a sound-only file)
	ReasonBurnAsked    = "burn-subtitle"     // the client asked for burned-in subtitles
	ReasonHLSVideo     = "hls-video-codec"   // the picture can't be carried in HLS for this client
	ReasonRemuxDisable = "remux-unavailable" // this client doesn't take remuxed streams
	ReasonSplit        = "split-file"        // a film in several files plays as one stream
	ReasonVideoTrack   = "video-track"       // another video stream of the file was chosen
	ReasonFlatten3D    = "flatten-3d"        // a 3D picture shown as 2D
	ReasonRemoteLimit  = "remote-limit"      // more data than viewers away from home are allowed
	ReasonRobust       = "robust-stream"     // more data than a robust stream's measured connection comfortably carries
)

Reasons a file can't play as it is. They are part of the API: apps may show them, and logs quote them.

View Source
const (
	StreamStandard = "standard"
	StreamRobust   = "robust"
)

Streaming modes: how a stream is sent, as opposed to what is in it (Decide).

Standard is how it has always worked: one stream, made as good as the settings allow, in four-second segments. Robust favours staying smooth over picture quality on a poor connection: a ladder of steady bitrates chosen from what the connection was measured to carry, two-second segments that each start with a keyframe (so a player can change rung or pick up again after a drop at any of them), and players told to keep a bigger buffer and to keep trying, with growing waits, rather than give up.

View Source
const (
	StreamFromDefault = "default" // nothing chose robust
	StreamFromServer  = "server"  // the server's setting, for viewers away from home
	StreamFromDevice  = "device"  // this device asked
)

Where a stream's mode came from.

View Source
const (
	StandardSegmentSec = 4
	RobustSegmentSec   = 2
)

Segment lengths, in seconds.

View Source
const ResumeMinSec = 60

ResumeMinSec: a video started less than this long ago starts over.

Variables

This section is empty.

Functions

func ChooseStreamMode

func ChooseStreamMode(server, device string, away bool) (mode, from string)

ChooseStreamMode applies the settings: a device's own choice wins wherever it is (a phone on poor Wi-Fi at home can ask for robust, a laptop on a fast connection away can ask for standard); otherwise the server's setting applies to viewers away from home.

func ExplainStreaming

func ExplainStreaming(mode, from string, ladder []Rung, measuredKbps int) string

ExplainStreaming words a stream's mode for the player's information: "" for standard, which needs no words. ladder is in the order of the stream's master playlist.

func FitsRobust

func FitsRobust(srcKbps, measuredKbps int) bool

FitsRobust says a file can be sent without converting it in robust mode: its bitrate is within half of what the connection was measured to carry, which leaves room for the connection to get worse. A file nobody measured the connection for is converted, since a file sent as it is can't step down.

func IsTextSubtitle

func IsTextSubtitle(codec string) bool

IsTextSubtitle reports whether a subtitle codec is text, not pictures (Blu-ray PGS, DVD and DVB bitmaps), which can only be drawn or burned in.

func LanguageFromWord

func LanguageFromWord(w string) string

LanguageFromWord reads a word in a file name as a language: a code in any of the usual forms, or a language's English name. "" when it isn't one.

func LanguageName

func LanguageName(tag string) string

LanguageName is a language tag in English words, "" when it isn't known.

func NormalizeLanguage

func NormalizeLanguage(tag string) string

NormalizeLanguage is a language tag reduced to its short base code.

func ReasonText

func ReasonText(code string) string

ReasonText puts a reason in words.

func SameLanguage

func SameLanguage(a, b string) bool

SameLanguage compares two language tags in any of the usual forms.

func Smallest

func Smallest(a, b int) int

Smallest is the lower of two limits, where 0 means no limit.

func ValidStreamMode

func ValidStreamMode(m string) bool

ValidStreamMode says a mode is one of the two. "" is not: callers decide what it means.

Types

type Audio

type Audio struct {
	Codec    string
	Channels int
	Language string
	Title    string
	Default  bool
	Comment  bool // commentary, never chosen by itself
}

Audio is one sound track of a file.

type Capabilities

type Capabilities struct {
	Containers        []string `json:"containers"`
	VideoCodecs       []string `json:"videoCodecs"`
	AudioCodecs       []string `json:"audioCodecs"`
	HDR               []string `json:"hdr"`
	TenBit            *bool    `json:"tenBit"`
	MaxHeight         *int     `json:"maxHeight"`
	MaxBitrateKbps    *int     `json:"maxBitrateKbps"`
	MaxAudioChannels  *int     `json:"maxAudioChannels"`
	EmbeddedSubtitles []string `json:"embeddedSubtitles"`
	SidecarSubtitles  *bool    `json:"sidecarSubtitles"`
	HLSAudio          []string `json:"hlsAudio"`
	HLSVideo          []string `json:"hlsVideo"`
	FMP4Video         []string `json:"fmp4Video"`
	HiTenH264         *bool    `json:"hi10pH264"`
	Interlaced        *bool    `json:"interlaced"`
	SwitchAudio       *bool    `json:"switchAudio"`
	Remux             *bool    `json:"remux"`
}

Capabilities are what an app found out about its own device. A field left out keeps the profile's value.

func (*Capabilities) Apply

func (c *Capabilities) Apply(p Profile) Profile

Apply returns the profile with the capabilities filled in. Everything a client sends is normalised: short lower-case names and sane numbers only.

type Chosen

type Chosen struct{ Audio, Subtitle int }

Chosen says which tracks play when the client didn't name any.

func ChooseTracks

func ChooseTracks(src Source, audioLang, subLang string) Chosen

ChooseTracks picks the default tracks, the same way for every client:

  • sound: the wanted language, else the track the file marks as default, else the first; commentary only if there's nothing else;
  • subtitles: the wanted language; else, with none wanted, the forced track in the language being heard (foreign dialogue in an otherwise understood film); else off.

type Decision

type Decision struct {
	Mode    string   `json:"mode"`
	Reasons []string `json:"reasons"` // why not a simpler mode; empty for direct
	// For HLS: what is copied, and how segments are stored.
	CopyVideo bool   `json:"copyVideo"`
	CopyAudio bool   `json:"copyAudio"`
	FMP4      bool   `json:"fmp4"`
	Subtitle  string `json:"subtitle"` // one of the Sub* delivery values
	// ToneMap: HDR converted to SDR because the display can't show it.
	ToneMap bool `json:"toneMap"`
	// AudioChannels is the channel count of converted sound: 2 or 6.
	AudioChannels int `json:"audioChannels"`
}

Decision is how the file will play.

func Decide

func Decide(p Profile, src Source, q Request) Decision

Decide applies the rules. Simplest first: play the file as it is; else rewrap it with the picture untouched; else convert it.

type Explanation

type Explanation struct {
	// Summary is one sentence about the whole thing.
	Summary string `json:"summary"`
	// Source says what the file is: "HEVC 10-bit in Matroska, DTS 5.1".
	Source string `json:"source"`
	// Picture, Sound and Subtitles say what happens to each.
	Picture   string `json:"picture"`
	Sound     string `json:"sound"`
	Subtitles string `json:"subtitles,omitempty"`
	// Reasons say why it isn't simpler, one sentence each.
	Reasons []string `json:"reasons"`
	// Load is what it costs the server: none (it only sends the file), light (it copies
	// or converts sound) or heavy (it converts the picture).
	Load string `json:"load"`
	// Streaming says how it is streamed, when that is the robust mode.
	Streaming string `json:"streaming,omitempty"`
}

Explanation says in words how a file plays and why, for the player's information: what happens to the picture, the sound and the subtitles, and how hard the server works for it. It is written for people, so apps show it as it is.

func Explain

func Explain(d Decision, src Source, q Request) Explanation

Explain words a decision.

func ExplainAudio

func ExplainAudio(direct bool, container, codec string) Explanation

ExplainAudio words what happens to a sound file.

type Ladder

type Ladder struct {
	Rungs []Rung `json:"rungs"`
	Start int    `json:"start"` // index into Rungs
}

Ladder is the rungs a robust stream offers, best first, and the one to start at.

func RobustLadder

func RobustLadder(srcHeight, maxHeight, capKbps, measuredKbps int) Ladder

RobustLadder chooses the rungs for a picture srcHeight lines tall. maxHeight and capKbps are the limits that apply (0 = none); measuredKbps is what the connection carried in the player's test (0 = not measured).

It starts at the best rung that fits in part of the measured speed, and offers one rung above it (a player that finds the connection better may climb once) and every rung below it (where it steps down to, instead of stalling).

type PlayerHints

type PlayerHints struct {
	// BufferSec is how far ahead the player tries to keep; MaxBufferSec the most it may.
	BufferSec    int `json:"bufferSec"`
	MaxBufferSec int `json:"maxBufferSec"`
	// Retries: how often a failed segment or playlist is asked for again, waiting
	// FirstRetryMs, then twice that each time, up to MaxRetryMs.
	Retries      int `json:"retries"`
	FirstRetryMs int `json:"firstRetryMs"`
	MaxRetryMs   int `json:"maxRetryMs"`
	// SegmentTimeoutMs is how long to wait for a segment to start arriving: the server may
	// be starting a conversion for it.
	SegmentTimeoutMs int `json:"segmentTimeoutMs"`
	// ResumeOnDrop: when the connection is lost, keep the position and pick up there once
	// it's back (asking /playback again with startSec if the stream is gone), rather than
	// show an error.
	ResumeOnDrop bool `json:"resumeOnDrop"`
	// StepDownOnStall: when the picture stalls, move to a lower rung at once rather than
	// wait for the bandwidth estimate to catch up.
	StepDownOnStall bool `json:"stepDownOnStall"`
}

PlayerHints are what a player should do in a mode, so that every app behaves alike.

func Hints

func Hints(mode string) PlayerHints

Hints returns the player hints for a mode.

type Profile

type Profile struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Direct play: file extensions without the dot, FFmpeg codec names.
	Containers  []string `json:"containers"`
	VideoCodecs []string `json:"videoCodecs"`
	AudioCodecs []string `json:"audioCodecs"`
	// HDR lists the kinds of HDR the display shows: hdr10, hlg, dv5.
	HDR []string `json:"hdr"`
	// TenBit: 10-bit HEVC, VP9 and AV1. HiTenH264 is 10-bit H.264, which
	// hardly anything but a browser's software decoder plays.
	TenBit     bool `json:"tenBit"`
	HiTenH264  bool `json:"hi10pH264"`
	Interlaced bool `json:"interlaced"` // the player deinterlaces by itself
	// HVC1Only: HEVC must be tagged hvc1 (Apple), so hev1 files are rewrapped.
	HVC1Only bool `json:"hvc1Only"`
	// 0 = no limit.
	MaxHeight        int `json:"maxHeight"`
	MaxBitrateKbps   int `json:"maxBitrateKbps"`
	MaxAudioChannels int `json:"maxAudioChannels"`
	// SurroundOutput: sound that has to be converted stays 5.1. Otherwise it becomes
	// stereo, which is what plays everywhere (a browser folds 5.1 down itself, but only
	// when it has to, and stereo is far less to send).
	SurroundOutput bool `json:"surroundOutput"`
	// SwitchAudio: the player can pick another sound track inside a file, so
	// choosing one needs no new stream.
	SwitchAudio bool `json:"switchAudio"`
	// EmbeddedSubtitles: subtitle codecs the player itself draws from inside
	// a directly played file. SidecarSubtitles: it (or the app) can show a
	// separate WebVTT file over a directly played file.
	EmbeddedSubtitles []string `json:"embeddedSubtitles"`
	SidecarSubtitles  bool     `json:"sidecarSubtitles"`
	// HLS: Remux allows rewrapping; HLSVideo and HLSAudio are the codecs
	// carried unchanged; FMP4Video must use fragmented MP4 segments (MPEG-TS
	// otherwise). HLSSubtitles: WebVTT renditions in the master playlist.
	Remux        bool     `json:"remux"`
	HLSVideo     []string `json:"hlsVideo"`
	HLSAudio     []string `json:"hlsAudio"`
	FMP4Video    []string `json:"fmp4Video"`
	HLSSubtitles bool     `json:"hlsSubtitles"`
}

Profile says what a client can play. The built-in ones are a safe default for each platform; an app that can ask its device (MediaCodecList on Android, AVPlayer on tvOS) sends what it found as Capabilities.

func Find

func Find(id string) (Profile, bool)

Find returns a built-in profile by id.

func Profiles

func Profiles() []Profile

Profiles returns the built-in client profiles.

Apple TV follows Apple's HLS authoring specification: HEVC only in fMP4, hvc1 tags, AAC, AC-3 and E-AC-3 sound, WebVTT renditions in the master playlist; AVPlayer doesn't open MKV and can't show a sidecar file over a progressive download by itself. Android TV follows the Media3 format tables: its extractors read MKV, WebM and MPEG-TS as well, decoders depend on the device, so the default stays with what every Android TV device must decode. The app adds what MediaCodecList reports (AC-3, DTS, AV1, Dolby Vision...) in Capabilities.

type Request

type Request struct {
	AudioIndex     int
	SubtitleIndex  int // -1 = off
	MaxHeight      int // the lower of the client's wish and the server's setting; 0 = none
	MaxBitrateKbps int
	AllowDirect    bool // the server's Direct Play setting
	ForceTranscode bool
	BurnSubtitle   bool // the client wants this subtitle in the picture (styled ASS)
	VideoIndex     int  // which of the file's video streams, when it has several
	Flatten3D      bool // show one eye of a 3D picture
	OverLimit      bool // the file sent as it is would be over the limit for viewers away from home
	// Robust: the stream is robust (see ChooseStreamMode) and the file sent as it is would
	// not fit the connection comfortably (FitsRobust), so it is converted to a ladder.
	Robust bool
}

Request is what the viewer chose.

type Rung

type Rung struct {
	Height int `json:"height"`
	Kbps   int `json:"kbps"`
}

Rung is one step of a robust ladder: a picture height and the bitrate of the whole stream (picture and sound).

type Source

type Source struct {
	Container  string // file extension without the dot
	HasVideo   bool
	VideoCodec string
	VideoTag   string // hvc1, hev1, avc1...
	Height     int
	BitDepth   int
	Range      string // sdr | hdr10 | hlg | dv5
	// Dynamic names what the range doesn't say, for the player's information: "HDR10+",
	// or the Dolby Vision profile a base layer belongs to.
	Dynamic    string
	Interlaced bool
	// Stereo: a 3D picture stored in the frame: sbs (side by side) or tab (one above
	// the other). "" is an ordinary picture.
	Stereo string
	// Parts: how many files a split film is stored in. 0 or 1 is an ordinary file.
	Parts       int
	BitrateKbps int
	Audio       []Audio
	Subtitles   []Subtitle
}

Source describes a file, from the media probe.

type Subtitle

type Subtitle struct {
	Codec    string
	Language string
	Title    string
	Default  bool
	Forced   bool
	SDH      bool
	// File: a subtitle file beside the video rather than a track inside it.
	File string
	// Format is that file's format in the registry.
	Format string
}

Subtitle is one subtitle track of a file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL