chapters

This is the core library of the chaptertool project and provides the functionality to handle the formats below.

Click here to open the web GUI or go install chaptertool locally for CLI use.

Supported formats

class	description	key	ext	info
ChaptersJson	Podcasting 2.0 Chapters	chaptersjson	json	spec
FFMetadata	FFMetadata	ffmpegdata	txt	spec
MatroskaXML	Matroska XML chapters	matroskaxml	xml	spec
MKVMergeXML	MKVToolNix mkvmerge XML	mkvmergexml	xml	spec
MKVMergeSimple	MKVToolNix mkvmerge simple	mkvmergesimple	txt	spec
WebVTT	WebVTT Chapters	webvtt	vtt	spec
Youtube	Youtube Chapter Syntax	youtube	txt
FFMpegInfo	FFMpegInfo	ffmpeginfo	txt	read only, used internally
PySceneDetect	PySceneDetect	pyscenedetect	csv	project home
VorbisComment	Vorbis Comment Format	vorbiscomment	txt	spec
AppleChapters	"Apple Chapters"	applechapters	xml	source
ShutterEDL	Shutter EDL	edl	edl	source
PodloveSimpleChapters	Podlove Simple Chapters	psc	xml	spec
PodloveJson	Podlove Simple Chapters JSON	podlovejson	json	source
MP4Chaps	MP4Chaps	mp4chaps	txt	source
AppleHLS	Apple HLS Chapters	applehls	json	spec, partial support
Scenecut	Scenecut format	scenecut	json	source

Installation

npm i @mtillmann/chapters

Usage

import { ChaptersJson } from '@mtillmann/chapters';

const chapters = new ChaptersJson()
chapters.add({ startTime: 0, title: 'Intro' })
chapters.add({ startTime: 30, title: 'Some Topic' })
const json = chapters.toString()

Autoformat

Autoformat is a helper that can be used to automatically detect the format of a given input and return the corresponding class, key or a new instance of the detected class. It also provides a method to convert the input to a specific format.

import { Autoformat } from '@mtillmann/chapters'
import { WebVTT } from '@mtillmann/chapters'

const content = '<podcasting 2.0 chapters.json>...'
const instance = Autoformat.detect(content) // returns an instance of ChaptersJson
const instance2 = Autoformat.from(content) // returns an instance of ChaptersJson

const key = Autoformat.detect(content, 'key') // returns 'chaptersjson'
const className = Autoformat.detect(content, 'class') // returns ChaptersJson

const webVttString = 'WEBVTT...';

const autodetectedWebVtt = Autoformat.detect(webVttString) // returns an instance of WebVTT

const fail = Autoformat.as('chaptersjson', webVttString) // throws an error

const vtt = Autoformat.as('webvtt', webVttString) // returns an instance of WebVTT
const vtt2 = Autoformat.as(WebVTT, webVttString) // returns an instance of WebVTT

API

All formats support the following methods:

constructor (duration: number = 3600)

Creates a new instance of the class, optionally with a duration in seconds.

const chapters = (new ChaptersJson(3600)).from(input)

the constructor will not accept any input due to javascript's order of initialization which prevents the parse method from having access to cerain locally defined properties and methods.

static create (input?: string | MediaItem): MediaItem

Creates a new media item. This is the suggested way to create a media item from a string:

const chapters = MatroskaXML.create(input)
// chapters is now an instance of MatroskaXML

const chapterString = WebVTT.create(chapters).toString()
// chapterString is now a string representation of the chapters

from (input?: string | MediaItem): MediaItem

Populates the media item's chapters from the given input.

to (className: any): MediaItem

Converts the media item to another format.

add (chapter: Chapter): void

Adds a chapter.

addChapterAt (index: number, chapter: object = {}): number

Adds a chapter at the given index.

addChapterAtTime (time: number | string, chapter: object = {}): boolean

Adds a chapter at the given time.

remove (index: number): void

Removes the chapter at the given index.

bump (keepDuration: boolean = false): void

Updates the chapters and duration. Called automatically after adding or removing chapters.

endTime (index: number): number

Returns the end time for the chapter at the given index.

expandFirstToStart (): void

Expands the first chapter to start at 0.

applyChapterMinLength (seconds: number): object

Applies a minimum length to the chapters.

chapterExistsAtStartTime (time: number): boolean

Checks if a chapter exists at the given start time.

updateChapterStartTime (index: number, startTime: number | string): number | 'timeInUse'

Updates the start time for the chapter at the given index.

chapterIndexFromStartTime (startTime: number | string): number

Returns the index of the chapter with the given start time.

chapterIndexFromTime (time: number | string): null | number

Returns the index of the chapter at the given time.

toString([pretty: boolean][, options: object]): string

Convert the chapters to a string.
If pretty is true, the output will be formatted for better readability. Only supported by json and xml formats. Some formats support additional options:

ChapterJson toString() options

option	type	default	description
imagePrefix	string	''	Prefix for image URLs
writeRedundantToc	boolean	false	Write redundant TOC attributes
writeEndTimes	boolean	false	Write end times

AppleChapters toString() options

option	type	default	description
acUseTextAttr	boolean	false	When set, the text-attribute will be used instead of node textContent

PySceneDetect toString() options

option	type	default	description
psdFramerate	number	23.976	Framerate of the video file
psdOmitTimecodes	boolen	false	When set, the first line will be omitted

Scenecut toString() options

option	type	default	description
frameRate	number	30	Framerate of the video file
ptsScale	number	1	PTS scale (See below)
score	number	0.5	Score threshold

When asked about the ptsScale-value, ChatGPT said:

The number "1001" in the context of video processing and multimedia, especially in relation to frame rates and timecodes, is often associated with the NTSC color system used in North America and Japan. In this system, the frame rate is often described as "29.97 frames per second", but it's technically 30000/1001 frames per second, which is approximately 29.97 but not exactly. This is known as a "drop frame" rate, and the "1001" comes from this fractional frame rate.

When you use 1 the output pts will be the same as the frame number. When you use 1001 the output pts will be the same as the frame number multiplied by 1001.