feat: add Podigee format support with corresponding tests

Author: Mtillmann

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mtillmann/chapters",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "library that manages and converts chapters of multiple formats",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,7 +34,8 @@
     "podcast-chapters",
     "edl",
     "hls",
-    "scenecut"
+    "scenecut",
+    "podigee"
   ],
   "license": "MIT",
   "devDependencies": {

readme.md

@@ -24,6 +24,7 @@ This is the core library of the [chaptertool](https://github.com/Mtillmann/chapt
 | VorbisComment         | Vorbis Comment Format        | vorbiscomment  | `txt`  | [spec](https://wiki.xiph.org/Chapter_Extension)                                                                                                                    |
 | 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)) |
 | ShutterEDL            | Shutter EDL                  | edl            | `edl`  | [source](https://github.com/paulpacifico/shutter-encoder/blob/f3d6bb6dfcd629861a0b0a50113bf4b062e1ba17/src/application/SceneDetection.java)                        |
+| 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)                                                                                                                        | 
 | PodloveSimpleChapters | Podlove Simple Chapters      | psc            | `xml`  | [spec](https://podlove.org/simple-chapters/)                                                                                                                       |
 | PodloveJson           | Podlove Simple Chapters JSON | podlovejson    | `json` | [source](https://github.com/podlove/chapters#:~:text=org/%3E-,Encode%20to%20JSON,-iex%3E%20Chapters)                                                               |
 | MP4Chaps              | MP4Chaps                     | mp4chaps       | `txt`  | [source](https://github.com/podlove/chapters#:~:text=%3Achapters%3E-,Encode%20to%20mp4chaps,-iex%3E%20Chapters)                                                    |

src/Formats/AutoFormat.ts

@@ -16,6 +16,7 @@ import { PodloveJson } from './PodloveJson'
 import { AppleHLS } from './AppleHLS'
 import { Scenecut } from './Scenecut'
 import { Audible } from './Audible'
+import { Podigee } from './Podigee'
 import { type MediaItem } from '../Types/MediaItem'
 
 const classMap: Record<string, any> = {
@@ -36,7 +37,8 @@ const classMap: Record<string, any> = {
   podlovejson: PodloveJson,
   applehls: AppleHLS,
   scenecut: Scenecut,
-  audible: Audible
+  audible: Audible,
+  podigee: Podigee
 }
 
 export const AutoFormat = {

src/Formats/Podigee.ts

@@ -0,0 +1,64 @@
+import { type Chapter } from '../Types/Chapter'
+import { secondsToTimestamp, timestampToSeconds } from '../util'
+import { Base } from './Base'
+
+export class Podigee extends Base {
+  supportsPrettyPrint = true
+
+  test (data: object[]): { errors: string[] } {
+    if (!Array.isArray(data)) {
+      return { errors: ['JSON Structure: must be an array'] }
+    }
+
+    if (data.length === 0) {
+      return { errors: ['JSON Structure: must not be empty'] }
+    }
+
+    if (!data.every(chapter => 'start_time' in chapter && 'title' in chapter)) {
+      return { errors: ['JSON Structure: every chapter must have a start_time and title property'] }
+    }
+
+    return { errors: [] }
+  }
+
+  parse (string: string): void {
+    const data = JSON.parse(string)
+    const { errors } = this.test(data as object[])
+    if (errors.length > 0) {
+      throw new Error(errors.join(''))
+    }
+
+    this.chapters = data.map((raw: Record<string, any>) => {
+      const { start_time: start, title, image, url } = raw
+      const chapter: Chapter = {
+        startTime: timestampToSeconds(start as string)
+      }
+      if (title) {
+        chapter.title = title
+      }
+      if (image) {
+        chapter.img = image
+      }
+      if (url) {
+        chapter.url = url
+      }
+      return chapter
+    })
+  }
+
+  toString (pretty = false): string {
+    return JSON.stringify(this.chapters.map((chapter, i) => {
+      const output: Record<string, any> = {
+        start_time: secondsToTimestamp(chapter.startTime),
+        title: this.ensureTitle(i)
+      }
+      if (chapter.img) {
+        output.image = chapter.img
+      }
+      if (chapter.url) {
+        output.url = chapter.url
+      }
+      return output
+    }), null, pretty ? 2 : 0)
+  }
+}

tests/conversions.test.ts

@@ -15,14 +15,15 @@ import { PodloveJson } from "../src/Formats/PodloveJson";
 import { AppleHLS } from "../src/Formats/AppleHLS";
 import { Scenecut } from "../src/Formats/Scenecut";
 import { Audible } from "../src/Formats/Audible";
+import { Podigee } from "../src/Formats/Podigee";
 import { readFileSync } from "fs";
 import { sep } from "path";
 
 describe('conversions from one format to any other', () => {
     const formats = [
         AppleChapters, AppleHLS, Audible, ChaptersJson, 
         FFMetadata, MatroskaXML, MKVMergeSimple, MKVMergeXML, 
-        MP4Chaps, PodloveJson, PodloveSimpleChapters, PySceneDetect, 
+        MP4Chaps, Podigee, PodloveJson, PodloveSimpleChapters, PySceneDetect, 
         Scenecut, ShutterEDL, VorbisComment, WebVTT, Youtube
     ];
 

tests/format_podigee.test.ts

@@ -0,0 +1,68 @@
+import { readFileSync } from "fs";
+import { sep } from "path";
+import { PodloveJson } from "../src/Formats/PodloveJson";
+import { Podigee } from "../src/Formats/Podigee";
+
+
+describe('Podigee Format Handler', () => {
+    it('accepts no arguments', () => {
+        expect(() => {
+            Podigee.create();
+        }).not.toThrow(TypeError);
+    });
+
+
+    it('fails on malformed input', () => {
+        expect(() => {
+            Podigee.create('asdf');
+        }).toThrow(Error);
+    });
+
+    const content = readFileSync(module.path + sep + 'samples' + sep + 'podigee.json', 'utf-8');
+
+    it('parses well-formed input', () => {
+        expect(() => {
+            Podigee.create(content);
+        }).not.toThrow(Error);
+    });
+
+    const instance = Podigee.create(content);
+
+    it('has the correct number of chapters from content', () => {
+        expect(instance.chapters.length).toEqual(5);
+    });
+
+    it('has parsed the timestamps correctly', () => {
+        expect(instance.chapters[1].startTime).toBe(112)
+    });
+
+    it('has parsed the chapter titles correctly', () => {
+        expect(instance.chapters[0].title).toBe('Einleitung')
+    });
+
+    it('exports to correct format', () => {
+        expect(instance.toString()).toContain('start_time":"');
+    });
+
+    it('export includes correct timestamp', () => {
+        expect(instance.toString()).toContain('00:01:52');
+    });
+
+    it('can import previously generated export', () => {
+        expect(Podigee.create(instance.toString()).chapters[2].startTime).toEqual(316);
+    });
+
+    it('can convert into other format', () => {
+        expect(instance.to(PodloveJson)).toBeInstanceOf(PodloveJson)
+    });
+
+    it('will apply the pretty print option', () => {
+        expect(instance.toString(true)).not.toEqual(instance.toString());
+    });
+
+    it('fails on empty input array', () => {
+        expect(() => {
+            (new Podigee).from(JSON.stringify([]));
+        }).toThrow(Error);
+    });
+});

tests/samples/podigee.json

@@ -0,0 +1,23 @@
+[
+    {
+        "title": "Einleitung",
+        "start_time": "00:00:00"
+    },
+    {
+        "title": "Diskettenlyrik",
+        "start_time": "00:01:52"
+    },
+    {
+        "title": "ENTWICKLUNG DER DISKETTE",
+        "start_time": "00:05:16"
+    },
+    {
+        "title": "Erstes Speichermedium: Die Lochkarte",
+        "start_time": "00:07:09"
+    },
+    {
+        "title": "Das Magnetband",
+        "start_time": "00:08:47"
+    }
+
+]