{"id":17036260,"url":"https://github.com/mtillmann/chapters","last_synced_at":"2025-10-10T12:31:18.725Z","repository":{"id":226674214,"uuid":"769352999","full_name":"Mtillmann/chapters","owner":"Mtillmann","description":"Create, manage and convert chapters between 20+ chapter formats","archived":false,"fork":false,"pushed_at":"2025-04-11T12:32:42.000Z","size":312,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-20T14:25:53.226Z","etag":null,"topics":["apple-chapters","chapters","edl","ffmpeg","hls","library","matroska","mkvmerge","mkvtoolnix","podcast","podigee","podlove","pyscenedetect","scenecut","spotify","transistorfm","video","vorbis-comment","webvtt","youtube"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mtillmann.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-08T21:47:11.000Z","updated_at":"2025-04-18T01:38:53.000Z","dependencies_parsed_at":"2024-03-08T23:25:21.992Z","dependency_job_id":"9ea6f480-af15-43f3-ac49-e34668bd2d8c","html_url":"https://github.com/Mtillmann/chapters","commit_stats":null,"previous_names":["mtillmann/chapters"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Mtillmann/chapters","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mtillmann%2Fchapters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mtillmann%2Fchapters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mtillmann%2Fchapters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mtillmann%2Fchapters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mtillmann","download_url":"https://codeload.github.com/Mtillmann/chapters/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mtillmann%2Fchapters/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003901,"owners_count":26083641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple-chapters","chapters","edl","ffmpeg","hls","library","matroska","mkvmerge","mkvtoolnix","podcast","podigee","podlove","pyscenedetect","scenecut","spotify","transistorfm","video","vorbis-comment","webvtt","youtube"],"created_at":"2024-10-14T08:49:53.413Z","updated_at":"2025-10-10T12:31:18.720Z","avatar_url":"https://github.com/Mtillmann.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![tests](https://github.com/Mtillmann/chapters/actions/workflows/tests.yaml/badge.svg?event=push)\n\n[![npm version](https://badge.fury.io/js/@mtillmann%2Fchapters.svg)](https://badge.fury.io/js/@mtillmann%2Fchapters)\n\n# chapters\n\nThis is the core library of [chaptertool](https://github.com/Mtillmann/chaptertool) and [chapconv](https://github.com/Mtillmann/chapconv/) and provides the functionality to handle the formats below.  \n\n[Click here to open the chaptertool web GUI](https://mtillmann.github.io/chaptertool).\n\n## Supported formats\n\n| class                 | description                  | key            | ext    | info                                                                                                                                                               |\n| --------------------- | ---------------------------- | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| ChaptersJson          | Podcasting 2.0 Chapters      | chaptersjson   | `json` | [spec](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md)                                                                   |\n| FFMetadata            | FFMetadata                   | ffmpegdata     | `txt`  | [spec](https://ffmpeg.org/ffmpeg-formats.html#Metadata-1)                                                                                                          |\n| MatroskaXML           | Matroska XML chapters        | matroskaxml    | `xml`  | [spec](https://www.matroska.org/technical/chapters.html)                                                                                                           |\n| MKVMergeXML           | MKVToolNix mkvmerge XML      | mkvmergexml    | `xml`  | [spec](https://mkvtoolnix.download/doc/mkvmerge.html#mkvmerge.chapters)                                                                                            |\n| MKVMergeSimple        | MKVToolNix mkvmerge _simple_ | mkvmergesimple | `txt`  | [spec](https://mkvtoolnix.download/doc/mkvmerge.html#mkvmerge.chapters)                                                                                            |\n| WebVTT                | WebVTT Chapters              | webvtt         | `vtt`  | [spec](https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API)                                                                                                |\n| Youtube               | Youtube Chapter Syntax       | youtube        | `txt`  |                                                                                                                                                                    |\n| FFMpegInfo            | FFMpegInfo                   | ffmpeginfo     | `txt`  | read only, used internally                                                                                                                                         |\n| PySceneDetect         | PySceneDetect                | pyscenedetect  | `csv`  | [project home](https://github.com/Breakthrough/PySceneDetect)                                                                                                      |\n| VorbisComment         | Vorbis Comment Format        | vorbiscomment  | `txt`  | [spec](https://wiki.xiph.org/Chapter_Extension)                                                                                                                    |\n| AppleChapters         | \"Apple Chapters\"             | applechapters  | `xml`  | [source](https://github.com/rigaya/NVEnc/blob/master/NVEncC_Options.en.md#--chapter-string:~:text=CHAPTER03NAME%3Dchapter%2D3-,apple%20format,-(should%20be%20in)) |\n| ShutterEDL            | Shutter EDL                  | edl            | `edl`  | [source](https://github.com/paulpacifico/shutter-encoder/blob/f3d6bb6dfcd629861a0b0a50113bf4b062e1ba17/src/application/SceneDetection.java)                        |\n| Podigee | Podigee Chapters/Chaptermarks | podigee | `json` | [spec](https://app.podigee.com/api-docs#!/ChapterMarks/updateChapterMark:~:text=Model-,Example%20Value,-%7B%0A%20%20%22title%22%3A%20%22string%22%2C%0A%20%20%22start_time)                                                                                                                        | \n| PodloveSimpleChapters | Podlove Simple Chapters      | psc            | `xml`  | [spec](https://podlove.org/simple-chapters/)                                                                                                                       |\n| PodloveJson           | Podlove Simple Chapters JSON | podlovejson    | `json` | [source](https://github.com/podlove/chapters#:~:text=org/%3E-,Encode%20to%20JSON,-iex%3E%20Chapters)                                                               |\n| MP4Chaps              | MP4Chaps                     | mp4chaps       | `txt`  | [source](https://github.com/podlove/chapters#:~:text=%3Achapters%3E-,Encode%20to%20mp4chaps,-iex%3E%20Chapters)                                                    |\n| AppleHLS              | Apple HLS Chapters           | applehls       | `json` | [spec](https://developer.apple.com/documentation/http-live-streaming/providing-javascript-object-notation-json-chapters), partial support                          |\n| Scenecut              | Scenecut format              | scenecut       | `json` | [source](https://github.com/slhck/scenecut-extractor#:~:text=cuts%20in%20JSON-,format,-%3A)                                                                        |\n| Audible               | Audible Chapter Format         | audible        | `json` | [source](./audible-chapter-spec.md)                                                                                                                               |\n| Spotify | Spotify Formats A/B | spotifya\\|spotifyb | `txt` | [see](misc-text-chapter-spec.md) |\n| Podcastpage | Podcastpage Format | podcastpage | `txt` | [see](misc-text-chapter-spec.md) |\n| Podigee Text | Podigee Text Format | podigeetext | `txt` | [see](misc-text-chapter-spec.md) |\n| TransistorFM | TransistorFM Chapter Format | transistorfm | `txt` | [see](misc-text-chapter-spec.md) |\n| \"Show Notes Chapters\" | Unknown Shownotes Format | shownotes | `txt` | [see](misc-text-chapter-spec.md) |\n\n## Installation\n\n`npm i @mtillmann/chapters`\n\n## Usage\n\n```javascript\nimport { ChaptersJson } from '@mtillmann/chapters';\n\nconst chapters = new ChaptersJson()\nchapters.add({ startTime: 0, title: 'Intro' })\nchapters.add({ startTime: 30, title: 'Some Topic' })\nconst json = chapters.toString()\n```\n\n## Autoformat\n\n`Autoformat` is a helper that can be used to automatically detect the format of a given input and return the corresponding class,\nkey or a new instance of the detected class. It also provides a method to convert the input to a specific format.\n\n```javascript\nimport { Autoformat } from '@mtillmann/chapters'\nimport { WebVTT } from '@mtillmann/chapters'\n\nconst content = '\u003cpodcasting 2.0 chapters.json\u003e...'\nconst instance = Autoformat.detect(content) // returns an instance of ChaptersJson\nconst instance2 = Autoformat.from(content) // returns an instance of ChaptersJson\n\nconst key = Autoformat.detect(content, 'key') // returns 'chaptersjson'\nconst className = Autoformat.detect(content, 'class') // returns ChaptersJson\n\nconst webVttString = 'WEBVTT...';\n\nconst autodetectedWebVtt = Autoformat.detect(webVttString) // returns an instance of WebVTT\n\nconst fail = Autoformat.as('chaptersjson', webVttString) // throws an error\n\nconst vtt = Autoformat.as('webvtt', webVttString) // returns an instance of WebVTT\nconst vtt2 = Autoformat.as(WebVTT, webVttString) // returns an instance of WebVTT\n```\n\n## API\n\nAll formats support the following methods:\n\n### `constructor (duration: number = 3600)`\n\nCreates a new instance of the class, optionally with a duration in seconds.\n\n```javascript\nconst chapters = (new ChaptersJson(3600)).from(input)\n```\n\n\u003e the constructor will not accept any input due to javascript's order of initialization which prevents the parse method\n\u003e from having access to certain locally defined properties and methods.\n\n### `static create (input?: string | MediaItem): MediaItem`\n\nCreates a new media item. This is the suggested way to create a media item from a string:\n\n```javascript\nconst chapters = MatroskaXML.create(input)\n// chapters is now an instance of MatroskaXML\n\nconst chapterString = WebVTT.create(chapters).toString()\n// chapterString is now a WebVTT string representation of the chapters\n```\n\n### `from (input?: string | MediaItem): MediaItem`\n\nPopulates the media item's chapters from the given input.\n\n### `to (className: any): MediaItem`\n\nConverts the media item to another format.\n\n### `add (chapter: Chapter): void`\n\nAdds a chapter.\n\n### `addChapterAt (index: number, chapter: Partial\u003cChapter\u003e = {}): number`\n\nAdds a chapter at the given index.\n\n### `addChapterAtTime (time: number | string, chapter: Partial\u003cChapter\u003e = {}): boolean`\n\nAdds a chapter at the given time.\n\n### `remove (index: number): void`\n\nRemoves the chapter at the given index.\n\n### `bump (keepDuration: boolean = false): void`\n\nUpdates the chapters and duration. Called automatically after adding or removing chapters.\n\n### `endTime (index: number): number`\n\nReturns the end time for the chapter at the given index.\n\n### `expandFirstToStart (): void`\n\nExpands the first chapter to start at 0.\n\n### `applyChapterMinLength (seconds: number): object`\n\nApplies a minimum length to the chapters.\n\n### `chapterExistsAtStartTime (time: number): boolean`\n\nChecks if a chapter exists at the given start time.\n\n### `updateChapterStartTime (index: number, startTime: number | string): number | 'timeInUse'`\n\nUpdates the start time for the chapter at the given index.\n\n### `chapterIndexFromStartTime (startTime: number | string): number`\n\nReturns the index of the chapter with the given start time.\n\n### `chapterIndexFromTime (time: number | string): null | number`\n\nReturns the index of the chapter at the given time.\n\n### `toString([pretty: boolean][, options: object]): string`\n\nConvert the chapters to a string.  \nIf `pretty` is `true`, the output will be formatted for better readability. Only supported by `json` and `xml` formats.\nSome formats support additional options:\n\n#### ChapterJson toString() options\n\n| option              | type      | default | description                                                                                                                                                      |\n| ------------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `imagePrefix`       | `string`  | `''`    | Prefix for image URLs                                                                                                                                            |\n| `writeRedundantToc` | `boolean` | `false` | Write [redundant](https://github.com/Podcastindex-org/podcast-namespace/blob/main/chapters/jsonChapters.md#:~:text=or%20not%20present%20at%20all) TOC attributes |\n| `writeEndTimes`     | `boolean` | `false` | Write end times                                                                                                                                                  |\n\n#### AppleChapters toString() options\n\n| option          | type      | default | description                                                            |\n| --------------- | --------- | ------- | ---------------------------------------------------------------------- |\n| `acUseTextAttr` | `boolean` | `false` | When set, the text-attribute will be used instead of node  textContent |\n\n#### PySceneDetect toString() options\n\n| option             | type     | default  | description                              |\n| ------------------ | -------- | -------- | ---------------------------------------- |\n| `psdFramerate`     | `number` | `23.976` | Framerate of the video file              |\n| `psdOmitTimecodes` | `boolen` | `false`  | When set, the first line will be omitted |\n\n#### Scenecut toString() options\n\n| option      | type     | default | description                 |\n| ----------- | -------- | ------- | --------------------------- |\n| `frameRate` | `number` | `30`    | Framerate of the video file |\n| `ptsScale`  | `number` | `1`     | PTS scale (See below)       |\n| `score`     | `number` | `0.5`   | Score threshold             |\n\nWhen asked about the `ptsScale`-value, ChatGPT said:\n\u003e 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.\n\u003e 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.\n\nWhen 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`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtillmann%2Fchapters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtillmann%2Fchapters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtillmann%2Fchapters/lists"}