Get the chapter list from a downloaded YouTube video

A yt-dlp download with the creator's chapters

--embed-chapters wrote the creator's description timestamps into the MP4. You get them straight back.

Input: tutorial.mp4 (yt-dlp --embed-chapters)

Output: tutorial-chapters.json
{
  "chapters": [
    { "start": 0,     "end": 42.0,   "title": "Intro" },
    { "start": 42.0,  "end": 360.0,  "title": "Setup" },
    { "start": 360.0, "end": 905.0,  "title": "Walkthrough" },
    { "start": 905.0, "end": 980.5,  "title": "Wrap-up" }
  ]
}

Rebuilding the 00:00 description timestamps

Format each start to MM:SS and prepend to the title. YouTube needs the first line at 00:00, 3+ chapters, each ≥ 10s.

const { chapters } = require('./tutorial-chapters.json');
const mmss = s => `${String(Math.floor(s/60)).padStart(2,'0')}:${String(Math.floor(s%60)).padStart(2,'0')}`;
console.log(chapters.map(c => `${mmss(c.start)} ${c.title ?? 'Chapter'}`).join('\n'));

// →
00:00 Intro
00:42 Setup
06:00 Walkthrough
15:05 Wrap-up

A download with no embedded chapters

Downloaded without --embed-chapters, so the chapters stayed in the description text only. The file has none.

Input: clip.mp4 (yt-dlp, no flag)

Output: clip-chapters.json
{
  "chapters": []
}

→ Re-download with --embed-chapters, or copy the
   timestamps from the original description manually.

Validating YouTube's chapter rules before pasting

Catch the common failures — first chapter not at 0, fewer than 3 chapters, or a sub-10-second segment — in code.

const { chapters } = require('./tutorial-chapters.json');
const ok = chapters.length >= 3
  && chapters[0].start === 0
  && chapters.every(c => (c.end - c.start) >= 10);
console.log(ok ? 'YouTube will enable chapters' : 'Fix: 00:00 start, 3+ chapters, each >=10s');

Re-timing chapters after trimming the intro

If you cut N seconds off the front in a re-edit, shift every start by N and drop anything now before 0.

const { chapters } = require('./tutorial-chapters.json');
const cut = 42; // removed the 42s intro
const shifted = chapters
  .map(c => ({ ...c, start: c.start - cut, end: c.end - cut }))
  .filter(c => c.end > 0)
  .map((c, i) => i === 0 ? { ...c, start: 0 } : c);
console.log(JSON.stringify(shifted, null, 2));

Returns { "chapters": [] }. Without that flag, yt-dlp leaves the chapters in the description text only — they're never written to the file's metadata. Re-download with --embed-chapters, or copy the timestamps from the original description by hand.

If the embedded first chapter's start isn't 0, YouTube won't enable chapters when you paste the rebuilt description. The cookbook's re-time example forces the first start to 00:00; do that before pasting.

YouTube requires at least 3 chapters. A video the creator gave only 1–2 markers will read back as a 1–2 item array — valid JSON, but YouTube won't show chapters. There's nothing to fix in extraction; add markers at the source.

YouTube needs each chapter ≥ 10 seconds. A sub-10s segment (end - start < 10) disables chapter detection for the whole video. Validate with the cookbook check before pasting.

Creator titles like 第1章 or Intro 🎬 round-trip verbatim as UTF-8 in the JSON, so they paste back into the description intact in a UTF-8 context.

This tool reads a downloaded file's metadata — it doesn't fetch from youtube.com. Download first (yt-dlp), then drop the resulting MP4/MKV here.

If you re-encoded the download (e.g. through a converter that didn't carry metadata), the chapters can be lost and the array comes back empty. Re-download the original with --embed-chapters to recover them.

Header-only parsing reads chapters in seconds regardless of runtime. Free tier caps the file at 1 GB; a long 1080p/4K download may need Pro (10 GB) or higher.

This tool gives you the chapter JSON; it doesn't post to YouTube or edit the file. Use the JSON to generate the MM:SS Title text and paste it into Studio yourself.