YouTubeAutoList

Sistema automatizado para gestionar listas de reproducción de YouTube basado en criterios configurables.

Requisitos Previos

1. Python 3.11 o superior
2. Docker (opcional)
3. Credenciales de YouTube API
4. Cuenta de Google y proyecto en Google Cloud Platform

Configuración de Google Cloud Platform

1. Crear un nuevo proyecto en Google Cloud Console

2. Habilitar YouTube Data API v3:

   • Ir a "APIs & Services" > "Library"
   • Buscar "YouTube Data API v3"
   • Clic en "Enable"

3. Configurar credenciales OAuth:

   • Ir a "APIs & Services" > "Credentials"
   • Clic en "Create Credentials" > "OAuth client ID"
   • Seleccionar "Desktop Application"
   • Configurar pantalla de consentimiento:
     • Tipo de usuario: Externo
     • Información de la aplicación
     • Permisos: .../auth/youtube.force-ssl
   • Descargar el archivo JSON de credenciales y renombrarlo a YouTubeAutoListClientSecret.json

Configuración de Autenticación

1. Revocar accesos previos (importante para obtener refresh_token):

   • Ir a https://myaccount.google.com/permissions
   • Buscar "YouTubeAutoList"
   • Revocar acceso existente

2. Generar nuevo token:

python auth_setup.py

3. Verificar el token generado:

ls -l YouTubeAutoListToken.json
cat YouTubeAutoListToken.json | grep refresh_token

Características Principales

• Sistema híbrido RSS/API para máxima eficiencia (95% reducción de cuota)
• Sistema de monitoreo y estadísticas detallado
• Autenticación OAuth 2.0 con YouTube API (3+ meses)
• Sistema de base de datos SQLite para persistencia y seguimiento
• Sistema de caché avanzado multinivel (RSS y API)
• Sistema inteligente de gestión de cuota de YouTube API
• Sistema de notificaciones detallado (Telegram/Email)
• Filtrado avanzado de videos por duración y patrones
• Detección y exclusión automática de Shorts
• Limpieza automática de videos antiguos
• Sistema de respaldo automático de datos y configuraciones
• Soporte para múltiples canales y listas de reproducción
• Contenedorización con Docker y persistencia de datos
• Sistema de logging detallado y colorizado

Estructura

YouTubeAutoList/
├── YouTubeAutoList.py       # Script principal
├── auth_setup.py           # Script de autenticación inicial
├── database_manager.py     # Gestor de base de datos SQLite
├── rss_manager.py         # Gestor de feeds RSS
├── entrypoint.sh          # Punto de entrada para Docker
├── Dockerfile             # Configuración de Docker
├── requirements.txt       # Dependencias Python
├── db_schema.sql         # Esquema de la base de datos
├── YouTubeAutoListConfig.json    # Configuración de canales
├── YouTubeAutoListToken.json     # Token de autenticación
├── YouTubeAutoListNotification_config.json # Notificaciones
├── YouTubeAutoListClientSecret.json  # Credenciales de Google Cloud
└── persistent_data/      # Datos persistentes
    ├── db/              # Base de datos SQLite
    └── logs/            # Logs del sistema

Diagrama de Flujo

graph TD
    A[main] --> B[YouTubeManager.__init__]
    B --> C[check_internet_connection]
    C --> D[authenticate]
    D --> E[load_config]
    E --> F[manage_playlist]

    %% Sistema Híbrido RSS/API
    subgraph "Sistema RSS"
        RSS[RSSManager]
        RC[RSS Cache]
        RF[RSS Feed]
        RSS --> RC
        RSS --> RF
        F --> RSS
        RSS --> RV[get_recent_videos]
        RV --> FT[Filtro por Título]
        RV --> FD[Filtro por Fecha]
    end

    %% Sistema API
    subgraph "Sistema API"
        F --> G[get_channel_videos<br/>quota: ~102/canal]
        G --> H[_video_matches_criteria<br/>quota: ~3/video]
        H --> I[_parse_duration]
        F --> J[_get_playlist_items<br/>quota: ~1/50 items]
        F --> K[_video_in_playlist]
        F --> L[_add_to_playlist<br/>quota: 50/video]
    end

    %% Sistema de Limpieza
    A --> M[cleanup_playlists]
    M --> N[_get_playlist_items<br/>quota: ~1/50 items]
    
    %% Manejo de Errores y Cuota
    subgraph "Control de Errores"
        QE[_check_quota_error]
        TE[_check_token_error]
        G --> QE & TE
        J --> QE & TE
        L --> QE & TE
        QE --> X[QuotaExceededException]
        TE --> Y[TokenExpiredException]
        X & Y --> Z[Notificación<br/>Telegram/Email]
        Z --> W[sys.exit]
    end

    %% Sistema de Caché Multinivel
    subgraph "Caché Multinivel"
        DB[(SQLite DB)]
        MC[Memoria Cache]
        RSS --> MC
        G --> MC
        MC --> DB
        DB --> MC
    end

    subgraph "Autenticación Extendida"
        D --> U[Verificar token existente]
        U --> V[Cargar credenciales<br/>duración: 3+ meses]
        V --> R[Refrescar token<br/>automático]
    end

    subgraph "Sistema de Notificaciones"
        NA[NotificationManager]
        NB[send_notification]
        NC[_send_email]
        NA --> NB
        NB --> NC
    end

Loading

Optimización y Gestión de Recursos

El sistema implementa una estrategia multinivel para maximizar la eficiencia:

1. Sistema RSS Primario:

   • Detección inicial sin consumo de cuota
   • Filtrado temprano por títulos y fecha
   • Caché de feeds RSS (60 minutos)
   • Procesamiento en paralelo de feeds
   • Validación de metadatos básicos

2. Sistema de Caché Multinivel:

   • Nivel 1 (Memoria):

     • Caché volátil de alta velocidad
     • Resultados frecuentes y recientes
     • Invalidación automática temporal

   • Nivel 2 (SQLite):

     • Almacenamiento persistente
     • Historial completo de videos
     • Métricas y estadísticas
     • Recuperación ante fallos

   • Nivel 3 (RSS):

     • Metadatos básicos de videos
     • Actualización periódica
     • Sin límites de cuota

3. Optimización de API: Solo se usa la API para:

   • Verificación final: 1-2 unidades/video
   • Operaciones de playlist: 1 unidad/50 videos
   • Modificaciones: 50 unidades/operación

   Estrategias de Optimización:

   • Procesamiento en lotes (hasta 50 videos)
   • Validación previa vía RSS
   • Caché de resultados frecuentes
   • Reintento inteligente
   • Control de concurrencia

4. Optimización de Llamadas:

   • Procesamiento en lotes de videos (hasta 50 por llamada)
   • Verificación previa en caché antes de consultas
   • Reutilización de datos entre sesiones

5. Gestión de Cuota:

   • Monitoreo continuo del consumo de cuota
   • Notificaciones automáticas al alcanzar límites
   • Parada segura ante exceso de cuota
   • Estadísticas detalladas de uso

Métricas de Rendimiento

El sistema logra una optimización significativa:

1. Reducción de Cuota (95%+):

   • Búsquedas RSS: 0 unidades (vs. 100/búsqueda API)
   • Detalles: 1-2 unidades/video (vs. 50/video API)
   • Verificaciones: 0.02 unidades/video (lotes de 50)

2. Mejoras de Rendimiento:

   • Tiempo de respuesta: <500ms para RSS
   • Latencia API: Reducida en 90%
   • Tasa de aciertos caché: >85%
   • Procesamiento paralelo: 2-3x más rápido

3. Confiabilidad:

   • Disponibilidad: 99.9%
   • Recuperación automática
   • Redundancia de datos
   • Consistencia garantizada

4. Monitoreo en Tiempo Real:

   • Dashboard de cuota
   • Métricas de rendimiento
   • Alertas predictivas
   • Análisis de tendencias

Nota: La cuota diaria gratuita de YouTube API v3 es de 10,000 unidades.

Configuración

Archivo YouTubeAutoListConfig.json

{
    "channels": [
        {
            "channel_id": "ID_CANAL",
            "channel_name": "Nombre Canal",
            "playlist_id": "ID_PLAYLIST",
            "playlist_name": "Nombre Playlist",
            "title_pattern": "regex_pattern",
            "min_duration": 120,
            "max_duration": 900,
            "hours_limit": 8
        }
    ]
}

Archivo YouTubeAutoListNotification_config.json

{
    "telegram_token": "YOUR_BOT_TOKEN",
    "telegram_chat_id": "YOUR_CHAT_ID",
    "email": {
        "smtp_server": "smtp.gmail.com",
        "username": "[email protected]",
        "password": "your-app-password",
        "from": "[email protected]",
        "to": "[email protected]"
    }
}

Expresiones Regulares en Configuración

Los patrones de búsqueda soportan:

1. Palabras exactas:

"title_pattern": "(?i)(\\b(IA|AI|cars)\\b)"

2. Palabras con sufijos:

"title_pattern": "\\b(bike|gravel|mtb)\\w*"

3. Patrones específicos por canal:

{
    "channel_name": "Bike Sport",
    "title_pattern": "(?i)((Latest news bulletin.*Evening)|\\b(Gravel|MTB)\\b)"
}

4. Formatos de fecha/hora:

{
    "channel_name": "TOUR FRANCE",
    "title_pattern": "(?i)(Noticias del \\d{4}/\\d{2}/\\d{2} 20h00)"
}

Variables de Entorno Docker

environment:
  - TZ=Europe/Madrid
  - CONFIG_DIR=/app/config
  - LOG_DIR=/app/logs
  - DATA_DIR=/app/data

Uso

Local

1. Instalar dependencias:

pip install -r requirements.txt

2. Inicializar base de datos:

sqlite3 YouTubeAutoList.db < db_schema.sql

3. Ejecutar:

python YouTubeAutoList.py

Docker

El sistema incluye un script de despliegue automatizado que maneja:

• Respaldo de datos existentes
• Verificación de integridad de la base de datos
• Actualización de esquemas
• Gestión de permisos
• Persistencia de datos

1. Ejecutar script de despliegue:

./deply_youtubeautolist.sh

El script solicitará la versión de la imagen y se encargará de:

• Crear estructura de directorios persistentes
• Respaldar datos del contenedor existente
• Construir nueva imagen
• Actualizar contenedor
• Restaurar datos persistentes
• Verificar permisos

Logging y Monitoreo

El sistema incluye un sistema de logging detallado y colorizado para facilitar el seguimiento y diagnóstico.

Ubicación de Logs

• logs/YouTubeAutoList.log: Logs detallados de la aplicación
• logs/cron.log: Logs de las ejecuciones programadas
• docker_logs/: Historial de construcción de imágenes

Estructura de Logs

1. Operaciones RSS (Verde/Cyan):

   === Iniciando obtención RSS para canal [nombre_canal] ===
   Obteniendo feed RSS para [nombre_canal]...
   Límite de tiempo: 8 horas (2025-08-27 10:00:00)
   Video encontrado en RSS:
     - Título: [título_video]
     - ID: [video_id]
     - Fecha: [fecha_publicación]
   Video aceptado/excluido - [razón]
   === RSS: Encontrados X videos válidos para [nombre_canal] ===
   

2. Sistema de Caché (Verde):

   Usando caché RSS para canal [nombre_canal] (válido por 60 minutos)
   Actualizando caché RSS para [nombre_canal]
   Cache hit/miss para video [video_id]
   

3. Operaciones API y Cuota (Cyan/Amarillo):

   === Estadísticas de Cuota ===
   Cuota ahorrada vía RSS: [X] unidades
   Operaciones evitadas: [número]
   Cuota restante: [Y] unidades
   
   === Detalles de Operación ===
   Verificando video [video_id]
   Consumo: [unidades] unidades ([operación])
   

4. Estadísticas de Ejecución (Blanco):

   === Resumen de Ejecución ===
   Videos procesados: [total]
   - Vía RSS: [número] ([porcentaje]%)
   - Vía API: [número] ([porcentaje]%)
   Cuota ahorrada: [unidades] ([porcentaje]%)
   Tiempo total: [segundos]s
   

5. Errores y Advertencias (Rojo/Amarillo):

   [ERROR] Error en feed RSS: [detalle]
   [WARNING] Límite de cuota cercano ([porcentaje]%)
   [INFO] Fallback a caché local
   

Monitoreo de Rendimiento

El sistema registra y muestra:

• Consumo de cuota en tiempo real
• Eficiencia del sistema RSS vs API
• Tiempos de respuesta y latencia
• Tasas de acierto de caché
• Estadísticas de operaciones fallidas
• Métricas de ahorro de recursos

Commits Convencionales

Este proyecto sigue la especificación de Commits Convencionales.

Estructura del Commit

Tipos de Commits

• feat: Nueva característica
• fix: Corrección de errores
• docs: Cambios en documentación
• style: Cambios de formato (espacios, punto y coma, etc)
• refactor: Refactorización de código
• perf: Mejoras de rendimiento
• test: Añadir o modificar tests
• build: Cambios en el sistema de build
• ci: Cambios en integración continua
• chore: Tareas de mantenimiento

Ejemplos

feat(auth): implementar autenticación OAuth
fix(cache): corregir error en expiración de caché
docs(readme): actualizar diagrama de flujo
refactor(api): optimizar llamadas a YouTube API