@indreamai/openclaw-plugin 0.1.0

package/skills/indream-editor-json/references/structure-and-principles.md

@@ -0,0 +1,159 @@
+# Structure and Principles
+
+## Mental model
+
+Indream editor JSON is easiest to author when you treat it as five linked layers:
+
+1. `assets`
+   Source media and source subtitle data.
+2. `items`
+   Timeline instances that place assets, text, shapes, effects, filters, and charts in time.
+3. `tracks`
+   Ordered clip lists that define which items belong together on one timeline lane.
+4. `transitions`
+   Same-track joins between adjacent clips.
+5. Optional top-level extras
+   `outputRatio`, `globalBackground`, `deletedAssets`, and any valid metadata already present in an existing draft.
+
+## Required top-level fields
+
+- `compositionWidth`
+- `compositionHeight`
+- `timebaseTicksPerSecond`
+- `tracks`
+- `assets`
+- `items`
+- `transitions`
+
+`timebaseTicksPerSecond` must always be `240000`.
+
+## Composition sizing
+
+Rules from the schema:
+
+- `compositionWidth`: integer from `50` to `1920`
+- `compositionHeight`: integer from `50` to `1920`
+- `outputRatio`: optional, one of `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `custom`
+
+Practical authoring guidance:
+
+- Use concrete width and height first.
+- Add `outputRatio` when the user asked for a standard aspect ratio or when it improves readability.
+- If the user says "vertical short video", `1080 x 1920` with `outputRatio: "9:16"` is a clear default.
+- If the user says "YouTube landscape", `1920 x 1080` with `outputRatio: "16:9"` is a clear default.
+
+## Build order
+
+Write editor JSON in this order:
+
+1. lock composition width, height, ratio, and high-level scene count
+2. create or map all assets
+3. create each item with full required fields
+4. place item IDs into tracks
+5. add transitions only after track order is stable
+6. add optional global background and preserve existing valid metadata only when needed
+7. validate
+
+## Stable ID strategy
+
+Prefer readable and stable IDs such as:
+
+- `track-main`
+- `track-captions`
+- `asset-hero-video`
+- `item-hero-video`
+- `item-lower-third`
+- `transition-scene-1-2`
+
+Do not rename valid IDs during repair unless the failure is caused by an ID mismatch.
+
+## Static and animated number tracks
+
+Many numeric item properties are not raw numbers.
+They must use the animated number track shape:
+
+```json
+{
+  "value": 1,
+  "keyframes": []
+}
+```
+
+Use static tracks by default.
+Add keyframes only when the user actually wants motion such as:
+
+- slide-in or slide-out movement
+- zooms
+- fades driven by `opacity`
+- rotating badges or callouts
+
+Example:
+
+```json
+{
+  "opacity": {
+    "value": 1,
+    "keyframes": [
+      { "timeTicks": 0, "value": 0 },
+      { "timeTicks": 24, "value": 1 }
+    ]
+  }
+}
+```
+
+## Track planning patterns
+
+### Sequential slideshow
+
+Use one primary track when the timeline is a simple sequence of back-to-back scenes.
+This is the easiest place to add transitions.
+
+### Layered promo
+
+Use separate logical tracks when the timeline has:
+
+- a primary footage layer
+- a text or subtitle overlay layer
+- decorative shapes or stickers
+- music or narration
+
+### Subtitle-driven video
+
+Use:
+
+- one primary video track
+- one captions track with a `captions` item
+- optional overlay text track for title cards and callouts
+
+## Transition rules
+
+Transitions belong in `transitions`, not in `items`.
+Each transition must:
+
+- reference one `trackId`
+- use `fromClipId` and `toClipId` that are adjacent in that track
+- use a supported transition type
+
+Do not create transitions across different tracks.
+
+## Optional top-level sections
+
+### `globalBackground`
+
+Use when the entire composition needs a background treatment.
+Supported schema forms:
+
+- `none`
+- `color`
+- `blur`
+- `image`
+
+### `brandRuntime`
+
+This field can appear in existing drafts.
+Preserve it if it is already present and valid, but do not treat it as a new authoring surface for this Open API skill.
+
+### `deletedAssets`
+
+Usually preserve this from an existing draft.
+Do not populate it during a fresh authoring pass unless you are deliberately editing asset deletion state.

package/skills/indream-editor-json/references/template-catalog.md

@@ -0,0 +1,45 @@
+# Scene Template Catalog
+
+These templates are meant to be copied, adapted, and validated.
+They cover common user requests while demonstrating real editor-state patterns.
+
+## Template list
+
+1. `templates/hello-world.json`
+   Minimal greeting scene with a solid background, centered text, clip animation, and caption animation.
+
+2. `templates/gallery-carousel.json`
+   Three-image carousel with transitions, overlay copy, and a timed filter window.
+
+3. `templates/product-intro.json`
+   Product hero scene with image media, geometric shapes, illustration support art, and an opening effect.
+
+4. `templates/subtitle-promo.json`
+   Vertical promo scene with a caption asset, styled subtitles, title copy, and subtitle animation.
+
+5. `templates/chart-showcase.json`
+   Data-driven showcase with multiple chart types, transitions, supporting copy, and timed look changes.
+
+6. `templates/illustration-board.json`
+   Hand-drawn vector collage scene built from the live illustration library and geometric decorations.
+
+7. `templates/keyframe-motion-lab.json`
+   Motion-focused scene that demonstrates single-keyframe entry motion, scale changes, opacity ramps, and timed effects.
+
+## How to use the catalog
+
+1. Pick the closest template for the user's request.
+2. Replace assets, copy, colors, and timing.
+3. Keep the required field shapes intact.
+4. Validate the edited state.
+5. If validation fails, repair the smallest possible part of the JSON.
+
+## Selection guidance
+
+- Use `hello-world` for the absolute minimum valid scene.
+- Use `gallery-carousel` for album-style slideshows and travel reels.
+- Use `product-intro` for launch, e-commerce, and feature callouts.
+- Use `subtitle-promo` for short-form caption-heavy edits.
+- Use `chart-showcase` for analytics, dashboard, and business storytelling.
+- Use `illustration-board` for hand-drawn vector compositions.
+- Use `keyframe-motion-lab` when the user wants custom motion beyond standard clip animations.