Files

T

Martin Delophyandhaixin.yang 11ddf231e0 Publish Timeline Studio agent editing skill (#42 )

* publish timeline agent editing skill

* install ffmpeg in CI

---------

Co-authored-by: haixin.yang <haixin.yang@weimob.com>

2026-07-22 18:47:40 +08:00

3.2 KiB

Raw Permalink Blame History

Agent command contract

Use JSON as a transport-neutral plan. The CLI and a future MCP server should call the same application service.

Plan envelope

{
  "schemaVersion": 1,
  "project": "/absolute/path/project.timeline",
  "baseRevision": 12,
  "dryRun": false,
  "operations": [
    {
      "id": "op-001",
      "type": "visual.trim",
      "clipId": "visual-123",
      "sourceIn": 1.2,
      "sourceOut": 8.4
    }
  ],
  "output": {
    "project": "/absolute/path/project-edited.timeline"
  }
}

All times are finite seconds. IDs are stable across reads and writes. A repeated operation ID must return its prior result without applying twice.

The standalone validate_edit_plan.mjs checks transport shape only. project.diff is the authoritative project-aware validation step: it uses the same registry and reducers as project.run, rejects unsupported operations, checks revision and clip/track preconditions, and never writes an archive.

Minimum read commands

project.inspect: format version, revision, duration, ratio, tracks, media inventory, warnings
track.inspect: ordered or timed clip summaries for one track
clip.inspect: source mapping, timing, transforms, effects, links, analysis records
transcript.inspect: timestamped words/segments and speakers
project.diff: predicted state changes, duration changes, and validation warnings

Implemented write operations

asset.import
visual.append, visual.insert, visual.trim, visual.split, visual.reorder
overlay.add, timed.move, timed.resize
clip.delete, clip.set_property, clip.set_speed, clip.set_muted
caption.add, caption.update, caption.link_audio, caption.unlink_audio
transition.set, track.set_visibility, track.set_locked
project.set_ratio

Use ../docs/command-reference.md for required fields and current media-import limits. Do not invent operation types not listed there.

Planned operations

caption.generate
audio.separate, voice.generate, music.add
multi-file Voiceover media storage
richer project.render coverage, structured progress events, and cancellation reporting

project.render is implemented as a separate versioned request rather than a write operation inside project.run. Its first deterministic local path renders the portable Visuals, Voiceover, and Music subset to H.264/AAC MP4 and rejects unsupported composition features. Until richer rendering and generation enter the shared services, use the browser workflow for captions, stickers, overlays, effects, ASR/TTS, and other AI generation.

Result envelope

{
  "ok": true,
  "revision": 13,
  "appliedOperationIds": ["op-001"],
  "warnings": [],
  "artifacts": {
    "project": "/absolute/path/project-edited.timeline"
  }
}

On failure, return ok: false, a stable error code, a human-readable message, the failing operationId, and no partial state unless the operation explicitly permits partial output.

Architectural rule

Do not implement CLI and MCP editing separately. Both must call a single command registry backed by pure project-state reducers and shared validation. The React UI should eventually dispatch those same commands so manual and Agent edits cannot diverge.

3.2 KiB Raw Permalink Blame History