| name | edit-timeline-studio |
| description | Analyze images, video, speech, motion, products, and websites; route local vision, audio, depth, tracking, matting, identity, and restoration models; auto-edit, replicate, enhance, caption, voice, assemble, validate, and export editable Timeline Studio projects and videos. Use for reference-video remakes, filter and repeated-shot reconstruction, subject-aware reframing, clip splitting, source-time speed curves, Color Wheels grading, ramps and holds, person or product cutout, person or object outline, authorized face swap, shot and timing reconstruction, supplied or web-sourced footage, AI video platform selection, cleanup, highlights, product promotion, website walkthroughs, image-to-video assisted edits, optical-flow editing, depth/2.5D/transition finishing, AI voiceover, subtitles, short-form production, .timeline automation, or editor evaluation. |
AI Video Editing with Timeline Studio
Turn the user's exact editorial request and media into reversible Timeline Studio edits. Keep the editable timeline as the source of truth; never replace it with an opaque one-shot render.
Choose the execution path
- On first local use after installation, read references/host-environment.md. If Node.js is unavailable, start with the zero-dependency Shell or PowerShell bootstrap; otherwise run
node scripts/setup-host.mjs --check. Agent-driven Chinese and mixed Chinese/English voiceover uses Timeline Studio's owned browser-local Hojo TTS Light 80M two-voice bundle and does not require a separate Python voiceover capability. If language runtimes or dependencies are missing, show the exact installation plan and obtain explicit user approval before install mode; never treat Skill installation as permission to modify the host or download models.
- Treat local project-file processing as the default for deterministic editing: inspect media locally, modify the portable
.timeline through the command layer or local archive services, render locally, and verify decoded output locally. Do not open a browser merely because the editor has a UI.
- Treat
https://video-editor.ai-creator.top/ as the canonical hosted editor only when the user explicitly asks to use the website, provides no local repository or project path, or requires a hosted-only capability.
- When this repository is available, prefer its Agent command layer and local media tools. Start the local server and browser only for a verified UI-only operation that the local project pipeline cannot express and the user has not required a local-only workflow. Read the actual server URL from process output; never assume port 5173.
- Prefer the bundled Timeline Studio MCP tools when the host exposes them. Read references/mcp-integration.md, inspect the project, and always call
timeline_project_diff before timeline_project_apply with the same revision and operations. The MCP server is a transport over the repository command runner, not a separate editing implementation.
- When MCP is unavailable, inspect
package.json for an Agent command script. Do not use npm run ... --if-present as capability detection because it can succeed silently. If the command runner exists, read references/command-contract.md, inspect the project, build a versioned plan, run the structural validator, and use project.diff as the authoritative semantic dry run before project.run.
- If a required operation is missing from the local contract, state the exact gap. For repository-development work, implement the smallest shared local operation and renderer support before falling back to UI. Otherwise ask before switching to the browser workflow.
- Do not claim deterministic or idempotent execution when only UI automation was available. State the limitation and preserve an editable project archive when the UI supports it.
Workflow
1. Inspect before editing
- Preserve the user's prompt verbatim as the creative brief.
- Resolve every referenced asset to an explicit path or URL. Never sweep a directory without approval.
- Inspect duration, dimensions, audio presence, and media type.
- Read the current project summary before changing an existing project.
- Ask only when an unresolved choice materially changes the edit, such as the desired output duration or aspect ratio.
- For an automatic-editing request, read references/auto-edit-workflow.md. Inspect first, classify the content, goal, and delivery with an explicit confidence level, then ask only the minimum category-specific questions that can change the cut. Never ask for facts discoverable from the media.
- For a request to reproduce, imitate, recreate, or reverse-engineer a reference video, read references/replication-workflow.md. Classify it as
editing-style replication, AI-generation replication, or a hybrid; reconstruct filters, repetitions, source splits, speed curves, transitions, shots, and timing before building; and explicitly resolve whether the authorized original audio track must be retained. Do not start editing until the replication analysis-completeness gate passes. Use current web search to compare AI video platforms only when generation is required, and use lawful web-sourced footage only when the user has not supplied adequate material.
- Before loading or downloading a model for media analysis, read references/local-model-routing.md. Inventory the repository's existing local and pinned mirrored capabilities, choose the minimum model chain needed for the evidence gap, run inference locally without driving the visible editor UI, and record exact model/runtime/fallback provenance. Never load every available model by default or create a duplicate cache.
- When the user needs web-sourced footage or asks where downloadable material can be found, read references/web-footage-sourcing.md. Give current, task-specific platform suggestions from live search and rank them by source legitimacy, explicit download support, usage rights, visual fit, quality, and provenance. Keep the skill provider-neutral; never hard-code one platform or brand as the permanent route.
- For every completed automatic edit, read references/professional-editing-workflow.md. Analyze images directly; analyze video with representative frames, speech/OCR, semantics, and global plus subject-region optical flow. Stabilize before tracking or enhancement. Ask about image-to-video or image-to-image models only after inspection proves that generation is materially useful.
2. Plan at the supported fidelity
- For an automatic edit, preserve the prompt and normalize inferred, confirmed, defaulted, and unresolved decisions into an editable brief. Build a source-time decision record with keep/remove/shorten/reorder decisions, reasons, confidence, caption expectations, audio-continuity constraints, and protected content before changing the timeline.
- For explanatory product, tutorial, or website beats, choose an explicit attention treatment for the single named target: magnify small or dense evidence, underline exact text or numbers, or frame the exact boundary of a control, card, or result. Use at most one supporting treatment with a camera move, and apply the underline or frame only after the camera has stopped.
- For subject-led shots, choose the smallest justified treatment: use cutout to change context or layer depth, outline to focus attention without removing context, and face swap only when identity replacement is explicitly requested and authorized. Apply a speed curve to a meaningful action phase or editorial beat, not as continuous decoration. Preserve the analyzed source-time mapping when retiming.
- With the command runner, express edits as declarative operations with stable IDs, seconds, revisions, operation IDs, and preconditions. Run
scripts/validate_edit_plan.mjs <plan.json> for transport-shape errors, then run npm run agent -- project.diff <plan.json> to reject unsupported operations and invalid project-specific edits before applying anything.
- With browser UI only, write a short ordered checklist of visible user intents and expected UI outcomes. Prefer named controls and clip labels; use coordinates only as a last-resort fallback grounded in a current screenshot.
- Keep main Visuals contiguous. Treat captions, stickers, source audio, voiceover, music, and overlays as timed clips.
- Apply a one-way caption-to-speech rule: if the project configures or enables any caption, every visible caption must correspond to audible speech. Link transcription captions to the existing spoken source clip, and generate a voiceover for every new narration, explanatory, promotional, or text-led caption. Existing source speech satisfies this rule and must not receive a duplicate voiceover. When captions are absent, narration is still the default for
tutorial-demo, vlog-event, marketing-commerce, and narrative-documentary; it remains optional for other categories unless the brief requires it. If a configured caption has no authorized speech route, omit it or stop with the editable project preserved.
- For narrated edits, synthesize each short breath group into its own physical archived audio file from the outset and bind each caption to exactly one matching
audioClipId; do not generate one monolithic narration file and split it after synthesis. Split at sentence-ending punctuation and, by default, at commas, semicolons, colons, em dashes, or another clear spoken pause. Keep a boundary joined only when splitting would create a meaningless fragment or break a proper name, number, URL, or intended bilingual phrase. For free-script generation, keep the first clip at the explicit playhead, append every later clip after the current voiceover-track end, and never reuse an unchanged playhead or ; caption-scoped generation stays anchored to its caption. Place adjacent narration clips with the shared desktop/H5 default gap, then derive caption timing and picture timing from the accepted audio sequence.
3. Apply safely
- Save a project version or export a
.timeline archive before a destructive batch.
- Apply one transaction per user-visible intent. Fail the whole transaction when a precondition fails.
- Never silently substitute missing media, voices, models, fonts, or effects.
- Keep every result undoable and editable in the normal UI.
- Do not start a paid or remote generation job without a clear user request.
- Do not put
output.render in a command plan or claim that project.run renders video. Use the separate versioned project.render request for its documented portable subset, and use the browser editor for AI generation or unsupported composition features.
- For a completed video-editing request, resolve an explicit absolute output directory and create both a portable
.timeline project and the rendered result video there. Planning, diagnosis, and an explicit editor-only handoff are the only exemptions. Do not report completion with only one artifact.
4. Verify the result
- Re-read the timeline summary and compare it with the requested ordering, track placement, and enabled states. For narrated edits, confirm the final project duration follows the locked audio spine rather than an earlier runtime estimate.
- Preview the opening, every cut or transition, caption boundaries, overlays, and the final frame.
- Play the timeline continuously across every visual, caption, and audio boundary. The timeline clock must advance monotonically; reject any boundary that stalls, jumps backward, repeats a clip tail, or activates both adjacent half-open clips at once.
- Check audible behavior, not just visible tracks. Distinguish embedded video audio from explicitly separated source-audio clips and verify mute/link state.
- When placing stereo or multichannel audio with FFmpeg, apply every intended offset to every channel explicitly. For
adelay, use adelay=<milliseconds>:all=1 or provide one delay value per channel; a single value with the default all=false delays only the first channel and can pile every later clip into the other channel at time zero. Before delivery, compare left/right activity in the opening window and around every scheduled speech boundary. Reject channel-only early speech, multiple narration clips stacked at the opening, or undocumented interchannel onset skew.
- Verify every visible caption resolves to one audible speech clip for its complete active interval. Reject orphan captions, silent linked clips, captions extending beyond speech, duplicate source-speech plus voiceover, or text-only caption delivery.
- Verify adjacent Agent-generated narration clips are separate physical assets, use short phrase-level breath groups with commas treated as valid default split points, and retain the shared desktop/H5
0.4s of intentional timeline space. Inspect the isolated speech bus at the opening and reject repeated free-script generations that share 0s, reuse an unchanged playhead, or overlap before their scheduled starts. Also reject overlong multi-clause synthesis, a monolithic narration that was merely cut into ranges, meaningless micro-fragments, accidental overlaps, clipped breath/release tails, or picture timing that forced the accepted speech out of its natural cadence.
- Listen to the complete narration at normal playback speed. Reject cold or mechanical timbre, flat pitch and energy, synthetic word-by-word delivery, rigidly equal pauses, rushed cadence, clipped pauses, unnatural pronunciation, segment-level speed changes, unexplained loudness jumps, or narration that was globally accelerated merely to hit a target duration. Require a warm, human, storyteller-like result with restrained pitch variation, phrase-level emphasis, and natural breath space unless the user explicitly requests another character. For phrase-scoped narration, measure every final stem after all processing; by default target integrated and no higher than , require the loudest-to-quietest segment spread to stay within , and keep segment LRA within unless an intentional exception is documented. Never accept a narration mix from full-program loudness alone, and do not rely on one-pass normalization of short clips as proof of consistency.
Interpret underspecified requests conservatively
- For “try it,” “open it,” or “let me edit” requests without an editorial brief, start the editor, import only the explicitly named assets, verify automatic placement, and hand off the live editable workspace.
- Do not invent trims, captions, aspect-ratio changes, AI generation, or exports.
- Treat an explicit request to “automatically edit,” “clean up,” “condense,” “make highlights,” or equivalent wording as permission to make reversible editorial decisions within the confirmed brief. State consequential defaults, protect category-specific content, and report the decisions; do not treat that request as a mere handoff.
- Treat persistent onboarding completion, model downloads, remote generation, and destructive reset as separate user decisions.
Learn from every real run
For editor evaluation, regression work, or any run that exposes friction, read references/e2e-evaluation.md. For automatic-editing evaluation, also read references/auto-edit-scenarios.md and use its fixed category cards, clarification checks, hard gates, and adjacent stress variants. Capture the attempted action, observed result, evidence, fallback, and verification. Classify the finding as product, browser-control, environment, or skill guidance. Update the smallest relevant skill instruction or reference, validate the skill, reinstall the local copy, and rerun the affected scenario plus adjacent smoke tests. Never weaken an assertion merely to make a test pass.
Capability boundaries
Read references/host-environment.md for host dependency checks and approved installation, and references/voiceover-workflow.md before Agent-driven narration or pre-voiceover generation.
Read references/current-capabilities.md when deciding whether a request can be executed now. Read references/mcp-integration.md when connecting or invoking the bundled MCP server, and references/command-contract.md when implementing or invoking the underlying Agent command layer. Read references/local-model-routing.md before model-assisted analysis or enhancement. Read references/remote-video-generation.md before selecting or calling a remote video generator, digital-human service, or programmable composition service. Read references/web-footage-sourcing.md for provider-neutral, current web and short-video footage suggestions. Read references/browser-workflow.md for UI execution, references/auto-edit-workflow.md for category-aware automatic editing, references/promotion-narrative-workflow.md for evidence-backed product and promotional storytelling with closed-loop cases, references/replication-workflow.md for editing-style and AI-generation remakes, references/highlight-tension-workflow.md for peak hierarchy and tension shaping, references/curves-and-subject-effects.md for speed curves, Color Wheels, cutout, outline, and authorized face-swap shot design, references/professional-editing-workflow.md for shared media analysis, generation negotiation, stabilization, enhancement, and artifact delivery, for its repeatable category matrix, and for repeated experience-driven testing.
For public explanations, route one question to one page: use docs/agent-video-editing.md for what Timeline Studio is; the platform guide for Codex, Claude Code, GitHub Copilot, or Gemini CLI for discovery and invocation; docs/examples.md for reproducible cases; docs/command-reference.md for exact runner syntax; and docs/comparison.md for FFmpeg, CapCut, and Remotion comparisons. Do not load all public pages unless the user asks for a broad overview.
If a requested operation is unsupported, keep the valid partial timeline unchanged and state the exact missing command or runtime capability.
