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.
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.
- 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.
- 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.
- 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.
- 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.
- 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-mediaTo 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.
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:
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
play mic 1920 bytes
playout delay 100msThe 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 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_000DefaultTimescale is the LOC default: timestamps in microseconds since the Unix epoch.
const MediaGroupTimeout = 30 * time.SecondMediaGroupTimeout 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() *CatalogCatalog returns the catalog last published.
func (Broadcast) Close
func (b *Broadcast) Close() errorClose ends every track and the catalog; subscribers see the broadcast end.
func (Broadcast) RemoveTrack
func (b *Broadcast) RemoveTrack(name string) errorRemoveTrack 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() *ClockNewClock 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.TimeStart returns the instant the clock was made.
type Codec
type Codec stringCodec 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 uint8Kind is the media kind of a track.
const (
Audio Kind = 1
Video Kind = 2
)Track kinds.
func (Kind) String
func (k Kind) String() stringString 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() errorClose 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) errorPush 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) errorSetOutputLatency 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() PlayoutStatsStats 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() stringError returns the message with the property type in hex.
func (PropertyError) Unwrap
func (e *PropertyError) Unwrap() errorUnwrap 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() errorClose 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() TrackTrack returns the track's description as published in the catalog.
func (TrackPublisher) WriteFrame
func (p *TrackPublisher) WriteFrame(f Frame) errorWriteFrame 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() *CatalogCatalog returns a copy of the catalog in use.
func (Watcher) Close
func (w *Watcher) Close() errorClose 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() WatchStatsStats returns a snapshot of the playout and the subscriptions.
func (Watcher) Tracks
func (w *Watcher) Tracks() SelectionTracks returns the tracks being played.
Good to know
How a frame travels
- The application captures and encodes a frame.
Clockstamps it andWriteFramepackages it as a LOC object in a group.- kolo-moq publishes the object on the track, and a relay forwards it.
Watchreceives it, restores the order inside a video group and hands it to thePlayout.Nextreturns it when it is due, with audio and video in sync.- 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 undernsin a kolo-moqOriginand publishes catalog version 0.AddTrack(track, opts)adds a track and publishes the next catalog version,RemoveTrack(name)removes one,Catalogreturns the current catalog andCloseends 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.Closeremoves the track.- Stamp every track with one
Clock:clock.At(time.Now(), timescale)for a capture instant andclock.After(d, timescale)for an offset. Timestamps must increase strictly per track, orWriteFramereturnsErrTimestampOrder. - 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.KeyframeRequestsis 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.PrioritytakesAudioPriority(48) orVideoPriority(68), and the catalog usesCatalogPriority(28). A lower number is sent first, and all three are ahead of a kolo-moq track at the default priority, 128. AddTrackreturns an error that wrapsErrInvalidCatalogandkolomoq.ErrObjectTooLargewhen the catalog does not fit the origin'sMaxObjectSize. The previous catalog stays current.- The kolo-moq session and the relay stay yours:
Broadcastonly writes to theOrigin. NewSecureBroadcast(origin, sender)isNewBroadcastwith every object, the catalog included, sealed by a kolo-moqsecobj.Sender. See Protected media.
Watch
Watch(ctx, session, ns, opts)subscribes to the catalog, waits for the first version, plays the tracksSelectpicks foropts.Capabilitiesand 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 ofAudioorVideoand itsTrack. It blocks while no track of that kind is selected.CatalogandTracksreturn a copy of the catalog in use and of the selection.Statsreports 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.Closestops the watch and leaves the session usable. The session stays yours.ErrBroadcastEndedmeans the publisher ended the catalog, or a relay ended it with a PUBLISH_DONE status. An error wrappingErrSessionEndedmeans the session ended, andErrClosedfollowsClose.Watchfails if the catalog selects tracks and none of their subscriptions starts.- Media subscriptions ask kolo-moq for an object delivery timeout of
MaxDelayplusMaxBehind, 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.RequestKeyframesmakes 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'sSubscription.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.KeyframeRequestscounts 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.
CatalogandTrackdescribe a broadcast.MarshalBinaryvalidates and encodes.ParseCatalog(b, limits)decodes, accepts only the canonical encoding and never panics. The codecs areOpus,PCMS16LE,VP8andVP9.Clockgives every track of a sender one time base.Rescale,ToDurationandFromDurationconvert between timescales, rounding to the nearest unit and reporting overflow withErrTimestampRange.NewPackager(track, opts)andPack(frame)return anObject: group, object ID, properties in ascending type order and the frame data as payload.NewUnpackager(track)andUnpack(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, andNext(ctx, track)blocks until the next frame is due.SetOutputLatencydelays the other tracks by a device buffer.Statscounts played, late, duplicate, ahead, overflowing, skipped and keyframe-less frames.Closewakes every blockedNextwithErrClosed.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 returnsErrNoMatchwhen 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
MinDelayandMaxDelay. 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
MaxBehindlate 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 asLateuntil 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 asLate, and a repeated timestamp asDuplicate. 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 callsOnKeyframeNeededonce, 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 itsTrack.Namein 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.
ParseCatalogrejects 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
Groupare 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.
Unpackignores 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.
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:
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 0Publish:
- Make a
secobj.Senderfor your namespace on the origin your peers read, and callNewSecureBroadcast(origin, sender). The Sender stays yours:Broadcast.Closedoes 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 afterSetMembersreturned. There is no agreed list of members, so tell the user "X no longer receives your media".- Write frames as usual.
Frame.AudioLevelis 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.Writeand read them throughkeys.Opener(session, ns, track), one per subscription. It fails withsecobj.ErrWrongSessionunless the session's peer ownsnsor is a listed relay, asWatchdoes.
Watch:
- Make one
secobj.Keyring. ItsAuthorizesays which peer owns which namespace (in a meeting,{room, hex(peer)}), andRelayslists the kolo-moq relays you use. Runkeys.Receivefor each sender on your session with that sender: keys never travel through a kolo-moq relay. Watchfails with an error wrappingsecobj.ErrWrongSessionunless the session's peer ownsnsor 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, withinMaxFramesandMaxBytes, and tried again when the keyring changes. It is dropped only if its key is still missing when it is tried afterMaxDelay. 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. Statscounts per kindNoKey(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) andUnauthenticated(failed authentication, was not protected, or was a replay). Catalog objects that do not open count inWatchStats.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
ErrBroadcastEndedandErrTrackEndedare 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:MinDelay100 ms,MaxDelay400 ms (orMinDelayif larger),MaxBehind50 ms,MaxFrames8192 per track andMaxBytes16 MiB per track. A negative value, orMinDelayoverMaxDelay, isErrInvalidConfig.- The catalog track and every media track count against the origin's
MaxTracks(1000 by default in kolo-moq), so a default origin stopsAddTrackat 999 media tracks withErrTooManyTracks. 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
MaxFramesandMaxBytes, 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 byMaxFramesandMaxBytes, held statuses byMaxFrames, 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 timesMaxFramesandMaxBytes, 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
MaxFramesandMaxBytes, the held video objects by the same bounds, and the catalog byCatalogLimits. 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 testandgo test -racepass 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
| Error | Message |
|---|---|
ErrBroadcastEnded | kolomedia: broadcast ended |
ErrBroadcastExists | kolomedia: broadcast already exists |
ErrBroadcastNotFound | kolomedia: broadcast not found |
ErrCatalogFormat | kolomedia: unsupported catalog format |
ErrClosed | kolomedia: closed |
ErrDuplicateProperty | kolomedia: duplicate property |
ErrFrameTooLarge | kolomedia: frame too large |
ErrInvalidCatalog | kolomedia: invalid catalog |
ErrInvalidConfig | kolomedia: invalid configuration |
ErrInvalidFrame | kolomedia: invalid frame |
ErrInvalidTimescale | kolomedia: invalid timescale |
ErrInvalidTrack | kolomedia: invalid track |
ErrMalformedProperty | kolomedia: malformed property |
ErrMissingProperty | kolomedia: missing property |
ErrNeedKeyframe | kolomedia: video track needs a keyframe |
ErrNoMatch | kolomedia: no track matches the capabilities |
ErrPropertyMismatch | kolomedia: property does not match the catalog |
ErrSessionEnded | kolomedia: session ended |
ErrTimestampOrder | kolomedia: timestamp not after the previous frame |
ErrTimestampRange | kolomedia: timestamp out of range |
ErrTooManyTracks | kolomedia: too many tracks |
ErrTrackEnded | kolomedia: track ended |
ErrUnknownTrack | kolomedia: 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
- Low Overhead Media Container, draft-ietf-moq-loc-04 (Internet-Draft, July 2026, expires 21 January 2027).
- Takes: the LOC object properties.
- Not implemented: VIDEO_FRAME_MARKING. Revision 05 (2 November 2026) exists and is not followed.
- RFC 6464, RTP Header Extension for Client-to-Mixer Audio Level Indication (Proposed Standard, December 2011).
- Takes: the AUDIO_LEVEL value: voice flag 0x80, level 0 to 127 in -dBov.
- Not implemented: the RTP header extension.
- RFC 9626, Video Frame Marking RTP Header Extension (Experimental, March 2025).
- Takes: nothing.
- Not implemented: all of it. It is not written or read.
- Media over QUIC Transport, draft-ietf-moq-transport-22 (Internet-Draft, October 2026, expires 4 April 2027).
- Takes: the transport, through kolo-moq.
- Not implemented: see the References of kolo-moq.
- End-to-End Secure Objects for Media over QUIC Transport, draft-ietf-moq-secure-objects-01 (Internet-Draft, July 2026, expires 7 January 2027, still the current revision).
- Takes: the Kolo profile of protected objects, through kolo-moq.
- Not implemented: see the References of kolo-moq.
- RFC 6716, Definition of the Opus Audio Codec (Proposed Standard, September 2012, updated by RFC 8251).
- Takes: the Opus codec identity in the catalog.
- Not implemented: nothing left out.