toc2audio 0.2.0

Add Table of Contents and chapters to audio files

Warning

WORK IN PROGRESS.

The content of this documentation does NOT reflect current state of the tool.

This tool parses a Table of Contents file and:

• Optionally, shows HTML in your browser.

• TODO: Optionally, adds the TOC generated HTML to an audio file.

• Optionally, adds timestamps (chapters) from your TOC file to an audio file.

• TODO: Optionally, adds timeoffsets to all timestamps (in the HTML and in the chapters) in order to compensate from initial presentation or teasers, advertisement during the audio, etc.

If the audio file already have chapter/TOC metadata, we will replace it as requested.

Table of Contents format

The Table of Contents must be written in markdown.

toc2audio will parse any markdown file and will, optionally, insert the generated HTML and chapters metadata in your audio file. If you want to use timestamps (chapters), you must use lines in this format:

[HH:MM:SS] Chapter title

HH:MM:SS is hours:minutes:seconds. The “hours” field is optional. You can specify fields with one or two digits.

The first line of the markdown file will be the title of the table of contents stored in the audio file if you store chapters information in it. If that first line is a markdown header line, the markdown header tags will be dropped in the (optionally) stored TOC title.

An example would be:

# First line will be the title of the TOC (header marks removed)

* [00:50] Presentation

    Here I describe the topics we will talk about.

* [02:11] Topic 1

    Blah blah blah blah...

* [17:29] Topic 2

    Blah blah blah blah...

Note

Notice that when list items have multiple paragraphs, each subsequent paragrap MUST BE indented by either FOUR spaces or a tab, as documented in Markdown Sytax Documentation and in the documentation of Python-Markdown project.

Time offsets

Warning

WORK IN PROGRESS. No available at this time.

You can add timeoffsets to apply to your Table of Contents file, with this format:

HH:MM:SS -> HH:MM:SS

Hours is optional.

The line indicates that after that timestamp, all times should be offset to the new timestamp. You can define several offsets. All origin timestamps references to the original Table of Contents.

Supported audio containers

Supported audio containers are:

• Opus.

• Vorbis.

• MP3.

  Warning

  In many MP3 players, the MP3 file MUST BE CBR in order for the chapter metadata seeking to be accurate.

• M4A (MP4 audio).

  Usually, MP4 audiobooks have a m4b extension to advertise the presence of bookmarks. Nevertheless, the file is bitwise identical to m4a. Some software doesn’t recognize m4b files, so I use a m4a suffix.

  Usually, the audio format will be AAC, HE-AAC or HE-AACv2, but I don’t really care. I manipulate the generic MP4 container, I don’t pay attention to the audio data. I guess I could even add chapters to video data.

  Warning

  This feature requires availability of FFmpeg software.

Author and License

The author of this package is Jesús Cea Avión.

• email: [e-mail].

• Webpage: https://www.jcea.es/.

• Blog: https://blog.jcea.es/.

• Twitter: @jcea.

This code is licensed under Affero GNU Public License v3 (AGPLv3)