ChannelTube

ChannelTube is a lightweight, self‑hosted service that automates the synchronization of YouTube channel content using yt-dlp. From a developer’s standpoint, it acts as a scheduled downloader that can be embedded into larger media‑management pipelines. The application exposes a minimal REST endpoint (default port 5000) and relies on environment variables for configuration, making it trivial to integrate with container orchestrators or CI/CD workflows. The core logic revolves around invoking yt-dlp with user‑defined format IDs, codec fallbacks, and subtitle handling options—all of which are exposed as environment variables for maximum flexibility.

• Runtime: Python 3 (the base image is python:slim), leveraging the official yt-dlp library as a dependency.
• Framework: A small Flask‑like microservice (or similar lightweight web server) that exposes a single HTTP endpoint for triggering syncs and reporting status.
• Data Layer: None beyond the filesystem; media files are written directly to mounted volumes (/channeltube/downloads for video, /channeltube/audio_downloads for audio). Metadata is optional and can be stored in a simple JSON file if needed.
• Scheduling: Cron‑style scheduling is implemented via an in‑process scheduler that reads a comma‑separated list of hours from the SYNC_HOURS environment variable. The scheduler is tolerant to drift, allowing a 10‑minute deadband around the target hour.
• Media Server Hooks: Optional callbacks to Plex or Jellyfin are performed by issuing HTTP POST requests to the respective /library/sections/{id}/refresh endpoints, using bearer tokens supplied via environment variables.

• Download Control: Specify video/audio format IDs (video_format_id, audio_format_id) and fallback codecs (fallback_vcodec, fallback_acodec).
• Subtitle Management: Choose between none, embed, or external subtitles; specify languages (subtitle_languages).
• Naming Conventions: Toggle inclusion of the YouTube video ID in filenames (include_id_in_filename).
• Threading: Configure concurrency with thread_limit.
• Logging: Verbose mode (verbose_logs) toggles detailed logs to stdout, which can be captured by Docker logging drivers or systemd journal.
• Webhook‑style API: The /sync endpoint accepts a JSON payload containing channel identifiers, triggering an immediate download outside the scheduled window.

• Containerization: A ready‑to‑use Docker image (thewicklowwolf/channeltube) is published to Docker Hub, with a docker‑compose snippet in the README for quick spin‑up.
• Volume Management: Separate volumes for video and audio downloads allow fine‑grained storage policies.
• User Permissions: PUID and PGID environment variables let the container run as a non‑root user, essential for host file system security.
• Scalability: While the application is single‑process, horizontal scaling can be achieved by running multiple instances behind a load balancer, each with isolated volume mounts. The thread_limit parameter ensures that each instance respects host CPU limits.

• Plugin Hooks: The design is intentionally minimal, but developers can fork the repository and add custom post‑processing steps (e.g., transcoding with FFmpeg or uploading to cloud storage).
• Webhooks: By exposing the /sync endpoint, external services (GitHub Actions, Jenkins) can trigger downloads on demand.
• Extensible Config: All runtime options are environment variables; adding new flags is straightforward and automatically picked up by the scheduler.
• Community Contributions: The project’s open‑source nature invites pull requests for additional media server integrations or advanced subtitle handling.

• Documentation: The README provides concise, actionable instructions for Docker deployment and environment variable usage.
• Community Support: The GitHub repository has active issue tracking and CI status badges, indicating ongoing maintenance.
• Error Handling: yt-dlp errors are captured and returned in the HTTP response, enabling automated retry logic.
• Testing: While not included, the codebase is amenable to unit tests around the scheduling and download logic due to its modular structure.

1. Personal Media Libraries – A hobbyist can keep a Plex or Jellyfin library up to date with their favorite channels without manual downloads.
2. Educational Institutions – Schools can automatically ingest lecture videos from institutional YouTube channels, ensuring consistent naming and subtitle availability.
3. Corporate Training – Companies can sync internal training channels to a private media server, with custom codecs and security tokens.
4. DevOps Pipelines – CI/CD workflows can trigger ChannelTube via its API to fetch build‑related video artifacts or tutorials for internal documentation.

• Zero‑Configuration Runtime – No database or external services required; all state lives on the filesystem.
• Fine‑Grained Control – Direct exposure of yt-dlp’s rich option set gives developers deep control over download quality and codec selection.
• Open Licensing – The project is released under a permissive license, allowing integration into proprietary systems without licensing headaches.
• Performance