Telegram Photo + YouTube Audio Video Bot (NestJS)

This project provides:

• A Telegram bot (/create -> photo -> YouTube URL -> generated video).
• A reusable REST API for future website integration.
• In-memory async jobs with ffmpeg + yt-dlp processing.

Features

• Accepts one photo + one public YouTube URL.
• Telegram guided UX with inline choices (source mode + output duration).
• Accepts audio source from either YouTube URL or uploaded video.
• Extracts audio with yt-dlp.
• Creates MP4 matching source image dimensions (odd dimensions padded by +1 pixel for compatibility).
• Max source duration is configurable (default: 10 minutes).
• API key protected endpoints.
• Swagger docs at /docs.
• Immediate temporary file cleanup after delivery/download.

Requirements

• Node.js 20+
• ffmpeg installed and available in PATH (or set FFMPEG_PATH)
• ffprobe installed and available in PATH (or set FFPROBE_PATH)
• yt-dlp installed and available in PATH (or set YTDLP_PATH)

Quick Start

1. Install dependencies:

   npm install

2. Create env file:

   cp .env.example .env

3. Set required values in .env:
   • API_KEY
   • TELEGRAM_BOT_TOKEN (optional if API-only)
   • Optional yt-dlp stability settings:
     • YTDLP_JS_RUNTIMES=node
     • YTDLP_EXTRACTOR_ARGS=youtube:player_client=android,web
     • YTDLP_RETRY_EXTRACTOR_ARGS=youtube:player_client=tv,ios
     • YTDLP_COOKIES_FILE=/absolute/path/to/cookies.txt (if 403 continues)
   • Optional upload limits:
     • MAX_UPLOADED_SOURCE_FILE_BYTES=209715200
4. Start in dev mode:

   npm run start:dev

API

Base path: /v1/media-jobs

• POST /v1/media-jobs
  • Multipart fields:
    • photo (file)
    • youtubeUrl (string)
  • Returns:

    { "jobId": "...", "status": "queued" }

• GET /v1/media-jobs/:jobId
  • Returns current status and error details if failed.
• GET /v1/media-jobs/:jobId/result
  • Streams final MP4 when ready.
  • Cleans generated file after successful download.

All API calls require header: x-api-key: <API_KEY>.

Telegram Flow

1. Send /create.
2. Pick source mode (YouTube URL or Upload Video).
3. Send image (document preferred for exact dimensions).
4. Send audio source (URL or video/document).
5. Pick output duration (15s, 30s, 60s, Full).
6. Bot edits one status message through progress and sends final video.

Run Tests

npm test

Docker

docker compose up --build

Notes

• Session state and jobs are in memory (reset on restart).
• Output/result files are stored in STORAGE_DIR (default ./tmp) and cleaned after delivery.