humeo-core/docs/MCP_USAGE.md

Using humeo-core from an MCP client

The installed console command is humeo-core. For backward compatibility, humeo-mcp is also registered (same entrypoint); either works in "command": ... if both are on PATH from the same install.

1. Add to your client

claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "humeo": {
      "command": "humeo-core"
    }
  }
}

2. A typical agent plan

→ humeo.list_layouts()
    # discover the 5 layouts (max 2 on-screen items per short)

→ humeo.ingest(source_path="/abs/long.mp4", work_dir="/abs/work", with_transcript=true)
    # IngestResult: scenes[], keyframes, transcript_words[]

→ humeo.classify_scenes(scenes=<IngestResult.scenes>)
    # SceneClassification[] — one layout per scene

→ humeo.select_clips(
      source_path=..., transcript_words=..., duration_sec=...,
      target_count=5, min_sec=30, max_sec=60
  )
    # ClipPlan — top non-overlapping clips

# For each clip, pick the layout of the scene its midpoint falls in,
# build a LayoutInstruction, and:

→ humeo.build_render_cmd(request={...})
    # dry-run: returns the exact ffmpeg argv, no execution

→ humeo.render_clip(request={..., "mode": "normal"})
    # actually renders the 9:16 MP4

3. Strict JSON all the way

Every request/response is validated against the schemas in schemas.py. Invalid input is rejected before ffmpeg is touched, so a confused agent can't accidentally rm-rf your disk or burn GPU hours.

4. Override knobs

LayoutInstruction accepts:

• zoom, person_x_norm, chart_x_norm — single-subject knobs.
• split_chart_region, split_person_region, split_second_chart_region, split_second_person_region — normalized bboxes that drive split-layout cropping.
• top_band_ratio — fraction of output height used by the top band (default 0.5 = even 50/50, the symmetric look).
• focus_stack_order — for split_chart_person, chart-on-top vs person-on-top.

Example: chart + person with a precise bbox crop and an even split.

{
  "clip_id": "001",
  "layout": "split_chart_person",
  "split_chart_region":  {"x1": 0.00, "y1": 0.10, "x2": 0.52, "y2": 0.95},
  "split_person_region": {"x1": 0.55, "y1": 0.05, "x2": 1.00, "y2": 1.00},
  "top_band_ratio": 0.5,
  "focus_stack_order": "chart_then_person"
}

Example: two-speaker interview.

{
  "clip_id": "002",
  "layout": "split_two_persons",
  "split_person_region":        {"x1": 0.02, "y1": 0.05, "x2": 0.48, "y2": 0.95},
  "split_second_person_region": {"x1": 0.52, "y1": 0.05, "x2": 0.98, "y2": 0.95}
}

5. When to stay in dry-run

• You want to show an approval UI before spending CPU.
• You want to diff the planned ffmpeg commands against a previous run.
• You're building tests.

mode="dry_run" is always safe, never writes output, and returns the exact argv list.