pycaps

A pycaps template is a self-contained directory used to create reusable and shareable styles. It bundles configuration, styles, and assets together. When using a template, pycaps searches for the template name in your current working directory first (as a local template) before falling back to its built-in templates.

my-awesome-template/
├── pycaps.template.json  # Main configuration for the pipeline
├── style.css             # All CSS styles for the subtitles
└── resources/            # Optional folder for assets
    └── my-font.ttf

A single Word is split into multiple WordClip objects to allow for dynamic visual changes as a word is spoken. This enables developers to use CSS to style different states of the same word.

Common states include:

1. "Not Narrated Yet": The clip visible before the word is spoken.
2. "Being Narrated": The clip active from word.time.start to word.time.end.
3. "Already Narrated": The clip that remains on screen after the word has been spoken.

Example CSS Application: You can target these states using specific classes (e.g., .word-being-narrated) to change colors or scale during narration.

The upper levels of the hierarchy manage the organization and layout of the transcription:

• Document: The top-level container representing the entire video's transcribed content. It contains a list of Segment objects and global elements like sound effects (sfxs).
• Segment: A logical unit of speech (e.g., a sentence or phrase). Segments are provided by Whisper and can be further subdivided using Splitters.
• Line: A single line of text as it appears on screen. Segments are broken into Line objects by a LineSplitter using layout rules such as max_width_ratio and max_number_of_lines.

The pycaps data model is organized in a strict hierarchy that flows from the entire video down to individual visual states of a word. Understanding this hierarchy is essential for manipulating transcription data, applying semantic tags, or customizing visual styles.

The hierarchy follows this path: Document $\rightarrow$ Segment $\rightarrow$ Line $\rightarrow$ Word $\rightarrow$ WordClip

When an AI-dependent feature is triggered, pycaps searches for credentials in the following order of precedence:

1. Pycaps API Key: The key configured via the pycaps config --set-api-key command.
2. OpenAI API Key: The value stored in the PYCAPS_OPENAI_API_KEY environment variable.

If neither is found, AI-dependent features will be disabled and a warning will be logged.

Semantic tags are applied based on the content or meaning of words. You define these rules using tagger_rules in a JSON configuration or via the SemanticTagger in Python.

There are three rule types available:

1. wordlist: Tags a word if it appears in a specified list of words.
2. regex: Tags words that match a regular expression pattern.
3. ai: Uses an LLM to tag words based on a natural language prompt (e.g., "words related to finance"). Note: This requires an API Key.

The lower levels of the hierarchy manage granular text and its visual rendering:

• Word: The most granular text element. It contains the text and the start/end timestamps. This is the primary target for applying semantic_tags (e.g., highlight) and structure_tags (e.g., first-word-in-line).
• WordClip: The actual renderable element. A single Word is represented by multiple WordClip objects, each corresponding to a different visual state over time. This separation allows for distinct CSS styling and animations for different temporal states of a word.

Tags are the core mechanism in pycaps for applying conditional styling and logic. They act as dynamic CSS classes attached to words, lines, and segments.

Tags serve two primary purposes:

1. Styling: Target elements in CSS (e.g., .word.highlight { color: yellow; }).
2. Logic: Trigger animations or effects based on whether an element has (or lacks) a specific tag.

There are two categories of tags: Structure Tags (automatic) and Semantic Tags (user-defined).

If you already have a transcription file (e.g., .srt or .vtt), you can skip the automatic transcription step.

CLI usage:

pycaps render --input my_video.mp4 --template minimalist --transcript transcript.srt

Python usage: Use .with_transcription_file() and specify the TranscriptFormat.

from pycaps import CapsPipelineBuilder, TranscriptFormat

pipeline = (
    CapsPipelineBuilder()
    .with_input_video("my_video.mp4")
    .with_transcription_file("transcript.vtt", TranscriptFormat.VTT)
    .add_css("styles.css")
    .build()
)

pipeline.run()

Note: You can also pass a dictionary or a Document object directly using .with_transcription(...).

After creating a template directory, you can customize it by modifying its contents:

1. style.css: Update fonts, colors, sizes, and backgrounds.
2. resources/: Add custom fonts or images and reference them in your CSS.
3. pycaps.template.json: Modify animations, effects, layout, and other pipeline settings. Note that paths for css and resources inside this JSON file should be relative to the file itself.

You can create a new template by scaffolding an existing one (defaulting to the default built-in template) using the template create command. This generates a new directory containing a working pycaps.template.json and style.css.

# Creates a new folder named 'my-new-style' in the current directory
pycaps template create --name my-new-style

You can perform a quick render by providing a config.json file that defines input/output, CSS, layout, and animations.

CLI usage:

pycaps render --config config.json

Python usage: Use JsonConfigLoader to load the configuration and run the resulting pipeline.

from pycaps import JsonConfigLoader

loader = JsonConfigLoader("config.json")
# Use loader.load(False) if you need to access the builder object directly
pipeline = loader.load()
pipeline.run()

{
  "input": "video.mp4",
  "output": "video_with_subs.mp4",
  "css": "styles.css",
  "layout": {
    "max_number_of_lines": 2
  },
  "animations": [
    {
      "type": "fade_in",
      "when": "narration-starts",
      "what": "segment",
      "duration": 0.3
    }
  ]
}