kolo docsbeta

Construa uma videochamada

Um tutorial passo a passo. Complete a parte do Kolo de uma janela de desktop já pronta: câmeras e microfones, um convite, um relay que o anfitrião roda e chaves de grupo que escondem do relay o áudio, o vídeo e os nomes.

Nesta página

Em uns 30 a 45 minutos você escreve a parte do Kolo do Kolo Meet, um exemplo de desktop para videochamadas. A janela, feita com Wails 3 e React, já está pronta, e também a maior parte do serviço em Go por trás dela: os estados da chamada, a rede, o notch e a bandeja. Você escreve as partes que usam o Kolo: as câmeras e os microfones, o convite, o relay que roda quem inicia a chamada, a sua própria transmissão, assistir aos outros e as chaves de grupo.

Uma chamada é câmera, microfone e mais nada: não há chat, nem mensagens de texto, nem compartilhamento de arquivos. Tudo fica no seu computador, no endereço 127.0.0.1, e você termina com três cópias do app na mesma chamada.

1Confira o que você precisa e abra a janela

Você precisa do Go 1.26 ou mais novo, do Node.js com npm, do Git e de três janelas de terminal. Se o Go ainda não estiver instalado, siga o primeiro passo de Construa um chat no seu terminal. Depois instale a ferramenta de linha de comando do Wails 3, que compila o app:

Terminal
go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0

No Linux, rode wails3 doctor: ele lista os pacotes do sistema de que a janela precisa. Só a janela precisa de cgo. As bibliotecas de áudio, vídeo e rede são só Go: para elas você não instala nenhum codec, nenhuma biblioteca de som e nenhum compilador.

Baixe o starter:

Terminal
git clone https://github.com/ciranda-dev/kolo-meet-wails3-starter.git && cd kolo-meet-wails3-starter

O go.mod dele já lista todas as bibliotecas que você usa: kolo-video para as câmeras e o VP8, kolo-audio para microfones, alto-falantes e Opus, kolo-invite para o convite, kolo-moq para o relay e as chaves, e kolo-media v0.1.0 para as transmissões, com kolo-swarm, kolo-dht e kolo-secure por baixo.

Compile. A primeira compilação leva alguns minutos, porque o codec de vídeo é um pacote Go grande; as seguintes usam o cache do Go. No macOS você pode ver avisos do linker sobre a versão do macOS; eles não atrapalham.

Terminal
wails3 build

Rode com uma pasta de dados só dele. -first faz esta janela rodar o primeiro nó de entrada de uma rede pequena em 127.0.0.1:4000, o endereço a que as outras janelas perguntam primeiro para se encontrarem. É só para testes locais: o Kolo Meet pronto usa a rede pública por padrão, e -bootstrap o aponta para um nó de entrada próprio.

bash
./bin/kolo-meet -data "$(mktemp -d)/ana" -first 127.0.0.1:4000

Quando a rede fica pronta, o terminal mostra a chave do app entre as linhas que o Wails imprime. A sua hora e a sua chave serão outras:

Texto
2026/11/16 09:53:02 kolo-id c7865ee7c063ed613ff06f2f24a706bc192e07e560dce797a7a5aef01d63ada7

A janela pede um nome: digite um e clique em Continuar. Clique em Iniciar uma chamada: a sala de espera mostra a prévia da câmera, o medidor do microfone e os seletores de dispositivos. Os dispositivos são inventados pelo starter, em starter.go: ligue a câmera e você vê listras cinza em movimento, ligue o microfone e o medidor se mexe a cada meio segundo. Nada real é aberto ainda. Clique em Iniciar chamada: a chamada termina na hora com "Não foi possível iniciar a chamada: not implemented in the starter (step 3 of the guide)." Cada parte que você escreve diz isso até você escrevê-la.

Isto é o que você escreve, e onde. Cada função já está no starter, como um stub que devolve ErrNotInStarter, então o app sempre compila:

PassoArquivoO que você escreve
2hw.golistar e abrir câmeras, microfones e alto-falantes, e os erros deles
3host.go, member.go, publisher.goo relay e o convite, entrar na chamada, a sua faixa de áudio
4guest.go, member.go, remote.goentrar com um convite, assistir aos outros, decodificar o que eles enviam
5member.goas chaves de grupo: quem recebe a sua e como você recebe as dos outros

Os passos 7 e 8 não acrescentam código: mostram duas partes que o starter já tem, o relatório de qualidade da chamada e o ritmo de imagens.

2Dispositivos e prévia na sala de espera

O serviço só chega à máquina pela interface hardware de hw.go. A versão do app é a kolo-video e a kolo-audio; os testes usam dispositivos inventados, então um teste nunca abre uma câmera, um microfone ou um alto-falante reais. Listar também não abre nenhum dispositivo, então nunca pede permissão: só ligar um dispositivo pede, e desligá-lo o fecha, então a luz de "em uso" do sistema se apaga.

Em hw.go, substitua o bloco de imports por:

hw.go
import (
	"context"
	"errors"
	"io/fs"

	koloaudio "github.com/ciranda-dev/kolo-audio"
	kolovideo "github.com/ciranda-dev/kolo-video"
)

Depois substitua tudo desde // realHardware is até o fim do arquivo pelos três blocos abaixo, colados um depois do outro.

hw.go
// realHardware is kolo-video and kolo-audio on the machine.
type realHardware struct{}

func list[T any](ds []T, err error, conv func(T) Device) ([]Device, error) {
	out := []Device{}
	for _, d := range ds {
		out = append(out, conv(d))
	}
	if errors.Is(err, kolovideo.ErrNoDevice) || errors.Is(err, kolovideo.ErrUnsupported) ||
		errors.Is(err, koloaudio.ErrNoDevice) || errors.Is(err, koloaudio.ErrUnsupported) {
		return out, nil
	}
	return out, err
}

func (realHardware) Cameras() ([]Device, error) {
	ds, err := kolovideo.Devices()
	return list(ds, err, func(d kolovideo.Device) Device { return Device{ID: d.ID, Name: d.Name, Default: d.Default} })
}

func audioDevices(kind koloaudio.Kind) ([]Device, error) {
	ds, err := koloaudio.Devices(kind)
	return list(ds, err, func(d koloaudio.Device) Device { return Device{ID: d.ID, Name: d.Name, Default: d.Default} })
}

func (realHardware) Microphones() ([]Device, error) { return audioDevices(koloaudio.Capture) }
func (realHardware) Speakers() ([]Device, error)    { return audioDevices(koloaudio.Playback) }

kolovideo.Devices e koloaudio.Devices listam o que está conectado. ErrNoDevice e ErrUnsupported não são erros aqui: um computador sem câmera recebe uma lista vazia e ainda pode entrar numa chamada para ouvir.

hw.go
func (realHardware) MicrophoneAccess() (string, error) {
	a, err := koloaudio.AccessStatus()
	if err != nil {
		return "", err
	}
	switch a {
	case koloaudio.AccessNotDetermined:
		return micNotDetermined, nil
	case koloaudio.AccessRestricted:
		return micRestricted, nil
	case koloaudio.AccessDenied:
		return micDenied, nil
	case koloaudio.AccessAuthorized:
		return micAuthorized, nil
	}
	return "", koloaudio.ErrBackend
}

func (realHardware) RequestMicrophone(ctx context.Context) error { return koloaudio.RequestAccess(ctx) }

func (realHardware) RequestCamera(ctx context.Context) error { return kolovideo.RequestAccess(ctx) }

func (realHardware) OpenCamera(id string, w, h int, fps float64) (cameraStream, error) {
	c, err := kolovideo.OpenCapture(kolovideo.CaptureConfig{DeviceID: id, Width: w, Height: h, FrameRate: fps})
	if err != nil {
		return nil, err
	}
	return c, nil
}

func (realHardware) OpenMicrophone(id string) (micStream, error) {
	in, err := koloaudio.OpenInput(koloaudio.Config{DeviceID: id, Format: koloaudio.Format{SampleRate: sampleRate, Channels: audioChannels}})
	if err != nil {
		return nil, err
	}
	return in, nil
}

func (realHardware) OpenSpeaker(id string) (speakerStream, error) {
	out, err := koloaudio.OpenOutput(koloaudio.Config{DeviceID: id, Format: koloaudio.Format{SampleRate: sampleRate, Channels: audioChannels}})
	if err != nil {
		return nil, err
	}
	return out, nil
}

OpenCapture e OpenInput nunca pedem permissão. RequestCamera e RequestMicrophone pedem: no macOS, kolovideo.RequestAccess e koloaudio.RequestAccess mostram o aviso do sistema na primeira vez, e no Linux e no Windows voltam na hora. MicrophoneAccess só lê a permissão do microfone (koloaudio.AccessStatus), então o lobby sabe de uma recusa antes de abrir qualquer dispositivo. O áudio roda a 48 kHz, mono, em quadros de 20 ms, os padrões da kolo-audio.

hw.go
// deviceError turns an error of kolo-video or kolo-audio into the MeetError of a device kind ("camera",
// "microphone" or "speaker").
func deviceError(kind string, err error) *MeetError {
	var me *MeetError
	switch {
	case err == nil:
		return nil
	case errors.As(err, &me):
		return me
	case errors.Is(err, kolovideo.ErrPermission), errors.Is(err, koloaudio.ErrPermission), errors.Is(err, fs.ErrPermission):
		return meetErr(kind+"-denied", err, "")
	case errors.Is(err, kolovideo.ErrNoDevice), errors.Is(err, koloaudio.ErrNoDevice),
		errors.Is(err, kolovideo.ErrUnsupported), errors.Is(err, koloaudio.ErrUnsupported):
		return meetErr(kind+"-none", err, "")
	case errors.Is(err, kolovideo.ErrDeviceLost), errors.Is(err, koloaudio.ErrDeviceLost):
		return meetErr(kind+"-lost", err, "")
	}
	return meetErr(kind+"-failed", err, "")
}

deviceError dá a cada falha a sua própria frase: uma recusa é kolovideo.ErrPermission para a câmera, koloaudio.ErrPermission para o microfone, ou um erro que corresponde a fs.ErrPermission, então a janela pode dizer onde permitir. Um dispositivo que falta e um perdido também têm a sua frase. Caso um sistema dê silêncio em vez de um erro, o app também avisa quando o microfone envia só zeros por 4 segundos.

O starter já carrega o codec de vídeo ao iniciar (loadCodecs em meetservice.go): o VP8 da kolo-video é a libvpx, como biblioteca embutida no módulo ou como o mesmo código traduzido para Go, e ele guarda a biblioteca na pasta de dados.

Confira que os testes continuam usando só dispositivos inventados e compile de novo:

Terminal
go test ./...
wails3 build

Abra a janela de novo, como no passo 1. Os seletores agora listam os seus dispositivos reais. No macOS, na primeira vez que você liga a câmera ou o microfone, o sistema pede permissão. Se ela for recusada, a janela diz isso, e você pode seguir com o que sobrou: uma chamada sem câmera, ou sem os dois, continua sendo uma chamada.

3Inicie uma chamada: o convite, o relay e a sua transmissão

Quem inicia uma chamada é o anfitrião. O app do anfitrião roda o relay da chamada: um relay da kolo-moq com identidade própria, num nó de rede próprio. O áudio e o vídeo de todos passam por ele. O convite é servido por um segundo nó de rede, com uma segunda identidade: qualquer pessoa com o convite pode chegar a esse nó, enquanto o nó do relay só deixa entrar as pessoas que o anfitrião aceitou. Assim, uma conexão que pede para entrar nunca é uma que leva áudio ou vídeo.

Em host.go, substitua o bloco de imports por:

host.go
import (
	"bytes"
	"crypto/ed25519"
	"crypto/rand"
	"encoding/hex"
	"errors"
	"net/netip"
	"strconv"

	kolodht "github.com/ciranda-dev/kolo-dht"
	koloid "github.com/ciranda-dev/kolo-id"
	invite "github.com/ciranda-dev/kolo-invite"
	kolomoq "github.com/ciranda-dev/kolo-moq"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
	kolotransport "github.com/ciranda-dev/kolo-transport"
)

Substitua startHost pelos quatro blocos abaixo, colados um depois do outro.

host.go
func (c *call) startHost() error {
	s := c.svc
	sw := s.swarm()
	if sw == nil {
		return meetErr("network-not-ready", ErrNotReady, "")
	}
	relID, err := koloid.Generate()
	if err != nil {
		return err
	}
	roomID, seed := make([]byte, 16), make([]byte, 32)
	rand.Read(roomID)
	rand.Read(seed)
	c.mu.Lock()
	c.relID = relID.PublicKey()
	c.room = &room{id: hex.EncodeToString(roomID), topic: roomTopic(seed), relay: relID.PublicKey(), host: c.me,
		hostName: s.displayName(), max: s.maxParticipants()}
	c.mu.Unlock()
	set := s.settingsCopy()
	payload, err := encodeGrant(c.room.id, seed, c.room.relay, c.me, c.room.hostName, c.room.max, relayKeys(set.relays))
	if err != nil {
		return err
	}

Uma identidade nova para o relay, um ID de sala aleatório e uma semente. O grant é o que cada convidado recebe quando o anfitrião o deixa entrar: a sala, a semente, a chave do relay, o anfitrião e as chaves dos relays de conexão do anfitrião, então um convidado que não tem nenhum deles na lista é avisado. A semente nunca viaja em claro: a rede só vê o topic derivado dela.

host.go
	if c.relay, err = kolomoq.NewRelay(&kolomoq.RelayConfig{Session: kolomoq.Config{Authorize: c.relayAuthorize}, Resume: reconnectWindow}); err != nil {
		return err
	}
	if c.ln, err = kolosecure.Listen(c.ctx, "127.0.0.1:0", relID, &kolosecure.Config{Transport: transportConfig()}); err != nil {
		return err
	}
	c.spawn(func() {
		for {
			conn, err := c.ln.Accept(c.ctx)
			if err != nil {
				return
			}
			if bytes.Equal(conn.RemotePublicKey(), c.me) {
				c.spawn(func() { c.relay.NewServer(c.ctx, conn) })
				continue
			}
			c.spawn(func() { c.serveConn(conn, conn.RemotePublicKey()) })
		}
	})

relayAuthorize, que já está no starter, é a regra do relay: o RoomPolicy da kolo-moq (só um membro pode anunciar um namespace dentro da sala, e só o seu), e um convidado sem lugar na chamada é recusado na hora. isMember diz quem o anfitrião deixou entrar enquanto a chamada tem lugar. O relay também escuta num endereço de loopback para a sessão do próprio anfitrião. O relay guarda o lugar de um convidado cuja conexão foi perdida por reconnectWindow, 60 segundos (RelayConfig.Resume), então ninguém vê o convidado sair enquanto ele se reconecta. A conexão do próprio anfitrião vai direto ao relay; qualquer outra vai para serveConn, que guarda a sessão do convidado sob a chave dele, para o anfitrião poder removê-lo depois.

host.go
	// The invite is served under a key of its own on a swarm any peer may reach; the call's relay only to the people
	// let in, so that a stranger never holds a connection with the stream budget of a person in the call.
	invID, err := koloid.Generate()
	if err != nil {
		return err
	}
	if c.rsw, err = c.openSwarm(set, swarmCallRelay, relID, c.relayAllow); err != nil {
		return err
	}
	if err := c.rsw.Join(c.ctx, c.room.topic, &koloswarm.JoinOptions{Announce: true}); err != nil {
		return meetErr("call-unavailable", err, "")
	}
	c.spawn(c.relayLoop)

O comentário diz por que há dois nós. Uma pessoa na chamada pode abrir até 1000 streams numa conexão, porque cada assinatura e cada grupo de objetos usa um stream, e o transporte fixa esse limite quando a conexão começa. Um estranho que pede para entrar precisa de um stream, então o nó do convite mantém o padrão da kolo-transport, 16, e um estranho nunca tem uma conexão com a margem de uma pessoa da chamada.

openSwarm, que já está no starter, abre um nó de rede com uma identidade e o liga à rede: os nós de entrada, os relays de conexão de -relay, então um convidado que não chega ao nó diretamente chega por um relay que os dois têm na lista, e o ajuste de transporte de swarmTransport. relayAllow deixa entrar no nó do relay só as pessoas que o anfitrião aceitou, e as que ele bloqueou, para poder avisá-las; nunca o próprio app do anfitrião. O nó do relay anuncia o topic da sala, assim os convidados o encontram, e relayLoop entrega ao relay cada convidado que se conecta.

host.go
	if c.isw, err = c.openSwarm(set, swarmCallInvite, invID, c.inviteAllow); err != nil {
		return err
	}
	db := kolostore.NewMemory()
	c.invDB = db
	if c.inv, err = invite.Open(db, invID, nil); err != nil {
		return err
	}
	c.spawn(func() {
		if err := c.inv.Announce(c.ctx, c.isw); err != nil && c.ctx.Err() == nil && !errors.Is(err, invite.ErrClosed) {
			c.logf("invite announce: %v", err)
		}
	})
	c.spawn(c.inviteSwarmLoop)
	c.grant = payload
	if _, err := c.newInvite(); err != nil {
		return err
	}
	c.spawn(c.inviteLoop)
	if err := sw.Join(c.ctx, c.room.topic, nil); err != nil {
		return meetErr("call-unavailable", err, "")
	}

	conn, err := kolosecure.Dial(c.ctx, c.ln.Addr().String(), s.id, relID.PublicKey(), &kolosecure.Config{Transport: transportConfig()})
	if err != nil {
		return meetErr("relay-unreachable", err, "")
	}
	return c.enter(conn)
}

O segundo nó usa a identidade do convite e aceita qualquer um menos o próprio app do anfitrião (inviteAllow). A kolo-invite guarda os registros dela na kolo-store, aqui só em memória, e é anunciada nesse nó; inviteSwarmLoop responde ali a cada pedido para entrar. Depois o anfitrião entra na própria chamada: conecta-se ao listener de loopback do relay e chama enter, como qualquer outro participante.

Substitua newInvite por:

host.go
// newInvite makes an invite for the call and keeps its code as the one the window shows. The earlier invites keep
// working until they expire or the call ends.
func (c *call) newInvite() (string, error) {
	if c.inv == nil {
		return "", ErrNoCall
	}
	infos, err := c.inv.List()
	if err != nil {
		return "", err
	}
	active := 0
	for _, i := range infos {
		if i.State == invite.Active {
			active++
		}
	}
	if active >= maxCallInvites {
		return "", meetErr("too-many-invites", ErrBusy, strconv.Itoa(maxCallInvites))
	}
	code, _, err := c.inv.Create(&invite.CreateOptions{TTL: inviteTTL, MaxUses: maxInviteUses, Manual: true})
	if err != nil {
		return "", err
	}
	c.mu.Lock()
	c.inviteStr = code
	c.mu.Unlock()
	c.changed()
	return code, nil
}

Um convite dura 24 horas e é respondido pelo app do anfitrião (Manual), que confere se a chamada tem lugar. O convite é um segredo: quem o tem pode pedir para entrar. Ele nunca vai para o histórico, os logs, a bandeja ou o notch.

Agora a transmissão. Em member.go, substitua o bloco de imports por:

member.go
import (
	"bytes"
	"context"
	"crypto/ed25519"
	"encoding/hex"
	"errors"
	"fmt"
	"slices"
	"sync"
	"time"

	kolomedia "github.com/ciranda-dev/kolo-media"
	kolomoq "github.com/ciranda-dev/kolo-moq"
	"github.com/ciranda-dev/kolo-moq/secobj"
	kolotransport "github.com/ciranda-dev/kolo-transport"
)

Substitua enter por:

member.go
// enter makes this person a participant: its protected broadcast, its keys, its session to the relay of the call,
// the roster and the media. conn is a connection to the relay.
func (c *call) enter(conn kolomoq.Conn) error {
	s := c.svc
	var err error
	if c.origin, err = kolomoq.NewOrigin(nil); err != nil {
		return err
	}
	ns := c.room.memberNS(c.me)
	if c.sender, err = secobj.NewSender(c.origin, ns, nil); err != nil {
		return err
	}
	if c.bc, err = kolomedia.NewSecureBroadcast(c.origin, c.sender); err != nil {
		return err
	}
	if c.keys, err = secobj.NewKeyring(secobj.KeyringConfig{Authorize: c.keyOwner, Relays: c.roomRelays()}); err != nil {
		return err
	}
	c.mu.Lock()
	c.pub = newPublisher(c.bc, c.sender, s.vid, &c.others)
	c.mu.Unlock()
	profile, err := c.origin.CreateTrack(ns, profileTrack, &kolomoq.TrackOptions{Priority: kolomoq.DefaultPriority, CacheGroups: 1})
	if err != nil {
		return err
	}
	c.profile = profile
	if err := c.attach(conn); err != nil {
		return err
	}
	c.mix = newMixer(nil)
	c.spawn(c.superviseRelay)
	c.spawn(c.rosterLoop)
	c.spawn(c.publishProfiles)
	c.spawn(c.expirePendingLoop)
	c.spawn(c.runSpeaker)
	c.spawn(c.adaptLoop)
	c.spawn(c.watchdogLoop)
	c.spawn(c.qualityLoop)
	mic, _ := s.media.isOpen()
	if err := c.pub.setAudio(mic); err != nil {
		return err
	}
	s.media.setSink(&sinks{audio: c.pub.onAudio, video: c.pub.onVideo})
	return nil
}

enter é onde uma pessoa vira participante, anfitrião ou convidado. O Origin guarda o que você publica. O Sender tem a sua chave para o seu namespace, e NewSecureBroadcast cria uma transmissão da kolo-media em que cada objeto, o catálogo incluído, é selado com ela. O Keyring vai guardar as chaves dos outros (passo 5). A sua sessão com o relay só deixa o relay ler a sua transmissão, e PublishNamespace a anuncia lá: quando esse anúncio volta, a chamada está ativa.

attach é a parte de enter que cria a sessão e anuncia a transmissão, uma função à parte para a chamada poder repeti-la. superviseRelay abre uma sessão nova quando a anterior termina, tentando por até 60 segundos com esperas que dobram de 0,5 s a 4 s, e mantém as suas pessoas, os dispositivos e o estado de mudo. watchdogLoop faz o mesmo quando uma pessoa que envia não entrega nada por 6 segundos, um caminho que deixa passar datagramas pequenos e descarta os grandes. adaptLoop move a câmera por uma escada de qualidade, 360p, 720p e o teto de 1080p, conforme o que a conexão com o relay carrega: desce na hora quando a fila está velha e sobe depois de 4 segundos de caminho livre. qualityLoop acrescenta o que você envia ao relatório de qualidade da chamada a cada 5 segundos (passo 7). Essas ajudas já estão no starter, em reconnect.go, watchdog.go, adapt.go, ladder.go e quality.go, então você não as escreve.

A faixa de vídeo já está no starter (onVideo em publisher.go). Escreva a faixa de áudio: em publisher.go, substitua setAudio por:

publisher.go
// setAudio adds or removes the microphone track.
func (p *publisher) setAudio(on bool) error {
	p.amu.Lock()
	defer p.amu.Unlock()
	if p.closed || (on == (p.audio != nil)) {
		return nil
	}
	if !on {
		err := p.audio.Close()
		p.audio = nil
		p.aenc.Close()
		p.aenc = nil
		return err
	}
	enc, err := opus.NewEncoder(audioEncoderConfig())
	if err != nil {
		return meetErr("codec-unavailable", err, "")
	}
	if audioComplexity >= 0 {
		enc.SetComplexity(audioComplexity)
	}
	tp, err := p.b.AddTrack(audioTrackDef(), kolomedia.PackagerOptions{})
	if err != nil {
		enc.Close()
		return err
	}
	if p.lossPct > 0 {
		setLoss(enc, p.lossPct)
	}
	ts, _ := p.clock.At(time.Now(), sampleRate)
	p.audio, p.aenc, p.abase, p.asamples = tp, enc, ts, 0
	return nil
}

Uma faixa só existe enquanto o dispositivo dela está ligado, então silenciar a remove, e os outros veem "microfone desligado" pelo seu catálogo selado. O áudio é Opus a 32 kbit/s constantes, então o tamanho dos pacotes não revela quando você fala. O codificador do microfone tem uma trava própria (amu), então nunca espera por um quadro de câmera que está sendo codificado, e o app liga a correção de erros adiante do Opus (setLoss) enquanto o caminho perde grupos.

Substitua onAudio por uma constante e a função:

publisher.go
// audioResync is how far the timeline of the microphone's frames may fall behind the clock before it jumps forward to
// it: the playout delay a receiver needs at least (kolo-media's PlayoutConfig.MinDelay), so ordinary jitter of the
// microphone's thread stays inside it.
const audioResync = 100 * time.Millisecond

// onAudio encodes one 20 ms frame of the microphone. Timestamps count samples, so they never jitter, and the timeline
// follows the clock of the video: a microphone that delivers fewer frames than the clock counts (its thread starved, or
// the device overran) moves it forward by the frames lost, a gap the receiver makes up, instead of letting it fall behind
// without end, which the receiver's playout, measuring arrival against these timestamps with the video's, takes for a
// lateness that no delay covers: it drops every audio frame from then on.
func (p *publisher) onAudio(pcm []int16) {
	now := time.Now()
	p.amu.Lock()
	defer p.amu.Unlock()
	if p.closed || p.audio == nil {
		return
	}
	out := make([]byte, opus.PacketBufferSize)
	n, err := p.aenc.Encode(pcm, out)
	if err != nil || n == 0 {
		return
	}
	ts := p.abase + p.asamples
	if wall, err := p.clock.At(now, sampleRate); err == nil && wall > ts+uint64(len(pcm))+uint64(audioResync.Seconds()*sampleRate) {
		p.abase += (wall - ts - uint64(len(pcm))) / uint64(len(pcm)) * uint64(len(pcm))
		ts = p.abase + p.asamples
	}
	p.asamples += uint64(len(pcm))
	if err := p.audio.WriteFrame(kolomedia.Frame{Timestamp: ts, Keyframe: true, Data: out[:n]}); err != nil && !errors.Is(err, kolomedia.ErrClosed) {
		return
	}
}

Cada quadro de 20 ms do microfone vira um pacote Opus e um quadro da faixa. O timestamp dele conta amostras, então nunca oscila. Quando o microfone entrega menos quadros do que o relógio conta, porque a thread dele ficou sem tempo ou o dispositivo estourou, a linha do tempo salta até o relógio assim que fica mais de 100 ms atrasada (audioResync). O que se perdeu vira então uma lacuna que o receptor compensa, e não áudio descartado para sempre.

Compile de novo e abra uma janela como no passo 1. Inicie uma chamada: a tela da chamada diz "1 na chamada, criptografia de ponta a ponta, pelo relé operado por você", e a tela do anfitrião tem o convite, que começa com koloinv0. Ninguém consegue entrar ainda.

4Entre numa chamada e assista aos outros

Um convidado cola o convite. O app dele procura o anfitrião num topic derivado do segredo do convite, pede para entrar, recebe o grant selado só para ele e depois se conecta ao relay.

Em guest.go, substitua o bloco de imports por:

guest.go
import (
	"context"
	"errors"
	"time"

	invite "github.com/ciranda-dev/kolo-invite"
	kolomoq "github.com/ciranda-dev/kolo-moq"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

Substitua joinHost por:

guest.go
func (c *call) joinHost() error {
	s := c.svc
	sw := s.swarm()
	if sw == nil {
		return meetErr("network-not-ready", ErrNotReady, "")
	}
	if err := sw.Join(c.ctx, c.code.Topic(), &koloswarm.JoinOptions{Lookup: true}); err != nil {
		return meetErr("lookup-failed", err, "")
	}
	var peer swarmPeer
	select {
	case peer = <-c.joinPeer:
	case <-time.After(s.set.FindTimeout):
		sw.Leave(c.code.Topic())
		c.mu.Lock()
		unreachable := c.noInviter
		c.mu.Unlock()
		if unreachable {
			return hostUnreachable(len(s.set.relays) > 0)
		}
		return ErrNotFound
	case <-c.ctx.Done():
		sw.Leave(c.code.Topic())
		return c.ctx.Err()
	}
	c.setPhase(phaseWaitingHost)
	actx, cancel := context.WithTimeout(c.ctx, joinAnswerTimeout)
	defer cancel()
	payload, err := invite.JoinConn(actx, peer.Conn(), s.id, c.code, nil)
	sw.Leave(c.code.Topic()) // the invite-only connection closes; the call gets its own
	if err != nil {
		return err
	}
	r, err := parseGrant(payload)
	if err != nil {
		return err
	}
	mine := s.settingsCopy().relays
	c.mu.Lock()
	c.room = r
	c.relayShare = shareRelay(mine, r.relayKeys)
	c.warning = relayMismatch(mine, r.relayKeys)
	c.mu.Unlock()
	if !c.move(callConnecting, phaseRelay) {
		return context.Canceled
	}
	if err := sw.Join(c.ctx, r.topic, nil); err != nil {
		return meetErr("lookup-failed", err, "")
	}
	select {
	case rp := <-c.relayPeer:
		kind, via := s.linkOf(rp.Conn())
		c.mu.Lock()
		c.relayLink, c.relayVia = kind, via
		c.mu.Unlock()
		conn := rp.Conn()
		if h := relayHook; h != nil {
			conn = h(c, conn)
		}
		return c.enter(conn)
	case <-time.After(s.set.FindTimeout):
		c.mu.Lock()
		defer c.mu.Unlock()
		return relayWaitReason(c.noRelay, c.relayShare)
	case <-c.ctx.Done():
		return c.ctx.Err()
	}
}

O convite leva uma impressão digital da chave do convite e um segredo, nunca um endereço. JoinConn pede para entrar no nó do convite do anfitrião e espera a resposta. parseGrant, que já está no starter, confere que a resposta é um grant e recusa tudo o que estiver malformado. A chave do convite nunca é a do relay, então o convidado só conhece a chave do relay pelo grant, selado só para ele. As outras ajudas também estão no starter: hostUnreachable diz quando o anfitrião foi encontrado mas não pôde ser alcançado, nem diretamente nem pelos relays de conexão, e relayMismatch avisa um convidado cujos relays de conexão não têm nenhum em comum com os do anfitrião.

Em member.go, substitua watchLoop por:

member.go
// watchLoop plays p's broadcast through the relay. Watch returns once a catalog that opens under p's key arrives,
// so until the key is here the person is "waiting for keys" and nothing of it plays.
func (c *call) watchLoop(p *participant) {
	caps := watchCapabilities()
	for p.ctx.Err() == nil {
		w, err := kolomedia.Watch(p.ctx, c.session(), p.ns, kolomedia.WatchOptions{Capabilities: caps, Keys: c.keys, RequestKeyframes: !noKeyRequests})
		if err != nil {
			c.mu.Lock()
			p.watchErr = err
			c.mu.Unlock()
			if !sleep(p.ctx, retryEvery) {
				return
			}
			continue
		}
		c.setPState(p, partLive)
		c.playWatcher(p, w)
		w.Close()
		if p.ctx.Err() != nil {
			return
		}
		c.mu.Lock()
		p.audioOn, p.videoOn = false, false
		c.mu.Unlock()
		c.setPState(p, partStopped)
		if !sleep(p.ctx, retryEvery) {
			return
		}
		c.setPState(p, partWaitingKeys)
	}
}

kolomedia.Watch com Keys só volta quando chega um catálogo que abre com a chave do emissor. Até lá a pessoa está "aguardando chaves" e nada dela toca. Ele roda sobre c.session(), a sessão atual com o relay, então depois de uma reconexão a escuta recomeça na nova. RequestKeyframes faz uma escuta pedir ao emissor um grupo novo, que começa com um quadro chave, quando a faixa de vídeo dela espera por um, no máximo uma vez por segundo, em vez de esperar o próximo grupo (até 2 s). O emissor atende com TrackPublisher.KeyframeRequests.

Em remote.go, substitua o bloco de imports por:

remote.go
import (
	"context"
	"fmt"
	"math"
	"sync"
	"time"

	"github.com/ciranda-dev/kolo-audio/opus"
	kolomedia "github.com/ciranda-dev/kolo-media"
	"github.com/ciranda-dev/kolo-video/vpx"
)

Substitua playAudio e playVideo por:

remote.go
func (c *call) playAudio(ctx context.Context, p *participant, w *kolomedia.Watcher) error {
	dec, err := opus.NewDecoder(sampleRate, audioChannels)
	if err != nil {
		return err
	}
	defer dec.Close()
	pcm := make([]int16, int(opus.MaxPacketDuration.Seconds()*sampleRate)*audioChannels)
	var speak speakTracker
	var g gaps
	for {
		f, _, err := w.Next(ctx, kolomedia.Audio)
		if err != nil {
			return err
		}
		if miss := g.missing(f.Timestamp); miss > 0 && miss <= maxGapFrames {
			p.missed.Add(uint64(miss))
			if !noConceal {
				c.concealGap(p, dec, f.Data, pcm, miss)
			}
		}
		n, err := dec.Decode(f.Data, pcm)
		if err != nil || n == 0 {
			continue
		}
		p.audioBytes.Add(uint64(len(f.Data)))
		db := pcmLevel(pcm[:n])
		now := time.Now()
		p.level.Store(math.Float64bits(db))
		p.speaking.Store(speak.update(db, now))
		p.lastAudio.Store(now.UnixNano())
		p.audioIn.Add(1)
		c.mix.push(p.id, pcm[:n])
	}
}
remote.go
func (c *call) playVideo(ctx context.Context, p *participant, w *kolomedia.Watcher) error {
	dec, err := vpx.NewDecoder(remoteDecoderConfig())
	if err != nil {
		return err
	}
	defer dec.Close()
	tile := tileRenderer{b: &c.svc.tiles, id: p.id}
	defer c.svc.tiles.release(p.id)
	for {
		f, _, err := w.Next(ctx, kolomedia.Video)
		if err != nil {
			return err
		}
		began := time.Now()
		img, err := dec.Decode(vpx.Packet{Data: f.Data, Keyframe: f.Keyframe})
		if err != nil || img == nil {
			continue
		}
		now := time.Now()
		p.noteDecode(now.Sub(began))
		p.videoIn.Add(1)
		p.videoBytes.Add(uint64(len(f.Data)))
		p.videoSize.Store(uint64(img.Width)<<32 | uint64(img.Height))
		if ev, ok := tile.render(img, now); ok {
			ev.ID = p.id
			c.svc.emit("meet:frame", ev)
			p.videoShown.Add(1)
			p.freeze.picture(now)
		}
	}
}

O áudio vai para o mixer, que toca todos no seu alto-falante; o volume mexe o anel de quem fala. O vídeo é decodificado e desenhado num JPEG pequeno para o quadro da janela. Um quadro que não decodifica é pulado até o próximo quadro chave. Os quadros que não chegaram são contados (gaps), e até 3 seguidos são preenchidos: ocultação de perdas do Opus e, para o último, a correção de erros adiante do pacote seguinte. Cada quadro também soma aos contadores do relatório de qualidade da chamada (passo 7): os bytes recebidos, o tamanho da imagem, o tempo que levou para decodificar, as imagens mostradas e freeze, que percebe quando as imagens param.

Compile de novo. No Terminal 1, abra o anfitrião como no passo 1. No Terminal 2, abra uma segunda janela que entra na rede da primeira:

bash
./bin/kolo-meet -data "$(mktemp -d)/bruno" -bootstrap 127.0.0.1:4000

Inicie uma chamada na primeira janela e copie o convite. Na segunda, clique em Entrar com um convite, cole o convite, clique em Continuar e depois em Entrar. Cada janela agora tem um quadro para a outra pessoa, o quadro diz "Aguardando chaves" e o cabeçalho conta "1 aguardando chaves": nem imagem, nem som. Faltam até os nomes: os quadros mostram "Guest" e o começo da chave da outra pessoa, porque os nomes também viajam selados. É assim de propósito. O áudio e o vídeo chegam selados ao relay, e ninguém deu ainda uma chave a ninguém.

5Chaves de grupo

Cada participante sela a sua transmissão com a sua própria chave e a entrega a cada um dos outros pela conexão entre os dois, direta ou por um relay de conexão que os dois têm na lista, nunca pelo relay da chamada. Quando alguém entra ou sai, a chave do emissor muda, então quem saiu não lê nada selado depois de sair.

Em member.go, substitua keyOwner por:

member.go
// keyOwner is the Keyring's rule: a peer gives the key of its own namespace, and only while it is in the call.
func (c *call) keyOwner(peer ed25519.PublicKey, ns kolomoq.Namespace) error {
	if !c.room.owns(peer, ns) {
		return errors.New("kolo-meet: not the owner of that namespace")
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.people[hex.EncodeToString(peer)] == nil {
		return errors.New("kolo-meet: not in the call")
	}
	return nil
}

Esta é a regra do Keyring: um peer pode dar a chave do próprio namespace, e só enquanto está na chamada.

Substitua updateMembers por:

member.go
// updateMembers gives our key to everyone in the call, rotating it when the set changed.
func (c *call) updateMembers() {
	if c.sender == nil {
		return
	}
	c.memberMu.Lock()
	defer c.memberMu.Unlock()
	c.mu.Lock()
	keys := make([]ed25519.PublicKey, 0, len(c.people))
	for _, p := range c.people {
		keys = append(keys, p.key)
	}
	c.mu.Unlock()
	c.others.Store(int32(len(keys)))
	if err := c.sender.SetMembers(keys); err != nil && c.ctx.Err() == nil {
		c.logf("set members: %v", err)
	}
}

SetMembers define quem recebe a sua chave. Quando o conjunto muda, o Sender cria uma chave nova, envia essa chave para a faixa de chaves de cada membro antes de usá-la e fecha a faixa de quem saiu. A janela mostra então "NOME não recebe mais o seu áudio nem o seu vídeo".

Substitua startLink por:

member.go
// startLink makes the media session between us and p on their own connection, and fetches p's key on it.
func (c *call) startLink(p *participant, peer swarmPeer) {
	c.spawn(func() {
		lctx, cancel := context.WithCancel(p.ctx)
		cfg := &kolomoq.Config{Origin: c.origin, Authorize: c.pairAuthorize, SetupTimeout: pendingTTL}
		var sess *kolomoq.Session
		var err error
		if bytes.Compare(c.me, p.key) < 0 {
			sess, err = kolomoq.NewClient(lctx, peer.Conn(), cfg)
		} else {
			sess, err = kolomoq.NewServer(lctx, peer.Conn(), cfg)
		}
		if err != nil {
			cancel()
			return
		}
		l := &link{peer: peer, sess: sess, cancel: cancel}
		l.kind, l.via = c.svc.linkOf(peer.Conn())
		if old := c.setLink(p, l, nil); old != nil {
			old.stop()
		}
		if c.svc.holdKeys != nil && c.svc.holdKeys(p.key) {
			return
		}
		for {
			err := c.keys.Receive(lctx, sess, c.me, p.ns)
			c.mu.Lock()
			p.keyErr, p.keyTries = err, p.keyTries+1
			c.mu.Unlock()
			select {
			case <-lctx.Done():
				return
			case <-sess.Done():
				return
			case <-time.After(retryEvery):
			}
		}
	})
}

A conexão entre dois participantes leva uma sessão da kolo-moq. pairAuthorize, que já está no starter, recusa nela todo pedido exceto a faixa de chaves feita para quem pede, então por ali não passa áudio nem vídeo. Receive instala as chaves da outra pessoa conforme elas chegam; holdKeys é um gancho que os testes usam para simular alguém cuja chave nunca chega, e no app ele é nil.

Compile de novo e abra outra vez as duas janelas do passo 4. Em cerca de um segundo, os quadros passam de "Aguardando chaves" para o nome, a imagem e o som da outra pessoa, e o cabeçalho da janela do anfitrião diz "2 na chamada, criptografia de ponta a ponta, pelo relé operado por você".

O que isso protege, como a janela diz quando você abre o cabeçalho: o relay não consegue ver áudio, vídeo nem nomes, nem mesmo o tamanho de um nome. O relay vê quem está na chamada, quem assiste a quem, quando cada pessoa envia e quanto, quando microfones e câmeras estão desligados, e o ID da sala; ele pode descartar ou atrasar o áudio e o vídeo. Qualquer pessoa na chamada pode ler o áudio e o vídeo de todos. Qualquer pessoa na chamada poderia, com a ajuda do relay, criar áudio, vídeo ou nomes que parecem vir de outra pessoa, e o anfitrião, que opera o relay, poderia fazer isso sozinho: cada participante tem a chave de cada emissor, e os objetos não são assinados por emissor. Não há proteção para o período de chave atual se um dispositivo for comprometido, nem recuperação depois de um comprometimento.

Um participante cuja chave não chegou não toca nada: não há reprodução sem chaves. As chaves só viajam pela conexão entre dois participantes, nunca pelo relay da chamada. Essa conexão é direta, ou passa por um relay de conexão que os dois informam com -relay. Um par que não consegue se conectar de nenhum dos dois jeitos continua mostrando "Aguardando chaves". O AES-GCM do Go é de tempo constante só em processadores amd64 e arm64 com instruções AES, ppc64x e s390x.

6Rode três cópias no mesmo computador

Todos os stubs estão escritos, então os arquivos próprios do starter não são mais necessários. Apague starter.go e starter_test.go: nada os usa mais. Depois confira o seu código com os testes do exemplo pronto. Eles iniciam de duas a quatro cópias do serviço num só processo, com dispositivos inventados, em 127.0.0.1, e conferem que todos veem e ouvem todos, o silenciar, a câmera desligada, a saída, uma chamada cheia e um participante cuja chave nunca chega. Levam um ou dois minutos:

Terminal
go vet -tags finished .
go test -tags finished .
wails3 build

Abra três janelas. O Terminal 1 é o anfitrião e roda o primeiro nó de entrada; o Terminal 2 e o Terminal 3 entram na rede dele:

bash
./bin/kolo-meet -data "$(mktemp -d)/ana" -first 127.0.0.1:4000
./bin/kolo-meet -data "$(mktemp -d)/bruno" -bootstrap 127.0.0.1:4000
./bin/kolo-meet -data "$(mktemp -d)/carla" -bootstrap 127.0.0.1:4000

Rode cada linha no seu próprio terminal (no Windows, rode a primeira linha em cada terminal antes da linha kolo-meet dele). Inicie uma chamada na janela da Ana e envie o convite para os outros dois: o mesmo convite serve para os dois. A grade mostra três pessoas, com os nomes e um anel em volta de quem fala. As três cópias dividem a sua única câmera e o seu único microfone, então use fones de ouvido ou silencie duas delas, senão os alto-falantes voltam para o microfone.

Experimente silenciar e desligar a câmera: o quadro muda para os outros. Quando o Bruno clica em Sair, os outros veem "Bruno não recebe mais o seu áudio nem o seu vídeo", e as chaves mudam. Quando a Ana, a anfitriã, encerra a chamada, ela termina para todos e diz por quê: o relay era dela.

7Veja como a chamada está indo

Enquanto uma chamada roda, cada janela escreve um relatório de qualidade da chamada: a cada 5 segundos, uma linha JSON para cada pessoa que você assiste ("kind":"remote") e uma para o que você envia ("kind":"local"). O arquivo é kolo-meet-quality.jsonl, na pasta de dados, e só você pode lê-lo (modo 0600); ao chegar a 2 MiB ele vira kolo-meet-quality.jsonl.1 e um novo começa. Ele guarda só contagens, tamanhos e tempos, nunca um nome, uma chave, um convite, um endereço nem áudio ou vídeo. Quando uma janela abre, o terminal dela diz para onde vai o relatório, numa linha que começa com call quality report is on. -quality-report off o desliga, e -quality-log também escreve cada linha no terminal, depois de quality:.

Neste passo você não escreve nada: o relatório está em quality.go, e você acrescentou os contadores dele nos passos 3 e 4. Aqui está de onde vêm os números. Para cada pessoa que você assiste, logMedia, que já está no starter, chama reportRemote a cada 5 segundos:

remote.go
// reportRemote writes the quality record of p for the interval since q0 and returns the counters it read.
func (c *call) reportRemote(p *participant, st kolomedia.WatchStats, q0 peerCounters, secs float64, now time.Time) peerCounters {
	q := p.counters(st)
	if !c.svc.qualityOn() {
		return q
	}
	r := remoteRecord(q0, q, secs)
	r.At, r.T, r.Call, r.Person = now.Unix(), round1(now.Sub(c.began).Seconds()), c.id, p.person
	size := p.videoSize.Load()
	r.VideoW, r.VideoH = int(size>>32), int(size&0xffffffff)
	n, longest := p.freeze.take(now)
	r.Freezes, r.FreezeLongestMs = n, longest.Milliseconds()
	r.PlayoutDelayMs, r.PlayoutJitterMs = st.Playout.Delay.Milliseconds(), st.Playout.Jitter.Milliseconds()
	r.DecodeMs = ms(time.Duration(p.decodeNs.Load()))
	rate, cost := c.svc.tiles.display(p.id)
	r.DisplayFPS, r.TileMs = rate, ms(cost)
	c.svc.reportQuality(r)
	return q
}

// counters reads the totals of p's watch for the quality record: the playout's drops come from st.
func (p *participant) counters(st kolomedia.WatchStats) peerCounters {
	dropped := func(t kolomedia.TrackStats) uint64 { return t.Late + t.Skipped + t.Overflow }
	return peerCounters{
		audioIn: p.audioIn.Load(), missed: p.missed.Load(), concealed: p.concealed.Load(), audioDropped: dropped(st.Playout.Tracks["audio"]),
		videoIn: p.videoIn.Load(), shown: p.videoShown.Load(), videoDropped: dropped(st.Playout.Tracks["video"]),
		audioBytes: p.audioBytes.Load(), videoBytes: p.videoBytes.Load(),
	}
}

Watcher.Stats da kolo-media diz o que a recepção de uma pessoa viu: o atraso do buffer de jitter e quão atrasados os quadros chegam (Playout.Delay e Playout.Jitter) e, para cada faixa, os quadros que ele descartou porque chegaram tarde demais, foram pulados ou não cabiam no buffer. Os contadores que você acrescentou em playAudio e playVideo dão o resto. Um congelamento é uma parada de mais de 500 ms entre duas imagens enquanto a câmera da pessoa está ligada.

Para o que você envia, qualityLoop lê Stats de cada uma das suas sessões com o relay (um anfitrião tem uma por convidado) e soma tudo:

quality.go
// sentStats is what the sessions of the sender showed at one reading, by session: counters restart with a session.
type sentStats map[*kolomoq.Session]kolomoq.SessionStats

// sinceLast adds up what each session carried since prev, and the oldest queue among them.
func (cur sentStats) sinceLast(prev sentStats) (sent, reset, expired uint64, queue time.Duration) {
	for s, st := range cur {
		p := prev[s]
		sent += sub(st.SentBytes, p.SentBytes)
		reset += sub(st.ResetGroups, p.ResetGroups)
		expired += sub(st.ExpiredGroups, p.ExpiredGroups)
		queue = max(queue, st.QueueDelay)
	}
	return sent, reset, expired, queue
}

// net is the transport's view of the sessions that report it, since prev; nil when none does. A session of a connection
// without statistics, such as one through a connection relay, has an empty controller name and is left out.
func (cur sentStats) net(prev sentStats) *qualityNet {
	var worst *kolomoq.SessionStats
	var sent, lost uint64
	for s, st := range cur {
		if st.Transport.CongestionController == "" {
			continue
		}
		p := prev[s].Transport
		sent += sub(st.Transport.PacketsSent, p.PacketsSent)
		lost += sub(st.Transport.PacketsLost, p.PacketsLost)
		if worst == nil || st.Transport.SmoothedRTT > worst.Transport.SmoothedRTT {
			worst = &st
		}
	}
	if worst == nil {
		return nil
	}
	t := worst.Transport
	n := &qualityNet{
		RTTMs: ms(t.SmoothedRTT), MinRTTMs: ms(t.MinRTT), RTTVarMs: ms(t.RTTVariation),
		CwndBytes: t.CongestionWindow, InFlightByte: t.BytesInFlight, Controller: t.CongestionController,
		BwKbps: round1(float64(t.BandwidthEstimate) * 8 / 1000), PathChanges: t.PathChanges,
	}
	if sent > 0 {
		n.LossPct = round1(float64(min(lost, sent)) * 100 / float64(sent))
	}
	return n
}

SessionStats da kolo-moq tem os bytes enviados, os grupos de objetos abandonados (reiniciados porque a fila estava cheia, ou expirados porque eram velhos demais) e quanto o objeto mais antigo ainda não enviado espera: mais de 250 ms é um caminho cheio. A parte Transport é o que a kolo-transport mediu na conexão: o tempo de ida e volta, os pacotes perdidos, a janela de congestionamento e o nome do controle de congestionamento. O objeto net da linha local fica com a sessão de maior tempo de ida e volta. Uma sessão por um relay de conexão não tem esses números, então fica de fora.

O controle é reno, a não ser que você abra o app com -congestion cubic ou -congestion bbr. Uma chamada envia menos do que o caminho carrega, e bbr mantém uma fila de 25 a 150 ms, então reno é o padrão; os outros dois estão lá para comparar num caminho com perdas, com este relatório.

8Escolha quantas imagens por segundo

A janela não decodifica vídeo: o serviço em Go decodifica os quadros de cada pessoa e desenha cada imagem num JPEG pequeno para o quadro dela na janela (tile.render em playVideo). Desenhar usa tempo de processador, então o app escolhe quantas imagens por segundo cada quadro da janela desenha. -display-fps define isso: auto, o padrão, 30 ou 15. Neste passo você também não escreve nada: a regra está em tiles.go.

tiles.go
// The display rates, in pictures a second of one tile, and the rule that picks one.
const (
	// tileRateHigh is the rate while at most tileFewRemote other people show video: kolo-video's default capture rate,
	// so every picture sent is shown.
	tileRateHigh = kolovideo.DefaultFrameRate
	// tileRateLow is the rate with more people, and while the guard finds the drawing too costly: half of it.
	tileRateLow   = kolovideo.DefaultFrameRate / 2
	tileFewRemote = 4
	// tileCPUMax is the share of one core the JPEG work of all tiles may take at tileRateHigh before the rate falls to
	// tileRateLow; it goes back up when that work is under tileCPUResume, so a load near the limit does not flip the rate.
	tileCPUMax    = 0.5
	tileCPUResume = 0.4
	// tileCostWeight is the weight of each new picture in a tile's mean cost, and tileCostWarm the pictures a tile
	// needs before its cost counts.
	tileCostWeight = 0.1
	tileCostWarm   = 5

	// tileEarly is how long before its turn a frame is still taken: camera frames are not evenly spaced, and at
	// tileRateHigh a frame that came a millisecond early would cost a whole interval.
	tileEarly = 8 * time.Millisecond

	// tileByteRateLow bounds the bytes a second of picture events over all tiles at tileRateLow. Wails parks an event
	// over 8 KiB until the webview fetches it, at most 64 MiB in all, each for 30 s plus up to a sweep of 7.5 s, and
	// sends what does not fit inline, which keeps memory on macOS (wails v3.0.0 pkg/application/event_payload_store.go:33-57,
	// webview_window.go:1459-1475). At this rate even a webview that fetches nothing never fills the store; the budget
	// grows with the rate (tileByteRate), so at tileRateHigh such a webview fills it in half the time.
	tileByteRateLow = (64 << 20) * 4 / (30 * 5)

	// selfTile is the ID of the tile of our own camera.
	selfTile = "self"
)

// -display-fps values. Auto is the rule above; the other two fix the rate and switch the guard off.
const (
	displayAuto = "auto"
	display30   = "30"
	display15   = "15"
)
tiles.go
// rateLocked is the rate tiles draw at now: the fixed one of -display-fps 30 or 15, else tileRateHigh with at most
// tileFewRemote other people showing video, unless the guard holds it at tileRateLow, else tileRateLow.
func (b *tileBudget) rateLocked() int {
	switch b.mode {
	case display30:
		return tileRateHigh
	case display15:
		return tileRateLow
	}
	remote := len(b.live)
	if _, ok := b.live[selfTile]; ok {
		remote--
	}
	if remote > tileFewRemote {
		return tileRateLow
	}
	if noTileGuard {
		return tileRateHigh
	}
	var work float64
	warm := true
	for _, t := range b.live {
		work += t.cost.Seconds() * tileRateHigh
		warm = warm && t.n >= tileCostWarm
	}
	switch {
	case !warm:
	case b.guarded && work < tileCPUResume:
		b.guarded = false
	case !b.guarded && work > tileCPUMax:
		b.guarded = true
	}
	if b.guarded {
		return tileRateLow
	}
	return tileRateHigh
}

Com auto, cada quadro da janela desenha 30 imagens por segundo, o ritmo de captura padrão da kolo-video, então toda imagem enviada é mostrada, enquanto no máximo 4 outras pessoas mostram vídeo, e 15 com mais. Uma proteção mantém uma média móvel de quanto tempo uma imagem leva para ser desenhada e comprimida, para cada quadro. Quando desenhar todos os quadros a 30 levaria mais da metade de um núcleo do processador, eles desenham a 15 até cair abaixo de 40%, assim uma carga perto do limite não faz o ritmo pular de um valor para o outro. 30 e 15 fixam o ritmo e desligam a proteção.

Para testar, abra mais uma janela como no passo 6, com uma pasta de dados própria e -display-fps 15 no fim da linha, e entre na chamada da Ana com o mesmo convite. Cada quadro dessa janela, inclusive o da própria câmera, desenha 15 imagens por segundo, e o relatório dela diz isso: display_mode é 15 nas linhas local, e as linhas remote têm display_fps 15 ao lado de tile_ms, o tempo que uma imagem leva para ser desenhada.

O que acabou de acontecer

  • Cada janela encontrou as outras pelo nó de entrada que a primeira rodou. O app do anfitrião rodou o relay da chamada, e cada transmissão passou por ele. O upload do anfitrião leva o áudio e o vídeo de cada participante para todos os outros.
  • O convite levou os convidados até o nó do convite do anfitrião, e o app do anfitrião os deixou entrar enquanto a chamada tinha lugar. Só então eles conheceram a identidade do relay, pelo grant.
  • Cada objeto de cada transmissão foi selado com a chave do seu emissor, e as chaves viajaram pela conexão direta entre cada par, nunca pelo relay. Veja kolo-media e kolo-moq.

Próximos passos

  • Leia a página da kolo-media: transmissões, assistir e mídia protegida, com os limites delas.
  • Leia como um convite funciona em Convide alguém para um grupo, em um programa de terminal.
  • O código pronto deste exemplo está no repositório kolo-meet-wails3-example da organização ciranda-dev. Sem starter.go, os seus arquivos Go são os mesmos.