Clearcut

Inspiration

Distributors won't touch a film without errors-and-omissions (E&O) insurance, and carriers won't bind a policy until every clearance issue on screen is resolved. That work — finding every logo, painting, face, sign and music cue in a cut, then identifying who owns it and how to license it — is done by clearance houses that charge thousands of dollars and take weeks. Indie films stall there. We wanted the legal department in a box, with the lawyer kept exactly where the law wants them: holding the pen.

What it does

Clearcut clears a film twice — the script before you shoot, the cut after — and hands your attorney an E&O-format package.

Cut mode. Frame Scout (Gemini) runs two-pass detection on the video: a visual pass that names every clearance-sensitive element with timestamps (trademarks, artwork, identifiable people, locations and signage, posters, clips), and an audio pass — anchored with the film's exact runtime — that segments music cues to the second, backstopped by a deterministic loudness check so a silent track can never produce a phantom cue. Rights Sleuth turns every flag into a Parallel Search objective at runtime and synthesises the evidence into a dossier: rights holder, status, contact or process, recommendation, sources — saying "unverified — needs human research" when the evidence is thin. Docket Clerk assembles the scene-by-scene report with the 12 standard E&O clearance procedures and a broadcast-style music cue sheet (MT/ET/BI usage codes; identification left honestly to a fingerprint or a human).

Script mode. The same fleet reads a screenplay and produces the classic script clearance report — character names, business names, addresses, products, real people, organisations, artwork, songs, on-screen text, locations — and researches the researchable ones. On our salted sample screenplay it found 19/19 planted entities and returned dossiers like "Bohemian Rhapsody → EMI Glenwood Music Corp. o/b/o Queen Music Ltd." and "Dunkin' → DD IP Holder LLC."

The console. A real application, not a demo page: a left-menu shell with Projects (every production — the shipped film and each named run — with a detail page of KPIs, elements and deliverables, and a project switcher in the top bar), Mission Control, a Docket (sortable, filterable table or board of every flagged element with dossier, recommendation, rights holder, status and actions), Runs (upload a clip, watch the stream, and a live table of your current and previous jobs), Script mode (entity table), Cue sheet (PRO-style table), Reports (rendered E&O report plus the 12-procedure sign-off table), Benchmark, About and Settings. The role switch in the top bar demonstrates the invariant: "Mark cleared" only enables for the attorney of record.

The fleet graph. An animated node diagram of the agents, the human gate and the services — Gemini, Parallel (Search live; Extract/Task/Monitor drawn dotted as roadmap), the ffmpeg rulers, the docket store. On the landing it runs ambient; in Mission Control it is driven by the replay, so when the Rights Sleuth queries Parallel you watch the packet leave and the dossier return.

Mission Control. The console replays a real run on the film itself: flags land on the frames at their true timecodes while the agent event log streams the exact Parallel queries and the dossiers that came back, and the clearance board fills in as it happens. Nothing is staged.

Governance. Agents can flag, research, draft and recommend. They can never mark an item Cleared. That transition is reserved for the attorney of record — an invariant in the code, not a promise in a README.

Benchmark. We built four salted films (baseline, small/occluded items, a multi-item frame with a silent no-music control, and a synthetic-style film for AI-generated content) with ground-truth JSON and publish the scores on the site: 15/15 planted items detected (recall 1.0), precision 0.938, 5/5 music cues within ±3 s, 0 false positives in negative zones. The one "spurious" flag is a fake magazine masthead we drew ourselves — a defensible flag, reported anyway. Every number is reproducible from the repo (spike/films, spike/scripts/run_evals.py).

Paper Chase. For every researched element the fleet drafts the licence or release request (or an internal note when no licence is needed, e.g. public-domain artwork). A sanitizer strips any contact address not present in the dossier evidence — the model does invent emails otherwise — and a human sends the request. The whole package (report, dossiers, drafts, cue sheet, 12-procedure sign-off page) exports as a PDF for the attorney of record.

How we built it

• Gemini via google-genai for detection passes, screenplay extraction and dossier synthesis (src/clearcut/detector.py, script_reader.py, research.py), structured JSON output throughout; model rotation across free-tier buckets.
• Google Cloud Agent Builder / ADK for the agent fleet: agents/clearcut_fleet/agent.py defines the clearance_supervisor root agent with detection, research and report tools; runnable with adk run.
• Parallel Search API called at runtime for every flagged item (src/clearcut/research.py::parallel_search, POST https://api.parallel.ai/v1/search), with type-aware query derivation.
• Parallel's MCP server as an ADK McpToolset on the Rights Sleuth (agents/clearcut_fleet/agent.py): web_search / web_fetch from https://search.parallel.ai/mcp, evidence synthesised into dossiers by Gemini, the Search API kept as fallback.
• Clearcut as an MCP server (mcp_server/server.py): ten tools — list projects, get docket, detect, shots, research, draft, report, cue sheet, script entities, policy — so any MCP-aware host or agent can call the clearance department. No mark_cleared tool exists.
• Backend (backend/): FastAPI job API with a Server-Sent-Events stream (detection → research → report), per-viewer and global daily caps, research cache — the "clear your own clip" panel on the site talks to it when it's online.
• Editor workflow (src/clearcut/shots.py, edl.py): ffmpeg scene detection gives every flag SMPTE in/out and a thumbnail; CMX3600 EDL / FCPXML import maps flags to clips and reels, a source-based cut-diff re-scans only what changed between versions, and flags export as a marker EDL editors can drop on their timeline.
• E&O package (src/clearcut/pdf.py): report, dossiers, drafts, cue sheet and the 12-procedure sign-off page as one PDF.
• Go/no-go spike (spike/): salted test films, ground truth, scorers — every claim above is checkable.

• ffmpeg + PIL for the films and the trailer; static console on GitLab Pages.

  Challenges we ran into

• Music cues taught us the most. A single-pass prompt merged cues and drifted past the film's real duration; a runtime-anchored audio pass fixed that on the baseline film, then our silent control film showed it will invent cues on silence, and the occluded-items film showed it heard a mid-film piano but placed it at the wrong time. The fix that held: the ruler proposes and the model labels — ffmpeg silencedetect finds the sound windows, Gemini says which contain music, a loudness check rejects anything on silence. Cues went from 4/5 to 5/5. Perception needs both a model and a ruler.

• Free-tier quotas: no pro-model quota at all and ~20 requests/day per flash model. Model rotation across per-model buckets, a resumable pipeline, and a research cache keep runs cheap.

• Hosting with no billing account: Docker hosting turned out to be paid nearly everywhere, so the console is static and the upload backend is served through a tunnel when the demo host is up; the site degrades gracefully when it isn't.

• Building demo films we actually own, salted with known landmines, so the demo is honest and rehearsable.

  Accomplishments that we're proud of

Perfect detection on the baseline film and 19/19 on the screenplay; research that surfaces real operators (Ocean Outdoor, Landsec, DD IP Holder) rather than generic advice; a control item where the system correctly admits it cannot verify; a benchmark that reports our own false positives; and a governance invariant that makes the human sign-off structural.

What we learned

Video-native models are ready for clearance work if you split perception into passes, anchor them with facts you already know (runtime, scene boundaries), and backstop them with deterministic measurements. Research agents are only as good as their honesty policy. And "E&O won't bind until every recommendation is implemented" is the hard gate that turns a nice demo into a real product.

What's next for Clearcut

Firestore docket with IAM-enforced attorney role; Parallel Extract for contact pages, Task for batch enrichment, Monitor to watch open items; license-request drafts sent and tracked from the docket; EDL/FCPXML import with cut-diff; C2PA provenance and disclosure checklists for AI-generated film; Vertex pro-model detection for feature-length cuts.

Built With

• adk
• fastapi
• ffmpeg
• gemini
• gitlab-pages
• google-cloud-agent-builder
• paralell
• parallel-search-api
• pillow
• python