Montage

View saved version →

---
name: create-moment
description: Create an editable moment (clip) from an ingested video via the Montage MCP tools and deliver an editor link. Use after video ingestion when the user wants a clip/moment created from their video.
---

# Create a moment from an ingested video

End-to-end flow: read the ingestion outputs, pick clip boundaries, create the
moment, wait for clip preprocessing (downscale + speaker detection), and hand
the user an editor link. All tools are on the Montage MCP server.

## 1. Locate the project/video

- `list_projects` / `get_project` to find the project the user means.
- If the video was just uploaded with `upload_video`, poll
  `get_upload_status(workflow_id)` until `completed` — it returns the
  `project_id` and `file_id`. Ingestion must be complete before creating a
  moment (transcription and video validation results are required).
- Never pass a video URL to `create_moment` — it takes `project_id`/`file_id`
  and resolves the video itself. On paid plans ingestion repoints the project's
  video at the noise-removed copy, so the moment is cut from cleaned audio
  automatically. Creating a moment before ingestion finishes can catch the
  pre-correction video, which is a second reason to wait for `completed`.

## 2. Understand the content

Read all four ingestion outputs before picking anything — each answers a
different question, and a moment chosen from the transcript alone will cut
across bad footage.

- `get_video_validation(project_id)` — technical ground truth: `duration_seconds`
  (the hard upper bound for every segment), `width`/`height`/`fps`, codecs,
  `is_valid` + `failed_checks`/`error_summary`, and the probe rollups
  `speech_detection_info`, `audio_quality_info`, `person_detection_info`. Read
  it first: it tells you whether the footage even has usable speech, audio and
  people on camera.
- `get_transcript(project_id)` — what was said, with timestamps and
  `speaker_id`. Paginate for full text. This is where segment boundaries come
  from.
- `get_video_analysis(project_id)` — the vision-model read: scene breakdown,
  clip candidates with hook/payoff reasoning, `category_name`,
  `max_people_count`, reframe instructions. Treat its clip candidates as
  proposals to validate against the transcript, not as final boundaries.
- `get_video_corpus(project_id, view="rollup")` — on-screen reality: coverage
  fraction, subject roster with speaking/tracked seconds, hard-veto ranges,
  screen-text inventory. Only fall back to `view="full"` when the rollup is
  genuinely not enough — it returns the whole index and is large.
- `get_moments(project_id)` to see what already exists — don't duplicate.

Low `coverage_fraction` means those windows were never analyzed, not that
nothing happens there. Say so instead of reporting absence as a finding.

## 3. Pick segments

Choose one or more `[start, end]` second-pairs, and make every one of them
survive all four reads:

- Boundaries come from **transcript** timestamps — cut on sentence edges, not
  mid-word.
- The story beat comes from **video analysis** scenes/clip candidates — a
  moment should be one coherent beat (or a hook plus its payoff).
- **Corpus** hard-veto ranges are exclusions: do not cut inside them, and
  prefer windows where the speaking subject is also on camera.
- **Validation** bounds it: `0 <= start < end <= duration_seconds`, and if
  `is_valid` is false or speech/person detection is empty, say so before
  creating anything.

Multiple pairs compose one moment. Write a short `title` (and optionally a
`summary`) describing the moment.

## 4. Create the moment

```
create_moment(project_id, title, segments, utterances, summary?, kind?, file_id?)
```

- `utterances` (required for speaker detection): the transcript segments from
  step 2 that overlap the chosen `segments`, as
  `[{"start": <sec>, "end": <sec>, "text": "...", "speaker": "<speaker_id>"}, ...]`
  — map `get_transcript` fields `start_time`→`start`, `end_time`→`end`,
  `speaker_id`→`speaker`, using absolute video seconds
  (`timestamp_format="seconds"`). Cover every chosen segment window; without
  utterances, speaker detection is skipped.
- `kind`: content (default), hook_montage, ad, or sponsor_read.
- `file_id` only when the project has multiple files.
- Requires the `moments:write` scope.

The response contains `moment.id`, `preprocessing.{status, workflow_id}`, and
`editor_url`.

## 5. Wait for preprocessing

- If `preprocessing.status` is `"processing"`: poll
  `get_workflow_status(preprocessing.workflow_id)` every ~30s until `status`
  is `completed` (typically 2–10 minutes). On `failed`/`timed_out`, report it
  — the moment still exists, but the editor may lack the downscaled preview.
- `"ready"` means enrichment already exists; `"skipped"` means preprocessing
  could not run (`preprocessing.reason`: `no_video_url` / `no_input_codec` /
  `no_utterances`) — nothing to poll, tell the user why.

## 6. Deliver

Give the user the `editor_url` from the create_moment response verbatim:

```
https://studio.montage.app/project/{project_id}?view=clipEditing&clipId={moment_id}
```

(`clipId` is the moment id.)

View saved version →

---
name: ingest-video
description: Use when the user wants to ingest, upload, or import a video into Montage from a Google Drive or public URL, or asks to track/poll an upload_video ingestion workflow through its pipeline steps.
---

# Ingest Video from URL

Ingest a video into Montage from a Google Drive (or any public) URL using the
Montage MCP tools and watch it through every pipeline step.

Argument: the video URL. If none was given, ask for one before doing anything.

Requires the Montage MCP server to be connected with the `upload_video` /
`get_upload_status` tools available (shipped in PR #1298). If the tools are
missing, say so and stop.

## Step 1: Start the ingestion

- Google Drive links must be shared as "Anyone with the link". If the URL is a
  gdrive link, remind the user of this BEFORE starting (a private file fails
  minutes in, during download).
- Call `upload_video(video_url=<url>)`. Optionally pass `project_name` if the
  user provided one. Record the returned `workflow_id`.
- Do NOT ask whether the video has background noise. Noise removal runs
  automatically on paid plans and is unavailable on free ones, so the answer
  changes nothing — and faint noise is inaudible to the user anyway. Pass
  `remove_background_noise=false` only if the user volunteers that the audio
  must be left untouched (music bed, ASMR, layered sound design).

## Step 2: Poll until done

Call `get_upload_status(workflow_id)` in a loop, sleeping between calls
(`sleep 30` via Bash; downloading and analyzing are the long steps — do not
poll faster than every 15s).

- Report each **step transition** to the user as it happens, with a plain
  reading of the step: `creating_records` → `validating_url` → `downloading` →
  `validating_video` → `analyzing` (watch `child_workflow_status` for
  understanding / corpus / transcription / thumbnail individually; `thumbnail`
  may be absent on older deployments) → `finalizing`.
- `child_workflow_status.audio_correction` appears only on paid plans: it reads
  `completed`, `skipped` (silent video) or `failed`. A failure is not fatal —
  processing continues on the original audio.
- Surface `project_id` / `file_id` as soon as they appear.
- Stop polling when `status` is anything other than `running`.

**Failure handling:**
- `result.success == false` or `status == failed`: report the `message`/
  `error` verbatim. Common causes: gdrive file not public ("Anyone with the
  link"), gdrive rate limit, non-video URL. The project is marked `failed` —
  tell the user they can rerun this command after fixing the share settings.
- A single failed analysis child (see `child_workflow_errors`) is not fatal to
  the others — say which succeeded and which failed. A failed `thumbnail` is
  cosmetic only: it never fails the project or blocks billing.

## Step 3: Verify and summarize

On success:
- `get_project(project_id)` to confirm the project exists and show its name.
- `get_transcript(project_id)` for the transcript.
- `get_video_validation(project_id)` for duration, resolution, fps, codecs and
  whether the footage has usable speech/audio/people.
- `get_video_analysis(project_id)` and `get_video_corpus(project_id,
  view="rollup")` when the user wants the visual read too — these are the same
  outputs the create-moment skill needs.
- Summarize for the user: project name/id, video size, duration if available,
  language, and a 2-3 sentence gist of the content from the transcript.