Documentation for --chapters-file not clear.

[scottmartincampbell]

Using 0.25.0-e2b9551 on Ubuntu.

I'm experimenting with the --chapters-file option, but can't figure out the format.

I tried two basic formats: 00:00:30 Test chapter and 00:00:30:000 Test chapter with a short file:

00:00:30:000 Test chapter 1
00:00:50:000 Test chapter 2
00:09:33:000 Test chapter 3  

MPV reads both formats, according to the log:

[bdmv/bluray] Opening testchap.txt
[file] Opening testchap.txt
[file] Stream opened successfully.
[demux] Trying demuxers for level=normal.
[lavf] Found 'vplayer' at score=100 size=94.
[lavf] Data looks like UTF-8, ignoring user-provided charset.
[lavf] avformat_find_stream_info() finished after 94 bytes.
[demux] Detected file format: vplayer (libavformat)
[lavf] assuming demuxer read all data; closing stream
[find_files] Loading external files in .

Any existing chapters in the video file are unavailable, but the new chapters in the chapter file are not. I've been testing an MP4 file.

There's some relevant discussion here: https://github.com/mpv-player/mpv/issues/1171, but doesn't provide a format. My next step was to just write a lua script that would read a chapters file, parse it, and add chapters, but using the existing option seems preferable.

[ghost]

The option opens the file like a media file. So this could be a mkv file, which it would load, take the chapter list from it, and then close again. Your "guessed format happens to interpret the file as subtitle file, but the file contains no chapters, only subtitle events, so the player will essentially clear the chapter list.

One way to make a text file that contains chapters only would be using EDL with explicit durations and using null:// instead of files: https://github.com/mpv-player/mpv/blob/master/DOCS/edl-mpv.rst

Another would be using this pseudo-format: http://ffmpeg.org/ffmpeg-formats.html#Metadata-1

[ghost]

OK using EDL is a bad idea, because null:// doesn't work, and you can't set the chapter names.

We could invent our own chapter format though, if ffmpeg's metadata format is too ugly.

[scottmartincampbell]

Thanks! The ffmpeg metadata pseudo-format works, so I'll do that. I didn't quite realize how it was reading it as a media file. That's clever.

However, it is, as you say, a bit ugly. The timebase makes it harder to read/edit by hand. A one-line, hh:mm:ss.ms format would be handy. As a pointer, MP4box reads a few different formats: https://gpac.wp.imt.fr/mp4box/mp4box-documentation/

-chap chap_file : adds chapter information located in chap_file to the destination file. Chapter extensions have been introduced by Nero and are NOT standard extensions of IsoMedia file format, don’t be surprised if some players don’t understand them.

The following syntaxes are supported in the chapter text file, with one chapter entry per line:

ZoomPlayer chapter files : AddChapter(nb_frames,chapter name),AddChapterBySeconds(nb_sec,chapter name) and AddChapterByTime(h,m,s,chapter name). One chapter entry per line.
Time codes : h:m:s name, h:m:s:ms name and h:m:s.ms name. One chapter entry per line.
SMPTE codes : h:m:s;nb_f/fps name and h:m:s;nb_f name with nb_f the number of frames and fps the framerate. One chapter entry per line.
Common syntax : CHAPTERX=h:m:s[:ms or .ms] on one line and CHAPTERXNAME=name on the other – the order is not important but chapter lines MUST be declared sequencially (same X value expected for 2 consecutive lines).

[porg]

Luckily meanwhile someone created a lua script chapter-make-read.lua for mpv which automatically loads a video chapter sidecar file .CHP which is a simple UTF-8 text file with exactly the simple human readable format H:MM:SS Chapter One\nH:MM:SS Two\n ... as you proposed in your original post.