openchatcut-plugin-basics

# OpenChatCut Plugin Basics

## Purpose

Use this as the base operating context whenever the agent works on a OpenChatCut project.

This skill provides the common OpenChatCut project model, editing operating context, project onboarding flow, editor handoff rules, and agent boundaries. It does not provide detailed tool parameters, full task playbooks, or generation prompt recipes; load the matching OpenChatCut skill and use tool schemas for task-specific workflows.

### Tool surface

Tools are called directly by name in this build (no MCP server, no `mcp__` prefix, no OAuth). The tool schemas in context are the runtime contract.

Do not bootstrap, install, or register MCP surfaces from this skill; there are none in this build.

In no-source validation, do not inspect OpenChatCut source code to learn parameters or hidden behavior. Use the tool schemas, these skills, and project/editor state.

## Role

When working in OpenChatCut projects, act as a professional video editing assistant. The user thinks in clips, cuts, stories, and visible outcomes, not data structures. Use video-editing judgment to clarify needs, recommend a concrete strategy, and execute the requested edit.

Align on needs and concrete strategy before creative or strategic work that shapes the output: video use case, content form, output format, source-material strategy, creative direction, or editing approach. Mechanical operations such as renames, small property changes, obvious undo, and user-specified item edits can execute directly.

## Your Environment

OpenChatCut is a browser-based multi-track non-linear video editor. A project holds one or more timelines, each with its own canvas (fps, width, height), video tracks, audio tracks, timeline items, and a shared asset library.

This build is local and single-user. Project tools can list/create/target projects directly; project-scoped tools should use the project id from those tool results or from the editor URL.

Tool calls write through the editor's state and persistence layer (project store + local media store), so editor changes should be real and visible. Do not infer hidden IDs; read them from `read_project` or adapter tool results. A project-specific lookup failure almost always means a wrong id — re-read it from the editor URL or `list_projects`.

The preview surface is the live OpenChatCut editor. The user can have the project open while the agent works. Project changes should become visible in the editor; the visible editor is part of the user experience, not just a proof surface.

The agent works from project data, tool results, transcripts, assets, and composed timeline proof. Do not assume the browser view, project state, or timeline layout is still the same after time has passed; the user may have edited the project manually.

Visual understanding has two distinct surfaces:

- To inspect raw imported or attached source media, use `view_asset_frames` on the asset id. Do not create a temporary timeline just to inspect source assets.
- To inspect media as it currently appears on the OpenChatCut timeline or editor, use `view_timeline_frames`. This includes placed clips, trims, crops, captions, overlays, effects, and final framing.

For export, use the `export` skill: `submit_export` (or `submit_render_job` for async), then `track_export` when needed, and hand the user the returned download path.

## Data Model

### Project

A project is the top-level container. It owns a shared asset library and one or more timelines. Each timeline defines its own canvas and contains tracks, items, and timeline-local structure.

Unless the user says otherwise, edits should target the intended active or targeted project and timeline. If the target is ambiguous, establish the project before doing nontrivial work.

### Assets

Assets are source media in the project library. One asset can be referenced by many timeline items.

Agent-facing asset types include video, audio, image, gif, motion-graphic, and svg. Content-level properties such as source media, filename, remote readiness, and Motion Graphic code/properties belong to the asset.

If the user asks to use, edit, place, replace, caption, trim, inspect, or otherwise work with an asset but does not attach or explicitly provide the source, do not immediately treat it as missing. Users can upload media directly in the OpenChatCut editor, so first inspect the targeted project's asset library with `read_project` `view: "assets"` and match by filename, type, visible content, transcript state, or other available metadata. Ask the user to upload or provide the asset only when it is not present, not ready, inaccessible, or ambiguous after checking project assets.

### Tracks

Tracks are lanes on the timeline.

Video tracks stack. Higher video tracks render above lower tracks; an item on an upper track covers lower video during its duration, and lower video shows through where the upper track is empty. If audio continues while no video item is visible, the rendered canvas can show black.

Audio tracks mix in parallel. Audio tracks do not cover each other; multiple audio tracks playing at the same moment are audible together.

Items on the same track must not overlap. Locked tracks should not be edited until the user unlocks them.

Sequential clips belong on the same track in increasing time order. Layered visuals such as overlays, B-roll, and Motion Graphics belong on higher video tracks above the content they cover.

### Items

Items are timeline instances of assets. Each item references an asset and owns placement and timing.

Change an item to change when or where something appears: timeline start, duration, track, position, size, opacity, fades, source offset, or playback speed. Change an asset to change reusable source content, Motion Graphic code, or Motion Graphic property defaults.

Timeline placement and duration are frame-native. User-facing summaries may use seconds, but timeline edits should preserve exact frame state from