Skip to content
HALOWERK

Tonwerk

letterbox detect

Runs ffmpeg cropdetect (per-frame reset, rows and columns whose mean luma is at or below black_level count as black) on the keyframes of the selected range, or on evenly spaced frames when there are fewer keyframes than samples. Frames that are black as a whole are ignored; the union of the remaining picture areas is the content area, so no frame loses content. The crop is aligned to even values for 4:2:0 video, the bars are classified, and the display aspect ratio of the content (using the.

POST https://ton.halowerk.com/v1/letterbox-detect

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
video_base64stringNoThe video as base64 (MP4/MOV, WebM/MKV, AVI, MPEG-TS, MPEG-PS, FLV, Ogg or animated GIF; at most 10 MiB decoded; a data: URL prefix is accepted).
video_urlstringNoPublic http(s) URL of the the video (at most 10 MiB; private, local and reserved addresses are refused).
start_snumberNoStart of the analysed range in seconds.
duration_snumberNoLength of the analysed range in seconds (at most 3600; default: to the end of the video).
samplesintegerNoEvenly spaced frames analysed when the range has fewer keyframes than this.
black_levelintegerNoHighest mean luma (8-bit scale, 16 = video black) of a row or column that still counts as black.
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "video_base64": {
      "type": "string",
      "minLength": 16,
      "maxLength": 14000000,
      "description": "The video as base64 (MP4/MOV, WebM/MKV, AVI, MPEG-TS, MPEG-PS, FLV, Ogg or animated GIF; at most 10 MiB decoded; a data: URL prefix is accepted)."
    },
    "video_url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://",
      "maxLength": 2048,
      "description": "Public http(s) URL of the the video (at most 10 MiB; private, local and reserved addresses are refused)."
    },
    "start_s": {
      "type": "number",
      "minimum": 0,
      "maximum": 36000,
      "default": 0,
      "description": "Start of the analysed range in seconds."
    },
    "duration_s": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 3600,
      "description": "Length of the analysed range in seconds (at most 3600; default: to the end of the video)."
    },
    "samples": {
      "type": "integer",
      "minimum": 6,
      "maximum": 60,
      "default": 24,
      "description": "Evenly spaced frames analysed when the range has fewer keyframes than this."
    },
    "black_level": {
      "type": "integer",
      "minimum": 4,
      "maximum": 64,
      "default": 24,
      "description": "Highest mean luma (8-bit scale, 16 = video black) of a row or column that still counts as black."
    }
  }
}

Open original schema

Published input example

{
  "video_url": "https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif"
}

Result & documentation

Machine-readable documentation of this hub

Source of this page: the published HALOWERK catalog. Updated: 2026-11-17 UTC.

More endpoints in this hub

All endpoints in this hub โ†’