preview

Documentation

Overview

Package preview provides per-source preview encoding for browser multiview.

Each source gets its own Encoder goroutine that scales incoming raw YUV420 frames to a lower resolution and encodes them with a lightweight x264 preset. The encoded H.264 stream is broadcast to a per-source MoQ relay so browsers can subscribe to individual preview feeds.

The Encoder uses a newest-wins drop policy: if the encode goroutine falls behind, older frames are silently discarded so the preview always shows the most recent frame. This is the correct behavior for a monitoring preview -- latency matters more than every-frame delivery.

Index

• type Config
• type Encoder
  • func NewEncoder(cfg Config) (*Encoder, error)
  • func (e *Encoder) DebugSnapshot() map[string]any
  • func (e *Encoder) ForceKeyframe()
  • func (e *Encoder) GetStats() StatsSnapshot
  • func (e *Encoder) Send(yuv []byte, w, h int, pts int64)
  • func (e *Encoder) SendOwned(yuv []byte, w, h int, pts int64, release func([]byte))
  • func (e *Encoder) Stop()
• type Relay
• type Stats
• type StatsSnapshot

Types

type Config

type Config struct {
	SourceKey     string // Source identifier (e.g. "cam1", "srt:feed1")
	Width         int    // Preview output width (e.g. 854)
	Height        int    // Preview output height (e.g. 480)
	Bitrate       int    // Target bitrate in bps (e.g. 500_000)
	FPSNum        int    // Frame rate numerator (e.g. 30)
	FPSDen        int    // Frame rate denominator (e.g. 1)
	Relay         Relay  // MoQ relay for broadcast
	FrameInterval int    // Encode every Nth frame (1=all, 2=half rate, etc). 0 treated as 1.
	Preset        string // x264 preset (default "ultrafast"). "veryfast" for better compression.
}

Config configures a preview encoder instance.

type Encoder

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

Encoder scales and encodes preview frames for a single source. Each source gets its own Encoder instance -- they run completely independently with no shared state.

func NewEncoder

func NewEncoder(cfg Config) (*Encoder, error)

NewEncoder creates and starts a preview encoder goroutine. The goroutine runs until Stop() is called.

func (*Encoder) DebugSnapshot

func (e *Encoder) DebugSnapshot() map[string]any

DebugSnapshot implements debug.SnapshotProvider for registration with the debug collector.

func (*Encoder) ForceKeyframe

func (e *Encoder) ForceKeyframe()

ForceKeyframe forces the next encoded frame to be an IDR keyframe. Call on source cuts to prevent P-frame artifacts from the old scene smearing into the new one.

func (*Encoder) GetStats

func (e *Encoder) GetStats() StatsSnapshot

GetStats returns a JSON-friendly snapshot of encoder performance metrics.

func (*Encoder) Send

func (e *Encoder) Send(yuv []byte, w, h int, pts int64)

Send submits a raw YUV420 frame for preview encoding. Non-blocking with newest-wins drop policy: if the channel is full, the oldest frame is drained and replaced with the new one. The YUV data is deep-copied so the caller can reuse or release the buffer.

func (*Encoder) SendOwned

func (e *Encoder) SendOwned(yuv []byte, w, h int, pts int64, release func([]byte))

SendOwned submits a raw YUV420 frame for preview encoding, taking ownership of the buffer (no deep copy). The optional release callback is called after the buffer is no longer needed (after scaling), or immediately if the frame is dropped due to channel overflow.

func (*Encoder) Stop

func (e *Encoder) Stop()

Stop signals the encode goroutine to exit and waits for it to finish. Safe to call multiple times.

type Relay

type Relay interface {
	BroadcastVideo(frame *media.VideoFrame)
	BroadcastAudio(frame *media.AudioFrame)
	SetVideoInfo(info distribution.VideoInfo)
}

Relay is the subset of distribution.Relay used by the preview encoder.

type Stats

type Stats struct {
	FramesIn      atomic.Int64
	FramesOut     atomic.Int64
	FramesDropped atomic.Int64
	EncodeErrors  atomic.Int64
	LastEncodeNs  atomic.Int64 // last encode duration in nanoseconds
	AvgEncodeNs   atomic.Int64 // exponential moving average
}

Stats tracks preview encoder performance counters using atomic operations.

type StatsSnapshot

type StatsSnapshot struct {
	FramesIn      int64   `json:"framesIn"`
	FramesOut     int64   `json:"framesOut"`
	FramesDropped int64   `json:"framesDropped"`
	EncodeErrors  int64   `json:"encodeErrors"`
	LastEncodeMs  float64 `json:"lastEncodeMs"`
	AvgEncodeMs   float64 `json:"avgEncodeMs"`
}

StatsSnapshot is the JSON-serializable view of encoder stats.