author-overlay
Author and review AKARI Video overlay HTML, captions, tables and charts, motion graphics, thumbnails, and text-behind-person effects. Routes the work to the relevant authoring leaf.(旧名: overlay-authoring)
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 214
- Forks
- 25
01 前言 Front Matter
- name
- author-overlay
- description
- Author and review AKARI Video overlay HTML, captions, tables and charts, motion graphics, thumbnails, and text-behind-person effects. Routes the work to the relevant authoring leaf.(旧名: overlay-authoring)
02 资源文件 11
- 参考文档3d.md429 B
- 脚本dev-fixtures/test_device_materials.py4.2 KB
- 参考文档glass.md5.0 KB
- 参考文档lang/en.md4.7 KB
- 参考文档lang/ja.md3.2 KB
- 参考文档motion.md14.7 KB
- 参考文档table.md4.4 KB
- 参考文档telop.md17.5 KB
- 参考文档text-behind-person.md14.4 KB
- 参考文档thumbnail.md7.1 KB
- 参考文档world.md4.3 KB
03 SKILL.md 正文
FORBIDDEN-level hard rules
Language: Respond in the user's language — conversation, questions, approval prompts, and the reports and records you write (including decision-log rows) follow the language the user writes in.
Never create or accept a video overlay that violates any rule below. These rules always outrank the detailed leaves.
Do not read all of edit.json or captions.json; grep by ID and read only matching lines (how to read edit.json).
For writes, use Edit on the matching lines or the edit-store script API.
Read lang/<content-language>.md for language-specific rules (content language: --lang → intake.json "language" → transcript language → ja; see https://github.com/AkariLabs/akari-video/blob/main/docs/contract-2026-10-11-content-language.md). If that file does not exist, read lang/en.md.
- Never hardcode adjustable values. Expose human-adjustable position, scale, font size, color, spacing, and content through CSS variables. Use nonreserved names such as
--font-size,--color, and--block-left. Reference them asvar(--name, fallback)so they inherit fromedit.json.overlays[].vars. Do not redefine the same variables on the fragment root: doing so blocks overrides from the outer vars.--x/--y/--scale/--rotateare runtime-reserved variables (renderOverlayNodeinpackages/render-cut/src/rasterize.mjsalways sets them inline on.akari-overlay-container. Values come fromoverlays[].transform;role==="background"forces identity values). Neither reference these four variables (var(--x, ...)) nor redefine them for your own use inside a fragment. Inheritance prevents the fallback and causes specified values to be ignored, pulling every overlay toward the origin (0,0; scale 1; rotate 0). This was observed inoverlay-css-var-collisionon 2026-08-17; edit-lint passes and rendering succeeds, so it can escape notice until visual inspection. Define nonreserved position, scale, and rotation knobs such as--block-left/--block-scale. - Never put timing on the fragment root.
edit.jsonis the SSOT for timeline start and duration; the runtime applies these to the outer container. Do not placedata-start/data-durationon the fragment root. If the asset's natural duration is needed, record it in seconds asdata-akari-natural-duration; write internal motion in local seconds starting at clip time 0. - Never animate layout every frame. Animate mainly
transform/opacity.filter: blur()andbackdrop-filterare forbidden over 4K video. - Never determine an image from wall-clock time. Do not depend on
Date.now(), elapsed differences fromperformance.now(),setTimeout,setInterval, accumulated rAF deltas, or unseeded randomness. Use deterministic motion so setting WAAPIcurrentTimeon seek reproduces the same frame. - 3D work belongs to author-scene3d. This skill covers 2D motion parts; do not author 3D here.
- Do not create multiple top-level elements. The HTML fragment must have exactly one root element so the AKARI outer container's translate / scale / rotate always applies.
Pointer hit testing
The runtime makes its full-screen container and the HTML fragment root pointer-events: none by default, leaving margins available to select video or layers below. It automatically restores pointer-events: auto only on visible descendants that actually draw a background, border, shadow, text, image, video, canvas, or SVG.
If an element needs different hit behavior, put data-akari-hit="catch" (catch below it) or data-akari-hit="pass" (pass through below it) on the element or an ancestor of the range. The nearest explicit setting inherits downward and outranks automatic detection. Use catch only with a deliberate reason, such as a transparent drag surface; do not casually put it on the full-screen root.
Elements directly editable in preview
This is not a FORBIDDEN-level hard rule (the image survives if it is ignored), but an element with neither class nor id cannot later be targeted individually in preview. Build likely direct-edit targets as follows.
- Only elements with a class or
idcan be selected directly in preview. Clicking one without either selects its nearest ancestor with a class orid; design with this in mind. - Put a meaningful class on bars, labels, headings, icons, and cards (
bar,value-label,legend-item,card-title, etc.) before visual utility classes. The first class forms the address. - Give elements with the same role the same class (all five bars should be
bar). Addresses use the index within that class, so additions, deletions, or reordering can shift an override to a neighbor. Revisit per-element overrides inedit.jsonsource.elementsif applied to that fragment. - An SVG is selectable as one picture; its internal
rectortextis not individually selectable. Build a chart whose individual bars or labels need direct editing with div + CSS. Use SVG for icons, logos, curves, and other pictures that can move as a unit. - When splitting a text effect into one
spanper character, the whole heading remains one selection unless eachspanhas a class. Add those classes only when character-level editing is intended. - Set finished bar or box dimensions with
width/height(px), and arrange neighbors with flex / grid. Changing a box then reflows its neighbors. Never create finished dimensions withtransform: scale(). Animate entry withtransformending at natural size (for examplescaleY(0)→scaleY(1)) andopacity, while final dimensions depend only onwidth/height. - Use a name tag (
data-akari-part) when an element needs its own time and motion and must appear as a timeline row. A class marks an element whose position, rotation, or box is sufficient to edit. See object-tree contract §§1.3–1.4 for name tags. - A general role name such as
baris fine for a class (addresses are counted inside the fragment). Keep CSS selectors scoped under a fragment-specific root as before (for example.sales-chart .bar).
Element overrides use translate / rotate / width / height and never touch child transform, so the outer-container geometry in motion.md can coexist with child motion transforms.
Leaf index
Read only the decision area needed.
- Subtitle and telop readability and placement: telop.md. Language-specific typesetting is in lang/<code>.md.
- HTML/CSS structure and animation for tables and charts: table.md
- 3D scenes (Three.js + glTF live scenes, 3D text, device screens, Blender bake): author-scene3d. Read it before any 3D fragment; this skill covers 2D only.
- Glass refraction declarations, nesting, knobs, and still backdrops: glass.md
- Canvas 2D worlds, DOM-sheet synchronization, and bird's-eye views: world.md
- Register new rendering types in the
packages/overlay-runtime/runtimes.mjsmanifest (procedure:packages/overlay-runtime/README.md). - Deterministic motion, easing, and compositor limits: motion.md
- Thumbnail patterns, design vocabulary, generation routes, and HTML screenshots: thumbnail.md
- Person cutouts, HEVC alpha, and text behind a person: text-behind-person.md
An HTML sheet for a still thumbnail is not a video overlay and needs no timing data attributes. It must still use CSS variables, a single root, local assets, and deterministic screenshots.
An overlay's library meta.json must declare asset contract v1 tier, for example "tier": "free" with "license": { "spdx": "CC0-1.0", ... }. Use "tier": "pro" for Pro and never specify CC0-1.0 in license.spdx. Confirm the tier with the creator (asset tier contract).
04 同仓库更多 Skills
verify-project
Verify an AKARI Video project with the L0 / L1 / L2 verification ladder required by an AKARI Video task contract on the current Theia stack. Read when acceptance criteria specify levels such as L0 or L0+L1, to determine exactly what to run and how at each level.(旧名: verify)
verify-edit
Verify edit.json and optional analysis.json / captions.json / media with a deterministic CLI, then finish QA with frame inspection and reporting after PASS. Use immediately after writing or modifying edit.json, before export, and after applying review feedback.(旧名: edit-lint)
setup-remote
Set up remote access to approval reports and previews from another device such as a phone, and send footage to the workspace. Use doctor to assess Tailscale, guide installation and login (human actions), expose the preview server (default 4567) and approval report helper over tailnet-only HTTPS with tailscale serve, connect Taildrop reception to workspace inbox/, and verify access from another device. Use for requests to view reports on a phone, approve remotely, send footage from a phone, or set up remote access. Public internet exposure (funnel) is outside the default scope.
setup-project
Set up an AKARI Video project headlessly. Recursively copy `templates/project-default/`, record the template version, initialize git only when safe, and generate an HTML creation report. No app launch is needed. Use to create a video project or fill in an existing folder as an AKARI Video project.(旧名: create-project)
setup-library
Use for first-time AKARI Video setup or when the current project needs more usable assets. This first-run skill checks ffmpeg / whisper-cli (and can install with approval), reads the bundled catalog with akari assets to propose a starter pack, obtains explicit human approval, then acquires, places, validates, and updates INDEX entries. It also covers the audio library (BGM and sound effects): bulk acquisition of first-party AKARI Sounds from GitHub Releases, a free-source candidate HTML list with drop-folder matching or assisted acquisition for missing families, and keep/drop decisions in the listening gallery. Use for requests such as "I want more BGM" or "add sound effects to the library".(旧名: setup-audio-library)
setup-connections
Set up and inspect AKARI Video connections: AI-service keys, which models are allowed, cost-approval policy, the tool and media-service state, and 3D settings. Use for first-time setup, adding a provider or key later, checking what is usable (「何が使える?」 'what can I use?'), setting a key such as fal (「fal の鍵を設定したい」), 3D settings (「3D の設定を使いたい」), connection checks, and gates before paid generation or external publication. Model selection belongs to the production skills (they read the ledger and preferences); this skill decides allowed models and the cost policy. Works with `.akari/connections.json` and a free, read-only doctor.(旧名: manage-connections)(旧名: connect)