voice/narrate

Standalone narration workflow — generate audio from text or a topic.

Category: voice
Source: workflows/voice/narrate.py

Input Schema

Field	Type	Default	Description
duration_secs	integer	60	Target duration in seconds
language	string	"en"	Language for script and voice
mood	string	"conversational"	Tone for narration
narration_text	object	—	Text to narrate (provide this OR topic)
regenerate	object	—	When set, this run is a regeneration. Workflows may read direction / keep / extra_instructions to modulate prompts; the engine persists parent_run_id and parent_variant_index as run lineage columns.
script	object	—	Script dict with full_narration key (populated by prepare_narration)
topic	object	—	Topic to generate narration from (provide this OR narration_text)
tts_model	object	—	TTS model override
variants	integer	1	Number of independent variant executions (1–10). When > 1, the engine runs the workflow N times with different sampling, producing N outputs.
voice_gender	object	—	“male” or “female”
voice_id	object	—	Explicit voice ID override
voice_style	object	—	Voice style preset (e.g. “narrator”, “warm”, “energetic-male”)

Output Schema

No schema defined.

Task Pipeline

prepare_narration → generate_narration_script → generate_narration_audio → collect_narration_output

Task	Description
prepare_narration	Validate input and set up for narration.
generate_narration_script	Generate narration text from a topic using a simple LLM call.
generate_narration_audio	Generate TTS audio — delegates to the SDK voiceover stage.
collect_narration_output	Surface the key output fields for easy consumption.

Run-spec example

Save the YAML below as my-run.yaml, edit the values, and run with the CLI or POST it to the API. Required fields are uncommented; optional knobs are documented above the input: block — copy any line under input: and uncomment to set.

workflow: voice/narrate

# Optional fields — copy any line(s) under `input:` and uncomment to set:
# Target duration in seconds
#   duration_secs: 60
#
# Language for script and voice
#   language: en
#
# Tone for narration
#   mood: conversational
#
# Text to narrate (provide this OR topic)
#   narration_text: null
#
# Script dict with full_narration key (populated by prepare_narration)
#   script: null
#
# Topic to generate narration from (provide this OR narration_text)
#   topic: null
#
# TTS model override
#   tts_model: null
#
# "male" or "female"
#   voice_gender: null
#
# Explicit voice ID override
#   voice_id: null
#
# Voice style preset (e.g. "narrator", "warm", "energetic-male")
#   voice_style: null
#

input: {}

Run it locally:

fab-workflow --from-file my-run.yaml

Or submit over the wire — the same file is the request body:

curl -X POST 'https://gofabric.dev/v1/workflows/runs?name=voice/narrate' \
  -H 'Authorization: Bearer fab_xxx' \
  -H 'content-type: application/yaml' \
  --data-binary @my-run.yaml

Every workflow also accepts the universal WorkflowInput fields — variants (1–10 fan-out) and regenerate (creative-direction hints with run lineage). See Run-specs (YAML / TOML / JSON) for the full top-level shape (metadata, priority, bundle, parent, etc.).

Warnings

• Last user task collect_narration_output has no Pydantic return type — workflow output schema is null. Declare a WorkflowOutput subclass and pass it to Flow(output=…) for a strict contract.
• Task generate_narration_audio has no Pydantic types — contract is opaque to consumers.