@makefully/dutifully 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
-# Changelog
-
-## 1.10.1
-
-- Publish as `@makefully/dutifully` on npm with trusted publishing support.
+# Changelog
+
+## 1.11.0
+
+- Preserve optional script-line `class` through transcription for VTT cue classes, SAMI spans, and JSON caption output.
+
+## 1.10.1
+
+- Publish as `@makefully/dutifully` on npm with trusted publishing support.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) Makefully Studios
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) Makefully Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,214 +1,216 @@
-# Dutifully (`@makefully/dutifully`)
-
-Client API for Cheerfully services. Cheerfully makes voice-over easy.
-
-```bash
-npm install @makefully/dutifully
-```
-
-To use the API, you will need to specify a root `./env-cheerfully.json` file with the following format:
-
-```javascript
-{
-    "server": "http://server:port",
-    "accessToken": "accessTokenToUseCheerfullyService"
-}
-```
-
-## 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:
-
-```javascript
-{
-    "scripts": {
-        "speech": "cheer -service elevenlabs",
-        "lipsync": "cheer -service rhubarb",
-        "captions": "cheer -service transcription"
-    }
-}
-```
-
-Alternatively, services can be run from Node by including Dutifully as shown:
-
-```javascript
-const
-    cheerfully = require('@makefully/dutifully');
-
-cheerfully({
-    service: 'polly'
-});
-```
-
-## Say (spoken notifications)
-
-`say` generates short spoken phrases through Cheerfully's ElevenLabs service, caches the audio under `.cache/tts/`, and plays it locally via `node-web-audio-api`. Use it from npm scripts instead of wiring ElevenLabs into the consuming project:
-
-```javascript
-{
-    "scripts": {
-        "say": "say",
-        "web:release": "… && npm run say the web release is complete"
-    }
-}
-```
-
-Or programmatically:
-
-```javascript
-const
-    cheerfully = require('@makefully/dutifully');
-
-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.
-
-### ElevenLabs
-
-This text-to-voice service requires a script as input and will download audio VO generated by ElevenLabs. You can set ElevenLabs settings in `cheerfully.json` like so:
-
-```javascript
-{
-    "elevenlabs": [{
-        "script": "./example/script.json",
-        "output": "./example/vo/en/",
-        "model": "eleven_multilingual_v1",
-        "updateAllMetaData": true,
-        "voice": "Laura"
-    }]
-}
-```
-
-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.
-
-Specifying the `model` is optional: if unspecified, Cheerfully will pick a good option for the selected `voice`.
-
-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.
-
-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`:
-
-```javascript
-{
-    "elevenLabsApiKey": "elevenlabsapikeyforyouraccount"
-}
-```
-
-### FFMPEG
-
-This audio file process accepts ffmpeg commandline arguments to perform operations on an audio file.
-
-```javascript
-{
-    "ffmpeg": [{
-        "options": {"ac": 1},
-        "src": "./example/vo/en/",
-        "output": "./example/vo/en/"
-    }]
-}
-```
-
-### 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:
-
-```javascript
-{
-    "polly": [{
-        "script": "./example/script.json",
-        "output": "./example/vo/en/",
-        "language": "en-US",
-        "updateAllMetaData": true,
-        "voice": "Ivy"
-    }]
-}
-```
-
-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.
-
-### Allosaurus
-
-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 Allosaurus. You can set Allosaurus settings in `cheerfully.json` like so:
-
-```javascript
-{
-    "allosaurus": [{
-        "options" {
-            "compress": true,
-            "exportFormat": "json"
-        },
-        "src": "./example/vo/en/",
-        "output": "./example/lipsync/en/"
-    }]
-}
-```
-
-Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
-
-For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
-
-### 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:
-
-```javascript
-{
-    "rhubarb": [{
-        "options" {
-            "compress": true,
-            "exportFormat": "json"
-        },
-        "src": "./example/vo/en/",
-        "output": "./example/lipsync/en/"
-    }]
-}
-```
-
-Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
-
-For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
-
-### Transcription
-
-This audio-to-captions service requires audio as input and will download a captions JSON file delineating captions with timestamps using Amazon Transcription. You can set Transcription settings in `cheerfully.json` like so:
-
-```javascript
-{
-    "transcription": [{
-        "format": "sami",
-        "language": "en-US",
-        "limit": 40,
-        "prependSpeaker": "[]",
-        "script": "./example/script.json",
-        "src": "./example/vo/en/",
-        "nowrap": [],
-        "output": "./example/captions/en/"
-    }]
-}
-```
-
-Transcription supports the following formats:
-
-* JSON
-* LRC
-* MP3 (Embedded in source MP3 as a SYLT ID3 tag labeled "captions".)
-* SAMI / SMI
-* SRT
-* VTT
-
-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"]`.
-
-## 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`.
-
-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.
-
----
-
-Maintainers: see [PUBLISHING.md](PUBLISHING.md) for npm trusted publishing setup.
+# Dutifully (`@makefully/dutifully`)
+
+Client API for Cheerfully services. Cheerfully makes voice-over easy.
+
+```bash
+npm install @makefully/dutifully
+```
+
+To use the API, you will need to specify a root `./env-cheerfully.json` file with the following format:
+
+```javascript
+{
+    "server": "http://server:port",
+    "accessToken": "accessTokenToUseCheerfullyService"
+}
+```
+
+## 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:
+
+```javascript
+{
+    "scripts": {
+        "speech": "cheer -service elevenlabs",
+        "lipsync": "cheer -service rhubarb",
+        "captions": "cheer -service transcription"
+    }
+}
+```
+
+Alternatively, services can be run from Node by including Dutifully as shown:
+
+```javascript
+const
+    cheerfully = require('@makefully/dutifully');
+
+cheerfully({
+    service: 'polly'
+});
+```
+
+## Say (spoken notifications)
+
+`say` generates short spoken phrases through Cheerfully's ElevenLabs service, caches the audio under `.cache/tts/`, and plays it locally via `node-web-audio-api`. Use it from npm scripts instead of wiring ElevenLabs into the consuming project:
+
+```javascript
+{
+    "scripts": {
+        "say": "say",
+        "web:release": "… && npm run say the web release is complete"
+    }
+}
+```
+
+Or programmatically:
+
+```javascript
+const
+    cheerfully = require('@makefully/dutifully');
+
+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.
+
+### ElevenLabs
+
+This text-to-voice service requires a script as input and will download audio VO generated by ElevenLabs. You can set ElevenLabs settings in `cheerfully.json` like so:
+
+```javascript
+{
+    "elevenlabs": [{
+        "script": "./example/script.json",
+        "output": "./example/vo/en/",
+        "model": "eleven_multilingual_v1",
+        "updateAllMetaData": true,
+        "voice": "Laura"
+    }]
+}
+```
+
+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.
+
+Specifying the `model` is optional: if unspecified, Cheerfully will pick a good option for the selected `voice`.
+
+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.
+
+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`:
+
+```javascript
+{
+    "elevenLabsApiKey": "elevenlabsapikeyforyouraccount"
+}
+```
+
+### FFMPEG
+
+This audio file process accepts ffmpeg commandline arguments to perform operations on an audio file.
+
+```javascript
+{
+    "ffmpeg": [{
+        "options": {"ac": 1},
+        "src": "./example/vo/en/",
+        "output": "./example/vo/en/"
+    }]
+}
+```
+
+### 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:
+
+```javascript
+{
+    "polly": [{
+        "script": "./example/script.json",
+        "output": "./example/vo/en/",
+        "language": "en-US",
+        "updateAllMetaData": true,
+        "voice": "Ivy"
+    }]
+}
+```
+
+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.
+
+### Allosaurus
+
+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 Allosaurus. You can set Allosaurus settings in `cheerfully.json` like so:
+
+```javascript
+{
+    "allosaurus": [{
+        "options" {
+            "compress": true,
+            "exportFormat": "json"
+        },
+        "src": "./example/vo/en/",
+        "output": "./example/lipsync/en/"
+    }]
+}
+```
+
+Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
+
+For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
+
+### 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:
+
+```javascript
+{
+    "rhubarb": [{
+        "options" {
+            "compress": true,
+            "exportFormat": "json"
+        },
+        "src": "./example/vo/en/",
+        "output": "./example/lipsync/en/"
+    }]
+}
+```
+
+Export formats include those supported by Rhubarb as well as "mp3" which will embed lipsync timings into the MP3's id3 meta data.
+
+For exporting to JSON, you can set `compress` to `true` for the format to use JSON arrays similar to Rhubarb's shorter `tsv` format.
+
+### Transcription
+
+This audio-to-captions service requires audio as input and will download a captions JSON file delineating captions with timestamps using Amazon Transcription. You can set Transcription settings in `cheerfully.json` like so:
+
+```javascript
+{
+    "transcription": [{
+        "format": "sami",
+        "language": "en-US",
+        "limit": 40,
+        "prependSpeaker": "[]",
+        "script": "./example/script.json",
+        "src": "./example/vo/en/",
+        "nowrap": [],
+        "output": "./example/captions/en/"
+    }]
+}
+```
+
+Transcription supports the following formats:
+
+* JSON
+* LRC
+* MP3 (Embedded in source MP3 as a SYLT ID3 tag labeled "captions".)
+* SAMI / SMI
+* SRT
+* VTT
+
+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"]`.
+
+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.
+
+## 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`.
+
+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.
+
+---
+
+Maintainers: see [PUBLISHING.md](PUBLISHING.md) for npm trusted publishing setup.

package/cheer.js

@@ -1,37 +1,37 @@
-#!/usr/bin/env node
-
-const
-    cheer = require('./src/index'),
-    getArgsAsObj = () => {
-        const
-            {argv: args} = process,
-            cmds = {},
-            cleanKey = (key) => key.replace(/\-/g, ' ').trim().replace(/ /g, '-');
-        let key = '';
-        
-        // copy arguments into environment data.
-        for (let i = 2; i < args.length; i++) {
-            const
-                arg = args[i];
-
-            if (arg[0] === '-') {
-                if (key) {
-                    cmds[key] = true;
-                }
-                key = cleanKey(arg);
-            } else if (key) {
-                cmds[key] = arg;
-                key = '';
-            } else {
-                cmds[cleanKey(arg)] = true;
-            }
-        }
-
-        if (key) { // in case last option has no value
-            cmds[key] = true;
-        }
-
-        return cmds;
-    };
-
+#!/usr/bin/env node
+
+const
+    cheer = require('./src/index'),
+    getArgsAsObj = () => {
+        const
+            {argv: args} = process,
+            cmds = {},
+            cleanKey = (key) => key.replace(/\-/g, ' ').trim().replace(/ /g, '-');
+        let key = '';
+        
+        // copy arguments into environment data.
+        for (let i = 2; i < args.length; i++) {
+            const
+                arg = args[i];
+
+            if (arg[0] === '-') {
+                if (key) {
+                    cmds[key] = true;
+                }
+                key = cleanKey(arg);
+            } else if (key) {
+                cmds[key] = arg;
+                key = '';
+            } else {
+                cmds[cleanKey(arg)] = true;
+            }
+        }
+
+        if (key) { // in case last option has no value
+            cmds[key] = true;
+        }
+
+        return cmds;
+    };
+
 cheer(getArgsAsObj());