search

enzo1982 / mp4v2

Reviving the MP4v2 project...
https://mp4v2.org
Other
140 stars 52 forks source link

Support informational comment tags in mp4v2 chapters.txt format #3

Closed sandreas closed 2 years ago

sandreas commented 2 years ago

I did not find a specification for the chapters.txt format, mp4v2 generates and makes use of.

One problem with the chapters.txt format is, that there is no hint for the total duration of a file, because it contains only the start of a chapter, not the duration or ending. Example:

00:00:00.000 chapter 1
00:00:00.500 chapter 2
00:00:01.000 chapter 3

The file could have a total duration 1.5 seconds but also 3.5 seconds or even 1 hour. While comments in the file are already ignored, I tried to use these to support this feature. 

# total-length 00:00:01.500
00:00:00.000 chapter 1
00:00:00.500 chapter 2
00:00:01.000 chapter 3

It would be also possible, to mark these special comments with an extra # and a key-value-pair separated by =

## total-duration=00:00:01.500
00:00:00.000 chapter 1
00:00:00.500 chapter 2
00:00:01.000 chapter 3

Maybe a more specified approach would be better, what do you think?

enzo1982 commented 2 years ago

I agree that that the generated chapters.txt should include the total duration. I like the special comment form:

## total-duration=00:00:01.500

There should also be some general title information included in chapters.txt. Things like album artist and title. Probably in the same special comment form.

Feel free to open a pull-request for this. Otherwise I will probably add this myself in a few days.

enzo1982 commented 2 years ago

I have committed a change in the new mp4chaps branch to include metadata at the top of chapter.txt files. Here's an example output:

## artist: Cœur de pirate
## album: Blonde
##
## total-duration: 00:38:37.034
##
00:00:00.000 Lève les voiles
00:01:12.709 Adieu
00:03:40.346 Danse et danse
00:06:50.775 Golden Baby
00:09:57.772 Ava
00:13:14.657 Loin d'ici
00:15:58.494 Les amours dévouées
00:18:26.443 Place de la république
00:22:37.664 Cap diamant
00:25:20.925 Verseau
00:29:14.722 Saint-Laurent
00:32:29.519 La petite mort
00:36:19.140 Hôtel amour

Please take a look. If you agree with the change, I will merge it to the main branch before the 2.1.0 release.

sandreas commented 2 years ago

Please take a look. If you agree with the change, I will merge it to the main branch before the 2.1.0 release.

Cool. Looks good to me, some questions I came up with:

Here is a fast and small draft of a spec like chapter for the README.md:


# CHPT_FMT_NATIVE specification

A file in the `CHPT_FMT_NATIVE` format contains chapter information and

- SHOULD be stored in the form of `<audio-filename>.chapters.txt`, e.g. `an-example.chapters.txt` for `an-example.m4a`
- MUST use the *default time format* `HH:MM:SS.fff` for time declarations (e.g. `00:13:14.657`)
- MUST contain at least one *chapter item* (see below)

Items in `CHPT_FMT_NATIVE` can have three different purposes:

  1. chapter items (with start time and title)
  2. metadata items (starting with `##` - a special form of comments containing metadata)
  3. comments (starting with `#`)

## Chapter items

Chapter items are MANDATORY defined in the following format:
``` whereas - `<start time>` is the start time of a chapter specificed in the *default time format* - followed by ONE ` ` (space) - `<title>` contains printable UTF-8 chars without line breaks ## Metadata items Metadata items are OPTIONAL can be used to embed additional information and are defined in the following format: ``` ## <key>: <value> ``` whereas Metadata comments - MUST start with `## ` - `<key>` MUST be one of the following values and SHOULD use the dasherized syntax (all lowercase, uses hyphens as word separators): - `artist` - for artist as string - `album` - for album as string - `total-duration` - the estimated total duration of the file in *the default time format* - followed by ONE `:` (colon) - `<value>` contains UTF-8 chars without line breaks ## Comments Comments are OPTIONAL, may contain any additional texutal information to enrich the content and are defined in the following format: ``` # <additional information> ``` whereas comments - MUST start with `#` - SHOULD NOT start with `##` to prevent being mixed up with *metadata comments* ```` Notes: - This is a quick 30 minute spec... you should definetely revise that before putting it into production - As you see, the start time is limited to a max value of `99:59:59.999`, if `HH:MM:SS.fff` is used - maybe it is easier to leave the first position open to more than 2 places - Line-Breaks are not supported, which is good in my opinion - More *metadata items* could be specified later, but for now I would do ONLY the most necessary ones (since it is a time specification format, I'm not sure, if `album` and `artist` are important enough, but I leave this up to you) </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/enzo1982"><img src="https://avatars.githubusercontent.com/u/7796713?v=4" />enzo1982</a> commented <strong> 2 years ago</strong> </div> <div class="markdown-body"> <p>Good idea to add a format specification! But Readme.md is not the right place for it. I've made a few minor changes to the specification, converted it to .texi format and included it in the tool guide (doc/ToolGuide.txt ist generated by <code>make dist</code>; here is what is currently generated from the mp4chaps branch: <a href="https://github.com/enzo1982/mp4v2/files/8103210/ToolGuide.txt">ToolGuide.txt</a>).</p> <p>I've also separated <code>artist</code> and <code>album-artist</code> in the latest update. Thanks for that hint as well!</p> <p>I think the artist and album/title information is important for humans rather than from a technical point of view. I'd like to see at a glance which album/work the chapters apply to when I look at the chapters.txt file. That's why included those fields.</p> <p>Regarding possible 99 hour limitation, the tools already support more than 2 digits for the hours field. I've added a note to the format description to indicate that more than 2 digits are alright if necessary.</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/sandreas"><img src="https://avatars.githubusercontent.com/u/2050604?v=4" />sandreas</a> commented <strong> 2 years ago</strong> </div> <div class="markdown-body"> <p>Awesome, thank you for your work. Nothing to add here. A little typo in <code>A.1.3 Comments</code>: <code>additional texutal information</code> => <code>additional textual information</code> Is there anything left? Otherwise this ticket can be closed</p> </div> </div> <div class="comment"> <div class="user"> <a rel="noreferrer nofollow" target="_blank" href="https://github.com/enzo1982"><img src="https://avatars.githubusercontent.com/u/7796713?v=4" />enzo1982</a> commented <strong> 2 years ago</strong> </div> <div class="markdown-body"> <p>Great! Thanks for taking a look so quickly!</p> <p>Fixed the typo, merged the mp4chaps branch and closing this ticket.</p> </div> </div> <div class="page-bar-simple"> </div> <div class="footer"> <ul class="body"> <li>© <script> document.write(new Date().getFullYear()) </script> Githubissues.</li> <li>Githubissues is a development platform for aggregating issues.</li> </ul> </div> <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.min.js"></script> <script src="/githubissues/assets/js.js"></script> <script src="/githubissues/assets/markdown.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/highlight.min.js"></script> <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.4.0/build/languages/go.min.js"></script> <script> hljs.highlightAll(); </script> </body> </html>