Add save-chapters command for FFmetadata chapter export (#323) by Davidvisualstudio007 · Pull Request #599 · Breakthrough/PySceneDetect

Davidvisualstudio007 · 2026-11-08T12:53:19Z

Closes #323

This adds a save-chapters command that saves the detected scenes as chapters in FFmetadata format. You can then add them to a video with ffmpeg without re-encoding:

scenedetect -i video.mp4 detect-content save-chapters
ffmpeg -i video.mp4 -i video-Chapters.txt -map_chapters 1 -codec copy output.mp4

What I changed:

Added write_scene_list_ffmetadata() to scenedetect.output. I based it on the EDL writer, so it works with a file path or an open file
Added the save-chapters command with -f, -t and -o options, and a [save-chapters] section in the config. -t lets you change chapter names using $VIDEO_NAME and $SCENE_NUMBER
Special characters in titles get escaped so ffmpeg doesn't misread them
Updated the changelog and features list, regenerated the CLI docs, and added save-chapters to the docs generator's CONCORDANCE and the API docs page

For the timing I used _frame_timecode_seconds(), so it stays accurate at 23.976 and 29.97 and doesn't drift like the EDL issue in #593. Times round up to the next millisecond so a chapter never starts before its first frame.

I added 25 tests in test_output.py and 2 in test_cli.py, including one that actually runs ffmpeg to add the chapters to a video and checks they're there. Ruff passes and the output and CLI tests all pass on the latest main. I also tried it on goldeneye.mp4 and the chapters showed up in VLC.

I left YouTube style chapters out for now. YouTube needs the first chapter at 00:00, at least 3 chapters, and each one at least 10 seconds long, so I wasn't sure how you'd want short scenes handled.

Breakthrough · 2026-11-10T01:43:03Z

+
+The chapters can be added to a video with ffmpeg without re-encoding, e.g.:
+
+    ffmpeg -i video.mp4 -i video-Chapters.txt -map_metadata 1 -codec copy output.mp4


Should we be using -map_chapters 1 here instead of -map_metadata 1?

The same command is also in the write_scene_list_ffmetadata docstring, the roundtrip test in tests/test_output.py, and the PR description.

ohh mb, didn't realise -map_metadata copies the other metadata too. Switched it to -map_chapters everywhere (help text, docstring, test and the PR description).

Breakthrough · 2026-11-10T03:13:41Z

+``save-chapters``
+========================================================================


Could you merge main, run python docs/generate_cli_docs.py, and commit what it changes under docs/? It should handle most of these docs changes for you now.

Done, rebased and ran the script. It also flagged that save-chapters was missing from CONCORDANCE and the API page, so I added it to both.

Breakthrough · 2026-11-10T03:13:43Z

+    write_scene_list_ffmetadata(
+        output_path=chapters_path,
+        scene_list=scenes,
+        title_format=title,


save-edl and save-otio substitute $VIDEO_NAME in their title before passing it on. Should we do the same here, so -t '$VIDEO_NAME - Scene $SCENE_NUMBER' works?

Ah nice, didn't think of that. Added it, and changed the CLI test to use "$VIDEO_NAME - Shot $SCENE_NUMBER" so it should be sweettt

Breakthrough · 2026-11-10T03:13:43Z

+def write_scene_list_ffmetadata(
+    output_path: StrPath | BytePath | ty.TextIO,
+    scene_list: SceneList,
+    title_format: str = "Scene $SCENE_NUMBER",


Let's call this title_format_template to be more clear that it's just a template, and for consistency w/ other commands args.

Breakthrough · 2026-11-10T03:13:44Z

+        start_ms = round(_frame_timecode_seconds(start) * 1000)
+        end_ms = round(_frame_timecode_seconds(end) * 1000)


Would math.ceil() be safer? Frame 12 at 24000/1001 fps (500.5 ms) would make a good test case since it should equal a start of 501.

Makes sense, switched to math.ceil and added your frame 12 example as a test, it comes out as 501 now.

Breakthrough · 2026-11-10T03:19:36Z

Thanks for the PR. Left you a few comments. Also I'll fix up the docs generator script to make it easier to update, so you will need to rebase this on main again, sorry.

Breakthrough · 2026-11-10T03:21:45Z

+    for char in ("\\", "=", ";", "#", "\n"):
+        value = value.replace(char, "\\" + char)
+    return value


We should also escape \r, and append a space when the escaped value ends in a backslash.

Added both, plus tests for each. Missed the trailing backslash one, thanks 4 the catch

…ough#323)

Davidvisualstudio007 · 2026-11-11T12:19:09Z

Thanks for going through it! much appreciated. Rebased on main and sorted all the comments. I also moved the changelog entry to 0.8 since 0.7.3 is out now. LMK if anything needs changing, Cheers!

MuhammadBilalKhan267

Found one minor issue with title substitution.

MuhammadBilalKhan267 · 2026-11-11T16:07:47Z

+    assert context.video_stream is not None
+    video_name = context.video_stream.name
+    chapters_path = get_and_create_path(
+        Template(filename).safe_substitute(VIDEO_NAME=video_name),


Could we pass the video name to the writer and substitute both variables in one pass per scene? The current two passes can interpret $SCENE_NUMBER inside the video name or an escaped literal as a placeholder.

Done. The writer now takes a video_name argument (same as write_scene_list_fcpx) and fills in both in one pass. Added tests for a video name with a placeholder in it and for $$ escapes.

Breakthrough requested review from Breakthrough and MuhammadBilalKhan267 November 10, 2026 01:11

Breakthrough assigned Breakthrough and Davidvisualstudio007 and unassigned Breakthrough Nov 10, 2026

Breakthrough added the feature label Nov 10, 2026

Breakthrough added this to the 0.8 milestone Nov 10, 2026

Breakthrough requested changes Nov 10, 2026

View reviewed changes

Breakthrough reviewed Nov 10, 2026

View reviewed changes

Davidvisualstudio007 added 5 commits November 11, 2026 19:34

[output] Add write_scene_list_ffmetadata for chapter export (Breakthr…

6cd42a0

…ough#323)

[tests] Add tests for write_scene_list_ffmetadata

fed5efd

[cli] Add save-chapters command (Breakthrough#323)

99672b9

[docs] Document save-chapters command

ff643b3

Address review feedback for save-chapters (Breakthrough#323)

6f25206

Davidvisualstudio007 force-pushed the save-chapters branch from 918b2c7 to 6f25206 Compare November 11, 2026 11:53

Davidvisualstudio007 requested a review from Breakthrough November 11, 2026 12:24

MuhammadBilalKhan267 reviewed Nov 11, 2026

View reviewed changes

Substitute chapter title placeholders in a single pass

a224a2e


		The chapters can be added to a video with ffmpeg without re-encoding, e.g.:

		ffmpeg -i video.mp4 -i video-Chapters.txt -map_metadata 1 -codec copy output.mp4

		``save-chapters``
		========================================================================

		start_ms = round(_frame_timecode_seconds(start) * 1000)
		end_ms = round(_frame_timecode_seconds(end) * 1000)

Conversation

Davidvisualstudio007 commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Breakthrough commented Nov 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Davidvisualstudio007 commented Nov 11, 2026

Uh oh!

MuhammadBilalKhan267 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Davidvisualstudio007 commented Nov 8, 2026 •

edited

Loading