SPEC · go2rtc — Referencia Completa

Identidad del Componente

Campo	Valor
Repo	github.com/AlexxIT/go2rtc
Lenguaje	Go (binario estático ~15 MB)
Licencia	MIT
RAM típica	~20–40 MB
Config	go2rtc.yaml
Install Debian	✘ No hay paquete — binario precompilado ARM
Entradas	V4L2, ALSA, RTSP, ffmpeg exec, HomeKit
Salidas	MJPEG, HLS, RTSP, WebRTC (WHEP), MP4, snapshot

go2rtc.yaml — Configuración Completa

Toda la config es un único fichero YAML. Sin flags CLI (al contrario que µStreamer). Un solo fichero = una fuente de verdad.

Config mínima (lo que arranca el SNH)

# /etc/go2rtc/go2rtc.yaml streams: solar-cam: - v4l2:///dev/video0 # USB webcam api: listen: "127.0.0.1:1984" # solo localhost

Config completa (CSI + USB + ALSA + IP cam)

# /etc/go2rtc/go2rtc.yaml — full streams: solar-cam: # cámara principal - v4l2:///dev/video0 solar-cam-csi: # alt: CSI via libcamera - "exec:libcamerify v4l2-ctl --stream" solar-mic: # micrófono ALSA - alsa:///default ext-cam: # cámara IP externa RTSP - rtsp://192.168.1.50/stream1 api: listen: "127.0.0.1:1984" webrtc: candidates: - 192.168.1.10:8555 # IP LAN fija para WHEP log: level: info

api.listen debe ser 127.0.0.1, nunca 0.0.0.0. Oasis (:3000) es la única puerta al exterior.

HTTP Endpoints — Referencia Completa

Endpoint	Content-Type	Uso en Arq. 3
GET /api/frame.mjpeg?src=	multipart/x-mixed-replace	MJPEG continuo → Oasis GET /video → <img>
GET /api/stream.m3u8?src=	application/vnd.apple.mpegurl	HLS playlist → Oasis GET /video.m3u8 → <video>
GET /api/frame.jpeg?src=	image/jpeg	Snapshot → Oasis GET /snapshot → SSB blob
GET /api/stream.mp4?src=	video/mp4	MP4 progressive (descarga)
POST /api/webrtc?src=	application/sdp (WHEP)	WebRTC P2P (necesita JS en browser)
GET /api/streams	application/json	Lista de streams (health check)
GET /api/config	application/json	Config cargada (debug)
GET /	text/html	WebUI embebida (debug, no exponer)

/api/frame.jpeg genera un snapshot JPEG puntual — ideal para guardar como SSB blob inmutable. Usar en cron para thumbnails del feed.

Captura: V4L2 vs CSI (libcamera)

Cámara	Stream config	Nota
USB (UVC)	v4l2:///dev/video0	Plug and play. Más simple.
CSI (libcamera)	exec:libcamerify v4l2-ctl --stream	Requiere libcamera-tools
CSI (legacy MMAL)	exec:raspivid -t 0 -o -	Deprecated en Bookworm
RTSP externa	rtsp://IP/stream	Cámara IP en la LAN

go2rtc no usa V4L2 M2M HW encode (a diferencia de µStreamer). Para CSI, usa la capa de captura de libcamera pero encodea JPEG en CPU. Si la CPU importa mucho → considerar Arq. 6.

Para CSI en Bookworm: sudo modprobe bcm2835-v4l2 antes de arrancar. O usar exec:libcamerify en el YAML.

Key Concept: HLS — La Ventaja clave de go2rtc

HLS (HTTP Live Streaming) fragmenta el vídeo H.264 en segmentos .ts de ~2-6 seg, listados en un .m3u8. El browser descarga segmentos secuencialmente. Resultado: ×10 menos BW que MJPEG, ideal para peers remotos sobre Tor.

# HLS playlist ejemplo (lo que devuelve go2rtc) #EXTM3U #EXT-X-VERSION:3 #EXT-X-TARGETDURATION:4 #EXT-X-MEDIA-SEQUENCE:0 #EXTINF:4.000, segment-000.ts #EXTINF:4.000, segment-001.ts

Browser	HLS nativo (sin JS)	Con hls.js
Safari (macOS/iOS)	✔ nativo	✔
Firefox	✘	✔ (necesita JS)
Chromium	✘	✔ (necesita JS)
Tor Browser (Firefox)	✘	⚠️ (JS=riesgo privacidad)

HLS sin JS solo funciona en Safari. Para Firefox/Chrome remoto: o se permite hls.js en una ruta /remote, o se usa MJPEG directo (más BW). Decisión de diseño del equipo.

WHEP — WebRTC sin Signaling Server

WHEP (WebRTC-HTTP Egress Protocol): estándar IETF que permite consumir streams WebRTC con una simple petición HTTP POST + SDP. go2rtc lo implementa nativamente en /api/webrtc.

# WHEP handshake (lo que haría un browser con JS) POST /api/webrtc?src=solar-cam Content-Type: application/sdp v=0 o=- ... IN IP4 0.0.0.0 ... a=recvonly → 201 Created + SDP answer

WHEP requiere JS en el browser (RTCPeerConnection). No usar para el browser LAN del SNH (cero JS). Reservar para peers remotos con browser estándar.

Troubleshooting — Quick Fixes

Síntoma	Causa probable	Fix
/dev/video0 not found	No hay cámara	lsusb, dmesg \| grep video, verificar cable
YAML parse error	Indentación incorrecta	python3 -c "import yaml; yaml.safe_load(open('go2rtc.yaml'))"
MJPEG sin frames	Stream name incorrecto	Verificar ?src= coincide con key en streams:
High CPU	Alta resolución + JPEG encode CPU	Reducir a 720p en cámara o en ffmpeg passthrough
HLS 404	Stream no generando segmentos	Esperar ~10 seg tras conectar, verificar /api/streams
Address in use :1984	Otra instancia	killall go2rtc; verificar systemctl status
CSI no captura	libcamera no configurado	apt install libcamera-tools; probar libcamerify v4l2-ctl --list-devices
go2rtc: exec not found	ffmpeg no en PATH	apt install ffmpeg

Keywords

go2rtc.yaml V4L2 ALSA MJPEG HLS .m3u8 .ts segments WHEP RTSP WebRTC :1984 snapshot Go binary libcamerify exec: