Documentation
¶
Overview ¶
Package transcoder manages a bounded pool of FFmpeg worker processes. Each stream may run one FFmpeg process per ladder rung (passthrough copy or ABR encode); all read the same raw ingest. GPU acceleration (NVENC) is used when configured on profiles / global HW.
Index ¶
- type ProbeResult
- type Profile
- type ProfileSnapshot
- type RenditionTarget
- type RuntimeStatus
- type Service
- func (s *Service) Config() config.TranscoderConfig
- func (s *Service) RuntimeStatus(streamID domain.StreamCode) (RuntimeStatus, bool)
- func (s *Service) SetConfig(cfg config.TranscoderConfig)
- func (s *Service) SetHealthyCallback(fn func(streamID domain.StreamCode))
- func (s *Service) SetUnhealthyCallback(fn func(streamID domain.StreamCode, reason string))
- func (s *Service) Start(ctx context.Context, logStreamCode domain.StreamCode, ...) error
- func (s *Service) StartProfile(streamID domain.StreamCode, profileIndex int, target RenditionTarget) error
- func (s *Service) Stop(streamID domain.StreamCode)
- func (s *Service) StopProfile(streamID domain.StreamCode, profileIndex int)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ProbeResult ¶ added in v0.0.36
type ProbeResult struct {
OK bool `json:"ok"`
Path string `json:"path"`
Version string `json:"version,omitempty"`
Encoders map[string]map[string]bool `json:"encoders"`
Muxers map[string]bool `json:"muxers"`
Filters map[string]bool `json:"filters,omitempty"`
Warnings []string `json:"warnings,omitempty"`
Errors []string `json:"errors,omitempty"`
}
ProbeResult is the structured outcome of inspecting an FFmpeg binary for compatibility with this app. Returned by Probe.
OK is true when no REQUIRED capability is missing (server can boot / serve any stream that uses default settings). Warnings list OPTIONAL capabilities that are absent — the server still runs but specific configurations (HW acceleration, h265, vp9, av1) will fail at runtime for streams that select them.
func Probe ¶ added in v0.0.36
Probe runs the FFmpeg binary at path and reports compatibility with this app. Returns an error only when the binary itself cannot be invoked (not found, not executable, not actually FFmpeg). For "ran but missing capabilities", Probe returns a non-nil ProbeResult with OK=false and Errors populated.
Empty path is normalised to "ffmpeg" (PATH lookup) — matches the runtime default at publisher.NewService and transcoder.Service.
hws filters the OPTIONAL encoder set to encoders relevant to the host's available backends. Caller passes the result of hwdetect.Available() — server auto-detects the hardware, the client (UI / boot) does NOT pick. Empty slice → union across every backend (defensive fallback).
REQUIRED set (libx264, aac, mpegts) is constant — independent of hw.
type Profile ¶
type Profile struct {
Width int
Height int
Bitrate string // e.g. "4000k"
Codec string // e.g. "h264_nvenc", "libx264"
Preset string // e.g. "p5" (NVENC), "fast" (libx264)
CodecProfile string // H.264/HEVC profile (baseline, main, high)
CodecLevel string // e.g. 4.1
MaxBitrate int // kbps peak (0 = omit -maxrate)
Framerate float64
KeyframeInterval int // GOP target in seconds (0 = encoder default)
Bframes *int // nil = encoder default; 0 = explicit none
Refs *int // nil = encoder default
SAR string // "" = inherit; "N:M" sets output sample aspect ratio
ResizeMode string // "" = pad; "pad"|"crop"|"stretch"|"fit"
}
Profile defines a single transcoding output rendition. Rendition label in logs and URLs is track_<n> from ladder order (see buffer.VideoTrackSlug).
type ProfileSnapshot ¶ added in v0.0.8
type ProfileSnapshot struct {
Index int `json:"index"` // 0-based ladder index; track label = track_<index+1>
Track string `json:"track"`
RestartCount int `json:"restart_count"`
Errors []domain.ErrorEntry `json:"errors,omitempty"`
}
ProfileSnapshot is a serialisable copy of one profile encoder's runtime state. Errors is a bounded rolling history (newest first) of FFmpeg crash messages captured for this profile since the stream started.
type RenditionTarget ¶
type RenditionTarget struct {
BufferID domain.StreamCode
Profile Profile
}
RenditionTarget binds one encoded ladder rung to its Buffer Hub output slot.
type RuntimeStatus ¶ added in v0.0.8
type RuntimeStatus struct {
Profiles []ProfileSnapshot `json:"profiles"`
}
RuntimeStatus is a JSON-safe snapshot of transcoder state for one stream.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service manages the FFmpeg worker pool. There is no upper bound on the number of concurrent encoders — every rendition gets its own FFmpeg process and the OS (rlimit / GPU NVENC slots / RAM) is the natural limit. The previous app-level semaphore was removed because it caused silent profile starvation when set too low (e.g. 4-slot cap with 20 streams × 2 profile = 40 needed → 36 stuck waiting forever).
func (*Service) Config ¶ added in v0.0.31
func (s *Service) Config() config.TranscoderConfig
Config returns a snapshot of the currently active transcoder config. Used by runtime.diff to compare old vs new without racing SetConfig.
func (*Service) RuntimeStatus ¶ added in v0.0.8
func (s *Service) RuntimeStatus(streamID domain.StreamCode) (RuntimeStatus, bool)
RuntimeStatus returns a snapshot of per-profile encoder state. Returns ok=false if the stream has no transcoder pipeline running.
func (*Service) SetConfig ¶ added in v0.0.31
func (s *Service) SetConfig(cfg config.TranscoderConfig)
SetConfig hot-swaps the cached transcoder config. Used by runtime.Manager when the operator updates GlobalConfig.Transcoder via POST /config so the next Start uses the new value.
Already-running streams are NOT restarted from here — caller must stop+start them separately to materialize behaviour-changing fields. Holding s.mu prevents a Start in flight from observing a torn (half-old, half-new) config.
func (*Service) SetHealthyCallback ¶ added in v0.0.40
func (s *Service) SetHealthyCallback(fn func(streamID domain.StreamCode))
SetHealthyCallback registers a function the Service calls the FIRST time every previously-failing profile in a stream has run stably for the sustain threshold. Pair with SetUnhealthyCallback for the degraded → active edge.
func (*Service) SetUnhealthyCallback ¶ added in v0.0.40
func (s *Service) SetUnhealthyCallback(fn func(streamID domain.StreamCode, reason string))
SetUnhealthyCallback registers a function the Service calls the FIRST time a stream transitions to "transcoder unhealthy" (any profile has crashed enough consecutive times that it is in a hot retry loop). reason is the latest crash error string.
Subsequent crashes on already-unhealthy streams do NOT re-fire — the coordinator only needs to see edges. Pair with SetHealthyCallback to be notified when the stream recovers.
func (*Service) Start ¶
func (s *Service) Start( ctx context.Context, logStreamCode domain.StreamCode, rawIngestID domain.StreamCode, tc *domain.TranscoderConfig, targets []RenditionTarget, ) error
Start launches the transcoder pipeline for a stream. The Stream's `transcoder.mode` selects topology: "" / "multi" (default) spawns ONE FFmpeg per stream that emits all renditions via separate output pipes; "per_profile" spawns one FFmpeg per RenditionTarget. See multi_output_run.go for rationale and trade-offs.
func (*Service) StartProfile ¶
func (s *Service) StartProfile(streamID domain.StreamCode, profileIndex int, target RenditionTarget) error
StartProfile starts a single FFmpeg encoder for one profile index on an existing stream worker.
func (*Service) Stop ¶
func (s *Service) Stop(streamID domain.StreamCode)
Stop cancels all FFmpeg encoders for a stream and waits for them to exit.
func (*Service) StopProfile ¶
func (s *Service) StopProfile(streamID domain.StreamCode, profileIndex int)
StopProfile stops a single FFmpeg encoder for one profile index.
Source Files