$ show SakuraForgot/FluentYTDL
FluentYTDL is a Windows desktop application built with PySide6 and qfluentwidgets that provides a modern Fluent Design GUI for downloading videos and audio from YouTube and X (Twitter). It wraps yt-dlp as the core download engine and adds a rich layer of task management, error diagnostics, cookie-based authentication, subtitle handling, metadata embedding, and VR/360 video support. The application features a persistent SQLite task database, structured observability with JSONL event tracing, rule-based error classification, and a self-update mechanism with component version management. It is heavily internationalized (English and Simplified Chinese) and includes a comprehensive test suite covering UI, download pipeline, diagnostics, and observability contracts. Architecturally, the codebase is organized into distinct modules: core (config, dependency, update), auth (cookie sentinel, WebView2 provider), download (executor, workers, staging, quality guard), processing (metadata, subtitles, sponsorblock), diagnostics (rule engine, line collector), observability (events, traces, artifacts), and UI (pages, dialogs, delegates, components). The download pipeline is transactional with staging areas and manifests, ensuring atomicity and recovery. The observability layer is best-effort and never blocks business logic, emitting structured events for debugging and bug bundle export. The code demonstrates strong engineering practices: immutable dataclasses for plans, singleton managers with explicit initialization guards, strategy patterns for subtitle selection, and extensive use of signals for async UI updates. Key reusable components include the container compatibility resolver (deterministic output container decision), BCP-47 language matching with tiered resolution, the quality guard pattern for pre/post-download verification, the transactional staging pattern for file management, and the cookie runfile isolation pattern to prevent yt-dlp from corrupting truth-source cookies. The diagnostics rule engine and observability event system are also well-isolated and could be extracted for other yt-dlp wrapper projects.
The LLM identified 6 files worth highlighting for reuse:
Provides a single authority for deciding the output container (MKV/MP4/WebM) based on subtitle count, audio multistreams, codec constraints, and user overrides. The ContainerResolution dataclass and resolve_output_container function are pure, stateless, and proven equivalent to legacy logic via 240 test cases. Easily reusable in any yt-dlp wrapper or media processing pipeline.
Implements tiered BCP-47 language matching (exact, prefix, alias, macro) with an alias table for simplified/traditional Chinese. Used by subtitle selection, audio scoring, and UI sorting. The functions match_tier, canonicalize, resolve_requested, and to_sub_langs_pattern are pure and well-tested, making them reusable for any application needing language preference resolution.
Implements a transactional staging pattern with StagingArea (payload/.work/.internal partitions) and Manifest (kept/drop/promote/mark_degraded/embed_evidence). Physical deletion only happens at rmtree; flag missing means keep. This pattern ensures atomic file operations and clean artifact lifecycle, reusable in any download or file-processing pipeline.
Provides a context manager that copies truth-source cookie files to disposable byte copies before passing to yt-dlp, preventing yt-dlp's jar write-back from corrupting the original. This isolation pattern is critical for any application that delegates credential handling to an external tool with write access.
Implements a QualityGuard pattern with QualityIntent, preflight quality check, post-download verification, and event emission. It detects resolution/format deviations and can trigger downgrade or warning. The pattern is self-contained and could be extracted for any download pipeline needing quality assurance.
Provides DiagnosticLineCollector that processes yt-dlp output lines, deduplicates, and produces structured diagnostic lines with codes, categories, severity, and retry policies. It uses a rule engine with regex/substr matching and supports demotion to warnings. Reusable for any tool that needs to classify stderr output into actionable diagnostics.