generate.subtitles

Operation: generate.subtitles
Category: media
Tags: subtitles, text, video

Generate TikTok-style ASS subtitles from narration text

Runtime

Type: Native (built-in)
Timeout: 300s
Retries: 3 (ExponentialWithJitter)

Inputs

Name	Type	Required	Default	Description
narration_text	String	Yes	—	Full narration text
audio_duration_secs	Number	No	25.0	Audio duration in seconds
words	JSON	No	—	Array of {start, end, word} word-level timestamps from audio.transcribe

Outputs

Name	Type	Description
url	Asset	ASS subtitle file URL
path	String	Local ASS file path
srt_url	Asset	SRT subtitle file URL (when output_formats includes srt)
srt_path	String	Local SRT file path (when output_formats includes srt)
word_count	Number	Number of words

Default Configuration

{
  "font_name": "Arial Black",
  "font_size": 90,
  "max_words": 2,
  "resolution_x": 1080,
  "resolution_y": 1920,
  "color": "#FFFFFF",
  "position": "lower-third",
  "output_formats": ["ass"]
}

Styling Parameters

Caption styling can be customized per-run via workflow input variables:

Parameter	Type	Default	Description
color	String	"#FFFFFF"	Caption text color (hex)
font_name	String	"Arial Black"	Font family
font_size	Number	90	Font size in pixels
position	String	"lower-third"	Caption placement: lower-third, center, top
output_formats	List	["ass"]	Subtitle formats to generate: ass (burned-in), srt (sidecar for platform upload)

Dual Format Output

When output_formats includes both ass and srt, the node generates two subtitle files from the same word-level timestamps. ASS is used for burned-in captions via ffmpeg.composite, while SRT can be uploaded as a sidecar file for platform-native captions (toggleable, translatable). This adds zero cost — both formats are pure text serialization of the same Whisper timestamps.

SDK Stage (v0.2.0)

The subtitle generation is also available as an SDK stage for direct use in Python workflows:

from fabric_workflow_sdk.stages.captions import generate_subtitles

result = await generate_subtitles({
    "transcript": [...],           # from transcribe_audio()
    "caption_color": "#FFDD00",    # highlight color
    "caption_font": "Arial",
    "caption_size": 72,
    "caption_position": "lower_third",
    "words_per_group": 4,
})
# result["ass_path"] — ASS file for burning
# result["srt_path"] — SRT file for sidecar upload

Fully Local Pipeline (Candle Backend)

For zero-dependency subtitle generation, use the built-in Candle Whisper backend for transcription. The word-level timestamps it produces are directly consumed by generate.subtitles:

from fabric_workflow_sdk.stages.captions import transcribe_audio, generate_subtitles

# Step 1: Transcribe with built-in Candle Whisper (no Python deps)
transcribed = await transcribe_audio({
    "voiceover_path": "audio.mp3",
    "transcription_backend": "candle",
})

# Step 2: Generate subtitles — same API regardless of backend
subtitled = await generate_subtitles({
    **transcribed,
    "caption_color": "#FFDD00",
    "caption_position": "lower_third",
})

See audio.transcribe for backend comparison and configuration details.

Usage

TypeScript

import { WorkflowBuilder } from "@fabric-platform/sdk";

const workflow = new WorkflowBuilder("my-workflow")
  .node("generate-subtitles", "tool", (n) =>
    n.config({
      operation: "generate.subtitles",
      // ... node-specific config
    })
  )
  .build();

Python

from fabric_platform import FabricClient

fabric = FabricClient(api_key="fab_xxx")

wf_id = fabric.upsert_workflow("my-workflow", nodes=[
    {
        "key": "generate-subtitles",
        "kind": "tool",
    },
])

Rust

use fabric_sdk::FabricClient;

let client = FabricClient::new("https://gofabric.dev", api_key)?;

let wf_id = client.upsert_workflow("my-workflow", serde_json::json!({
    "nodes": [{
        "key": "generate-subtitles",
        "kind": "tool"
    }]
})).await?;

curl

curl -X POST https://gofabric.dev/v1/workflow-definitions \
  -H "Authorization: Bearer $FABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-workflow",
    "nodes": [{
      "key": "generate-subtitles",
      "kind": "tool"
    }]
  }'