kolo docsbeta

kolo-media

A catalog, LOC packaging, a clock, playout and audio and video sync for broadcasts over kolo-moq. It works on encoded frames and is pure Go. A broadcast can be sealed so a kolo-moq relay forwards it without reading it.

On this page

kolo-media sits between your codecs and kolo-moq. A sender describes its tracks in a catalog, stamps frames on one clock and publishes them as LOC objects (Low Overhead Media Container, draft-ietf-moq-loc-04). A receiver reads the catalog, subscribes to the tracks it can decode, and plays the frames through a jitter buffer, with audio and video in sync, following catalog updates. It works on encoded frames only: capture, codecs and output stay in your application. A broadcast can also be sealed end to end with kolo-moq's secobj, so a relay forwards it without being able to read it. The Go package is named kolomedia.

All steps

A broadcast, from catalog to playout

The catalog lists the tracks. The receiver plays the ones it can decode, and audio and video stay in sync.

  1. A broadcast is a kolo-moq namespace. Its catalog is a track with one group for each version, and it lists the other tracks of the broadcast.
  2. Each audio or video track is another track of the same namespace. One Clock stamps every frame, and WriteFrame publishes it without waiting for subscribers. A lower priority number is sent first.
  3. Watch subscribes to the catalog, and Select picks one audio and one video track the receiver can decode. A new catalog version can change the choice.
  4. Each picked track goes into its own jitter buffer in Playout, which reorders frames, drops duplicate and late ones and sets a delay from the jitter it measures, between 100 ms and 400 ms by default.
  5. Audio paces the clock and video follows the audio that was actually played, so the two stay in sync. Next returns each frame when it is due.

Install

go get github.com/ciranda-dev/kolo-media

To pin this release, run go get github.com/ciranda-dev/kolo-media@v0.1.0. It is pure Go, with no cgo and nothing to install, so it builds with CGO_ENABLED=0. It needs Go 1.26 or newer. It depends on kolo-moq v0.1.0, which go get installs with it.

Quick start

This program publishes one audio track and watches it on 127.0.0.1, with generated media. Alice publishes a broadcast with one audio track and serves it, and a clock stamps her frames, each 20 ms of silence. Bob dials her and plays what her catalog offers him: he asks only for the codec PCMS16LE, so the Select call picks her track.

main.go
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	kolomedia "github.com/ciranda-dev/kolo-media"
	kolomoq "github.com/ciranda-dev/kolo-moq"
	kolosecure "github.com/ciranda-dev/kolo-secure"
)

func must[T any](v T, err error) T {
	if err != nil {
		log.Fatal(err)
	}
	return v
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	alice, bob := must(koloid.Generate()), must(koloid.Generate())

	// Alice publishes a broadcast with one audio track and serves it.
	origin := must(kolomoq.NewOrigin(nil))
	ns := kolomoq.Namespace{"room", "alice"}
	broadcast := must(kolomedia.NewBroadcast(origin, ns))
	defer broadcast.Close()
	mic := must(broadcast.AddTrack(kolomedia.Track{
		Name: "mic", Kind: kolomedia.Audio, Codec: kolomedia.PCMS16LE, Timescale: 48000,
		SampleRate: 48000, Channels: 1, FrameDuration: 20 * time.Millisecond,
	}, kolomedia.PackagerOptions{}))
	ln := must(kolosecure.Listen(ctx, "127.0.0.1:0", alice, nil))
	defer ln.Close()
	go func() {
		if conn, err := ln.Accept(ctx); err == nil {
			if s, err := kolomoq.NewServer(ctx, conn, &kolomoq.Config{Origin: origin}); err == nil {
				<-s.Done()
			}
		}
	}()

	// Her encoder would produce these frames: 20 ms of silence each.
	clock := kolomedia.NewClock()
	go func() {
		for range time.Tick(20 * time.Millisecond) {
			ts, err := clock.At(time.Now(), 48000)
			if err != nil || mic.WriteFrame(kolomedia.Frame{Timestamp: ts, Data: make([]byte, 1920)}) != nil {
				return
			}
		}
	}()

	// Bob dials alice and plays what her catalog offers him.
	conn := must(kolosecure.Dial(ctx, ln.Addr().String(), bob, alice.PublicKey(), nil))
	session := must(kolomoq.NewClient(ctx, conn, nil))
	defer session.Close()
	caps := kolomedia.Capabilities{Codecs: []kolomedia.Codec{kolomedia.PCMS16LE}}
	watcher := must(kolomedia.Watch(ctx, session, ns, kolomedia.WatchOptions{Capabilities: caps}))
	defer watcher.Close()
	for range 5 {
		frame, track, err := watcher.Next(ctx, kolomedia.Audio)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("play", track.Name, len(frame.Data), "bytes")
	}
	fmt.Println("playout delay", watcher.Stats().Playout.Delay)
}

It prints:

Text
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
playout delay 100ms

The repository also has examples/publish, which runs a relay and publishes a generated tone and a video track through it, and examples/watch, which watches that broadcast and prints the frames, the tone's level and the audio and video offset each second.

API reference

The API reference is generated from the Go source and is in English.

Package kolomedia · github.com/ciranda-dev/kolo-media · v0.1.0

Package kolomedia describes, packages, publishes and plays out the encoded audio and video of a Kolo broadcast on kolo-moq: a binary catalog, LOC objects (draft-ietf-moq-loc-04), a shared media clock, a receive-side playout with jitter buffers and A/V sync, rendition selection, and Broadcast and Watch to tie them to MoQ sessions. It never captures, encodes, decodes or renders, and it does not use cgo.

Experimental: the API may change before v1.0.0.

Constants

const (
	PropertyTimescale   = 0x08
	PropertyAudioLevel  = 0x0C
	PropertyVideoConfig = 0x0D
	PropertyAudioConfig = 0x0F
	PropertyTimestamp   = 0x10
)

LOC property types (draft-ietf-moq-loc-04). An even type carries a varint Value, an odd type Bytes.

const (
	CatalogPriority = 28
	AudioPriority   = 48
	VideoPriority   = 68
)

MoQ publisher priorities (lower is sent first): the catalog, then audio, then video, all ahead of a track at kolomoq.DefaultPriority.

const CatalogTrack = "catalog"

CatalogTrack is the name of the track that carries a broadcast's catalog: one group per catalog version, with the encoded catalog as its only object.

const DefaultTimescale = 1_000_000

DefaultTimescale is the LOC default: timestamps in microseconds since the Unix epoch.

const MediaGroupTimeout = 30 * time.Second

MediaGroupTimeout is the subgroup delivery timeout of media tracks: a group not sent 30 s after it ended is no use to a live subscriber and is dropped.

Variables

var (
	// ErrInvalidFrame means a frame is empty, out of range or does not fit its track.
	ErrInvalidFrame = errors.New("kolomedia: invalid frame")
	// ErrInvalidTrack means a track description is not valid.
	ErrInvalidTrack = errors.New("kolomedia: invalid track")
	// ErrInvalidCatalog means a catalog is malformed, over a limit or not valid.
	ErrInvalidCatalog = errors.New("kolomedia: invalid catalog")
	// ErrCatalogFormat means an encoded catalog has an unknown format version.
	ErrCatalogFormat = errors.New("kolomedia: unsupported catalog format")
	// ErrInvalidTimescale means a timescale of zero.
	ErrInvalidTimescale = errors.New("kolomedia: invalid timescale")
	// ErrTimestampRange means a timestamp or duration does not fit the target unit.
	ErrTimestampRange = errors.New("kolomedia: timestamp out of range")
	// ErrTimestampOrder means a frame's timestamp is not after the previous frame's.
	ErrTimestampOrder = errors.New("kolomedia: timestamp not after the previous frame")
	// ErrNeedKeyframe means a video track was given a delta frame where a group must start: before
	// its first keyframe, or after a failed TrackPublisher.WriteFrame.
	ErrNeedKeyframe = errors.New("kolomedia: video track needs a keyframe")
	// ErrMissingProperty means an object lacks a property its track requires.
	ErrMissingProperty = errors.New("kolomedia: missing property")
	// ErrDuplicateProperty means an object carries a property more than once.
	ErrDuplicateProperty = errors.New("kolomedia: duplicate property")
	// ErrMalformedProperty means a property has the wrong form or value, or does not belong to the track's kind.
	ErrMalformedProperty = errors.New("kolomedia: malformed property")
	// ErrPropertyMismatch means a property disagrees with the track's catalog entry.
	ErrPropertyMismatch = errors.New("kolomedia: property does not match the catalog")
	// ErrInvalidConfig means a playout configuration is not valid.
	ErrInvalidConfig = errors.New("kolomedia: invalid configuration")
	// ErrUnknownTrack means a track name the playout or broadcast does not have.
	ErrUnknownTrack = errors.New("kolomedia: unknown track")
	// ErrFrameTooLarge means a frame is larger than a whole track buffer, or its object is larger than
	// the origin's MaxObjectSize (the error then also wraps kolomoq.ErrObjectTooLarge).
	ErrFrameTooLarge = errors.New("kolomedia: frame too large")
	// ErrClosed means the playout, broadcast, track publisher or watcher was closed.
	ErrClosed = errors.New("kolomedia: closed")
	// ErrNoMatch means no track of the catalog fits the receiver's capabilities.
	ErrNoMatch = errors.New("kolomedia: no track matches the capabilities")
	// ErrBroadcastEnded means the broadcast's catalog track ended: the publisher ended it, or a relay
	// ended it with a kolomoq.PublishDoneError, which the error then wraps.
	ErrBroadcastEnded = errors.New("kolomedia: broadcast ended")
	// ErrSessionEnded means the MoQ session ended; the error wraps the session's reason when it has one.
	ErrSessionEnded = errors.New("kolomedia: session ended")
	// ErrTrackEnded means a track the watcher was playing ended: the publisher ended it, or a relay
	// ended it with a kolomoq.PublishDoneError, which the error then wraps.
	ErrTrackEnded = errors.New("kolomedia: track ended")
	// ErrBroadcastNotFound means the peer has no broadcast under the namespace; the error wraps the kolomoq request error.
	ErrBroadcastNotFound = errors.New("kolomedia: broadcast not found")
	// ErrBroadcastExists means the origin already has a broadcast under the namespace; the error wraps kolomoq.ErrTrackExists.
	ErrBroadcastExists = errors.New("kolomedia: broadcast already exists")
	// ErrTooManyTracks means the origin has no room for another track; the error wraps kolomoq.ErrTooManyTracks.
	ErrTooManyTracks = errors.New("kolomedia: too many tracks")
)

Functions

func FromDuration

func FromDuration(d time.Duration, timescale uint64) (uint64, error)

FromDuration converts a non-negative duration to a timestamp in the given timescale.

func Rescale

func Rescale(ts, from, to uint64) (uint64, error)

Rescale converts a timestamp from one timescale to another, rounding to the nearest unit.

func ToDuration

func ToDuration(ts, timescale uint64) (time.Duration, error)

ToDuration converts a timestamp in the given timescale to a duration.

Types

type AudioLevel

type AudioLevel struct {
	// Voice reports voice activity.
	Voice bool
	// Level is the magnitude in -dBov, from 0 (loudest) to 127 (silence).
	Level uint8
}

AudioLevel is the level of an audio frame as RFC 6464 defines it.

type Broadcast

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

Broadcast publishes the tracks of one broadcast and its catalog under a namespace of an origin. Its methods are safe for concurrent use.

func NewBroadcast
func NewBroadcast(origin *kolomoq.Origin, ns kolomoq.Namespace) (*Broadcast, error)

NewBroadcast creates the catalog track under ns in origin and publishes an empty catalog, version 0. Catalog versions are the catalog track's group IDs.

func NewSecureBroadcast
func NewSecureBroadcast(origin *kolomoq.Origin, s *secobj.Sender) (*Broadcast, error)

NewSecureBroadcast is NewBroadcast with every object, the catalog included, sealed by s under s.Namespace(). Protected audio tracks carry no AUDIO_LEVEL.

func (Broadcast) AddTrack
func (b *Broadcast) AddTrack(t Track, opts PackagerOptions) (*TrackPublisher, error)

AddTrack adds t to the broadcast and publishes the new catalog. A zero t.Priority takes AudioPriority or VideoPriority. The catalog must fit the origin's MaxObjectSize, else the error wraps ErrInvalidCatalog and kolomoq.ErrObjectTooLarge and the track is not added.

func (Broadcast) Catalog
func (b *Broadcast) Catalog() *Catalog

Catalog returns the catalog last published.

func (Broadcast) Close
func (b *Broadcast) Close() error

Close ends every track and the catalog; subscribers see the broadcast end.

func (Broadcast) RemoveTrack
func (b *Broadcast) RemoveTrack(name string) error

RemoveTrack removes the named track, publishes the new catalog and ends the track for its subscribers.

type Capabilities

type Capabilities struct {
	// Codecs lists the codecs the receiver decodes. Without an audio or video codec, that kind is not selected.
	Codecs []Codec
	// MaxWidth, MaxHeight and MaxFrameRate bound video tracks.
	MaxWidth     uint32
	MaxHeight    uint32
	MaxFrameRate float64
	// MaxBitrate bounds each selected track. A track of unknown bitrate passes.
	MaxBitrate uint64
	// VideoGroup, if set, limits video to the tracks of this rendition group.
	VideoGroup string
}

Capabilities describes what a receiver can decode. A zero limit means no limit.

type Catalog

type Catalog struct {
	Version uint64
	Tracks  []Track
}

Catalog describes one broadcast. Version increases with every change.

func ParseCatalog
func ParseCatalog(b []byte, lim CatalogLimits) (*Catalog, error)

ParseCatalog decodes and validates an encoded catalog. It accepts only the canonical encoding, never panics and allocates in proportion to len(b).

func (Catalog) MarshalBinary
func (c *Catalog) MarshalBinary() ([]byte, error)

MarshalBinary validates the catalog against the default limits and returns its canonical encoding.

type CatalogLimits

type CatalogLimits struct {
	// MaxTracks defaults to 1024, the renditions per broadcast a player keeps.
	MaxTracks int
	// MaxNameLen bounds track and group names in bytes. It defaults to 4096, the MoQ bound on a full track name.
	MaxNameLen int
	// MaxConfigLen defaults to 65508, the largest config that fits one object property.
	MaxConfigLen int
}

CatalogLimits bounds what ParseCatalog accepts. A field outside 1 to its default takes the default, so whatever ParseCatalog accepts, MarshalBinary encodes again.

type Clock

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

Clock gives the tracks of one sender one time base: Unix time read once by NewClock, then advanced by the monotonic clock. Use NewClock; a Clock is safe for concurrent use.

func NewClock
func NewClock() *Clock

NewClock returns a clock that starts now.

func (Clock) After
func (c *Clock) After(d time.Duration, timescale uint64) (uint64, error)

After returns the timestamp of the instant d after the clock's start in the given timescale.

func (Clock) At
func (c *Clock) At(t time.Time, timescale uint64) (uint64, error)

At returns the timestamp of capture instant t in the given timescale.

func (Clock) Start
func (c *Clock) Start() time.Time

Start returns the instant the clock was made.

type Codec

type Codec string

Codec names the encoding of a track's frames.

const (
	Opus     Codec = "opus"
	PCMS16LE Codec = "pcm-s16le"
	VP8      Codec = "vp8"
	VP9      Codec = "vp9"
)

Supported codecs.

type Frame

type Frame struct {
	// Timestamp is the capture time in the track's timescale.
	Timestamp uint64
	// Duration is the frame's length in the track's timescale, 0 if unknown.
	Duration uint64
	// Keyframe marks a video frame that decodes without earlier frames. Every audio frame is one.
	Keyframe bool
	// AudioLevel is the optional level of an audio frame.
	AudioLevel *AudioLevel
	// Data is the codec's frame as is. It must not be empty.
	Data []byte
}

Frame is one encoded audio or video frame of a track, in decode order.

type Kind

type Kind uint8

Kind is the media kind of a track.

const (
	Audio Kind = 1
	Video Kind = 2
)

Track kinds.

func (Kind) String
func (k Kind) String() string

String returns "audio", "video" or "unknown".

type Object

type Object struct {
	Group      uint64
	ID         uint64
	Properties []Property
	Payload    []byte
}

Object is a frame packaged for MoQ: its place in the track, its properties in ascending type order and its payload. Payload and Bytes share memory with the frame and track; do not modify them.

type Packager

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

Packager turns the frames of one track into LOC objects and decides the group boundaries: a video track starts a group at each keyframe, an audio track per frame or per AudioGroupDuration. A Packager is not safe for concurrent use.

func NewPackager
func NewPackager(t Track, opts PackagerOptions) (*Packager, error)

NewPackager returns a Packager for track t, which must be valid.

func (Packager) Pack
func (p *Packager) Pack(f Frame) (Object, error)

Pack returns the object for the next frame. Timestamps must increase and a video track must start with a keyframe.

type PackagerOptions

type PackagerOptions struct {
	// AudioGroupDuration starts a new audio group once the current one spans this long.
	// Zero puts every audio frame in its own group.
	AudioGroupDuration time.Duration
}

PackagerOptions configures a Packager.

type Playout

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

Playout buffers the received frames of one broadcast and releases each when it is due, keeping the tracks in sync; video follows the audio actually played. It is safe for concurrent use.

func NewPlayout
func NewPlayout(tracks []Track, cfg PlayoutConfig) (*Playout, error)

NewPlayout returns a Playout for the tracks of one broadcast, which share one time base. At most one track may be audio: it paces the others.

func (Playout) Close
func (p *Playout) Close() error

Close drops every buffered frame and makes blocked and later calls return ErrClosed.

func (Playout) Next
func (p *Playout) Next(ctx context.Context, track string) (Frame, error)

Next returns the next frame of the named track when it is due, blocking until then. It returns ctx.Err() if ctx ends first and ErrClosed once the Playout is closed.

func (Playout) Push
func (p *Playout) Push(track string, f Frame, arrival time.Time) error

Push copies a received frame of the named track into its buffer; arrival is when it was received, the zero time meaning now. Dropped frames are counted in Stats, not reported as errors.

func (Playout) SetOutputLatency
func (p *Playout) SetOutputLatency(track string, d time.Duration) error

SetOutputLatency reports how long the application holds frames of the named track after Next, such as an audio device buffer. The other tracks are delayed to match.

func (Playout) Stats
func (p *Playout) Stats() PlayoutStats

Stats returns a snapshot of the delay and the counters of every track.

type PlayoutConfig

type PlayoutConfig struct {
	// MinDelay is the least playout delay, 100 ms by default: the jitter allowance of an interactive call.
	MinDelay time.Duration
	// MaxDelay caps the delay, 400 ms (a Wi-Fi retransmission burst) or MinDelay if larger by default.
	MaxDelay time.Duration
	// MaxBehind is how late past its due time a frame may still play, 50 ms by default. Later audio is
	// dropped; late video jumps to its newest due keyframe, or plays at once if there is none.
	MaxBehind time.Duration
	// MaxFrames bounds the frames buffered per track, 8192 by default.
	MaxFrames int
	// MaxBytes bounds the frame data buffered per track, 16 MiB by default.
	MaxBytes int
	// OnKeyframeNeeded, if set, is called once when a video track drops a delta frame while it waits
	// for a keyframe, at start or after a gap. It runs on the goroutine calling Next and must not block.
	OnKeyframeNeeded func(track string)
}

PlayoutConfig configures a Playout. A zero field takes its default.

type PlayoutStats

type PlayoutStats struct {
	// Delay is the current playout delay.
	Delay time.Duration
	// Jitter is the measured 95th percentile of arrival lateness.
	Jitter time.Duration
	// Tracks holds the counters of each track by name.
	Tracks map[string]TrackStats
}

PlayoutStats is a snapshot of a Playout.

type Property

type Property struct {
	Type  uint64
	Value uint64
	Bytes []byte
}

Property is one MoQ object property: Value when Type is even, Bytes when Type is odd.

type PropertyError

type PropertyError struct {
	Type uint64
	Err  error
}

PropertyError reports a malformed, missing, duplicate or mismatched LOC property of an object.

func (PropertyError) Error
func (e *PropertyError) Error() string

Error returns the message with the property type in hex.

func (PropertyError) Unwrap
func (e *PropertyError) Unwrap() error

Unwrap returns the sentinel error.

type Selection

type Selection struct {
	Audio *Track
	Video *Track
}

Selection holds the tracks to subscribe to. A kind with no matching track is nil.

func Select
func Select(c *Catalog, caps Capabilities) (Selection, error)

Select picks at most one audio and one video track of c that fit caps, preferring the lowest Priority number, then the highest quality, then catalog order. It returns ErrNoMatch if it picks nothing.

type Track

type Track struct {
	// Name is the MoQ track name: not empty, unique in the catalog and not CatalogTrack.
	Name string
	// Kind is Audio or Video and must match the codec.
	Kind Kind
	// Codec is one of the supported codecs.
	Codec Codec
	// Timescale is the number of timestamp units per second, usually DefaultTimescale.
	Timescale uint64
	// Priority is the MoQ publisher priority: a lower number is sent first.
	Priority uint8
	// Group names a rendition group: tracks with the same non-empty Group are alternatives of one source.
	Group string
	// Config is the optional codec configuration a decoder needs.
	Config []byte
	// Bitrate is in bits per second, 0 if unknown.
	Bitrate uint64

	// SampleRate, Channels and FrameDuration describe an audio track and are required for one.
	SampleRate    uint32
	Channels      uint8
	FrameDuration time.Duration

	// Width and Height in pixels are required for a video track; FrameRate in frames per second is 0 if unknown.
	Width     uint32
	Height    uint32
	FrameRate float64
}

Track describes one track of a broadcast.

type TrackPublisher

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

TrackPublisher publishes the frames of one track of a Broadcast. Its methods are safe for concurrent use.

func (TrackPublisher) Close
func (p *TrackPublisher) Close() error

Close removes the track from its broadcast, as Broadcast.RemoveTrack. Closing it again, or after the broadcast closed, does nothing.

func (TrackPublisher) KeyframeRequests
func (p *TrackPublisher) KeyframeRequests() <-chan struct{}

KeyframeRequests receives when a watcher asks, with WatchOptions.RequestKeyframes, for a new group. The next frame written must then be a keyframe. Signals merge. Answer with at most one keyframe a second: watchers add up.

func (TrackPublisher) Track
func (p *TrackPublisher) Track() Track

Track returns the track's description as published in the catalog.

func (TrackPublisher) WriteFrame
func (p *TrackPublisher) WriteFrame(f Frame) error

WriteFrame packages f and publishes it, starting a new group where the Packager does. It never waits for subscribers. A failed write leaves only a new group for the next frame, which on a video track must be a keyframe (ErrNeedKeyframe). On a protected broadcast f.AudioLevel is checked and dropped, and the catalog is published again under each new key; a failure there is not the frame's error.

type TrackStats

type TrackStats struct {
	// Received counts the valid frames pushed.
	Received uint64
	// Played counts the frames returned by Next.
	Played uint64
	// Late counts frames dropped for being older than a frame already played or skipped.
	Late uint64
	// Duplicate counts frames dropped for a timestamp already buffered or just played.
	Duplicate uint64
	// Ahead counts frames dropped for arriving more than 2 s earlier than the reference allows.
	Ahead uint64
	// Overflow counts frames dropped because the buffer was over MaxFrames or MaxBytes.
	Overflow uint64
	// Skipped counts frames dropped for being more than MaxBehind late (skip to live).
	Skipped uint64
	// NoKeyframe counts video frames dropped while waiting for a keyframe.
	NoKeyframe uint64
	// Buffered is the number of buffered frames.
	Buffered int
	// BufferedBytes is the size of the buffered frames' data.
	BufferedBytes int
	// WaitingKeyframe reports a video track that needs a keyframe before it can play again.
	WaitingKeyframe bool
}

TrackStats counts the frames of one track.

type TrackWatchStats

type TrackWatchStats struct {
	// Track is the name of the track played, empty if none.
	Track string
	// Subscriptions counts the subscriptions started for this kind, switches and restarts included.
	Subscriptions uint64
	// Gaps counts video groups cut short because an object was missing or malformed.
	Gaps uint64
	// Malformed counts objects that failed Unpack or did not fit the playout.
	Malformed uint64
	// Dropped counts groups the transport dropped because the reader fell behind.
	Dropped uint64
	// NoKey counts objects dropped because their key did not arrive in time.
	NoKey uint64
	// Retired counts objects under a key already retired: later than Retain after a newer key, or
	// under a Key ID older than the keys held.
	Retired uint64
	// Unauthenticated counts objects that failed authentication, were not protected or were replays.
	Unauthenticated uint64
	// KeyframeRequests counts the requests for a new group sent for this kind.
	KeyframeRequests uint64
	// Err is why the last subscription ended, or nil while it runs. Once it ended, Next for its kind
	// blocks until a catalog update lists the track again or selects another, unless the catalog in
	// use still lists it: then it subscribes again at once, under the same catalog only once.
	Err error
}

TrackWatchStats describes the subscription of one kind.

type Unpackager

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

Unpackager turns the LOC objects of one track back into frames. It is safe for concurrent use.

func NewUnpackager
func NewUnpackager(t Track) (*Unpackager, error)

NewUnpackager returns an Unpackager for track t, which must be valid.

func (Unpackager) Unpack
func (u *Unpackager) Unpack(id uint64, props []Property, payload []byte) (Frame, error)

Unpack returns the frame in the object with the given ID in its group; Data is the payload itself and Duration comes from the catalog. Unknown property types are ignored.

type WatchOptions

type WatchOptions struct {
	// Capabilities chooses the tracks to play, as in Select; with no codecs nothing plays.
	Capabilities Capabilities
	// Playout configures the playout; zero fields take their defaults.
	Playout PlayoutConfig
	// CatalogLimits bounds each received catalog; zero fields take their defaults.
	CatalogLimits CatalogLimits
	// Keys, if set, opens every object with its sender's key, drops objects without one, and
	// refuses a session that neither owns the namespace nor is a listed relay. Each subscription
	// opens through its own secobj.Opener, so several watches can share one Keyring.
	Keys *secobj.Keyring
	// RequestKeyframes asks the publisher for a new group, which starts with a keyframe, when the video track
	// waits for one, lost the rest of a group, or gets no frame for 500 ms. Requests are bounded: a request for
	// silence doubles the silence the next needs, and an unanswered one is repeated after 1, 2, 4 and 8 s, then
	// dropped until a frame plays. The publisher must serve it (TrackPublisher.KeyframeRequests). Off by default.
	RequestKeyframes bool
}

WatchOptions configures Watch.

type WatchStats

type WatchStats struct {
	// Playout holds the playout's counters, with the tracks named "audio" and "video".
	Playout PlayoutStats
	// Catalog is the version of the catalog in use; BadCatalogs counts catalog objects that were ignored.
	Catalog     uint64
	BadCatalogs uint64
	Audio       TrackWatchStats
	Video       TrackWatchStats
}

WatchStats is a snapshot of a Watcher.

type Watcher

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

Watcher plays one broadcast received over a MoQ session. Its methods are safe for concurrent use.

func Watch
func Watch(ctx context.Context, s *kolomoq.Session, ns kolomoq.Namespace, opts WatchOptions) (*Watcher, error)

Watch subscribes to the catalog of the broadcast under ns, plays the tracks Select picks and follows catalog updates. It returns once the first catalog arrived, even if it selects nothing yet, and fails if the catalog selects tracks and none of their subscriptions starts. The session stays the caller's. With opts.Keys, Watch fails with an error wrapping secobj.ErrWrongSession unless the session's peer owns ns or is a listed relay, and returns once a catalog that opens arrives.

func (Watcher) Catalog
func (w *Watcher) Catalog() *Catalog

Catalog returns a copy of the catalog in use.

func (Watcher) Close
func (w *Watcher) Close() error

Close stops every subscription and goroutine of the watch; blocked and later Next calls return ErrClosed.

func (Watcher) Next
func (w *Watcher) Next(ctx context.Context, kind Kind) (Frame, Track, error)

Next returns the next frame of the given kind when it is due, and the track it belongs to, whose Config the caller must not modify. It blocks while no track of that kind is selected. After the watch ended it returns an error wrapping ErrBroadcastEnded or ErrSessionEnded, or ErrClosed.

func (Watcher) Stats
func (w *Watcher) Stats() WatchStats

Stats returns a snapshot of the playout and the subscriptions.

func (Watcher) Tracks
func (w *Watcher) Tracks() Selection

Tracks returns the tracks being played.

Good to know

How a frame travels

  1. The application captures and encodes a frame.
  2. Clock stamps it and WriteFrame packages it as a LOC object in a group.
  3. kolo-moq publishes the object on the track, and a relay forwards it.
  4. Watch receives it, restores the order inside a video group and hands it to the Playout.
  5. Next returns it when it is due, with audio and video in sync.
  6. The application decodes and renders it.

With NewSecureBroadcast, the object is sealed before step 3, and Watch opens it before step 4. See Protected media.

Publish

  • NewBroadcast(origin, ns) creates the catalog track under ns in a kolo-moq Origin and publishes catalog version 0. AddTrack(track, opts) adds a track and publishes the next catalog version, RemoveTrack(name) removes one, Catalog returns the current catalog and Close ends every track and the catalog.
  • TrackPublisher.WriteFrame(frame) packages the frame and publishes it without waiting for subscribers. kolo-moq queues per subscriber and drops whole groups for a slow one. Close removes the track.
  • Stamp every track with one Clock: clock.At(time.Now(), timescale) for a capture instant and clock.After(d, timescale) for an offset. Timestamps must increase strictly per track, or WriteFrame returns ErrTimestampOrder.
  • A video track starts with a keyframe. After a failed write the next frame starts a new group, and on a video track it must be a keyframe (ErrNeedKeyframe).
  • TrackPublisher.KeyframeRequests is a channel that fires when a watcher asks for a new group (see Watch). The publisher then writes a keyframe, which starts a new group, so a late joiner or a watcher that lost a group gets a picture within a round trip instead of waiting for the next group. A track nobody asks about never fires. Every watcher asks, so answer with at most one keyframe a second.
  • A zero Track.Priority takes AudioPriority (48) or VideoPriority (68), and the catalog uses CatalogPriority (28). A lower number is sent first, and all three are ahead of a kolo-moq track at the default priority, 128.
  • AddTrack returns an error that wraps ErrInvalidCatalog and kolomoq.ErrObjectTooLarge when the catalog does not fit the origin's MaxObjectSize. The previous catalog stays current.
  • The kolo-moq session and the relay stay yours: Broadcast only writes to the Origin.
  • NewSecureBroadcast(origin, sender) is NewBroadcast with every object, the catalog included, sealed by a kolo-moq secobj.Sender. See Protected media.

Watch

  • Watch(ctx, session, ns, opts) subscribes to the catalog, waits for the first version, plays the tracks Select picks for opts.Capabilities and follows catalog updates. A track that leaves stops, and a better one is switched to, starting at a keyframe.
  • Next(ctx, kind) returns the next due frame of Audio or Video and its Track. It blocks while no track of that kind is selected.
  • Catalog and Tracks return a copy of the catalog in use and of the selection. Stats reports the playout, the catalog version, the ignored catalogs and, per kind, the subscriptions, the cut video groups, the malformed objects, the dropped groups and why the last subscription ended.
  • Close stops the watch and leaves the session usable. The session stays yours.
  • ErrBroadcastEnded means the publisher ended the catalog, or a relay ended it with a PUBLISH_DONE status. An error wrapping ErrSessionEnded means the session ended, and ErrClosed follows Close. Watch fails if the catalog selects tracks and none of their subscriptions starts.
  • Media subscriptions ask kolo-moq for an object delivery timeout of MaxDelay plus MaxBehind, since a later frame can no longer play. Audio subscribes from the next object, and the catalog and video from the current group, so a late joiner starts at a keyframe.
  • WatchOptions.RequestKeyframes makes a watch ask the publisher for a new group, which starts with a keyframe, when its video track waits for one (at the start, or after frames it could not use), loses the rest of a group, or delivers no frame for 500 ms, through kolo-moq's Subscription.RequestNewGroup, which a relay forwards to the publisher. The asking is bounded, so a track that is only quiet (a still screen share, a paused camera) is not asked forever: each request made for silence doubles the silence the next one needs (500 ms, 1 s, 2 s, 4 s, 8 s), and after five of them silence no longer counts until 30 frames have come in a row or a loss is reported. A request that gets no playable frame is repeated after 1 s, 2 s, 4 s and 8 s, and five unanswered requests in a row end the asking until a frame plays. A watch does not ask while the catalog lists no video track. Stats().Video.KeyframeRequests counts the requests sent. It is off by default, because a publisher that does not serve the request gets a REQUEST_UPDATE it has no use for.

Building blocks

These work without kolo-moq.

  • Catalog and Track describe a broadcast. MarshalBinary validates and encodes. ParseCatalog(b, limits) decodes, accepts only the canonical encoding and never panics. The codecs are Opus, PCMS16LE, VP8 and VP9.
  • Clock gives every track of a sender one time base. Rescale, ToDuration and FromDuration convert between timescales, rounding to the nearest unit and reporting overflow with ErrTimestampRange.
  • NewPackager(track, opts) and Pack(frame) return an Object: group, object ID, properties in ascending type order and the frame data as payload. NewUnpackager(track) and Unpack(id, properties, payload) return the frame, or a *PropertyError.
  • NewPlayout(tracks, config) plays the tracks of one broadcast, at most one of them audio. Push(track, frame, arrival) copies a received frame into its buffer, and Next(ctx, track) blocks until the next frame is due. SetOutputLatency delays the other tracks by a device buffer. Stats counts played, late, duplicate, ahead, overflowing, skipped and keyframe-less frames. Close wakes every blocked Next with ErrClosed.
  • Select(catalog, capabilities) picks one audio and one video track the receiver decodes within its size, frame rate and bitrate limits, lowest priority number first, then highest quality, then catalog order. It returns ErrNoMatch when nothing fits.

Playout

  • The reference is the earliest arrival minus media time over the last 2 s of arrivals, across all tracks. A frame stamped T is due at the reference plus T plus the delay.
  • The delay is the 95th percentile of the measured lateness over the same window, between MinDelay and MaxDelay. Outliers under 5% do not raise it.
  • Video also waits for the audio lag of the last audio frame played, so audio paces the clock and video follows.
  • Audio more than MaxBehind late is dropped (Skipped). Late video jumps to its newest due keyframe, or plays its late frames at once if there is none.
  • A frame more than 2 s earlier than the reference allows is dropped (Ahead). A first frame stamped far ahead cannot be told from an honest one: it becomes the reference, and the frames that follow are dropped as Late until the 2 s window passes, so the track is silent for 2 to 3 s and then plays. Only the sender's own track is affected. A frame older than one already played is dropped as Late, and a repeated timestamp as Duplicate. If only older frames arrive for 2 s, the last frame played is taken as the bad one and the older frames play, so after a delivery stall that resumes from an older point one frame can play after a later one. A full buffer evicts its oldest frame (Overflow).
  • A video track waits for a keyframe at start and after it evicted a frame, drops delta frames meanwhile (NoKeyframe) and calls OnKeyframeNeeded once, so the application can ask the publisher for a new group.

Formats

  • A broadcast is a kolo-moq namespace. Its catalog is the track named catalog (CatalogTrack, a reserved name): one group per catalog version, whose group ID is the version, with the encoded catalog as object 0. A new version repeats the whole catalog, with no delta updates. Each media track is the track named by its Track.Name in the same namespace.
  • The catalog encoding is canonical, on kolo-codec: one catalog has exactly one encoding. Format byte 1, then the version and the track count, then each track with its name, kind, codec, timescale, priority, group, config and bitrate, and the audio or video parameters. ParseCatalog rejects non-minimal varints, trailing bytes, unknown kinds and codecs, an unknown format byte (ErrCatalogFormat) and any field the kind does not use.
  • Tracks with the same non-empty Group are alternatives of one source, of one kind and one timescale, and a receiver can switch between them at group boundaries. Changing a track's codec config means a new catalog version.
  • Objects follow draft-ietf-moq-loc-04, and the payload is the codec's frame as is. Properties are TIMESTAMP, TIMESCALE (when the timescale is not 1000000), AUDIO_LEVEL (as RFC 6464), VIDEO_CONFIG and AUDIO_CONFIG (on the first object of a group), written in ascending type order. A video group starts at every keyframe, and an audio group holds one frame, or the frames of AudioGroupDuration.
  • VIDEO_FRAME_MARKING is not written or read: LOC leaves its bit layout to another RFC. Keyframes are known from the group structure.
  • Unpack ignores Immutable Properties (0x0B), which kolo-moq hands over as one property holding their serialized contents, so a LOC property inside them is not read.
  • A protected object is the sealed form of the same object. The plaintext is the vi64 length of the payload, the payload (the codec frame or the encoded catalog) and, when there are properties, the marker 00 0A, a vi64 length and the LOC properties in ascending type order. A relay sees one visible property, Immutable Properties (0x0B) holding the Key ID at type 0x78, and the payload as ciphertext with its 16-byte tag. AUDIO_LEVEL is not written on a protected track, because its size would reveal speech, and the catalog has no properties. A protected object follows the Kolo profile of draft-ietf-moq-secure-objects-01 and does not interoperate with other Secure Objects implementations.

Protected media

NewSecureBroadcast(origin, sender) is NewBroadcast for the namespace of a kolo-moq secobj.Sender. Every object, the catalog included, is sealed before kolo-moq writes it, so a kolo-moq relay forwards it without reading it. WatchOptions.Keys, a secobj.Keyring, makes Watch open every object before anything uses it. The sealing and the keys are described under Protected objects in kolo-moq.

This program is the quick start with the broadcast sealed. Alice gives her key to Bob over the session they already have, and Bob accepts keys for her namespace only from her. They are connected directly, with no relay.

main.go
package main

import (
	"context"
	"crypto/ed25519"
	"errors"
	"fmt"
	"log"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	kolomedia "github.com/ciranda-dev/kolo-media"
	kolomoq "github.com/ciranda-dev/kolo-moq"
	"github.com/ciranda-dev/kolo-moq/secobj"
	kolosecure "github.com/ciranda-dev/kolo-secure"
)

func must[T any](v T, err error) T {
	if err != nil {
		log.Fatal(err)
	}
	return v
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	alice, bob := must(koloid.Generate()), must(koloid.Generate())
	ns := kolomoq.Namespace{"room", "alice"}

	// Alice seals every object with a key that only Bob receives, on a track of its own.
	origin := must(kolomoq.NewOrigin(nil))
	sender := must(secobj.NewSender(origin, ns, nil))
	defer sender.Close()
	broadcast := must(kolomedia.NewSecureBroadcast(origin, sender))
	defer broadcast.Close()
	mic := must(broadcast.AddTrack(kolomedia.Track{
		Name: "mic", Kind: kolomedia.Audio, Codec: kolomedia.PCMS16LE, Timescale: 48000,
		SampleRate: 48000, Channels: 1, FrameDuration: 20 * time.Millisecond,
	}, kolomedia.PackagerOptions{}))
	if err := sender.SetMembers([]ed25519.PublicKey{bob.PublicKey()}); err != nil {
		log.Fatal(err)
	}
	ln := must(kolosecure.Listen(ctx, "127.0.0.1:0", alice, nil))
	defer ln.Close()
	go func() {
		if conn, err := ln.Accept(ctx); err == nil {
			if s, err := kolomoq.NewServer(ctx, conn, &kolomoq.Config{Origin: origin}); err == nil {
				<-s.Done()
			}
		}
	}()
	clock := kolomedia.NewClock()
	go func() {
		for range time.Tick(20 * time.Millisecond) {
			ts, err := clock.At(time.Now(), 48000)
			if err != nil || mic.WriteFrame(kolomedia.Frame{Timestamp: ts, Data: make([]byte, 1920)}) != nil {
				return
			}
		}
	}()

	// Bob accepts keys for alice's namespace only from alice, and opens every object with them.
	keys := must(secobj.NewKeyring(secobj.KeyringConfig{
		Authorize: func(peer ed25519.PublicKey, _ kolomoq.Namespace) error {
			if !peer.Equal(alice.PublicKey()) {
				return errors.New("not the owner of the namespace")
			}
			return nil
		},
	}))
	conn := must(kolosecure.Dial(ctx, ln.Addr().String(), bob, alice.PublicKey(), nil))
	session := must(kolomoq.NewClient(ctx, conn, nil))
	defer session.Close()
	go func() {
		if err := keys.Receive(ctx, session, bob.PublicKey(), ns); err != nil && !errors.Is(err, kolomoq.ErrClosed) && ctx.Err() == nil {
			log.Print(err)
		}
	}()
	caps := kolomedia.Capabilities{Codecs: []kolomedia.Codec{kolomedia.PCMS16LE}}
	watcher := must(kolomedia.Watch(ctx, session, ns, kolomedia.WatchOptions{Capabilities: caps, Keys: keys}))
	defer watcher.Close()
	for range 5 {
		frame, track, err := watcher.Next(ctx, kolomedia.Audio)
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println("play", track.Name, len(frame.Data), "bytes")
	}
	audio := watcher.Stats().Audio
	fmt.Println("no key", audio.NoKey, "retired", audio.Retired, "unauthenticated", audio.Unauthenticated)
}

It prints:

Text
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
no key 0 retired 0 unauthenticated 0

Publish:

  • Make a secobj.Sender for your namespace on the origin your peers read, and call NewSecureBroadcast(origin, sender). The Sender stays yours: Broadcast.Close does not close it.
  • sender.SetMembers(members) takes the participants your application authorizes. Each change rotates the key and sends the new key to every member over your session with it, before the key is used. A removed member opens nothing sealed after SetMembers returned. There is no agreed list of members, so tell the user "X no longer receives your media".
  • Write frames as usual. Frame.AudioLevel is checked and then dropped on a protected track, since its 1 or 2 bytes would reveal speech through the ciphertext size. Receivers compute levels from decoded audio. Use Opus at a constant bitrate with DTX off, so packet sizes do not reveal speech either.
  • After a rotation, the broadcast publishes the catalog again under the new key at once, even while no frame is written, so a member who just joined can read it. If that fails, the next frame tries again. Force a keyframe on each video track when sender.KeyID() changes (sender.Changed() tells when), or a joiner waits for the next one.
  • Removing a track and adding it again restarts its group IDs. The Sender rotates before it seals the new track, so no nonce is used twice.
  • Data tracks of your application, such as reactions, raised hands and chat, go on their own tracks in the same namespace. Write them with sender.Write and read them through keys.Opener(session, ns, track), one per subscription. It fails with secobj.ErrWrongSession unless the session's peer owns ns or is a listed relay, as Watch does.

Watch:

  • Make one secobj.Keyring. Its Authorize says which peer owns which namespace (in a meeting, {room, hex(peer)}), and Relays lists the kolo-moq relays you use. Run keys.Receive for each sender on your session with that sender: keys never travel through a kolo-moq relay.
  • Watch fails with an error wrapping secobj.ErrWrongSession unless the session's peer owns ns or is a listed relay, so a member cannot serve another member's namespace on its own direct session. It returns once a catalog that opens under the sender's key arrives.
  • Each object is opened before its metadata is used. LOC properties come only from the decrypted list. Visible properties and track properties, which a relay can add, are ignored.
  • There is no downgrade: an object without a Key ID is dropped and counted. Decide whether a participant is protected only from keys received on the authenticated session, never from what a relay shows, and play nothing of a participant without keys ("waiting for keys").
  • An object under a Key ID newer than every key held may wait for a key message in flight. It is held for at most PlayoutConfig.MaxDelay, within MaxFrames and MaxBytes, and tried again when the keyring changes. It is dropped only if its key is still missing when it is tried after MaxDelay. Object statuses and the end of the subscription wait behind held objects, so they never overtake them. One catalog object, the newest version, waits for its key until a newer one replaces it. An object under a retired key is dropped at once.
  • Stats counts per kind NoKey (the key did not arrive in time), Retired (the object came after its key was retired, or names a Key ID older than the keys held) and Unauthenticated (failed authentication, was not protected, or was a replay). Catalog objects that do not open count in WatchStats.BadCatalogs.
  • Each subscription opens its objects through its own secobj.Opener, with its own replay window. Several watches of one namespace, and a subscription restarted on a track it already read, share one Keyring.
  • End of Track, End of Group and the PUBLISH_DONE behind ErrBroadcastEnded and ErrTrackEnded are not authenticated: show them as "media stopped", never as "left the call". Presence comes from the session between participants.

What a kolo-moq relay still sees and does:

  • Each participant's address, kolo-id public key and connect times. The namespaces, so the room identifier (use an opaque one) and who publishes which tracks, and who watches whom. Group and Object IDs, priorities and Key IDs, so when each sender rotated and when people joined or left.
  • The size and timing of every object: when each person sends, chat message lengths, video motion and keyframes. Mute and camera off show as tracks that stop or end.
  • It can drop, delay, reorder or withhold objects, end tracks and serve objects to anyone. Without keys that yields nothing readable, and every object it changes fails authentication.

What the libraries do not give:

  • Every member holds every sender's key, and objects are not signed per sender. A member who controls the relay, runs it or colludes with its operator can make audio, video, catalogs and data that seem to come from any other member, without being detected. Through an honest relay with kolomoq.RoomPolicy, and in a direct session, a member cannot.
  • There is no forward secrecy within a key generation and no recovery after a compromise. Anyone in the call can read everyone's media.
  • Keys are never written to disk. Base keys and salts are overwritten when replaced, removed or closed. The AES key schedules and the key messages held in key track caches and transport buffers are released, not overwritten, and Go does not guarantee that no copy remains in memory. Go's AES-GCM is constant time only in its assembly for amd64 and arm64 CPUs with AES instructions, ppc64x and s390x. On other CPUs it is generic code that is not constant time, while Go's TLS then prefers ChaCha20, so object protection is the weakest link there.

Limits

A zero field in a config takes the default. The full tables are in Limits.

  • CatalogLimits: 1024 tracks, 4096-byte names and 65508-byte configs by default, the largest that fits one object property. It can only lower them.
  • PlayoutConfig: MinDelay 100 ms, MaxDelay 400 ms (or MinDelay if larger), MaxBehind 50 ms, MaxFrames 8192 per track and MaxBytes 16 MiB per track. A negative value, or MinDelay over MaxDelay, is ErrInvalidConfig.
  • The catalog track and every media track count against the origin's MaxTracks (1000 by default in kolo-moq), so a default origin stops AddTrack at 999 media tracks with ErrTooManyTracks.
  • MediaGroupTimeout, 30 s: a group not sent 30 s after it ended is no use to a live subscriber and is dropped.
  • A video track holds up to twice MaxFrames and MaxBytes, 32 MiB by default, because the group assembler counts its held objects separately from the playout buffer.
  • At most one audio track per Playout.
  • Protected media: an object whose key may be in flight is held for at most MaxDelay, 400 ms by default. Held objects per track are bounded by MaxFrames and MaxBytes, held statuses by MaxFrames, and one catalog object is held until its key arrives or a newer one replaces it. With the group assembler and the playout, a protected video track can hold up to three times MaxFrames and MaxBytes, 48 MiB by default.
  • A protected audio object is 24 bytes larger than an unprotected one, 9.6 kbit/s at 50 objects per second, and the overhead is under 1 percent for video. The keys are bounded by kolo-moq's secobj (Limits). Calls of up to 20 participants are tested. This is a testing bound, not a cryptographic one, and the library sets no limit.
  • Memory per remote participant: an audio track holds up to 16 MiB in the playout, 32 MiB when protected, and a video track 32 MiB, 48 MiB when protected. A protected participant with audio and video is therefore up to 80 MiB in kolo-media, plus kolo-moq's MaxBufferedBytes (32 MiB by default) for each of its subscriptions. A hostile sender that keeps every bound full costs that much.

Security

  • Every buffer is bounded: the playout buffer by MaxFrames and MaxBytes, the held video objects by the same bounds, and the catalog by CatalogLimits. A frame stamped too far ahead is dropped, and a first frame stamped far ahead mutes only the sender's own track, for 2 to 3 s.
  • A catalog object that fails to parse, is not object 0 or whose version differs from its group ID is ignored and counted in WatchStats.BadCatalogs, and so is a protected catalog object that does not open.
  • The parsers have fuzz targets.
  • A protected watch opens every object before it uses it. An object that fails authentication, has no Key ID or repeats one already opened in its subscription is dropped and counted in Unauthenticated.

Status

  • Done: catalog, LOC packaging, clock, playout, selection, publishing and watching over kolo-moq, with fuzz targets and tests over real connections on 127.0.0.1.
  • Done: protected broadcasts and watches with kolo-moq's secobj. Protected calls of 4, 8 and 20 participants were measured on one laptop on loopback, and the repository's limits page gives the figures and the conditions.
  • Tested on macOS arm64: go vet, go test and go test -race pass and the examples run. Linux and Windows were not run, only cross-vetted.
  • Not done: VIDEO_FRAME_MARKING.
  • Experimental. The API may change before v1.0.0.

Errors

ErrorMessage
ErrBroadcastEndedkolomedia: broadcast ended
ErrBroadcastExistskolomedia: broadcast already exists
ErrBroadcastNotFoundkolomedia: broadcast not found
ErrCatalogFormatkolomedia: unsupported catalog format
ErrClosedkolomedia: closed
ErrDuplicatePropertykolomedia: duplicate property
ErrFrameTooLargekolomedia: frame too large
ErrInvalidCatalogkolomedia: invalid catalog
ErrInvalidConfigkolomedia: invalid configuration
ErrInvalidFramekolomedia: invalid frame
ErrInvalidTimescalekolomedia: invalid timescale
ErrInvalidTrackkolomedia: invalid track
ErrMalformedPropertykolomedia: malformed property
ErrMissingPropertykolomedia: missing property
ErrNeedKeyframekolomedia: video track needs a keyframe
ErrNoMatchkolomedia: no track matches the capabilities
ErrPropertyMismatchkolomedia: property does not match the catalog
ErrSessionEndedkolomedia: session ended
ErrTimestampOrderkolomedia: timestamp not after the previous frame
ErrTimestampRangekolomedia: timestamp out of range
ErrTooManyTrackskolomedia: too many tracks
ErrTrackEndedkolomedia: track ended
ErrUnknownTrackkolomedia: unknown track

Every error starts with kolomedia:. Use errors.Is and errors.As. An error of kolo-moq keeps its cause in the chain under the prefix, so errors.Is(err, kolomoq.ErrObjectTooLarge) and errors.As(err, &requestError) still work. ErrBroadcastNotFound is Watch of a namespace the peer does not publish, and it wraps the kolomoq.RequestError with DOES_NOT_EXIST. ErrBroadcastExists is NewBroadcast where the origin already has the catalog track, and a frame whose object is over the origin's MaxObjectSize is ErrFrameTooLarge. NewSecureBroadcast with a nil Sender is ErrInvalidConfig, a protected Watch on a session that may not carry the namespace wraps secobj.ErrWrongSession, and a frame that cannot be sealed keeps the secobj or kolo-moq error in the chain (kolomoq.ErrClosed once the Sender is closed). Nothing of it is written.

References