Video trim end past the clip: trim_clamped_to_source vs start error

When a Sume video trim asks for a range that runs past the end of the clip, the job succeeds with a shorter file and a trim_clamped_to_source warning. When the start itself is at or past the end of the clip, the job fails with trim_start_past_source. The first is forgiving by design, the second is a hard error, and both are worth handling.

The clamp is documented on the video trim page: end "past the source clamps and the result warns". The failure code and the warning's context fields come from the trim executor in the Sume repository.

What does the clamp do?

The executor measures the source, then compares the requested length with what is left after start. If the request is longer, it shortens the cut to the remainder, rounded to three decimals, and adds a warning whose message says the range ran past the end and was clamped. The warning's context carries requested_seconds and source_seconds.

A comment in the code explains the intent: a caller who asked for 50 to 70 seconds of a 60 second clip "wanted the tail, not a failure". The same rule applies whether you passed end or duration, because the program is reduced to a duration internally.

When does a trim fail instead?

These are the cases that matter for a range cut.

Why does the shorter file matter?

Because a pipeline can mistake success for the length it wanted. Suppose an episode must be at most 180 seconds, which is the Shorts series limit YouTube's help page gives, read on 2026-10-02 at Create shows from your videos. A clamp can only make the clip shorter, so it never breaks that cap, but a 61 second file where you planned a 90 second one is a quality problem, not an API error.

The result carries duration_seconds, so compare it with what you asked for. A mismatch plus a warning is the signal. Without that check, a wrong source_seconds assumption, for example a clip that was re-exported shorter, goes unnoticed until someone watches the output.

How do I check the length before and after?

Probe first with video inspect and frames: false, which is unbilled for the probe, and read the duration. Then choose start and duration so that start + duration is at most the source length, and check warnings[] on the result. Poll the job rather than holding a request open; the jobs page explains the 30-second sync limit.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: trim-tail-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 50,
    "duration": 20
  }'

What if the source has no audio?

The same executor adds a second warning, trim_source_has_no_audio, when you keep audio on a clip that has none: the trimmed file is silent, and the job still succeeds. Read the warnings array for both codes. If you need sound, the cause is upstream, not in the trim.