Rendered video judders: output_fps_resamples_sources and 24 to 30 fps

If a timeline render looks juddery, check whether you forced output.fps to a value your clips do not use. When the output rate differs from a source rate, Sume repeats or drops a frame every few frames, and the job reports the warning output_fps_resamples_sources with the rate the sources wanted. The fix is to omit output.fps, so the render follows the sources.

What happens when you leave fps out

The default is not 30. If you omit output.fps, the render uses the rate of the sources: the longest video sources decide, stills have no rate, and 30 applies only when no source has a rate. The default frame size is 1080 x 1920 MP4.

If you do set output.fps, the allowed values are 24, 25, 30, and 60. Setting one is fine when every clip already runs at that rate. It is the mismatch that costs smoothness.

The arithmetic of a mismatch

Take 24 fps clips in a 30 fps output. Each second of source holds 24 frames and each second of output needs 30, so 6 frames per second must be repeated. By that arithmetic, one output frame in five is a repeat. Slow pans make this visible as a rhythmic hitch. Going the other way, 60 fps clips into a 30 fps output drop half the frames, which reads as sharper but choppier motion.

The docs call this behavior judder on motion and describe the repeat or drop as happening every few frames. The exact pattern is the renderer's; the counts above are only the ratio.

Where else fps appears

The same rule exists upstream. Timeline compose defaults to the frame rate of the video layer, which it calls the only rate that does not repeat or drop a frame, and warns output_fps_resamples_sources if you force another. Video trim keeps the source rate unless you pass an output conform, which works only with precision: "exact" and accepts the same four rates.

So the clean pipeline is: prepare clips at one rate, leave output.fps out of the render, and read warnings[] on the result. If the warning shows up, the response tells you which rate the sources wanted.

Reading the warning in practice

The warning is soft, so a render that resamples still finishes and still bills the normal $0.10 per output minute. That makes it easy to miss. Make your client look at warnings[] on every result and fail a review step if output_fps_resamples_sources appears. The warning carries the rate that the sources wanted, which is the value you should have used.

If you intend to resample on purpose, for example to deliver a 30 fps file to a platform that requires it, accept the warning knowingly and check the motion visually. For 24 fps film-style footage going to a 25 fps file, the arithmetic above shows one repeated frame per second, which is the mildest mismatch in the table and is usually hard to see.

A short checklist

• Do not send output.fps unless every source shares that rate.
• If sources are mixed, pick one rate on the trim step (output.fps, exact precision) and keep it through compose.
• Read warnings[] in GET /v1/jobs/:id/result; warnings do not change the price.