@makefully/dutifully 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.13.0
+
+- Add `packfully` service client for packing images into texture atlases.
+
+## 1.12.1
+
+- Preserve optional script-line `events` through Transcript for timed marker definitions.
+
 ## 1.12.0
 
 - Treat missing `src`/`output` directories as empty instead of failing; create output directories when writing.

package/README.md

@@ -40,7 +40,7 @@ cheerfully({
 });
 ```
 
-## Say (spoken notifications)
+### 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:
 
@@ -109,6 +109,51 @@ This audio file process accepts ffmpeg commandline arguments to perform operatio
 }
 ```
 
+### Packfully
+
+This image-to-atlas service packs PNG/JPG/WebP sprites into texture atlases and downloads atlas PNG(s) plus descriptor file(s).
+
+```javascript
+{
+    "packfully": [{
+        "format": "texturepacker",
+        "src": "./example/sprites/",
+        "output": "./example/atlases/",
+        "options": {
+            "maxWidth": 2048,
+            "maxHeight": 2048,
+            "pot": true,
+            "smart": true,
+            "square": false,
+            "padding": 1,
+            "extrude": 1,
+            "border": 1,
+            "allowRotation": false,
+            "trim": true,
+            "trimThreshold": 0,
+            "prefix": "packed",
+            "scale": 1
+        },
+        "files": {
+            "hero.png": { "trim": false }
+        }
+    }]
+}
+```
+
+Use `exports: ["texturepacker", "createjs"]` (or `format`) to choose one or more atlas descriptors. Supported formats:
+
+* `texturepacker` / `json-hash` / `pixi` / `phaser-hash` — TexturePacker JSON Hash
+* `json-array` / `phaser-array` — TexturePacker JSON Array
+* `createjs` / `easeljs` — CreateJS SpriteSheet JSON
+* `spine` — Spine `.atlas` text
+* `css` — CSS sprite classes
+* `starling` / `sparrow` — Starling/Sparrow XML
+* `unity` — Unity-oriented JSON
+* `godot` — Godot atlas JSON
+
+Spacing: `padding` is empty gap beyond `extrude`; `extrude` is edge-pixel bleed into that gap; `border` is margin from the atlas edge.
+
 ### 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:
@@ -205,9 +250,17 @@ If your scripts include any phrases that should remain unbroken by the captionin
 
 Script lines may include an optional `class` (for example `"title"` or `"stage"`). In VTT exports this becomes a cue class span (`<c.title>…</c>`). In SAMI/SMI the paragraph `Class` is the job language plus `CC` (for example `ENUSCC` for `en-US`); when a speaker and/or script `class` is present, the dialog is wrapped in `<SPAN Class="…">` (for example `Class="todd stage"`). In JSON exports it is included on each caption entry. SRT, LRC, and MP3 SYLT ignore it.
 
+Script lines may also include an optional `events` array for one-shot timed markers. Entries may be:
+
+* a **number** — add to the running absolute time offset (ms)
+* a **string** `"<phrase"` / `">phrase"` — set the offset to just before/after that phrase in the caption; any other string fires that event at the current offset
+* an **object** `{ "event", "time"?, "before"?, "after"? }` — fires `event`; optional fields set the absolute offset (`time` wins over `before` over `after`)
+
+Cheerfully resolves these against caption timings and exports them in parallel using the same caption `format` (`events.json`, `{id}.events.vtt` / `.srt` / `.sami` / `.smi` / `.lrc`, or a separate MP3 SYLT frame with content type `EVENTS` labeled `"events"`).
+
 ## Example
 
-Find an example script in the `./examples/` folder. You can run either `npm run test-elevenlabs` or `npm run test-polly` to create VO tracks in the examples folder that you can then use to try out `npm run test-rhubarb` and `npm run test-transcription`.
+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/`.
 
 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.12.0",
+    "version": "1.13.0",
     "description": "Client tools for Cheerfully service.",
     "main": "./src/index.js",
     "bin": {
@@ -19,6 +19,7 @@
         "test-allosaurus": "node ./cheer.js -service allosaurus",
         "test-elevenlabs": "node ./cheer.js -service elevenlabs",
         "test-ffmpeg": "node ./cheer.js -service ffmpeg",
+        "test-packfully": "node ./cheer.js -service packfully",
         "test-polly": "node ./cheer.js -service polly",
         "test-rasterize": "node ./cheer.js -service rasterize",
         "test-rhubarb": "node ./cheer.js -service rhubarb",
@@ -41,7 +42,10 @@
         "polly",
         "lipsync",
         "transcription",
-        "captions"
+        "captions",
+        "packfully",
+        "atlas",
+        "spritesheet"
     ],
     "author": "Derek Detweiler <derek@makefullystudios.com>",
     "contributors": [

package/src/classes/Packfully.js

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

package/src/classes/Transcript.js

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

package/src/index.js

@@ -6,6 +6,7 @@ const
         allosaurus: LipSync,
         elevenlabs: require('./classes/ElevenLabs'),
         ffmpeg: require('./classes/FFMPEG'),
+        packfully: require('./classes/Packfully'),
         polly: require('./classes/Polly'),
         rasterize: require('./classes/Rasterize'),
         rhubarb: LipSync,