video-filter dim amount 0 or 1.2 is refused: the (0, 1] range
Dim amount takes values above 0 up to 1. Zero, negatives and 1.2 return video_filter_amount_out_of_range. What it does, and how to lift a dark clip.
The dim op in Sume video filter takes an amount in the half-open range (0, 1]. 0.45 darkens the clip, 1 leaves it unchanged, and anything at or below 0, or above 1, is refused with video_filter_amount_out_of_range. Dim only ever darkens; it cannot brighten, so a 1.2 is an error and not a boost.
What the number multiplies
The compiler turns amount into a luma-only expression, lutyuv=y=(val-minval)*amount+minval. Two consequences follow from that line of source. Black stays black, because the multiply is anchored at the range minimum. Chroma planes are untouched, so a dim never tints the picture toward grey or blue. That makes it a good fit for putting a calm layer under caption text, which the busy-footage caption post covers in full.
Typical mistakes
Percent values are the usual one. 45 and 0.45 look alike in a spreadsheet column, and 45 fails the range check. Zero is the second: someone wants the clip black for a few frames, but a zero multiplier is refused rather than rendering a black video. For a fade to black use a fade filter in filtergraph, which is on the allowlist.
| amount | Result |
|---|---|
| 0.45 | Darker picture, black and colour balance preserved |
| 1 | No change |
| 1.2 | video_filter_amount_out_of_range |
| 0 | video_filter_amount_out_of_range |
| -0.3 | video_filter_amount_out_of_range |
| 45 | video_filter_amount_out_of_range |
Lifting a dark clip
Because dim cannot go above 1, brightening belongs in the filtergraph. Tone filters such as eq, exposure, normalize and vibrance are on the allowlist. An example is eq=brightness=0.06:contrast=1.05. Run it through the check route first so a typo in an option shows up as a diagnostic and not a failed job.
curl -X POST https://api.sume.com/v1/video-filter/check \
-H "Authorization: Bearer $SUME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
"ops": [{ "op": "dim", "amount": 0.45 }]
}'Limits to keep in mind
Source clips for video filter must be 300 seconds or shorter; longer sources fail with output_duration_exceeded, so cut a range with video trim first. An encode job is $0.02 and the check is free. Up to 8 ops are allowed in one program, and dim and crop can sit in the same one.
Sources
Related posts
More in Media tools
- video-filter invalid_filtergraph: every reason and the fix for each
A video-filter filtergraph is refused for eight reasons, from a [0:v] label to a quote character. What each one means and how to rewrite the graph so it passes.
- video-filter unsupported_filter_op_field: crop and dim keys allowed
A crop op takes four fractions and dim takes one amount; any extra key returns unsupported_filter_op_field. The exact key lists and where the extra work goes.
- video-frames returned a null url: the job succeeded, one frame failed
If one instant fails to extract, video-frames sets that frame's url to null and the job still completes. How to detect it and retry only that time.
- video-inspect frames: at[] and fps together is a 400, pick one
video-inspect and video-frames take a list of times or a sample rate, never both. The codes, the 24-still cap, the fps 2 ceiling, and the empty object.
Written by Sume