# Playhead

> An MCP (Model Context Protocol) server that lets an AI agent watch video.
> Give it a YouTube, TikTok, Instagram, X, Vimeo or Reddit link — or a path to a
> file on the machine the agent is running on — and it returns contact sheets:
> grids of frames in reading order, with the timestamp burned into the pixels of
> every frame.

## What problem it solves

Language models cannot decode a video file. Asked about a video, they answer
from the title, the description, or the transcript — none of which contain what
is on screen. Playhead turns the video into images the model can actually look
at, and burns the timestamp onto each one so the answer comes back anchored to a
second rather than to a guess.

## What is specific about it

- **Timestamps are in the pixels**, not in the surrounding text. A model cannot
  lose track of which frame it is looking at, and cannot invent a time for one.
- **Coverage is stated.** Ask without a window and the whole video is covered.
  Every response says what it covered, where the gaps are, and the exact call
  that would fill them.
- **Six detail levels**, from 0.5 fps across an hour to 30 fps with consecutive
  frames 33 ms apart. The level is chosen from the question, not fixed.
- **Detail costs tiles, not pixels.** Looking closer means fewer frames per
  sheet, never a larger image — models downscale anything past 1568 px, so a
  bigger sheet is only more expensive, not more legible.
- **It measures, it does not interpret.** Cut times, freezes, black frames,
  silence gaps and pacing come back as numbers. Nothing is labelled "a hook" or
  "a strong opening" — those are readings, and whoever reads them also has the
  frame the number belongs to.
- **Nothing to install.** ffmpeg, yt-dlp and transcription run on the server.
  This is the difference from the local scripts and Claude skills that do
  something similar: those need a working toolchain on the user's machine, which
  rules out Claude on the web and on phones entirely.
- **Local files work like links.** Pass `~/Movies/cut.mov` and it is uploaded
  once and reused, so a user's own edits, screen recordings and exports are
  analysable without publishing them anywhere.

## Three ways to use it

| Interface | For | Where |
|---|---|---|
| MCP server | An agent calling tools itself | `https://mcp.tryplayhead.com/mcp`, or `npx -y @playhead/mcp` |
| TypeScript SDK | Node code | `npm install @playhead/sdk` |
| REST API | Anything that speaks HTTP | `https://api.tryplayhead.com` |
| OpenAPI 3.1 | Agent frameworks and code generators | `https://api.tryplayhead.com/openapi.json` |

The MCP server and the SDK are both clients of the REST API, so nothing is
available through one and missing from another. The OpenAPI document is served
unauthenticated on purpose: a tool that cannot read the spec until it has a
credential cannot find out how to get one.

## Tools an agent gets

| Tool | What it returns |
|---|---|
| `watch_video(url)` | Contact sheets covering the whole video unless a window is given |
| `inspect_frame(url, t)` | One frame at 1560 px — the call to make when text has to be read |
| `get_transcript(url)` | Words with timings, no image tokens at all |
| `get_account()` | Which plan is connected, credits left, what recent calls cost |

## Detail levels

| Level | Rate | Max window | Answers |
|---|---|---|---|
| `overview` | 0.5–2 fps | no limit | What is this video, start to end |
| `standard` | 5 fps | no limit | What happens when — cuts, overlays, entrances |
| `detail` | 5 fps | 30 s | Objects and text blocks, tiles four times larger |
| `fine` | 10 fps | 10 s | Type, logos, subtle transitions |
| `motion` | 30 fps | 3 s | Animation, easing, dropped frames |
| `single` | one frame | a moment | Reading text at full resolution |

## Supported sources

YouTube, TikTok, Instagram, X (Twitter), Vimeo, Reddit, and any local file path.
Anything behind a login has to be uploaded rather than linked.

## Clients it connects to

- [How to let Claude watch a video](https://tryplayhead.com/watch-video-in/claude): Claude cannot open a video file on its own. Adding Playhead as a custom connector gives it three tools — watch_video, inspect_frame and get_transcript — and from then on you paste a link into the chat and ask what happens at second 37.
- [How to let Claude Code watch a video](https://tryplayhead.com/watch-video-in/claude-code): Run `claude mcp add --transport http playhead https://mcp.tryplayhead.com/mcp`, then `/mcp` to sign in. Claude Code can then watch any URL or any file on the machine by path.
- [How to let ChatGPT watch a video](https://tryplayhead.com/watch-video-in/chatgpt): ChatGPT reaches Playhead over MCP once developer mode is switched on: Settings → Connectors → Advanced → Developer mode, then add https://mcp.tryplayhead.com/mcp as a connector.
- [How to let Cursor watch a video](https://tryplayhead.com/watch-video-in/cursor): Click Add to Cursor and it writes the MCP server into Cursor's settings. From then on the agent can call watch_video on any link or on a file in the workspace.
- [How to let VS Code Copilot watch a video](https://tryplayhead.com/watch-video-in/vs-code): VS Code supports MCP servers natively. The install button opens the editor and adds Playhead to your MCP configuration; the first call asks you to sign in.
- [How to let Codex watch a video](https://tryplayhead.com/watch-video-in/codex): Codex reads MCP servers from ~/.codex/config.toml. Add an entry with url and auth = "oauth", and the CLI, the IDE extension and the desktop app all pick it up.
- [How to let a local model watch a video](https://tryplayhead.com/watch-video-in/lm-studio): LM Studio supports MCP servers. The install button adds Playhead to its list, and any vision-capable model you have loaded can then be handed contact sheets to look at.

## Pricing

| Plan | Price | Credits |
|---|---|---|
| Free | $0 | 60 credits a month |
| Creator | $19/mo | 600 credits a month |
| Pro | $39/mo | 2,000 credits a month |
| Studio | $109/mo | 7,500 credits a month |

One credit is roughly one minute of video at the standard level. `motion` is
billed per second because it extracts six times the frames. Analysing a
three-second window costs three seconds' worth, not a whole minute. A repeat
question about a window already paid for costs 20% of the original. Studio adds
seats: three people included, then $29 each for 2,000 more credits into one
shared pool.

## What it does not do

- It does not generate or edit video.
- It does not label what it measures. There is no `is_music` field and no
  `hook_ends_at` — those are judgements, and the evidence is returned instead.
- It cannot reach a video that requires a login. Upload the file instead.
- It does not run offline. The Enterprise deployment runs inside a customer's
  own network; the hosted service does not run on the user's machine.

## Documentation

### Getting started

- [Documentation — let an AI agent watch video](https://tryplayhead.com/docs): Playhead is an MCP server, a REST API and a TypeScript SDK over one engine. Give it a video link and get contact sheets with burned-in timestamps.
- [Quickstart — your first video in two minutes](https://tryplayhead.com/docs/quickstart): Connect Playhead to Claude, or make one API call with curl or the SDK. A free account starts with 60 credits and needs no card.
- [Connect to Claude, ChatGPT, Cursor or VS Code](https://tryplayhead.com/docs/connect): One-click connect buttons for Claude, Claude Code, ChatGPT, Codex, Cursor, VS Code and LM Studio. No API key to paste — you sign in instead.

### Using it

- [MCP server — five tools an agent can call](https://tryplayhead.com/docs/mcp): watch_video, inspect_frame, get_transcript, get_account and get_playbook. What each returns, when an agent should reach for it, and what it costs.
- [Detail levels — 0.5 fps to 30 fps, 33 ms apart](https://tryplayhead.com/docs/detail-levels): Six levels: overview, standard, detail, fine, motion and single. Looking closer means fewer frames per sheet, never a bigger image.
- [Supported platforms and video formats](https://tryplayhead.com/docs/platforms): YouTube, TikTok, Instagram, X, Facebook and Meta Ad Library, Vimeo, Twitch, Dailymotion, Reddit, any other site, plus broadcast formats like MXF and ProRes.
- [Playbooks — methods for recurring video jobs](https://tryplayhead.com/docs/playbooks): Seven worked methods: ad teardowns, hook analysis, caption audits, accessibility passes, brand checks, render QA and turning a recording into an SOP.
- [Examples — questions and the calls for them](https://tryplayhead.com/docs/examples): Worked examples: finding every cut, reading on-screen text, auditing an ad, checking a render, aligning a transcript to frames.

### Building on it

- [TypeScript SDK — @playhead/sdk](https://tryplayhead.com/docs/sdk): A typed Node client for the Playhead API: watch, transcript, uploads, jobs and credits, with typed errors that carry the call that would have worked.
- [REST API reference](https://tryplayhead.com/docs/api): Every endpoint: POST /v1/frames, /v1/transcript, /v1/uploads, GET /v1/jobs, /v1/credits, /v1/detail-levels and DELETE /v1/videos.
- [OpenAPI — add video analysis to any agent](https://tryplayhead.com/docs/openapi): A machine-readable OpenAPI 3.1 spec at /openapi.json, so agent frameworks, code generators and custom GPTs can add video analysis on their own.
- [Authentication — API keys and OAuth](https://tryplayhead.com/docs/authentication): Bearer API keys for your own code, OAuth 2.1 for connected agents. Keys are shown once and stored as a hash, so a lost key is replaced, not recovered.
- [Errors — written to be acted on, not just logged](https://tryplayhead.com/docs/errors): Every error type, what causes it, and which ones carry a suggestion object holding the exact call that would have worked instead.

### Comparisons

- [Compared to claude-video, claude-watch and DIY](https://tryplayhead.com/docs/compare): How a hosted MCP server differs from an Agent Skill that needs yt-dlp, ffmpeg and your own Whisper key on the machine you are sitting at.

## Worked examples

- [How to find every cut in a video, with timestamps](https://tryplayhead.com/docs/examples/find-every-cut): Where are all the cuts in this video, and how fast is it cut?
- [How to read on-screen text at a given second](https://tryplayhead.com/docs/examples/read-text-on-screen): What does the caption at 0:37 say, and how is it set?
- [How to analyse a competitor ad from Meta Ads](https://tryplayhead.com/docs/examples/analyse-a-competitor-ad): Why does this ad work, and what is the hook?
- [How to QA a render before it ships](https://tryplayhead.com/docs/examples/qa-a-render): Is there anything broken in this export?
- [How to align a transcript to what is on screen](https://tryplayhead.com/docs/examples/transcript-aligned-to-frames): What was on screen while they said the price?
- [How to analyse a long video asynchronously](https://tryplayhead.com/docs/examples/long-video-without-blocking): How do I survey a two-hour recording from a backend job?
- [How to recover when a call is refused](https://tryplayhead.com/docs/examples/recover-from-an-error): The API refused my window. What now?

## Playbooks — written methods for recurring jobs

- [Take an ad apart](https://tryplayhead.com/docs/playbooks/ad-teardown): Break a performing ad into its beats and claims so the reusable part can be named. Applies when an ad or piece of marketing is to be taken apart, or called a winner and copied from.

## How it compares to the alternatives

The alternatives are Agent Skills: Python that runs where the agent runs,
shelling out to yt-dlp and ffmpeg on the user's own machine, with a Groq or
OpenAI key of theirs for anything without captions. They are free, MIT-licensed,
and good on a laptop. What they cannot be is a connector — a skill that shells
out to ffmpeg has nowhere to run on a phone, cannot be called by a backend job,
and cannot be shared with a team as one account.

Their genuine advantages, which any fair comparison has to state: they cost
nothing, they are open source throughout, and the video never leaves the user's
machine. For footage under NDA that last one decides it.

- [Playhead vs claude-video — MCP server or Skill?](https://tryplayhead.com/docs/compare/claude-video): claude-video is a free MIT skill running yt-dlp and ffmpeg on your machine. Playhead is a hosted MCP server with burned-in timestamps and a REST API.
- [Playhead vs claude-watch — notes or evidence?](https://tryplayhead.com/docs/compare/claude-watch): claude-watch turns a lecture into markdown notes with screenshots. Playhead returns measured frames, cuts and coverage for any video. Which fits your job.
- [Playhead vs your own yt-dlp and ffmpeg script](https://tryplayhead.com/docs/compare/ffmpeg-script): Extracting frames is twenty lines. Timestamps a model cannot lose, stated coverage and nine platforms that keep working are the other 95% of the work.

## Links

- Home: https://tryplayhead.com
- Pricing: https://tryplayhead.com/pricing
- Docs: https://tryplayhead.com/docs
- REST API reference: https://tryplayhead.com/docs/api
- OpenAPI spec: https://api.tryplayhead.com/openapi.json
- TypeScript SDK: https://www.npmjs.com/package/@playhead/sdk
- MCP server package: https://www.npmjs.com/package/@playhead/mcp
- Remote connector URL: https://mcp.tryplayhead.com/mcp
- Sitemap: https://tryplayhead.com/sitemap.xml