Writing a sidecar

This page describes what a writer must do and what it can leave out. A writer is anything that has the original file: an app, a pipeline, a script, or an agent. The AnalyzeMedia API is the reference writer, and it follows the steps below. How the result maps to the format shows what it returns.

To write a sidecar, follow these steps:

1. Hash the original first. Compute source.sha256 over all the bytes. Compute source.quickHash as the SHA-256 of the size in bytes as decimal text, followed by the first MiB and then the last MiB. If you only saw a proxy, the hashes are still the original's. Record what you saw in generated.proxy.
2. Declare the type. Choose one of the six types and put it in type. Don't explain the choice in the file, and don't let the content decide it. A photo of a screen is a scene. A screenshot of a photo is a graphic. A jingle under a voice is speech.
3. Fill the envelope. Set format, version, and type. Set generated to your name, your version, and the models by role. Set source to the facts of the file by medium.
4. Write only what you analyzed. If you didn't run a section, leave it out. If you ran a section and found nothing, write an empty array or null. Don't write placeholders.
5. Give every timed item its seconds and every placed item its fractions. Use two decimals. Write spans as s and e, instants as t, points as x, y, and boxes as x, y, w, h. Sort every array.
6. Keep the grades honest. Measured fields hold facts of the bytes. Observed fields describe what is there. No field holds a judgment of quality, importance, or intent. If you can't pick a vocabulary value, use other.
7. Letter the people. Use A, B, C in order of first appearance, and use the same letter for the same person everywhere in the file. Number scenes from 1 in time order.
8. Regenerate events. This field is derived from the rest of the file. Don't edit it by hand.
9. Keep what you don't know. When you rewrite someone else's sidecar, preserve the fields that you don't understand.
10. Validate. Validate against the schema for the type. Then write <name>.analyzemedia next to the original.

What you can leave out

You can leave out everything below the envelope. A file that contains only the envelope is valid. It states that the file exists and what its bytes say. Add sections as you have them. A reader treats an absent section as not analyzed.