Timestamps & captions

The CLI can call Typecast Timestamp TTS and save alignment data alongside the generated audio. Use this when an agent needs subtitles for Shorts, caption timing for social video, karaoke-style highlights, or lip-sync metadata.

Generate subtitles

# Save audio and SRT subtitles
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.srt

# Save audio and WebVTT subtitles
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.vtt \
  --timestamp-format vtt

When --timestamp-format is omitted, CLI infers srt or vtt from the --timestamp-out extension and falls back to json.

Save raw timestamp JSON

cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.timestamps.json

JSON is useful when another tool will create captions, animate text, or align visuals manually.

Choose granularity

cast "Hello, world." \
  --out hello.wav \
  --timestamp-out hello.srt \
  --timestamp-granularity both

For languages without whitespace between words, such as Japanese (jpn) or Chinese (zho), use character-level timestamps for usable subtitle timing:

cast "こんにちは。世界。" \
  --language jpn \
  --out hello.wav \
  --timestamp-out hello.srt

Caption workflow for agents

Create narration audio and captions from script.txt.
Use the CLI.
Write audio to ./video/voiceover.wav.
Write subtitles to ./video/voiceover.srt.
Keep the subtitle file next to the audio file.

Output choices

Control silence duration

Use --remove-silence-ms with Cast v1.0.10 or later. The default is unset, not 0.

cast "Hello. Thank you for listening." --voice-id tc_672c5f5ce59fac2a48faeaee --remove-silence-ms 300

remove_silence_ms specifies the silence duration to retain, not the amount to remove. Use an integer from 0 to 1000 ms. 0 removes detected silence; omission or null disables duration-based silence removal.

Standard, streaming, and timestamp TTS use output.remove_silence_ms; Compose uses segments[].output.remove_silence_ms on each tts segment. Returned timestamps align with the processed audio, and explicit pause segments are preserved.

Streaming's default leading-silence trimming is separate. Small values such as 0 can leave gaps between playable chunks; allow sufficient playback buffering and test with your content.