feat: chapters from the video description #16

Chapters were left out of 1.1.0 because YoutubeExplode has no chapters API. This issue adds them by parsing the description, which ytx already fetches.

Design

• Source. Creator chapters are the timestamped lines in the description, such as 00:00 Intro or (03:12) - Setup. No extra request is needed, and the code stays AOT-safe.

• YouTube's own rules. Keep a run only if it meets all of these, otherwise return an empty list:

  • it starts at 00:00
  • it has at least 3 chapters
  • times strictly increase
  • each chapter lasts at least 10 seconds

  These rules stop tracklists and stray timestamps from being read as chapters.

• Output. A new chapters field, [{start, end, title}], with times in seconds. end is the next chapter's start, or the video's duration for the last chapter, or null for a live stream. The field is [] when a video has no chapters. It is filled with --metadata-only too. Adding a field doesn't break existing consumers, so this ships as 1.2.0.

• Markdown. transcript and -f md get a ## Title heading at each chapter boundary.

Out of scope

• Auto-generated "key moments". They need the watch page to be scraped, which is fragile.
• A chapter index on each segment.
• WebVTT chapter tracks.

Limitation

Only videos whose creators wrote chapters in the description have any.

Follows #3 and #7.

🤖 Generated with Claude Code