Find the moments in a video, or in an edit as it renders, that match what you describe in plain words, so you go straight to them instead of watching it all. Name each criterion and say what a matching frame shows; you get back the stretches of time where each one holds, with the time and picture of the best frame in each.
Use it to:
- Check quality: find frames that are too dark or blown out, out of focus, black or blank (a gap in an edit), with a microphone or crew in shot, with text cut off at the edge, or with a caption over a face. With timeline_id it checks the edit as it renders, titles, effects and gaps included.
- Watch efficiently: looking through a whole video costs you a picture for every moment. Seek judges the frames for you and says where things are, so you look only there: where the demo starts, where the speaker holds up the product, where the second location begins.
- Pick shots: B-roll or a thumbnail moment that fits a description ("a wide shot of a city street at night", "she smiles straight at the camera with her eyes open").
- Find changes: with with_previous, where the slide changes, someone walks in or the camera angle switches ("`frame` shows a different slide from `previous`").
- Find room or trouble for overlays: where the lower third stays empty for a title, or where a logo, a licence plate or a face appears that needs a blur.
HOW TO WRITE CRITERIA. TypeSafe Jev, a fast judgment model (preview), judges each sampled frame on its own, as a picture named `frame` (about 512 px on its long edge; with with_previous also `previous`, the frame sampled before), and gives each criterion the probability that it is true. A criterion is a statement or a question about how the picture looks. Keep one judgment to a criterion, and say what shows rather than a verdict: not "bad lighting" but "the faces are too dark to make out their eyes"; not "a good thumbnail" but "a person looks straight at the camera with eyes open and mouth closed". Criteria that name no picture or state entry in backticks are asked about `frame` ("In `frame`: <your words>"); name `frame`, `previous` or your state entries yourself to judge them together ("`frame` shows the button `line` talks about"). Jev answers most accurately from examples: give {instructions, criteria: {true: "…", false: "…"}} with a case of each ({true: "the face is a dark silhouette against a bright window", false: "the face is evenly lit, a little dim"}). Detail too small to see at that size (fine print, slight softness) answers poorly; check it with render.frames at full size.
READING THE RESULT. matches gives, per criterion, each run of consecutive samples at or above min_probability (default 0.5), with its start, end and best sample: peak_seconds, frame (for render.frames) and uri (a resource to read the picture). samples has every probability, for your own cut-off. A probability near 0.5 means Jev cannot tell, not that the thing is half there: reword a criterion that keeps landing there. asked shows the question each criterion became.
COST. Each frame is one judgment however many criteria it carries, so ask everything you are looking for in one call (up to 32 criteria). Work in passes: every_seconds 2 to 5 over the whole video, then at_seconds around a match to find more exactly where it starts. Up to 600 frames a call. Long-running: returns a task, or a job_id for job.get.
media.analyze look asks typed questions (a choice, a score, a box) of every frame when you need measurements rather than moments; judge.ask judges one picture at once.
