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
- func ChooseStreamMode(server, device string, away bool) (mode, from string)
- func ExplainStreaming(mode, from string, ladder []Rung, measuredKbps int) string
- func FitsRobust(srcKbps, measuredKbps int) bool
- func IsTextSubtitle(codec string) bool
- func LanguageFromWord(w string) string
- func LanguageName(tag string) string
- func NormalizeLanguage(tag string) string
- func ReasonText(code string) string
- func SameLanguage(a, b string) bool
- func Smallest(a, b int) int
- func ValidStreamMode(m string) bool
- type Audio
- type Capabilities
- type Chosen
- type Decision
- type Explanation
- type Ladder
- type PlayerHints
- type Profile
- type Request
- type Rung
- type Source
- type Subtitle
Constants ¶
const ( Direct = "direct" Remux = "remux" Transcode = "transcode" )
Modes.
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.
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.
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.
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.
const ( StandardSegmentSec = 4 RobustSegmentSec = 2 )
Segment lengths, in seconds.
const ResumeMinSec = 60
ResumeMinSec: a video started less than this long ago starts over.
Variables ¶
This section is empty.
Functions ¶
func ChooseStreamMode ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
LanguageName is a language tag in English words, "" when it isn't known.
func NormalizeLanguage ¶
NormalizeLanguage is a language tag reduced to its short base code.
func SameLanguage ¶
SameLanguage compares two language tags in any of the usual forms.
func ValidStreamMode ¶
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 ¶
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.
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 ¶
Ladder is the rungs a robust stream offers, best first, and the one to start at.
func RobustLadder ¶
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.
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 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 ¶
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.