Skip to content
HALOWERK

Tonwerk

burned subtitle extract

Crops the subtitle band (band_top to band_bottom of the frame height) and samples it at sample_fps. A text mask keeps bright pixels that have a dark neighbour within 2 px (outline or shadow; the reverse for dark text). A cue is a run of samples with a mask present whose consecutive masks overlap (IoU at least 0.5); runs shorter than min_cue_s are dropped. The middle sample of each run is re-extracted at up to 1600 px width, binarised with the same rule (black text on white) and read with.

POST https://ton.halowerk.com/v1/burned-subtitle-extract

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 180; default: to the end of the video).
band_topnumberNoTop of the subtitle band as a fraction of the frame height.
band_bottomnumberNoBottom of the subtitle band as a fraction of the frame height.
text_colorstringNolight: white or yellow captions with dark outline or shadow; dark: dark captions on a light background.
languagestringNoTesseract language data: English, German or both.
sample_fpsnumberNoSamples of the band per second (time resolution).
min_cue_snumberNoShortest caption duration kept.
min_confidenceintegerNoMinimum mean Tesseract confidence (0–100) of a caption line.
max_cuesintegerNoMaximum number of captions read per call.
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": 180,
      "description": "Length of the analysed range in seconds (at most 180; default: to the end of the video)."
    },
    "band_top": {
      "type": "number",
      "minimum": 0,
      "maximum": 0.95,
      "default": 0.7,
      "description": "Top of the subtitle band as a fraction of the frame height."
    },
    "band_bottom": {
      "type": "number",
      "minimum": 0.05,
      "maximum": 1,
      "default": 1,
      "description": "Bottom of the subtitle band as a fraction of the frame height."
    },
    "text_color": {
      "type": "string",
      "enum": [
        "light",
        "dark"
      ],
      "default": "light",
      "description": "light: white or yellow captions with dark outline or shadow; dark: dark captions on a light background."
    },
    "language": {
      "type": "string",
      "enum": [
        "eng",
        "deu",
        "deu+eng"
      ],
      "default": "eng",
      "description": "Tesseract language data: English, German or both."
    },
    "sample_fps": {
      "type": "number",
      "minimum": 2,
      "maximum": 8,
      "default": 4,
      "description": "Samples of the band per second (time resolution)."
    },
    "min_cue_s": {
      "type": "number",
      "minimum": 0.2,
      "maximum": 5,
      "default": 0.4,
      "description": "Shortest caption duration kept."
    },
    "min_confidence": {
      "type": "integer",
      "minimum": 0,
      "maximum": 95,
      "default": 50,
      "description": "Minimum mean Tesseract confidence (0–100) of a caption line."
    },
    "max_cues": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60,
      "default": 40,
      "description": "Maximum number of captions read per call."
    }
  }
}

Open original schema

Published input example

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

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 →