FFMETADATA fails to create a CTOC frame when adding chapters to MP3 files.

[Gavin Smalley]

• What you were trying to accomplish?
  • Trying to add chapters to an MP3 file using FFMETADATA.

• The problem you encountered?
  • The id3v2.3 metadata written was incomplete. CHAP frames were correctly created for every [CHAPTER] section in the FFMETADATA file, but no CTOC frame was created.
  • Without the CTOC frame the chapters are un-navigable in a wide variety of podcasting software. Furthermore the id3 standard requires CTOC to be added wherever CHAP frames are present.

• The exact command line you were using?
  • I used the command and file structure from the official documentation here - ​https://www.ffmpeg.org/ffmpeg-formats.html#Metadata-1

• Version of ffmpeg used?
  • ffmpeg version 3.4.6-0ubuntu0.18.04.1

• Comment
  • This method of adding both standard metadata and chapters using a simple FFMETADATA file is to be commended for it's simplicity but it's failure to add a CTOC frame means it is fundamentally flawed. Either the functionality to add chapters should work (ie follow the ID3 standard) or it should not be present in non-beta versions.

[Elon Musk]

Could you provide sample file with CTOC in id3v2.3 metadata?

[Gavin Smalley]

I can't provide the file here as the 2.5MB upload limit makes it impossible to upload any mp3 long enough for a demonstration of chapter functionality. I have instead made available a folder on Google Drive (​https://drive.google.com/drive/folders/1tkqpc0xeIrh1uwucn2tXAO1vx5o-ogEC?usp=sharing) containing:

• The original mp3 file (no chapter metadata)
• The desired metadata
• The ffmetadata file (generated based on the documentation referred to in the original report)
• The ffmpeg command and output
• The mp3 file post processing with ffmpeg (containing the CHAP frames but no CTOC
• An mp3 file containing also the CTOC frame, and
• The python file used to add that CTOC frame.

I hope this provides all the information required.

[Gavin Smalley]

Incidentally the full documentation describing the CHAP frames and the CTOC frame and there relationship can be found at ​http://id3.org/id3v2-chapters-1.0

[Gyan]

Furthermore the id3 standard requires CTOC to be added wherever CHAP frames are present.

Where's this requirement stated?

[Gavin Smalley]

​http://id3.org/id3v2-chapters-1.0

Section 4.2 states

"It is permitted to include "CHAP" frames that are not referenced by any "CTOC" frames. For example, these might be used to provide images that can be presented in synchronisation with the audio, rather than to support a table of contents."

The corollary of that statement is that all "normal" (non-special) CHAP frames ought to be included in at least one CTOC frame.

Excepting the special frames defined in that note, there is no point having chapters if there is no table of contents and the chapters are, therefore, not navigable.

[Gyan]

Then, it's not required, even if expected or good practice. The only declaration in your quote is the first sentence; the rest describes an example. I see nothing within the specs for CHAP frames that defines what makes a "special" CHAP tag, so it's upto the writer.

Anyway, a patch is in review. See ​https://patchwork.ffmpeg.org/patch/13412/

[Gavin Smalley]

It is, I agree, a matter of semantics - much of the document appears quite loosely written and several areas seem open to some degree of interpretation.

My reading of "It is permitted to..." was that this sentence introduced an "exception" and that, by extension, the opposite to the exception should be considered the "rule".

I apologise if I have made too much from those four words, it is not my intention to cause a problem just to find a reliable way of encoding chapters on the command line in a way that follows what most playback software seems to expect.

I will try and follow the review of the patch (I'm not sure I understand much of the code!)

Thank you all for all your help.

[Elon Musk]

Could you try latest master and report back?

[Gavin Smalley]

I cloned and compiled the latest master just now and repeated the test, you can see the output below:

$ ~/bin/ffmpeg -i original.mp3 -i ffmetadata.txt -map_metadata 1 -codec copy patched_result.mp3
ffmpeg version N-94033-g7c2c5c4940 Copyright (c) 2000-2019 the FFmpeg developers
  built with gcc 7 (Ubuntu 7.4.0-1ubuntu1~18.04)
  configuration: --prefix=/home/gavin/ffmpeg_build --pkg-config-flags=--static --extra-cflags=-I/home/gavin/ffmpeg_build/include --extra-ldflags=-L/home/gavin/ffmpeg_build/lib --extra-libs='-lpthread -lm' --bindir=/home/gavin/bin --enable-gpl --enable-libass --enable-libfreetype --enable-libmp3lame --enable-libvorbis --enable-nonfree
  libavutil      56. 28.100 / 56. 28.100
  libavcodec     58. 53.100 / 58. 53.100
  libavformat    58. 27.103 / 58. 27.103
  libavdevice    58.  7.100 / 58.  7.100
  libavfilter     7. 55.100 /  7. 55.100
  libswscale      5.  4.101 /  5.  4.101
  libswresample   3.  4.100 /  3.  4.100
  libpostproc    55.  4.100 / 55.  4.100
Input #0, mp3, from 'original.mp3':
  Metadata:
    title           : Edition 1767 23-05-2019
    artist          : Witney Talking News
    album           : WTN Editions
    track           : 1767
    genre           : Speech
    comment         : Edition 1767 23-05-2019
    date            : 2019
  Duration: 01:07:48.75, start: 0.025057, bitrate: 64 kb/s
    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 64 kb/s
Input #1, ffmetadata, from 'ffmetadata.txt':
  Metadata:
    title           : Edition 1767 23-05-2019
    artist          : Witney Talking News
    album           : WTN Editions
    year            : 2019
    comment         : Edition 1767 23-05-2019
    genre           : Speech
    genreno         : 101
    track           : 1767
  Duration: 01:07:50.03, start: 0.000000, bitrate: 0 kb/s
    Chapter #1:0: start 0.000000, end 23.092000
    Metadata:
      title           : Track - 001
    Chapter #1:1: start 23.092000, end 262.530000
    Metadata:
      title           : Track - 002
    Chapter #1:2: start 262.530000, end 510.902000
    Metadata:
      title           : Track - 003
    Chapter #1:3: start 510.902000, end 658.363000
    Metadata:
      title           : Track - 004
    Chapter #1:4: start 658.363000, end 837.511000
    Metadata:
      title           : Track - 005
    Chapter #1:5: start 837.511000, end 991.555000
    Metadata:
      title           : Track - 006
    Chapter #1:6: start 991.555000, end 1097.403000
    Metadata:
      title           : Track - 007
    Chapter #1:7: start 1097.403000, end 1231.829000
    Metadata:
      title           : Track - 008
    Chapter #1:8: start 1231.829000, end 1340.185000
    Metadata:
      title           : Track - 009
    Chapter #1:9: start 1340.185000, end 1443.734000
    Metadata:
      title           : Track - 010
    Chapter #1:10: start 1443.734000, end 1591.352000
    Metadata:
      title           : Track - 011
    Chapter #1:11: start 1591.352000, end 1736.776000
    Metadata:
      title           : Track - 012
    Chapter #1:12: start 1736.776000, end 1744.638000
    Metadata:
      title           : Track - 013
    Chapter #1:13: start 1744.638000, end 1939.773000
    Metadata:
      title           : Track - 014
    Chapter #1:14: start 1939.773000, end 2371.655000
    Metadata:
      title           : Track - 015
    Chapter #1:15: start 2371.655000, end 2385.291000
    Metadata:
      title           : Track - 016
    Chapter #1:16: start 2385.291000, end 2651.635000
    Metadata:
      title           : Track - 017
    Chapter #1:17: start 2651.635000, end 2872.788000
    Metadata:
      title           : Track - 018
    Chapter #1:18: start 2872.788000, end 3183.384000
    Metadata:
      title           : Track - 019
    Chapter #1:19: start 3183.384000, end 3234.453000
    Metadata:
      title           : Track - 020
    Chapter #1:20: start 3234.453000, end 3412.242000
    Metadata:
      title           : Track - 021
    Chapter #1:21: start 3412.242000, end 3515.740000
    Metadata:
      title           : Track - 022
    Chapter #1:22: start 3515.740000, end 3637.026000
    Metadata:
      title           : Track - 023
    Chapter #1:23: start 3637.026000, end 3826.048000
    Metadata:
      title           : Track - 024
    Chapter #1:24: start 3826.048000, end 3992.291000
    Metadata:
      title           : Track - 025
    Chapter #1:25: start 3992.291000, end 4070.031000
    Metadata:
      title           : Track - 026
Output #0, mp3, to 'patched_result.mp3':
  Metadata:
    TIT2            : Edition 1767 23-05-2019
    TPE1            : Witney Talking News
    TALB            : WTN Editions
    year            : 2019
    comment         : Edition 1767 23-05-2019
    TCON            : Speech
    genreno         : 101
    TRCK            : 1767
    TSSE            : Lavf58.27.103
    Chapter #0:0: start 0.000000, end 23.092000
    Metadata:
      TIT2            : Track - 001
    Chapter #0:1: start 23.092000, end 262.530000
    Metadata:
      TIT2            : Track - 002
    Chapter #0:2: start 262.530000, end 510.902000
    Metadata:
      TIT2            : Track - 003
    Chapter #0:3: start 510.902000, end 658.363000
    Metadata:
      TIT2            : Track - 004
    Chapter #0:4: start 658.363000, end 837.511000
    Metadata:
      TIT2            : Track - 005
    Chapter #0:5: start 837.511000, end 991.555000
    Metadata:
      TIT2            : Track - 006
    Chapter #0:6: start 991.555000, end 1097.403000
    Metadata:
      TIT2            : Track - 007
    Chapter #0:7: start 1097.403000, end 1231.829000
    Metadata:
      TIT2            : Track - 008
    Chapter #0:8: start 1231.829000, end 1340.185000
    Metadata:
      TIT2            : Track - 009
    Chapter #0:9: start 1340.185000, end 1443.734000
    Metadata:
      TIT2            : Track - 010
    Chapter #0:10: start 1443.734000, end 1591.352000
    Metadata:
      TIT2            : Track - 011
    Chapter #0:11: start 1591.352000, end 1736.776000
    Metadata:
      TIT2            : Track - 012
    Chapter #0:12: start 1736.776000, end 1744.638000
    Metadata:
      TIT2            : Track - 013
    Chapter #0:13: start 1744.638000, end 1939.773000
    Metadata:
      TIT2            : Track - 014
    Chapter #0:14: start 1939.773000, end 2371.655000
    Metadata:
      TIT2            : Track - 015
    Chapter #0:15: start 2371.655000, end 2385.291000
    Metadata:
      TIT2            : Track - 016
    Chapter #0:16: start 2385.291000, end 2651.635000
    Metadata:
      TIT2            : Track - 017
    Chapter #0:17: start 2651.635000, end 2872.788000
    Metadata:
      TIT2            : Track - 018
    Chapter #0:18: start 2872.788000, end 3183.384000
    Metadata:
      TIT2            : Track - 019
    Chapter #0:19: start 3183.384000, end 3234.453000
    Metadata:
      TIT2            : Track - 020
    Chapter #0:20: start 3234.453000, end 3412.242000
    Metadata:
      TIT2            : Track - 021
    Chapter #0:21: start 3412.242000, end 3515.740000
    Metadata:
      TIT2            : Track - 022
    Chapter #0:22: start 3515.740000, end 3637.026000
    Metadata:
      TIT2            : Track - 023
    Chapter #0:23: start 3637.026000, end 3826.048000
    Metadata:
      TIT2            : Track - 024
    Chapter #0:24: start 3826.048000, end 3992.291000
    Metadata:
      TIT2            : Track - 025
    Chapter #0:25: start 3992.291000, end 4070.031000
    Metadata:
      TIT2            : Track - 026
    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 64 kb/s
Stream mapping:
  Stream #0:0 -> #0:0 (copy)
Press [q] to stop, [?] for help
size=   31789kB time=01:07:48.70 bitrate=  64.0kbits/s speed=2.67e+03x    
video:0kB audio:31787kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 0.006129%

However when I examine the metadata using PHP/getID3 I see the following error:

CTOS subframe "ch3" at frame offset 29 claims to be "1667773440" bytes, which is more than the available data (98 bytes)
Invalid ID3v2 padding found at offset 1777 (the remaining 23 bytes are considered invalid)
Unknown data before synch (ID3v2 header ends at 1800, then 195 bytes garbage, synch detected at 1995)

and the CTOC frame looks like this:

      ["CTOC"]=>
      array(1) {
        [0]=>
        array(11) {
          ["frame_name"]=>
          string(4) "CTOC"
          ["frame_flags_raw"]=>
          int(0)
          ["data"]=>
          string(127) "tocch0ch1ch2ch3ch4ch5ch6ch7ch8ch9ch10ch11ch12ch13ch14ch15ch16ch17ch18ch19ch20ch21ch22ch23ch24ch25"
          ["datalength"]=>
          int(127)
          ["dataoffset"]=>
          int(246)
          ["flags"]=>
          array(8) {
            ["TagAlterPreservation"]=>
            bool(false)
            ["FileAlterPreservation"]=>
            bool(false)
            ["ReadOnly"]=>
            bool(false)
            ["GroupingIdentity"]=>
            bool(false)
            ["compression"]=>
            bool(false)
            ["Encryption"]=>
            bool(false)
            ["Unsynchronisation"]=>
            bool(false)
            ["DataLengthIndicator"]=>
            bool(false)
          }
          ["element_id"]=>
          string(3) "toc"
          ["entry_count"]=>
          int(3)
          ["child_element_ids"]=>
          array(3) {
            [0]=>
            string(4) "ch0"
            [1]=>
            string(3) "ch1"
            [2]=>
            string(3) "ch2"
          }
          ["ctoc_flags"]=>
          array(2) {
            ["ordered"]=>
            bool(false)
            ["top_level"]=>
            bool(false)
          }
          ["subframes"]=>
          array(0) {
          }
        }
      }

As you can see the array cuts off just before "ch3" indicating that the data there is corrupt.

I have uploaded the output mp3 (as "patched_result.mp3") to the same publicly readable Google Drive folder I linked at the start of this bug (​https://drive.google.com/drive/folders/1tkqpc0xeIrh1uwucn2tXAO1vx5o-ogEC)

I hope this means more to you than to me...

Thank you again for your help so far.

[Gavin Smalley]

Further to the above, I believe if only 1 TOC is being specified that the "ctoc_flags" "ordered" and "top_level" should be set to "true".

[Elon Musk]

Could you retry with latest master?

[Elon Musk]

Feel free to reopen if it does not work.

[Gavin Smalley]

Thank you very much for your hard work here. Apologies I was not able to reply over the weekend, I have re-compiled this morning and it does now appear to create the correct metadata.

However I still get the following error when parsing that metadata:

"Invalid ID3v2 padding found at offset 1776 (the remaining 24 bytes are considered invalid) Unknown data before synch (ID3v2 header ends at 1800, then 194 bytes garbage, synch detected at 1994)"

I don't know if that is serious or not, the file still plays OK but I'm not sure if it may cause others a problem so I have re-opened. If it is an expected warning, please do feel free to re-close.

For analysis, if required, I have added the file "patched_result2.mp3" to the same Google Drive folder as referenced above.

[Elon Musk]

I think this have been resolved by 929e5159bc13da374b83f5627879c607acce180b.

Feel free to reopen this report if that is not true.