kolo docsbeta

kolo-media

Um catálogo, empacotamento LOC, um relógio, a reprodução e a sincronia de áudio e vídeo para broadcasts sobre a kolo-moq. Ela trabalha com frames já codificados e é Go puro. Um broadcast pode ser selado para que um relay da kolo-moq o repasse sem lê-lo.

Nesta página

A kolo-media fica entre os seus codecs e a kolo-moq. Quem envia descreve os seus tracks em um catálogo, carimba os frames com um único relógio e os publica como objetos LOC (Low Overhead Media Container, draft-ietf-moq-loc-04). Quem recebe lê o catálogo, assina os tracks que consegue decodificar e toca os frames por um jitter buffer, com áudio e vídeo em sincronia, acompanhando as atualizações do catálogo. Ela trabalha só com frames já codificados: captura, codecs e saída ficam na sua aplicação. Um broadcast também pode ser selado de ponta a ponta com o secobj da kolo-moq, para que um relay o repasse sem conseguir lê-lo. O pacote Go se chama kolomedia.

Todos os passos

Um broadcast, do catálogo à reprodução

O catálogo lista os tracks. O receptor toca os que consegue decodificar, e o áudio e o vídeo ficam em sincronia.

  1. Um broadcast é um namespace da kolo-moq. O catálogo dele é um track com um grupo para cada versão e lista os outros tracks do broadcast.
  2. Cada track de áudio ou vídeo é outro track do mesmo namespace. Um único Clock carimba cada frame, e o WriteFrame o publica sem esperar pelos assinantes. Um número de prioridade menor é enviado antes.
  3. O Watch assina o catálogo e o Select escolhe um track de áudio e um de vídeo que o receptor consegue decodificar. Uma nova versão do catálogo pode mudar a escolha.
  4. Cada track escolhido entra no próprio jitter buffer do Playout, que reordena os frames, descarta os duplicados e os atrasados e define um atraso a partir do jitter que mede, entre 100 ms e 400 ms por padrão.
  5. O áudio dita o relógio e o vídeo segue o áudio que foi realmente tocado, então os dois ficam em sincronia. O Next devolve cada frame quando chega a hora.

Instalação

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

Para fixar esta versão, rode go get github.com/ciranda-dev/kolo-media@v0.1.0. Ela é Go puro, sem cgo e sem nada para instalar, então compila com CGO_ENABLED=0. Precisa do Go 1.26 ou mais novo. Ela depende da kolo-moq v0.1.0, que o go get instala junto.

Início rápido

Este programa publica um track de áudio e o assiste em 127.0.0.1, com mídia gerada. A Alice publica um broadcast com um track de áudio e o serve, e um relógio carimba os frames dela, cada um com 20 ms de silêncio. O Bob se conecta a ela e toca o que o catálogo dela oferece: ele pede só o codec PCMS16LE, então o Select escolhe o track da Alice.

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)
}

Ele imprime:

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

O repositório também traz examples/publish, que roda um relay e publica por ele um tom gerado e um track de vídeo, e examples/watch, que assiste a esse broadcast e imprime a cada segundo os frames, o nível do tom e o desvio entre áudio e vídeo.

Referência da API

A referência da API é gerada a partir do código Go e está em inglês.

Pacote 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.

Constantes

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.

Variáveis

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")
)

Funções

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.

Tipos

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.

Bom saber

Como um frame viaja

  1. A aplicação captura e codifica um frame.
  2. O Clock o carimba e o WriteFrame o empacota como um objeto LOC em um grupo.
  3. A kolo-moq publica o objeto no track, e um relay o repassa.
  4. O Watch o recebe, restaura a ordem dentro de um grupo de vídeo e o entrega ao Playout.
  5. O Next o devolve quando chega a hora, com áudio e vídeo em sincronia.
  6. A aplicação o decodifica e o exibe.

Com NewSecureBroadcast, o objeto é selado antes do passo 3, e o Watch o abre antes do passo 4. Veja Mídia protegida.

Publicar

  • NewBroadcast(origin, ns) cria o track de catálogo sob ns em um Origin da kolo-moq e publica a versão 0 do catálogo. AddTrack(track, opts) acrescenta um track e publica a próxima versão do catálogo, RemoveTrack(name) remove um, Catalog devolve o catálogo atual e Close encerra todos os tracks e o catálogo.
  • TrackPublisher.WriteFrame(frame) empacota o frame e o publica sem esperar pelos assinantes. A kolo-moq enfileira por assinante e descarta grupos inteiros para um assinante lento. Close remove o track.
  • Carimbe todos os tracks com um único Clock: clock.At(time.Now(), timescale) para um instante de captura e clock.After(d, timescale) para um deslocamento. Os carimbos de tempo precisam crescer estritamente em cada track, ou o WriteFrame devolve ErrTimestampOrder.
  • Um track de vídeo começa com um keyframe. Depois de uma escrita que falhou, o frame seguinte começa um grupo novo, e em um track de vídeo ele precisa ser um keyframe (ErrNeedKeyframe).
  • TrackPublisher.KeyframeRequests é um canal que dispara quando um espectador pede um grupo novo (veja Assistir). O publicador então escreve um keyframe, que começa um grupo novo, então quem entra tarde ou um espectador que perdeu um grupo recebe uma imagem em um tempo de ida e volta em vez de esperar o próximo grupo. Um track sobre o qual ninguém pergunta nunca dispara. Todo mundo que assiste pede, então responda com no máximo um keyframe por segundo.
  • Um Track.Priority em zero assume AudioPriority (48) ou VideoPriority (68), e o catálogo usa CatalogPriority (28). Um número menor é enviado antes, e os três ficam à frente de um track da kolo-moq com a prioridade padrão, 128.
  • AddTrack devolve um erro que embrulha ErrInvalidCatalog e kolomoq.ErrObjectTooLarge quando o catálogo não cabe no MaxObjectSize do origin. O catálogo anterior continua sendo o atual.
  • A sessão da kolo-moq e o relay continuam sendo seus: o Broadcast só escreve no Origin.
  • NewSecureBroadcast(origin, sender) é o NewBroadcast com cada objeto, o catálogo inclusive, selado por um secobj.Sender da kolo-moq. Veja Mídia protegida.

Assistir

  • Watch(ctx, session, ns, opts) assina o catálogo, espera a primeira versão, toca os tracks que o Select escolhe para opts.Capabilities e acompanha as atualizações do catálogo. Um track que sai deixa de ser tocado, e a troca para um melhor começa em um keyframe.
  • Next(ctx, kind) devolve o próximo frame devido de Audio ou Video e o Track dele. Ele bloqueia enquanto nenhum track desse tipo estiver escolhido.
  • Catalog e Tracks devolvem uma cópia do catálogo em uso e da seleção. Stats informa o playout, a versão do catálogo, os catálogos ignorados e, por tipo, as assinaturas, os grupos de vídeo cortados, os objetos malformados, os grupos descartados e por que a última assinatura terminou.
  • Close para de assistir e deixa a sessão utilizável. A sessão continua sendo sua.
  • ErrBroadcastEnded significa que o publicador encerrou o catálogo, ou que um relay o encerrou com um estado PUBLISH_DONE. Um erro que embrulha ErrSessionEnded significa que a sessão terminou, e ErrClosed vem depois de Close. O Watch falha se o catálogo escolhe tracks e nenhuma das assinaturas deles começa.
  • As assinaturas de mídia pedem à kolo-moq um timeout de entrega de objetos de MaxDelay mais MaxBehind, porque um frame posterior já não pode ser tocado. O áudio assina a partir do próximo objeto, e o catálogo e o vídeo a partir do grupo atual, então quem chega tarde começa em um keyframe.
  • WatchOptions.RequestKeyframes faz uma exibição pedir ao publicador um grupo novo, que começa com um keyframe, quando o track de vídeo dela espera por um (no início, ou depois de frames que não conseguiu usar), perde o resto de um grupo ou não entrega nenhum frame por 500 ms, pela Subscription.RequestNewGroup da kolo-moq, que um relay repassa ao publicador. Os pedidos são limitados, então um track que só está parado (um compartilhamento de tela parado, uma câmera em pausa) não recebe pedidos para sempre: cada pedido feito por silêncio dobra o silêncio de que o próximo precisa (500 ms, 1 s, 2 s, 4 s, 8 s), e depois de cinco deles o silêncio deixa de contar até chegarem 30 frames seguidos ou uma perda ser informada. Um pedido que não recebe nenhum frame reproduzível é repetido depois de 1 s, 2 s, 4 s e 8 s, e cinco pedidos sem resposta seguidos encerram os pedidos até um frame tocar. Uma exibição não pede enquanto o catálogo não lista nenhum track de vídeo. Stats().Video.KeyframeRequests conta as requisições enviadas. Vem desligado, porque um publicador que não atende a requisição recebe um REQUEST_UPDATE que não lhe serve.

Peças avulsas

Funcionam sem a kolo-moq.

  • Catalog e Track descrevem um broadcast. MarshalBinary valida e codifica. ParseCatalog(b, limits) decodifica, aceita só a codificação canônica e nunca entra em pânico. Os codecs são Opus, PCMS16LE, VP8 e VP9.
  • Clock dá a todos os tracks de quem envia uma única base de tempo. Rescale, ToDuration e FromDuration convertem entre escalas de tempo, arredondando para a unidade mais próxima e informando o estouro com ErrTimestampRange.
  • NewPackager(track, opts) e Pack(frame) devolvem um Object: grupo, ID do objeto, propriedades em ordem crescente de tipo e os dados do frame como payload. NewUnpackager(track) e Unpack(id, properties, payload) devolvem o frame, ou um *PropertyError.
  • NewPlayout(tracks, config) toca os tracks de um broadcast, no máximo um deles de áudio. Push(track, frame, arrival) copia um frame recebido para o buffer dele, e Next(ctx, track) bloqueia até chegar a hora do próximo frame. SetOutputLatency atrasa os outros tracks pelo buffer de um dispositivo. Stats conta os frames tocados, atrasados, duplicados, adiantados, estourados, pulados e sem keyframe. Close acorda com ErrClosed cada Next bloqueado.
  • Select(catalog, capabilities) escolhe um track de áudio e um de vídeo que o receptor decodifica dentro dos seus limites de tamanho, de taxa de frames e de bitrate: primeiro o menor número de prioridade, depois a maior qualidade e depois a ordem do catálogo. Devolve ErrNoMatch quando nada serve.

Reprodução

  • A referência é a chegada mais cedo menos o tempo da mídia, nos últimos 2 s de chegadas, entre todos os tracks. Um frame carimbado com T deve ser tocado na referência mais T mais o atraso.
  • O atraso é o percentil 95 do atraso medido na mesma janela, entre MinDelay e MaxDelay. Valores atípicos de menos de 5% não o aumentam.
  • O vídeo também espera o atraso do último frame de áudio tocado, então o áudio dita o relógio e o vídeo o segue.
  • O áudio que chega com mais de MaxBehind de atraso é descartado (Skipped). O vídeo atrasado pula para o keyframe devido mais recente, ou toca de uma vez os frames atrasados se não houver nenhum.
  • Um frame que chega com mais de 2 s de antecedência sobre o que a referência permite é descartado (Ahead). Um primeiro frame carimbado muito adiante não se distingue de um honesto: ele vira a referência, e os frames seguintes são descartados como Late até a janela de 2 s passar, então o track fica em silêncio por 2 a 3 s e depois toca. Só o track do próprio emissor é afetado. Um frame mais antigo que um já tocado é descartado como Late, e um carimbo repetido como Duplicate. Se durante 2 s só chegam frames mais antigos, o último frame tocado é tomado como o errado e os frames mais antigos são tocados, então, depois de uma parada de entrega que retoma de um ponto anterior, um frame pode ser tocado depois de um posterior. Um buffer cheio expulsa o frame mais antigo (Overflow).
  • Um track de vídeo espera um keyframe no início e depois de expulsar um frame, descarta nesse meio-tempo os frames delta (NoKeyframe) e chama OnKeyframeNeeded uma vez, para que a aplicação possa pedir um grupo novo ao publicador.

Formatos

  • Um broadcast é um namespace da kolo-moq. O catálogo dele é o track chamado catalog (CatalogTrack, um nome reservado): um grupo por versão do catálogo, cujo ID de grupo é a versão, com o catálogo codificado como objeto 0. Uma versão nova repete o catálogo inteiro, sem atualizações delta. Cada track de mídia é o track nomeado pelo seu Track.Name no mesmo namespace.
  • A codificação do catálogo é canônica, sobre a kolo-codec: um catálogo tem exatamente uma codificação. Byte de formato 1, depois a versão e o número de tracks, depois cada track com o seu nome, tipo, codec, escala de tempo, prioridade, grupo, config e bitrate, e os parâmetros de áudio ou de vídeo. O ParseCatalog rejeita varints não mínimos, bytes sobrando, tipos e codecs desconhecidos, um byte de formato desconhecido (ErrCatalogFormat) e qualquer campo que o tipo não usa.
  • Tracks com o mesmo Group não vazio são alternativas de uma mesma fonte, de um tipo e uma escala de tempo, e quem recebe pode trocar entre eles nos limites de grupo. Mudar a config do codec de um track significa uma nova versão do catálogo.
  • Os objetos seguem o draft-ietf-moq-loc-04, e o payload é o frame do codec como está. As propriedades são TIMESTAMP, TIMESCALE (quando a escala de tempo não é 1000000), AUDIO_LEVEL (conforme a RFC 6464), VIDEO_CONFIG e AUDIO_CONFIG (no primeiro objeto de um grupo), escritas em ordem crescente de tipo. Um grupo de vídeo começa em cada keyframe, e um grupo de áudio tem um frame, ou os frames de AudioGroupDuration.
  • VIDEO_FRAME_MARKING não é escrito nem lido: o LOC deixa o layout de bits dele para outra RFC. Os keyframes são conhecidos pela estrutura dos grupos.
  • O Unpack ignora as Immutable Properties (0x0B), que a kolo-moq entrega como uma única propriedade com o conteúdo serializado delas, então uma propriedade LOC dentro delas não é lida.
  • Um objeto protegido é a forma selada do mesmo objeto. O texto claro é o comprimento vi64 do payload, o payload (o frame do codec ou o catálogo codificado) e, quando há propriedades, a marca 00 0A, um comprimento vi64 e as propriedades LOC em ordem crescente de tipo. Um relay vê uma propriedade visível, as Immutable Properties (0x0B) com o Key ID no tipo 0x78, e o payload como texto cifrado com a sua etiqueta de 16 bytes. O AUDIO_LEVEL não é escrito em um track protegido, porque o tamanho dele revelaria a voz, e o catálogo não tem propriedades. Um objeto protegido segue o perfil da Kolo do draft-ietf-moq-secure-objects-01 e não interopera com outras implementações de Secure Objects.

Mídia protegida

NewSecureBroadcast(origin, sender) é o NewBroadcast para o namespace de um secobj.Sender da kolo-moq. Cada objeto, o catálogo inclusive, é selado antes de a kolo-moq escrevê-lo, então um relay da kolo-moq o repassa sem lê-lo. WatchOptions.Keys, um secobj.Keyring, faz o Watch abrir cada objeto antes de qualquer coisa usá-lo. A selagem e as chaves estão descritas em Objetos protegidos, na kolo-moq.

Este programa é o início rápido com o broadcast selado. A Alice entrega a chave dela ao Bob pela sessão que eles já têm, e o Bob aceita chaves para o namespace dela só dela. Eles estão conectados diretamente, sem 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)
}

Ele imprime:

Texto
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

Publicar:

  • Crie um secobj.Sender para o seu namespace no origin que os seus peers leem e chame NewSecureBroadcast(origin, sender). O Sender continua sendo seu: Broadcast.Close não o fecha.
  • sender.SetMembers(members) recebe os participantes que a sua aplicação autoriza. Cada mudança faz a rotação da chave e envia a nova a cada membro pela sua sessão com ele, antes de usá-la. Um membro removido não abre nada selado depois que SetMembers retornou. Não há uma lista de membros combinada, então diga ao usuário "X não recebe mais a sua mídia".
  • Escreva os frames como de costume. Frame.AudioLevel é conferido e depois descartado em um track protegido, porque os 1 ou 2 bytes dele revelariam a voz pelo tamanho do texto cifrado. Os receptores calculam os níveis a partir do áudio decodificado. Use Opus com taxa de bits constante e DTX desligado, para que os tamanhos dos pacotes também não revelem a voz.
  • Depois de uma rotação, o broadcast publica o catálogo de novo com a chave nova na hora, mesmo sem nenhum frame sendo escrito, para que um membro que acabou de entrar consiga lê-lo. Se isso falhar, o próximo frame tenta de novo. Force um keyframe em cada track de vídeo quando sender.KeyID() mudar (sender.Changed() avisa), ou quem entra espera o próximo.
  • Remover um track e adicioná-lo de novo reinicia os IDs de grupo dele. O Sender faz a rotação antes de selar o track novo, então nenhum nonce se repete.
  • Os tracks de dados da sua aplicação, como reações, mãos levantadas e chat, vão em tracks próprios do mesmo namespace. Escreva-os com sender.Write e leia-os com keys.Opener(session, ns, track), um por assinatura. Ele falha com secobj.ErrWrongSession a menos que o peer da sessão seja o dono de ns ou um relay da lista, como o Watch faz.

Assistir:

  • Crie um único secobj.Keyring. O Authorize dele diz qual peer é dono de qual namespace (em uma reunião, {room, hex(peer)}), e Relays lista os relays da kolo-moq que você usa. Rode keys.Receive para cada remetente na sua sessão com esse remetente: as chaves nunca viajam por um relay da kolo-moq.
  • O Watch falha com um erro que embrulha secobj.ErrWrongSession a menos que o peer da sessão seja o dono de ns ou um relay da lista, então um membro não consegue servir o namespace de outro membro na sua própria sessão direta. Ele retorna quando chega um catálogo que abre com a chave do remetente.
  • Cada objeto é aberto antes de os seus metadados serem usados. As propriedades LOC vêm só da lista decifrada. As propriedades visíveis e as propriedades do track, que um relay pode acrescentar, são ignoradas.
  • Não há rebaixamento: um objeto sem Key ID é descartado e contado. Decida se um participante está protegido só pelas chaves recebidas na sessão autenticada, nunca pelo que um relay mostra, e não toque nada de um participante sem chaves ("esperando chaves").
  • Um objeto com um Key ID mais novo que todas as chaves que se têm pode esperar uma mensagem de chave a caminho. Ele é retido no máximo por PlayoutConfig.MaxDelay, dentro de MaxFrames e MaxBytes, e tentado de novo quando o keyring muda. Ele só é descartado se a chave dele ainda faltar quando for tentado depois de MaxDelay. Os estados de objeto e o fim da assinatura esperam atrás dos objetos retidos, então nunca passam na frente. Um objeto de catálogo, o da versão mais nova, espera a chave dele até ser substituído por um mais novo. Um objeto com uma chave aposentada é descartado na hora.
  • O Stats conta por tipo NoKey (a chave não chegou a tempo), Retired (o objeto chegou depois de a chave dele ser aposentada, ou nomeia um Key ID mais antigo que as chaves que se têm) e Unauthenticated (falhou na autenticação, não era protegido, ou era uma repetição). Os objetos de catálogo que não abrem contam em WatchStats.BadCatalogs.
  • Cada assinatura abre os seus objetos pelo seu próprio secobj.Opener, com a sua própria janela de repetições. Vários Watch de um mesmo namespace, e uma assinatura reiniciada em um track que já leu, compartilham um Keyring.
  • End of Track, End of Group e o PUBLISH_DONE por trás de ErrBroadcastEnded e ErrTrackEnded não são autenticados: mostre-os como "a mídia parou", nunca como "saiu da chamada". A presença vem da sessão entre os participantes.

O que um relay da kolo-moq ainda vê e faz:

  • O endereço, a chave pública kolo-id e os horários de conexão de cada participante. Os namespaces, ou seja, o identificador da sala (use um opaco) e quem publica quais tracks, e quem assiste a quem. Os Group ID e Object ID, as prioridades e os Key ID, ou seja, quando cada remetente fez a rotação e quando as pessoas entraram ou saíram.
  • O tamanho e os tempos de cada objeto: quando cada pessoa envia, o comprimento das mensagens de chat, o movimento do vídeo e os keyframes. Microfone mudo e câmera desligada aparecem como tracks que param ou terminam.
  • Ele pode descartar, atrasar, reordenar ou reter objetos, encerrar tracks e servir objetos a qualquer um. Sem as chaves isso não produz nada legível, e todo objeto que ele altera falha na autenticação.

O que as bibliotecas não dão:

  • Todo membro tem a chave de cada remetente, e os objetos não são assinados por remetente. Um membro que controla o relay, o roda ou se alia ao operador dele pode criar áudio, vídeo, catálogos e dados que parecem vir de qualquer outro membro, sem ser detectado. Por um relay honesto com kolomoq.RoomPolicy, e em uma sessão direta, um membro não consegue.
  • Não há sigilo futuro dentro de uma geração de chave nem recuperação depois de um comprometimento. Qualquer pessoa na chamada pode ler a mídia de todos.
  • As chaves nunca são gravadas em disco. As chaves base e os sais são sobrescritos quando substituídos, removidos ou fechados. Os key schedules do AES e as mensagens de chave guardadas em caches de tracks de chaves e em buffers do transporte são liberados, não sobrescritos, e o Go não garante que nenhuma cópia fique na memória. O AES-GCM do Go é de tempo constante só no seu assembly para CPUs amd64 e arm64 com instruções AES, ppc64x e s390x. Em outras CPUs ele é código genérico que não é de tempo constante, enquanto o TLS do Go então prefere ChaCha20, então a proteção dos objetos é o elo mais fraco ali.

Limites

Um campo em zero de uma config assume o padrão. As tabelas completas estão em Limites.

  • CatalogLimits: 1024 tracks, nomes de 4096 bytes e configs de 65508 bytes por padrão, o máximo que cabe em uma propriedade de objeto. Ele só pode baixá-los.
  • PlayoutConfig: MinDelay 100 ms, MaxDelay 400 ms (ou MinDelay se for maior), MaxBehind 50 ms, MaxFrames 8192 por track e MaxBytes 16 MiB por track. Um valor negativo, ou MinDelay maior que MaxDelay, é ErrInvalidConfig.
  • O track de catálogo e cada track de mídia contam para o MaxTracks do origin (1000 por padrão na kolo-moq), então um origin padrão faz o AddTrack parar em 999 tracks de mídia com ErrTooManyTracks.
  • MediaGroupTimeout, 30 s: um grupo que não foi enviado 30 s depois de terminar não serve a um assinante ao vivo e é descartado.
  • Um track de vídeo retém até o dobro de MaxFrames e MaxBytes, 32 MiB por padrão, porque o montador de grupos conta os objetos retidos separadamente do buffer do playout.
  • No máximo um track de áudio por Playout.
  • Mídia protegida: um objeto cuja chave pode estar a caminho é retido no máximo por MaxDelay, 400 ms por padrão. Os objetos retidos por track são limitados por MaxFrames e MaxBytes, os estados retidos por MaxFrames, e um objeto de catálogo fica retido até chegar a chave dele ou um mais novo o substituir. Com o montador de grupos e o playout, um track de vídeo protegido pode reter até três vezes MaxFrames e MaxBytes, 48 MiB por padrão.
  • Um objeto de áudio protegido tem 24 bytes a mais que um sem proteção, 9,6 kbit/s a 50 objetos por segundo, e o custo extra é de menos de 1 por cento no vídeo. As chaves são limitadas pelo secobj da kolo-moq (Limites). Chamadas de até 20 participantes são testadas. É um limite de teste, não criptográfico, e a biblioteca não define nenhum.
  • Memória por participante remoto: um track de áudio retém até 16 MiB no playout, 32 MiB quando protegido, e um track de vídeo 32 MiB, 48 MiB quando protegido. Um participante protegido com áudio e vídeo ocupa então até 80 MiB na kolo-media, mais o MaxBufferedBytes da kolo-moq (32 MiB por padrão) para cada uma das assinaturas dele. Um emissor hostil que mantém todos os limites cheios custa tudo isso.

Segurança

  • Todo buffer é limitado: o buffer do playout por MaxFrames e MaxBytes, os objetos de vídeo retidos pelos mesmos limites e o catálogo por CatalogLimits. Um frame carimbado muito adiante é descartado, e um primeiro frame carimbado muito adiante só silencia o track do próprio emissor, por 2 a 3 s.
  • Um objeto de catálogo que não pode ser interpretado, que não é o objeto 0 ou cuja versão difere do ID do grupo é ignorado e contado em WatchStats.BadCatalogs, e o mesmo vale para um objeto de catálogo protegido que não abre.
  • Os analisadores têm fuzz targets.
  • Um Watch protegido abre cada objeto antes de usá-lo. Um objeto que falha na autenticação, não tem Key ID ou repete um já aberto na sua assinatura é descartado e contado em Unauthenticated.

Estado

  • Feito: catálogo, empacotamento LOC, relógio, playout, seleção, publicar e assistir sobre a kolo-moq, com fuzz targets e testes sobre conexões reais em 127.0.0.1.
  • Feito: broadcasts e Watch protegidos com o secobj da kolo-moq. Chamadas protegidas de 4, 8 e 20 participantes foram medidas em um notebook por loopback, e a página de limites do repositório traz os números e as condições.
  • Testada no macOS arm64: go vet, go test e go test -race passam, e os exemplos rodam. Linux e Windows não foram executados, só conferidos com go vet entre plataformas.
  • Não feito: VIDEO_FRAME_MARKING.
  • Experimental. A API pode mudar antes da v1.0.0.

Erros

ErroMensagem
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

Todos os erros começam com kolomedia:. Use errors.Is e errors.As. Um erro da kolo-moq mantém a causa na cadeia sob o prefixo, então errors.Is(err, kolomoq.ErrObjectTooLarge) e errors.As(err, &requestError) continuam funcionando. ErrBroadcastNotFound é um Watch de um namespace que o peer não publica, e embrulha o kolomoq.RequestError com DOES_NOT_EXIST. ErrBroadcastExists é um NewBroadcast onde o origin já tem o track de catálogo, e um frame cujo objeto passa do MaxObjectSize do origin é ErrFrameTooLarge. NewSecureBroadcast com um Sender nil é ErrInvalidConfig, um Watch protegido em uma sessão que não pode levar o namespace embrulha secobj.ErrWrongSession, e um frame que não pode ser selado mantém na cadeia o erro do secobj ou da kolo-moq (kolomoq.ErrClosed quando o Sender está fechado). Nada dele é escrito.

Referências