@senseihq/emaki-cli 0.0.0-stage → 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.
- package/LICENSE +21 -0
- package/README.md +69 -2
- package/package.json +44 -4
- package/plugin/.claude-plugin/plugin.json +19 -0
- package/plugin/PLAYBOOK.md +137 -0
- package/plugin/README.md +51 -0
- package/plugin/agents/fact-checker.md +28 -0
- package/plugin/agents/localizer.md +34 -0
- package/plugin/agents/scene-builder.md +43 -0
- package/plugin/agents/story-planner.md +42 -0
- package/plugin/agents/story-writer.md +34 -0
- package/plugin/agents/visual-reviewer.md +33 -0
- package/plugin/modules/campaign/README.md +30 -0
- package/plugin/modules/campaign/calendar.csv +2 -0
- package/plugin/modules/campaign/day-script.template.md +42 -0
- package/plugin/modules/posting-desk/README.md +37 -0
- package/plugin/skills/emaki/SKILL.md +107 -0
- package/plugin/skills/emaki/references/01-interview.md +68 -0
- package/plugin/skills/emaki/references/02-architecture.md +69 -0
- package/plugin/skills/emaki/references/03-content-model.md +68 -0
- package/plugin/skills/emaki/references/04-scene-authoring.md +99 -0
- package/plugin/skills/emaki/references/05-voice-and-video.md +97 -0
- package/plugin/skills/emaki/references/06-i18n.md +37 -0
- package/plugin/skills/emaki/references/07-quality-gates.md +44 -0
- package/plugin/skills/emaki/references/08-feedback-loop.md +32 -0
- package/plugin/skills/emaki/references/09-publishing.md +14 -0
- package/plugin/skills/story-build/SKILL.md +37 -0
- package/plugin/skills/story-localize/SKILL.md +24 -0
- package/plugin/skills/story-media/SKILL.md +38 -0
- package/plugin/skills/story-publish/SKILL.md +36 -0
- package/plugin/skills/story-review/SKILL.md +29 -0
- package/plugin/templates/brief.md +32 -0
- package/plugin/templates/change-request.md +7 -0
- package/plugin/templates/changelog.md +4 -0
- package/plugin/templates/decisions.md +5 -0
- package/plugin/templates/glossary.md +4 -0
- package/plugin/templates/item-card.md +34 -0
- package/plugin/templates/outline.md +19 -0
- package/plugin/templates/review-sheet.md +12 -0
- package/plugin/templates/style-guide.md +21 -0
- package/plugin/templates/tracker.md +11 -0
- package/src/api.js +20 -0
- package/src/campaign.js +157 -0
- package/src/capture.js +205 -0
- package/src/carousel.js +91 -0
- package/src/config.js +32 -0
- package/src/day-script.js +66 -0
- package/src/desk-client.js +37 -0
- package/src/desk-plan.js +57 -0
- package/src/films.js +152 -0
- package/src/http.js +30 -0
- package/src/index.js +353 -0
- package/src/init.js +110 -0
- package/src/media.js +236 -0
- package/src/migrate.js +67 -0
- package/src/plugin.js +106 -0
- package/src/publish.js +118 -0
- package/src/stage.js +107 -0
- package/src/stories.js +66 -0
- package/src/tts.js +290 -0
- package/src/upload/instagram.js +34 -0
- package/src/upload/youtube.js +90 -0
- package/src/util.js +66 -0
- package/src/voice.js +295 -0
- package/src/youtube-text.js +58 -0
- package/templates/content/films/index.json +1 -0
- package/templates/content/films/measure-the-right-work/film.json +68 -0
- package/templates/content/films/measure-the-right-work/look.css +17 -0
- package/templates/content/films/measure-the-right-work/scene-close.json +153 -0
- package/templates/content/films/measure-the-right-work/scene-groups.json +99 -0
- package/templates/content/films/measure-the-right-work/scene-hook.json +96 -0
- package/templates/content/films/measure-the-right-work/scene-pair.json +190 -0
- package/templates/content/films/measure-the-right-work/scene-problem.json +162 -0
- package/templates/content/films/measure-the-right-work/score.js +19 -0
- package/templates/content/films/measure-the-right-work/strings/en.json +50 -0
- package/templates/content/films/measure-the-right-work/strings/es.json +50 -0
- package/templates/content/films/measure-the-right-work/timing.en.json +24 -0
- package/templates/content/films/measure-the-right-work/timing.es.json +24 -0
- package/templates/content/films/measure-the-right-work/voice/en/close.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/en/groups.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/en/hook.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/en/pair.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/en/problem.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/en.json +7 -0
- package/templates/content/films/measure-the-right-work/voice/es/close.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/es/groups.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/es/hook.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/es/pair.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/es/problem.m4a +0 -0
- package/templates/content/films/measure-the-right-work/voice/es.json +7 -0
- package/templates/content/logos/brand.svg +1 -0
- package/templates/content/site.json +10 -0
- package/templates/content/stories/en/measure-the-right-work.json +13 -0
- package/templates/content/stories/es/measure-the-right-work.json +13 -0
- package/templates/content/stories/index.json +12 -0
- package/templates/content/ui/en.json +1 -0
- package/templates/content/ui/es.json +1 -0
- package/templates/emaki.config.json +67 -0
- package/templates/film/look.css +17 -0
- package/templates/film/scene-close.json +153 -0
- package/templates/film/scene-template.json +71 -0
- package/templates/film/score.js +12 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Day NN · <Weekday Mon D> · <Topic>: <Title>
|
|
2
|
+
|
|
3
|
+
**Story:** <site>/<locale>/stories/<slug> (goes live YYYY-MM-DD)
|
|
4
|
+
**Tags:** tag-one, tag-two, tag-three
|
|
5
|
+
|
|
6
|
+
## 1 · Short video (9:16, about 45 s, YouTube Shorts + Instagram Reels)
|
|
7
|
+
|
|
8
|
+
The motion film `content/films/<slug>/` rendered 9:16, the same scenes as the story's figures. Action tones only;
|
|
9
|
+
voiceover per scene; captions burned in. The voice lines below are the copy of record (`voice/<locale>.json`).
|
|
10
|
+
|
|
11
|
+
| # | Voiceover | On screen (scene) |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| 1 | The hook, as a question or a surprising claim. | hook |
|
|
14
|
+
| 2 | … | … |
|
|
15
|
+
| N | The punchline. | close |
|
|
16
|
+
|
|
17
|
+
## 2 · YouTube
|
|
18
|
+
|
|
19
|
+
**Title:** <title> #shorts
|
|
20
|
+
**Description:** <one or two sentences>. Read the full story: <link>
|
|
21
|
+
#hashtag #hashtag
|
|
22
|
+
|
|
23
|
+
## 3 · Instagram carousel (1080×1350, 6 slides)
|
|
24
|
+
|
|
25
|
+
1. <hook>
|
|
26
|
+
2. …
|
|
27
|
+
6. <punchline>
|
|
28
|
+
|
|
29
|
+
**Caption:** <two lines + "link in bio">
|
|
30
|
+
**Hashtags:** #… #…
|
|
31
|
+
|
|
32
|
+
## 4 · X
|
|
33
|
+
|
|
34
|
+
**Post:** <one sentence that stands alone> 👇
|
|
35
|
+
**Thread:**
|
|
36
|
+
1. …
|
|
37
|
+
2. Full story: <link>
|
|
38
|
+
|
|
39
|
+
## 5 · Posting
|
|
40
|
+
|
|
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.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Posting desk (optional module)
|
|
2
|
+
|
|
3
|
+
A private admin where a person sees the publishing plan, previews each story before it goes live, reorders what
|
|
4
|
+
comes next, asks for changes, and **approves** posts; a scheduled job then posts the approved, unchanged media to
|
|
5
|
+
YouTube, Instagram and X. Nothing is posted that a person did not approve, and an approval is void the moment the
|
|
6
|
+
media or text changes.
|
|
7
|
+
|
|
8
|
+
The implementation is the npm package `@senseihq/emaki-posting`: framework-free rules and a Web `Request → Response`
|
|
9
|
+
API (`createDesk`), a store interface with an in-memory store, a Cloudflare adapter (`/cloudflare`: D1 + R2) and a
|
|
10
|
+
SvelteKit adapter (`/sveltekit`: the guard hook and route handlers), the D1 migrations, and the CI poster scripts
|
|
11
|
+
(`poster/`). Other stacks implement `PostingStore` + `MediaStore` and mount `desk.api` on any fetch-style server.
|
|
12
|
+
|
|
13
|
+
## The model
|
|
14
|
+
|
|
15
|
+
| Piece | What it does | Reference |
|
|
16
|
+
|---|---|---|
|
|
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
|
+
| 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: `emaki stage <slug>`. | `desk.api` → `stage`, `media/<key>` (PUT) |
|
|
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
|
+
| 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
|
+
| 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
|
+
| 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 (`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
|
+
| Audit | Every approve, revoke, pause, post and failure is logged with who and when. | `migrations/0001_posting.sql`, `desk.desk.plan().audit` |
|
|
26
|
+
|
|
27
|
+
## Setup checklist (adapt to your stack)
|
|
28
|
+
|
|
29
|
+
1. A database with the tables in `node_modules/@senseihq/emaki-posting/migrations/` and object storage for media.
|
|
30
|
+
2. The identity proxy in front of the admin paths, with your people allowed; two service tokens (stager, poster).
|
|
31
|
+
3. App secrets: the proxy's audience and team domain, `ADMIN_EMAILS`, the two service token ids, `MEDIA_URL_SECRET`.
|
|
32
|
+
4. The poster's environment: platform credentials (YouTube OAuth refresh token, Instagram Graph token and account id,
|
|
33
|
+
X OAuth 1.0a keys), `POST_MODE=dry-run`, `YT_PRIVACY=private`. Keys live only there, never in the repo.
|
|
34
|
+
5. Test end to end in dry-run: stage → approve → (change the text: approval voids) → re-approve → dry-run post.
|
|
35
|
+
6. Turn on live posting one channel at a time.
|
|
36
|
+
|
|
37
|
+
The package README has the step-by-step guide for the Cloudflare + SvelteKit + GitHub Actions version.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: emaki
|
|
3
|
+
description: >
|
|
4
|
+
This skill should be used when the user asks to "build a learning portal", "build our story site", "set up motion
|
|
5
|
+
stories", "build the site from the playbook", "create explainer stories with animations", "make an alert or awareness
|
|
6
|
+
site with articles and videos", or hands over the emaki playbook and says "build". It runs the whole
|
|
7
|
+
program: interview, outline, item cards, foundation, a pilot story, then automated batches of reader-friendly
|
|
8
|
+
articles, presentation-ready story players and narrated videos from one set of JSON scenes, in every language.
|
|
9
|
+
metadata:
|
|
10
|
+
version: "0.1.0"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Motion stories: the program
|
|
14
|
+
|
|
15
|
+
Build a site of **stories**: each one an article for readers, a story player (slides) for presenting, and optionally
|
|
16
|
+
narrated videos, all rendered from one set of data files per story, in every configured language. The code is on npm under
|
|
17
|
+
`@senseihq`: `@senseihq/emaki` (framework-free core, web components, loaders, JSON Schemas), one wrapper per framework
|
|
18
|
+
(`@senseihq/emaki-svelte`, `-react`, `-vue`), `@senseihq/emaki-posting` (the posting desk) and `@senseihq/emaki-cli`
|
|
19
|
+
(the `emaki` command: init, validate, sheet, voice, fit, render, build). The plugin home (`.claude/emaki/`
|
|
20
|
+
after `emaki plugin install`, holding `PLAYBOOK.md`, `templates/`, `modules/`) carries the method. Read `PLAYBOOK.md`
|
|
21
|
+
once at the start of a program.
|
|
22
|
+
|
|
23
|
+
## Operating rules
|
|
24
|
+
|
|
25
|
+
- Work in phases with gates. Never start a phase before the previous gate is approved by the owner.
|
|
26
|
+
- Ask with AskUserQuestion (≤ 4 questions per call, recommended option first). Ask nothing the files answer.
|
|
27
|
+
- Keep a task list (TaskCreate/TaskUpdate) mirroring `project/tracker.md`, one task per gate and per item.
|
|
28
|
+
- Write decisions to `project/decisions.md` and requirements to `project/brief.md` as they are made.
|
|
29
|
+
- Show evidence at every gate: contact sheets (Read the image before sending), page screenshots, validation output.
|
|
30
|
+
- Content is data: fix text and scenes in the JSON, never by editing renders. Every claim needs a source.
|
|
31
|
+
- Secrets (TTS keys, platform tokens) live in environment variables only; never write, print or commit them.
|
|
32
|
+
|
|
33
|
+
## Phase 0 · Orient
|
|
34
|
+
|
|
35
|
+
1. Locate the plugin root and the target project folder (ask once if neither a repo nor an empty folder is obvious).
|
|
36
|
+
2. If `project/brief.md` exists, resume: read `project/tracker.md`, report where the program stands, continue.
|
|
37
|
+
3. Otherwise create `project/` from `templates/` (brief, decisions, outline, tracker, style-guide, changelog).
|
|
38
|
+
|
|
39
|
+
## Phase 1 · Interview and outline → Gate A
|
|
40
|
+
|
|
41
|
+
Follow `references/01-interview.md` rounds 1–3: purpose and audience, languages, stack and hosting, media scope;
|
|
42
|
+
brand and tone; source material and topics. Draft `project/outline.md` (site map + catalogue + pilot + batches)
|
|
43
|
+
and present it. Iterate until the owner approves. Record Gate A in the tracker.
|
|
44
|
+
|
|
45
|
+
## Phase 2 · Item cards (cover details)
|
|
46
|
+
|
|
47
|
+
For the pilot and the first batch, fill `templates/item-card.md` per item (`project/items/<slug>.md`) using the
|
|
48
|
+
`story-planner` agent for drafts: audience, objective, the one message, the punchline, 5–8 scenes with the picture
|
|
49
|
+
for each, facts with sources, CTA, voice draft. Confirm cards with the owner in batches of 3–5. Only approved cards
|
|
50
|
+
are built. Run the `fact-checker` agent over each card's claims before approval.
|
|
51
|
+
|
|
52
|
+
## Phase 3 · Foundation → Gate B
|
|
53
|
+
|
|
54
|
+
1. Scaffold the app in the chosen stack (or open the existing repo). Run `npx @senseihq/emaki-cli init` (it detects
|
|
55
|
+
the framework, writes `emaki.config.json`, the film source and the `/show/[film]` capture route, and copies the
|
|
56
|
+
sample content), then install the packages it names (`@senseihq/emaki` plus the framework's wrapper, and
|
|
57
|
+
`@senseihq/emaki-cli` + `playwright` as dev dependencies).
|
|
58
|
+
2. Edit `content/` (the sample from `emaki init`: site.json with the owner's name, url, time zone, locales; the
|
|
59
|
+
brand logo; ui strings per locale). Keep the sample story until the pilot replaces it.
|
|
60
|
+
3. Build the routes: `/[locale]/` (home), `/[locale]/stories` (index with topic filters and search),
|
|
61
|
+
`/[locale]/stories/[slug]` (article: header, film player, sections with figures, takeaway band with sub,
|
|
62
|
+
sources, related), `/show/[slug]` (player + capture contract). Server-render the text; hydrate the elements.
|
|
63
|
+
4. Apply the brand to `look.css` tokens and the site CSS. Verify in every launch locale at 375/768/1280 px and
|
|
64
|
+
capture screenshots. Present them with the sample story's sheet. Gate B = the owner approves the look.
|
|
65
|
+
|
|
66
|
+
## Phase 4 · The pilot story → Gate C
|
|
67
|
+
|
|
68
|
+
Run the `story-build` skill for the pilot item end to end (story body, scenes, strings, sound, sheet, article page),
|
|
69
|
+
then `story-media` if video is in scope. Review against `references/07-quality-gates.md`, fix, then present: the
|
|
70
|
+
article page, the player link, the contact sheet per locale, and the video. Iterate with the feedback loop
|
|
71
|
+
(`references/08-feedback-loop.md`). On approval, write `project/style-guide.md` from what the pilot settled (layout
|
|
72
|
+
rules, motion grammar, tone, wording rules, punchline style). Gate C.
|
|
73
|
+
|
|
74
|
+
## Phase 5 · Batch build (automated)
|
|
75
|
+
|
|
76
|
+
For each approved item card, in batches of 3–5:
|
|
77
|
+
1. Dispatch one `scene-builder` agent per story (they can run in parallel) with the item card, the style guide, the
|
|
78
|
+
pilot's scenes as examples, and `references/04-scene-authoring.md`; one `story-writer` agent for the story bodies
|
|
79
|
+
and voice scripts.
|
|
80
|
+
2. When each returns: run `emaki validate <slug>` and `emaki sheet <slug>`; run the `visual-reviewer` agent
|
|
81
|
+
on the sheet; apply its fixes; re-sheet.
|
|
82
|
+
3. Present the batch to the owner: per story one line, the sheet image, the page link. Collect change requests in the
|
|
83
|
+
review sheet; apply them (`story-review` skill); repeat until approved. Update the tracker per story.
|
|
84
|
+
|
|
85
|
+
## Phase 6 · Languages
|
|
86
|
+
|
|
87
|
+
Once a story is approved in the default locale, run `story-localize` per additional locale (draft by the `localizer`
|
|
88
|
+
agent, native review, validate, sheet). Video per locale follows in Phase 7.
|
|
89
|
+
|
|
90
|
+
## Phase 7 · Media (if in scope)
|
|
91
|
+
|
|
92
|
+
Run `story-media` per story per locale: choose the voice provider per locale if not yet chosen (it asks: the
|
|
93
|
+
organisation's cloud platform, Piper or Kokoro offline, a premium service, or recorded), then voice → fit → render →
|
|
94
|
+
build → covers; review the delivery checklist.
|
|
95
|
+
|
|
96
|
+
## Phase 8 · Release → Gate E
|
|
97
|
+
|
|
98
|
+
Run the release checklist (07-quality-gates.md, Gate E). Deploy. If posting or a campaign is in scope, run
|
|
99
|
+
`story-publish`. Hand over: `project/` (brief, decisions, style guide, tracker, changelog), how to add a story
|
|
100
|
+
(`emaki new` + the per-item loop), and who approves what.
|
|
101
|
+
|
|
102
|
+
## Additional resources
|
|
103
|
+
|
|
104
|
+
- `PLAYBOOK.md`: the method for humans (roles, phases, gates, conventions, FAQ).
|
|
105
|
+
- `references/02-architecture.md`, `03-content-model.md`, `04-scene-authoring.md`, `05-voice-and-video.md`,
|
|
106
|
+
`06-i18n.md`, `07-quality-gates.md`, `08-feedback-loop.md`, `09-publishing.md`.
|
|
107
|
+
- The package READMEs (`node_modules/@senseihq/*/README.md`), the sample content from `emaki init` (a complete bilingual example), `node_modules/@senseihq/emaki/schemas/`, `templates/`, `modules/`.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Interview: from "build it" to an approved outline
|
|
2
|
+
|
|
3
|
+
Run the interview with AskUserQuestion, at most four questions per call, options first and a recommended default
|
|
4
|
+
marked "(Recommended)". Never ask what the files already answer: read `project/brief.md`, existing content and
|
|
5
|
+
any brand material the user attaches first. Record every answer in `project/brief.md` and every choice that would be
|
|
6
|
+
expensive to undo in `project/decisions.md`.
|
|
7
|
+
|
|
8
|
+
## Round 1 · The site (one call)
|
|
9
|
+
|
|
10
|
+
1. **Purpose and audience.** Learning portal (staff, partners, customers), marketing or awareness site, product
|
|
11
|
+
explainers, onboarding. Who reads it, on what device, how they arrive (email, social, search, LMS link).
|
|
12
|
+
2. **Languages.** Which locales at launch, which later, the default, any right-to-left language, who translates
|
|
13
|
+
(Claude drafts + human review is the default), whether the voiceover is localised or only captions.
|
|
14
|
+
3. **Stack.** React/Next.js, Svelte/SvelteKit, Vue/Nuxt, Astro, or "pick for us" (recommend the team's existing
|
|
15
|
+
stack; otherwise SvelteKit or Astro with static prerendering). Hosting (static host, Vercel, Netlify, Cloudflare,
|
|
16
|
+
internal). Existing repo or new.
|
|
17
|
+
4. **Media.** Stories with motion only, or also narrated videos (16:9 for the site/YouTube, 9:16 for Shorts/Reels),
|
|
18
|
+
and whether social posting is in scope (posting desk, daily campaign modules).
|
|
19
|
+
|
|
20
|
+
When narrated video is in scope, ask a follow-up about the **voice** (one question, options from
|
|
21
|
+
`05-voice-and-video.md`): "Which voice engine should we use?" with options *Your organisation's cloud platform
|
|
22
|
+
(Recommended if you have Azure, Google Cloud or AWS)*, *Piper: free and offline (Recommended otherwise)*, *A premium
|
|
23
|
+
service (ElevenLabs or OpenAI)*, *Recorded by a person*. Then per locale pick a voice (`emaki voices`), record it
|
|
24
|
+
with `emaki set-voice`, and make a 10-second sample take for the owner to approve with the pilot. Ask the owner to
|
|
25
|
+
set any key as an environment variable themselves; never ask for a key in chat.
|
|
26
|
+
|
|
27
|
+
## Round 2 · Brand and look (one call, plus attachments)
|
|
28
|
+
|
|
29
|
+
Ask for the logo (SVG), colours, fonts, an existing site or deck to match, and two or three references they like.
|
|
30
|
+
If none: propose the kit's default look (washi paper, ink, one accent, dot-grid board, Fraunces + Inter) re-coloured
|
|
31
|
+
to their accent, and show it on the pilot. Confirm tone of voice (plain and direct by default), reading level, and
|
|
32
|
+
any words or claims to avoid (legal, regulated topics).
|
|
33
|
+
|
|
34
|
+
## Round 3 · The catalogue (one call, then a document)
|
|
35
|
+
|
|
36
|
+
Ask for the source material (policies, decks, docs, transcripts, SME notes, URLs) and the list of topics, or offer
|
|
37
|
+
to propose topics from the material. Then draft `project/outline.md` from `templates/outline.md`:
|
|
38
|
+
|
|
39
|
+
- the site map (home, story index with filters by topic, story pages per locale, the player, about/contact);
|
|
40
|
+
- the **catalogue**: one row per item with slug, working title, format (film 60–90 s · short 30–60 s · article only),
|
|
41
|
+
topic, priority, target date, source documents, owner/SME;
|
|
42
|
+
- the order of work: the **pilot** first (an item that exercises the most scene types), then batches.
|
|
43
|
+
|
|
44
|
+
Present the outline (a table in chat plus the file), ask for approval or edits, and do not build anything until it
|
|
45
|
+
is approved. Re-ask only for what changed.
|
|
46
|
+
|
|
47
|
+
## Round 4 · Cover details per item (batched)
|
|
48
|
+
|
|
49
|
+
For each item, fill an **item card** (`templates/item-card.md`) and confirm it with the owner in batches of 3–5:
|
|
50
|
+
|
|
51
|
+
- **Audience and objective:** who, and what they should know, feel or do afterwards (one sentence each).
|
|
52
|
+
- **The one message** and the **punchline** (the closing line, 3–9 words; it becomes the cover, the takeaway band
|
|
53
|
+
and the last voice line).
|
|
54
|
+
- **Scenes:** 5–8 for a film (hook → problem/why → 2–4 idea scenes → how/what to do → close), 4–6 for a short. For
|
|
55
|
+
each: id, the one point it makes, the picture that makes it (cards, chart, flow, before/after, list), and the
|
|
56
|
+
section of the article it illustrates.
|
|
57
|
+
- **Facts and sources:** every number, name and claim with its source; mark illustrative data as such on screen.
|
|
58
|
+
- **Call to action** and links; what must not be said.
|
|
59
|
+
- **Voice:** the script draft (150 words a minute; 10–30 words per scene).
|
|
60
|
+
|
|
61
|
+
An item card is "ready" when the owner has approved it. Only ready cards go to the build.
|
|
62
|
+
|
|
63
|
+
## Questions to ask only when relevant
|
|
64
|
+
|
|
65
|
+
- Accessibility level (WCAG 2.2 AA default), captions on all video (default yes), reduced-motion behaviour.
|
|
66
|
+
- Analytics and consent; SEO (per-locale URLs and hreflang default yes); LMS packaging (SCORM/xAPI wrappers).
|
|
67
|
+
- Review roles: who approves content, who approves look, who signs off translations; turnaround expected.
|
|
68
|
+
- For alerts/advisories: severity labels, update cadence, expiry of a story, "last reviewed" dates.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Architecture: one source, three outputs, every language
|
|
2
|
+
|
|
3
|
+
## The idea
|
|
4
|
+
|
|
5
|
+
Each story is written once as **data** and renders three ways from the same files:
|
|
6
|
+
|
|
7
|
+
| Output | Who it's for | How |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| **Article** (reader-friendly) | People reading on any device; search engines | The story body (title, dek, sections, takeaway) as HTML; each section whose id matches a scene shows that scene as a looping **figure** (artwork only; the words are in the article). |
|
|
10
|
+
| **Story player** (presentation/capture-friendly) | Presenters, kiosks, the top of the article, and the video pipeline | The film's scenes as slides, 16:9 or 9:16, with words on screen and opt-in sound; `/show/<slug>`. |
|
|
11
|
+
| **Video** (social, YouTube, LMS) | Feeds and playlists | The player captured frame by frame (Playwright) + the score + the voiceover per locale + captions → MP4 16:9 and 9:16, with the closing card as cover. |
|
|
12
|
+
|
|
13
|
+
Scenes are **pure functions of time**: `render(t)` draws the frame at time `t`, with no timers or randomness, so the
|
|
14
|
+
same scene can be looped as a figure, scrubbed in the player, and captured at 30 fps for video.
|
|
15
|
+
|
|
16
|
+
## Layers
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
content/ ← the source of truth (deployed with the site)
|
|
20
|
+
site.json name, url, timeZone, locales, defaultLocale, brand, topics
|
|
21
|
+
ui/<locale>.json interface strings
|
|
22
|
+
stories/index.json locale-neutral: slug, publish_date, kind, topic, tags, film, cover, social
|
|
23
|
+
stories/<locale>/<slug>.json title, dek, sections, takeaway, takeawaySub, sources (one per locale)
|
|
24
|
+
films/<slug>/ film.json · look.css · scene-<id>.json · score.js · strings/<locale>.json
|
|
25
|
+
· voice/<locale>.json · timing[.<locale>].json
|
|
26
|
+
logos/<name>.svg
|
|
27
|
+
production/ ← never deployed: takes, renders, contact sheets, finished videos, per locale
|
|
28
|
+
emaki.config.json content/production folders, dev server, capture path, voice provider per locale
|
|
29
|
+
node_modules/@senseihq/
|
|
30
|
+
motion the core (framework-free TypeScript): kit (easing), renderer (JSON scenes), registry (film
|
|
31
|
+
source), mount (layouts, shadow DOM), show (player + capture contract), sound (score synth),
|
|
32
|
+
i18n, content (stories), controller (attachScene), setupMotion
|
|
33
|
+
· /elements <motion-scene> and <motion-show> web components
|
|
34
|
+
· /loaders/vite (bundled via your import.meta.glob) · /loaders/fetch (static files at runtime)
|
|
35
|
+
· /schemas JSON Schemas for every content file
|
|
36
|
+
motion-svelte MotionScene, MotionShow, ScenePlayer, ShowPage (Svelte 5)
|
|
37
|
+
motion-react the same components + useScenePlayer / useShowState hooks
|
|
38
|
+
motion-vue the same components + composables
|
|
39
|
+
motion-posting the posting desk (stage → approve → post), with Cloudflare and SvelteKit adapters
|
|
40
|
+
motion-cli `emaki`: init, plugin install, manifest, validate, new, sheet, tts-check, set-voice,
|
|
41
|
+
voices, voice, fit, render, build
|
|
42
|
+
app/ (your framework) routes: /[locale]/, /[locale]/stories, /[locale]/stories/[slug], /show/[film]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Data flow
|
|
46
|
+
|
|
47
|
+
1. **Write**: item card → story body (per locale) + film folder (scenes as JSON, text as `{{keys}}` in strings).
|
|
48
|
+
2. **Load**: the app installs a film source (`useSource`) and a content source; `loadStory(slug, locale)` merges
|
|
49
|
+
the index entry with the locale's body (falling back along `fr-CA → fr → default`), maps sections to scenes.
|
|
50
|
+
3. **Render**: the article page renders text on the server; `<motion-scene>`/`<motion-show>` hydrate on the client,
|
|
51
|
+
mount each scene in a shadow root, localise its text, and draw `render(t)` every frame.
|
|
52
|
+
4. **Produce**: `emaki` drives `/show/<slug>?capture=1&o=…&locale=…` through `window.__show` (meta, ready,
|
|
53
|
+
seek, audio) to make sheets, renders and covers; voice takes per locale set `timing.<locale>.json`, which the
|
|
54
|
+
site also reads, so the player, the figures, the sound and the video stay in step in every language.
|
|
55
|
+
5. **Publish**: prerender every published story per locale (publishing is by date in the site's time zone); covers
|
|
56
|
+
become `og:image`; videos go to the platforms (optionally through the posting desk).
|
|
57
|
+
|
|
58
|
+
## Layouts
|
|
59
|
+
|
|
60
|
+
- `landscape` 1920×1080: words left, artwork right (the authoring board).
|
|
61
|
+
- `portrait` 1080×1920: the same scene recomposed by its `portrait` block: hoisted words at the top, the art region
|
|
62
|
+
(`crop`) scaled into a band (`frame`). No second scene file.
|
|
63
|
+
- `figure` 1600×1000: the art region only, for the article (the scene's words are hidden; the article says them).
|
|
64
|
+
|
|
65
|
+
## Framework neutrality
|
|
66
|
+
|
|
67
|
+
The core imports no UI library. The only framework-specific code is a page that renders the story body and the
|
|
68
|
+
`/show/<slug>` capture route; both are a few lines (`emaki init` writes the capture route; the wrappers' `ShowPage` does the work). Server rendering is for the article text;
|
|
69
|
+
the elements are client-only.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Content model
|
|
2
|
+
|
|
3
|
+
JSON Schemas for every file are in `node_modules/@senseihq/emaki/schemas/`; `emaki validate` checks the cross-file rules below. The
|
|
4
|
+
starter (`emaki init`, which copies it into `content/`) is a complete, valid example in English and Spanish.
|
|
5
|
+
|
|
6
|
+
## site.json
|
|
7
|
+
|
|
8
|
+
`name`, `url`, `timeZone` (IANA; stories publish by date there), `locales`, `defaultLocale`, `rtl`, `brand`
|
|
9
|
+
(`logo` name in `logos/`, `accent`), `topics` (`id`, `label` per locale).
|
|
10
|
+
|
|
11
|
+
## stories/index.json (locale-neutral)
|
|
12
|
+
|
|
13
|
+
One entry per story: `slug` (kebab-case, permanent: it is the URL and the film folder), `publish_date`
|
|
14
|
+
(YYYY-MM-DD), `kind` (`film` 60–90 s narrated · `short` 30–60 s, 9:16 first · `article` no film), `topic`, `tags`,
|
|
15
|
+
`film` (only when it differs from the slug), `cover` (`/covers/<slug>.jpg`, written by `render`), `minutes`,
|
|
16
|
+
`social` (links filled after posting), `related`.
|
|
17
|
+
|
|
18
|
+
## stories/<locale>/<slug>.json (one per locale)
|
|
19
|
+
|
|
20
|
+
```json
|
|
21
|
+
{
|
|
22
|
+
"title": "Spot a phish in ten seconds",
|
|
23
|
+
"dek": "One or two sentences: what the reader gets.",
|
|
24
|
+
"sections": [
|
|
25
|
+
{ "id": "hook", "eyebrow": "The question", "title": "…", "body": ["…"], "caption": "A line under the figure." },
|
|
26
|
+
{ "id": "signs", "eyebrow": "What to look for", "title": "…", "body": ["…"], "points": ["…", "…"] },
|
|
27
|
+
{ "id": "more", "eyebrow": "Read more", "title": "…", "body": ["…"] }
|
|
28
|
+
],
|
|
29
|
+
"takeaway": "Pause, check, report.",
|
|
30
|
+
"takeawaySub": "The line under the punchline, as on the closing card.",
|
|
31
|
+
"sources": [{ "label": "Policy 4.2", "href": "https://…" }]
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Rules:
|
|
36
|
+
- A section whose `id` equals a scene id gets that scene as its figure (artwork only). `motion: {film, scene}`
|
|
37
|
+
points elsewhere explicitly. Sections without a scene are reading text.
|
|
38
|
+
- `takeaway` is the closing card's title, as text, without the mark; `takeawaySub` is the line under it. Every film
|
|
39
|
+
story has a takeaway.
|
|
40
|
+
- Plain text only in body fields (the page escapes it). Use `points` for lists, `code` for code.
|
|
41
|
+
- A missing translation falls back to the default locale and the page says so ("not yet in your language").
|
|
42
|
+
|
|
43
|
+
## films/<slug>/
|
|
44
|
+
|
|
45
|
+
| File | Contents |
|
|
46
|
+
|---|---|
|
|
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
|
+
| `scene-<id>.json` | The scene as data (components, tracks, css, portrait, locales). See 04-scene-authoring.md. |
|
|
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
|
+
| `score.js` | The sound: action tones timed to scene events (`T.<scene> + seconds`). |
|
|
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
|
+
| `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` (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. |
|
|
56
|
+
|
|
57
|
+
## Production (not deployed)
|
|
58
|
+
|
|
59
|
+
`production/<slug>/<locale>/takes/take-NN.wav` · `render/<slug>-<locale>-16x9.mp4`, `-9x16.mp4`, `score.wav`,
|
|
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.
|
|
63
|
+
|
|
64
|
+
## Naming
|
|
65
|
+
|
|
66
|
+
- Slugs and scene ids: lowercase kebab-case, stable forever (URLs, files, analytics). Rename by redirect only.
|
|
67
|
+
- Component ids are unique per scene and prefixed with the scene id (`signs-card`), so CSS never collides.
|
|
68
|
+
- String keys: `<scene>.<part>` (`hook.line`, `hook.eyebrow`, `signs.3`, `close.title`, `close.sub`).
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# Scene authoring
|
|
2
|
+
|
|
3
|
+
A scene is one idea, on screen for 6–15 s, ending on a held picture. Write it as JSON (`scene-<id>.json`); the
|
|
4
|
+
renderer (`renderer.ts` in `@senseihq/emaki`, types in `scene-schema.ts`) turns it into DOM once and into style operations
|
|
5
|
+
every frame. Read the starter's `scene-*.json` before writing a new one.
|
|
6
|
+
|
|
7
|
+
## The board and the grammar
|
|
8
|
+
|
|
9
|
+
- Author on a **1920×1080 board**. Words on the left (x 110, width ≈ 700); the artwork on the right (x 880–1820,
|
|
10
|
+
y 150–830). Keep 40 px clear of every edge.
|
|
11
|
+
- One idea per scene: a head (eyebrow, line, sub) that says it, and one picture that shows it.
|
|
12
|
+
- Order of motion: the head arrives first (eyebrow, words of the line, then the sub), then the artwork builds in the
|
|
13
|
+
order the voice mentions things; every beat lands on its word. End with ≥1.5 s of stillness (the hold).
|
|
14
|
+
- Motion is calm: fades and short rises (12–24 px), pops with a little overshoot, lines that draw, a slow camera
|
|
15
|
+
push (1.00 → 1.02–1.03). No spinning, bouncing loops or flashing.
|
|
16
|
+
- Illustrative numbers say "Illustrative" on screen. Real numbers carry a source in the article.
|
|
17
|
+
- **Connectors meet what they connect**: line ends sit on card edges at their centres; measure, don't guess.
|
|
18
|
+
Symmetric layouts are centred on the board's art region. Repeated cards share one size.
|
|
19
|
+
- The **close** scene is the punchline card: title (3–9 words) + bar + one-line sub on the paper, the brand mark on
|
|
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.
|
|
24
|
+
|
|
25
|
+
## The file
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"components": [ … ], // what is on stage, in paint order
|
|
30
|
+
"tracks": [ … ], // how it moves over t
|
|
31
|
+
"css": "…", // the scene's own classes (prefixed with the scene id)
|
|
32
|
+
"portrait": { "hoist": [".signs-head"], "frame": [640, 1000], "crop": [880, 160, 940, 680], "css": "…" },
|
|
33
|
+
"locales": { "de": { "css": ".signs-head .line{font-size:72px}" }, "ar": { "css": "…" } }
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Components
|
|
38
|
+
|
|
39
|
+
| type | Use | Key fields |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| `board` | The dot-grid paper (always first) | `id` |
|
|
42
|
+
| `head` | Eyebrow + line + sub, word-split for arrival | `eyebrow`, `line`, `sub`, `style`, `at: "ground"` |
|
|
43
|
+
| `text` | Any run of text; `split: true` for word-by-word arrival (count is automatic, so any language works); `html: true` keeps `<b>/<em>` | `text`, `tag`, `cls`, `style`, `split`, `html` |
|
|
44
|
+
| `box` | An HTML container (card, column) holding `text`/`raw`/`box` children; sizes to its content | `cls`, `style`, `children` |
|
|
45
|
+
| `checks` | A ticked list | `items`, `style` |
|
|
46
|
+
| `node` | A square tile with a glyph (spark, brace, ring, tri, grid, db, lock, crown, list, check, steps, doc, wave) | `kind`, `tone` (hot/ok), `size`, `x`, `y` |
|
|
47
|
+
| `wire` | A quadratic connector | `a`, `c`, `b`, `color` |
|
|
48
|
+
| `bars` | Code lines as rounded bars | `x`, `y`, `rows` [[indent, width, tone]] |
|
|
49
|
+
| `logo` | A registered brand mark | `name`, `x`, `y`, `size` |
|
|
50
|
+
| `group` | SVG children with a shared style/transform | `style`, `children` |
|
|
51
|
+
| `svg` | Bespoke SVG (paths, charts) | `body` |
|
|
52
|
+
| `raw` | Bespoke HTML | `html` |
|
|
53
|
+
|
|
54
|
+
SVG components share one `<svg class="art" viewBox="0 0 1920 1080">`; HTML components sit in the camera layer
|
|
55
|
+
(`.cam`, which the push scales) unless `at: "ground"` (fixed: heads, captions). Paint order is the array order.
|
|
56
|
+
|
|
57
|
+
### Tracks
|
|
58
|
+
|
|
59
|
+
- `tween`: one property over [t0, t1] with an easing (`linear`, `eo`, `ei`, `eio`, `eoq`, `eox`, `eob`, `spring`),
|
|
60
|
+
optionally staggered over `count` matches: `prop` `opacity` | `transform` (with `template: "translateY({v}px)"`)
|
|
61
|
+
| `attr:<name>`.
|
|
62
|
+
- `effect`: `push` (camera), `showHead`, `fade` (+ rise), `pop`, `draw` (paths with `pathLength="1"`), `words`
|
|
63
|
+
(word arrival; target a split `text`), `counter` (counting numbers, locale-formatted), `swap` (restyle/reclass
|
|
64
|
+
from a time, seek-safe), `settle` (the closing mark), `growBars` (chart bars).
|
|
65
|
+
- Times are scene seconds. The head starts at −0.4 so it's already arriving at 0. Stagger lists 0.25–0.6 s apart.
|
|
66
|
+
|
|
67
|
+
### Text and languages
|
|
68
|
+
|
|
69
|
+
Every word on screen is a `{{key}}` from `strings/<locale>.json`; nothing language-specific lives in the scene. Size
|
|
70
|
+
text boxes for the longest locale (German and Finnish run ~30% longer, CJK shorter); wrap rather than shrink; use a
|
|
71
|
+
`locales.<code>.css` block for a language that needs a smaller line or a different placement. Right-to-left
|
|
72
|
+
locales get `dir="rtl"` on the stage; mirror the board for them with a `locales.ar.css` block only if the picture has
|
|
73
|
+
a reading direction (timelines, arrows). Pick fonts that cover every locale's glyphs (Noto families for non-Latin
|
|
74
|
+
scripts) and check diacritics in the display face (some display fonts misplace combining marks).
|
|
75
|
+
|
|
76
|
+
### Portrait and figure
|
|
77
|
+
|
|
78
|
+
`portrait.hoist` lifts the head to the top (`css` places it: left 70, top 150, width 940); `crop` is the art region
|
|
79
|
+
on the board; `frame` [top, height] is where it lands in 1080×1920. The figure layout reuses `crop`. Every scene
|
|
80
|
+
needs a portrait block; check both orientations on every sheet.
|
|
81
|
+
|
|
82
|
+
## The escape hatch: code scenes
|
|
83
|
+
|
|
84
|
+
When the picture needs computed geometry (paths along a curve, physics-free procedural layouts), write
|
|
85
|
+
`scene-<id>.js` against the kit (`kit.scene(id, { init(kit) {…}, render(t) {…} })`, helpers in `shared.js`,
|
|
86
|
+
`W.portrait(kit, spec)` at the end of `init`, text via `kit.t('key')`). Rules: draw from `t` only; no timers,
|
|
87
|
+
`Date.now()`, `Math.random()` (use `kit.rng(seed)`), or CSS transitions; class names prefixed with the scene id.
|
|
88
|
+
When the same need recurs, promote it to a renderer component or effect instead.
|
|
89
|
+
|
|
90
|
+
## Sound (score.js)
|
|
91
|
+
|
|
92
|
+
Action tones only: a soft pitched note when something lands (a card, a tick, a reveal), a chord on the close. Time
|
|
93
|
+
each to its beat (`T.signs + 2.4`). Instruments: vibes, marimba, pluck, ep, bass; effects: click, tick, thud, pop,
|
|
94
|
+
whoosh, ding, chime, sparkle, roll. Sound is always off until the viewer turns it on.
|
|
95
|
+
|
|
96
|
+
## Checking a scene
|
|
97
|
+
|
|
98
|
+
`emaki sheet <slug> [--locale xx] [--at scene:t,…]` makes a contact sheet of every scene's final picture in both
|
|
99
|
+
orientations. Look at it (Read the image) before showing anyone. Check mid-animation frames for beats that matter.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# Voice, timing and video
|
|
2
|
+
|
|
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
|
+
|
|
6
|
+
## Choosing the voice provider
|
|
7
|
+
|
|
8
|
+
Claude writes the script, the pronunciations and the translations; the audio comes from a speech engine or a person.
|
|
9
|
+
the `emaki` CLI's TTS providers supports these, set per locale in `emaki.config.json` (`voice.default`, `voice.<lang>`,
|
|
10
|
+
`voice.<locale>`; a block that names a different provider starts fresh):
|
|
11
|
+
|
|
12
|
+
| Provider | Runs | Cost | Quality | Good for | Needs |
|
|
13
|
+
|---|---|---|---|---|---|
|
|
14
|
+
| `piper` | offline, any OS | free | good, clear | default for teams with no TTS account; private content; air-gapped | `pip install piper-tts` + a voice file (.onnx + .onnx.json) per language |
|
|
15
|
+
| `kokoro` | offline, any OS | free | very natural | best free quality in en, es, fr, it, pt, hi, ja, zh | `pip install kokoro soundfile` (pulls PyTorch), espeak-ng |
|
|
16
|
+
| `macos` | offline, Mac | free | fair | quick drafts and timing passes | macOS `say` (more voices in Accessibility › Spoken Content) |
|
|
17
|
+
| `espeak` | offline, any OS | free | robotic | timing drafts only | espeak-ng |
|
|
18
|
+
| `azure` | cloud | per character | excellent, 140+ locales | Microsoft 365 / Azure organisations | `AZURE_SPEECH_KEY`, `AZURE_SPEECH_REGION` |
|
|
19
|
+
| `google` | cloud | per character | excellent | Google Workspace / GCP organisations | `GOOGLE_TTS_API_KEY` or `gcloud auth login` |
|
|
20
|
+
| `polly` | cloud | per character | very good | AWS organisations | the `aws` CLI + AWS credentials |
|
|
21
|
+
| `openai` | cloud | per character | natural, steerable tone | teams with OpenAI or Azure OpenAI | `OPENAI_API_KEY` (or `AZURE_OPENAI_ENDPOINT` + key) |
|
|
22
|
+
| `elevenlabs` | cloud | subscription | top | premium narration, voice cloning | `ELEVENLABS_API_KEY` |
|
|
23
|
+
| `manual` | a person | time | human | regulated or brand-critical narration | recorded `take-NN.wav` files |
|
|
24
|
+
|
|
25
|
+
Rules: use the same voice for a locale across the whole site; the default recommendation is the organisation's
|
|
26
|
+
existing cloud platform if it has one (procurement and data agreements already exist), otherwise Piper (free,
|
|
27
|
+
offline, private). Use `macos`/`espeak` only for draft timing passes, never for published video. Keys go in
|
|
28
|
+
environment variables or the CI secret store, never in `emaki.config.json` (`set-voice` refuses them).
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
emaki tts-check # per locale: provider and whether it's ready here
|
|
32
|
+
emaki voices --locale es --provider azure # list voices to choose from
|
|
33
|
+
emaki set-voice --locale es --provider azure --opt voice=es-ES-ElviraNeural
|
|
34
|
+
emaki voice <slug> --locale es --provider macos # one-off override (e.g. a draft pass)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Steps per story per locale
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
emaki voice <slug> --locale en # takes from voice/en.json → production/<slug>/en/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
|
|
43
|
+
emaki render <slug> --locale en # 16:9 + 9:16 picture with the score, covers
|
|
44
|
+
emaki build <slug> --locale en # voice laid at each scene start, score ducked, -14 LUFS, captions
|
|
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
|
+
|
|
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
|
|
61
|
+
scene runs longer. Write for the ear: short sentences, the scene's point first, numbers spoken as words where it helps.
|
|
62
|
+
Put tricky pronunciations in `say` (`"Sen-say"`, `"S-Q-L"`). Same voice per locale across the site.
|
|
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
|
|
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.
|
|
76
|
+
- **Captions** come from the voice text (`.vtt` for the site player, `.srt` burned into social cuts). Review them in
|
|
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.
|
|
82
|
+
- **Covers**: the last frame of the close scene, per orientation and locale; the 16:9 one is copied to the site's
|
|
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}`).
|
|
88
|
+
- **Credentials**: every provider key lives in the environment only; never in files, never committed, never printed,
|
|
89
|
+
never pasted into chat. Each take run records which provider and voice made it (`takes/provider.json`).
|
|
90
|
+
|
|
91
|
+
## Delivery checklist
|
|
92
|
+
|
|
93
|
+
- Durations: film 60–90 s, short 30–60 s. Loudness -14 LUFS, true peak ≤ -1.5 dB.
|
|
94
|
+
- Watch the first and last 5 s of every render; spot-check each scene change for a frozen or blank frame.
|
|
95
|
+
- 9:16 safe area: nothing important in the bottom 300 px (platform UI) or top 150 px.
|
|
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`.
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Internationalisation
|
|
2
|
+
|
|
3
|
+
Everything a reader sees or hears is keyed by locale; nothing language-specific lives in code or scene geometry.
|
|
4
|
+
|
|
5
|
+
| Layer | Per-locale file | Fallback |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| Interface | `content/ui/<locale>.json` (`t(dict, key, vars)`) | default locale, then the key |
|
|
8
|
+
| Story text | `content/stories/<locale>/<slug>.json` | `fr-CA → fr → default`, with a "not yet translated" note |
|
|
9
|
+
| Scene text | `content/films/<slug>/strings/<locale>.json` (`{{key}}`) | merged along the same chain |
|
|
10
|
+
| Voice + captions | `content/films/<slug>/voice/<locale>.json` | none: a locale without voice ships captions-only or no video |
|
|
11
|
+
| Timing | `timing.<locale>.json` | `timing.json`, then design times |
|
|
12
|
+
| Video | `production/<slug>/<locale>/out/…` | n/a |
|
|
13
|
+
|
|
14
|
+
## Routing and SEO
|
|
15
|
+
|
|
16
|
+
`/<locale>/…` for every page (the default locale may also live at `/`). Negotiate the first visit from
|
|
17
|
+
`Accept-Language` (`negotiate()`), then keep the reader's choice. Prerender every story per locale; add `hreflang`
|
|
18
|
+
alternates (and `x-default`), localized `<title>`, description and `og:image` (the locale's cover). Dates and
|
|
19
|
+
numbers through `Intl` (`formatDate`, counters are locale-formatted automatically).
|
|
20
|
+
|
|
21
|
+
## Translation workflow
|
|
22
|
+
|
|
23
|
+
1. Freeze the default-locale story (owner-approved) before translating.
|
|
24
|
+
2. Claude drafts each locale (the `localizer` agent): story body, scene strings, voice script, UI strings; keeps keys
|
|
25
|
+
identical; adapts examples and idioms rather than translating them literally; keeps the punchline short.
|
|
26
|
+
3. A native reviewer approves in the review sheet (one row per locale). Legal/regulated wording is reviewed by a
|
|
27
|
+
person, always.
|
|
28
|
+
4. `emaki validate` must pass (every `{{key}}` present in every locale), then a contact sheet per locale.
|
|
29
|
+
5. Voice, fit, render, build per locale.
|
|
30
|
+
|
|
31
|
+
## Layout across languages
|
|
32
|
+
|
|
33
|
+
- Size for the longest language; let lines wrap; check each locale's sheet. Use `locales.<code>.css` in a scene for
|
|
34
|
+
exceptions rather than separate scene files.
|
|
35
|
+
- RTL (`ar`, `he`, `fa`, `ur`): `dir="rtl"` on the page and stage; place heads on the right with a locale CSS block
|
|
36
|
+
if the composition reads left-to-right (arrows, timelines), otherwise leave the art as is.
|
|
37
|
+
- Fonts: confirm glyph coverage per locale (diacritics, CJK, Arabic); load the font subsets for each locale only.
|