¿Qué es jellyfin-force-transcode?

jellyfin-force-transcode es un proxy reverse-proxy minimalista que fuerza transcodificación de audio y/o video en Jellyfin para clientes seleccionados, incluso cuando estos no tienen configuraciones nativas disponibles. Utiliza mitmproxy con una extensión Python para interceptar la solicitud POST /Items/{id}/PlaybackInfo, reemplazando el perfil del dispositivo antes de que Jellyfin decida transcodificar o direct-play.

Para quién es

• Administradores de servidores Jellyfin con clientes sin opciones nativas de transcodificación
• Usuarios con dispositivos que reportan soporte multicanal pero no lo reproducen correctamente
• Situaciones donde se requiere forzar codecs específicos o limitar bitrate/resolución por dispositivo

Casos de uso principales

• Audío estéreo obligatorio: Forzar downmix a 2 canales cuando un dispositivo muestra multicanal pero no lo reproduce (ej. tablets Android con ExoPlayer)
• Límite de bitrate: Reducir bitrate máximo para evitar saturación en enlaces lentos o remotos
• Resolución limitada: Forzar 720p/1080p en pantallas pequeñas sin reencodificar archivos existentes
• Codecs específicos: Forzar transcodificación de HEVC 10-bit a 8-bit para dispositivos incompatibles
• Dispositivos problemáticos: Fire TV que estremea en HEVC, clientes sin configuración nativa de canales/bitrate/resolución

Arquitectura

Stack: único contenedor Docker ejecutando mitmproxy con extensión Python. Arquitectura neutral y fail-safe: sin reglas el proxy no cambia nada; en error, reenvía sin modificaciones. Nunca detiene reproducción.

flowchart LR
C["Jellyfin client"] -->|request| P["jellyfin-force-transcode :8097"]
P -->|"POST /PlaybackInfo: device profile rewritten
everything else: forwarded unchanged"| J["Jellyfin :8096"]
J -->|"transcoded audio/video"| P --> C

Prerrequisitos

• Docker (requerido)
• Jellyfin 12.1.0 o posterior (probado), compatible con 10.x+
• Acceso al puerto 8097 del proxy y 8096 de Jellyfin
• Volúmenes para rules.json
• FFmpeg en el servidor Jellyfin (para transcodificación)

Instalación/Despliegue

Docker Run

docker run -d --name jellyfin-force-transcode \
  -p 8097:8080 \
  -e JELLYFIN_URL=http://192.168.1.50:8096 \
  -v "$(pwd)/rules.json:/addon/rules.json:ro" \
  --restart unless-stopped \
  ghcr.io/forward-tonight7079/jellyfin-force-transcode:latest

Docker Compose

services:
  jellyfin-force-transcode:
    image: ghcr.io/forward-tonight7079/jellyfin-force-transcode:latest
    environment:
      JELLYFIN_URL: "http://192.168.1.50:8096" # tu dirección Jellyfin
    ports:
      - "8097:8080"
    volumes:
      - ./rules.json:/addon/rules.json:ro
    restart: unless-stopped

Configuración del cliente

En el cliente, establecer la dirección del servidor como http://<docker-host-ip>:8097.

Persistencia

El único volumen persistente es rules.json, montado en /addon/rules.json:ro. No hay estado guardado dentro del contenedor.

Red/Puertos

• 8097: Puerto del proxy (expuesto al cliente)
• 8096: Puerto de Jellyfin (interno, configurable vía JELLYFIN_URL)
• Todos los demás tráfico (video segments, WebSocket, imágenes) pasa sin cambios

Seguridad

• MIT License - código abierto y auditable
• No almacena credenciales ni datos sensibles
• Reglas en rules.json (JSON plano, no exponer públicamente)
• Proxy neutral: sin reglas = sin cambios

Actualización/Backup

Actualizar imagen Docker a la última versión. Backup de rules.json antes de cualquier cambio. El proxy es inmutable: si Jellyfin cambia su protocolo/API, podría requerir ajustes.

Ventajas

• No requiere instalación ni configuración adicional en Jellyfin
• Permite forzar transcodificación sin afectar archivos existentes
• Soporta múltiples perfiles por dispositivo/usuario mediante reglas JSON
• Compatible con clientes que no muestran opciones de transcodificación nativas
• El proxy nunca detiene el flujo de reproducción ni genera errores visibles

Limitaciones

• Funciona únicamente para la negociación del perfil de dispositivo (PlaybackInfo); no puede forzar transcodificación en otros contextos
• No permite forzar transcodificación simultánea de audio y video en un solo dispositivo sin reglas separadas
• El proxy es inmutable: si Jellyfin cambia su protocolo o API, el plugin podría dejar de funcionar
• No ofrece control granular sobre codecs específicos por canal de audio
• La configuración requiere acceso al servidor y conocimiento del formato de Authorization header

Alternativas reales

• Jellyfin 10.9.11+: Configuración nativa "Maximum Allowed Audio Channels" para direct play (corrige limitaciones anteriores)
• Límite de bitrate por usuario: Configuración nativa en Jellyfin para limitar streaming global
• Plugins oficiales: No existen plugins que hagan esto; jellyfin-force-transcode es la solución externa recomendada

FAQ sustentada

¿Necesito este proxy?

No siempre. Primero examina las opciones nativas: si tu cliente muestra "Maximum allowed audio channels" y corrige el audio, úsalo. Jellyfin 10.9.11+ aplica esta configuración a direct play. Usa el proxy cuando esas opciones no estén disponibles o sean insuficientes.

¿Funciona con todos los clientes?

Sí, incluye players que dan ninguna configuración para canales, bitrate o resolución (ej. Android app con ExoPlayer).

¿Puedo forzar transcodificación de video y audio simultáneamente?

No en una sola regla. Audio y video son independientes; requieren reglas separadas.

¿Cómo verifico que funciona?

Reproduce un título en el cliente configurado. Abre Jellyfin Dashboard → Playback (active streams) o lee el log del servidor. Debes ver transcode con las limitaciones establecidas (ej. -ac 2 para estéreo, scale / -maxrate para video).

¿Es un plugin de Jellyfin?

No. No es plugin, no modifica Jellyfin ni sus archivos de medios.