Peckworks Lab · source-available MP4 metadata suite · MCP-native
Tag the clip you just recorded, by voice, while you're still playing.
// clipmeta writes searchable metadata INSIDE your .mp4 files, so the tag never leaves the clip.
You have a hard drive full of game clips you'll never get through, and a highlight reel in your head you'll never sit down to make. clipmeta fixes the root cause: the moment something great happens, you say what it was out loud, "tag that, market-garden triple, save it for the montage", and Claude writes that straight into the clip's bytes. Later you ask for "every TF2 airshot rated 4+" and they're just there. No spreadsheet, no folders, no sidecar files that get lost. The tag lives inside the MP4 and travels with it forever.
A folder of thousands of clips is a graveyard, not a library.
Modern capture makes saving a moment effortless, one hotkey and the last 30 seconds are on disk. So you press it. A lot. Months later you have a directory of 2022-02-01 21.50.02.mp4, Replay_0473.mp4, clip001.mp4, hundreds of gigabytes, and no idea what's in any of them.
Two specific frustrations started this project:
The library I'll never get through. The great moments are in there. Finding them means re-watching everything, which means I never do.
The montage I'll never make. I can picture the highlight reel perfectly. Actually scrubbing a thousand files to assemble it? That hour never arrives.
The information that would fix this, what game, who was in it, what happened, was it any good, existed for about ten seconds: right when the clip was recorded, while I was still grinning about it. Then it evaporated. By the time I'm looking at the file name, it's gone.
Feynman version: it's a shoebox of unlabeled photos. Every single one was obvious the day it was taken, "oh that's the trip to the coast." A year later it's a stack of strangers. The fix was never a better shoebox. It's writing on the back of the photo while you still remember.
The funnel that never drains. The bottleneck isn't capture or storage. It's that the meaning is never recorded.
PART 02
The idea, record the meaning when it's freshest
The insight the whole tool is built around
The best time to label a clip is the second it happens, not "later."
"Later" is where metadata goes to die. The entire design follows from refusing to wait. If the only moment you reliably know what a clip is worth is right after it's recorded, then that is when the tag has to be written, without breaking your flow, without alt-tabbing out of the game, ideally without even taking your hands off the controls.
That single constraint produced three design commitments:
Capture at the source
Tag the moment of recording, when the memory is vivid, not in a cleanup session that never happens.
Hands-free input
Speaking is the only input that doesn't pull you out of the game. So the front door is your voice, via an AI assistant.
The tag rides along
Write it inside the file, not a database beside it. Move the clip, back it up, share it, the meaning goes too.
Analogy: a field biologist doesn't photograph a hundred birds and identify them next winter from memory. They speak into a recorder the instant they see one, "male goldfinch, north ridge, 7:12." clipmeta is that recorder, for your clips. The identification happens at the only moment it's easy.
PART 03
The solution, metadata that lives inside the MP4
Why inside the file, and not a sidecar
The tag is written into the clip's own bytes, so it can never get separated from it.
Most "tagging" tools keep your labels in a separate database or a .json sitting next to the video. The day you move, rename, copy to another drive, or hand a clip to an editor, that link breaks and the metadata is orphaned. clipmeta takes the harder, durable path: it writes the metadata into the MP4 container itself, the same place a camera stores GPS and a song stores its artist.
Feynman version: a sidecar file is a sticky note on a folder, it falls off. clipmeta is ink on the back of the photo. The two never part, because they're one object.
An MP4 is a tree of nested boxes (the format calls them "atoms"). clipmeta adds its fields as ---- "freeform" atoms under a private namespace, com.peckworkslab.clipmeta, so they sit alongside, and never collide with, the file's existing metadata, the iTunes-style tags, or another tool's data.
Because clipmeta already walks that entire tree to read and write safely, it can also hand the whole structure to you: clip_get_boxtree (in Claude Desktop) and clipmetaview --json (in the terminal) return every box's type, friendly name, size, and position as JSON, with clipmeta's own fields flagged, so you can inspect exactly how a file is laid out. Read-only, it never touches a byte.
schema 1 · tagged_by Peckworks ClipMeta · stored in-file, travels with the clip
The fields you get out of the box
Six well-known fields cover most of what you'd search by, plus any custom name you invent. Multi-value fields are pipe-delimited ("rocket jump|headshot").
game
What you were playing, the top-level filter.
players
Who was in it (you, your squad, the victim).
tags
Free-form moments: airshot, clutch, funny.
rating
Is it montage-worthy? The "make the cut" signal.
timecode
The exact in-clip moment worth keeping.
notes
Anything else, context, a caption idea.
PART 04
Tag by voice, the workflow this was built for
The headline use-case
You're still in the match. You say what just happened. It's tagged before the round ends.
This is the part that makes clipmeta more than a metadata library. Because it ships an MCP server, an AI assistant like Claude can drive it directly. Pair that with voice input and the whole loop closes without you ever leaving the game: you hit your normal record hotkey, then talk, and Claude figures out which clip you mean and writes the tag.
YOU
mid-match, hands on keyboard
"Claude, that last clip, tag it. Team Fortress 2, market-garden airshot on the spy. Rate it a 5, that's going in the montage."
AI
Claude, via the clipmeta MCP server
Found the clip you just recorded, Replay_0488.mp4 (newest in your library, and your player still has it open). It's playing right now, so I've queued the tag; it'll be written the instant the file is free. game=Team Fortress 2 · tags=market garden|airshot · players=spy · rating=5 ✓
YOU
next day
"Pull up every TF2 clip rated 4 or higher."
AI
Claude
7 clips match game=Team Fortress 2 and rating ≥ 4. Here they are, newest first, want me to copy them into a montage/ folder?
// Illustrative exchange. Voice-to-text is provided by your assistant/OS; clipmeta provides the tools Claude calls.
What actually happens under the hood
The clever part is "which clip." You didn't give a filename, you can't, you're playing. clipmeta resolves it from the world around you: it checks your open media players and your newest recordings, scoped strictly to your clips folder.
The resolve-then-tag loop. You never type a path. library_watching figures out which clip you mean; a write (or a deferred queue) records it.
Resolve, never guess
A clip is only ever matched from a file inside your library folder. A window title that names a path elsewhere matches nothing, it's dropped. The tool selects; it never invents a path.
Playing = locked
A clip your player is showing can't be safely rewritten. clipmeta detects the lock and defers the tag to a queue instead of failing or corrupting.
Drains automatically
Next time you tag, list, or flush, queued tags whose clips are now free get written, so "tag it now" works even mid-playback.
ClipMeta · Voice Tagging
Say it once. It lands in the file.
gaming mode · just clipped
1
You said
"Tag that last one... Team Fortress 2, badwater. Chuck rocket-jumping up to second point and landing a perfect market garden on chicken."
2
ClipMeta resolved which clip
library_watching→Team Fortress 2 2026.07.04 - 07.58.38.444.DVR.mp4● HIGH recent_write · saved 3s ago while no player was open · directly writable
3
Structured metadata written
gameTeam Fortress 2
mappl_badwater
playerschuckchicken
tagsrocket jumpmarket garden
notesChuck rocket jumping on 2nd point, landing a perfect Market Garden on chicken
written to file · backup kept · com.peckworkslab.clipmeta · schema 1 · tagged_by Peckworks ClipMeta
PART 04 · DETAIL
From spoken tag to saved byte: the exact path
THE DECISION TREE
Two ways to answer "which clip do you mean?"
Tagging by voice hides one hard question: at the instant you speak, which file on disk do you mean? clipmeta never guesses. It resolves that deterministically, and the answer comes from one of two modes, depending on what you are doing right then.
Think of a darkroom. If a print just dropped into the tray, the newest one is obviously the shot you mean. If you are flipping through prints already hung on the line, the one you mean is whichever you are holding up to the light. Same words, two different ways to know which print.
Gaming mode
No media player open. You just made a clip and you are still in the game. clipmeta resolves the clip just saved to disk.
Review mode
You are watching clips back in a player. clipmeta binds to the clip that was playing the moment you spoke, even if you have skipped ahead since.
resolvewritedoneasks you to confirmstops safely, file unchangedqueued, written later
Gaming mode: tag the clip you just saved
Gaming mode. One fresh save is auto-taggable. Zero or several, and clipmeta asks you first.
Review mode: tag the clip you are watching
Review mode. A clip a player still holds is locked, so the tag waits in a queue and lands the instant the file frees.
Both modes converge on the same safe write pipeline (see Part 07): the only file ever opened for writing is a throwaway temp, verified to be byte-identical before an all-or-nothing swap. Any failed check leaves your original exactly as it was.
PART 05
How it's built, one engine, three front doors
The architecture, in one breath
All the real work lives in one zero-dependency core. The CLI, the batch jobs, and the MCP server are thin shells over it.
clipmeta is a small suite of C# (.NET 10) projects. The rule that keeps it honest: all business logic lives in clipmeta.core, MP4 parsing, the safe write engine, search and indexing, and it has zero external NuGet dependencies, pure .NET base library only. Everything a user touches is a thin shell that parses input and calls into Core. Add a new front door without rewriting the engine.
One engine, three shells. The MCP server is just another thin caller of the same Core the CLI uses, so a tool Claude runs and a command you type take the exact same safe path.
What is MCP, and why does it matter here?
MCP, the Model Context Protocol, is an open standard for giving an AI assistant real, typed tools instead of just a chat box. The clipmeta MCP server speaks JSON-RPC over stdio and advertises 17 tools the model can call, each with a strict schema and a description written for the model so it self-corrects.
Analogy: without MCP, an assistant is a brilliant intern who can only talk about your clips. MCP hands that intern a labelled control panel, buttons for "list," "tag," "search," "undo", each one wired to the same safe engine you'd use by hand. clipmeta builds and ships that control panel.
The 17 tools Claude can call
Tool
What it does
Read, 7 tools (always safe, never modify a file)
clip_get_metadata
Read every clipmeta field on one clip.
library_list
List clips in the library with their tags.
library_find
Find clips where a field matches a value (live scan).
library_vocab
Show every distinct value used for a field, your tag vocabulary.
library_export
Export the library's metadata as JSON or CSV.
library_search_index
Fast search against a pre-built index.
library_watching
Resolve the clip you're currently/just watching from open players + newest files.
Write, 4 tools (the safe write engine, sandboxed)
clip_set_fields
Set one or more fields on a clip.
clip_append_field
Add a value to a multi-value field without losing the rest.
clip_clear_fields
Remove specific fields.
clip_clear_all
Strip all clipmeta metadata back to pristine.
Backup & restore, 3 tools (an undo button for writes)
library_list_backups
List the .bak safety copies on hand.
clip_restore_backup
Roll a clip back to a backup.
clip_prune_backups
Clean up old backups.
Deferred-tag queue, 3 tools (for clips that are still playing)
library_queue_tag
Queue a tag for a clip that's locked, to write when it frees up.
library_flush_queue
Write all queued tags whose clips are now free.
library_queue_status
Show what's waiting in the queue.
// The server is delivered as a one-click .mcpb bundle for Claude Desktop; the library folder is chosen at install and becomes a hard sandbox (see Part 07).
…and the CLI underneath, for everything else
Prefer the keyboard, or want to script a thousand clips at once? clipmetascribe is the same engine as a command-line tool. Directory-wide batch ops, copying tags from one clip to many, building a search index, and flushing the queue all live here.
clipmetascribe, PowerShell
# tag one clipPS> clipmetascribe "Replay_0488.mp4"--set game "Team Fortress 2"--append tags "airshot"--set rating "5" ✓ wrote 3 fields · verified · mdat byte-identical# find everything that matches, across the whole libraryPS> clipmetascribe "C:\clips\"--find game "Team Fortress 2" Replay_0488.mp4 tags=airshot|market garden rating=5 Replay_0461.mp4 tags=clutch rating=4 2 clips matched# copy a clip's tags onto a whole folder of related clipsPS> clipmetascribe "C:\clips\stream-07\"--copy-from"reference.mp4" ✓ 38 clips tagged · 1 source skipped
PART 06
Finding your clips, the payoff
Tagging is only worth it if finding is effortless
Ask in plain language; get back the exact clips, by game, player, tag, rating, or any combination.
Because every clip carries its own metadata, search is just reading it back. There are two speeds:
Live find (library_find / --find) scans the folder directly, always current, great for a few hundred clips.
Indexed search (library_search_index / --index then --index-search) builds a small index file once, then answers instantly across huge libraries.
Two more tools turn a pile of tags into something you can actually reason about:
vocab
"What tags do I even use?" Lists every distinct value for a field, so your vocabulary stays consistent instead of airshot vs air-shot vs airshots.
export
Dump the whole library to JSON or CSV, drop it into a spreadsheet, a video-editor script, or a montage tool.
copy-from
Tag one clip well, then stamp those tags across an entire folder of related clips in one command.
Barblitz and barnblitz are almost certainly the same map, split across two clips. Vocab surfaces the drift so you can merge it, and shows that half your maps carry the pl_ prefix while half don't.
One line answers "what have I actually called this field?" · read from the com.peckworkslab.clipmeta atoms in every clip
PART 07
Built not to corrupt your files
The part that took the most engineering
A tool that edits irreplaceable footage has exactly one unforgivable bug: silently breaking the video.
Rewriting an MP4 in place is genuinely dangerous, get one byte-offset table wrong and the file still looks fine but plays garbage, or the entire video track vanishes while the program reports success. clipmeta is built around not doing that, and the safety is tested, not assumed (~600 tests, including ones that hash every frame of video before and after a write).
The golden rule: your original is never opened for writing
Every change goes to a brand-new temp file. The new file is then re-parsed and verified from scratch, does it still contain all the video, byte-for-byte?, and only if it passes does an atomic swap replace the original. If anything fails, the temp is deleted and your file is untouched. You can't end up half-written.
Temp → verify → atomic swap. The only file ever opened for writing is a throwaway. The swap is all-or-nothing.
WAR STORY"Read-lenient, write-strict." Early on, a single unreadable box between the header and the video made the parser stop early, and the writer faithfully rebuilt the file without the video, returning success. The footage was gone, exit code 0. The fix is now a hard rule: the parser stays forgiving so a damaged file is still viewable, but the writer refuses any rewrite whose parsed boxes don't account for the whole file, byte-for-byte. That boundary is explicit and tested.
Foreign data preserved
Tags another tool wrote, iTunes fields, camera GPS, a different app's data, are copied through byte-for-byte. clipmeta only ever touches its own atoms.
Survives the AV race
Antivirus grabbing a freshly-written file used to make the swap fail. The final swap now retries on transient locks, safely, because the bytes are already verified.
Hard sandbox
The MCP server can only ever touch files inside the one library folder you chose at install, verified against the OS-canonical path, so even directory-junction tricks can't escape it.
Backups + undo
Opt-in .bak copies and restore tools mean a write is reversible. Clearing metadata returns the file to genuinely pristine bytes.
// Every hazard above is a real bug that was hit, fixed, and written into docs/PITFALLS.md, the project keeps a running log of exactly this class of mistake.
PART 08
Caveats & roadmap, the honest limits
What it does and doesn't do, stated plainly
No vaporware. Here's exactly where the edges are.
MP4 onlytoday
Reads and writes .mp4 / MOV-family files. That covers most game capture (ShadowPlay, OBS-MP4, GoPro, consoles). The architecture is built for new formats to plug in, but right now, MP4 is it.
Fragmented MP4 refusedby design
Some live-streaming recorders write fragmented (moof) MP4s. clipmeta detects these and refuses to write with a clear message rather than risk corruption. Reading still works.
Watched-clip = Windowsmaturing
The "which clip am I watching" resolution currently recognizes Windows media players (MPC-HC, VLC). Tagging and search are cross-platform; the live-resolution piece is being dogfooded and hardened.
Voice is your assistant's jobintegration
clipmeta doesn't ship a microphone. It provides the tools; speech-to-text comes from Claude Desktop, your OS dictation, or a voice front-end. clipmeta makes the tagging hands-free, not the talking.
Desktop install is a dev flowv1
The MCP bundle installs via Claude Desktop's "Install Extension" developer flow (an unpacked-folder fallback exists for a Store-build quirk). It works; it's not yet a polished one-tap store listing.
It's young, but carefulstatus
This is an actively developed personal project, dogfooded on real clip libraries. The safety engineering is mature; the convenience layer is still growing. Try it on copies first.
On the roadmap
The full "montage run" workflow, describe a reel out loud, have Claude gather, order, and stage the matching clips.
Broader watched-clip support across players and platforms.
More capture formats behind the same safe write engine.
FAQ
Questions you're probably about to ask
Straight answers
QWill this re-encode or degrade my video? No. Your video and audio streams are copied byte-for-byte; only a tiny metadata box is added. A tagged clip is bit-identical in the parts that matter, and that's verified on every write.
QDo the tags survive uploading to YouTube / Discord / a cloud drive? The tags live in the file, so any copy or move keeps them. Platforms that re-encode on upload (YouTube) won't preserve them in the published video, but your local master keeps them, which is exactly where you search and build montages.
QCan other tools read clipmeta's tags? They're standard MP4 freeform (----) atoms under a private namespace. Tools that surface freeform atoms can see them; clipmeta won't disturb tags written by other tools either.
QDo I have to use Claude / voice? No. The CLI (clipmetascribe) does everything by hand or in scripts. Voice + MCP is the marquee workflow, not a requirement.
QWhat if I tag the wrong clip? Writes can keep a .bak, there are restore tools, and clearing returns the file to pristine bytes. The whole design assumes you'll occasionally want to undo.
QIs my clip library sent anywhere? No. clipmeta runs locally and has zero network calls and zero external dependencies. If you use it through Claude, your assistant sees the tool results you invoke, the files themselves stay on your machine.
START
Get started
Three ways in
Download and install. Grab clipmeta.mcpb from the latest release. In Claude Desktop open Settings, Extensions, Advanced settings, Install Extension and pick the file, then choose your clips folder when prompted. No terminal, and no .NET to install (Windows 10/11, 64-bit).
Tag by voice. Open any conversation and say "tag that last clip...". Claude resolves which clip you mean and writes the tag inside the file. Ask "find my TF2 clips rated 4 or higher" to pull them back.
Prefer a terminal? The optional clipmeta-cli-win-x64.zip in the same release gives you clipmetascribe and clipmetaview, self-contained. Developers can also clone the repo and dotnet build.