@senseihq/emaki-cli 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/README.md +42 -7
  2. package/package.json +4 -2
  3. package/plugin/.claude-plugin/plugin.json +1 -1
  4. package/plugin/modules/campaign/README.md +10 -3
  5. package/plugin/modules/campaign/day-script.template.md +2 -1
  6. package/plugin/modules/posting-desk/README.md +2 -2
  7. package/plugin/skills/emaki/references/03-content-model.md +7 -4
  8. package/plugin/skills/emaki/references/04-scene-authoring.md +3 -0
  9. package/plugin/skills/emaki/references/05-voice-and-video.md +41 -8
  10. package/plugin/skills/emaki/references/09-publishing.md +5 -2
  11. package/plugin/skills/story-media/SKILL.md +2 -0
  12. package/plugin/skills/story-publish/SKILL.md +18 -4
  13. package/src/api.js +12 -1
  14. package/src/campaign.js +157 -0
  15. package/src/capture.js +69 -33
  16. package/src/carousel.js +91 -0
  17. package/src/day-script.js +66 -0
  18. package/src/desk-client.js +37 -0
  19. package/src/desk-plan.js +57 -0
  20. package/src/films.js +12 -5
  21. package/src/http.js +30 -0
  22. package/src/index.js +161 -3
  23. package/src/init.js +5 -4
  24. package/src/media.js +236 -0
  25. package/src/migrate.js +67 -0
  26. package/src/publish.js +118 -0
  27. package/src/stage.js +107 -0
  28. package/src/stories.js +66 -0
  29. package/src/upload/instagram.js +34 -0
  30. package/src/upload/youtube.js +90 -0
  31. package/src/util.js +7 -0
  32. package/src/voice.js +119 -40
  33. package/src/youtube-text.js +58 -0
  34. package/templates/content/films/measure-the-right-work/film.json +9 -0
  35. package/templates/content/films/measure-the-right-work/look.css +1 -0
  36. package/templates/content/films/measure-the-right-work/timing.en.json +24 -0
  37. package/templates/content/films/measure-the-right-work/timing.es.json +24 -0
  38. package/templates/content/films/measure-the-right-work/voice/en/close.m4a +0 -0
  39. package/templates/content/films/measure-the-right-work/voice/en/groups.m4a +0 -0
  40. package/templates/content/films/measure-the-right-work/voice/en/hook.m4a +0 -0
  41. package/templates/content/films/measure-the-right-work/voice/en/pair.m4a +0 -0
  42. package/templates/content/films/measure-the-right-work/voice/en/problem.m4a +0 -0
  43. package/templates/content/films/measure-the-right-work/voice/es/close.m4a +0 -0
  44. package/templates/content/films/measure-the-right-work/voice/es/groups.m4a +0 -0
  45. package/templates/content/films/measure-the-right-work/voice/es/hook.m4a +0 -0
  46. package/templates/content/films/measure-the-right-work/voice/es/pair.m4a +0 -0
  47. package/templates/content/films/measure-the-right-work/voice/es/problem.m4a +0 -0
  48. package/templates/film/look.css +1 -0
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # @senseihq/emaki-cli
2
2
 
3
- `emaki`: set a project up for motion stories, install the Claude plugin, and run the production steps per film and
4
- per locale.
3
+ `emaki`: set a project up for motion stories, install the Claude plugin, run the production steps per film and per
4
+ locale, and take finished pieces out: stage them for approval, publish them, and run a daily campaign.
5
5
 
6
6
  ```sh
7
7
  npm i -D @senseihq/emaki-cli playwright && npx playwright install chromium
@@ -16,20 +16,55 @@ npx emaki init # sample content, emaki.config.json, film source, /sho
16
16
  | `manifest` | `content/films/index.json` (for the fetch loader) |
17
17
  | `validate [slug]` | files, scene ids, `{{keys}}` in every locale, voice lines, story bodies |
18
18
  | `new <slug> --scenes a,b,c [--title] [--date]` | scaffold a story + film in every locale |
19
+ | `migrate <site> [--locale en]` | move a sensei-hq.com-style site (`src/lib/motion`, `src/lib/content/articles`, `films/` takes) into `content/` and `production/`; never overwrites, then validates |
19
20
  | `sheet <slug> [--locale] [--at scene:t,…]` | contact sheet, both orientations |
20
21
  | `tts-check` | each locale's voice provider and whether it's ready; offline engines on this machine |
21
22
  | `set-voice --locale x --provider p [--opt k=v]` | choose the voice; keys are refused (environment only) |
22
23
  | `voices [--locale] [--provider]` | the voices a provider offers |
23
24
  | `voice <slug> [--locale] [--only 2,5] [--provider] [--opt]` | narration takes from `voice/<locale>.json` |
24
- | `fit <slug> [--locale] [--check]` | scene times fitted to the takes: `timing.<locale>.json` |
25
- | `render <slug> [--locale] [--o both] [--fps 30]` | picture + score + covers |
26
- | `build <slug> [--locale] [--no-captions]` | voice + ducked score, −14 LUFS, captions (.srt/.vtt, burned in) |
25
+ | `fit <slug> [--locale] [--check]` | each narrated scene runs for its take (longer or shorter than designed, never before its content settles): `timing.<locale>.json` |
26
+ | `voice-web <slug> [--locale]` | the site's narration: each take as `voice/<locale>/<scene>.m4a` (mono AAC, -16 LUFS) and its start in `timing.<locale>.json` |
27
+ | `render <slug> [--locale] [--o both] [--fps 30] [--from s] [--to s] [--out file.mp4\|dir] [--music synth\|export\|none] [--audio-only] [--cover-only]` | picture + music + covers; `--from/--to` a stretch of film time, `--out` a file (one layout) or a folder, `--music export` the audio of `production/<slug>/<locale>/<slug>.mp4`, `--audio-only` lays the music on the existing render, `--cover-only` just the covers; survives the dev server reloading mid-capture |
28
+ | `build <slug> [--locale] [--no-captions] [--check] [--out dir]` | voice + ducked music, −14 LUFS, captions (.srt/.vtt, burned in), a chapter per scene embedded, `-web.mp4`, `chapters.txt`, `description.txt`, posters and `-thumb.jpg`; a take that outruns its scene freezes the scene's last frame until it ends (`--check` prints that table and builds nothing) |
29
+ | `stage <slug> [--channels a,b] [--locale] [--dry-run]` | upload a finished piece's media (sha256-checked) and post text to the posting desk, one post per channel, for approval; a film's text is drafted into `content/films/<slug>/post.<locale>.json` on the first run |
30
+ | `stage status [slug]` | report each story's script and what is produced (takes, renders, Short, carousel) to the desk's plan |
31
+ | `stage requests`, `stage reply <id> "text" [--working \| --done]` | read the open motion requests from the desk (with their threads) and answer them |
32
+ | `publish youtube <slug> [--privacy unlisted] [--update id] [--force-new] [--description-mode prepend]` | upload the 16:9 film with chapters, tags, captions and the cover as thumbnail; `--update` refreshes an uploaded video in place |
33
+ | `publish instagram <slug> [--video-url u --cover-url u]` | post the 9:16 film as a Reel; without URLs the files go to the desk and are linked (signed) for an hour |
34
+ | `publish … --dry-run`, `publish youtube\|instagram --verify` | print exactly what would post and send nothing; check the keys read-only and name the account |
35
+ | `carousel <slug…> \| --all` | a campaign day's Instagram carousel, 1080×1350 PNGs from its day script (needs Playwright) |
36
+ | `campaign status [--from] [--days 14]` | what is due, and for each day: story, film, takes, render, Short, carousel, posts |
37
+ | `campaign shortfilm <slug>` | a Short's film (one scene per beat, the voice lines) from its day script's voiceover table |
38
+ | `campaign posted <slug> [--youtube id] [--instagram url] [--x url]` | record where a piece went: the campaign's `published.json` and the story's `social` links |
39
+ | `campaign due [--date]`, `campaign calendar` | one day's piece as JSON (for automation); rewrite `CALENDAR.md` from `calendar.csv` |
27
40
 
28
41
  Voice providers, set per locale in `emaki.config.json` (`default` → language → locale): **offline** `piper`,
29
42
  `kokoro`, `macos` (`say`), `espeak`; **cloud** `elevenlabs`, `openai` (or Azure OpenAI), `azure`, `google`, `polly`
30
43
  (via the `aws` CLI); **a person** `manual`. Keys come from environment variables only.
31
44
 
32
- Needs Node 20.10+, ffmpeg, and Playwright with Chromium for `sheet` and `render`. The same steps are importable as
33
- functions from `@senseihq/emaki-cli` (`project`, `validate`, `voice`, `fit`, `render`, `build`, …).
45
+ After the build. `publish` writes each new link into the story's entry in `content/stories/index.json` (`youtube`
46
+ and `social`) and never replaces one that is there. Published files come from `production/<slug>/<locale>/`
47
+ (`out/<slug>-<locale>-16x9.mp4`, `-9x16.mp4`, `.srt`, `out/description.txt` if you wrote one, and the covers in
48
+ `render/`). A campaign lives in `campaign/` (`calendar.csv`, `days/day-NN-<slug>.md`, `carousels/<slug>/`,
49
+ `published.json`); a day script gives every channel's text for `stage`. Settings in `emaki.config.json`, all
50
+ optional: `campaign` (the folder), `storyUrl` (a story's public link, default `{url}/{locale}/stories/{slug}`), and
51
+ `carousel` (`marks` per topic, `mark`, `footer`, `swipe`, `last`, or a `template` HTML file).
52
+
53
+ Credentials come from environment variables (or CI secrets) only; nothing writes them to a file or prints them:
54
+
55
+ | Variable | For |
56
+ |---|---|
57
+ | `ADMIN_ORIGIN` | the posting desk's site (default: `url` in `content/site.json`); `ADMIN_API` if its API is not at `/api/admin` |
58
+ | `STAGER_CLIENT_ID`, `STAGER_CLIENT_SECRET` | the stager's Cloudflare Access service token: `stage`, and Instagram media for `publish` |
59
+ | `MEDIA_URL_SECRET` | signs the one-hour media links Instagram fetches (the desk's secret); `MEDIA_PATH` if not `/m` |
60
+ | `YT_CLIENT_ID`, `YT_CLIENT_SECRET`, `YT_REFRESH_TOKEN` | YouTube Data API, scopes `youtube.upload` and `youtube.force-ssl` |
61
+ | `IG_USER_ID`, `IG_ACCESS_TOKEN` (`IG_GRAPH_VERSION`, default `v21.0`) | Instagram Graph API, `instagram_content_publish` |
62
+
63
+ Load them from a file that git ignores without writing them anywhere else, e.g. `node --env-file=.env
64
+ node_modules/.bin/emaki stage <slug>` or `set -a; . ./.env; set +a`.
65
+
66
+ Needs Node 20.10+, ffmpeg, and Playwright with Chromium for `sheet`, `render` and `carousel`. The same steps are importable as
67
+ functions from `@senseihq/emaki-cli` (`project`, `validate`, `voice`, `voiceWeb`, `fit`, `render`, `build`, `stage`, `publish`,
68
+ `youtube`, `instagram`, `carousel`, `campaignStatus`, …); every network call takes an injectable `fetch`.
34
69
 
35
70
  MIT © SenecaGlobal
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@senseihq/emaki-cli",
3
- "version": "0.1.0",
4
- "description": "The motion stories command line: set a project up, install the Claude plugin (skills, agents, playbook), and run the production steps (validate, sheet, voice, fit, render, build) per film and locale.",
3
+ "version": "0.1.1",
4
+ "description": "The motion stories command line: set a project up, install the Claude plugin (skills, agents, playbook), run the production steps (validate, sheet, voice, fit, render, build) per film and locale, then stage, publish and run a campaign.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "author": "SenecaGlobal",
@@ -28,6 +28,8 @@
28
28
  "postpublish": "rm -f LICENSE"
29
29
  },
30
30
  "dependencies": {
31
+ "@senseihq/emaki": "0.1.1",
32
+ "@senseihq/emaki-posting": "0.1.1",
31
33
  "sade": "^1.8.1"
32
34
  },
33
35
  "peerDependencies": {
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "emaki",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Build a multilingual site of motion stories (articles, story player and narrated videos from one set of JSON scenes) through a guided, gated program: interview, outline, item cards, pilot, automated batches, review loop.",
5
5
  "author": {
6
6
  "name": "SenecaGlobal"
@@ -9,14 +9,21 @@ A run of short pieces (one a day for N weeks) around a theme. Each day has one s
9
9
  |---|---|
10
10
  | `calendar.csv` | One row per day: date, slug, product/topic, title, the hook line, status. The plan at a glance. |
11
11
  | `days/day-NN-<slug>.md` | The day script, from `day-script.template.md`: the voiceover table (one line per scene), the YouTube title and description, the Instagram carousel (6–7 slides) and caption, the X post and thread, and the posting step. |
12
- | `carousels/<slug>/*.png` | Carousel slides, rendered from the film's scenes (`emaki sheet` frames, or a dedicated carousel layout). |
12
+ | `carousels/<slug>/*.png` | Carousel slides: `emaki carousel <slug>` renders the day script's numbered slides (1080×1350); `emaki sheet` frames work too. |
13
+ | `published.json` | Where each piece was posted (`emaki campaign posted`). |
14
+ | `CALENDAR.md` | The calendar as a readable table (`emaki campaign calendar`). |
15
+
16
+ The folder is `campaign/` at the project root, or wherever `"campaign"` in `emaki.config.json` points.
13
17
 
14
18
  ## Flow
15
19
 
16
20
  1. Plan the calendar with the owner (topics, order, cadence, which days are Shorts vs. articles only).
17
21
  2. Write the day scripts in batches of 5–7; the owner approves the batch.
18
- 3. For each day: build the story (the orchestrator's per-item loop), voice, render the 9:16 (and 16:9), build.
19
- 4. Stage it to the posting desk; the owner approves; the scheduled poster publishes on the day.
22
+ 3. For each day: `emaki campaign shortfilm <slug>` (scenes and voice lines from the voiceover table), build the story
23
+ (the orchestrator's per-item loop), voice, render the 9:16 (and 16:9), build; `emaki carousel <slug>`.
24
+ 4. `emaki stage <slug>` (every channel's text from the day script); the owner approves; the scheduled poster publishes
25
+ on the day. `emaki campaign status` shows what each day still needs; `emaki campaign due` gives today's piece as
26
+ JSON for automation.
20
27
  5. Weekly: read the numbers back into the calendar (views, saves, clicks to the article) and adjust the next batch.
21
28
 
22
29
  Translations: one day script per locale (`days/<locale>/...`) or a column per locale in the voiceover table; the
@@ -38,4 +38,5 @@ voiceover per scene; captions burned in. The voice lines below are the copy of r
38
38
 
39
39
  ## 5 · Posting
40
40
 
41
- After the build: stage to the posting desk; the owner approves; the scheduled job posts on the day and records the links.
41
+ After the build: `emaki carousel <slug>`, then `emaki stage <slug>`; the owner approves on the desk; the scheduled job
42
+ posts on the day and records the links.
@@ -16,12 +16,12 @@ SvelteKit adapter (`/sveltekit`: the guard hook and route handlers), the D1 migr
16
16
  |---|---|---|
17
17
  | Identity at the edge | Every `/admin`, `/api/admin`, preview URL sits behind an identity proxy (Cloudflare Access, Google IAP, Azure AD App Proxy, oauth2-proxy). The app **re-verifies** the signed identity header (signature, audience, issuer, expiry, key id) and fails closed. | `verifyCaller`, `callerOf`; `/sveltekit` `postingHandle` |
18
18
  | Roles | `admin` (people, by email), `stager` (the production machine's service token: uploads media and text), `poster` (the scheduled job's service token: reads the queue, records results). A matrix allows each role only its routes and methods. | `allowed` |
19
- | Staging | The production machine uploads each post's media (sha256 checked) and text per channel. | `desk.api` → `stage`, `media/<key>` (PUT) |
19
+ | Staging | The production machine uploads each post's media (sha256 checked) and text per channel: `emaki stage <slug>`. | `desk.api` → `stage`, `media/<key>` (PUT) |
20
20
  | Approval bound to content | An approval stores the sha256 of the canonical post (channel + text + media hashes). Restaging anything changes the hash, so the approval no longer matches. | `contentSha`, `PostingStore.approve` |
21
21
  | The queue | A post is due only when the story's publish date has passed in the site's time zone, it is approved, the hash still matches, and posting isn't paused (it starts paused). | `due`, `desk.api` → `queue` |
22
22
  | Media to platforms | Platforms fetch media by URL: short-lived signed URLs (HMAC, one hour) on a public route that serves nothing else. | `signMedia`, `desk.signedMedia`; `/sveltekit` `mediaRoute` |
23
23
  | The poster | A scheduled job (GitHub Actions in a protected environment holding the platform keys) reads the queue, re-checks each file's hash, posts, and records the link. `POST_MODE=dry-run` until you trust it; YouTube starts `private`. | `poster/post.py` (see the package README for the workflow) |
24
- | Planning | Make next (pull a story forward; the rest shift a slot), production status from the production machine, and a request thread per story ("ask for a change"), which the producer answers. | `desk.desk` (`plan`, `makeNext`, `request`, `reply`) |
24
+ | Planning | Make next (pull a story forward; the rest shift a slot), production status from the production machine (`emaki stage status`), and a request thread per story ("ask for a change"), which the producer answers (`emaki stage requests`, `emaki stage reply`). | `desk.desk` (`plan`, `makeNext`, `request`, `reply`) |
25
25
  | Audit | Every approve, revoke, pause, post and failure is logged with who and when. | `migrations/0001_posting.sql`, `desk.desk.plan().audit` |
26
26
 
27
27
  ## Setup checklist (adapt to your stack)
@@ -44,19 +44,22 @@ Rules:
44
44
 
45
45
  | File | Contents |
46
46
  |---|---|
47
- | `film.json` | `title`, `look` (one paragraph describing the visual language, used by builders), `background`, `palette`, `fonts`, `scenes` [`id`, `name`, `dur` (design seconds incl. a 1.5–2 s end hold), `desc`], optional `cover` {scene, at}. The last scene is `close`. |
48
- | `look.css` | The film's tokens and shared classes (`.card`, `.tag`, `.words`, `.line`, `.sub`, `.eyebrow`, `.ground`, `.cam`, `.art`). Scoped to each scene's shadow root. One look per site is the norm; copy it per film. |
47
+ | `film.json` | `title`, `look` (one paragraph describing the visual language, used by builders), `background`, `palette`, `dark` (`background`, `palette`: the dark look; without it the film is always light), `fonts`, `scenes` [`id`, `name`, `dur` (design seconds incl. a 1.5–2 s end hold), `desc`, `settle` (JS scenes: when the motion is over, so `fit` never ends a narrated scene before it)], optional `cover` {scene, at}. The last scene is `close`. |
48
+ | `look.css` | The film's tokens and shared classes (`.card`, `.tag`, `.words`, `.line`, `.sub`, `.eyebrow`, `.ground`, `.cam`, `.art`). Scoped to each scene's shadow root. Dark tokens go under `#stage[data-mode="dark"]` (only with a `dark` block in film.json). One look per site is the norm; copy it per film. |
49
49
  | `scene-<id>.json` | The scene as data (components, tracks, css, portrait, locales). See 04-scene-authoring.md. |
50
50
  | `scene-<id>.js` + `shared.js` | The escape hatch for a scene the JSON catalogue cannot express yet (procedural drawing). Same rules: pure `render(t)`. Prefer adding a component or effect to the renderer over writing JS. |
51
51
  | `score.js` | The sound: action tones timed to scene events (`T.<scene> + seconds`). |
52
52
  | `strings/<locale>.json` | Every on-screen word, keyed `scene.part` (`hook.line`, `signs.2`). Inline `<b>`/`<em>` allowed in strings used by `raw`/`html` text. |
53
53
  | `voice/<locale>.json` | One line per scene, in order: `{ scene, text, say }`; `say` is the TTS spelling when it differs (acronyms, names). The text is also the caption. |
54
- | `timing.json` / `timing.<locale>.json` | Written by `emaki fit`: per scene `dur` (stretched to fit that locale's take) and hand-set `holds` [[at, seconds]] (pause the clock at a beat). The site reads the locale's file. |
54
+ | `timing.json` / `timing.<locale>.json` | Written by `emaki fit`: per scene `dur` (that locale's running time: lead + take + tail, never before the scene's content settles; absent means the design time) and hand-set `holds` [[at, seconds]] (pause the clock at a beat); `emaki voice-web` adds `voice`, where the scene's narration starts. The site reads the locale's file. |
55
+ | `voice/<locale>/<scene>.m4a` | The site's narration, encoded from the takes by `emaki voice-web`. A scene with a `voice` start plays it when sound is on. |
55
56
 
56
57
  ## Production (not deployed)
57
58
 
58
59
  `production/<slug>/<locale>/takes/take-NN.wav` · `render/<slug>-<locale>-16x9.mp4`, `-9x16.mp4`, `score.wav`,
59
- covers · `out/` final videos + `.vtt`/`.srt` · `sheets/` contact sheets.
60
+ covers · `out/` final videos (chapters embedded), `-web.mp4`, `.vtt`/`.srt`, `chapters.txt`, `description.txt`,
61
+ `poster.jpg`, `poster-vertical.jpg`, `-thumb.jpg` · `sheets/` contact sheets · `<slug>.mp4` an exported film whose
62
+ audio `render --music export` lays under the picture.
60
63
 
61
64
  ## Naming
62
65
 
@@ -18,6 +18,9 @@ every frame. Read the starter's `scene-*.json` before writing a new one.
18
18
  Symmetric layouts are centred on the board's art region. Repeated cards share one size.
19
19
  - The **close** scene is the punchline card: title (3–9 words) + bar + one-line sub on the paper, the brand mark on
20
20
  the right; no card behind it, no URL. Its final frame is the cover (thumbnail, og:image, poster).
21
+ - **Colour comes from the look's tokens** (`var(--main)`, `var(--accent)`, `var(--tile)`, `var(--hair)`, …), never a
22
+ literal hex: the film's dark look redefines the tokens under `#stage[data-mode="dark"]`, and a literal stays put. Soft
23
+ shadows (`rgba(0,0,0,.07)`) are the exception; they read on both.
21
24
 
22
25
  ## The file
23
26
 
@@ -1,7 +1,7 @@
1
1
  # Voice, timing and video
2
2
 
3
- Optional module; the site works without it (figures and the player are silent unless the viewer turns on the
4
- action tones). Needs ffmpeg, Playwright (Chromium), and one voice provider per locale.
3
+ Optional module; the site works without it (figures and the player are silent unless the viewer turns on sound).
4
+ The same takes narrate the site and the videos. Needs ffmpeg, Playwright (Chromium), and one voice provider per locale.
5
5
 
6
6
  ## Choosing the voice provider
7
7
 
@@ -38,21 +38,53 @@ emaki voice <slug> --locale es --provider macos # one-off override (e.g. a d
38
38
 
39
39
  ```sh
40
40
  emaki voice <slug> --locale en # takes from voice/en.json → production/<slug>/en/takes/
41
- emaki fit <slug> --locale en # timing.en.json: scenes stretched to fit their takes
41
+ emaki fit <slug> --locale en # timing.en.json: each narrated scene runs for its take
42
+ emaki voice-web <slug> --locale en # the site's narration: voice/en/<scene>.m4a + each scene's voice start
42
43
  emaki render <slug> --locale en # 16:9 + 9:16 picture with the score, covers
43
44
  emaki build <slug> --locale en # voice laid at each scene start, score ducked, -14 LUFS, captions
44
45
  ```
45
46
 
47
+ Render, for the moments in between:
48
+
49
+ ```sh
50
+ emaki render <slug> --o portrait --from 12 --to 20 --out preview.mp4 # one stretch of film time, to a file
51
+ emaki render <slug> --audio-only # lay a changed score on the existing render; no frames captured
52
+ emaki render <slug> --cover-only # refresh just the covers
53
+ emaki render <slug> --music export # the audio of production/<slug>/<locale>/<slug>.mp4 (or --music none)
54
+ emaki build <slug> --check # each scene's take, freeze and start; builds nothing
55
+ ```
56
+
57
+ A render survives the dev server reloading the page mid-capture (someone saving a file): it waits for the show to
58
+ come back and repeats the frame.
59
+
46
60
  - **Voice script**: 150 words a minute; each line ≤ the scene's length minus 2 s (lead 0.6 s + tail 1.2 s), or the
47
- scene stretches. Write for the ear: short sentences, the scene's point first, numbers spoken as words where it helps.
61
+ scene runs longer. Write for the ear: short sentences, the scene's point first, numbers spoken as words where it helps.
48
62
  Put tricky pronunciations in `say` (`"Sen-say"`, `"S-Q-L"`). Same voice per locale across the site.
49
- - **Fit vs retime**: `fit` lengthens a scene so it holds its last picture until the voice ends (fine for most). When
50
- a beat must land on a word, retime the scene's track times (and the matching `T.<scene>` times in score.js) or add
63
+ - **Fit vs retime**: `fit` runs each narrated scene for lead + take + tail: longer than its design (it holds its last
64
+ picture until the voice ends) or shorter (it ends with the voice), but never before its content has settled, the
65
+ end of its last track (the camera push and the closing mark's breathing are background and do not count). A JS
66
+ scene has no tracks to read: give `settle` (seconds) on its film.json entry, or it keeps its design length when
67
+ the voice is shorter. When a beat must land on a word, retime the scene's track times (and the matching `T.<scene>` times in score.js) or add
51
68
  a hold `[[at, seconds]]` in `timing.<locale>.json` to pause the clock at that moment.
69
+ - **Narration on the site**: `voice-web` encodes each take as `content/films/<slug>/voice/<locale>/<scene>.m4a`
70
+ (mono AAC 64k, -16 LUFS, about 8 KB a second) and records `voice` (the lead, 0.6 s) per scene in
71
+ `timing.<locale>.json`. With sound on, the story player speaks the scene on screen from where the picture is and
72
+ ducks the score under it; an article figure's sound button plays its scene's take with its slice of the score.
73
+ Commit the `.m4a` files with the story; rerun `voice-web` after re-recording a take (a scene whose take is gone
74
+ loses its file). Vite apps glob them as URLs (`voice` in the source, written by `emaki init`); the fetch loader
75
+ reads them from the published content folder.
52
76
  - **Captions** come from the voice text (`.vtt` for the site player, `.srt` burned into social cuts). Review them in
53
77
  every locale.
78
+ - **Freeze, the safety net**: when a take is longer than its scene in the render (a take re-recorded after the render,
79
+ or `fit` skipped), `build` freezes the scene's last frame until the voice has finished, loops the score under the
80
+ hold and moves every later scene along. `build --check` shows it in the `ext` column. A freeze is a still picture;
81
+ `fit` and a fresh render give the scene its ambient motion instead.
54
82
  - **Covers**: the last frame of the close scene, per orientation and locale; the 16:9 one is copied to the site's
55
- covers folder (`coversDir`) as the og:image.
83
+ covers folder (`coversDir`) as the og:image. `build` turns them into `poster.jpg`, `poster-vertical.jpg` and
84
+ `<slug>-<locale>-thumb.jpg` (1280x720, YouTube's custom thumbnail).
85
+ - **Chapters**: one per scene is embedded in each final MP4; `chapters.txt` is YouTube's list (from 0:00, every
86
+ chapter ≥ 10 s, short scenes folded in), and `description.txt` is title + chapters + the story link
87
+ (`<site url>/<locale>/stories/<slug>`, or `storyUrl` in `emaki.config.json`, e.g. `{site}/articles/{slug}`).
56
88
  - **Credentials**: every provider key lives in the environment only; never in files, never committed, never printed,
57
89
  never pasted into chat. Each take run records which provider and voice made it (`takes/provider.json`).
58
90
 
@@ -61,4 +93,5 @@ emaki build <slug> --locale en # voice laid at each scene start, score duc
61
93
  - Durations: film 60–90 s, short 30–60 s. Loudness -14 LUFS, true peak ≤ -1.5 dB.
62
94
  - Watch the first and last 5 s of every render; spot-check each scene change for a frozen or blank frame.
63
95
  - 9:16 safe area: nothing important in the bottom 300 px (platform UI) or top 150 px.
64
- - File names: `<slug>-<locale>-16x9.mp4`, `-9x16.mp4`, `.vtt`, `.srt`, `cover-16x9.jpg`.
96
+ - File names: `<slug>-<locale>-16x9.mp4`, `-9x16.mp4`, `-web.mp4` (keep it under 25 MiB for static hosting),
97
+ `.vtt`, `.srt`, `cover-16x9.jpg`, `-thumb.jpg`, `poster.jpg`, `chapters.txt`, `description.txt`.
@@ -4,8 +4,11 @@
4
4
  live on their day in the site's time zone. Drafts are visible only in preview/admin.
5
5
  - **Posting desk** (`modules/posting-desk/`): private admin with preview, reorder ("make next"), change requests and
6
6
  approval bound to a content hash; a scheduled poster publishes approved media to YouTube, Instagram and X. Start
7
- paused, dry-run, YouTube private.
7
+ paused, dry-run, YouTube private. The producing machine stages with `emaki stage <slug>` (and reports
8
+ `emaki stage status`, answers `emaki stage requests` / `emaki stage reply`).
9
+ - **Direct**: `emaki publish youtube|instagram <slug>` (`--verify`, `--dry-run` first) posts without the desk and records
10
+ the link in the stories index.
8
11
  - **Campaign** (`modules/campaign/`): a calendar of daily shorts with a day script per day (voice table + channel copy),
9
- built with the same per-item loop.
12
+ built with the same per-item loop: `emaki campaign shortfilm`, `emaki carousel`, `emaki stage`, `emaki campaign status`.
10
13
  - **Analytics**: per story and locale: views, read depth, player starts, sound-on rate, video completion; feed the
11
14
  numbers into the next batch's priorities.
@@ -28,6 +28,8 @@ provider per locale (the `emaki` CLI's TTS providers). Never ask for, print or s
28
28
  recording list for a person). Report each take's length; for manual takes, wait for the files.
29
29
  3. `emaki fit <slug> --locale <l>`; read the table. If a beat must land on a word, retime the
30
30
  scene's tracks (and `score.js`) or add a hold in `timing.<l>.json`, then fit again.
31
+ Then `emaki voice-web <slug> --locale <l>` so the site's player and figures speak the same takes (commit the
32
+ `voice/<l>/*.m4a` files and `timing.<l>.json` with the story).
31
33
  4. `emaki render <slug> --locale <l> --o both` (picture + score + covers; the 16:9 cover goes to the
32
34
  site's covers folder).
33
35
  5. `emaki build <slug> --locale <l>` (voice, ducked score, -14 LUFS, captions).
@@ -16,7 +16,21 @@ metadata:
16
16
  3. **Posting desk** (only if in scope): follow `modules/posting-desk/README.md`. Ask which identity proxy, database,
17
17
  object storage and scheduler the organisation uses; port the reference logic; set it up paused, dry-run,
18
18
  YouTube private; test the approval-voids-on-change path; go live one channel at a time with the owner.
19
- 4. **Campaign** (only if in scope): follow `modules/campaign/README.md`: plan the calendar with the owner, write day
20
- scripts in batches for approval, build each day's story with `story-build` (shorts) and `story-media`, stage for
21
- approval.
22
- 5. Record what was released in `project/changelog.md` and hand over the runbook (how to add a story, approve, post).
19
+ From the producing machine: `emaki stage <slug> --dry-run` (read the posts), then `emaki stage <slug>` (uploads
20
+ the media with its sha256 and stages each channel; a film's text is drafted into
21
+ `content/films/<slug>/post.<locale>.json` on the first run: have the owner read it, then stage again);
22
+ `emaki stage status` keeps the desk's plan current; `emaki stage requests` and
23
+ `emaki stage reply <id> "…" --working|--done` answer the owner's motion requests.
24
+ 4. **Straight to a platform** (no desk; only when the owner asks): `emaki publish youtube|instagram --verify` (names
25
+ the account), `emaki publish <channel> <slug> --dry-run`, show the owner the output, then run it without
26
+ `--dry-run`. YouTube stays `--privacy unlisted` until the owner says public; a film already on YouTube is refreshed
27
+ with `--update <id>`, never uploaded twice. The link goes into `content/stories/index.json`.
28
+ 5. **Campaign** (only if in scope): follow `modules/campaign/README.md`: plan the calendar with the owner, write day
29
+ scripts in batches for approval, `emaki campaign shortfilm <slug>` for each day's Short, build it with
30
+ `story-build` and `story-media` (`--o portrait`), `emaki carousel <slug>`, then `emaki stage <slug>`.
31
+ `emaki campaign status` shows what each day still needs; `emaki campaign posted <slug> --youtube … --x …` records
32
+ links posted by hand.
33
+ 6. Keys: never ask for, print or store one. Name the environment variable that is missing (`STAGER_CLIENT_ID`,
34
+ `STAGER_CLIENT_SECRET`, `MEDIA_URL_SECRET`, `YT_CLIENT_ID`, `YT_CLIENT_SECRET`, `YT_REFRESH_TOKEN`, `IG_USER_ID`,
35
+ `IG_ACCESS_TOKEN`) and stop until the owner has set it.
36
+ 7. Record what was released in `project/changelog.md` and hand over the runbook (how to add a story, approve, post).
package/src/api.js CHANGED
@@ -1,9 +1,20 @@
1
1
  // The same steps as the CLI, as functions (for scripts and CI): project() reads emaki.config.json and content/.
2
2
  export { project, SIZES, SUFFIX } from './config.js'
3
3
  export { manifest, validate, validateFilm, validateStory, newFilm, keysIn } from './films.js'
4
- export { voice, fit, build, captions, ttsCheck, setVoice, listVoices, takesFor } from './voice.js'
4
+ export { voice, voiceWeb, fit, build, captions, ttsCheck, setVoice, listVoices, takesFor } from './voice.js'
5
5
  export { sheet, render, openSite } from './capture.js'
6
6
  export { PROVIDERS, OFFLINE, provider, voiceConfig, TTSError } from './tts.js'
7
7
  export { installPlugin, installSkills, installAgents, listSkills, listAgents, parseFrontmatter } from './plugin.js'
8
8
  export { init, detectFramework } from './init.js'
9
+ export { migrate } from './migrate.js'
9
10
  export { MotionError } from './util.js'
11
+ export { stage, postsFor, pngToJpeg } from './stage.js'
12
+ export { deskClient } from './desk-client.js'
13
+ export { storyFor, storyUrl, filmFiles, recordLinks } from './stories.js'
14
+ export { productionStatus, deskRequests, deskReply, pieceStatus } from './desk-plan.js'
15
+ export { youtube } from './upload/youtube.js'
16
+ export { instagram } from './upload/instagram.js'
17
+ export { publish } from './publish.js'
18
+ export { chapters, mergeDescription, youtubeDescription, scenePlan } from './youtube-text.js'
19
+ export { parseCsv, todayIn, calendarRows, campaignStatus, campaignDue, campaignPosted, shortFilm, campaignCalendar } from './campaign.js'
20
+ export { carousel, carouselSlides, slideHtml } from './carousel.js'
@@ -0,0 +1,157 @@
1
+ // emaki campaign status | shortfilm | posted | due | calendar: a daily series around a theme, from the command line.
2
+ // Sources: <campaign>/calendar.csv (one row per day: the website's date,product,theme,title,status,script or the
3
+ // plugin template's date,day,slug,topic,title,…), <campaign>/days/*.md (the day scripts), content/stories/index.json
4
+ // and <campaign>/published.json (where each piece was posted). <campaign> is emaki.config.json "campaign".
5
+ import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
6
+ import { join, relative } from 'node:path'
7
+ import { SUFFIX } from './config.js'
8
+ import { beatsOf, campaignDir, dayScriptPath, slugOfScript } from './day-script.js'
9
+ import { newFilm } from './films.js'
10
+ import { filmFiles, recordLinks, storiesIndex, storyUrl } from './stories.js'
11
+ import { die, exists, load, save } from './util.js'
12
+
13
+ /** Rows of a CSV with a header line, as objects. Quoted fields may hold commas, newlines and "" quotes. */
14
+ export function parseCsv(text) {
15
+ const rows = []
16
+ let row = [], cell = '', quoted = false
17
+ for (let i = 0; i < text.length; i++) {
18
+ const c = text[i]
19
+ if (quoted) {
20
+ if (c === '"' && text[i + 1] === '"') { cell += '"'; i++ }
21
+ else if (c === '"') quoted = false
22
+ else cell += c
23
+ } else if (c === '"') quoted = true
24
+ else if (c === ',') { row.push(cell); cell = '' }
25
+ else if (c === '\n' || c === '\r') {
26
+ if (c === '\r' && text[i + 1] === '\n') i++
27
+ row.push(cell); rows.push(row); row = []; cell = ''
28
+ } else cell += c
29
+ }
30
+ if (cell || row.length) { row.push(cell); rows.push(row) }
31
+ const [head = [], ...body] = rows.filter((r) => r.some((x) => x !== ''))
32
+ return body.map((r) => Object.fromEntries(head.map((h, i) => [h.trim(), r[i] ?? ''])))
33
+ }
34
+
35
+ /** Today (YYYY-MM-DD) in a time zone. */
36
+ export const todayIn = (timeZone = 'UTC', now = new Date()) =>
37
+ new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(now)
38
+ const siteToday = (p) => todayIn(p.site.timeZone ?? 'UTC')
39
+
40
+ /** The calendar, one normalised row per day: { date, topic, theme, title, slug, script (path or null) }. */
41
+ export function calendarRows(p, locale = p.site.defaultLocale) {
42
+ const f = join(campaignDir(p), 'calendar.csv')
43
+ if (!exists(f)) die(`no ${p.rel(f)}; start one from the plugin's modules/campaign/calendar.csv`)
44
+ return parseCsv(readFileSync(f, 'utf-8')).map((r) => {
45
+ const slug = r.slug || (r.script ? slugOfScript(r.script) : null)
46
+ const named = r.script ? join(campaignDir(p), r.script) : null
47
+ const script = named && exists(named) ? named : slug ? dayScriptPath(p, slug, locale) : null
48
+ return { date: r.date, topic: r.product ?? r.topic ?? '', theme: r.theme ?? '', title: r.title ?? '', slug, script }
49
+ })
50
+ }
51
+
52
+ const ledgerPath = (p) => join(campaignDir(p), 'published.json')
53
+ const ledger = (p) => (exists(ledgerPath(p)) ? load(ledgerPath(p)) : {})
54
+ const stories = (p) => new Set((exists(storiesIndex(p)) ? load(storiesIndex(p)) : []).map((e) => e.slug))
55
+ const pngs = (dir) => (exists(dir) ? readdirSync(dir).filter((n) => n.endsWith('.png')).length : 0)
56
+
57
+ /** What is due from a date (default today, in the site's time zone), and for each day what exists. */
58
+ export function campaignStatus(p, { from, days = 14, locale = p.site.defaultLocale } = {}) {
59
+ from ??= siteToday(p)
60
+ const known = stories(p), led = ledger(p)
61
+ return calendarRows(p, locale).filter((r) => r.date >= from).slice(0, Number(days)).map((r) => {
62
+ const s = r.slug, takes = s ? p.prod(s, locale, 'takes') : null, posted = (s && led[s]) || {}
63
+ return {
64
+ date: r.date, topic: r.topic, title: r.title, slug: s,
65
+ story: Boolean(s && known.has(s)), script: Boolean(r.script),
66
+ film: Boolean(s && exists(join(p.films, s, 'film.json'))),
67
+ takes: takes && exists(takes) ? readdirSync(takes).filter((n) => /^take-\d+\./.test(n)).length : 0,
68
+ render: Boolean(s && exists(p.prod(s, locale, 'render', `${s}-${locale}-${SUFFIX.portrait}.mp4`))),
69
+ built: Boolean(s && filmFiles(p, s, locale).tall),
70
+ carousel: s ? pngs(join(campaignDir(p), 'carousels', s)) : 0,
71
+ posts: { youtube: Boolean(posted.youtube), instagram: Boolean(posted.instagram), x: Boolean(posted.x) }
72
+ }
73
+ })
74
+ }
75
+
76
+ /** One day's piece as JSON, for automation (default today in the site's time zone). */
77
+ export function campaignDue(p, { date, locale = p.site.defaultLocale } = {}) {
78
+ date ??= siteToday(p)
79
+ const r = calendarRows(p, locale).find((x) => x.date === date)
80
+ if (!r) die(`nothing scheduled on ${date}`)
81
+ const s = r.slug
82
+ return {
83
+ date, topic: r.topic, title: r.title, slug: s,
84
+ script: r.script ? p.rel(r.script) : null,
85
+ story: s ? storyUrl(p, s, locale) : null,
86
+ short: s ? p.rel(filmFiles(p, s, locale).expect.tall) : null,
87
+ carousel: s ? p.rel(join(campaignDir(p), 'carousels', s)) : null,
88
+ posted: (s && ledger(p)[s]) || {}
89
+ }
90
+ }
91
+
92
+ /** Records where a piece was posted: <campaign>/published.json and the story's social links (replacing them). */
93
+ export function campaignPosted(p, slug, links = {}, { today } = {}) {
94
+ const ip = storiesIndex(p)
95
+ const entry = (exists(ip) ? load(ip) : []).find((e) => e.slug === slug)
96
+ if (!entry) die(`${slug} is not in ${p.rel(ip)}`)
97
+ const vals = Object.fromEntries(['youtube', 'instagram', 'x'].filter((k) => links[k]).map((k) => [k, links[k]]))
98
+ if (!Object.keys(vals).length) die('nothing to record: pass --youtube ID, --instagram URL and/or --x URL')
99
+ const led = ledger(p)
100
+ led[slug] = { ...led[slug], ...vals, updated: today ?? siteToday(p) }
101
+ save(ledgerPath(p), led)
102
+ const yt = vals.youtube && !/^https?:/.test(vals.youtube)
103
+ ? (entry.video === 'short' ? `https://www.youtube.com/shorts/${vals.youtube}` : `https://www.youtube.com/watch?v=${vals.youtube}`)
104
+ : vals.youtube
105
+ recordLinks(p, slug, { youtube: yt, instagram: vals.instagram, x: vals.x }, { overwrite: true })
106
+ return led[slug]
107
+ }
108
+
109
+ /**
110
+ * Sets up a Short's film from its day script: one scene per voiceover beat (the on-screen column is the scene id when
111
+ * it is one, else beat-N; the last beat is the close), the voice lines from the table, 6 s per scene until
112
+ * `emaki fit` times them to the takes. An existing story keeps its index entry and body; an existing film is refused.
113
+ */
114
+ export function shortFilm(p, slug, { locale = p.site.defaultLocale } = {}) {
115
+ const f = dayScriptPath(p, slug, locale)
116
+ if (!f) die(`no day script for ${slug} in ${p.rel(join(campaignDir(p), 'days'))}/`)
117
+ if (exists(join(p.films, slug))) die(`${p.rel(join(p.films, slug))} already exists; edit its film.json and voice/${locale}.json`)
118
+ const md = readFileSync(f, 'utf-8'), beats = beatsOf(md)
119
+ if (!beats.length) die(`${p.rel(f)} has no voiceover table (| # | Voiceover | On screen |)`)
120
+ const seen = new Set()
121
+ const ids = beats.map((b, i) => {
122
+ let id = i === beats.length - 1 ? 'close' : /^[a-z][a-z0-9-]*$/.test(b.screen) && b.screen !== 'close' ? b.screen : `beat-${b.n}`
123
+ while (seen.has(id)) id = `${id}-${b.n}`
124
+ seen.add(id)
125
+ return id
126
+ })
127
+ const title = md.match(/^# Day \d+ · .+? · .+?: (.+)$/m)?.[1]?.trim()
128
+ newFilm(p, slug, { scenes: ids.join(','), title })
129
+ const fp = join(p.films, slug, 'film.json'), film = load(fp)
130
+ film.scenes = film.scenes.map((s, i) => ({ ...s, name: beats[i].screen.slice(0, 40), dur: 6 }))
131
+ save(fp, film)
132
+ save(join(p.films, slug, 'voice', `${locale}.json`), beats.map((b, i) => ({ scene: ids[i], text: b.text, say: null })))
133
+ return { slug, scenes: ids.length, path: p.rel(fp) }
134
+ }
135
+
136
+ const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'], MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
137
+ const dayLabel = (iso) => { const d = new Date(iso + 'T00:00:00Z'); return `${DAYS[d.getUTCDay()]} ${MONTHS[d.getUTCMonth()]} ${String(d.getUTCDate()).padStart(2, '0')}` }
138
+
139
+ /** Rewrites <campaign>/CALENDAR.md from calendar.csv: a section per week, a row per day, links to the day scripts. */
140
+ export function campaignCalendar(p) {
141
+ const rows = calendarRows(p), dir = campaignDir(p)
142
+ if (!rows.length) die('calendar.csv has no days')
143
+ const t0 = Date.parse(rows[0].date + 'T00:00:00Z')
144
+ const md = ['# Campaign calendar', '', `${rows.length} days, ${rows[0].date} → ${rows.at(-1).date}. Expanded: ${rows.filter((r) => r.script).length}. Edit calendar.csv, then \`emaki campaign calendar\` to rewrite this file.`]
145
+ let week = 0
146
+ for (const r of rows) {
147
+ const wk = Math.floor((Date.parse(r.date + 'T00:00:00Z') - t0) / 86400000 / 7) + 1
148
+ if (wk !== week) {
149
+ week = wk
150
+ md.push('', `## Week ${wk} · ${r.date} · ${r.topic}${r.theme ? `: ${r.theme}` : ''}`, '', '| Date | Title | |', '|---|---|---|')
151
+ }
152
+ md.push(`| ${dayLabel(r.date)} | ${r.title} | ${r.script ? `[script](${relative(dir, r.script)})` : ''} |`)
153
+ }
154
+ const out = join(dir, 'CALENDAR.md')
155
+ writeFileSync(out, md.join('\n') + '\n')
156
+ return { path: p.rel(out), days: rows.length }
157
+ }