CoralBit

captionbob docs

Version 1.0.0
Contents ↓

Python: captionbob.effects

captionbob.effects.glow_reveal

Glow reveal effect: each word lights up when it is spoken, with a glow.

A caption shows a few words. Its first word shows when the caption starts, and each later word appears at the time at which it is spoken. A word that is not spoken yet is hidden but keeps its room, so no word moves when the next word appears. A word starts black: its letters, its stroke and its glow. It gets its colors in two thirds of the time in which it is spoken. Each word that is shown has a soft glow around it.

A caption is two events of the script that sit at one place: the glow, and the text over it. The effect draws nothing itself. It builds the text of an ASS script, and the ffmpeg filter ass draws the script on the video. The common part of the effects is in effect_common.py.

Source file: captionbob/effects/glow_reveal.py

Settings

The command line and the HTTP API call this effect the style glow_reveal. Its settings class is GlowRevealSettings. Each setting has the default below.

Setting Type Default Description
most_words integer 3 The most words that one caption shows.
fewest_words integer 1 The fewest words that one caption shows, when its sentence is long enough for that.
font_name string "DejaVu Sans" Name of the font of the text.
font_size integer 80 Height of the font in pixels.
bold boolean true True for bold text.
primary_color string "#FFFFFF" Color of the text, as "#RRGGBB".
stroke_color string "#000000" Color of the outline of the text, as "#RRGGBB".
stroke_width number 6.0 Width of the outline in pixels. 0 gives no outline.
bottom_position number 0.75 Where the bottom of the caption sits, as a part of the video height from the top. 0.75 is three quarters of the way down.
side_margin integer 54 Room in pixels that stays free on the left and on the right of the caption. A caption that is too wide for the room between the margins breaks into lines.
glow_color string "#68FF3A" Color of the glow, as "#RRGGBB".
glow_radius number 12.0 Size of the glow in pixels. The glow is at half of its strength at this distance from the stroke of the text, and it is gone at about two and a half times this distance. 0 gives no glow.
glow_opacity number 1.0 Strength of the glow, from 0 for no glow to 1 for the strongest glow.
hold_seconds number 0.6 The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

GlowRevealSettings

@dataclass(frozen=True)
class GlowRevealSettings(CaptionSettings)

The look and the timing of the glow reveal effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. These settings follow them. The glow reaches into the side margins.

Args:

  • glow_color: Color of the glow, as "#RRGGBB".
  • glow_radius: Size of the glow in pixels. The glow is at half of its strength at this distance from the stroke of the text, and it is gone at about two and a half times this distance. 0 gives no glow.
  • glow_opacity: Strength of the glow, from 0 for no glow to 1 for the strongest glow.
  • hold_seconds: The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

Raises:

  • TypeError: When a word count is not a whole number.
  • ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", or when the font name is empty or holds a comma.

GlowRevealSettings.has_glow

@property
def has_glow(self) -> bool

True when the settings give a glow that can be seen.

GlowRevealSettings.glow_style_line

def glow_style_line(self, margin_vertical: int) -> str

Write the ASS style line of the glow of these settings.

The glow is the same text in the glow color, with an outline that is wider than the stroke of the text by the glow radius. The event of the glow blurs this outline.

Args:

  • margin_vertical: Room in pixels between the bottom of the caption and the bottom edge of the video.

Returns:

The style line of the glow of the captions.

Raises:

  • ValueError: When the font name, the font size, the glow color, the stroke width or a margin is outside its range.

GlowRevealEffect

class GlowRevealEffect
    def __init__(self, settings: GlowRevealSettings) -> None

Builds the ASS script that lights the words up with a glow.

Args:

  • settings: The look and the timing of the effect.

GlowRevealEffect.build_ass_text

def build_ass_text(self, words: Sequence[Word], video: VideoInfo) -> str

Build the ASS script of the effect for the words of one video.

Each caption group is two events of the script with the same words and the same times: the glow on the lower layer and the text on the layer above it. Settings with no glow give only the text event. An event starts with its first word. It ends when the next caption starts, and at the latest the hold time after its last word and at the end of the video.

Args:

  • words: The words of the video in time order, each with its times.
  • video: The frame size and the duration of the video.

Returns:

The text of the ASS script. It has no event when there are no words.

Raises:

  • ValueError: When the side margins leave no room for the caption in the width of the video.