Skip to content
HALOWERK

Tonwerk

audio description script

Finds scene cuts with the ffmpeg scdet filter (scene_threshold on a 160 px wide copy), takes speech from caption cues when captions are supplied, otherwise detects it in the audio with Silero VAD v6.2 (or an energy detector). Pauses between speech, shortened by padding_s at both ends, become description slots when at least min_gap_s remain; each slot gets a word budget at words_per_minute (no standard rate exists; 150 wpm is a common narration pace, set your own) and the scenes it touches..

POST https://ton.halowerk.com/v1/audio-description-script

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 600; default: to the end of the video).
captionsstringNoCaptions or subtitles as SRT or WebVTT text.
captions_formatstringNoFormat of captions; auto detects WEBVTT headers, otherwise SRT.
detectorstringNoSpeech detection: silero (Silero VAD v6.2 neural voice activity detector, robust to music and noise) or energy (frame level above the noise floor; for clean recordings).
words_per_minuteintegerNoNarration pace used for word budgets.
min_gap_snumberNoShortest usable pause (after padding) that becomes a slot.
padding_snumberNoDistance kept from speech at both ends of a pause.
scene_thresholdnumberNoscdet threshold (0–100 scale); lower finds more cuts.
descriptionsarrayNoOptional description texts to place.
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": 600,
      "description": "Length of the analysed range in seconds (at most 600; default: to the end of the video)."
    },
    "captions": {
      "type": "string",
      "minLength": 10,
      "maxLength": 400000,
      "description": "Captions or subtitles as SRT or WebVTT text."
    },
    "captions_format": {
      "type": "string",
      "enum": [
        "auto",
        "srt",
        "vtt"
      ],
      "default": "auto",
      "description": "Format of captions; auto detects WEBVTT headers, otherwise SRT."
    },
    "detector": {
      "type": "string",
      "enum": [
        "silero",
        "energy"
      ],
      "default": "silero",
      "description": "Speech detection: silero (Silero VAD v6.2 neural voice activity detector, robust to music and noise) or energy (frame level above the noise floor; for clean recordings)."
    },
    "words_per_minute": {
      "type": "integer",
      "minimum": 80,
      "maximum": 250,
      "default": 150,
      "description": "Narration pace used for word budgets."
    },
    "min_gap_s": {
      "type": "number",
      "minimum": 0.5,
      "maximum": 10,
      "default": 1.2,
      "description": "Shortest usable pause (after padding) that becomes a slot."
    },
    "padding_s": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 0.2,
      "description": "Distance kept from speech at both ends of a pause."
    },
    "scene_threshold": {
      "type": "number",
      "minimum": 1,
      "maximum": 50,
      "default": 10,
      "description": "scdet threshold (0–100 scale); lower finds more cuts."
    },
    "descriptions": {
      "type": "array",
      "maxItems": 200,
      "description": "Optional description texts to place.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "at_s",
          "text"
        ],
        "properties": {
          "at_s": {
            "type": "number",
            "minimum": 0,
            "maximum": 36000
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 600
          }
        }
      }
    }
  }
}

Open original schema

Published input example

{
  "video_url": "https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif",
  "captions": "1\n00:00:00,500 --> 00:00:01,500\nHello.\n",
  "descriptions": [
    {
      "at_s": 1.8,
      "text": "The Earth turns."
    }
  ]
}

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 →