@makefully/dutifully 1.11.0 → 1.12.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.12.1
+
+- Preserve optional script-line `events` through Transcript for timed marker definitions.
+
+## 1.12.0
+
+- Treat missing `src`/`output` directories as empty instead of failing; create output directories when writing.
+
 ## 1.11.0
 
 - Preserve optional script-line `class` through transcription for VTT cue classes, SAMI spans, and JSON caption output.

package/README.md

@@ -205,6 +205,14 @@ If your scripts include any phrases that should remain unbroken by the captionin
 
 Script lines may include an optional `class` (for example `"title"` or `"stage"`). In VTT exports this becomes a cue class span (`<c.title>…</c>`). In SAMI/SMI the paragraph `Class` is the job language plus `CC` (for example `ENUSCC` for `en-US`); when a speaker and/or script `class` is present, the dialog is wrapped in `<SPAN Class="…">` (for example `Class="todd stage"`). In JSON exports it is included on each caption entry. SRT, LRC, and MP3 SYLT ignore it.
 
+Script lines may also include an optional `events` array for one-shot timed markers. Entries may be:
+
+* a **number** — add to the running absolute time offset (ms)
+* a **string** `"<phrase"` / `">phrase"` — set the offset to just before/after that phrase in the caption; any other string fires that event at the current offset
+* an **object** `{ "event", "time"?, "before"?, "after"? }` — fires `event`; optional fields set the absolute offset (`time` wins over `before` over `after`)
+
+Cheerfully resolves these against caption timings and exports them in parallel using the same caption `format` (`events.json`, `{id}.events.vtt` / `.srt` / `.sami` / `.smi` / `.lrc`, or a separate MP3 SYLT frame with content type `EVENTS` labeled `"events"`).
+
 ## Example
 
 Find an example script in the `./examples/` folder. You can run either `npm run test-elevenlabs` or `npm run test-polly` to create VO tracks in the examples folder that you can then use to try out `npm run test-rhubarb` and `npm run test-transcription`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.11.0",
+    "version": "1.12.1",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {

package/src/classes/LipSync.js

@@ -2,11 +2,12 @@ const
     Cheer = require('./Cheer'),
     fs = require('fs').promises,
     getJSON = require('../helpers/getJSON'),
+    {ensureDir, ensureParentDir, readdirOrEmpty} = require('../helpers/dirs'),
     id3 = require('node-id3').Promise,
     filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`),
     combine = async (path, fileType) => {
         const
-            files = (await fs.readdir(path)).filter(filter.bind(null, fileType)),
+            files = (await readdirOrEmpty(path)).filter(filter.bind(null, fileType)),
             list = [];
         
         for (let i = 0; i < files.length; i++) {
@@ -56,7 +57,13 @@ const
                 {config} = this,
                 {files = {}, options = {}, output, src} = config,
                 {exportFormat = 'json', output: outputType = 'json'} = options,
-                file = 'mouthCues.json',
+                file = 'mouthCues.json';
+
+            if (output) {
+                await ensureDir(output);
+            }
+
+            const
                 raw = outputType === 'json' && exportFormat !== 'mp3' ? await getJSON(`${output}${file}`) ?? {} : null,
                 alreadyLipSynced = raw ? Object.keys(raw) : await combine(output, exportFormat),
                 check = (id) => {
@@ -83,6 +90,7 @@ const
                         console.log(`Removed "${key}"`);
                     }
                     if (raw) {
+                        await ensureParentDir(`${output}${file}`);
                         await fs.writeFile(`${output}${file}`, JSON.stringify(sortKeys({
                             ...raw,
                             ...newLipSync ? await getJSON(`${output}${file}`) ?? {} : {} // get new version.
@@ -91,7 +99,7 @@ const
 
                     return alreadyLipSynced.length;
                 },
-                list = (await fs.readdir(src)).filter(filter.bind(null, 'mp3')).filter((file) => !check(file.substring(0, file.length - 4)));
+                list = (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3')).filter((file) => !check(file.substring(0, file.length - 4)));
 
             this.differenceOnly = true;
 

package/src/classes/TextToSpeech.js

@@ -3,6 +3,7 @@ const
     Transcript = require('./Transcript'),
     fs = require('fs').promises,
     getFileData = require('../helpers/getFileData'),
+    {ensureDir, readdirOrEmpty} = require('../helpers/dirs'),
     id3 = require('node-id3').Promise,
     isoLanguageMap = {
         'en-US': 'eng',
@@ -11,7 +12,7 @@ const
     matches = (file, types) => types.reduce((prev, current) => prev || (file.slice(-(current.length + 1)) === `.${current}`), false),
     getMP3s = async ({encodedBy = '', output = './', fileTypes = [], transcripts}) => {
         const
-            all = (await fs.readdir(output))
+            all = (await readdirOrEmpty(output))
                 .filter((file) => (file.indexOf('.') !== 0) && (fileTypes.length === 0 || matches(file, fileTypes)));
 
         if (transcripts) {
@@ -76,7 +77,11 @@ const
             }
         }
     },
-    appendMP3Meta = ({album, captions, generated = false, language, output, voice}) => {
+    appendMP3Meta = async ({album, captions, generated = false, language, output, voice}) => {
+        if (output) {
+            await ensureDir(output);
+        }
+
         Object.keys(captions).forEach(async (id) => {
             const
                 text = captionText(captions[id]),
@@ -140,7 +145,13 @@ const
         async checkDifference () {
             const
                 {album, config, encodedBy = '', transcripts} = this,
-                {output, files = {}, language, updateAllMetaData = false} = config,
+                {output, files = {}, language, updateAllMetaData = false} = config;
+
+            if (output) {
+                await ensureDir(output);
+            }
+
+            const
                 {missing, present, unlisted} = await getMP3s({
                     encodedBy,
                     fileTypes: ['mp3'],

package/src/classes/Transcript.js

@@ -41,7 +41,7 @@ const
                 }
 
                 const
-                    {caption, class: lineClass, speaker, voice} = line,
+                    {caption, class: lineClass, speaker, voice, events} = line,
                     resolvedVoice = voice ?? (voiceOrVoiceMap ? resolveVoice(voiceOrVoiceMap, speaker) : null),
                     result = {caption};
 
@@ -53,6 +53,10 @@ const
                     result.speaker = speaker;
                 }
 
+                if (events) {
+                    result.events = events;
+                }
+
                 if (resolvedVoice) {
                     result.voice = resolvedVoice;
                 }

package/src/classes/Transcription.js

@@ -5,6 +5,7 @@ const
     getCaptions = require('../helpers/getCaptions'),
     getFileData = require('../helpers/getFileData'),
     getJSON = require('../helpers/getJSON'),
+    {ensureDir, readdirOrEmpty} = require('../helpers/dirs'),
     SEPARATE_CHARACTER = '|',
     JOIN_CHARACTER = '^',
     filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`),
@@ -44,7 +45,13 @@ const
             const
                 {config} = this,
                 {files, format = 'json', output, src} = config,
-                fileType = format.toLowerCase(),
+                fileType = format.toLowerCase();
+
+            if (output) {
+                await ensureDir(output);
+            }
+
+            const
                 {captions: alreadyCaptioned, file: captionsFile, files: fileMap} = await getCaptions(output, fileType),
                 check = (id, caption) => {
                     const
@@ -99,7 +106,7 @@ const
     
                     return olds.length;
                 },
-                list = (await fs.readdir(src)).filter(filter.bind(null, 'mp3')).filter((file) => {
+                list = (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3')).filter((file) => {
                     const
                         id = file.substring(0, file.length - 4),
                         caption = files?.[id];

package/src/formats/File.js

@@ -1,5 +1,6 @@
 const
     fs = require('fs').promises,
+    {ensureParentDir} = require('../helpers/dirs'),
     File = class {
         constructor ({fileType}) {
             this.data = null;
@@ -15,7 +16,8 @@ const
             return null; // does not support hashes.
         }
 
-        save () { // return a promise
+        async save () { // return a promise
+            await ensureParentDir(this.path);
             return fs.writeFile(`${this.path}`, this.data ?? '');
         }
 

package/src/formats/JSONFile.js

@@ -2,6 +2,7 @@ const
     crypto = require('crypto'),
     fs = require('fs').promises,
     File = require("./File"),
+    {ensureParentDir} = require('../helpers/dirs'),
     getJSON = require('../helpers/getJSON'),
     sortKeys = (obj) => Object.keys(obj).sort().reduce((s, key) => {
         s[key] = obj[key];
@@ -11,7 +12,7 @@ const
 module.exports = class JSONFile extends File {
     async load (path) {
         await super.load(path);
-        this.data = await getJSON(path);
+        this.data = await getJSON(path) ?? {};
         return this.data;
     }
 
@@ -34,7 +35,8 @@ module.exports = class JSONFile extends File {
         });
     }
 
-    save () { // return a promise
+    async save () { // return a promise
+        await ensureParentDir(this.path);
         return fs.writeFile(`${this.path}`, JSON.stringify(this.data, null, 4));
     }
 }

package/src/formats/MP3.js

@@ -1,6 +1,7 @@
 const
     id3 = require('node-id3').Promise,
-    File = require("./File");
+    File = require("./File"),
+    {ensureParentDir} = require('../helpers/dirs');
 
 module.exports = class MP3 extends File {
     async load (path) {
@@ -31,7 +32,8 @@ module.exports = class MP3 extends File {
         return null;
     }
 
-    save () { // return a promise
+    async save () { // return a promise
+        await ensureParentDir(this.path);
         return id3.write(this.data, this.path);
     }
 

package/src/helpers/dirs.js

@@ -0,0 +1,30 @@
+const
+    fs = require('fs').promises,
+    path = require('path'),
+    ensureDir = async (dir) => {
+        if (dir) {
+            await fs.mkdir(dir, {recursive: true});
+        }
+    },
+    ensureParentDir = async (filePath) => {
+        if (filePath) {
+            await ensureDir(path.dirname(filePath));
+        }
+    },
+    readdirOrEmpty = async (dir) => {
+        try {
+            return await fs.readdir(dir);
+        } catch (e) {
+            if (e?.code === 'ENOENT') {
+                return [];
+            }
+
+            throw e;
+        }
+    };
+
+module.exports = {
+    ensureDir,
+    ensureParentDir,
+    readdirOrEmpty
+};

package/src/helpers/getCaptions.js

@@ -1,6 +1,6 @@
 const
-    fs = require('fs').promises,
     getFileData = require("./getFileData"),
+    {readdirOrEmpty} = require("./dirs"),
     filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`);
 
 module.exports = async (path, fileType) => {
@@ -9,10 +9,10 @@ module.exports = async (path, fileType) => {
     if (fileType.toLowerCase() === 'json') {
         const
             file = await getFileData(`${path}captions.json`, 'json'),
-            {data: json} = file;
+            {data: json = {}} = file;
 
         return {
-            captions: Object.keys(json).reduce((obj, key) => {
+            captions: Object.keys(json ?? {}).reduce((obj, key) => {
                 obj[key] = json[key].map(({content}) => content).join(' ');
                 return obj;
             }, {}),
@@ -21,7 +21,7 @@ module.exports = async (path, fileType) => {
         };
     } else { // Otherwise we pull all the files and construct a key/value object.
         const
-            files = (await fs.readdir(path)).filter(filter.bind(null, fileType)),
+            files = (await readdirOrEmpty(path)).filter(filter.bind(null, fileType)),
             captions = {},
             fileMap = {};