EtchMotion Studio 1.2 · product reference

Agent reference

Use this as the source of truth for the revision-safe local automation surface included with EtchMotion Studio 1.2.

Open machine-readable JSONConnection guide

Connection contract

Local, discovered, short-lived.

The bridge finds EtchMotion's runtime discovery file, validates a 127.0.0.1 origin and sends the rotating x-etchmotion-token header. Never expose or persist the token. The desktop app must remain open.

Transportstdio MCP to loopback HTTP
Write boundaryExact desktop approval
Publish toolsNone

Required workflow

Review first. Prove the look. Then scale.

  1. Call status, catalog and Channel Styles.
  2. Search or batch-preview new external subjects.
  3. Show identity, creator, licence, source page and warnings.
  4. Render one or two proofs for a new recipe.
  5. Request visible approval for the exact write body and idempotency key.
  6. For Long-form, read the revision before every focused edit.
  7. Poll jobs and report concrete project IDs or failures.

MCP tools

Twenty-nine small, inspectable actions.

etchmotion_statusRead

Runtime, queue and library counts

etchmotion_catalogRead

Current engines, recipes, templates and music

etchmotion_projectsRead

Completed projects, masters and exports

etchmotion_compositionsRead

Longer multi-scene productions

etchmotion_longform_getRead

One Long-form document and its current revision

etchmotion_artifact_getRead

Path-free artifact identity, revision, size and SHA-256

etchmotion_proof_comparePreview

Byte identity or a required visual-review checklist

etchmotion_channel_stylesRead

Latest immutable styles and version history

etchmotion_jobsRead

Persistent queue and recovery state

etchmotion_story_formatsRead

Built-in journeys, layouts and safe custom limits

etchmotion_approvalsRead

Sanitized exact-write receipts and decision state

etchmotion_request_approvalWrite

Create a visible proposal; cannot approve itself

etchmotion_longform_validatePreview

Normalize and preflight a Long-form draft

etchmotion_longform_create_draftWrite

Create a new non-overwriting Long-form draft

etchmotion_longform_add_sceneWrite

Add one reviewed scene at the current revision

etchmotion_longform_patch_sceneWrite

Patch bounded fields without replacing id, type or media

etchmotion_longform_move_sceneWrite

Move one scene to an exact timeline index

etchmotion_longform_remove_sceneWrite

Remove one scene without deleting source assets

etchmotion_longform_save_revisionWrite

Save a reviewed complete document at its current revision

etchmotion_validate_story_formatPreview

Validate a portable custom Story Plan

etchmotion_save_channel_styleWrite

Save a new immutable style version

etchmotion_plan_channelWrite

Build a reviewed plan and upload-ready CSV

etchmotion_searchPreview

Reusable source candidates

etchmotion_batch_previewPreview

Reviewed candidates for newline subjects

etchmotion_createWrite

One reviewed local project

etchmotion_batch_createWrite

Up to 24 reviewed local projects

etchmotion_composeWrite

Queue a reviewed hybrid document or legacy composition

etchmotion_cancel_jobWrite

Cancel one queue step without deleting files

etchmotion_retry_jobWrite

Retry a recoverable queue step

Generator contract

Six engines with explicit presets.

engraving

Portraits, objects and full scenes drawn with ordered marks

photoreal, atelier, classic

color-regions

A pencilled colouring page followed by a paced colour reveal

atelier-premium-v2, storybook, poster, stained-glass

restoration

Disclosed creative restoration sequence

museum-conservation, family-album, colour-memory

mosaic

Material pieces assembled around important detail

artisan-ceramic, ceramic, paper-cut, pixel-luxe

painted-canvas

Progressive painting, including a hard-surface product route

product-gouache, oil-linen, gouache-board, watercolour-coldpress

story-plate

Structured explanation with semantic callouts and optional local narration

editorial-ink, field-guide, darkboard

Restoration is a creative simulation, not forensic recovery. Story Plate works best with a structured brief and verified callout facts. Engraving Atelier is portrait-only.

Shared settings

Keep important choices explicit.

Presentation

auto, framed, editorial, sketchbook, blueprint, product-stage

Format

vertical, portrait, square, landscape

Subject mode

auto, portrait, full-scene, isolated-object

Detail

standard, dense, ultra

Visible tool

physical, classic

Colour page opening

draw-first or ready-page

Duration

18 to 90 seconds for one render

creation settingsJSON
{
  "generatorMode": "engraving",
  "generatorPreset": "photoreal",
  "detail": "dense",
  "hook": "Can you name this computing pioneer?",
  "brand": "Gallery of Faces",
  "theme": "gallery-gold",
  "subjectMode": "portrait",
  "presentation": "framed",
  "toolStyle": "physical",
  "coloringPageMotion": "ready-page",
  "drawSeconds": 35,
  "outputFormat": "vertical",
  "musicAsset": "quiet-archive",
  "musicVolume": 0.18,
  "pencilSound": true,
  "pencilVolume": 0.55,
  "voiceVolume": 0.9
}

A custom opening question belongs in hook. It must be present when the project is created and again when the video is rendered from saved project settings.

Payload pattern

Pass reviewed data, not a vague prompt.

Batch preview lines

Ada Lovelace | Can you name this computing pioneer?
Monarch butterfly | Why does this traveller cross a continent?

One project

{
  "request": {
    "name": "Ada Lovelace",
    "imageUrl": "REVIEWED_ORIGINAL_URL",
    "source": { "title": "KEEP_FULL_SOURCE_RECORD" },
    "settings": {
      "generatorMode": "engraving",
      "generatorPreset": "photoreal",
      "hook": "Can you name this computing pioneer?",
      "autoRender": true
    },
    "draft": true
  }
}

One revision-safe scene edit

{
  "id": "episode-123",
  "expectedRevision": "current-revision",
  "sceneId": "title-scene-01",
  "patch": {
    "text": { "title": "A clearer opening" },
    "transition": { "type": "cut", "duration": 0 }
  },
  "idempotencyKey": "episode-title-001",
  "approvalId": "the exact receipt approved in Studio"
}

Rights and safety

What an agent must not assume.

  • A search result is a candidate, not legal clearance.
  • Check licence, attribution, identity, likeness, privacy, publicity and trademarks for the planned use.
  • Do not imply historical authenticity for a simulated restoration.
  • Every local write needs a unique idempotency key and an exact receipt approved visibly in Studio.
  • Long-form scene patches cannot replace scene identity, type or reviewed media; agents cannot import arbitrary local paths.
  • Do not publish or delete. Those actions are intentionally outside the API.