captionbob.effects.moving_highlight - captionbob docs

Moving highlight effect: a box behind the word that is spoken.

A caption shows a few words, and it shows them all from its start. A colored box is behind one word at a time. The box is behind the first word when the caption starts. It jumps to each later word at the time at which that word is spoken, and it stays behind the last word until the caption goes.

A caption is two events of the script that sit at one place: the highlight, and the text over it. The highlight event holds the same words with the same font, so libass puts each box behind its word, and this code measures no text. The letters of the highlight event are hidden, and only the box of one word is seen. The box has square corners. It is as wide as the word and as high as the text line, plus the paddings. 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, with the style line of the highlight from box_border_style_line.

Source file: captionbob/effects/moving_highlight.py

Settings

The command line and the HTTP API call this effect the style moving_highlight. Its settings class is MovingHighlightSettings. 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.
`highlight_color`	string	`"#FFFF00"`	Color of the box behind the spoken word, as "#RRGGBB".
`highlight_opacity`	number	`0.5`	Strength of the box, from 0 for no box to 1 for a box that hides the video behind it.
`highlight_side_padding`	number	`12.0`	Room in pixels between the word and the left and the right edge of its box.
`highlight_vertical_padding`	number	`6.0`	Room in pixels between the text line and the top and the bottom edge of the box. The text line is as high as the font size. libass gives a box 1 pixel of room at the least on each side, and it draws no box when the two paddings are 0.
`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.

MovingHighlightSettings

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

The look and the timing of the moving highlight 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 box of a word reaches into the side margins by its side padding.

Args:

highlight_color: Color of the box behind the spoken word, as "#RRGGBB".
highlight_opacity: Strength of the box, from 0 for no box to 1 for a box that hides the video behind it.
highlight_side_padding: Room in pixels between the word and the left and the right edge of its box.
highlight_vertical_padding: Room in pixels between the text line and the top and the bottom edge of the box. The text line is as high as the font size. libass gives a box 1 pixel of room at the least on each side, and it draws no box when the two paddings are 0.
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", when the font name is empty or holds a comma, or when the two paddings are 0.

MovingHighlightSettings.has_highlight

@property
def has_highlight(self) -> bool

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

MovingHighlightSettings.highlight_style_line

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

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

The highlight is the same text with the box border style, so libass draws a box in the highlight color behind it. The style holds the vertical padding as its outline width. The event of the highlight sets the two paddings with its tags.

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 highlight of the captions.

Raises:

ValueError: When the font name, the font size, the highlight color, the vertical padding or a margin is outside its range.

MovingHighlightEffect

class MovingHighlightEffect
    def __init__(self, settings: MovingHighlightSettings) -> None

Builds the ASS script that puts a box behind the spoken word.

Args:

settings: The look and the timing of the effect.

MovingHighlightEffect.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 highlight on the lower layer and the text on the layer above it. Settings with no highlight 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.