# KIRA Studio authoring guide for creators and AI This guide covers four KIRA Motion asset types, spatial video edits, and editable mesh scenes. Use the chapters that match your assignment. The tutorial page introduces the workflow and this file provides the syntax and examples to attach to Claude, Argon, or another assistant. ## 1. Give your AI a clear brief 1. Download this Markdown file. Attach it to a new AI chat or paste its contents if the chat accepts text only. 2. Describe the result. Include the asset type, duration, canvas size, where the effect appears, and which elements should stay editable. For a reference clip, attach it and describe its key moments in words. 3. For a Graphic, Effect, Transition, or Template, ask for one complete `.kmotion` file or its complete source in a single code block. Copy only the file contents into KIRA. 4. For a mesh scene, use the live 3D workflow in section 8 when your AI already has a KIRA MCP connection. A text-only chat can draft a shot plan and scene data for review. 5. Compile and place the result in a sample project. Give the AI the exact diagnostic or a screenshot with the time and expected result when you want a revision. ### Copy this prompt > Read the attached KIRA Studio authoring guide. Build a 6-second transparent lower third for a 1920 × 1080 YouTube video. Use a soft coral accent that slides in, a clean hold, and a short exit. The title and subtitle must remain independently editable. Include an optional replaceable PNG logo slot. Return one complete KIRA Motion Template using the exact version 1 wrapper and composition syntax. Use native text layers. Include all code and describe how to import it and what I should see at the start, middle, and end. Tell me which checks you actually ran. For an Effect, replace the design request with a change to the source footage. For a Transition, describe the change from outgoing A to incoming B. Ask for the entire corrected file on each revision so imports remain reproducible. ## 2. Choose the right asset | Type | When to use it | Where it goes | | --- | --- | --- | | Graphic | An overlay, ident, background, or procedural animation | Its own timeline clip | | Effect | Change the look of footage, such as a color treatment or distortion | Apply to a selected clip | | Transition | Animate the cut between two neighboring clips | Apply at their shared cut | | Template | Keep text, PNG slots, and graphic layers editable | Add as a compound and open it to edit its children | Open Shader Studio from the Library. In Studio, **Import code** accepts a saved file and **Paste code** accepts the complete source. Choose **Compile**, read the result, and use **Save to Custom** to keep the asset. Choose **Add to timeline**, **Apply to clip**, **Apply at cut**, or **Add compound graphic** according to the asset type. Saved library names and the library panel can vary by build. ## 3. KIRA Motion file format A shareable shader asset is a text `.kmotion` file. Begin with one metadata comment. Use the exact case for `Graphic`, `Effect`, `Transition`, or `Template`. Change the name, kind, and positive duration to match your design. ```hlsl /* KIRA_MOTION_V1 { "version": 1, "kind": "Graphic", "name": "Coral Orbit", "duration_seconds": 6.0 } KIRA_MOTION_END */ ``` Put this comment before the shader. For Templates, put the composition comment directly after the metadata. Both comments contain valid JSON. Keep the delimiters exact and escape any comment terminator inside strings as `*\/`. Keep the two durations equal for a Template. Plain `.hlsl` source is also accepted. Use the wrapper to make the intended asset category explicit when sharing an asset. ## 4. The shader contract Use the following header once for a standalone shader. Append one of the bodies in section 5 after the header. A complete file has one metadata wrapper, one header, helpers as needed, and one `PSMain`. A Template layer can use a body alone because the importer supplies the header when the complete header is absent. ```hlsl struct PSInput { float4 pos : SV_POSITION; float2 uv : TEXCOORD0; }; cbuffer FXConstants : register(b0) { float progress; float aspect_ratio; float2 resolution; float time; float in_progress; float out_progress; float clip_frame; float4 params0; float4 params1; float4 params2; float4 params3; }; Texture2D tex0 : register(t0); Texture2D tex1 : register(t1); SamplerState samLinear : register(s0); ``` - Keep the field names, order, types, and bindings. Place design settings in ordinary HLSL constants or use the documented controls. Target a pixel shader with entry point `float4 PSMain(PSInput input) : SV_TARGET`. - `uv` covers the frame from 0 to 1. X goes right and Y goes down. Multiply centered X by `aspect_ratio` when computing circles in image-height units. `resolution` gives the current pixel dimensions. - `time` is local time in seconds for a Graphic. `progress` is its normalized clip position and the blend phase for a Transition. Use normalized progress for animations that should stretch with clip duration. A Template's children each have their own local clock. - For Graphics, `params0` and `params1` are the primary and accent colors. `params2` holds the four Inspector sliders in order: Glow Intensity, Glitch Burst, Refraction, Speed / Rate. Effects and Transitions use their own parameter values. Build the first version with fixed design constants. A new uniform or comment will not create an Inspector control. - Output straight RGBA. A half-covered white pixel is `float4(1, 1, 1, 0.5)`. Outside transparent artwork, return zero alpha. Make opacity and coverage intentional, including soft edges and glows. - Use bounded loops and deterministic motion so seeking backward produces the same result at the same time. Use native text and PNG layers for editable labels and images. The shader receives the inputs bound by Studio and has no file-loading API. ## 5. Three starter shaders Assemble each example with the metadata and header above. Set `kind` to the example's type. Use a six-second duration for the Graphic and choose the actual transition duration at the cut. ### Graphic — Coral Orbit A transparent ring that travels horizontally, holds a clean edge, and fades near the ends of its clip. Place it above bright and dark footage and scrub to the middle. ```hlsl float4 PSMain(PSInput input) : SV_TARGET { float phase = saturate(progress); float2 p = input.uv - float2(0.5, 0.5); p.x *= aspect_ratio; p.x -= 0.22 * sin(6.2831853 * phase); float edge = abs(length(p) - 0.18) - 0.012; float aa = max(fwidth(edge), 0.001); float ring = 1.0 - smoothstep(-aa, aa, edge); float envelope = smoothstep(0.0, 0.15, phase) * (1.0 - smoothstep(0.83, 1.0, phase)); return float4(1.0, 0.42, 0.32, ring * envelope); } ``` ### Effect — Warm Highlights Select a video clip, compile as an Effect, then apply it to the clip. The source is `tex0`. The shader warms bright areas and preserves source alpha. Compare it against the untouched clip in the Program monitor. ```hlsl float4 PSMain(PSInput input) : SV_TARGET { float4 source = tex0.Sample(samLinear, input.uv); float luma = dot(source.rgb, float3(0.2126, 0.7152, 0.0722)); float amount = 0.22 * smoothstep(0.4, 0.9, luma); float3 warm = saturate(source.rgb * float3(1.10, 1.03, 0.92)); return float4(lerp(source.rgb, warm, amount), source.a); } ``` ### Transition — Soft Push Wipe Compile as a Transition and apply at the cut between two touching video clips. `tex0` is outgoing A and `tex1` is incoming B. The start returns A and the end returns B. The blend interpolates coverage and returns straight color. ```hlsl float4 PSMain(PSInput input) : SV_TARGET { float4 a = tex0.Sample(samLinear, input.uv); float4 b = tex1.Sample(samLinear, input.uv); float t = saturate(progress); if (t <= 0.0) return a; if (t >= 1.0) return b; float edge = lerp(-0.08, 1.08, t); float mixB = 1.0 - smoothstep(edge - 0.08, edge + 0.08, input.uv.x); float coverage = lerp(a.a, b.a, mixB); float3 weighted = lerp(a.rgb * a.a, b.rgb * b.a, mixB); return float4(weighted / max(coverage, 0.00001), coverage); } ``` ## 6. Make an editable Template Save the entire example below as `coral-title.kmotion`, or paste it into Studio. It includes both comments and a complete template shader body. Place it over footage. Double-click the compound to edit the text or choose a PNG for the logo, then use Back or Esc to return to the main timeline. ```hlsl /* KIRA_MOTION_V1 {"version":1,"kind":"Template","name":"Coral Title","duration_seconds":6.0} KIRA_MOTION_END */ /* KIRA_COMPOSITION_V1 { "version": 1, "name": "Coral Title", "duration_seconds": 6.0, "layers": [ {"name":"Accent","kind":"graphic","shader":"@self","start_seconds":0,"duration_seconds":6}, {"name":"Logo slot","kind":"image","png":null,"start_seconds":0,"duration_seconds":6, "transform":{"position":[0.32,0.17],"anchor_point":[0.5,0.5],"scale":0.12,"rotation":0,"opacity":1}}, {"name":"Title","kind":"text","text":"YOUR NEXT VIDEO","start_seconds":0,"duration_seconds":6, "style":{"font":"Inter","size":58,"bold":true,"fill":[255,247,239,255]}, "presentation":{"role":"Text","motion":{ "entrance":{"preset":"SlideUp","seconds":0.45,"intensity":1}, "exit":{"preset":"Fade","seconds":0.35,"intensity":1}}}} ] } KIRA_COMPOSITION_END */ float4 PSMain(PSInput input) : SV_TARGET { float entrance = smoothstep(0.0, 0.14, progress); float exit = 1.0 - smoothstep(0.82, 1.0, progress); float ruleMask = 1.0 - smoothstep(0.003, 0.006, abs(input.uv.y - 0.59)); float band = smoothstep(0.25, 0.27, input.uv.x) * (1.0 - smoothstep(0.73, 0.75, input.uv.x)); return float4(1.0, 0.42, 0.32, ruleMask * band * entrance * exit); } ``` - List layers back to front. Use unique names and keep every span inside the composition. Include a layer spanning the whole composition from time zero. `shader: "@self"` uses the outer shader. Additional graphics can carry complete shader strings. - Use `kind: "text"` with a text string. `style` supports `font`, `size`, `bold`, and `fill` as RGBA bytes. `presentation.role` can be `Text` or `Caption`. Useful motion presets include `Fade`, `SlideUp`, `Scale`, `Typewriter`, and `CinematicRise`. - An `image` layer with `png: null` is an empty slot. Choose or replace it in the Inspector. Use up to ten declared image slots. Include an actual PNG when a logo must ship with the design. Text and PNG layers remain editable when the template is opened. - Transform positions are normalized around the canvas center, with positive Y going up. The anchor uses source UV coordinates, with positive Y going down. `scale` is a positive number or a two-component array. Rotation is in degrees and opacity is 0–1. - Add an `animation` array to a layer for native motion. Each key contains `seconds` and a complete `transform`. Keys are local to the layer, strictly increasing, and linearly interpolated. Use multiple keys to describe an eased move. Inspect the fitted result at the final sequence aspect. Example keys for a logo that fades and slides up over 0.6 seconds: ```json [ {"seconds":0,"transform":{"position":[0.32,0.12],"anchor_point":[0.5,0.5],"scale":0.12,"rotation":0,"opacity":0}}, {"seconds":0.6,"transform":{"position":[0.32,0.17],"anchor_point":[0.5,0.5],"scale":0.12,"rotation":0,"opacity":1}} ] ``` ## 7. Animate video and titles in 3D 1. Put a background shot on the timeline and add a title, video layer, or compound above it. Start with a short shot so you can export it quickly. 2. Open **Scene + Program**. Select the layer and use **Spatial** or the scene tools to adjust position, depth, rotation, and scale. Scene lets you inspect the stage. Program shows the camera's composition. 3. Set the camera at the beginning. Open the timeline **Camera** lane and add a key with its diamond control. Move the playhead later, reposition the camera, and set the second key. Use the previous and next key buttons to check both endpoints. 4. Play from before the move. Look for clipped titles, camera intersections, and unintended overlap. Check the selected output aspect and export the short sequence. 5. Treat a closed compound as one layer for placement and effects. Open it to edit the individual layers, then return to Program to check the whole shot. A useful brief is “Design a six-second intro with a title in front, a video plate behind it, and a slow push that leaves the title readable for the last two seconds.” Ask the AI to give you a time sheet with the start, reveal, hold, and finish times. ## 8. Author an editable mesh scene with a connected AI Attaching this guide gives an assistant the authoring rules. Live editing requires a separately configured KIRA MCP connection with the scene tools available. Check the connected tool list first. Tool support and setup depend on the installed build and AI client. 1. Open a sample project. Ask the agent to call `kira_scene_capabilities` and inspect its example document and supported operations. Use those live schemas for this build. 2. Give a shot brief with duration, frame rate, aspect, materials, lighting, and camera path. Start with one mesh, a floor, a light, and a camera. Ask for stable IDs and named objects so you can revise them later. 3. A scene document contains the composition clock, nodes, and referenced resources. The current general scene workflow exposes Box, RoundedBox, Sphere, Cylinder, and Plane meshes, ImageCards, materials, and Directional, Point, or Spot lights. For image cards, use a PNG or JPEG you have supplied locally. Check the capabilities result for the available set. 4. Use `kira_scene_apply` to create and place the document. The common operations are `put_document` and `place`. Use a unique document and instance ID. For an existing scene, read `kira_scene_get` and include its current `expected_revision` before applying changes. Work in one deliberate batch so the edit has one undo entry. 5. Use `set_transform` for an object's placement and `set_tracks` for its animated properties. The track names include `position`, `rotation_degrees`, `scale`, and `opacity`. Key times are composition ticks. At 30 fps, two seconds is 60 ticks. Animate the camera's own `position`, `target`, `fov_degrees`, or `roll_degrees` parameters using the schema from the connected build. 6. Use `kira_capture_viewport` with a project tick to inspect real frames. Check the opening, movement, and final hold. Verify in Program, then save the editable `.kproject` and export through KIRA's normal Export dialog. This operation rotates the node `hero` from zero to 90 degrees over four seconds in a 30 fps composition. Apply it to a document that already contains that node. `set_tracks` replaces that node's animation tracks, so include any other tracks you want to retain. ```json { "op": "set_tracks", "node_id": "hero", "tracks": { "rotation_degrees": {"kf":[{"t":0,"v":[0,0,0],"e":"ease_in_out"},{"t":120,"v":[0,90,0]}]} } } ``` ### Copy this mesh scene prompt > Read the attached guide and use the connected KIRA scene tools if they are available. Build a six-second 1080 × 1920 product reveal at 30 fps with a matte rounded object, a neutral floor, warm key light, cool fill, and a slow camera push. Animate the object from a slight angle into a readable hero pose. Call scene capabilities first and use supported primitives and materials. Start in my sample project. Capture actual frames at the beginning, midpoint, and end. Report what you can see, then save the scene as an editable project. If the connection is unavailable, give me a shot plan and reviewable scene data using the documented fields. ## 9. Review before sharing | Check | What to look for | | --- | --- | | Compile | Compile the exact delivered source. Read the first diagnostic and keep the reported line number. | | Place | Use footage for Effects and two touching clips for Transitions. For Templates, open the compound and change the text. | | Scrub | Check the same frame twice in a different seek order. Inspect start, middle, and last visible frames. | | Alpha | Preview over bright and dark footage to catch black boxes, halos, and missing coverage. | | Layout | Check titles, logos, and the camera framing at the intended aspect. Check both if you deliver horizontal and vertical versions. | | Save and export | Save and reopen a sample project. Export a short section and compare it with the Program monitor at matching times. | When reporting a problem, include the KIRA build, asset type, expected result, what you saw, and the source or exact diagnostic. For a timing issue, add the sequence rate and the frame or time where it happens.