SPEC · go2rtc

Identidad del Componente

Campo	Valor
Repo	github.com/AlexxIT/go2rtc
Lenguaje	Go (binario estático)
Licencia	MIT
Binario ARM	~15 MB (pre-compilado, descargar y ejecutar)
RAM típica	~20–40 MB (depende de re-encode)
Ecosistema	Home Assistant, Frigate — miles de despliegues
Killer feature	V4L2 + ALSA directo → multi-protocolo sin ffmpeg

Key Concept

go2rtc captura de fuentes heterogéneas (V4L2, ALSA, RTSP, exec, MJPEG…) y las re-sirve simultáneamente en múltiples formatos de salida. No es un transcoder pesado: reempaqueta cuando puede (PCMA→FLAC para MSE, passthrough H.264) y solo re-codifica cuando es estrictamente necesario. El resultado: un solo proceso reemplaza ffmpeg + servidor HTTP + lógica de streaming.

go2rtc.yaml — Referencia Completa

# /etc/go2rtc/go2rtc.yaml # ── Streams ── streams: solar-cam: - v4l2:///dev/video0 # fuente principal (CSI o USB) # Alternativas CSI más eficientes: # - exec:rpicam-vid -t 0 --codec h264 --inline -w 1280 -h 720 -o - # Alternativa USB con H.264 HW nativo: # - v4l2:///dev/video0#format=h264 solar-mic: - alsa:///default # micrófono USB # go2rtc transcodifica PCMA/PCMU → FLAC para MSE/HLS auto # Stream compuesto (vídeo + audio en uno): # solar-av: # - v4l2:///dev/video0 # - alsa:///default # ── API ── api: listen: "127.0.0.1:1984" # solo local (Oasis hace proxy) # origin: "*" # CORS si se accede directo # ── RTSP (opcional, si otros servicios consumen) ── rtsp: listen: "127.0.0.1:8554" # ── WebRTC (WHEP) ── webrtc: listen: ":8555" # para clients con JS candidates: - stun:stun.l.google.com:19302 # solo LAN: no necesario # ── Log ── log: level: info # debug | info | warn | error

API HTTP Endpoints (:1984)

Endpoint	Formato	Content-Type	HTML sin JS	Latencia
/api/frame.mjpeg?src={name}	MJPEG continuo	multipart/x-mixed-replace	✔ `<img>`	100–300 ms
/api/stream.m3u8?src={name}	HLS fMP4	application/vnd.apple.mpegurl	✔ `<video>`	2–6 s
/api/stream.mp4?src={name}	MP4 progressive	video/mp4	✔ `<video>`	~1 s
/api/frame.jpeg?src={name}	JPEG snapshot	image/jpeg	✔ `<img>`	instant
/api/webrtc?src={name}	WHEP offer	application/sdp	✘ (JS)	~100 ms
/api/ws?src={name}	WebSocket	—	✘ (JS)	~100 ms
/api/streams	JSON status	application/json	N/A	—
/	Web UI	text/html	N/A	—

Todos los endpoints video soportan parámetro width y height para redimensionar on-the-fly.

Transcodificación Automática

Entrada	Salida	Proceso	CPU
H.264 (CSI rpicam-vid)	HLS fMP4	Reempaquetado (mux only)	~1%
H.264	MJPEG	Decode frame → JPEG	~5–10%
MJPEG (USB)	MJPEG stream	Passthrough	~0%
MJPEG (USB)	HLS	Re-encode H.264 (SW)	~15–25%
PCMA/PCMU (ALSA)	FLAC (MSE/HLS)	Transcode auto	~1%
PCMA/PCMU	Opus (WebRTC)	Resample + encode	~2%

Caso crítico: USB MJPEG → HLS requiere re-encode H.264 en software (~15–25% CPU). Solución: si la webcam tiene H.264 HW nativo, usar #format=h264 para passthrough.

Audio: ALSA → Browser

go2rtc captura ALSA directamente — ni MediaMTX ni µStreamer pueden hacer esto. El audio pasa por la misma API que el vídeo. Para browser sin JS: HLS incluye audio automáticamente en el fMP4. Para browser con JS: WHEP entrega Opus.

Ruta sin JS	HTML	Latencia
/api/stream.m3u8?src=solar-mic	`<video src="…" autoplay>`	2–6 s
/api/stream.m3u8?src=solar-av	`<video>` (AV compuesto)	2–6 s

Alternativa baja latencia: proxy Oasis con ffmpeg ALSA→OGG para <audio src="/audio.ogg"> (~200 ms). O Mumble bridge (Arq. 3) para bidireccional.

V4L2: Detección y Formatos

# Listar dispositivos v4l2-ctl --list-devices # Ver formatos soportados v4l2-ctl -d /dev/video0 --list-formats-ext # Verificar que go2rtc puede acceder curl -s http://127.0.0.1:1984/api/streams | jq .

Formato V4L2	go2rtc URL	Nota
MJPEG	v4l2:///dev/video0	Formato por defecto de la mayoría de webcams USB
H.264	v4l2:///dev/video0#format=h264	Solo webcams con H.264 HW (ej: Logitech C920)
YUYV	v4l2:///dev/video0#format=yuyv	Raw — go2rtc codifica a MJPEG/H.264 (CPU alto)

Troubleshooting

Síntoma	Causa	Fix
v4l2: device busy	Otro proceso tiene /dev/video0	fuser -v /dev/video0 — matar proceso conflictivo
ALSA: no such device	Micrófono no detectado o nombre incorrecto	arecord -l — verificar device. Puede ser `alsa:///hw:1,0`
HLS: no audio	Stream de cámara no incluye audio	Crear stream compuesto solar-av con vídeo + audio como sources separados
MJPEG: imagen congelada	Buffer lleno, client lento	Reducir resolución o FPS. Verificar BW red.
Alta CPU (~25%)	Re-encode MJPEG→H.264 para HLS	Usar exec:rpicam-vid (CSI) o #format=h264 (USB con HW)
API 404 en /api/stream.*	Nombre de stream incorrecto en ?src=	Verificar en /api/streams que el nombre coincide con go2rtc.yaml
WebRTC no conecta (LAN)	Firewall bloquea UDP	Para cero-JS no se usa WebRTC. Si se necesita: abrir UDP 8555.

go2rtc V4L2 ALSA MJPEG HLS fMP4 WHEP FLAC passthrough :1984 snapshot