Inspect Media
Use this action when a workflow needs to know the shape of a media file — how long a video or audio clip is, how large an image is, and what format it is in — before deciding what to do with it.
Best for
- Checking how long a video or recording is before converting or transcribing it
- Making sure an uploaded image is big enough before using it as a logo or profile picture
- Checking whether a video actually contains sound before trying to use its audio
- Estimating what a transcription will cost before starting one
Why it matters
Every other way of looking at a file tells you its size in bytes and its type — and nothing else. That is enough to know a file is a 4 MB video, but not enough to know whether it is four seconds or forty minutes long, and those lead to very different decisions.
This action is the only place that answers those questions. Put it before the step that acts on the file, then use its answers in that step's condition.
Main fields
| Field | What it does |
|---|---|
| File | The file to inspect, usually step(0).file from an upload, download, or document step |
| Bucket and Full path | An alternative to File when you want to point at the file directly |
| Purpose | Optional label for what this step is for, shown in the logs. It does not change which file is inspected |
What later steps can use
| Value | What it is |
|---|---|
step(N).durationSeconds | How long the video or audio is, in seconds. 0 for images |
step(N).width, step(N).height | Size in pixels, for video and images. Empty for audio-only files |
step(N).hasAudio | Whether the file contains a sound track |
step(N).formatName | The container format, as the media tooling reports it |
step(N).videoCodec, step(N).audioCodec | How the picture and sound are encoded |
step(N).sizeBytes, step(N).contentType | Size in bytes and file type |
step(N).cached | Whether the answer was already known — see below |
What it costs
Reading these details means reading the file itself, so this step is billed against your transcoding allowance based on how long that takes. Larger files cost more; the file's size matters more than its length. A long podcast in a compact format is cheap; a short clip in a very high-quality format is not.
Two things keep that in check:
- Files over 512 MiB are refused rather than inspected, with a clear error naming the limit.
- Inspecting the same file twice is free. The first look is remembered on the file itself, so any later step or workflow that inspects it again gets the answer at no cost.
step(N).cachedtells you which happened. Media that arrived through a conversation has usually been inspected already, so it is free from the start.
Which files work
Video and audio files work in general. Images work — PNG, JPEG, WebP, GIF and SVG — and report a duration of 0.
A file that is not really media usually does not fail. If someone uploads a text file named photo.png, this step will normally still succeed. It reports an empty width and height — but a duration of about 0.04 seconds, which looks real. So checking that the duration is greater than zero will not catch a bad file. When the file comes from somewhere you do not control, check step(N).width instead, and do not rely on the step failing for you.
Tips
- Chain it directly: put Upload to storage, Download to storage, or an incoming file in one step, this action in the next, and your decision in the one after.
- Use it as a guard before expensive work: check
step(N).durationSecondsbefore starting a transcription, and skip the file if it is longer than you want to pay for. - Check
step(N).hasAudiobefore trying to transcribe a video. A silent video produces nothing useful, and finding out early saves the attempt. - Inspecting a file never changes its contents. It does record what it found on the file, which is what makes the second look free.