**Repo:** https://github.com/jjairocj/home-channel-hls (MIT)
---
## 🇬🇧 English
Hi everyone! I've been building **Home Channel HLS**, a self-hosted playout engine that turns a folder of your own videos into a **continuous 24/7 linear TV channel**. It feels like old-school cable TV: there's a schedule, shows start on the hour and half-hour, and there are bumpers and breaks between them. You don't pick from a menu, you just tune in.
**Why I built it:** nostalgia is part of it, but the real goal is a calmer relationship with screens. Yes, it's still a screen, but it works differently from a feed. There's no algorithm, no autoplay rabbit hole, no endless catalog to scroll through, and no subscription. Something is on, you watch it or you turn it off. A fixed schedule gives your time a shape again: shows start and end, and "what's on at 8" replaces 40 minutes of deciding what to watch. It's an attempt to push back against doomscrolling and the constant overstimulation we've gotten used to, using media you already own.
**Some context on the repo:** the public repo was created just yesterday, but the project isn't new. It started as a private, local project just for me, and I've been working on it for over a year. After talking it over with some friends, I decided to open it up so anyone can use it. I took the chance to separate it from my private setup and improve the development practices (docs, tests, Docker). That's why the public history starts with a single commit.
**What it does**
- **Continuous HLS stream** (`/live/channel.m3u8`) with fast start, playable in the browser, VLC, Kodi, TiviMate, and Smart TV / Android TV IPTV apps. It also exposes an M3U playlist.
- **Clock-aligned slots:** shows snap to `:00` and `:30`, so the schedule doesn't drift over the day.
- **Interstitial composer:** fills the gaps between episodes with "You're watching…" bumpers, non-repeating spots, station idents, and "Coming up next…" previews.
- **Next-up graphics + voiceover:** SVG billboards rendered on the fly, announced with TTS (local edge-tts or ElevenLabs).
- **Weekly grid with rules:** drag-and-drop planner, automatic daily episode progression, weekend marathons, a printable PDF schedule, and **XMLTV EPG** export (`/epg.xml`).
- **Hardware encoding:** NVENC, VAAPI/QuickSync, VideoToolbox, or `libx264` CPU fallback.
- **Web "Master Control":** monitor stream health, override what's on air, manage the transcode queue, and see viewer stats.
- **FM-style radio mode:** an audio-only HLS station with a retro 90s Hi-Fi tuner UI (analog dial, RDS display) and an automated DJ. The DJ's intros are written by a **local LLM via Ollama** (with templates as a fallback when Ollama isn't configured) and voiced with edge-tts. Rotation avoids playing the same artist twice in a row, and a jingle plays every few songs.
- UI in English and Spanish, and you can add a language by dropping in a JSON file.
**Stack:** Node.js 22, Express, FFmpeg, PostgreSQL (with a local JSON fallback), Docker Compose. HLS segments are written to a tmpfs RAM disk to avoid SSD wear.
**Tests:** 111 unit tests (`node --test`) covering clock and slot math, break composition and anti-repetition, episode progression, EPG generation, radio rotation, and auth/rate-limiting. End-to-end tests of the FFmpeg/HLS pipeline are on the roadmap.
**Quick start**
git clone https://github.com/jjairocj/home-channel-hls.git
cd home-channel-hls && cp .env.example .env
docker compose up -d
Then open `http://localhost:3000` for the player and `/admin` for Master Control.
**Scope note:** it's meant for media you have the rights to: personal recordings, public domain, Creative Commons (the demo uses Blender open movies). There are no scrapers.
**On AI use (transparency):** this project was co-developed with AI coding assistants. My role was mainly requirements analysis, defining the architecture, and choosing the tech stack. I also wrote code, but AI wrote a large share of it, including the FFmpeg pipelines and the automated tests, and it solved several problems I was stuck on or didn't know how to approach. I reviewed the result and defined what the tests should check. The 111 tests are readable and runnable (`npm test`), so you can judge the core logic for yourself.
**Make it yours:** the whole point is for people to use it and adapt it to their own needs: a kids' channel with curated content, a channel of family videos, a 24/7 local radio station, whatever you have in mind. Whether you customize it by hand or with an AI assistant is up to you. That's why the repo ships an `AGENTS.md`, an architecture manual that works for humans and assistants alike. It's MIT-licensed, so feel free to fork it and take it in any direction you like.
This is the first public release, and I'd really appreciate feedback on the architecture, the docs, or features you'd like to see. Issues and PRs are welcome!
---
## 🇪🇸 Español
¡Hola a todos! Les comparto **Home Channel HLS**, un motor de *playout* autoalojado que convierte una carpeta con tus propios videos en un **canal de TV lineal 24/7**. La idea es la experiencia de la televisión de antes: hay una programación, los programas empiezan en punto o y media, y entre ellos salen cortinillas y tandas. No eliges de un catálogo, simplemente sintonizas.
**Por qué lo hice:** la nostalgia es parte, pero el objetivo real es una relación más tranquila con las pantallas. Sí, sigue siendo una pantalla, pero funciona distinto a un feed. No hay algoritmo, ni reproducción automática que te arrastre, ni un catálogo infinito por el que deslizar, ni suscripción. Hay algo al aire: lo ves o apagas. Una programación fija le devuelve forma al tiempo: los programas empiezan y terminan, y "qué dan a las 8" reemplaza 40 minutos decidiendo qué ver. Es un intento de hacerle frente al *doomscrolling* y a la sobreestimulación constante a la que nos acostumbramos, usando contenido que ya tienes.
**Un poco de contexto sobre el repo:** el repositorio público se creó apenas ayer, pero el proyecto no es nuevo. Empezó como un proyecto privado y local, solo para mí, y llevo más de un año trabajando en él. Después de conversarlo con algunos amigos, decidí abrirlo para que cualquiera lo use. Aproveché para separarlo de mi configuración privada y mejorar las prácticas de desarrollo (documentación, tests, Docker). Por eso el historial público empieza con un solo commit.
**Qué hace**
- **Stream HLS continuo** (`/live/channel.m3u8`) de arranque rápido, que funciona en el navegador, VLC, Kodi, TiviMate y apps IPTV de Smart TV / Android TV. También genera una playlist M3U.
- **Franjas alineadas al reloj:** los programas arrancan en `:00` y `:30`, así que la parrilla no se desfasa durante el día.
- **Compositor de tandas:** rellena los espacios entre episodios con cortinillas tipo "Estás viendo…", comerciales que no se repiten, identificadores del canal y avances de "A continuación…".
- **Gráficos y voz dinámicos:** carteles SVG generados al vuelo y anunciados con TTS (edge-tts local o ElevenLabs).
- **Parrilla semanal por reglas:** planificador drag-and-drop, avance automático de episodios diarios, maratones de fin de semana, programación imprimible en PDF y exportación **EPG XMLTV** (`/epg.xml`).
- **Aceleración por hardware:** NVENC, VAAPI/QuickSync, VideoToolbox, o `libx264` por CPU como respaldo.
- **"Master Control" web:** monitoreas la salud del stream, cambias lo que está al aire, gestionas la cola de transcodificación y ves estadísticas de audiencia.
- **Modo radio estilo FM:** emisora HLS de solo audio con un sintonizador retro Hi-Fi de los 90 (dial analógico, display RDS) y un locutor automático. Sus presentaciones las escribe un **LLM local vía Ollama** (con plantillas de respaldo si Ollama no está configurado) y edge-tts les pone la voz. La rotación evita repetir el mismo artista dos veces seguidas, y suena un jingle cada pocas canciones.
- Interfaz en español e inglés, y puedes agregar un idioma solo con un archivo JSON.
**Stack:** Node.js 22, Express, FFmpeg, PostgreSQL (con respaldo local en JSON), Docker Compose. Los segmentos HLS se escriben en un disco RAM (tmpfs) para no desgastar el SSD.
**Pruebas:** 111 tests unitarios (`node --test`) que cubren la matemática de reloj y franjas, la composición de tandas y la anti-repetición, el avance de episodios, la generación del EPG, la rotación de la radio y la autenticación con límite de intentos. Las pruebas end-to-end del pipeline FFmpeg/HLS están en el roadmap.
**Inicio rápido:** los mismos 3 comandos de arriba, y luego abres `http://localhost:3000` (reproductor) y `/admin` (Master Control).
**Alcance:** está pensado para contenido sobre el que tienes derechos: grabaciones propias, dominio público, Creative Commons (el demo usa películas abiertas de Blender). No incluye scrapers.
**Sobre el uso de IA (transparencia):** este proyecto fue co-desarrollado con asistentes de programación con IA. Mi rol fue principalmente el análisis y la definición de requerimientos, la arquitectura y la elección de tecnologías. También escribí código, pero buena parte la escribió la IA, incluidos los pipelines de FFmpeg y las pruebas automatizadas, y resolvió varios problemas en los que estaba atascado o que no sabía cómo abordar. Revisé el resultado y definí qué debían validar las pruebas. Los 111 tests se pueden leer y ejecutar (`npm test`), así que cualquiera puede juzgar la lógica central por sí mismo.
**Hazlo tuyo:** la idea es que la gente lo use y lo adapte a lo que necesite: un canal infantil con contenido curado, un canal con los videos de la familia, una radio local 24/7, lo que se te ocurra. Si lo personalizas a mano o con un asistente de IA, es decisión tuya. Por eso el repo incluye un `AGENTS.md`, un manual de arquitectura que sirve tanto a personas como a asistentes. Tiene licencia MIT, así que eres libre de hacer forks y llevarlo en la dirección que quieras.
Es la primera versión pública. Me encantaría recibir feedback sobre la arquitectura, la documentación o funciones que les gustaría ver. ¡Issues y PRs bienvenidos!