SubCraft is a lightweight, cloud-native Telegram bot and web service built with Python, FastAPI, and python-telegram-bot. It leverages state-of-the-art AI APIs (Groq Whisper, Google Gemini, OpenAI) and FFmpeg to extract audio, generate precise subtitle transcriptions, translate subtitles into fluent line-by-line Persian, and soft-embed subtitles into video clips on the fly.
- Cloud-Native AI Workloads: Uses Groq Whisper (
whisper-large-v3) for lightning-fast speech-to-text with word-level timestamps. - Fluent Persian Translation: Uses Groq AI (
openai/gpt-oss-120b) for natural Persian translation with fallback to Google Gemini, while preserving exact.srttiming. - Line-by-Line Subtitles: Produces alternating original language / Persian translation subtitles.
- Fast Soft-Subtitle Embedding: Soft-embeds subtitles into MKV containers via FFmpeg without full video re-encoding.
- MP3 with Synced LRC Lyrics (Musicolet Standard): Exports tagged MP3 audio with timestamped ID3
USLTsynced lyrics and cover art directly playable in Musicolet and advanced Android music players. - Web Video Download Support: Downloads videos directly from social media platforms using
yt-dlp. - Telegram Bot Webhook Integration: Powered by FastAPI with automatic webhook setup on startup.
Direct media uploads to the bot (up to the Telegram 20 MB API limit):
- Video Extensions:
.mp4,.mkv,.mov,.avi,.webm,.flv,.m4v - Audio & Voice Extensions:
.mp3,.wav,.aac,.m4a,.flac,.ogg,.opus, Telegram Voice messages (.ogg)
Send video or audio URLs directly in chat for seamless processing without file size limits:
- Instagram: Reels, Posts, IGTV clips
- YouTube: YouTube Shorts, standard YouTube Videos
- TikTok: Public video clips
- Twitter / X: Video tweets
- Direct Web Links: Any publicly downloadable
.mp4,.mp3,.mkvdirect file URLs
Make sure you have Docker and Docker Compose installed on your machine or VPS.
# 1. Clone the repository from GitHub
git clone https://github.com/mehdichamani/SubCraft.git
cd SubCraft
# 2. Prepare environment file
cp .env.example .env
# Edit .env file and fill in your TELEGRAM_BOT_TOKEN, GROQ_API_KEY, GEMINI_API_KEY, and RENDER_EXTERNAL_URL
# 3. Build and launch with Docker Compose
docker compose up -d --builddocker-compose.yml service definition:
version: '3.8'
services:
subcraft:
build:
context: .
dockerfile: Dockerfile
container_name: subcraft
restart: always
ports:
- "8000:8000"
env_file:
- .env
environment:
- PORT=8000# Build Docker image
docker build -t subcraft .
# Run container with environment file
docker run -d \
--name subcraft \
--env-file .env \
-p 8000:8000 \
subcraftRender supports deploying this repository directly using Docker runtime built from your GitHub repository.
- Log in to Render Dashboard.
- Click New + -> Web Service.
- Connect your GitHub repository
https://github.com/mehdichamani/SubCraft. - Select Docker as the Environment / Runtime (Render automatically detects
Dockerfile).
Platforms like YouTube and Instagram require cookie authentication for yt-dlp download requests. Because multiline cookies.txt files can be corrupted when pasted directly into cloud environment variables, SubCraft supports Base64-encoded cookie strings.
- Generate a single-line Base64 string from your local
cookies.txtorcombined_cookies.txt:# On Linux / VPS: base64 -w 0 cookies.txt # On macOS: base64 -i cookies.txt # On Windows (PowerShell): [Convert]::ToBase64String([IO.File]::ReadAllBytes("cookies.txt"))
- Copy the resulting Base64 string.
- In your Render Web Service dashboard, go to Environment -> Add Environment Variable.
- Set Key:
YOUTUBE_COOKIES,INSTAGRAM_COOKIES, orCOOKIESand Value:<your-base64-encoded-string>. - When the application runs, it automatically decodes and merges the cookies into a valid temporary Netscape cookie file for
yt-dlp.
💡 Tip: For a comprehensive guide on managing cookies, extraction tips, and handling database expiration/failover scenarios, refer to the Cookie & Database Fallback Guide.
Add the following Environment Variables in your Render Web Service settings:
| Variable | Required | Description | Example |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
Yes | Telegram Bot token from @BotFather | 123456789:ABCdef... |
GROQ_API_KEY |
Yes | Groq API Key for Whisper STT & LLM Translation from Groq Console | gsk_... |
GEMINI_API_KEY |
Optional | Optional Google Gemini API key from Google AI Studio for fallback | AIzaSy... |
RENDER_EXTERNAL_URL |
Yes | Public Render service HTTPS URL (No trailing slash) | https://subcraft.onrender.com |
WEBHOOK_SECRET |
Optional | Secret token for secure webhook authorization | random_secret_string |
YOUTUBE_COOKIES |
Optional | Base64-encoded string of YouTube cookies for yt-dlp |
IyBOZXRzY2FwZSBDb29raWU... |
INSTAGRAM_COOKIES |
Optional | Base64-encoded string of Instagram cookies for yt-dlp |
IyBOZXRzY2FwZSBDb29raWU... |
COOKIES |
Optional | Base64-encoded string of combined Netscape cookies (combined_cookies.txt) |
IyBOZXRzY2FwZSBDb29raWU... |
PORT |
Optional | Listening port (Render automatically sets $PORT) |
8000 |
- Repository: mehdichamani/SubCraft
- Developer: Mehdi Chamani (مهدی چمنی)
- Email:
mahdi.chamani20@gmail.com - Telegram: @mehdichamanni
SubCraft یک ربات تلگرام و سرویس ابری سبک و هوشمند است که با زبان پایتون، فریمورک FastAPI و کتابخانه python-telegram-bot توسعه یافته است. این ربات با بهرهگیری از هوش مصنوعی Groq Whisper، Google Gemini و FFmpeg، صدا را استخراج کرده، زیرنویس دقیق را تولید میکند، آن را به فارسی روان ترجمه کرده و زیرنویس سافتساب را روی ویدیو متصل مینماید.
- تبدیل گفتار به متن هوشمند: استفاده از Groq Whisper (
whisper-large-v3) برای استخراج متن و زمانبندی دقیق زیرنویس. - ترجمه فارسی روان: ترجمه خط به خط با مدل هوش مصنوعی (
openai/gpt-oss-120b) و مترجم گوگل با حفظ کامل زمانبندی فایل.srt. - نمایش متناوب زیرنویس: تولید زیرنویس دو زبانه (زبان اصلی / فارسی متناوب).
- الصاق سریع زیرنویس سافتساب: الصاق زیرنویس روی ویدیو با کانتینر MKV بدون افت کیفیت و رندر مجدد.
- خروجی صوت MP3 با لیریکس همگام زمانی (Musicolet LRC): ساخت فایل صوتی MP3 با متادیتای استاندارد ID3 و تگهای
USLTحاوی زمانبندی[mm:ss.xx]جهت پخش همگام و کارائوکه در اپلیکیشن موزیکپلیر Musicolet و سایر پلیرهای پیشرفته. - دانلود از شبکههای اجتماعی: پشتیبانی از دریافت ویدیو از لینکهای مختلف با
yt-dlp. - معماری وبهوک: پاسخدهی سریع بر پایه FastAPI و ثبت خودکار Webhook.
امکان ارسال مستقیم فایل به ربات (تا سقف محدودیت ۲۰ مگابایت تلگرام):
- فرمتهای ویدیو:
.mp4,.mkv,.mov,.avi,.webm,.flv,.m4v - فرمتهای صوتی و ویس:
.mp3,.wav,.aac,.m4a,.flac,.ogg,.opus, ویسهای تلگرام
ارسال لینک ویدیو یا صوت بدون محدودیت حجم فایل:
- اینستاگرام: ریلمز (Reels)، پستها، و ویدیوهای IGTV
- یوتیوب: ویدیوهای اصلی و یوتیوب شورتس (Shorts)
- تیکتاک: کلیپهای ویدئویی تیکتاک
- توییتر / ایکس: ویدیوهای پست شده در Twitter/X
- لینکهای مستقیم: تمامی لینکهای مستقیم قابل دانلود با پسوند
.mp4و.mp3
اطمینان حاصل کنید که داکر و داکر کامپوز روی سرور یا سیستم شما نصب شده است.
# ۱. دریافت مخزن پروژه از گیتهاب
git clone https://github.com/mehdichamani/SubCraft.git
cd SubCraft
# ۲. ایجاد و تنظیم فایل متغیرهای محیطی
cp .env.example .env
# فایل .env را ویرایش کرده و توکن تلگرام و کلیدهای API را وارد کنید
# ۳. ساخت و اجرای کانتینر با داکر کامپوز
docker compose up -d --buildمحتوای فایل docker-compose.yml:
version: '3.8'
services:
subcraft:
build:
context: .
dockerfile: Dockerfile
container_name: subcraft
restart: always
ports:
- "8000:8000"
env_file:
- .env
environment:
- PORT=8000سرویس Render.com به صورت مستقیم از محیط اجرایی داکر (Docker) و اتصال به مخزن گیتهاب پشتیبانی میکند.
۱. وارد حساب کاربری خود در Render.com شوید.
۲. روی گزینه New + و سپس Web Service کلیک کنید.
۳. مخزن گیتهاب https://github.com/mehdichamani/SubCraft را متصل کنید.
۴. نوع محیط اجرا (Runtime) را روی Docker قرار دهید (Render به صورت خودکار Dockerfile موجود در مخزن را شناسایی میکند).
دانلود از یوتیوب یا اینستاگرام ممکن است نیازمند کوکیهای معتبر جهت احراز هویت yt-dlp باشد. از آنجا که فرمت چندخطی فایل cookies.txt ممکن است در متغیرهای محیطی سرورهای ابری بهم بریزد، پروژه SubCraft به طور کامل از فرمت Base64 پشتیبانی میکند.
۱. تبدیل فایل cookies.txt یا combined_cookies.txt به یک رشته تکخطی Base64:
# در لینوکس / VPS:
base64 -w 0 cookies.txt
# در مک (macOS):
base64 -i cookies.txt
# در ویندوز (PowerShell):
[Convert]::ToBase64String([IO.File]::ReadAllBytes("cookies.txt"))۲. رشته Base64 خروجی را کپی کنید.
۳. در داشبورد Render، به بخش Environment -> Add Environment Variable بروید.
۴. نام کلید را YOUTUBE_COOKIES یا INSTAGRAM_COOKIES یا COOKIES و مقدار آن را برابر با رشته Base64 کپیشده قرار دهید.
۵. ربات هنگام اجرا به طور خودکار این رشتهها را رمزگشایی کرده و فایل کوکی یکپارچه و معتبر ایجاد میکند.
💡 راهنمای تکمیلی: برای بررسی ساختار معماری Fail-Safe، سناریوی انقضای دیتابیس Render و استخراج کوکیها به راهنمای جامع مدیریت کوکی و Fallback دیتابیس مراجعه کنید.
| متغیر | اجباری | توضیحات | نمونه |
|---|---|---|---|
TELEGRAM_BOT_TOKEN |
بله | توکن ربات دریافتی از @BotFather | 123456789:ABCdef... |
GROQ_API_KEY |
بله | کلید API سرور Groq برای تبدیل گفتار به متن و ترجمه هوشمند | gsk_... |
GEMINI_API_KEY |
اختیاری | کلید API جمینای از Google AI Studio برای جایگزین موقت (Fallback) | AIzaSy... |
RENDER_EXTERNAL_URL |
بله | آدرس عمومی HTTPS سرویس رندر برای ثبت وبهوک | https://subcraft.onrender.com |
WEBHOOK_SECRET |
اختیاری | توکن امنیتی وبهوک جهت تایید درگاه | random_secret_string |
YOUTUBE_COOKIES |
اختیاری | رشته Base64 شده فایل کوکی یوتیوب برای دانلود ویدیوها | IyBOZXRzY2FwZSBDb29raWU... |
INSTAGRAM_COOKIES |
اختیاری | رشته Base64 شده فایل cookies.txt برای دانلود از اینستاگرام |
IyBOZXRzY2FwZSBDb29raWU... |
COOKIES |
اختیاری | رشته Base64 شده کوکیهای ترکیبی Netscape برای تمام سرویسها | IyBOZXRzY2FwZSBDb29raWU... |
- توسعهدهنده: مهدی چمنی
- ایمیل:
mahdi.chamani20@gmail.com - تلگرام: @mehdichamanni
- مخزن گیتهاب: https://github.com/mehdichamani/SubCraft
- میزبانی شده در: Render.com (توسط Docker Runtime)

