$ show EgalitarianMonkey/hometube
HomeTube is a Streamlit-based web application for downloading and managing media from YouTube and 1800+ other platforms via yt-dlp. It provides a rich UI for URL analysis, quality profile selection (AV1/VP9/H.264), subtitle embedding, video cutting (keyframe/precise), SponsorBlock ad removal, and playlist synchronization with full diff-based state management. The architecture is a monolithic Streamlit app with heavy subprocess orchestration of yt-dlp and ffmpeg, backed by a typed configuration system, JSON-based workspace state files, and a comprehensive test suite with mocked Streamlit dependencies. Designed for homelab deployment, it includes Docker multi-arch builds, Nginx reverse proxy config, and daily automated rebuilds to stay current with yt-dlp updates. Core data flows: URLs are analyzed via yt-dlp (with client fallback chain default → ios → web), metadata is cached in url_info.json, download strategies are computed using format profile matching (codec priorities, audio language detection), and final files are moved to a configurable destination with optional hardlinking. Playlists are handled via a dedicated sync module that computes rename/archive/delete plans and applies them with dry-run support. The system emphasizes resilience through generic file naming, temporary workspace preservation, and intelligent caching that refuses to overwrite premium AV1/VP9 metadata with lower-quality data. The application is not a data research project; it is a production-ready media downloader and manager with no ML or analytical components. Its complexity lies in data integrity patterns (metadata caching, state machines, filesystem mutations) rather than data science.
The LLM identified 6 files worth highlighting for reuse:
Provides run_subprocess_safe and run_subprocess_with_progress helper functions that wrap subprocess.Popen with configurable timeouts, standardized error context logging, and retry-ready return values (CompletedProcess even on failure). This is a standalone utility that can be extracted into any Python project needing robust subprocess execution without dependency on the rest of HomeTube.
Encapsulates file operations including ensure_dir, move_final_to_destination (with cross-device fallback via shutil.copy2), sanitize_filename, and JSON file interaction helpers. The cross-device move pattern is especially valuable for Docker deployments on CIFS/SMB volumes. The module is self-contained (only uses os, shutil, pathlib) and readily reusable.
Implements a typed Settings dataclass loaded from environment variables with validation, alias handling, and lru_cache singleton pattern. Includes ensure_folders_exist for directory creation. This is a clean, testable configuration pattern that can be extracted for any application requiring environment-driven settings with minimal dependencies.
Provides a centralized logging system with safe_push_log that handles fallback to console, message classification (info/warning/error), session-aware log suppression, and error hint generation. The i18n integration via translation keys makes it adaptable to multilingual applications. The module is loosely coupled and can be reused with its own translation pattern.
Contains PlaylistSyncPlan and SyncAction dataclasses that model pending filesystem mutations (rename, relocate, archive, delete, download) for playlist synchronization. The dry-run capable plan/apply split is a clean pattern for any state reconciliation task beyond media management. The module is largely self-contained (imports only standard library and internal utility modules) and the dataclass-based approach is portable.
Implements subtitle embedding with an optimized MP4 path (using mov_text codec) and generic MKV/WebM support. Includes language code normalization (2/3-letter codes), SRT/VTT format validation, and handling of auto-generated vs manual subtitles. The ffmpeg command construction and validation logic is a reusable pattern for any media processing pipeline needing subtitle management.