@crievo/omni 0.0.0-stage → 0.1.1

package/reference/publish.md

@@ -0,0 +1,305 @@
+# Publishing to YouTube, Instagram and TikTok
+
+The **Publicar** (Publish) button lives in the studio's Publicar stage. Each
+platform is a card with the icon, the photo and the @ of the connected account;
+check one, two or all three. It writes the text to
+`videos/<slug>/publication.json` and runs `tools/publish.mjs`, which uploads the
+MP4 from `export/assembly.json` and writes back each platform's id and link. A
+video that is already up on a platform doesn't go up again, unless you check
+that platform again (`--again`).
+
+Credentials live in `.env` (outside git). Each account is set up only once, in
+Configurações (Settings) → Plataformas (Platforms) or in the terminal.
+
+## Title, description and post caption
+
+They come out of the script on their own. When the video has no text yet, the
+Publicar stage runs `node tools/publish.mjs text videos/<slug>`: Claude
+(`claude -p`, in the studio sessions' config folder) reads `script.md` and writes
+the title, description, post caption and tags. Without Claude, the title comes
+from the script's heading, the description from the thesis and the caption from
+the hook. Everything is editable in the studio, and "Escrever de novo a partir do
+roteiro" (Rewrite from the script) (`--redo`) replaces what is there. Publishing
+also writes the text before uploading, if the title is missing.
+
+The **post caption** is the same on Instagram and TikTok. If empty, the title
+plus the description is used. Each platform's footer and the fixed hashtags go
+at the end.
+
+```bash
+node tools/publish.mjs status        # what is connected
+```
+
+## YouTube
+
+1. **Project and API.** At [console.cloud.google.com](https://console.cloud.google.com),
+   create a project (for example `omnivideo`) and enable the **YouTube Data API v3**
+   under APIs & Services → Library.
+2. **Consent screen.** In Google Auth Platform (or APIs & Services → OAuth
+   consent screen): type **External**, app name, your email. Under Audience, set
+   the app to **In production**. In "Testing", the login expires every 7 days.
+   Since the app isn't verified, Google shows a warning at login ("Google hasn't
+   verified this app"). For your own use, click Advanced → continue.
+3. **OAuth client.** Under Clients → Create client, type **Desktop app**. Copy
+   the ID and the secret into `.env`:
+   ```
+   YOUTUBE_CLIENT_ID=…apps.googleusercontent.com
+   YOUTUBE_CLIENT_SECRET=GOCSPX-…
+   ```
+4. **Login.** `node tools/publish.mjs auth youtube`. The browser opens: pick the
+   **channel's** account and allow. The refresh token goes to `.env`
+   (`YOUTUBE_REFRESH_TOKEN`), and the command shows the channel name.
+   `--browser Dia` opens the login in Dia; `--no-open` only prints the link to
+   paste. From the studio: Configurações → Plataformas → **Conectar no Dia**
+   (Connect in Dia) or **Gerar link para copiar** (Generate a link to copy). The
+   link only works in a browser on this machine, because Google sends the login
+   back to `127.0.0.1`. It waits up to 10 min.
+
+**Private until the audit.** New API projects can only upload videos as
+private. Even if you ask for "Public", YouTube locks it as private. Until the
+project is audited, publish as private and switch to public in YouTube Studio
+(the link is in `publication.json`, at `youtube.studio`). To unlock it, request
+the audit through the "YouTube API Services – Audit and Quota Extension" form
+(Google answers in days or weeks). Once approved, set
+`publish.youtube.audited: true` in the config.
+
+**Quota.** 10,000 units per day, and each upload costs about 1,600: roughly 6
+videos per day.
+
+A 9:16 video up to 3 min becomes a Short on its own. Category, language and
+"made for kids" live in `publish.youtube` in the config. If the video has
+realistic synthetic content that needs a disclosure, use
+`synthetic_content: true`.
+
+## Instagram (Reels)
+
+1. **Professional account.** In the Instagram app: Settings → Account type →
+   switch to **Creator** or **Business**. A personal account can't publish
+   through the API.
+2. **Meta app.** At [developers.facebook.com/apps](https://developers.facebook.com/apps),
+   create an app (use case: manage messaging and content on Instagram) and add
+   the **Instagram** product → "API setup with Instagram login".
+3. **You as a tester.** Under App roles → Roles, add your Instagram account as
+   an **Instagram tester** and accept the invite in Instagram (Settings → Apps
+   and websites → Tester invites). With the app in development mode and only
+   your account, there is no need to go through App Review.
+4. **Token.** Under "Generate access tokens", add the account and generate the
+   token with the `instagram_business_basic` and
+   `instagram_business_content_publish` permissions (for omnichat on comments,
+   also `instagram_business_manage_comments` and
+   `instagram_business_manage_messages`: `reference/omnichat.md`). Then run
+   `node tools/publish.mjs auth instagram <token>`.
+
+The token lasts 60 days. `publish.mjs` renews it by itself when fewer than 20
+days are left, on every publish or `status`. If more than 60 days pass without
+publishing, generate another one (step 4).
+
+**How the video gets there.** With Instagram login, Meta doesn't accept the
+file: it downloads the video from a public URL (direct upload is only for apps
+with Facebook login). `publish.mjs` opens that URL on the spot: a server on
+`127.0.0.1` that serves only that MP4, at a random path, behind a `cloudflared`
+quick tunnel (`https://<random>.trycloudflare.com/<token>.mp4`). The tunnel
+takes about 15 s to respond, stays up until Instagram finishes processing and
+closes right after. It needs `cloudflared` installed (`brew install
+cloudflared`).
+
+The video goes as Reels, also to the feed (`share_to_feed`). The cover is the
+selected thumbnail (below, **Cover**); without one, the frame at `cover_at_s`
+seconds (`null` = Instagram's choice). The post caption is the one in the
+"Legenda" (Caption) field (the same as TikTok's), or the title and description
+if it is empty: up to 2,200 characters and 30 hashtags. Reels through the API
+accept 3 s to 15 min.
+
+## Carousel (Instagram)
+
+`node tools/publish.mjs carousel videos/<slug> --confirm` (the button of the
+carousel's Publicar stage in the studio does the same). It uploads
+`carousel/export/NN.jpg` (exported on the spot if the build changed after the last
+export) as a carousel post. Images don't go up as files either: each JPEG goes
+through the same `cloudflared` tunnel as the Reel, becomes a child container
+(`is_carousel_item`), and the `CAROUSEL` container joins the children with the
+caption. The caption is `carousel/publication.json`'s (the one edited in the
+studio) or `carousel.json`'s `caption`, with the Instagram footer and the
+hashtags from `publish.text`. The API accepts 2 to 10 slides
+(`carousel.slides.publish`) and images from 4:5 to 1.91:1: the app's 3:4 does not
+go through it yet. The result (id, link, when) goes back to
+`carousel/publication.json`, which prevents publishing twice (`--again` uploads
+it again). `--auto` and the schedule do not publish carousels. After it goes up,
+the carousel's omnichat is checked like the Reel's.
+
+## TikTok
+
+1. **App.** At [developers.tiktok.com](https://developers.tiktok.com), create an
+   app. Add the **Login Kit** (platform **Desktop**) and **Content Posting API**
+   (turn on **Direct Post**) products. Under scopes, request
+   `user.info.basic`, `user.info.profile`, `video.publish` and `video.upload`.
+2. **Credentials and redirect.** Copy the Client key and Client secret into
+   `.env` (or into Configurações → Plataformas → TikTok):
+   ```
+   TIKTOK_CLIENT_KEY=…
+   TIKTOK_CLIENT_SECRET=…
+   ```
+   Under Login Kit → Redirect URI, register `http://127.0.0.1:*/callback/`: the
+   login comes back to a free port on this machine.
+3. **You as a tester.** Until the app is approved, add your TikTok account under
+   Sandbox → Target users (or use the app in sandbox mode).
+4. **Login.** `node tools/publish.mjs auth tiktok` (or the button in
+   Configurações). The tokens go to `.env` (`TIKTOK_ACCESS_TOKEN`,
+   `TIKTOK_REFRESH_TOKEN`…). Access lasts 24 h and renews itself on every use; the
+   login lasts a year.
+
+**Only me until the audit.** An unaudited app can only post directly as "Only
+me" (`SELF_ONLY`), even if you ask for something else, and only to a **private
+account**. On a public account TikTok refuses
+(`unaudited_client_can_only_post_to_private_accounts`) and `publish.mjs` sends
+it as a draft to the app's inbox, where you finish the post. To unlock it,
+request the Content Posting API audit and set `publish.tiktok.audited: true`
+(Configurações → TikTok → App auditado (App audited)).
+
+**Draft.** With `publish.tiktok.mode: "draft"` the video goes to the TikTok
+app's inbox, and you finish the post there (music, cover, text). It doesn't
+depend on the audit.
+
+Comments, duet, stitch, the AI-generated content label (`ai_content`) and the
+cover (`cover_at_s`) live in `publish.tiktok`. The video needs at least 3 s,
+and the maximum duration is whatever the account allows (publish checks it
+first).
+
+## Cover
+
+The cover is the thumbnail selected in the studio's Publicar stage ("Usar este
+na publicação" (Use this one for publishing), or
+`node tools/thumbnail.mjs videos/<slug> choose v2`), which becomes
+`thumbnail/thumbnail.png`. `publish.mjs` reads it **at upload time**: a
+scheduled post takes whatever is selected when the scheduler runs, and the form
+shows which one will go. `node tools/publish.mjs cover videos/<slug>` says the
+same in the terminal, without publishing anything.
+
+| platform | how it goes |
+|---|---|
+| YouTube | `thumbnails.set` right after the upload, as a JPG up to 2 MB. The channel needs advanced features (phone verification, youtube.com/verify); without them, YouTube refuses with 403. On Shorts the API accepts it, but YouTube doesn't guarantee the cover in the Shorts feed |
+| Instagram | `cover_url`, through the same temporary link as the video, instead of `cover_at_s` |
+| TikTok | doesn't go: the API only accepts a frame of the video (`cover_at_s`) |
+
+With no thumbnail selected, each platform uses its usual frame. A failing
+cover doesn't bring the video down: it uploads (Instagram retries without the
+cover), publish warns, and the result stores
+`cover: { version, applied: false, error }`.
+
+## Schedule
+
+In the Publicar stage, choose **Agendar** (Schedule), the day and time (this
+Mac's time), and confirm. It is the same request as the Publicar button
+(platforms, privacy, text), stored in `publication.json` (`schedule`) to go up
+later. While it waits, the stage shows "agendada" (scheduled) and the card with
+the time, from where it can be cancelled. Scheduling again replaces the previous
+schedule.
+
+To change only the time, drag the post in the studio's **Agenda** (Schedule)
+screen, or
+`node tools/publish.mjs schedule videos/<slug> --reschedule --when "2026-10-15 09:30" --confirm`.
+Platforms, privacy and text stay; the state goes back to `scheduled` and the
+attempts restart (a schedule that failed or missed its time, once rescheduled,
+is valid again).
+
+What publishes on time is the **scheduler agent**: a macOS LaunchAgent
+(`~/Library/LaunchAgents/com.omnivideo.schedule.plist`) that runs
+`publish.mjs scheduler run` every minute, with the studio open or closed. Turn
+it on once in Configurações → Publicação → Agenda (Settings → Publishing →
+Schedule) (or `scheduler install`). It uses the `node` of whoever installed it:
+if you switch node versions, turn it on again. The log is in
+`.schedule/schedule.log`.
+
+- **Late.** A video that couldn't go up at its time still goes up to
+  `publish.schedule.max_delay_h` (12 h) after it; past that, it is **missed** and doesn't go up.
+- **Failure.** A platform that fails retries on its own, up to
+  `publish.schedule.attempts` times (3), every `interval_min` (10 min). Then it
+  becomes **failed**, with the reason, waiting for you to schedule again or
+  publish now. The ones already up don't go up again.
+- **Publishing by hand** a scheduled platform removes it from the schedule.
+- **Instagram:** the `cloudflared` tunnel opens at publishing time, so the
+  internet has to be up at that time, as with the button.
+
+```bash
+node tools/publish.mjs schedule videos/<slug> --when "2026-10-14 18:00" --youtube --tiktok --confirm
+node tools/publish.mjs schedule videos/<slug> --cancel
+node tools/publish.mjs scheduler                  # the agent and everything scheduled
+node tools/publish.mjs scheduler install          # turns the agent on (uninstall turns it off)
+```
+
+### In the cloud (cloud.schedule)
+
+With `cloud.schedule: true` in the config, the Worker in `cloud/omnichat` publishes at the time. Scheduling does here what needs this
+machine (the text, ffprobe, the cover JPEG and the omnichat rule the Reel will have, from
+`omnichat.mjs published --plan`), uploads the MP4 and the cover to the cloud's R2 (deleted when the job
+ends, or by a 7-day rule) and stores the job there; `--reschedule` and `--cancel` go to the cloud.
+
+- **One short step a minute.** YouTube uploads in one; Instagram creates the container, then looks at
+  it each minute until it is processed, then publishes (it downloads the video from the Worker's
+  `/media/<key>`); TikTok uploads, then looks each minute. That keeps each run within the Workers Free
+  plan (10 ms of CPU, 50 subrequests). A failed step retries every `interval_min`, up to `attempts`.
+- **The minute cron reads KV first** (`schedule:next`), so the database only wakes when something is
+  due.
+- **When the Reel is live,** the cloud turns on its omnichat rule and adds it to the metrics right away.
+- **This Mac's agent** only reads the outcome after the time (`scheduler run`) and writes the platform
+  entries into `publication.json`, as a local run would; until it does, the studio shows "agendada".
+- **Credentials:** `publish.mjs cloud push` sends YouTube's and TikTok's (sealed there). TikTok renews
+  its refresh token on every renewal, so while the cloud schedules, this machine takes TikTok's newest
+  tokens from the cloud before using them and sends back what it renews: one chain, never two.
+- A schedule made before the switch stays local: `cloud push` sends the pending ones up.
+
+## In the terminal
+
+```bash
+node tools/publish.mjs text videos/<slug>              # title, description and post caption from the script
+node tools/publish.mjs videos/<slug> --youtube --instagram --tiktok --confirm
+node tools/publish.mjs videos/<slug> --youtube --privacy unlisted --confirm
+node tools/publish.mjs videos/<slug> --tiktok --tiktok-privacy FOLLOWER_OF_CREATOR --confirm
+```
+
+`--confirm` exists because publishing goes outward: Claude only runs this when
+the user asks. Scheduling also takes `--confirm`: it is the same request, made
+now to go up later.
+
+## publication.json
+
+```json
+{
+  "title": "…", "description": "…", "caption": "", "tags": ["…"],
+  "text_generated": { "at": "…", "by": "claude" },
+  "youtube": { "id": "…", "url": "https://youtube.com/shorts/…", "studio": "…", "privacy": "private",
+               "published_at": "…", "mp4": "export/<slug>.mp4", "mp4_mtime": 0 },
+  "instagram": { "id": "…", "url": "https://www.instagram.com/reel/…", "published_at": "…", "mp4": "…", "mp4_mtime": 0 },
+  "tiktok": { "id": "…", "publish_id": "…", "url": "https://www.tiktok.com/@…/video/…", "privacy": "SELF_ONLY",
+              "published_at": "…", "mp4": "…", "mp4_mtime": 0 }
+}
+```
+
+`caption_instagram` is the old name of `caption`: it is still read. In draft
+mode, `tiktok` gets `"draft": true` and has no `url`. The TikTok link only
+exists after the post becomes public and passes moderation.
+
+When an attempt fails, the reason goes in `<platform>.last_error`. When a video
+goes up again, the previous id goes to `<platform>.previous`.
+
+With the Reel live, `publish.mjs` calls `omnichat.mjs published`: an omnichat
+rule that is already enabled starts replying on it and, with
+`omnichat.instagram.enable_on_publish`, a missing one turns on by itself
+(`reference/omnichat.md`, On publish). An omnichat failure is a warning: it
+doesn't bring the publication down.
+
+When scheduled, the file gets a `schedule`, which is removed once everything is
+up; each platform published by the scheduler stores the scheduled time in
+`scheduled_for`:
+
+```json
+"schedule": {
+  "when": "2026-10-14T21:00:00.000Z", "platforms": ["youtube", "tiktok"],
+  "privacy": "private", "tiktok_privacy": "SELF_ONLY", "republish": false,
+  "state": "scheduled", "attempts": 0, "created_at": "…", "origin": "studio"
+}
+```
+
+`state`: `scheduled` (waiting for the time or the next attempt, in
+`next_attempt`), `publishing`, `failed` or `missed`; the reason for the last two
+is in `last_error`.

package/reference/scenes-contract.md

@@ -0,0 +1,109 @@
+# The `scenes.json` contract
+
+One file per video, at `videos/<slug>/scenes.json`. It is the only source of
+scene, beat, line, duration and position. Each field has **one** owning stage;
+the others only read it. A full example is in `templates/scenes.example.json`.
+
+## Root
+
+| field | owner | what it is |
+|---|---|---|
+| `slug` | 0 · open | `YYYY-MM-DD-subject`, also the export name (`export/<slug>.mp4`) |
+| `title` | 1 · script | working title |
+| `format` | 2 · motion script | `{ aspect: "9:16" \| "16:9", w, h, fps }` |
+| `references` | 2 · motion script | library folders (`references.dir` in the config) the style came from: `["apura-paraguai"]` |
+| `captions_in_motion` | 2, optional | `true` when the captions are drawn by the motion itself (from `OMNIVIDEO.video`); `assemble.mjs` does not burn the captions layer. `captions.srt` is still generated |
+| `captions` | 8 · assembly, or the studio's Legenda (Captions) stage; optional | where the burned captions appear: `{ platform, anchor, x, y, style, scenes: { <scene>: { anchor?, x?, y? } }, individual: { <line>.<n>: { anchor?, x?, y?, hidden? } }, texts: { <line>.<n>: { text, original } } }` (`hidden: true` turns that caption off: assembly does not burn it; `texts` is the text edited in the studio, already written to `captions.srt`, and `original` is what the line generated). Each level overrides the previous one; whatever is missing comes from `captions.default_position` in the config. Rules in `reference/captions.md` |
+| `voice` | optional | voice for this video only: `provider` (`fish`, `cartesia` or `voicestudio`; the others in the config's `voice.order` stay as fallback; the studio screen writes here), `speed` (applies to all lines), `voice_profile` (the `id` of a voice in the config's `voice.profiles`: its Fish `voice_id`, its Cartesia one and its VoiceStudio profile, plus the `order` to try them in; without it `voice.default_profile` applies, and with no voice at all each provider's `voice_id` and `voice.order`; a voice that no longer exists fails Fish and Cartesia with the reason, without switching voices), and for VoiceStudio `profile`, `language`, `num_step` |
+| `preview` | legacy | the preview a video from before 2026-10-17 had approved (stage P no longer exists): ignored |
+| `bed` | 3, optional | track under the video (music or texture), from `<video>/sfx/`: `"name.mp3"` or `{ name, db, from, to, trim, fade, loop, duck }`. `from`/`to` in seconds of the video (default: all of it); `loop` repeats the trim (texture only). Level: `sound.bed.level_db` below the voice, ducking `sound.bed.ducking_db`. The bed is isolated: `cuts` and `speed` never cut it or change its tempo; it plays straight through on the final timeline, ducked by the voice where the voice ends up (`from`/`to` say which part of the video it covers) |
+| `speed` | 6 · studio Editor, optional | export speed, `1` to `1.5` (always written by the editor, even at `1`). `assemble.mjs` writes the base export at 100% (the editor's picture) and a second one, `export/<slug>-speed-<pct>.mp4`, that `assembly.json` then points to: picture, voice and effects sped up (voice without changing pitch), the bed not |
+| `cuts` | 6 · studio Editor (the Corte de área (Range cut) tool), optional | `[{ from, to }]`, in seconds of scenes.json time (the video with no cuts at all), frame-aligned and non-overlapping: ranges removed from the export. `assemble.mjs` cuts at the end, with picture, captions and sound already assembled, and joins the rest; whatever crosses a cut loses only the part inside it. Voice, timing, render and `sound/` do not change. Conversions and rules in `tools/cuts.mjs`; `assembly.json` stores the cuts the export has |
+| `scenes` | 2 · motion script | ordered list; the order is the timeline order |
+| `total_duration` | 5 · `omnivideo.py timing` | sum of the scene durations |
+
+## Scene
+
+| field | owner | what it is |
+|---|---|---|
+| `id` | 2 | `c01`, `c02`… |
+| `title`, `goal`, `visual`, `hero` | 2 | what the scene communicates and shows; `hero` is the single highlighted element |
+| `min_duration` | 3 | the minimum the motion needs, a multiple of 0.6 s |
+| `html`, `mp4` | 2 | relative paths: `motion/c01.html`, `motion/c01.mp4` |
+| `transition` | 3, optional | how the scene enters from the previous one: `"cut"` (default) or `{ "continues": ["card", "bg"] }`, the `data-continues` elements that must not jump at the cut. `sound` in the object (with or without `continues`) puts an effect on the cut, at the instant `scene.start` (same fields as a beat's `sound`). Ignored on the first scene |
+| `beats` | 3 (`element`, `t`, `sound`) · 4 (`enters_with`, through `narrate.mjs apply`) | see below |
+| `lines` | 4 (`id`, `text`, through `narrate.mjs apply`) · 5 · 7 | see below |
+| `clips` | 6 · studio Editor (Navalha (Razor), drag, delete), optional | pieces of the scene MP4: `[{ from, to, offset, speed? }]`, `from`/`to` in seconds inside the MP4 (frame-aligned), `offset` how far the piece moves from its own place (negative moves it earlier) and `speed` (0.5 to 2, absent = 1) how fast the piece plays: it lasts (to − from) / speed from the same start, and what follows stays put (the gap holds the last frame). The Razor splits a clip in two; anything not in any clip was deleted. Without `clips`, the whole MP4 in place (or shifted by the old `video_offset`, which is still read). Beat and transition effects move with the piece they fall in (a beat in a deleted piece is dropped). `assemble.mjs` builds the picture with `tools/soundtrack.mjs`: where two pieces overlap, the one that started last shows, and in a gap the picture holds the last frame. A background that moves on video time may jump where a piece was shifted |
+| `lead_in`, `hold` | 3, optional | seconds before the first line and after the last one, for this scene only (default: the config's `timing.lead_in` and `timing.final_hold`). A sentence that continues into the next scene uses `hold: 0` here and a comma-sized `lead_in` there |
+| `duration` | 5 · `timing` | final duration, frame-aligned: `max(end of last line + hold, min_duration)` |
+| `start` | 5 · `timing` | second at which the scene starts on the timeline |
+
+## Beat
+
+| field | owner | what it is |
+|---|---|---|
+| `element` | 3 | name of what enters; becomes the CSS variable `--b-<element>` |
+| `t` | 3 | provisional time in seconds, used until a voice exists |
+| `enters_with` | 4 | reference to the line: `c01f2`, `c01f2:end`, `c01f2:palavra`, `c01f2:palavra#2`, with optional `+0.3`/`-0.3`. The word is the spoken (PT) word; `:fim` is still accepted as a legacy alias of `:end` |
+| `sound` | 3, optional | effect on the beat: a file name in the global kit (`kit/sfx/kit.json`) or in `<video>/sfx/`, captured from Epidemic and registered in `sfx/sources.json` (`"clique-seco.mp3"`), an object with adjustments, or a list of them (layers at the same instant). Fields below |
+
+`tools/timing.mjs` → `beatTime(scene, beat)` resolves it: `enters_with` if
+present, otherwise `t`.
+
+### Fields of a `sound`
+
+| field | default | what it is |
+|---|---|---|
+| `name` | required | file in the video's `sfx/` or in the global kit (`kit/sfx/`); the video's one wins. From the kit, the role's `db` is added (`sound.roles`) |
+| `anchor` | `"peak"` | which point of the effect lands on the instant: `"peak"` (the loudest sample) or `"start"` |
+| `offset` | 0 | seconds after the instant (negative: before) |
+| `db` | 0 | adjustment over the default level: `sound.level_db` below the voice's integrated loudness |
+| `trim` | whole file | `[from, to]` in seconds inside the file; `to: null` goes to the audible tail |
+| `fade` | `[0, 0.05]` | `[in, out]` in seconds (4 ms fade-in when the trim does not start at 0) |
+| `dur` | — | stretches or shrinks the trim to last this long, without changing pitch (continuous motion) |
+| `speed` | 1 | speed factor; `dur` takes precedence. Limited to 0.25× to 4× |
+| `pitch` | 0 | semitones, without changing duration |
+| `duck` | `sound.ducking.db` | ducking under the voice for this effect only, in dB; `false` turns it off |
+
+Each effect becomes `sound/<id>.wav` (`tools/sound.mjs`): id `<scene>-<element>`,
+`<scene>-transition`, and `-2`, `-3`… for layers. The WAV comes out already
+trimmed, processed, at volume and with ducking, starting at
+`instant + offset − anchor`. The volume is measured after processing, by
+perceived loudness (K-weighting over the `sound.window_s` window), not by peak.
+`sound/plan.json` stores everything, including the voice segments that drive
+the ducking.
+
+## Line
+
+| field | owner | what it is |
+|---|---|---|
+| `id` | 4 | `<scene>f<n>`: `c01f1`, `c01f2` |
+| `text` | 4 | what the voice says and the captions show, with final spelling and punctuation |
+| `instruct` | 4, optional | style instruction for the voice (`"animado"`, `"sussurrando"`) |
+| `wav`, `dur`, `hash` | 5 · `voice` | generated audio, duration in seconds, hash of text + voice + config of the provider that generated it |
+| `provider`, `provider_requested` | 5 · `voice` | who generated the line and which provider the video had at that time; different = it came from fallback. A line with no `provider` predates providers (VoiceStudio) |
+| `voice_profile` | 5 · `voice`, optional | the `id` of the voice (profile in `voice.profiles`) that spoke the line, for the studio player. Older lines don't have it; they show no voice name |
+| `provider_pinned` | 5 · `voice`, optional | `true` when the line was generated with a provider chosen just for it (`voice --regenerate <line> --provider <id>`, the select next to "Gerar outra fala" (Generate another take)) or when the user picked a version from another provider in the studio (`voice --use`): it is a choice, not a fallback. The general `voice` run and `--regenerate-fallback` don't redo it, and it is left out of the mixed-voices warning. It disappears when the line is generated again without a choice |
+| `start`, `end` | 5 · `timing` | position **inside the scene**, in seconds |
+| `clips` | 6 · studio Editor, optional | pieces of the line's WAV, like the scene's `clips` (`from`/`to` in the audio, in ms; `speed` plays the piece faster with its pitch kept, through atempo). Without `clips`, the whole line in place. Captions and ducking move with the voice piece; a range outside the clips is silent and its caption is dropped |
+| `words` | 7 · `captions` | `[{ w, s, e }]`, time of each word **inside the line**, measured on the audio (no transcription) |
+
+Absolute time of a word on the timeline:
+`scene.start + line.start + word.s`.
+
+## Invalidation
+
+| changed | becomes invalid | who recomputes |
+|---|---|---|
+| `line.text` or the voice profile | `wav`, `dur` and everything that depends on timing | `voice` detects it by the hash and clears the line's `start`, `end`, `words` |
+| any `dur` | `start`/`duration` of every scene | `timing` |
+| a scene's `duration` | that scene's MP4 and the following MP4s, if some background moves on video time (`--scene-start`) | `build-motion.mjs --render` |
+| `transition`, `data-continues` or `motion/src/_common.html` | the scenes on both sides of the cut | `build-motion.mjs --transitions --render` |
+| a beat's or transition's `sound`, `bed`, the voice, or any timing | `sound/` (level and ducking depend on the voice) | `assemble.mjs` (redoes `sound/` by itself) |
+| `captions` (position) or `motion/src/_captions.css` | the export | `assemble.mjs` |
+| `cuts` or `speed` | the export (the background music is not cut or sped up) | `assemble.mjs` |
+| `clips` (scene or line) | `sound/` (beats and ducking move) and the export | `assemble.mjs` |
+| anything above | `captions.srt`, export | `captions`, `assemble.mjs` |
+
+`omnivideo.py status` checks most of this, including whether each MP4's
+duration matches `scene.duration`.