Skip to content
HALOWERK

Tonwerk

audio only version

Synthesises each text description with the flite speech synthesiser built into ffmpeg 6.1 (libflite, CMU Flite, BSD-style licence; voices slt, rms, awb, kal16, kal; English only) or decodes a supplied description clip (any language, at most 20 clips). In duck mode every description starts at at_s (or right after the previous one) and the soundtrack is lowered by duck_db while it plays; in extend mode the soundtrack pauses at at_s for the length of the description plus 0.2 s (extended audio.

POST https://ton.halowerk.com/v1/audio-only-version

Inputs

Fields of the published input schema
FieldTypeRequiredDescription
media_base64stringNoThe video or audio file 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).
media_urlstringNoPublic http(s) URL of the the video or audio file (at most 10 MiB; private, local and reserved addresses are refused).
descriptionsarrayYesDescriptions to add, each with text (English, synthesised) or audio_base64 (recorded clip, at most 1 MiB).
modestringNoduck: mix over the lowered soundtrack; extend: pause the soundtrack for each description.
voicestringNoflite voice for text descriptions.
duck_dbnumberNoLevel reduction of the soundtrack while a description plays (duck mode).
description_gain_dbnumberNoLevel change of the descriptions.
formatstringNoOutput format.
bitrate_kbpsintegerNoBit rate for MP3 and Opus.
check_speechbooleanNoIn duck mode, report descriptions that overlap detected speech.
Show full input schema
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "descriptions"
  ],
  "properties": {
    "media_base64": {
      "type": "string",
      "minLength": 16,
      "maxLength": 14000000,
      "description": "The video or audio file 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)."
    },
    "media_url": {
      "type": "string",
      "format": "uri",
      "pattern": "^https?://",
      "maxLength": 2048,
      "description": "Public http(s) URL of the the video or audio file (at most 10 MiB; private, local and reserved addresses are refused)."
    },
    "descriptions": {
      "type": "array",
      "minItems": 1,
      "maxItems": 60,
      "description": "Descriptions to add, each with text (English, synthesised) or audio_base64 (recorded clip, at most 1 MiB).",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "at_s"
        ],
        "properties": {
          "at_s": {
            "type": "number",
            "minimum": 0,
            "maximum": 36000
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 600
          },
          "audio_base64": {
            "type": "string",
            "minLength": 16,
            "maxLength": 1400000
          }
        }
      }
    },
    "mode": {
      "type": "string",
      "enum": [
        "duck",
        "extend"
      ],
      "default": "duck",
      "description": "duck: mix over the lowered soundtrack; extend: pause the soundtrack for each description."
    },
    "voice": {
      "type": "string",
      "enum": [
        "slt",
        "rms",
        "awb",
        "kal16",
        "kal"
      ],
      "default": "slt",
      "description": "flite voice for text descriptions."
    },
    "duck_db": {
      "type": "number",
      "minimum": 0,
      "maximum": 30,
      "default": 12,
      "description": "Level reduction of the soundtrack while a description plays (duck mode)."
    },
    "description_gain_db": {
      "type": "number",
      "minimum": -12,
      "maximum": 12,
      "default": 0,
      "description": "Level change of the descriptions."
    },
    "format": {
      "type": "string",
      "enum": [
        "mp3",
        "opus",
        "wav"
      ],
      "default": "mp3",
      "description": "Output format."
    },
    "bitrate_kbps": {
      "type": "integer",
      "minimum": 32,
      "maximum": 192,
      "default": 96,
      "description": "Bit rate for MP3 and Opus."
    },
    "check_speech": {
      "type": "boolean",
      "default": true,
      "description": "In duck mode, report descriptions that overlap detected speech."
    }
  }
}

Open original schema

Published input example

{
  "media_url": "https://upload.wikimedia.org/wikipedia/commons/2/2c/Rotating_earth_%28large%29.gif",
  "descriptions": [
    {
      "at_s": 0.5,
      "text": "The Earth turns slowly in space."
    }
  ],
  "mode": "extend",
  "bitrate_kbps": 32
}

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 โ†’