beam: streaming de videos efímeros en C99 con peticiones Range y túneles HTTPS

Publicado: 14 de septiembre de 2026. Categoría: Sistemas & Redes. Tiempo de lectura: ~6 min
Etiquetas: C99, beam, HTTP, Redes, POSIX, Video

En mi artículo anterior expliqué cómo construí autodub para transcribir, traducir y doblar videos en inglés al español y mandárselos a mi novia, ahorrándole el cansancio de leer subtítulos después de trabajar todo el día frente a una pantalla.

Pero apenas empecé a usar la herramienta en la vida real, me di cuenta de que tenía resuelta solo la mitad del problema.

El pipeline de autodub me dejaba un archivo .mp4 de 300 o 500 MB impecable en mi disco duro. La pregunta inmediata era: ¿cómo se lo hago llegar a ella de una vez y sin fricción?

Las opciones convencionales son todas un fastidio:

WhatsApp o Telegram: comprimen el video hasta volverlo una sopa de píxeles, tardan un siglo subiendo archivos pesados o imponen límites de tamaño arbitrarios.
Google Drive, Dropbox o WeTransfer: implican abrir el navegador, esperar que suba el archivo completo, copiar un enlace y lidiar con almacenamiento en la nube. Peor todavía: Google Drive se queda "procesando el video" durante diez o quince minutos antes de permitir streaming web, obligando a la otra persona a descargar el archivo entero antes de poder reproducir el primer segundo.
Nginx, S3 o CloudFront: levantar un servidor web público o configurar buckets para compartir videos personales de 20 minutos es matar moscas a cañonazos, cuesta dinero y requiere mantenimiento innecesario.

Yo no quería subir nada a la nube. El video ya estaba en mi computadora. Lo único que quería era exponer ese archivo local mediante un enlace web efímero para que ella lo abriera en Safari o Chrome desde su teléfono o laptop, le diera play y comenzara a sonar de inmediato en el reproductor nativo del navegador, con capacidad de adelantar o atrasar la reproducción (seek), y que cuando terminara o pasaran unas horas, el servidor se apagara solo.

Para resolver esto escribí beam: un servidor HTTP mínimo en C99 puro diseñado para compartir archivos locales mediante enlaces temporales, streaming con peticiones Range y túneles HTTPS automáticos.

1. El reproductor nativo y las peticiones HTTP Range (206)

Cuando abres un video en un navegador móvil como Safari en iOS o Chrome en Android, el navegador no hace una petición GET normal para bajarse el archivo completo de un solo golpe.

Los reproductores modernos dependen del estándar HTTP Range Requests (RFC 7233):

Navegador (Cliente)                              beam (Servidor C99)
       │                                                 │
       │─── GET /token (Range: bytes=0-1048575) ────────>│
       │                                                 │ [Lee primeros bytes]
       │<── 206 Partial Content (Content-Range: 0-...) ──│
       │                                                 │
  [Play inmediato]                                       │
       │                                                 │
  [Usuario adelanta al min 15:30]                        │
       │─── GET /token (Range: bytes=35684000-) ────────>│
       │                                                 │ [sendfile() en offset]
       │<── 206 Partial Content (Content-Range: ...) ────│

El navegador solicita primero unos pocos kilobytes o megabytes para inspeccionar los metadatos del contenedor (Range: bytes=0-1048575).
Comprueba si el servidor soporta rangos verificando la cabecera Accept-Ranges: bytes.
Si el usuario arrastra la barra de reproducción hasta la mitad del video, el cliente cancela la descarga actual e inmediatamente dispara una nueva petición con el offset exacto: Range: bytes=35684000-.

Si el servidor responde con un simple 200 OK y empieza a transmitir el archivo desde el byte 0, el reproductor entra en pánico: o bloquea la barra de desplazamiento obligando al usuario a esperar que baje todo el video, o sencillamente se queda en negro.

En beam implementé un parser estricto de peticiones Range en C99. Soporta:

Rangos abiertos: Range: bytes=1024- (desde el byte 1024 hasta el final del archivo).
Rangos cerrados: Range: bytes=0-499 (los primeros 500 bytes exactos).
Rangos de sufijo: Range: bytes=-1000 (los últimos 1000 bytes del archivo).
Validación de límites: si el offset solicitado supera el tamaño real del archivo, responde de inmediato con 416 Range Not Satisfiable y la cabecera Content-Range: bytes */TOTAL.

Al responder con 206 Partial Content y la cabecera Content-Disposition: inline, los navegadores abren el archivo directo en sus controles nativos de video y permiten adelantar o retroceder con latencia casi nula.

2. El problema del átomo moov en archivos MP4

Hay una trampa muy común al hacer streaming de video en la web con archivos MP4.

En el formato contenedor ISO base media (MP4/MOV), los metadatos del video (duración, resolución, códecs y la tabla de muestras temporales) se almacenan en un bloque llamado átomo moov. Los datos crudos de video y audio se almacenan en el átomo mdat.

Por defecto, muchos codificadores colocan el átomo moov al final del archivo, después de todo el bloque mdat:

MP4 sin optimizar:
[ ftyp ][                     mdat (500 MB)                     ][ moov (1 MB) ]
  ▲                                                                 ▲
  Inicio                                                            Metadatos al final

MP4 con Faststart (+faststart):
[ ftyp ][ moov (1 MB) ][                     mdat (500 MB)                     ]
  ▲        ▲
  Inicio   Metadatos disponibles en el byte 32 -> Play instantáneo

Si el átomo moov está al final, el navegador no puede calcular la duración del video ni decodificar los fotogramas iniciales sin haber leído primero esos metadatos. En conexiones móviles o a través de túneles, esto causa demoras enormes antes de que comience el video.

beam inspecciona automáticamente el encabezado del archivo. Si detecta que se trata de un archivo MP4 y ffmpeg está disponible en el sistema, ejecuta un remux ultra rápido en segundo plano utilizando -movflags +faststart. Esto reubica el átomo moov al inicio del archivo sin reencodear nada. El proceso toma apenas un par de segundos y garantiza que el video comience a reproducirse en menos de 100 milisegundos.

3. De túneles SSH inversos a Cloudflare Quick Tunnels

Compartir un servidor local que corre en localhost:8080 con alguien fuera de tu red local suele ser un rollo: abrir puertos en el router es imposible bajo CGNAT residencial, el DNS dinámico es tedioso, y configurar daemons persistentes exige registrarse y manejar API keys.

En el primer prototipo de beam, resolví esto abriendo un túnel SSH inverso contra localhost.run:

/* Prototipo inicial: reenvío de puertos remoto con OpenSSH */
execlp("ssh", "ssh",
       "-T",
       "-o", "StrictHostKeyChecking=no",
       "-o", "UserKnownHostsFile=/dev/null",
       "-o", "ExitOnForwardFailure=yes",
       "-o", "Compression=no",
       "-o", "IPQoS=throughput",
       "-R", port_spec,
       "nokey@localhost.run",
       (char *)NULL);

Aunque funcionaba como prueba de concepto, las pruebas en redes celulares revelaron dos problemas serios de arquitectura:

TCP-over-TCP y Head-of-Line Blocking: Encapsular tráfico HTTP sobre una conexión TCP de SSH provocaba caídas brutales de rendimiento ante la menor pérdida de paquetes.
Cabeceras fragmentadas por latencia: En conexiones móviles con alta latencia, SSH dividía la petición HTTP en múltiples paquetes. Si el servidor llamaba a recv() y recibía únicamente GET /token HTTP/1.1 antes de que la cabecera Range: llegara en el siguiente segmento TCP, beam asumía que era una petición sin rango y devolvía un 200 OK completo desde el byte 0, congelando el reproductor.

Para solucionar esto de raíz, reemplacé el reenvío por SSH por Cloudflare Quick Tunnels (cloudflared):

/* Implementación actual: Cloudflare Quick Tunnel sin cuentas */
snprintf(origin, sizeof(origin), "http://127.0.0.1:%d", local_port);
bin = getenv("BEAM_TUNNEL_BIN");
if (!bin || !bin[0])
    bin = "cloudflared";
execlp(bin, bin, "tunnel", "--url", origin, "--no-autoupdate", (char *)NULL);

Ventajas clave de este cambio:

Sin encapsulación SSH: El tráfico viaja directo desde la red Anycast de Cloudflare hacia el daemon HTTP local. Sin handshakes SSH, sin advertencias de known_hosts y sin bloqueos de TCP sobre TCP.
Extracción dinámica de la URL: beam vigila el proceso hijo cloudflared mediante una tubería no bloqueante, extrae la URL https://*.trycloudflare.com y mantiene el pipe de logs abierto para evitar que cloudflared muera por Broken Pipe (SIGPIPE).
Propagación en el Edge: Espera un segundo antes de mostrar el enlace para que las tablas de enrutamiento de Cloudflare se propaguen en el edge antes de que el usuario lo abra.
Resiliencia ante caídas: Si el túnel se cae, beam lo levanta de nuevo automáticamente y refresca la URL sin interrumpir las descargas locales.

4. Rendimiento del sistema: sendfile(), keep-alive y tracking de sesiones Range

Dado que beam fue escrito en C99 puro sobre POSIX, optimicé la transmisión para lidiar con las mañas de los reproductores móviles:

Streaming zero-copy y ajustes de socket

Zero-copy con sendfile(2): En Linux, beam transfiere los rangos solicitados directamente desde el descriptor del archivo hacia el socket TCP en el kernel. Los bytes nunca tocan la memoria RAM en espacio de usuario, manteniendo el uso de memoria en unos pocos kilobytes aunque se sirvan videos 4K de varios gigabytes.
Ajustes de socket: Se configuran sockets con TCP_NODELAY (desactivando el algoritmo de Nagle para enviar los rangos sin retraso), TCP_QUICKACK en Linux para reducir los round-trips de confirmación, y posix_fadvise(fd, offset, len, POSIX_FADV_SEQUENTIAL) para forzar lectura anticipada en el page cache del kernel.
Conexiones persistentes (Connection: keep-alive): Los reproductores móviles disparan decenas de peticiones Range seguidas. Usar HTTP/1.1 persistente en el mismo socket ahorra el costo de múltiples apretones de manos TCP.
Buffer de cabeceras robusto: Se acumulan bytes hasta encontrar el terminador \r\n\r\n con control de tiempo mediante gettimeofday. Los bytes sobrantes tras el terminador se conservan para procesar peticiones encoladas (pipelining).

Manejo de sesiones Range en modo de un solo uso (`-1`)

Un servidor efímero clásico se apaga apenas entrega un archivo completo. Pero los reproductores de video nunca piden el archivo completo de un tirón: hacen decenas de peticiones 206 Partial Content mientras cargan buffers o el usuario adelanta.

Si -1 se apagara en la primera petición, el video moriría a los 100 milisegundos.

En beam, el flag -1 cuenta una respuesta Range completada como una sesión de espectador activa. Mientras el reproductor siga pidiendo fragmentos, el servidor sigue vivo. Una vez que todos los workers hijos terminan y expira la ventana de gracia de 2 segundos de keep-alive para clientes inactivos, beam se apaga limpiamente.

Reanudación y controles en vivo

Si cierras beam y más tarde quieres volver a compartir el mismo archivo, basta con ejecutar beam -p -c (o beam -r). Reabre el archivo anterior manteniendo el mismo token, por lo que el enlace ya compartido sigue funcionando.

Además, mientras corre en la consola puedes presionar [p] para abrir o reabrir el túnel bajo demanda, [c] para copiar el enlace al portapapeles, o [q] para salir.

5. La tubería UNIX perfecta con autodub

El motivo principal por el que construí beam fue integrarlo de forma natural con autodub siguiendo la filosofía UNIX: herramientas pequeñas, enfocadas y conectables mediante pipes.

# Doblar un video de YouTube y compartirlo públicamente de inmediato
autodub "https://www.youtube.com/watch?v=EXAMPLE_ID" | beam -p -c

¿Qué ocurre internamente cuando ejecuto ese comando?

┌──────────────────────────────────────────────────────────────┐
│ autodub (Python)                                             │
│ 1. Descarga video con yt-dlp                                 │
│ 2. Transcribe con faster-whisper en CPU                      │
│ 3. Traduce texto y sintetiza con Piper TTS                   │
│ 4. Alinea audio en memoria y aplica ducking con FFmpeg       │
│ 5. Imprime en stdout: "Dubbed: /tmp/autodub/video_es.mp4"    │
└──────────────────────────────┬───────────────────────────────┘
                               │ (pipe en tiempo real)
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ beam (C99)                                                   │
│ 1. Muestra el progreso de autodub en la terminal             │
│ 2. Detecta la ruta del video final cuando el proceso termina │
│ 3. Ejecuta faststart con FFmpeg si es necesario              │
│ 4. Abre el túnel reverso SSH (-p)                            │
│ 5. Copia el enlace HTTPS al portapapeles (-c)                │
│ 6. Dibuja el código QR en la consola                         │
│ 7. Sirve el video con peticiones Range hasta que expire      │
└──────────────────────────────────────────────────────────────┘

Cuando autodub termina su trabajo, beam captura la ruta del archivo generado, levanta el servidor, abre el túnel público, copia el enlace al portapapeles del sistema (usando clipbridge o wl-copy) y me avisa.

Yo solo tengo que pegar el enlace en el chat con mi novia. Ella hace clic en el enlace desde su teléfono, el video comienza a sonar de inmediato en su navegador sin logins ni publicidad, y yo me desentiendo por completo porque a las 5 horas el servidor expira y se apaga solo.

El código fuente en C99, manual de uso y pruebas unitarias están disponibles en GitHub: github.com/riccivr/beam.

beam: streaming dubbed videos with ephemeral HTTP tunnels and Range requests in C99

Published: September 14, 2026. Category: Systems & Networking. Reading time: ~6 min
Tags: C99, beam, HTTP, Networking, POSIX, Video

In my previous post, I wrote about building autodub to transcribe, translate, and dub English videos into Spanish so I could send them to my girlfriend, sparing her the eye fatigue of reading tiny subtitles after working in front of a screen all day.

As soon as I started using it regularly, I ran straight into the second half of the problem.

The autodub pipeline produced a clean 300 MB or 500 MB .mp4 file sitting on my local drive. But how was I supposed to get that video to her immediately, with zero friction?

The standard options were all frustrating:

WhatsApp or Telegram: messaging apps either recompress the video into pixelated mush, take ages to upload, or enforce arbitrary file size caps.
Google Drive, Dropbox, or WeTransfer: you have to open a browser tab, wait for the full upload to complete, copy a link, and deal with cloud storage limits. Worse, Google Drive frequently spends 10 to 15 minutes "processing" the video before letting you stream it, forcing the other person to download the entire 400 MB file before playing a single frame.
Nginx, S3, or CloudFront: spinning up a public web server or provisioning cloud storage buckets just to share a 20-minute video with someone is complete overkill, costs money, and requires maintenance.

I had no interest in uploading files to cloud services. The video already lived on my hard drive. All I wanted was a temporary, self-expiring link that allowed her to open Safari or Chrome on her phone or laptop, press play, and have the video stream instantly in the native media player with full seeking support, shutting down automatically once the timer expired.

To solve this, I built beam: a zero-dependency, minimal HTTP file-sharing server written in C99, designed specifically for ephemeral media streaming via single-range byte seeking and automated HTTPS reverse tunnels.

1. Native browser playback and HTTP Range requests (206)

When you tap a video link in iOS Safari or Android Chrome, the mobile browser does not issue a single monolithic GET request to pull down the entire file.

Modern web media players rely heavily on the HTTP Range Requests specification (RFC 7233):

Browser (Client)                                 beam (C99 Server)
       │                                                 │
       │─── GET /token (Range: bytes=0-1048575) ────────>│
       │                                                 │ [Reads initial metadata]
       │<── 206 Partial Content (Content-Range: 0-...) ──│
       │                                                 │
  [Instant Playback]                                     │
       │                                                 │
  [User seeks forward to 15:30]                          │
       │─── GET /token (Range: bytes=35684000-) ────────>│
       │                                                 │ [sendfile() at offset]
       │<── 206 Partial Content (Content-Range: ...) ────│

The browser requests an initial small slice of bytes (e.g. Range: bytes=0-1048575) to inspect container headers.
It verifies that the server advertises Accept-Ranges: bytes.
When the viewer drags the scrubber forward, the player cancels the in-flight transfer and immediately sends a new request with the exact target offset: Range: bytes=35684000-.

If your HTTP server responds with a naive 200 OK and attempts to stream from byte 0, mobile players choke: scrubbers lock up, playback freezes, or the interface errors out.

In beam, I wrote a strict byte-range parser in C99. It handles:

Open-ended ranges: Range: bytes=1024- (from offset 1024 through EOF).
Closed ranges: Range: bytes=0-499 (exactly the first 500 bytes).
Suffix ranges: Range: bytes=-1000 (the final 1000 bytes of the file).
Boundary checks: if the requested offset exceeds the file length, beam replies immediately with 416 Range Not Satisfiable and Content-Range: bytes */TOTAL.

By returning 206 Partial Content along with Content-Disposition: inline, browsers trigger their built-in system player, delivering native hardware-accelerated playback with near-zero initial buffering.

2. The MP4 moov atom problem

Serving MP4 files over HTTP has an infamous architectural catch.

In the ISO Base Media File Format (MP4/MOV), critical video metadata (duration, frame rate, resolution, codec configurations, and the sample index table) is stored inside the moov atom. Raw audio and video frames live inside the mdat atom.

By default, most encoders write the moov atom at the very end of the file, after all media samples:

Default MP4:
[ ftyp ][                     mdat (500 MB)                     ][ moov (1 MB) ]
  ▲                                                                 ▲
  File start                                                        Metadata at the end

Faststart MP4 (+faststart):
[ ftyp ][ moov (1 MB) ][                     mdat (500 MB)                     ]
  ▲        ▲
  Start    Metadata at byte 32 -> Instant streaming playback

When the moov atom sits at the end of a 500 MB file, a web browser cannot begin playing or calculate total runtime until it has fetched the end of the file. Over high-latency tunnels or mobile data, this causes noticeable playback lag.

beam inspects the container header at startup. If it is serving an MP4 and ffmpeg is available on the machine, it runs a background remux with -movflags +faststart. This relocates the moov atom to the very beginning of the container without re-encoding any audio or video tracks. It takes two seconds and ensures that playback starts within 100 milliseconds.

3. From SSH reverse tunnels to Cloudflare Quick Tunnels

Sharing a local server running on localhost:8080 with someone outside your local network usually means setting up port forwarding (often impossible behind residential CGNAT), managing Dynamic DNS, or configuring persistent tunnel daemons with accounts and API keys.

In the initial prototype of beam, I implemented public tunneling via OpenSSH reverse port-forwarding to localhost.run:

/* Initial prototype: OpenSSH reverse port-forwarding */
execlp("ssh", "ssh",
       "-T",
       "-o", "StrictHostKeyChecking=no",
       "-o", "UserKnownHostsFile=/dev/null",
       "-o", "ExitOnForwardFailure=yes",
       "-o", "Compression=no",
       "-o", "IPQoS=throughput",
       "-R", port_spec,
       "nokey@localhost.run",
       (char *)NULL);

While that worked for a quick proof of concept, real-world testing over cellular networks uncovered two painful architectural flaws:

TCP-over-TCP and Head-of-Line Blocking: Encapsulating HTTP over an SSH TCP tunnel caused throughput collapse whenever minor packet loss occurred.
Split Packet Headers: High-latency SSH links frequently split the HTTP request across multiple packets. If the server called recv() once and only got the GET /token HTTP/1.1 line before the Range: header arrived in the next TCP segment, beam fell back to serving a full 200 OK from byte 0, crashing the mobile video scrubber.

To permanently fix this, I replaced SSH port-forwarding with Cloudflare Quick Tunnels (cloudflared):

/* Modern beam: Zero-account Cloudflare Quick Tunnel */
snprintf(origin, sizeof(origin), "http://127.0.0.1:%d", local_port);
bin = getenv("BEAM_TUNNEL_BIN");
if (!bin || !bin[0])
    bin = "cloudflared";
execlp(bin, bin, "tunnel", "--url", origin, "--no-autoupdate", (char *)NULL);

Why Cloudflare Quick Tunnels make a massive difference:

No SSH encapsulation overhead: Traffic routes directly from Cloudflare's global Anycast edge down to the local HTTP daemon. No SSH handshakes, no host key prompts, and zero TCP-over-TCP meltdown.
Dynamic URL extraction: beam monitors the child cloudflared process using a non-blocking pipe, extracts the generated https://*.trycloudflare.com URL, and keeps the log pipe open so cloudflared never hits a broken pipe (SIGPIPE).
Edge route propagation delay: A short one-second wait ensures Cloudflare's edge routing tables propagate before the URL is printed to the terminal or copied to the clipboard.
Tunnel resilience: If the connection drops or the process exits, beam automatically re-establishes the tunnel and prints the new URL without interrupting the underlying HTTP server.

4. Systems performance: sendfile(), keep-alive, and Range session tracking

Because beam is written from scratch in POSIX C99, I tuned the network transmission pipeline specifically for the quirky behavior of mobile video players:

Zero-copy streaming and socket tuning

Kernel zero-copy with sendfile(2): On Linux systems, beam streams requested byte ranges directly from the file descriptor into the TCP socket within the kernel. Bytes never travel through user-space RAM, keeping memory consumption down to a few kilobytes even when streaming multi-gigabyte 4K media.
Socket flags: Sockets are tuned with TCP_NODELAY (disabling Nagle's algorithm for immediate range delivery), TCP_QUICKACK on Linux to minimize ACK round-trips, and posix_fadvise(fd, offset, len, POSIX_FADV_SEQUENTIAL) to trigger aggressive kernel page cache readahead.
Persistent connections (Connection: keep-alive): Native players fire dozens of Range requests in rapid succession. Speaking HTTP/1.1 persistent connections on the same socket eliminates the latency of repeated three-way TCP handshakes.
Robust header buffering: Incoming requests are buffered until the \r\n\r\n boundary is reached, with gettimeofday timeout bounds. Any leftover bytes after the terminator are preserved for the next pipelined request on the socket.

Range session tracking in one-shot mode (`-1`)

A classic burn-after-reading file server simply terminates after serving one complete file. But video players never download the entire file in one request. They fire dozens of 206 Partial Content requests as the user buffers and seeks.

If -1 had terminated on the first request, the video would freeze after 0.1 seconds.

In beam, the -1 flag treats a finished Range response as part of an active viewer session. As long as the viewer continues requesting chunks, the worker stays alive. Once all sibling worker processes finish and the two-second keep-alive grace window closes, beam safely terminates.

Resume and interactive controls

If you close beam and want to re-share the same video later, running beam -p -c (or beam -r) reopens the previous file while preserving the original token hash, keeping existing shared links alive.

While beam runs, you can also press [p] to reopen or refresh the tunnel on demand, [c] to re-copy the URL, and [q] to quit cleanly.

5. UNIX composition with autodub

The primary reason I built beam was to close the loop with autodub using classic UNIX piping principles: small, focused utilities composed together.

# Dub a YouTube video and immediately share it publicly
autodub "https://www.youtube.com/watch?v=EXAMPLE_ID" | beam -p -c

Here is what happens during that pipeline:

┌──────────────────────────────────────────────────────────────┐
│ autodub (Python)                                             │
│ 1. Downloads media with yt-dlp                               │
│ 2. Transcribes on CPU using faster-whisper                   │
│ 3. Translates text and synthesizes speech via Piper TTS      │
│ 4. Performs PCM alignment and FFmpeg audio ducking           │
│ 5. Writes to stdout: "Dubbed: /tmp/autodub/video_es.mp4"     │
└──────────────────────────────┬───────────────────────────────┘
                               │ (real-time pipe stream)
                               ▼
┌──────────────────────────────────────────────────────────────┐
│ beam (C99)                                                   │
│ 1. Echoes autodub's progress bars to the terminal            │
│ 2. Extracts the final dubbed video path when completed       │
│ 3. Executes faststart remuxing if necessary                  │
│ 4. Opens the public HTTPS reverse tunnel (-p)                │
│ 5. Copies the secure URL to the system clipboard (-c)        │
│ 6. Renders the ANSI QR code in the terminal                  │
│ 7. Streams Range chunks until the TTL expires                │
└──────────────────────────────────────────────────────────────┘

Once autodub finishes processing, beam detects the output file path, launches the HTTP daemon, establishes the HTTPS tunnel, and places the ready-to-share URL straight onto my clipboard via clipbridge or wl-copy.

All I have to do is paste the link into a chat with my girlfriend. She taps it from her phone, the video streams immediately in Safari without logins, ads, or file downloads, and the server automatically shuts down five hours later.

The complete C99 source code, man page, and test suite are available on GitHub: github.com/riccivr/beam.

[<] Volver al Blog [^] Arriba