@makefully/dutifully 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 1.24.0
+
+### Added
+
+- WebM export format mirror for lipsync / transcription (`webm` beside `mp3`); `.weba` is an accepted alias that preserves the `.weba` filename on embed; read-only `WebM.js` via `music-metadata@^11`.
+- TTS jobs send `album` + `generationHashes` for Cheerfully server-side metadata stamping; drop post-download ID3 hash writes for newly generated VO.
+- `Metadata` Cheerfully client + `updateAllMetaData` via the `metadata` service (MP3 local ID3 fallback).
+- Require Node `>=22` (for `music-metadata` ESM).
+
+## 1.23.1
+
+### Added
+
+- Shared `auth` on jobs and `env-cheerfully.json` `auth.<service>` map (job wins; env fills defaults). Legacy `elevenLabsApiKey` and top-level ElevenLabs `apiKey` still map into `auth.apiKey`.
+
 ## 1.23.0
 
 - Provider umbrellas: `translate` (`amazon` default → `amazontranslate`, or `deepl` / `google` / `microsoft`), `lipsync` (`rhubarb` default / `allosaurus`), and `voiceover` (`elevenlabs` default / `polly`) resolve to Cheerfully concrete services before Yap submit.

package/README.md

@@ -6,17 +6,30 @@ Client API for Cheerfully services. Cheerfully makes voice-over easy.
 npm install @makefully/dutifully
 ```
 
-To use the API, you will need to specify a root `./env-cheerfully.json` file with the following format:
+Requires **Node.js 22+** (for `music-metadata` WebM reads).
+
+To use the API, you will need a root `./env-cheerfully.json` with Showfully Yap credentials and optional per-service auth defaults:
 
 ```javascript
 {
     "server": "http://server:port",
-    "accessToken": "BearerTokenForShowfullyYap"
+    "accessToken": "BearerTokenForShowfullyYap",
+    "auth": {
+        "elevenlabs": { "apiKey": "…" },
+        "deepl": { "apiKey": "…", "serverUrl": "https://api-free.deepl.com" },
+        "googletranslate": { "apiKey": "…" },
+        "microsofttranslate": { "key": "…", "region": "eastus" },
+        "amazontranslate": { "config": { } },
+        "polly": { "config": { }, "bucket": "…", "root": "…" },
+        "transcription": { "config": { }, "bucket": "…", "root": "…" }
+    }
 }
 ```
 
 `accessToken` is sent as `Authorization: Bearer …` on yap submit/status/download (Showfully 1.4+). For local Showfully, use the same value as `SHOWFULLY_DEBUG_TOKEN` with `SHOWFULLY_ALLOW_DEBUG_TOKEN=1`.
 
+Job listings may include their own `auth` object (same shapes). Dutifully merges `auth.<service>` from env into each job; **job `auth` wins**. Legacy `elevenLabsApiKey` still maps to `auth.elevenlabs.apiKey`.
+
 ## Services
 
 All services can be specified in `cheerfully.json` as described in the following sections. Services can be run as scripts specified in `package.json` as:
@@ -100,7 +113,7 @@ await cheerfully.say('The build is complete');
 ```
 
 
-Voice settings come from the first `elevenlabs` entry in `cheerfully.json` (same as other ElevenLabs chores). Server credentials and `elevenLabsApiKey` come from `env-cheerfully.json`. Cached files are keyed by voice + text, so repeats play immediately without regenerating.
+Voice settings come from the first `elevenlabs` entry in `cheerfully.json` (same as other ElevenLabs chores). Server credentials and optional `auth.elevenlabs` (or legacy `elevenLabsApiKey`) come from `env-cheerfully.json`. Cached files are keyed by voice + text, so repeats play immediately without regenerating.
 
 ### ElevenLabs
 
@@ -122,16 +135,28 @@ You may set a single `voice` value to an ElevenLabs voice id, or an object of sp
 
 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.
+Specifying `updateAllMetaData` is `false` by default. If it's set to `true`, album, title, and unsynchronized lyrics are applied to any present VO files that were not regenerated, via Cheerfully’s `metadata` service (works for `.mp3` and `.webm`; falls back to local ID3 for MP3 if the service is unavailable).
 
-You may include your ElevenLabs API Key directly in the ElevenLabs spec above as `apiKey`, or set your API Key separately in `env-cheerfully.json`:
+Newly generated VO is tagged on the server (`updateMediaMeta`) using `album` and per-file `generationHashes` from the Dutifully job. WebM is **read-only** on Dutifully (`music-metadata`); all WebM writes go through Cheerfully.
+
+You may include credentials on the job as `auth.apiKey`, or set defaults in `env-cheerfully.json`:
 
 ```javascript
 {
-    "elevenLabsApiKey": "elevenlabsapikeyforyouraccount"
+    "auth": {
+        "elevenlabs": {
+            "apiKey": "elevenlabsapikeyforyouraccount"
+        }
+    }
 }
 ```
 
+Legacy `elevenLabsApiKey` at the top level of `env-cheerfully.json` is still accepted.
+
+### Metadata
+
+Tag-only Cheerfully chore (`service: "metadata"`). Upload media plus a `metadata.json` payload of per-file tags (same schema as Cheerfully’s metadata service). Dutifully’s `Metadata` parser mirrors this for `updateAllMetaData` and ad-hoc retags.
+
 ### FFMPEG
 
 This audio file process accepts ffmpeg commandline arguments to perform operations on an audio file.
@@ -305,7 +330,7 @@ This text-to-voice service requires a script as input and will download audio VO
 
 You may set a single `voice` value matching an available AMazon Polly voice or this may be an object of key/value pairs with speaker name keys matched to voices. The speaker names must match speakers listed in the script. If "default" is provided as a key, this voice will be used for any scripts not specifying a speaker.
 
-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.
+Specifying `updateAllMetaData` is `false` by default. If it's set to `true`, present VO files are retagged via Cheerfully’s `metadata` service (same behavior as ElevenLabs).
 
 ### Allosaurus
 
@@ -324,7 +349,7 @@ 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 embeds lipsync timings into the MP3's ID3 metadata.
+Export formats include those supported by Rhubarb as well as `mp3` / `webm`, which embed lipsync timings into the source audio (ID3 SYLT or WebVTT track).
 
 Set `exportFormat`, `exports`, or omit/`null` for export selection:
 
@@ -366,7 +391,7 @@ 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 embeds lipsync timings into the MP3's ID3 metadata.
+Export formats include those supported by Rhubarb as well as `mp3` / `webm`, which embed lipsync timings into the source audio (ID3 SYLT or WebVTT track).
 
 Use `exportFormat`, `exports`, or omit/`null` with the same string | array | all semantics as Rhubarb (see Allosaurus above).
 
@@ -396,6 +421,7 @@ Transcription supports the following formats:
 * JSON
 * LRC
 * MP3 (Embedded in source MP3 as a SYLT ID3 tag labeled "captions".)
+* WebM (Embedded WebVTT track titled `captions` / `words`. Accepts `.webm` / `.weba` sources; embeds keep the source extension. Dutifully reads via `music-metadata`; embedding is server-side.)
 * SAMI / SMI
 * SRT
 * VTT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/dutifully",
-    "version": "1.23.0",
+    "version": "1.24.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {
@@ -66,10 +66,11 @@
         "access": "public"
     },
     "engines": {
-        "node": ">=18"
+        "node": ">=22"
     },
     "dependencies": {
         "archiver": "^7.0.1",
+        "music-metadata": "^11.16.1",
         "node-id3": "^0.2.6",
         "node-web-audio-api": "^2.0.0",
         "png-chunk-text": "^1.0.0",

package/src/classes/Cheer.js

@@ -6,6 +6,7 @@ const
     https = require('https'),
     {PassThrough} = require('stream'),
     unzipper = require('unzip-stream'),
+    {applyServiceAuth} = require('../helpers/applyServiceAuth'),
     cleanPath = (path) => path[path.length - 1] === '/' ? path.substring(0, path.length - 1) : path,
     isZipMagic = (buf) => buf && buf.length >= 4 && buf[0] === 0x50 && buf[1] === 0x4b &&
         ((buf[2] === 0x03 && buf[3] === 0x04) || (buf[2] === 0x05 && buf[3] === 0x06) || (buf[2] === 0x07 && buf[3] === 0x08)),
@@ -264,9 +265,9 @@ const
     },
     Cheer = class {
         constructor ({config, contents}) {
-            this.config = config;
             this.contents = contents;
             this.service = contents.service;
+            this.config = applyServiceAuth(config, contents, contents.service);
         }
 
         prepare ({difference = true, extract = true}) {

package/src/classes/ElevenLabs.js

@@ -4,14 +4,11 @@ const
 module.exports = class ElevenLabs extends TextToSpeech {
     constructor (data) {
         const
-            {id, elevenLabsApiKey} = data.contents;
+            {id} = data.contents;
 
         data.album = id;
         data.encodedBy = 'ElevenLabs';
-        if (elevenLabsApiKey) {
-            data.config.apiKey = elevenLabsApiKey;
-        }
-
+        // Auth (env auth.elevenlabs / elevenLabsApiKey / job.auth) is applied in Cheer.
         super(data);
     }
-};
+};

package/src/classes/LipSync.js

@@ -2,10 +2,32 @@ const
     Cheer = require('./Cheer'),
     fs = require('fs').promises,
     getJSON = require('../helpers/getJSON'),
-    {resolveJobExports} = require('../helpers/jobExports'),
+    {resolveJobExports, isWebMExt} = 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}`),
+    getFileData = require('../helpers/getFileData'),
+    fileExt = (file) => {
+        const
+            i = file.lastIndexOf('.');
+
+        return i >= 0 ? file.slice(i + 1).toLowerCase() : '';
+    },
+    filter = (fileType, file) => {
+        if (file.indexOf('.') === 0) {
+            return false;
+        }
+
+        const
+            ext = fileExt(file);
+
+        if (fileType === 'webm') {
+            return isWebMExt(ext);
+        }
+
+        return ext === fileType;
+    },
+    AUDIO_SRC_EXTS = ['mp3', 'webm', 'weba'],
+    stripExt = (file) => file.replace(/\.[^.]+$/, ''),
     combine = async (path, fileType) => {
         const
             files = (await readdirOrEmpty(path)).filter(filter.bind(null, fileType)),
@@ -13,7 +35,8 @@ const
         
         for (let i = 0; i < files.length; i++) {
             const
-                file = files[i];
+                file = files[i],
+                ext = fileExt(file);
 
             if (fileType === 'mp3') {
                 const
@@ -24,11 +47,22 @@ const
                         index = synchronisedLyrics.map(({shortText}) => shortText).indexOf('lipsync');
 
                     if (index >= 0) {
-                        list.push(file.substring(0, file.length - fileType.length - 1));
+                        list.push(stripExt(file));
+                    }
+                }
+            } else if (fileType === 'webm' || isWebMExt(ext)) {
+                try {
+                    const
+                        webm = await getFileData(`${path}${file}`, ext);
+
+                    if (webm.hasTimedTrack('lipsync')) {
+                        list.push(stripExt(file));
                     }
+                } catch (e) {
+                    // ignore unreadable webm/weba
                 }
             } else {
-                list.push(file.substring(0, file.length - fileType.length - 1));
+                list.push(stripExt(file));
             }
         }
 
@@ -40,7 +74,7 @@ const
     }, {}),
     mapReduction = (map, list) => list.reduce((obj, file) => {
         const
-            id = file.substring(0, file.length - 4);
+            id = stripExt(file);
 
         obj[id] = map[id];
         return obj;
@@ -145,6 +179,10 @@ const
 
                             if (formatId !== 'json') {
                                 await fs.rm(`${output}${key}.${formatId}`, {force: true});
+
+                                if (formatId === 'webm') {
+                                    await fs.rm(`${output}${key}.weba`, {force: true});
+                                }
                             }
                         }
 
@@ -163,12 +201,14 @@ const
                 },
                 list = [];
 
-            for (const fileName of (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3'))) {
-                const
-                    id = fileName.substring(0, fileName.length - 4);
+            for (const ext of AUDIO_SRC_EXTS) {
+                for (const fileName of (await readdirOrEmpty(src)).filter(filter.bind(null, ext))) {
+                    const
+                        id = stripExt(fileName);
 
-                if (!(await isCurrent(id))) {
-                    list.push(fileName);
+                    if (!(await isCurrent(id))) {
+                        list.push(fileName);
+                    }
                 }
             }
 

package/src/classes/Metadata.js

@@ -0,0 +1,34 @@
+const
+    Cheer = require('./Cheer'),
+    Metadata = class Metadata extends Cheer {
+        constructor (data) {
+            const
+                {mediaFiles = [], ...rest} = data;
+
+            super({
+                ...rest,
+                contents: {
+                    ...rest.contents,
+                    service: 'metadata'
+                }
+            });
+            this.mediaFiles = mediaFiles;
+        }
+
+        beforeSend (archive) {
+            const
+                {src} = this.config;
+
+            if (this.mediaFiles.length) {
+                this.mediaFiles.forEach(({path: filePath, name}) => {
+                    archive.file(filePath, {name});
+                });
+            } else if (src) {
+                archive.directory(src, false);
+            }
+
+            super.beforeSend(archive);
+        }
+    };
+
+module.exports = Metadata;

package/src/classes/TextToSpeech.js

@@ -1,5 +1,6 @@
 const
     Cheer = require('./Cheer'),
+    Metadata = require('./Metadata'),
     Transcript = require('./Transcript'),
     fs = require('fs').promises,
     getFileData = require('../helpers/getFileData'),
@@ -143,6 +144,15 @@ const
             this.config.files = standardizedFiles;
             this.transcripts = transcripts;
 
+            // Server-side metadata stamping (Cheerfully updateMediaMeta).
+            this.config.album = this.album;
+            this.config.generationHashes = Object.keys(transcripts).reduce((map, id) => {
+                map[id] = transcripts[id].getHash({
+                    seed: this.encodedBy ?? ''
+                });
+                return map;
+            }, {});
+
             return super.prepare(data);
         }
 
@@ -171,11 +181,12 @@ const
             }
     
             if (updateAllMetaData && present.length) {
-                await appendMP3Meta({
+                await this.updatePresentMeta({
                     album,
                     captions: mapReduction(files, present),
                     language,
-                    output
+                    output,
+                    present
                 });
             }
     
@@ -186,10 +197,64 @@ const
             this.updateList = missing;
         }
 
+        /**
+         * Retag existing VO via Cheerfully `metadata` service (mp3 / webm).
+         * Falls back to local ID3 writes if the metadata chore fails.
+         */
+        async updatePresentMeta ({album, captions, language, output, present}) {
+            const
+                {contents} = this,
+                tagFiles = {},
+                mediaFiles = present.map((filename) => {
+                    const
+                        id = filename.substring(0, filename.lastIndexOf('.')),
+                        text = captionText(captions[id]);
+
+                    tagFiles[filename] = {
+                        album,
+                        title: clamp(text, 40),
+                        lyrics: text,
+                        language
+                    };
+
+                    return {
+                        path: `${output}${filename}`,
+                        name: filename
+                    };
+                });
+
+            try {
+                const
+                    job = new Metadata({
+                        config: {files: tagFiles},
+                        contents: {
+                            ...contents,
+                            service: 'metadata',
+                            output,
+                            extract: true
+                        },
+                        mediaFiles
+                    });
+
+                await job.send({instanceId: `${contents.id || 'tts'}-metadata`});
+                present.forEach((filename) => {
+                    console.log(`Voice meta data updated for "${filename.substring(0, filename.lastIndexOf('.'))}".`);
+                });
+            } catch (e) {
+                console.warn(`metadata service failed (${e.message || e}); falling back to local MP3 ID3 writes.`);
+                await appendMP3Meta({
+                    album,
+                    captions,
+                    language,
+                    output
+                });
+            }
+        }
+
         async afterExport (...args) {
             const
-                {album, encodedBy, config, transcripts, updateList} = this,
-                {files, output, language, voice} = config,
+                {config, updateList} = this,
+                {files, output} = config,
                 list = updateList ?? Object.keys(files).map((id) => `${id}.mp3`),
                 missing = [];
 
@@ -222,27 +287,10 @@ const
                 );
             }
 
-            await appendMP3Meta({
-                album,
-                captions: files,
-                generated: true,
-                language,
-                output,
-                voice
+            // Album / title / lyrics / GenerationHash are stamped server-side via updateMediaMeta.
+            list.forEach((filename) => {
+                console.log(`Voice generated for "${filename.substring(0, filename.lastIndexOf('.'))}".`);
             });
-            for (let i = 0; i < list.length; i++) {
-                const
-                    filename = list[i],
-                    id = filename.substring(0, filename.length - 4),
-                    file = await getFileData(`${output}${filename}`, 'mp3');
-
-                file.addHash(transcripts[id].getHash({
-                    seed: encodedBy ?? ''
-                }), {
-                    hashKey: 'GenerationHash'
-                });
-                await file.save();
-            }
             super.afterExport(...args);
         }
     };

package/src/classes/Transcription.js

@@ -10,9 +10,11 @@ const
     SEPARATE_CHARACTER = '|',
     JOIN_CHARACTER = '^',
     filter = (fileType, file) => (file.indexOf('.') !== 0) && (file.slice(-(fileType.length + 1)) === `.${fileType}`),
+    AUDIO_SRC_EXTS = ['mp3', 'webm', 'weba'],
+    stripExt = (file) => file.replace(/\.[^.]+$/, ''),
     mapReduction = (map, list) => list.reduce((obj, file) => {
         const
-            id = file.substring(0, file.length - 4);
+            id = stripExt(file);
 
         obj[id] = map[id];
         return obj;
@@ -141,6 +143,10 @@ const
                                 if (fileType !== 'json') {
                                     await fs.rm(`${output}${caption}.${fileType}`, {force: true});
                                     await fs.rm(`${output}${caption}.events.${fileType}`, {force: true});
+
+                                    if (fileType === 'webm') {
+                                        await fs.rm(`${output}${caption}.weba`, {force: true});
+                                    }
                                 }
                             }
                         }
@@ -178,13 +184,19 @@ const
 
                     return staleIds.size;
                 },
-                list = (await readdirOrEmpty(src)).filter(filter.bind(null, 'mp3')).filter((file) => {
+                list = [];
+
+            for (const ext of AUDIO_SRC_EXTS) {
+                for (const file of (await readdirOrEmpty(src)).filter(filter.bind(null, ext))) {
                     const
-                        id = file.substring(0, file.length - 4),
+                        id = stripExt(file),
                         caption = files?.[id];
 
-                    return !check(id, caption);
-                });
+                    if (!check(id, caption)) {
+                        list.push(file);
+                    }
+                }
+            }
 
             if (exportFormats.length === 1) {
                 config.format = exportFormats[0];
@@ -213,10 +225,10 @@ const
                 const
                     fileType = exportFormats[i];
 
-                if (fileType !== 'json' && fileType !== 'mp3') {
+                if (fileType !== 'json' && fileType !== 'mp3' && fileType !== 'webm') {
                     for (let j = 0; j < list.length; j++) {
                         const
-                            id = list[j].substring(0, list[j].length - 4);
+                            id = stripExt(list[j]);
 
                         await fs.rm(`${output}${id}.events.${fileType}`, {force: true});
                     }
@@ -258,7 +270,14 @@ const
                 for (let j = 0; j < updateList.length; j++) {
                     const
                         filename = updateList[j],
-                        id = filename.substring(0, filename.length - 4),
+                        id = stripExt(filename);
+
+                    // WebM hashes are stamped server-side (read-only client format).
+                    if (formatId === 'webm') {
+                        continue;
+                    }
+
+                    const
                         file = await getFileData(`${output}${id}.${formatId}`, formatId);
 
                     file.addHash(transcripts[id].getHash());

package/src/formats/WebM.js

@@ -0,0 +1,96 @@
+const
+    File = require('./File');
+
+let musicMetadataPromise = null;
+
+const loadMusicMetadata = () => {
+    if (!musicMetadataPromise) {
+        musicMetadataPromise = import('music-metadata');
+    }
+
+    return musicMetadataPromise;
+};
+
+const trackName = (track) => track?.name || track?.codecName || '';
+
+module.exports = class WebM extends File {
+    async load (path) {
+        await super.load(path);
+        const
+            mm = await loadMusicMetadata(),
+            metadata = await mm.parseFile(path);
+
+        this.data = metadata;
+        this.common = metadata.common || {};
+        this.native = metadata.native || {};
+        this.format = metadata.format || {};
+        return this.data;
+    }
+
+    /**
+     * Read CAPTION_HASH / GENERATION_HASH (or Capti* aliases) from Matroska native tags.
+     */
+    getHash ({hashKey = 'CaptionHash'} = {}) {
+        const
+            wanted = new Set([
+                hashKey,
+                hashKey.toUpperCase(),
+                hashKey.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase(),
+                String(hashKey).replace(/\s+/g, '_').toUpperCase()
+            ]),
+            matroska = this.native.matroska || this.native.Matroska || [];
+
+        for (let i = 0; i < matroska.length; i++) {
+            const
+                {id, value} = matroska[i] || {};
+
+            if (wanted.has(id) || wanted.has(String(id || '').toUpperCase())) {
+                return value;
+            }
+        }
+
+        // Fallback: common / format tags
+        if (hashKey === 'CaptionHash' || hashKey === 'CAPTION_HASH') {
+            return this.common.comment?.[0] ?? null;
+        }
+
+        return null;
+    }
+
+    addHash () {
+        throw new Error('WebM hashes must be written via Cheerfully metadata service (read-only on Dutifully).');
+    }
+
+    async save () {
+        throw new Error('WebM.save is not supported on Dutifully; use Cheerfully metadata service.');
+    }
+
+    hasTimedTrack (name) {
+        const
+            tracks = this.format.trackInfo || [];
+
+        return tracks.some((track) => {
+            const
+                n = trackName(track).toLowerCase();
+
+            return n === String(name).toLowerCase();
+        });
+    }
+
+    toString () {
+        if (this.common.lyrics) {
+            const
+                lyrics = this.common.lyrics;
+
+            if (typeof lyrics === 'string') {
+                return lyrics;
+            }
+
+            if (Array.isArray(lyrics)) {
+                return lyrics.map((entry) => entry?.text ?? entry).join(' ');
+            }
+        }
+
+        return this.common.title || '';
+    }
+};

package/src/helpers/applyServiceAuth.js

@@ -0,0 +1,89 @@
+/**
+ * Merge Dutifully env-cheerfully.json `auth.<service>` into a job's `auth`.
+ * Job-level auth wins; env fills defaults. Legacy `elevenLabsApiKey` maps to elevenlabs.
+ */
+
+const isPlainObject = (value) => (
+    value != null && typeof value === 'object' && !Array.isArray(value)
+);
+
+/**
+ * Normalize legacy env aliases into `contents.auth`.
+ * @param {Record<string, unknown>} contents
+ * @returns {Record<string, unknown>}
+ */
+const normalizeContentsAuth = (contents = {}) => {
+    const
+        auth = isPlainObject(contents.auth) ? {...contents.auth} : {};
+
+    if (contents.elevenLabsApiKey) {
+        auth.elevenlabs = {
+            ...(isPlainObject(auth.elevenlabs) ? auth.elevenlabs : {}),
+            apiKey: contents.elevenLabsApiKey
+        };
+    }
+
+    return auth;
+};
+
+/**
+ * Apply service auth defaults onto a job config (mutates config).
+ * @param {Record<string, unknown>} config job listing from cheerfully.json
+ * @param {Record<string, unknown>} contents merged cheer + env + CLI
+ * @param {string} [service] Cheerfully service id (defaults to contents.service)
+ * @returns {Record<string, unknown>} config
+ */
+const applyServiceAuth = (config, contents = {}, service = contents.service) => {
+    if (!config || typeof config !== 'object') {
+        return config;
+    }
+
+    const
+        authMap = normalizeContentsAuth(contents),
+        fromEnv = service && isPlainObject(authMap[service]) ? {...authMap[service]} : {},
+        fromJob = isPlainObject(config.auth) ? {...config.auth} : {},
+        // Legacy ElevenLabs top-level apiKey on the job
+        legacyJobKey = service === 'elevenlabs'
+            && typeof config.apiKey === 'string'
+            && config.apiKey
+            && fromJob.apiKey == null
+            ? {apiKey: config.apiKey}
+            : {};
+
+    const
+        merged = {
+            ...fromEnv,
+            ...legacyJobKey,
+            ...fromJob
+        };
+
+    if (isPlainObject(fromEnv.config) || isPlainObject(fromJob.config) || isPlainObject(legacyJobKey.config)) {
+        merged.config = {
+            ...(isPlainObject(fromEnv.config) ? fromEnv.config : {}),
+            ...(isPlainObject(fromJob.config) ? fromJob.config : {})
+        };
+
+        if (isPlainObject(fromEnv.config?.credentials) || isPlainObject(fromJob.config?.credentials)) {
+            merged.config.credentials = {
+                ...(isPlainObject(fromEnv.config?.credentials) ? fromEnv.config.credentials : {}),
+                ...(isPlainObject(fromJob.config?.credentials) ? fromJob.config.credentials : {})
+            };
+        }
+    }
+
+    if (Object.keys(merged).length) {
+        config.auth = merged;
+    }
+
+    // Prefer auth container; drop legacy top-level apiKey once folded in.
+    if (service === 'elevenlabs' && config.apiKey != null && config.auth?.apiKey) {
+        delete config.apiKey;
+    }
+
+    return config;
+};
+
+module.exports = {
+    normalizeContentsAuth,
+    applyServiceAuth
+};

package/src/helpers/getCaptions.js

@@ -1,18 +1,36 @@
 const
     getFileData = require("./getFileData"),
     {readdirOrEmpty} = require("./dirs"),
-    filter = (fileType, file) => {
+    {isWebMExt} = require("./jobExports"),
+    fileExt = (file) => {
+        const
+            i = file.lastIndexOf('.');
+
+        return i >= 0 ? file.slice(i + 1).toLowerCase() : '';
+    },
+    matchesType = (fileType, file) => {
         if (file.indexOf('.') === 0) {
             return false;
         }
 
-        if (file.slice(-(fileType.length + 1)) !== `.${fileType}`) {
+        const
+            ext = fileExt(file);
+
+        if (fileType === 'webm') {
+            return isWebMExt(ext);
+        }
+
+        return ext === fileType;
+    },
+    filter = (fileType, file) => {
+        if (!matchesType(fileType, file)) {
             return false;
         }
 
         // Parallel event exports are `{id}.events.{format}` — not caption tracks.
         const
-            base = file.slice(0, -(fileType.length + 1));
+            ext = fileExt(file),
+            base = file.slice(0, -(ext.length + 1));
 
         return !base.endsWith('.events');
     };
@@ -47,8 +65,9 @@ module.exports = async (path, fileType) => {
         for (let i = 0; i < files.length; i++) {
             const
                 filename = files[i],
-                file = await getFileData(`${path}${filename}`, fileType),
-                key = filename.substring(0, filename.length - fileType.length - 1);
+                ext = fileExt(filename),
+                file = await getFileData(`${path}${filename}`, ext),
+                key = filename.substring(0, filename.length - ext.length - 1);
                 
             captions[key] = file.toString();
             fileMap[key] = file;

package/src/helpers/getFileData.js

@@ -2,6 +2,7 @@ const
     JSONFile = require("../formats/JSONFile"),
     LRC = require("../formats/LRC"),
     MP3 = require("../formats/MP3"),
+    WebM = require("../formats/WebM"),
     SAMI = require("../formats/SAMI"),
     SRT = require("../formats/SRT"),
     VTT = require("../formats/VTT"),
@@ -9,6 +10,8 @@ const
         json: JSONFile,
         lrc: LRC,
         mp3: MP3,
+        webm: WebM,
+        weba: WebM,
         sami: SAMI,
         smi: SAMI,
         srt: SRT,

package/src/helpers/jobExports.js

@@ -3,26 +3,37 @@
  * 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 LYRIC_FORMATS = ['json', 'lrc', 'mp3', 'sami', 'smi', 'srt', 'vtt', 'tsv', 'xml', 'dat', 'webm'];
+const TRANSCRIPTION_FORMATS = ['json', 'lrc', 'mp3', 'sami', 'smi', 'srt', 'vtt', 'webm'];
 const PACKFULLY_FORMATS = ['texturepacker', 'json-array', 'createjs', 'spine', 'css', 'starling', 'unity', 'godot'];
 const TRANSLATE_FORMATS = ['json', 'i18n', 'catalog', 'po', 'xliff', 'properties', 'yml', 'yaml', 'strings', 'xml', 'csv', 'tsv'];
+/** Extensions that satisfy the `webm` embed export (same Matroska container). */
+const WEB_M_SOURCE_EXTS = ['webm', 'weba'];
 
 const EXPORT_CATALOG = {
     transcription: {
         keys: ['format', 'exportFormat', 'exports', 'f'],
         formats: TRANSCRIPTION_FORMATS,
-        constraints: {mp3: {sourceExt: 'mp3'}}
+        constraints: {
+            mp3: {sourceExt: 'mp3'},
+            webm: {sourceExt: WEB_M_SOURCE_EXTS}
+        }
     },
     rhubarb: {
         keys: ['exportFormat', 'exports', 'f'],
         formats: LYRIC_FORMATS,
-        constraints: {mp3: {sourceExt: 'mp3'}}
+        constraints: {
+            mp3: {sourceExt: 'mp3'},
+            webm: {sourceExt: WEB_M_SOURCE_EXTS}
+        }
     },
     allosaurus: {
         keys: ['exportFormat', 'exports', 'f'],
         formats: LYRIC_FORMATS,
-        constraints: {mp3: {sourceExt: 'mp3'}}
+        constraints: {
+            mp3: {sourceExt: 'mp3'},
+            webm: {sourceExt: WEB_M_SOURCE_EXTS}
+        }
     },
     translate: {
         keys: ['format', 'exports'],
@@ -61,6 +72,30 @@ const normalizeFormatId = (format) => {
     return id;
 };
 
+const normalizeExt = (ext) => String(ext || '').toLowerCase().replace(/^\./, '');
+
+const isWebMExt = (ext) => WEB_M_SOURCE_EXTS.includes(normalizeExt(ext));
+
+const embedArchiveExt = (exportFormat, sourceExt) => {
+    if (exportFormat === 'webm' && isWebMExt(sourceExt)) {
+        return normalizeExt(sourceExt);
+    }
+
+    return exportFormat;
+};
+
+const sourceExtAllowed = (ruleExt, sourceExt) => {
+    if (!ruleExt || !sourceExt) {
+        return true;
+    }
+
+    const
+        allowed = Array.isArray(ruleExt) ? ruleExt : [ruleExt],
+        src = normalizeExt(sourceExt);
+
+    return allowed.map(normalizeExt).includes(src);
+};
+
 const extractRawValue = (job = {}, keys = []) => {
     for (let i = 0; i < keys.length; i++) {
         const
@@ -86,7 +121,7 @@ const applyConstraints = (formats, constraints = {}, {sourceExt} = {}) => format
         return true;
     }
 
-    if (rule.sourceExt && sourceExt && rule.sourceExt !== sourceExt) {
+    if (rule.sourceExt && sourceExt && !sourceExtAllowed(rule.sourceExt, sourceExt)) {
         return false;
     }
 
@@ -143,5 +178,8 @@ const resolveJobExports = (job = {}, serviceId, {sourceExt, defaultFormats} = {}
 
 module.exports = {
     EXPORT_CATALOG,
+    WEB_M_SOURCE_EXTS,
+    isWebMExt,
+    embedArchiveExt,
     resolveJobExports
 };

package/src/index.js

@@ -11,6 +11,7 @@ const
         elevenlabs: require('./classes/ElevenLabs'),
         ffmpeg: require('./classes/FFMPEG'),
         googletranslate: Translate,
+        metadata: require('./classes/Metadata'),
         microsofttranslate: Translate,
         packfully: require('./classes/Packfully'),
         polly: require('./classes/Polly'),