README.md

---
title: TutorialMaker
emoji: 💻
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.19.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: Make Tutorials from YouTube Videos
---

# YouTube → Tutorial Post Generator

Give a **topic** and your **Hugging Face token**, and this Space builds a downloadable
**`.docx` tutorial** (text + AI-captioned screenshots) from the single best YouTube video
on that topic.

## Pipeline

1. **Search** — top 5 videos via the [`adarshajay/youtube-search`](https://huggingface.co/spaces/adarshajay/youtube-search) Space.
2. **Sentiment rank** — fetch top comments per video with `yt-dlp` and score them with the
   BERT classifier [`OmarMedhat7/youtube-sentiment-analysis-model`](https://huggingface.co/OmarMedhat7/youtube-sentiment-analysis-model);
   the video with the highest positive share wins.
3. **Download** the winner with `yt-dlp` and extract audio with `ffmpeg`.
4. **Transcribe** locally with `faster-whisper` (segment timestamps).
5. **Candidate frames** are extracted densely from the video, then the **video is
   auto-deleted** — only small JPEGs and the transcript remain.
6. **Tutorial text** — `deepseek-ai/DeepSeek-V3` (HF Inference Providers, billed to your
   token) turns the transcript into structured steps.
7. **Screenshot selection** — a weighted indicator blends each step's LLM-suggested
   timestamp with Whisper's actual speech timing.
8. **Captions** — a vision model (default `Qwen/Qwen2.5-VL-72B-Instruct`, billed to your
   token) captions each screenshot.
9. **Assemble** the `.docx` for download.

## Notes

- **Your HF token is used only for the LLM and vision-model calls** and is billed to your
  account. Create a fine-grained token with *"Make calls to Inference Providers"* at
  <https://huggingface.co/settings/tokens>.
- **Free CPU tier:** Whisper runs on CPU, so transcription is slow — keep videos short
  (default cap ~20 min).
- **YouTube may block the Space's IP.** If downloads/comments fail, add a Netscape-format
  cookie file as a Space secret named `YT_COOKIES` (the file's contents).

## Local run

```bash
pip install -r requirements.txt   # needs ffmpeg on PATH
python app.py
```