How to remove black bars from a video by cropping

To remove black bars from a video, crop them off: measure how thick the bars are, then cut the frame down to the picture inside them. Bars baked into the file, at the top and bottom (letterboxing) or at the sides (pillarboxing), are part of every frame, so only a crop removes them, and the result is a smaller frame. With Sume, both steps take a clip already hosted on media.sume.com: measure the bars on a full-size still from POST /v1/video-frames, then crop with POST /v1/video-filter.

The Sume facts come from the Video frames and Video filter docs and the Sume API reference, and the crop syntax from the FFmpeg filters documentation, all read on 2026-09-27. Behavior read from Sume's code is described as it works today.

How do I measure the black bars?

Take one still from a bright scene, where the bars' edges are easy to see, and count the black rows or columns in any image editor. POST /v1/video-frames returns stills at the times you name, at the source frame size when you leave out max_edge, and it's unbilled. format: "png" gives a lossless still.

The clip must already be your workspace's media.sume.com artifact or asset, such as an earlier Sume job's output; which URLs each endpoint accepts explains the rule. The submit always answers 202: read GET /v1/video-frames/:id until resource_status is ready, and each frame carries its url, width, and height. Extract frames from a video covers the rest of the route.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bars-still-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/letterboxed.mp4",
    "at": [5],
    "format": "png"
  }'

How do I crop the black bars off?

Crop to the picture's size and position. FFmpeg's crop takes the output width, height, x, and y in that order; x and y place the top-left corner of the kept area, and the area is centered when you leave them out. For example, by our arithmetic:

• A 1920×1080 file with 140-pixel bars above and below holds a 1920×800 picture: crop=1920:800:0:140, or crop=iw:ih-2*140, which stays centered.
• A 9:16 clip with side bars in a 1920×1080 file is about 608 pixels wide: crop=608:1080:656:0.
• A 16:9 clip letterboxed in a vertical 1080×1920 file is about 608 pixels tall: crop=1080:608:0:656.
• Use even numbers: by default FFmpeg rounds a crop on subsampled video down to the nearest smaller value. If a thin dark line is left at an edge, crop two more pixels on that side.
• Sume's own crop op takes the rectangle as fractions of the frame, and today it rounds them down to even pixels, so for bars measured in pixels the filtergraph form is simpler. POST /v1/video-filter/check validates either for free before you encode.

curl -X POST https://api.sume.com/v1/video-filter \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: remove-bars-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/letterboxed.mp4",
    "filtergraph": "crop=1920:800:0:140"
  }'

Why does my video still show black bars?

If a still from the file has no bars but the video shows them when it plays, the bars aren't in the file: the player adds them because the video's shape differs from the screen's. A cropped 1920×800 picture is still wider than a 16:9 screen, so a player letterboxes it again. The only way to fill that screen without distorting the picture is to crop it to the screen's shape, which cuts off its edges, as in make a video square or make a vertical video horizontal.

Can Sume find the bars automatically?

No, you measure them. FFmpeg's cropdetect filter, which detects the non-black area, isn't on Sume's filter allowlist today, and an unknown filter fails with invalid_filtergraph. Every crop is also a re-encode that keeps fewer pixels. To resize the result in the same job, add scale with one side set to -2, which keeps the aspect ratio and an even size; change a video's frame rate or resolution covers resizing.

What are the limits?

The cropped MP4 is a new file with the source's frame rate and audio; the source stays untouched.