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**, your **Hugging Face token**, and a **YouTube Data API key**, and this
Space builds a downloadable **`.docx` tutorial** (text + captioned screenshots) from the
single best YouTube video on that topic. **No video download** — acquisition is API-based.

## Pipeline

1. **Search** — top 5 videos via the [`adarshajay/youtube-search`](https://huggingface.co/spaces/adarshajay/youtube-search) Space.
2. **Sentiment rank** — fetch each video's comments via the **YouTube Data API v3** and
   score them with the BERT classifier
   [`OmarMedhat7/youtube-sentiment-analysis-model`](https://huggingface.co/OmarMedhat7/youtube-sentiment-analysis-model);
   the highest positive share wins.
3. **Transcript** — fetched with **`youtube-transcript-api`** (already timestamped; no
   download, no Whisper).
4. **Tutorial text** — `deepseek-ai/DeepSeek-V3` (HF Inference Providers, billed to your
   token) turns the transcript into an **answer-engine-optimized** post: answer-first
   paragraph, H2 steps, FAQ, meta description, URL slug, last-updated/source citation.
   Optional **primary/secondary keyword** placement.
5. **Screenshots** — real frames at the right moments **without downloading the video**:
   `yt-dlp` resolves a direct stream URL (metadata only), then `ffmpeg -ss T -frames:v 1`
   grabs one frame per timestamp (sharpest of 3 candidates). Timestamps come from a
   weighted blend of the LLM's suggestion and the transcript's actual timing.
6. **Captions** — a vision model (default `Qwen/Qwen2.5-VL-72B-Instruct`, billed to your
   token) captions each screenshot.
7. **Assemble** the `.docx` for download.

## Keys & setup

- **Hugging Face token** — for the LLM + vision-model calls, billed to your account.
  Create a fine-grained token with *"Make calls to Inference Providers"* at
  <https://huggingface.co/settings/tokens>.
- **YouTube Data API key** — for fetching comments. Create one in the
  [Google Cloud Console](https://console.cloud.google.com/) and **enable *YouTube Data API
  v3***. Provide it in the UI, or set the **`YOUTUBE_API_KEY`** Space secret. (Without a
  key the Space skips sentiment and just uses the top search result.)

## Notes on YouTube access

The transcript and the stream-URL resolution hit YouTube directly. From a datacenter IP
(like a Space) these can occasionally be **blocked**:

- If transcript/stream resolution fails, set the optional **`YT_PROXY`** secret (a
  residential proxy) and/or **`YT_COOKIES`** (Netscape cookies.txt contents, raw or
  base64) — used only as a thin fallback.
- If the stream URL can't be resolved, the Space still produces a **text-only** tutorial.

## Local run

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