A clearer way to download, organize, and process media on Windows.
Native Fluent Design ยท YouTube and X ยท Powered by yt-dlp and FFmpeg
๐ ็ฎไฝไธญๆ ยท โจ Features ยท ๐ฆ Installation ยท ๐งโ๐ป Development ยท ๐๏ธ Architecture V2 (Chinese)
FluentYTDL turns yt-dlp and FFmpeg into a guided desktop workflow. Parse a link, choose exactly what you need, follow every task from one queue, and let the application coordinate downloads, recovery, and post-processing without manually assembling command-line options.
Note
FluentYTDL is developed for 64-bit Windows 10 and Windows 11. YouTube has the broadest feature coverage. X support currently targets individual post URLs; profile and timeline downloads are outside the supported scope.
FluentYTDL makes advanced yt-dlp and FFmpeg workflows accessible to Windows users who prefer a guided desktop experience. Official release assets have surpassed 20,000 downloads, while active, issue-driven releases continue to adapt the application to upstream platform and tool changes.
| Parse | Format selection | Task queue |
|---|---|---|
 |
 |
 |
| ๐๏ธ Precise format control Choose resolution, container, codec, audio language, or a simple quality preset. |
๐ Batch workflows Parse YouTube playlists and channels, load metadata on demand, and queue selected entries. |
| ๐ง Resilient tasks Persist task state, isolate temporary files, configure concurrency, and recover after a restart. |
๐ก๏ธ Quality guard Detect format downgrades and optionally verify downloaded media with FFprobe. |
| ๐ฌ Subtitles and covers Download them independently, merge bilingual subtitles, and embed supported artwork. |
โ๏ธ Video clipping Select a time range from an ordinary YouTube video with fast or precise cut modes. |
| ๐๏ธ Media processing Mux and convert with FFmpeg, process SponsorBlock segments, and optionally transform VR projection. |
๐ Authenticated sessions Manage local cookies and use an isolated WebView2 login flow when a site requires a session. |
| ๐งฐ Managed components Update the application and external media tools with checksum verification. |
๐ช Native desktop experience Use a focused Fluent interface instead of manually coordinating multiple command-line tools. |
| Area | Current support |
|---|---|
| ๐ช Operating system | Windows 10/11, 64-bit |
| ๐ Application languages | Simplified Chinese and English; changes apply after restart. Audio/subtitle languages are independent. See localization and log policy. |
| Videos, Shorts, live/video URLs, playlists, channels, subtitles, covers, and VR workflows | |
| ๐ X (Twitter) | Individual post URLs with downloadable media |
| ๐ Other yt-dlp sites | Not part of the supported product scope |
| ๐ Source runtime | Python 3.12 or newer |
Important
FluentYTDL depends on upstream services and tools. Site changes, expired media URLs, account or region restrictions, and yt-dlp regressions can temporarily affect extraction or downloads.
Download the latest installer or portable archive from GitHub Releases.
| Package | Best for |
|---|---|
*-setup.exe |
A standard Windows installation |
*-full.7z |
A portable copy with the complete runtime bundle |
*-app-core.7z |
Updating only the application core |
Tip
Release assets include SHA256SUMS.txt. Verify checksums when redistributing or archiving a package. Official binaries are published only through this repository.
git clone https://github.com/SakuraForgot/FluentYTDL.git
cd FluentYTDL
# Recommended: uv
uv sync --locked --extra dev --extra build
uv run python main.pyAlternatively, use a Python virtual environment and install the project with pip install -e ".[dev]", then run python main.py.
Note
Python dependencies do not include external components. Open Settings โ Components to install or update yt-dlp, FFmpeg, Deno, POT and AtomicParsley directly from their upstream releases. POT uses the built-in Deno to prepare its dependencies; its separate window shows runtime status and retry. See development setup for command-line installation and verification.
| Layer | Implementation |
|---|---|
| ๐ผ๏ธ Desktop UI | PySide6 and PySide6-Fluent-Widgets |
| ๐ Application core | Python 3.12.15 with a src/ package layout |
| โฌ๏ธ Download engine | yt-dlp behind a CLI subprocess boundary |
| ๐๏ธ Media pipeline | FFmpeg and companion media tools |
| ๐งฑ Service boundaries | Authentication, download, processing, storage, and YouTube services |
uv sync --locked --extra dev --extra build
uv run ruff check src tests
$env:QT_QPA_PLATFORM = "offscreen"
uv run pytest tests -q
uv run python scripts/version_manager.py check| Read | When you need it |
|---|---|
| Contributing guide | Setup, workflow, tests, and pull request expectations |
| Architecture V2 (Chinese) | Current source, runtime mechanisms, rationale and verification limits |
| Development rules | Repository-specific engineering constraints |
| yt-dlp integration notes | Subprocess protocol and downloader behavior |
| Security policy | Supported versions and private vulnerability reporting |
Caution
Cookies, logs, downloaded media, and local configuration can contain sensitive information. Never post unredacted credentials, cookies, tokens, or private URLs in an issue. Report vulnerabilities through the private process in SECURITY.md.
Important
Use FluentYTDL only for content you are authorized to access and download. Users are responsible for following applicable law, copyright rules, and platform terms. The project does not grant access to private or restricted content.
Bug reports, focused pull requests, documentation improvements, and reproducible platform feedback are welcome.
| Project document | |
|---|---|
| ๐ ๏ธ | Contributing guide |
| ๐ซถ | Code of Conduct |
| ๐งโ๐ | Maintainers |
| ๐ก๏ธ | Security policy |
Note
Source code is licensed under GPL-3.0. The trademark policy protects project identity without reducing GPL rights, while the academic integrity notice explains attribution expectations without adding license restrictions.
FluentYTDL stands on the shoulders of an outstanding open-source ecosystem. Special thanks to the projects and people who make its core experience possible:
| Project | What it brings to FluentYTDL | |
|---|---|---|
| ๐ฌ | yt-dlp | Media extraction, format discovery, and download orchestration. |
| ๐๏ธ | FFmpeg | Stream merging, conversion, metadata processing, and VR projection support. |
| ๐ฅ๏ธ | PySide6 and PySide6-Fluent-Widgets | The Qt desktop foundation and Fluent-style interface. |
| ๐ | rookiepy and pywebview | Browser-session integration and the isolated WebView2 login experience. |
| ๐งฉ | bgutil-ytdlp-pot-provider and Deno | YouTube player compatibility and JavaScript challenge support. |
| โจ | SponsorBlock and AtomicParsley | Sponsor-segment processing and media metadata enrichment. |
Thank you to every upstream maintainer, code contributor, issue reporter, documentation contributor, and tester. Every reproducible report and thoughtful improvement helps FluentYTDL become more dependable and accessible.
๐ License texts and third-party notices are collected in licenses/. If this project helps you, consider supporting the upstream projects that make it possible.