A metadata schema for logging video

A metadata schema is the fixed set of questions you ask every clip, each with a type and a defined set of answers. That is all it is, and it is the difference between a library that answers questions and a folder of files with words sprinkled on them.

This is the reference: which fields earn a slot, what the types do, and what file the answers have to live in. How to grow a schema without abandoning it by clip thirty is a separate discipline, in design a logging palette that earns its keep.

Why free-text tags fail, in three specific ways

Tags feel like freedom and behave like entropy.

First, the vocabulary forks. "TD", "td", and "touchdown" become three different searches by November, and nobody circulates a memo about which one won. A controlled list makes them one thing, permanently.

Second, and this is the failure people never articulate: with tags, absence is unreadable. A clip with no "wide" tag might be a close-up, or it might be a clip nobody has logged. Those are completely different facts and a tag cloud cannot tell them apart. With a field, "Framing: not set" and "Framing: close" are distinguishable states, so you can filter for what is unlogged and finish the job. Tag-based libraries never finish, because they cannot see their own gaps.

Third, tags cannot be asked quantitative questions. A rating, number, date, or duration range supports comparisons. A string does not.

There is a fourth reason that only exists now: a schema is the AI's output space. A model handed your fields, options, and one-line definitions must answer inside them. Handed a blank tagging box, it returns generic prose that reads well and filters badly. The schema is what makes analysis useful rather than decorative, which is the practical half of analyzing video clips with AI.

Three layers, and only one of them is your job

Layer one is what the camera already wrote: codec, duration, dimensions, frame rate, color space, log format, file size, timecode. Never type any of it. It is captured perfectly and already in the file, and a schema that asks you to re-enter it is a schema that will be abandoned. This is the most common beginner mistake, and it burns the enthusiasm you needed for the fields that matter.

Layer two is the decisions the camera cannot record. That is the schema. Layer three is project-specific and gets added later, from evidence, when you catch yourself wanting the same extra decision a third time.

The six fields that earn their slot on footage

Across sports, events, documentary, and commercial work, the same small set keeps proving out. You will not run all six on day one. Start with three.

Usability (single-select: hero, usable, reject). The field that pays for itself first, because it is the only one that shrinks the pile. Every other filter runs faster on a set you have already culled.

Subject (a linked identity, roster-bound where you have a roster). Who or what is in the clip, as a durable entry rather than a typed name, so the person found by face grouping in one clip and by jersey number in another resolves to one thing. That model is subjects: one identity, many signals.

Content or Action (single-select, vocabulary specific to your work). The play type, the ceremony beat, the interview topic, the product shot. Its options will grow the most.

Framing (single-select: wide, medium, close, insert). Cheap, near-objective, and what editors actually filter on when they need coverage.

Sound (toggle). Is there usable sync audio. One bit, and it saves an editor opening thirty clips to find out.

Location (single-select, ideally from a lookup table of codes).

Notice what is absent: mood, lens, weather, sponsor visibility. Real fields, someday. On day one they are the fields you fill twelve times and quietly stop filling.

Field type decides where the value lands

This part is rarely explained, and it decides whether your work is visible outside your own app.

Native kinds map onto the standard metadata slots every editing tool already reads: flag, rating from 0 to 5, color label, text note, and keywords. In ClipLogger these write through to their XMP, Resolve, and ALE equivalents, with notes landing in dc:description and keywords in dc:subject. Structured kinds (single-select, multi-select, toggle, number, date, people, and subject) live in your own log record under your own keys, each carrying its own provenance and timestamp.

The rule: put the two or three fields other tools must see into native kinds, and let everything else be structured. If your assistant works in Premiere and needs the usability call, make it the rating or the flag.

Closed fields also constrain the model, dropping out-of-vocabulary suggestions entirely, while keywords, text, ratings, and a narrative description field stay open by design. Either way the value is a suggestion until a person accepts it, for the reason in AI proposes, you confirm.

One more type note: any field whose options come from a list somebody else already maintains should be driven by that list, not retyped. A jersey roster, location codes, crew, SKUs. Import the sheet as a code-to-value table and log by typing the code, and because every code resolves through one shared table, the same athlete cannot fork into two entries. That is rosters, CSVs, and logging at the speed of a game.

The schema is only as durable as the file under it

A schema you cannot read without its application is a schema on loan.

The arrangement that has survived every vendor death so far is plain files, in documented formats, next to the media they describe. ClipLogger writes a .logger.json sidecar beside each clip, named after the full filename, in three blocks: media for what the camera wrote, ai for the evidence with each model attempt stamped by engine and time, and user for your confirmed decisions with per-field provenance. It is pretty-printed JSON with documented keys, so a ten-line script pulls every action value out of a season with no ClipLogger installed anywhere. Optional XMP, Resolve CSV, FCPXML, and ALE writers exist for pipelines that want native shapes.

Apply the delete test to whatever you adopt: describe ten clips, remove the app in your head, and look at what is still readable on the drive. The checklist is metadata should outlive the app.

The schema also writes the filename

One more payoff, easy to miss. A schema of confirmed values can compose the output filename, because the values are structured and predictable. That matters because the filename is the only metadata that survives a transcode, a review portal, and a round trip through someone else's NLE, argued in the file name is the only metadata that always travels and built out in naming conventions that survive.

What the AI pass contributes to filling all this in is what an AI video logger actually does, and for terabytes already sitting on a share, an AI assistant for the footage on your NAS.

A schema is worth having when every field is a question you answer on every clip and every answer lands in a file a stranger could read in ten years.