captionbob.effects.bouncy_emoji - captionbob docs

Bouncy emoji effect: a caption grows into place under an emoji.

A caption shows a few words, in lines of a few words each. All its words show together from the time at which the first word is spoken. The caption starts smaller and grows in a straight line to its full size around its own middle. Every second line is turned by a few degrees. The first word of each caption takes the next color of a cycle of three colors, and the other words have the primary color. One emoji image stands above the middle of the caption. Its width is a part of the width of the caption, and it grows with the caption. An animated emoji plays from its first frame at the start of each caption.

The text is an ASS script, which the ffmpeg filter ass draws. 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 width of a caption comes from the caption measure, which also says when libass breaks a line that is too wide into two rows. The common part of the effects is in effect_common.py.

Source file: captionbob/effects/bouncy_emoji.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`6`	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	`"#FF1911"`	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.
`words_per_line`	integer	`3`	The words of one line of a caption.
`secondary_color`	string	`"#FFE434"`	The color of the first word of every caption whose number in the cycle of three is 2, as "#RRGGBB". The first word of the first caption has the primary color.
`tertiary_color`	string	`"#FF1911"`	The color of the first word of every caption whose number in the cycle of three is 3, as "#RRGGBB".
`tilt_degrees`	number	`5.0`	The angle by which every second line is turned, to the left for an angle above 0. 0 turns no line.
`start_scale`	number	`0.8`	The size of a caption at its start, as a part of its full size, above 0.
`grow_seconds`	number	`0.5`	Time in which a caption grows to its full size. A caption grows in half of its time at most. 0 gives no growth.
`emoji_width_part`	number	`0.2`	The width of the emoji as a part of the width of the widest line of the caption, above 0.
`emoji_gap`	number	`20.0`	Room in pixels between the emoji and the top of the caption at the full size. It grows with the caption.
`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.

EmojiLayer

class EmojiLayer(NamedTuple)

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

The emoji is a square. It starts at the start scale of its full size and grows in a straight line to its full size in the grow time, in step with its caption. Its bottom stays the gap above the top of the caption, so it rises while the caption grows.

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.
grow_seconds: Time in which the caption grows. 0 gives no growth.
start_scale: The size of the caption at its start, as a part of its full size.
full_size: The side of the emoji in pixels at the full size.
middle_x: The column of the middle of the caption.
middle_y: The row of the middle of the caption.
lift: How far the bottom of the emoji is above the middle of the caption at the full size, in pixels: half of the caption height and the gap.

EmojiLayer.scale_expression

def scale_expression(self) -> str

Write the size of the caption at the time t as ffmpeg reads it.

Returns:

An ffmpeg expression of the time t of a frame, in seconds of the video. It is the start scale at the start of the caption and 1 from the end of the grow time on.

EmojiLayer.size_expression

def size_expression(self) -> str

Write the side of the emoji at the time t as ffmpeg reads it.

Returns:

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

EmojiLayer.left_expression

def left_expression(self) -> str

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

Returns:

An ffmpeg expression with the width w of the emoji frame.

EmojiLayer.top_expression

def top_expression(self) -> str

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

Returns:

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

BouncyEmojiLayers

class BouncyEmojiLayers(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.

BouncyEmojiSettings

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

The look and the timing of the bouncy emoji effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. This effect shows up to 6 words, and its primary color is red. These settings follow them.

Args:

words_per_line: The words of one line of a caption.
secondary_color: The color of the first word of every caption whose number in the cycle of three is 2, as "#RRGGBB". The first word of the first caption has the primary color.
tertiary_color: The color of the first word of every caption whose number in the cycle of three is 3, as "#RRGGBB".
tilt_degrees: The angle by which every second line is turned, to the left for an angle above 0. 0 turns no line.
start_scale: The size of a caption at its start, as a part of its full size, above 0.
grow_seconds: Time in which a caption grows to its full size. A caption grows in half of its time at most. 0 gives no growth.
emoji_width_part: The width of the emoji as a part of the width of the widest line of the caption, above 0.
emoji_gap: Room in pixels between the emoji and the top of the caption at the full size. It grows with the caption.
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 or the words per line 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.

BouncyEmojiEffect

class BouncyEmojiEffect
    def __init__(
            self, settings: BouncyEmojiSettings,
            caption_measure: CaptionMeasure) -> None

Builds the ASS script and the emoji layers of the bouncy emoji effect.

Args:

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

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

BouncyEmojiEffect.build_layers

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

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

Each line of a caption is one event of the script, on a layer of its own. All events of a caption start with its first word. They end when the next caption starts, and at the latest the hold time after its last word and at the end of the video. The bottom of the last line of a caption at its full size is the caption bottom.

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.