captionbob.effects.word_hopping_emoji_push - captionbob docs

Word hopping emoji push effect: each word of a caption is pushed down in its turn, and an emoji goes from word to word above them.

A caption shows a few words. All its words show together from the time at which the first word is spoken. libass breaks a caption that is too wide for the room between the side margins into more rows. The time of a caption is cut into even parts, one part for each word, in the order of the words. In the first half of the part of a word, the word moves down by the push distance at one speed. In the second half it moves back up. The other words stay in their places.

One emoji image stands above the words, with a gap between the emoji and the top of the row of a word. Its side is a part of the smaller side of the video. In the part of a word, the middle of the emoji moves at one speed from above the middle of the word to above the middle of the next word. Its start place goes down and up with the word, so the emoji dips while it leaves the word. In the part of the last word, the emoji stays above that word and goes down and up with it. An animated emoji plays from its first frame at the start of each caption. A caption that is shorter than one centisecond for each word gives some words a part with no time. Such a word is not pushed, and the emoji does not stop above it.

The text is an ASS script, which the ffmpeg filter ass draws. ASS moves only a whole event. So each caption is one event in which the word of a part is hidden in its part and keeps its room. The word that moves has one event for each half of its part. Such an event holds the whole caption with the other words hidden, so libass puts the word at its place in the caption. ASS cannot draw an image, so the effect also gives one emoji layer for each caption, and the ffmpeg filter overlay draws it under the text. The emoji image is not a setting of the look: build_layers takes it with the words, and build_ass_text needs no image. The breaks of a caption and the columns of its words come from the caption measure. The common part of the effects, with the way of the emoji from word to word, is in effect_common.py.

Source file: captionbob/effects/word_hopping_emoji_push.py

Settings

The command line and the HTTP API call this effect the style word_hopping_emoji_push. Its settings class is WordHoppingEmojiPushSettings. 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.
`emoji_size_part`	number	`0.1`	The side of the emoji as a part of the smaller side of the video, above 0.
`emoji_gap`	number	`5.0`	Room in pixels between the emoji and the top of the row of a word.
`push_distance`	number	`15.0`	How far a word goes down in the middle of its part, in pixels. 0 gives words that stay in their places.
`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.

WordHoppingEmojiPushLayer

class WordHoppingEmojiPushLayer(NamedTuple)

The emoji above one caption, as the ffmpeg filters draw it.

The emoji is a square of one size. An edge of the emoji is a line between two columns or two rows of pixels.

Args:

image_path: The emoji image. An animated image plays from its first frame at the start of the caption.
start_seconds: Time at which the caption starts.
end_seconds: Time at which the caption ends.
full_size: The side of the emoji in pixels.
hops: The part of each word that has time, in the order of the words. The parts follow one another from the start of the caption to its end.
push_distance: How far a word goes down in the middle of its part, in pixels.

WordHoppingEmojiPushLayer.size_expression

def size_expression(self) -> str

Write the side of the emoji as ffmpeg reads it.

Returns:

An ffmpeg expression of a whole number of pixels, 1 or above.

WordHoppingEmojiPushLayer.left_expression

def left_expression(self) -> str

Write the left column of the emoji as the overlay filter reads it.

The middle of the emoji moves from the middle of a word to the middle of the next word in the part of the word.

Returns:

An ffmpeg expression of the time t and the width w of the emoji frame.

WordHoppingEmojiPushLayer.top_expression

def top_expression(self) -> str

Write the top row of the emoji as the overlay filter reads it.

A row lower on the video has a higher number, so the push adds to the row.

Returns:

An ffmpeg expression of the time t and the height h of the emoji frame.

WordHoppingEmojiPushLayers

class WordHoppingEmojiPushLayers(NamedTuple)

What the effect gives for the words of one video.

Args:

ass_text: The text of the ASS script.
emojis: One emoji layer for each caption, in time order.

WordHoppingEmojiPushSettings

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

The look and the timing of the word hopping emoji push effect.

The settings of CaptionSettings come first, with their defaults: the word counts, the font, the colors, the stroke, the bottom position and the side margin. These settings follow them.

Args:

emoji_size_part: The side of the emoji as a part of the smaller side of the video, above 0.
emoji_gap: Room in pixels between the emoji and the top of the row of a word.
push_distance: How far a word goes down in the middle of its part, in pixels. 0 gives words that stay in their places.
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.

caption_word_tags

def caption_word_tags(slot: tuple[int, int], start: int, end: int) -> str

Write the tags of one word in the event of its caption.

The word is hidden in its part and keeps its room, because the event of the word that moves shows it then. Each word names its transparency, so no word takes the transparency of the word in front of it.

Args:

slot: The start and the end of the part of the word, in centiseconds.
start: Time at which the caption starts, in centiseconds.
end: Time at which the caption ends, in centiseconds.

Returns:

The tags with no curly brackets.

WordHoppingEmojiPushEffect

class WordHoppingEmojiPushEffect
    def __init__(
            self, settings: WordHoppingEmojiPushSettings,
            caption_measure: CaptionMeasure) -> None

Builds the ASS script and the emoji layers of the word hopping emoji push effect.

Args:

settings: The look and the timing of the effect.
caption_measure: The measure that says where libass draws each word of a caption. It must use the ffmpeg that draws the video.

WordHoppingEmojiPushEffect.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.

The script is the text of the effect with no emoji. It is the script that build_layers gives.

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, or when libass draws no pixel for a word.
RuntimeError: When the ffmpeg of the caption measure fails.

WordHoppingEmojiPushEffect.build_layers

def build_layers(
        self, words: Sequence[Word], video: VideoInfo,
        emoji_path: Path) -> WordHoppingEmojiPushLayers

Build the ASS script and the emoji layers for one video.

A caption shows from 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.
emoji_path: The emoji image, such as an animated GIF or a PNG with a see-through background. The effect does not read the image. ffmpeg reads it when it draws the layers.

Returns:

The script and one emoji layer for each caption that has time on the screen.

Raises:

TypeError: When the emoji path is not a Path.
FileNotFoundError: When the emoji image is not a file.
ValueError: When the side margins leave no room for the caption in the width of the video, or when libass draws no pixel for a word.
RuntimeError: When the ffmpeg of the caption measure fails.