Youtube timestamper

YouTube Timestamper

Generates accurate, human-readable chapter timestamps for YouTube videos by fetching the real transcript (with second-level offsets) and grouping it into meaningful sections.

Never invent or guess timestamps. Always use real transcript data or explicitly tell the user that the transcript is unavailable.

---

Step 1 — Extract the video ID and fetch the transcript

Run the bundled script using bash_tool. The script handles URL parsing and language fallback automatically:

pip install youtube-transcript-api --break-system-packages -q 2>/dev/null
python /path/to/skill/scripts/fetch_transcript.py "<url_or_video_id>"

The script path is relative to wherever the skill is installed. Use the path shown in your available_skills list, or find it with:

find /mnt/skills -name "fetch_transcript.py" 2>/dev/null | head -1

The script outputs one of:

• Success: {"segments": [...], "language": "en", "video_id": "..."}
  • Each segment: {"start": 42.3, "text": "some spoken text"}
• Error: {"error": "..."}

---

Step 2 — Handle errors gracefully

If the script returns an error:

Error type	What to tell the user
Transcripts disabled	"This video has transcripts turned off. You can paste the transcript manually — YouTube's auto-captions are available under the ... menu → 'Open transcript'."
Video unavailable	"This video appears to be private, age-restricted, or deleted."
No transcript found	"No transcript is available in the requested language. Try without specifying a language, or paste it manually."
Network / install error	"I couldn't reach YouTube from this environment. Paste the transcript text and I'll generate timestamps from that."

If the user pastes a transcript manually, parse it by looking for timestamp patterns like [0:00], (1:23), or just raw text blocks — then proceed to Step 3.

---

Step 3 — Group segments into chapters

The raw transcript has hundreds of short segments. Your job is to identify topic boundaries and group them into meaningful chapters.

Scale chapter count to video length:

Video duration	Target chapters
Under 10 min	4–7
10–30 min	7–12
30–60 min	12–20
60–90 min	18–28
90+ min	25–40

Never stop early — cover the entire video from start to finish.

How to find good boundaries:

• Look for topic shifts: new concepts introduced, speaker transitions, scene changes
• Look for natural pauses (gaps > 3–5 seconds between segments)
• Look for transitional phrases: "Now let's talk about...", "Moving on...", "The next thing is...", "So in summary..."
• Aim for chapters of roughly similar length, but let content drive the cuts

For long transcripts (30+ min): Process the transcript in thirds or halves mentally, ensuring you identify chapter boundaries throughout the entire video — not just the first portion. Always verify your last timestamp is within a few minutes of the video end.

Use the start value of the first segment in each group as the chapter timestamp.

---

Step 4 — Format the output

Always format timestamps so they work as YouTube chapter markers:

• The first chapter must start at 0:00 (YouTube requires this)
• Format: M:SS Title for videos under 1 hour, H:MM:SS Title for longer
• Title: 2–6 words, title case, no punctuation at the end
• Keep it scannable — this output is meant to be pasted into a YouTube description

Example output:

0:00 Introduction
1:45 What Is Machine Learning
4:22 Types of Neural Networks
9:10 Training a Model
14:33 Common Pitfalls
19:08 Real World Applications
24:55 Conclusion and Resources

After the timestamps, offer a one-sentence summary of each chapter if the user might want it (e.g. for a video description). Don't pad with unnecessary commentary.

---

Tips for quality

• If the transcript has filler words or garbled auto-captions, use the surrounding context to infer the topic rather than quoting bad text in chapter titles
• For tutorial videos, chapters often follow the step sequence — respect that structure
• For interviews, chapters often follow question topics — use the question as the title
• For lectures, chapters follow conceptual units — name the concept, not the time slot
• If a video is under 3 minutes, timestamps may not be useful — tell the user that YouTube only shows chapters for videos with 3+ chapters and the first at 0:00
• For long videos (30+ min): Always scan all the way to the end of the transcript before writing timestamps. A common failure mode is stopping at chapter 12 partway through. Check that your final timestamp is near the video's end.

---

Compatibility

Requires youtube-transcript-api. The script installs it automatically if missing. Works with any public YouTube video that has auto-generated or manual captions.