README.md

metadata

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 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; 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 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/ 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.
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

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