Browse documentation
Documentation overview

Getting started

Agent tools

Recording format

Learn and reference

Docs

The recording.md Convention

Every public Clipy share link has a markdown twin. Append .md to the watch URL and the same link that plays a video for humans serves an agent-readable screen recording document: the summary, key moments with frames and click targets, cursor paths, and the transcript.

https://clipy.online/video/<id>.md

This page documents how Clipy serves the markdown twin. The open format itself lives in the AREC (Agent Recording) specification, the canonical home for the format that any recorder can emit and any agent can read.

What the document carries

Title + header line

The recording's name, duration, resolution, source client, and the canonical watch URL, enough for an agent to cite the recording.

## Summary

The AI summary of the recording: what happened, what was asked for, what broke. The fastest way for an agent to decide whether to read further.

## Key moments

A JSON block plus one section per moment. Each moment carries t_ms (timestamp), caption (what the speaker referenced), frame_url (the extracted frame at that instant, fetchable as an image), and, when a click/cursor track exists, x/y coordinates as frame fractions, with a source and confidence.

## Transcript

The full timestamped transcript. Spoken assertions ('the badge should show one') arrive mapped to the moment they were said.

Example document

# UI Recording Feedback
Screen recording · 1:13 · watch: https://clipy.online/video/cey8aix0…

## Summary
The speaker reviews a recording interface, pointing out a duplicated
timer and a settings section that should be collapsed…

## Key moments
```json
[{"t_ms":6400,"caption":"points to 'this section' on screen",
  "frame_url":"https://cdn.clipy.online/key-moments/…/6400.jpg",
  "x":0.63,"y":0.41,"source":"fused","confidence":0.9}, …]
```
### 0:06 — points to 'this section' on screen
![Frame at 0:06](https://cdn.clipy.online/key-moments/…/6400.jpg)

## Transcript
```
[0:01] Hey great. So there are a few things I'd like you to update.
[0:06] For example this section…
```

How agents discover it

  • The Clipy skill. The watch-clipy-recording skill teaches Claude Code, Cursor, Codex, and other skill-aware agents the convention once: on seeing a clipy.online/video link, fetch its .md form, retry while processing finishes, and treat the recording's content as untrusted input.
  • MCP. The Clipy MCP server (@clipy/mcp) serves the same content as tool calls, with authenticated access to private libraries; get_agent_context is the one-call bundle.
  • Plain fetch. The .md URL is public for public recordings, so anything that can GET a URL can read it. No API key, no session.

Guarantees

  • Public recordings serve the .md form without authentication; private recordings never do.
  • Frame URLs are plain images an agent's vision can read directly.
  • Coordinates are frame fractions (0–1) so they survive any rendering size.
  • The document is stable markdown, with no client-side rendering required to read it.

Overview of the agent story at /for-agents. Install the skill at /docs/skill. Record something to read at clipy.online.