@makefully/dutifully 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.14.0
+
+- Add `sharp` service client for image convert/compress/resize, thumbnails, and favicon packs.
+- Add `stackfully` service client for multi-layer image compositing.
+
+## 1.13.1
+
+- Harden `say` / ElevenLabs export when the result zip has no MP3 (clearer error, no unhandled ENOENT from ID3 metadata).
+
 ## 1.13.0
 
 - Add `packfully` service client for packing images into texture atlases.

package/README.md

@@ -76,14 +76,14 @@ This text-to-voice service requires a script as input and will download audio VO
         "output": "./example/vo/en/",
         "model": "eleven_multilingual_v1",
         "updateAllMetaData": true,
-        "voice": "Laura"
+        "voice": "21m00Tcm4TlvDq8ikWAM"
     }]
 }
 ```
 
-You may set a single `voice` value matching an available ElevenLabs voice id or this may be an object of key/value pairs with speaker name keys matched to voice ids. The speaker names must match speakers listed in the script. If "default" is provided as a key, this voice id will be used for any scripts not specifying a speaker.
+You may set a single `voice` value to an ElevenLabs voice id, or an object of speaker name keys mapped to voice ids. The speaker names must match speakers listed in the script. If "default" is provided as a key, this voice id will be used for any scripts not specifying a speaker.
 
-Specifying the `model` is optional: if unspecified, Cheerfully will pick a good option for the selected `voice`.
+Specifying the `model` is optional: if unspecified, Cheerfully tries to look up the voice id and pick a good model; if lookup fails it falls back to `eleven_multilingual_v2`.
 
 Specifying `updateAllMetaData` is `false` by default. If it's set to `true`, album, title, and unsynchronized lyrics are appended to any MP3's in the source directory that were not generated.
 
@@ -154,6 +154,67 @@ Use `exports: ["texturepacker", "createjs"]` (or `format`) to choose one or more
 
 Spacing: `padding` is empty gap beyond `extrude`; `extrude` is edge-pixel bleed into that gap; `border` is margin from the atlas edge.
 
+### Sharp
+
+This still-image service converts, compresses, resizes, and can emit multi-size thumbnails or favicon packs (including `.ico`). Every image under `src` is processed; `files` overrides are optional.
+
+```javascript
+{
+    "sharp": [{
+        "src": "./example/images/",
+        "output": "./example/out/",
+        "options": {
+            "format": "webp",
+            "quality": 80,
+            "resize": { "width": 1920, "fit": "inside", "withoutEnlargement": true }
+        },
+        "files": {
+            "logo.png": {
+                "format": ["ico", "png"],
+                "sizes": [16, 32, 48, 64, 128, 256],
+                "prefix": "favicon"
+            }
+        }
+    }]
+}
+```
+
+### Stackfully
+
+This multi-layer compositing service builds sized outputs from ordered image layers (positioning, blend, alpha). Every image under `src` is available as a layer source; define composites under `outputs`.
+
+```javascript
+{
+    "stackfully": [{
+        "src": "./example/images/",
+        "output": "./example/composites/",
+        "options": {
+            "format": "png"
+        },
+        "files": {
+            "badge.png": { "composite": true }
+        },
+        "outputs": {
+            "hero.png": {
+                "width": 1024,
+                "height": 1024,
+                "format": "png",
+                "layers": [
+                    "background.png",
+                    {
+                        "input": "foreground.png",
+                        "alpha": 0.85,
+                        "blend": "over",
+                        "bottom": 0,
+                        "right": 0
+                    }
+                ]
+            }
+        }
+    }]
+}
+```
+
 ### Polly
 
 This text-to-voice service requires a script as input and will download audio VO generated by Amazon Polly. You can set Polly settings in `cheerfully.json` like so:
@@ -253,8 +314,8 @@ Script lines may include an optional `class` (for example `"title"` or `"stage"`
 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`)
+* a **string** `"<phrase"` / `">phrase"` — set the offset to just before/after that phrase in the caption (first word may be an incomplete suffix, last word an incomplete prefix); unmatched phrases leave the offset unchanged and are warned/logged for the client; 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`; same phrase edge rules)
 
 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"`).
 

package/package.json

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

package/src/classes/Sharp.js

@@ -0,0 +1,15 @@
+const
+    Cheer = require('./Cheer'),
+    Sharp = class Sharp extends Cheer {
+        beforeSend (archive) {
+            const
+                {src} = this.config;
+
+            if (src) {
+                archive.directory(src, false);
+            }
+            super.beforeSend(archive);
+        }
+    };
+
+module.exports = Sharp;

package/src/classes/Stackfully.js

@@ -0,0 +1,15 @@
+const
+    Cheer = require('./Cheer'),
+    Stackfully = class Stackfully extends Cheer {
+        beforeSend (archive) {
+            const
+                {src} = this.config;
+
+            if (src) {
+                archive.directory(src, false);
+            }
+            super.beforeSend(archive);
+        }
+    };
+
+module.exports = Stackfully;

package/src/classes/TextToSpeech.js

@@ -82,8 +82,12 @@ const
             await ensureDir(output);
         }
 
-        Object.keys(captions).forEach(async (id) => {
+        const
+            ids = Object.keys(captions);
+
+        for (let i = 0; i < ids.length; i++) {
             const
+                id = ids[i],
                 text = captionText(captions[id]),
                 tags = {
                     album,
@@ -95,13 +99,13 @@ const
                 };
 
             await id3.update(tags, `${output}${id}.mp3`);
-            
+
             if (generated) {
                 console.log(`Voice generated for "${id}".`);
             } else {
                 console.log(`Voice meta data updated for "${id}".`);
             }
-        });
+        }
     },
     mapReduction = (map, list) => list.reduce((obj, file) => {
         const
@@ -167,7 +171,7 @@ const
             }
     
             if (updateAllMetaData && present.length) {
-                appendMP3Meta({
+                await appendMP3Meta({
                     album,
                     captions: mapReduction(files, present),
                     language,
@@ -186,9 +190,39 @@ const
             const
                 {album, encodedBy, config, transcripts, updateList} = this,
                 {files, output, language, voice} = config,
-                list = updateList ?? Object.keys(files).map((id) => `${id}.mp3`);
+                list = updateList ?? Object.keys(files).map((id) => `${id}.mp3`),
+                missing = [];
+
+            for (let i = 0; i < list.length; i++) {
+                const
+                    filename = list[i],
+                    fullPath = `${output}${filename}`;
+
+                try {
+                    await fs.access(fullPath);
+                } catch (e) {
+                    missing.push(filename);
+                }
+            }
+
+            if (missing.length) {
+                let detail = '';
+
+                try {
+                    const
+                        log = JSON.parse(await fs.readFile(`${output}log.json`, 'utf8'));
+
+                    if (log?.errors?.length) {
+                        detail = ` Server errors: ${log.errors.join('; ')}`;
+                    }
+                } catch (e) { /* no log.json */ }
+
+                throw new Error(
+                    `Voice export missing ${missing.length === 1 ? `"${missing[0]}"` : `${missing.length} files (${missing.join(', ')})`}.${detail}`
+                );
+            }
 
-            appendMP3Meta({
+            await appendMP3Meta({
                 album,
                 captions: files,
                 generated: true,

package/src/classes/Transcription.js

@@ -53,6 +53,8 @@ const
 
             const
                 {captions: alreadyCaptioned, file: captionsFile, files: fileMap} = await getCaptions(output, fileType),
+                eventsJsonExisting = fileType === 'json' ? await getJSON(`${output}events.json`) : null,
+                eventsFile = eventsJsonExisting ? await getFileData(`${output}events.json`, 'json') : null,
                 check = (id, caption) => {
                     const
                         file = fileMap?.[id],
@@ -82,6 +84,17 @@ const
                         return cap === '' || cap === original;
                     }
                 },
+                saveEventsFile = async () => {
+                    if (!eventsFile) {
+                        return;
+                    }
+
+                    if (Object.keys(eventsFile.data ?? {}).length === 0) {
+                        await fs.rm(eventsFile.path, {force: true});
+                    } else {
+                        await eventsFile.save();
+                    }
+                },
                 mergeCaptions = async (newCaptions = false) => { // Must run _after_ all checks and will remove what's left.
                     const
                         olds = Object.keys(alreadyCaptioned);
@@ -92,14 +105,40 @@ const
     
                         if (captionsFile) {
                             captionsFile.removeKey(caption);
+                            eventsFile?.removeKey(caption);
                         } else {
-                            await fs.rm(`${output}${caption}.${fileType}`);
+                            await fs.rm(`${output}${caption}.${fileType}`, {force: true});
+                            // Remove parallel event export for the same caption id, if present.
+                            await fs.rm(`${output}${caption}.events.${fileType}`, {force: true});
                         }
                         console.log(`Removed "${caption}"`);
                     }
                     if (captionsFile) {
                         if (newCaptions) {
                             captionsFile.mergeData(await getJSON(`${output}captions.json`));
+
+                            // Drop events for every regenerated caption, then merge whatever the server returned.
+                            // Captions that no longer export events stay removed (no orphan keys).
+                            const
+                                updated = this.updateList ?? [],
+                                newEvents = await getJSON(`${output}events.json`) ?? {};
+
+                            updated.forEach((filename) => {
+                                const
+                                    id = filename.substring(0, filename.length - 4);
+
+                                eventsFile?.removeKey(id);
+                            });
+
+                            if (eventsFile) {
+                                eventsFile.mergeData(newEvents);
+                                await saveEventsFile();
+                            } else if (Object.keys(newEvents).length === 0) {
+                                await fs.rm(`${output}events.json`, {force: true});
+                            }
+                            // else: first events.json for this output — unzipped partial is already correct.
+                        } else if (olds.length) {
+                            await saveEventsFile();
                         }
                         await captionsFile.save();
                     }
@@ -128,6 +167,16 @@ const
             this.updateList = list;
             config.files = mapReduction(files, list);
             this.mergeCaptions = mergeCaptions;
+
+            // Sidecar event files are not overwritten when the server omits them — clear before regenerate.
+            if (fileType !== 'json' && fileType !== 'mp3') {
+                for (let i = 0; i < list.length; i++) {
+                    const
+                        id = list[i].substring(0, list[i].length - 4);
+
+                    await fs.rm(`${output}${id}.events.${fileType}`, {force: true});
+                }
+            }
         }
 
         beforeSend (archive) {
@@ -167,4 +216,4 @@ const
         }
     };
 
-module.exports = Transcription;
+module.exports = Transcription;

package/src/helpers/getCaptions.js

@@ -1,7 +1,21 @@
 const
     getFileData = require("./getFileData"),
     {readdirOrEmpty} = require("./dirs"),
-    filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`);
+    filter = (fileType, file) => {
+        if (file.indexOf('.') === 0) {
+            return false;
+        }
+
+        if (file.slice(-(fileType.length + 1)) !== `.${fileType}`) {
+            return false;
+        }
+
+        // Parallel event exports are `{id}.events.{format}` — not caption tracks.
+        const
+            base = file.slice(0, -(fileType.length + 1));
+
+        return !base.endsWith('.events');
+    };
 
 module.exports = async (path, fileType) => {
 
@@ -13,6 +27,11 @@ module.exports = async (path, fileType) => {
 
         return {
             captions: Object.keys(json ?? {}).reduce((obj, key) => {
+                // Guard against any legacy/mistaken event keys in captions.json.
+                if (key.endsWith('.events')) {
+                    return obj;
+                }
+
                 obj[key] = json[key].map(({content}) => content).join(' ');
                 return obj;
             }, {}),
@@ -41,4 +60,4 @@ module.exports = async (path, fileType) => {
             files: fileMap
         };
     }
-};
+};

package/src/index.js

@@ -10,6 +10,8 @@ const
         polly: require('./classes/Polly'),
         rasterize: require('./classes/Rasterize'),
         rhubarb: LipSync,
+        sharp: require('./classes/Sharp'),
+        stackfully: require('./classes/Stackfully'),
         transcription: require('./classes/Transcription')
     },
     getJSON = require('./helpers/getJSON'),

package/src/say.js

@@ -59,17 +59,20 @@ const
                 },
                 path: '',
                 voice,
-                output
+                output,
+                extract: true
             },
             handler = new ElevenLabs({
                 config,
                 contents: {
                     ...contents,
-                    service: 'elevenlabs'
+                    service: 'elevenlabs',
+                    extract: true
                 }
             });
 
         delete config.script;
+        delete config.src;
 
         await handler.prepare({
             difference: false,
@@ -79,7 +82,30 @@ const
             instanceId: `${contents.id}-say`
         });
 
-        return path.join(CACHE_DIR, `${key}.mp3`);
+        const
+            mp3File = path.join(CACHE_DIR, `${key}.mp3`);
+
+        try {
+            await fsp.access(mp3File);
+        } catch (e) {
+            let detail = '';
+
+            try {
+                const
+                    log = JSON.parse(await fsp.readFile(path.join(CACHE_DIR, 'log.json'), 'utf8'));
+
+                if (log?.errors?.length) {
+                    detail = ` ${log.errors.join('; ')}`;
+                }
+            } catch (err) { /* ignore */ }
+
+            throw new Error(
+                `Speech generation finished but "${mp3File}" was not created.${detail} ` +
+                'Check that the Cheerfully worker is running and picking up elevenlabs chores.'
+            );
+        }
+
+        return mp3File;
     };
 
 module.exports = async (textOrArgs = {}) => {