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 are usually **blocked**. The fix is a **residential proxy** — and each
user can bring their own.

### Recommended: run your own residential proxy (per user)

Paste your own proxy URL into the **Your proxy URL** field so YouTube requests for *your*
generation exit from *your* home IP. Get a proxy with the **Home Proxy Panel**:

**GitHub:** <https://github.com/vivekchakraverty/tutorialmaker-home-proxy-panel>
(also in [`tools/`](tools/) here).

1. **Download** the prebuilt `HomeProxyPanel` app for your OS from the repo's Releases (no
   Python needed), **or** run from source: `pip install -r tools/requirements.txt` then
   `python tools/home_proxy_panel.py`.
2. **Compile it yourself** (optional): `pip install pyinstaller` then
   `pyinstaller tools/home_proxy_panel.spec` → `dist/HomeProxyPanel`. PyInstaller doesn't
   cross-compile, so build on each OS (or use the repo's GitHub Actions matrix). Full details
   in [`tools/build_panel.md`](tools/build_panel.md).
3. **Use it:** Start proxy → Start tunnel (bore auto-downloads) → Test proxy →
   **📋 Copy my Proxy URL** → paste into **Your proxy URL** above → **Generate**. Keep the
   panel running during generation.

### Fallbacks (owner)

- Set the optional **`YT_PROXY`** secret (a shared residential proxy) and/or **`YT_COOKIES`**
  (Netscape cookies.txt contents, raw or base64). The per-user field above overrides `YT_PROXY`.
- 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
```