captionbob.effects.keyword_float - captionbob docs

Keyword float effect: a caption floats, and its keywords stand out.

A caption shows a few words. All its words show together from the time at which the first word is spoken. While the caption shows, it floats to the left and up. It moves fast at the start and slower at the end. The float to the left is even around the middle of the video: the caption starts half of the float to the right of the middle and ends half of it to the left.

A keyword picker names the keywords of each caption. A keyword has its own font, size and color, and a soft glow around it.

A caption is two rows of events of the script that sit at one place: the glow of the keywords, 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/keyword_float.py

Settings

The command line and the HTTP API call this effect the style keyword_float. Its settings class is KeywordFloatSettings. 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.
`float_left`	number	`0.05`	How far a caption floats to the left, as a part of the video width. The caption starts half of this distance to the right of the middle and ends half of it to the left. 0 gives no float to the left.
`float_up`	number	`0.05`	How far a caption floats up from its bottom position, as a part of the video height. It must be below the bottom position. 0 gives no float up.
`keyword_font_name`	string	`"DejaVu Sans"`	Name of the font of a keyword.
`keyword_font_size`	integer	`110`	Height of the font of a keyword in pixels.
`keyword_italic`	boolean	`true`	True for a keyword in italic letters.
`keyword_color`	string	`"#FFE434"`	Color of a keyword, as "#RRGGBB".
`keyword_glow_color`	string	`"#FF0808"`	Color of the glow of a keyword, as "#RRGGBB".
`keyword_glow_radius`	number	`6.0`	Size of the glow in pixels. The glow is at half of its strength at this distance from the stroke of the keyword. 0 gives no glow.
`keyword_glow_opacity`	number	`0.5`	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.

KeywordFloatSettings

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

The look and the timing of the keyword float 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. In this effect, bold holds for the keywords too, and the keywords have the stroke color and the stroke width of the text. The bottom position is the place of a caption when it starts, and the side margins are those of a caption that sits in the middle.

Args:

float_left: How far a caption floats to the left, as a part of the video width. The caption starts half of this distance to the right of the middle and ends half of it to the left. 0 gives no float to the left.
float_up: How far a caption floats up from its bottom position, as a part of the video height. It must be below the bottom position. 0 gives no float up.
keyword_font_name: Name of the font of a keyword.
keyword_font_size: Height of the font of a keyword in pixels.
keyword_italic: True for a keyword in italic letters.
keyword_color: Color of a keyword, as "#RRGGBB".
keyword_glow_color: Color of the glow of a keyword, as "#RRGGBB".
keyword_glow_radius: Size of the glow in pixels. The glow is at half of its strength at this distance from the stroke of the keyword. 0 gives no glow.
keyword_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 a font name is empty or holds a comma.

KeywordFloatSettings.has_glow

@property
def has_glow(self) -> bool

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

KeywordFloatSettings.has_float

@property
def has_float(self) -> bool

True when a caption moves while it shows.

KeywordFloatSettings.keyword_style_line

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

Write the ASS style line of a keyword of these settings.

Args:

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

Returns:

The style line of a keyword: its font, its size and its color, with the stroke of the text.

Raises:

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

KeywordFloatSettings.keyword_glow_style_line

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

Write the ASS style line of the glow of a keyword.

The glow is the keyword in the glow color, with an outline that is wider than the stroke 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 a keyword.

Raises:

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

KeywordFloatEffect

class KeywordFloatEffect
    def __init__(
            self, settings: KeywordFloatSettings,
            keyword_picker: KeywordPicker = longest_word_keywords) -> None

Builds the ASS script that floats the captions with their keywords.

Args:

settings: The look and the timing of the effect.
keyword_picker: Names the keywords of each caption. With no value, the keyword of a caption is its longest word.

KeywordFloatEffect.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 shows from the start of 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. This time is cut into events that follow one another, and each event is one straight move of the caption. A caption with a keyword has the same events one more time on the layer below, for the glow of the keyword.

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, when the float to the left is so wide that a caption can leave the video, or when the keyword picker gives a place that is not a word of the caption.