# OttoCut

> OttoCut extracts clips from video and audio by the start and end words spoken in them. It resolves
> those phrases against a transcript and cuts the media. The HTTP API is the primary interface; a
> browser UI, a CLI and an MCP server are layers on it.

Status: pre-launch. The clipping pipeline works. Accounts, API keys and billing ship with v1, so
public API access is not open yet.

## How clipping works

- A clip is defined by two markers, `start` and `end`.
- A marker is either a phrase (`{"type":"phrase","value":"the results are in"}`) or a timestamp in
  seconds (`{"type":"timestamp","value":"30.5"}`).
- Phrase matching is case-insensitive and punctuation-tolerant.
- When a phrase repeats, `occurrence_index` selects which one; `near_timestamp` instead selects the
  occurrence closest to a given time and overrides `occurrence_index`.
- `start` must resolve earlier than `end`, or the request is rejected.
- Identical requests return the cached clip. Transcripts are cached per source video.
- Download URLs are signed and valid for one hour; request the clip again for a fresh URL.

## Endpoints

- POST /media/upload-url — create a media record, get a signed upload URL
- POST /media/{media_id}/finalize — confirm the upload, start processing (idempotent)
- POST /media — ingest from a source URL
- GET /media/{media_id} — poll status; returns the transcript word list when ready
- POST /clips — create a clip from start and end markers
- GET /clips/{clip_id} — fetch a clip and refresh its download URL

Every response uses the envelope `{"data": ..., "error": ..., "meta": {"request_id": ...}}`.

## Docs

- Quickstart: https://ottocut.com/docs/quickstart/
- Clipping reference: https://ottocut.com/docs/clipping/
- API reference: https://ottocut.com/docs/api/
- Agent integration: https://ottocut.com/for-agents/