@makefully/dutifully 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 1.21.0
+
+- Add `jobExports` mirror for multi-format diff checks in LipSync and Transcription.
+- Packfully difference checks honor `exports: null` → all atlas formats.
+- Document `exports` string | array | null semantics for lipsync and transcription jobs.
+
+
+- Add `translate` client for Amazon Translate (Cheerfully script JSON or language-matrix CSV/TSV).
+- Support `ignore` for phrases left untranslated.
+
 ## 1.19.0
 
 - Authenticate Showfully yap chores with `Authorization: Bearer` and `POST /yap/:service` (token no longer in the URL path).

package/README.md

@@ -288,10 +288,31 @@ This audio-to-lip-flap service requires audio as input and will download a mouth
 }
 ```
 
-Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
+Export formats include those supported by Rhubarb as well as `mp3`, which embeds lipsync timings into the MP3's ID3 metadata.
+
+Set `exportFormat`, `exports`, or omit/`null` for export selection:
+
+* **string** — one format (for example `"json"` or `"mp3"`)
+* **array** — multiple formats in one run (for example `"exports": ["json", "mp3"]`)
+* **`null` / omit** — all supported formats (difference checks require every format to be current)
+
+MP3 export does **not** include `mouthCues.json` unless `json` is also requested.
 
 For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
 
+```javascript
+{
+    "rhubarb": [{
+        "exports": ["json", "mp3"],
+        "options": {
+            "compress": true
+        },
+        "src": "./example/vo/en/",
+        "output": "./example/lipsync/en/"
+    }]
+}
+```
+
 ### Rhubarb
 
 This audio-to-lip-flap service requires audio as input and will download a mouth cues JSON file delineating mouth shapes for particular timestamps using Rhubarb Lip-Sync. You can set Rhubarb settings in `cheerfully.json` like so:
@@ -309,7 +330,9 @@ This audio-to-lip-flap service requires audio as input and will download a mouth
 }
 ```
 
-Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
+Export formats include those supported by Rhubarb as well as `mp3`, which embeds lipsync timings into the MP3's ID3 metadata.
+
+Use `exportFormat`, `exports`, or omit/`null` with the same string | array | all semantics as Rhubarb (see Allosaurus above).
 
 For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
 
@@ -341,6 +364,24 @@ Transcription supports the following formats:
 * SRT
 * VTT
 
+Use `format`, `exports`, or omit/`null`:
+
+* **string** — one format (for example `"vtt"`)
+* **array** — multiple formats (for example `"exports": ["json", "vtt", "srt"]`)
+* **`null` / omit on `exports`** — all supported formats in one Cheerfully run
+
+```javascript
+{
+    "transcription": [{
+        "exports": ["json", "vtt", "srt"],
+        "language": "en-US",
+        "script": "./example/script.json",
+        "src": "./example/vo/en/",
+        "output": "./example/captions/en/"
+    }]
+}
+```
+
 Specify `limit` to set the maximum number of characters for a single caption line. The default is `40`.
 
 If your scripts include any phrases that should remain unbroken by the captioning process, add them to the `nowrap` list. For example: `"nowrap": ["Makefully Studios"]`.
@@ -355,9 +396,40 @@ Script lines may also include an optional `events` array for one-shot timed mark
 
 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"`).
 
+### Translate
+
+This text-to-text service translates Cheerfully scripts or language-matrix CSV/TSV via Amazon Translate. Set jobs in `cheerfully.json`:
+
+```javascript
+{
+    "translate": [{
+        "script": "./example/script.json",
+        "language": "en-US",
+        "languages": ["es-ES", "fr-FR"],
+        "output": "./example/scripts/",
+        "ignore": ["Makefully Studios"]
+    }, {
+        "script": "./example/strings.csv",
+        "language": "en-US",
+        "languages": ["es-ES", "fr-FR"],
+        "output": "./example/scripts/"
+    }]
+}
+```
+
+* `script` — path to a Cheerfully `.json` script or a language-matrix `.csv` / `.tsv` (first column = ids, first row = language tags).
+* `language` — source locale (CSV: source column). Matrix jobs require this; JSON may use `auto`.
+* `languages` — target locales to produce or fill.
+* `format` / `exports` — optional. Defaults to the source extension (`json`, `csv`, or `tsv`).
+* `ignore` — phrases left untranslated.
+
+JSON sources write `{lang}/{basename}.{ext}` under `output`. CSV/TSV sources write an updated matrix file and leave existing non-empty cells unchanged.
+
+Supported formats: `json`, `i18n`, `csv`, `tsv`, `po`, `xliff`, `properties`, `yml` / `yaml`, `strings`, `xml`.
+
 ## 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`. Sample sprites for atlas packing are under `./example/sprites/`; run `npm run test-packfully` to pack them into `./example/atlases/`.
+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`. Sample sprites for atlas packing are under `./example/sprites/`; run `npm run test-packfully` to pack them into `./example/atlases/`. Run `npm run test-translate` to translate `./example/script.json` and `./example/strings.csv` into `./example/scripts/`.
 
 These examples are specified using a JSON definition in `./cheerfully.json` which you can copy or modify to set different generation parameters as supported by Cheerfully.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.19.0",
+    "version": "1.21.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {
@@ -28,6 +28,7 @@
         "test-sharp": "node ./cheer.js -service sharp",
         "test-stackfully": "node ./cheer.js -service stackfully",
         "test-transcription": "node ./cheer.js -service transcription",
+        "test-translate": "node ./cheer.js -service translate",
         "say": "node ./say.js"
     },
     "repository": {
@@ -50,7 +51,8 @@
         "packfully",
         "atlas",
         "spritesheet",
-        "classfully"
+        "classfully",
+        "translate"
     ],
     "author": "Derek Detweiler <derek@makefullystudios.com>",
     "contributors": [

package/src/classes/LipSync.js

@@ -2,6 +2,7 @@ const
     Cheer = require('./Cheer'),
     fs = require('fs').promises,
     getJSON = require('../helpers/getJSON'),
+    {resolveJobExports} = require('../helpers/jobExports'),
     {ensureDir, ensureParentDir, readdirOrEmpty} = require('../helpers/dirs'),
     id3 = require('node-id3').Promise,
     filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`),
@@ -14,7 +15,7 @@ const
             const
                 file = files[i];
 
-            if (fileType === 'mp3') { // check id3 for lyrics presence.
+            if (fileType === 'mp3') {
                 const
                     {synchronisedLyrics} = await id3.read(`${path}${file}`);
 
@@ -54,9 +55,13 @@ const
 
         async checkDifference () {
             const
-                {config} = this,
-                {files = {}, options = {}, output, src} = config,
-                {exportFormat = 'json', output: outputType = 'json'} = options,
+                {config, service} = this,
+                {files = {}, options = {}, output, src, exports: configExports} = config,
+                exportFormats = resolveJobExports({
+                    exports: configExports,
+                    options
+                }, service, {defaultFormats: ['json']}),
+                usesJsonAggregate = exportFormats.includes('json'),
                 file = 'mouthCues.json';
 
             if (output) {
@@ -64,47 +69,128 @@ const
             }
 
             const
-                raw = outputType === 'json' && exportFormat !== 'mp3' ? await getJSON(`${output}${file}`) ?? {} : null,
-                alreadyLipSynced = raw ? Object.keys(raw) : await combine(output, exportFormat),
-                check = (id) => {
-                    const
-                        index = alreadyLipSynced.indexOf(id);
+                raw = usesJsonAggregate ? await getJSON(`${output}${file}`) ?? {} : null,
+                formatLists = {},
+                loadFormatList = async (formatId) => {
+                    if (formatId === 'json') {
+                        return raw ? Object.keys(raw) : [];
+                    }
 
-                    if (index >= 0) {
-                        alreadyLipSynced.splice(index, 1);
-                        return true;
-                    } else {
-                        return false;
+                    formatLists[formatId] = formatLists[formatId] ?? await combine(output, formatId);
+                    return formatLists[formatId];
+                },
+                markDone = (id) => {
+                    if (raw) {
+                        delete raw[id];
                     }
+
+                    exportFormats.forEach((formatId) => {
+                        if (formatId === 'json') {
+                            return;
+                        }
+
+                        const
+                            list = formatLists[formatId];
+
+                        if (!list) {
+                            return;
+                        }
+
+                        const
+                            index = list.indexOf(id);
+
+                        if (index >= 0) {
+                            list.splice(index, 1);
+                        }
+                    });
                 },
-                mergeLipSync = async (newLipSync = false) => { // Must run _after_ all checks and will remove what's left.
-                    for (let i = 0; i < alreadyLipSynced.length; i++) {
+                isCurrent = async (id) => {
+                    for (let i = 0; i < exportFormats.length; i++) {
                         const
-                            key = alreadyLipSynced[i];
+                            formatId = exportFormats[i],
+                            list = await loadFormatList(formatId);
+
+                        if (list.indexOf(id) < 0) {
+                            return false;
+                        }
+                    }
+
+                    markDone(id);
+                    return true;
+                },
+                mergeLipSync = async (newLipSync = false) => {
+                    const
+                        staleIds = new Set();
+
+                    if (raw) {
+                        Object.keys(raw).forEach((key) => staleIds.add(key));
+                    }
+
+                    exportFormats.forEach((formatId) => {
+                        if (formatId === 'json') {
+                            return;
+                        }
+
+                        (formatLists[formatId] || []).forEach((key) => staleIds.add(key));
+                    });
 
+                    for (const key of staleIds) {
                         if (raw) {
                             delete raw[key];
-                        } else {
-                            await fs.rm(`${output}${key}.${exportFormat}`);
                         }
+
+                        for (let i = 0; i < exportFormats.length; i++) {
+                            const
+                                formatId = exportFormats[i];
+
+                            if (formatId !== 'json') {
+                                await fs.rm(`${output}${key}.${formatId}`, {force: true});
+                            }
+                        }
+
                         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.
+                            ...newLipSync ? await getJSON(`${output}${file}`) ?? {} : {}
                         }), null, 4));
                     }
 
-                    return alreadyLipSynced.length;
+                    return staleIds.size;
                 },
-                list = (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3')).filter((file) => !check(file.substring(0, file.length - 4)));
+                list = [];
+
+            for (const fileName of (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3'))) {
+                const
+                    id = fileName.substring(0, fileName.length - 4);
+
+                if (!(await isCurrent(id))) {
+                    list.push(fileName);
+                }
+            }
+
+            if (exportFormats.length === 1) {
+                config.options = {
+                    ...options,
+                    exportFormat: exportFormats[0]
+                };
+                delete config.exports;
+            } else {
+                config.exports = exportFormats;
+                config.options = {
+                    ...options,
+                    exportFormat: undefined,
+                    f: undefined
+                };
+            }
 
             this.differenceOnly = true;
+            this.exportFormats = exportFormats;
 
             if (list.length === 0) {
-                // We'll still run the merge in case any have been removed.
                 if (await mergeLipSync()) {
                     throw Error('Old lip-sync removed, but no new ones required generation.');
                 } else {
@@ -138,4 +224,4 @@ const
         }
     };
 
-module.exports = LipSync;
+module.exports = LipSync;

package/src/classes/Packfully.js

@@ -10,18 +10,48 @@ const
         listImageFiles
     } = require('../helpers/imageHash'),
     {ensureDir, readdirOrEmpty} = require('../helpers/dirs'),
+    {resolveJobExports} = require('../helpers/jobExports'),
     HASH_KEY = HASH_KEYS.packfully,
-    listFormats = (job = {}) => {
+    packfullyAlias = (format) => {
         const
-            raw = job.exports ?? job.format ?? job.options?.format;
-
-        if (raw == null) {
-            return ['texturepacker'];
+            id = String(format || 'texturepacker').toLowerCase();
+
+        switch (id) {
+        case 'texturepacker':
+        case 'json-hash':
+        case 'jsonhash':
+        case 'pixi':
+        case 'phaser-hash':
+        case 'phaserhash':
+            return 'texturepacker';
+        case 'json-array':
+        case 'jsonarray':
+        case 'phaser-array':
+        case 'phaserarray':
+            return 'json-array';
+        case 'createjs':
+        case 'easeljs':
+            return 'createjs';
+        case 'spine':
+        case 'atlas':
+            return 'spine';
+        default:
+            return id;
         }
+    },
+    listFormats = (job = {}) => {
         const
-            list = Array.isArray(raw) ? raw : [raw];
-
-        return [...new Set(list.map((f) => String(f).toLowerCase()))];
+            raw = job.exports ?? job.format ?? job.options?.format,
+            normalizedJob = raw === undefined
+                ? job
+                : {
+                    ...job,
+                    exports: (Array.isArray(raw) ? raw : [raw]).map(packfullyAlias),
+                    format: undefined
+                },
+            list = resolveJobExports(normalizedJob, 'packfully', {defaultFormats: ['texturepacker']});
+
+        return [...new Set(list.map(packfullyAlias))];
     },
     Packfully = class Packfully extends Cheer {
         async checkDifference () {

package/src/classes/Transcription.js

@@ -5,6 +5,7 @@ const
     getCaptions = require('../helpers/getCaptions'),
     getFileData = require('../helpers/getFileData'),
     getJSON = require('../helpers/getJSON'),
+    {resolveJobExports} = require('../helpers/jobExports'),
     {ensureDir, readdirOrEmpty} = require('../helpers/dirs'),
     SEPARATE_CHARACTER = '|',
     JOIN_CHARACTER = '^',
@@ -22,7 +23,6 @@ const
             this.updateList = null;
             await this.replaceConfigPathWithJSON('script', 'files');
             
-            // create standardized transcripts and an accompanying hash for each.
             const
                 {files, voice} = this.config,
                 standardizedFiles = {},
@@ -44,45 +44,68 @@ const
         async checkDifference () {
             const
                 {config} = this,
-                {files, format = 'json', output, src} = config,
-                fileType = format.toLowerCase();
+                {files, format = 'json', exports, output, src} = config,
+                exportFormats = resolveJobExports({format, exports}, 'transcription', {
+                    defaultFormats: [format || 'json']
+                }),
+                formatState = {};
 
             if (output) {
                 await ensureDir(output);
             }
 
+            for (let i = 0; i < exportFormats.length; i++) {
+                const
+                    fileType = exportFormats[i];
+
+                formatState[fileType] = await getCaptions(output, fileType);
+            }
+
             const
-                {captions: alreadyCaptioned, file: captionsFile, files: fileMap} = await getCaptions(output, fileType),
-                eventsJsonExisting = fileType === 'json' ? await getJSON(`${output}events.json`) : null,
+                jsonState = formatState.json,
+                eventsJsonExisting = exportFormats.includes('json') ? await getJSON(`${output}events.json`) : null,
                 eventsFile = eventsJsonExisting ? await getFileData(`${output}events.json`, 'json') : null,
-                check = (id, caption) => {
+                staleByFormat = exportFormats.reduce((obj, fileType) => {
+                    obj[fileType] = {...(formatState[fileType]?.captions ?? {})};
+                    return obj;
+                }, {}),
+                checkFormat = (fileType, id, caption) => {
                     const
-                        file = fileMap?.[id],
-                        original = alreadyCaptioned[id],
+                        state = formatState[fileType],
+                        file = state?.files?.[id],
+                        original = state?.captions?.[id],
                         hash = file?.getHash();
-                        
-                    delete alreadyCaptioned[id];
-                    
+
+                    delete staleByFormat[fileType][id];
+
                     if (hash) {
                         const
                             same = hash === this.transcripts[id].getHash();
 
                         if (!same) {
-                            console.log(`Updating "${id}".`);
+                            console.log(`Updating "${id}" (${fileType}).`);
                         }
 
                         return same;
-                    } else {
-                        const
-                            cap = (Array.isArray(caption) ? caption : [caption]).map((cap) => cap?.caption ?? cap ?? null).filter((cap) => cap !== null).join(' ').replaceAll(JOIN_CHARACTER, ' ').replaceAll(SEPARATE_CHARACTER, ' ');
-        
-                        if (cap && cap !== original) {
-                            console.log(`Updating "${id}".`);
-                        }
+                    }
 
-                        // if a caption is not supplied, we'll assume the existence of an original caption means we don't need to redo.
-                        return cap === '' || cap === original;
+                    const
+                        cap = (Array.isArray(caption) ? caption : [caption]).map((cap) => cap?.caption ?? cap ?? null).filter((cap) => cap !== null).join(' ').replaceAll(JOIN_CHARACTER, ' ').replaceAll(SEPARATE_CHARACTER, ' ');
+
+                    if (cap && cap !== original) {
+                        console.log(`Updating "${id}" (${fileType}).`);
                     }
+
+                    return cap === '' || cap === original;
+                },
+                check = (id, caption) => {
+                    for (let i = 0; i < exportFormats.length; i++) {
+                        if (!checkFormat(exportFormats[i], id, caption)) {
+                            return false;
+                        }
+                    }
+
+                    return true;
                 },
                 saveEventsFile = async () => {
                     if (!eventsFile) {
@@ -95,30 +118,40 @@ const
                         await eventsFile.save();
                     }
                 },
-                mergeCaptions = async (newCaptions = false) => { // Must run _after_ all checks and will remove what's left.
+                mergeCaptions = async (newCaptions = false) => {
                     const
-                        olds = Object.keys(alreadyCaptioned);
-                        
-                    for (let i = 0; i < olds.length; i++) {
+                        staleIds = new Set();
+
+                    exportFormats.forEach((fileType) => {
+                        Object.keys(staleByFormat[fileType] || {}).forEach((id) => staleIds.add(id));
+                    });
+
+                    for (const caption of staleIds) {
                         const
-                            caption = olds[i];
-    
+                            captionsFile = jsonState?.file;
+
                         if (captionsFile) {
                             captionsFile.removeKey(caption);
                             eventsFile?.removeKey(caption);
                         } else {
-                            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});
+                            for (let i = 0; i < exportFormats.length; i++) {
+                                const
+                                    fileType = exportFormats[i];
+
+                                if (fileType !== 'json') {
+                                    await fs.rm(`${output}${caption}.${fileType}`, {force: true});
+                                    await fs.rm(`${output}${caption}.events.${fileType}`, {force: true});
+                                }
+                            }
                         }
+
                         console.log(`Removed "${caption}"`);
                     }
-                    if (captionsFile) {
+
+                    if (jsonState?.file) {
                         if (newCaptions) {
-                            captionsFile.mergeData(await getJSON(`${output}captions.json`));
+                            jsonState.file.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`) ?? {};
@@ -136,14 +169,14 @@ const
                             } 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) {
+                        } else if (staleIds.size) {
                             await saveEventsFile();
                         }
-                        await captionsFile.save();
+
+                        await jsonState.file.save();
                     }
-    
-                    return olds.length;
+
+                    return staleIds.size;
                 },
                 list = (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3')).filter((file) => {
                     const
@@ -153,10 +186,18 @@ const
                     return !check(id, caption);
                 });
 
+            if (exportFormats.length === 1) {
+                config.format = exportFormats[0];
+                delete config.exports;
+            } else {
+                config.exports = exportFormats;
+                delete config.format;
+            }
+
             this.differenceOnly = true;
+            this.exportFormats = exportFormats;
 
             if (list.length === 0) {
-                // We'll still run the merge in case any have been removed.
                 if (await mergeCaptions()) {
                     throw Error('Old captions removed, but no new captions required generation.');
                 } else {
@@ -168,13 +209,17 @@ const
             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);
+            for (let i = 0; i < exportFormats.length; i++) {
+                const
+                    fileType = exportFormats[i];
+
+                if (fileType !== 'json' && fileType !== 'mp3') {
+                    for (let j = 0; j < list.length; j++) {
+                        const
+                            id = list[j].substring(0, list[j].length - 4);
 
-                    await fs.rm(`${output}${id}.events.${fileType}`, {force: true});
+                        await fs.rm(`${output}${id}.events.${fileType}`, {force: true});
+                    }
                 }
             }
         }
@@ -195,23 +240,32 @@ const
 
         async afterExport (...args) {
             const
-                {config, transcripts, updateList} = this,
-                {format = 'json', output} = config;
+                {config, transcripts, updateList, exportFormats = [config.format || 'json']} = this,
+                {output} = config;
 
             if (this.mergeCaptions) {
                 await this.mergeCaptions(true);
             }
-            if (format !== 'json') {
-                for (let i = 0; i < updateList.length; i++) {
+
+            for (let i = 0; i < exportFormats.length; i++) {
+                const
+                    formatId = exportFormats[i];
+
+                if (formatId === 'json') {
+                    continue;
+                }
+
+                for (let j = 0; j < updateList.length; j++) {
                     const
-                        filename = updateList[i],
+                        filename = updateList[j],
                         id = filename.substring(0, filename.length - 4),
-                        file = await getFileData(`${output}${id}.${format}`, format);
+                        file = await getFileData(`${output}${id}.${formatId}`, formatId);
 
                     file.addHash(transcripts[id].getHash());
                     await file.save();
                 }
             }
+
             super.afterExport(...args)
         }
     };

package/src/classes/Translate.js

@@ -0,0 +1,47 @@
+const
+    path = require('path'),
+    Cheer = require('./Cheer'),
+    MATRIX_EXTS = new Set(['csv', 'tsv']),
+    Translate = class Translate extends Cheer {
+        async prepare (data) {
+            const
+                {config} = this,
+                scriptPath = config.script;
+
+            this.matrixMode = false;
+            this.scriptPath = null;
+
+            if (scriptPath) {
+                const
+                    ext = path.extname(scriptPath).slice(1).toLowerCase(),
+                    basename = path.basename(scriptPath, path.extname(scriptPath));
+
+                this.scriptPath = scriptPath;
+                config.basename = config.basename ?? basename;
+
+                if (!config.format && !config.exports) {
+                    config.format = MATRIX_EXTS.has(ext) ? ext : 'json';
+                }
+
+                if (MATRIX_EXTS.has(ext)) {
+                    this.matrixMode = true;
+                    config.matrixFile = path.basename(scriptPath);
+                    delete config.script;
+                } else {
+                    await this.replaceConfigPathWithJSON('script', 'files');
+                }
+            }
+
+            return super.prepare(data);
+        }
+
+        beforeSend (archive) {
+            if (this.matrixMode && this.scriptPath) {
+                archive.file(this.scriptPath, {name: this.config.matrixFile});
+            }
+
+            return super.beforeSend(archive);
+        }
+    };
+
+module.exports = Translate;

package/src/helpers/jobExports.js

@@ -0,0 +1,131 @@
+/**
+ * Client-side mirror of Cheerfully server/helpers/jobExports.js
+ * Keep catalog subsets in sync with the canonical Cheerfully module.
+ */
+
+const LYRIC_FORMATS = ['json', 'lrc', 'mp3', 'sami', 'smi', 'srt', 'vtt', 'tsv', 'xml', 'dat'];
+const TRANSCRIPTION_FORMATS = ['json', 'lrc', 'mp3', 'sami', 'smi', 'srt', 'vtt'];
+const PACKFULLY_FORMATS = ['texturepacker', 'json-array', 'createjs', 'spine', 'css', 'starling', 'unity', 'godot'];
+const TRANSLATE_FORMATS = ['json', 'i18n', 'po', 'xliff', 'properties', 'yml', 'yaml', 'strings', 'xml', 'csv', 'tsv'];
+
+const EXPORT_CATALOG = {
+    transcription: {
+        keys: ['format', 'exportFormat', 'exports', 'f'],
+        formats: TRANSCRIPTION_FORMATS,
+        constraints: {mp3: {sourceExt: 'mp3'}}
+    },
+    rhubarb: {
+        keys: ['exportFormat', 'exports', 'f'],
+        formats: LYRIC_FORMATS,
+        constraints: {mp3: {sourceExt: 'mp3'}}
+    },
+    allosaurus: {
+        keys: ['exportFormat', 'exports', 'f'],
+        formats: LYRIC_FORMATS,
+        constraints: {mp3: {sourceExt: 'mp3'}}
+    },
+    translate: {
+        keys: ['format', 'exports'],
+        formats: TRANSLATE_FORMATS
+    },
+    packfully: {
+        keys: ['format', 'exports', 'exportFormat'],
+        formats: PACKFULLY_FORMATS
+    }
+};
+
+const normalizeFormatId = (format) => {
+    const
+        id = String(format).toLowerCase().replace(/^\./, '');
+
+    if (id === 'jpeg') {
+        return 'jpg';
+    }
+
+    return id;
+};
+
+const extractRawValue = (job = {}, keys = []) => {
+    for (let i = 0; i < keys.length; i++) {
+        const
+            key = keys[i];
+
+        if (job[key] !== undefined) {
+            return job[key];
+        }
+
+        if (job.options?.[key] !== undefined) {
+            return job.options[key];
+        }
+    }
+
+    return undefined;
+};
+
+const applyConstraints = (formats, constraints = {}, {sourceExt} = {}) => formats.filter((format) => {
+    const
+        rule = constraints[format];
+
+    if (!rule) {
+        return true;
+    }
+
+    if (rule.sourceExt && sourceExt && rule.sourceExt !== sourceExt) {
+        return false;
+    }
+
+    return true;
+});
+
+const resolveJobExports = (job = {}, serviceId, {sourceExt, defaultFormats} = {}) => {
+    const
+        catalog = EXPORT_CATALOG[serviceId];
+
+    if (!catalog) {
+        throw new Error(`Unknown export service "${serviceId}"`);
+    }
+
+    const
+        raw = extractRawValue(job, catalog.keys);
+
+    if (raw === undefined) {
+        const
+            fallback = defaultFormats?.length
+                ? defaultFormats.map(normalizeFormatId)
+                : [catalog.formats[0]];
+
+        return applyConstraints([...new Set(fallback)], catalog.constraints, {sourceExt});
+    }
+
+    if (raw === null || raw === '') {
+        return applyConstraints([...catalog.formats], catalog.constraints, {sourceExt});
+    }
+
+    const
+        list = (Array.isArray(raw) ? raw : [raw])
+            .map(normalizeFormatId)
+            .filter(Boolean),
+        seen = new Set(),
+        out = [];
+
+    list.forEach((format) => {
+        if (!catalog.formats.includes(format)) {
+            return;
+        }
+
+        if (!seen.has(format)) {
+            seen.add(format);
+            out.push(format);
+        }
+    });
+
+    const
+        constrained = applyConstraints(out.length ? out : [catalog.formats[0]], catalog.constraints, {sourceExt});
+
+    return constrained.length ? constrained : applyConstraints([catalog.formats[0]], catalog.constraints, {sourceExt});
+};
+
+module.exports = {
+    EXPORT_CATALOG,
+    resolveJobExports
+};

package/src/index.js

@@ -13,7 +13,8 @@ const
         rhubarb: LipSync,
         sharp: require('./classes/Sharp'),
         stackfully: require('./classes/Stackfully'),
-        transcription: require('./classes/Transcription')
+        transcription: require('./classes/Transcription'),
+        translate: require('./classes/Translate')
     },
     getJSON = require('./helpers/getJSON'),
     send = async function (contents) {