🎬 YouTube Downloader – GitHub Actions Workflow

This workflow downloads YouTube videos (or audio) with:

• Codec selection
• Auto‑generated subtitles
• Thumbnail & chapter embedding
• SponsorBlock
• Splitting large files into 7‑zip volumes

راهنمای فارسی

🎬 دانلودر ویدیوی یوتیوب

📦 پیش‌نیازها

قبل از استفاده، نیاز دارید:

1. یک مخزن گیت‌هاب (عمومی یا خصوصی) با اکشن فعال.
2. فایل معتبر cookies.txt که از نشست واردشده به یوتیوب دریافت شده باشد.
   • از افزونه مرورگر مانند “Get cookies.txt LOCALLY” استفاده کنید. پس از ورود به یوتیوب، کوکی‌ها را خروجی گرفته و فایل را به cookies.txt تغییر نام دهید.
3. فایل cookies.txt را در روت مخزن قرار دهید.

⚠️ هرگز cookies.txt واقعی خود را در مخزن عمومی قرار ندهید.

---

🚀 راه‌اندازی Workflow

1. پوشه .github/workflows/ را در مخزن خود ایجاد کنید.
2. فایل download.yml (موجود در همین مخزن) را در آن پوشه قرار دهید.
3. تغییرات را commit کنید.

---

▶️ اجرای دانلودر

1. به مخزن خود در گیت‌هاب بروید.
2. روی برگه Actions کلیک کنید.
3. در نوار کناری سمت چپ، 🎬 YouTube Downloader را انتخاب کنید.
4. دکمه Run workflow (آبی) را بزنید.
5. فرم را پر کنید. *اگر دستگاه شما جدید است از Codec های av 1 برای ویدئو و opus برای صدا استفاده کنید تا فایل با حجم کم و کیفیت بالا به شما خروجی دهد *اگر دستگاه شما قدیمی است از h 264 برای ویدئو و aac, mp 3 برای صدا استفاده کنید *برای استفاده از ویژگی هایی مثل sponsorblock, chapters, thumbnails بهتر است از فرمت mkv استفاده کنید
6. دکمه سبز رنگ Run workflow را بزنید.
7. بعد از مدتی فایل شما در پوشه downloads در روت مخزن شما دانلود می شود

---

📦 Prerequisites

Before using this workflow, you need:

1. A GitHub repository (private) with Actions enabled.
2. A valid cookies.txt exported from your logged‑in YouTube session.
   How to get it? – Use a browser extension like “Get cookies.txt LOCALLY” (Chrome/Firefox). After logging into YouTube, export the cookies and rename the file to cookies.txt.
3. Place cookies.txt in the root of your repository.

⚠️ Never commit your real cookies.txt to a public repository – it grants access to your YouTube account.

---

🚀 How to set up the workflow

1. Create the folder .github/workflows/ in your repository.
2. Place the download.yml file (provided in this repository) inside that folder.
3. Commit the file.

---

▶️ How to run the downloader

1. Go to your repository on GitHub.
2. Click the Actions tab.
3. On the left sidebar, select 🎬 YouTube Downloader.
4. Click the Run workflow button (blue).
5. Fill in the form:
   • YouTube URL – the video link.
   • Video resolution – best / 1080p / 720p / 480p / audio.
   • Video codec – best / av1 / h264.
   • Audio codec – best / opus / aac / mp3.
   • Container – mkv (recommended) / mp4 / webm.
   • Embed thumbnail – yes/no (not supported for WebM).
   • Embed chapters – yes/no.
   • SponsorBlock – off / mark / remove.
   • Auto‑generated subs – language codes (e.g., fa,en). Leave empty for no subs.
   • Split archive size – e.g., 100m (default). This splits the final 7‑zip archive so each part stays under GitHub’s 100 MB limit.
   • Password – (optional) encrypt the archive.
6. Click Run workflow again to start.

The workflow will:

• Download the video + subtitles.
• Embed metadata, thumbnail, and chapters (if enabled).
• Create a 7‑zip archive (split if needed) containing both the video and .srt subtitle files.
• Commit and push the archive to your repository.

---

🙏 Credits

This workflow is a combination and improvement of:

• CNS (CNS Download Video) by MercilessMarcel
• ir-downloader by ali25az

Thank you to both authors for their foundational work!

---

📄 License

This workflow is free to use and modify. No warranty is provided. Use at your own risk.