Is it possible to generate subtitles/captions along with audio output?

[sayyedshah]

Hi

After generating audio files I am overlaying audio onto a different video using capcut and it can auto generate captions. However, the generated captions in capcut are not very good. Is it possible to auto generate Captions/subtitles file along side audio file generated from Kokoro-FastAPI using the original input text?

Thank you in advance.

[michael-chipmates]

Yes, you can get this straight from Kokoro-FastAPI, no CapCut needed. There's a captioned-speech endpoint that returns word-level timestamps aligned to your original input text, so you skip the auto-caption STT step (and its mistakes) entirely.

Use POST /dev/captioned_speech instead of /v1/audio/speech:

import base64, requests

text = "Hello world! Welcome to the captioned speech system."

r = requests.post(
    "http://localhost:8880/dev/captioned_speech",
    json={
        "model": "kokoro",
        "input": text,
        "voice": "af_heart",
        "speed": 1.0,
        "response_format": "mp3",
        "stream": False,
    },
)
data = r.json()
audio_bytes = base64.b64decode(data["audio"])   # the mp3
words = data["timestamps"]                       # [{"word","start_time","end_time"}, ...]

with open("out.mp3", "wb") as f:
    f.write(audio_bytes)

Each entry in timestamps is {"word": str, "start_time": float, "end_time": float}, times in seconds. Because the words and timing come straight from the synthesis and not a second STT pass over the audio, the captions line up with what was actually spoken, which is the part CapCut's auto-captions get wrong.

Turning that into an SRT is a small loop. Group a handful of words per cue, take the start from the first word and the end from the last:

def to_srt(words, words_per_cue=7):
    def ts(t):  # seconds -> "HH:MM:SS,mmm"
        total = int(round(t * 1000))
        h, total = divmod(total, 3600000)
        m, total = divmod(total, 60000)
        s, ms = divmod(total, 1000)
        return f"{h:02}:{m:02}:{s:02},{ms:03}"
    out = []
    for i in range(0, len(words), words_per_cue):
        cue = words[i:i + words_per_cue]
        out += [str(i // words_per_cue + 1),
                f"{ts(cue[0]['start_time'])} --> {ts(cue[-1]['end_time'])}",
                " ".join(w["word"] for w in cue), ""]
    return "\n".join(out)

open("out.srt", "w").write(to_srt(words))

That out.srt imports straight into CapCut as a subtitle track. For WebVTT it's the same idea, just start the file with WEBVTT and use a period before the milliseconds (00:00:00.000) instead of a comma.

One gotcha: the API normalizes your input text before synthesis, which can quietly drop or rewrite a few phrases in the timestamps JSON (the audio stays fine). There's an open bug (#249) where a --- run triggers it. The clean fix is to turn normalization off for that request by adding "normalization_options": {"normalize": false} to the JSON, or just strip oddities like --- before sending. There's a full reference version in the repo at examples/captioned_speech_example.py.