captionbob.effects.word_by_word

Word by word effect: the words of a caption appear one after the other.

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.

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/word_by_word.py

Settings

The command line and the HTTP API call this effect the style word_by_word. Its settings class is WordByWordSettings. 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.
`fade_seconds`	number	`0.1`	Time in which a caption fades in, and in which it fades out. 0 gives no fade.
`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.

WordByWordSettings

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

The look and the timing of the word by word 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.

Args:

fade_seconds: Time in which a caption fades in, and in which it fades out. 0 gives no fade.
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.

WordByWordEffect

class WordByWordEffect
    def __init__(self, settings: WordByWordSettings) -> None

Builds the ASS script that shows the captions word by word.

Args:

settings: The look and the timing of the effect.

WordByWordEffect.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 one event of the script. 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.