captionbob.effects.floating_color_shift_emoji - captionbob docs

Floating color shift emoji effect: a caption floats with an emoji above it.

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. A caption has one color. A caption that starts in an even second of the video has the primary color and the stroke of the common settings. A caption that starts in an odd second has the secondary color and the secondary stroke.

The caption floats up and to the left by the float distance and back in its time: it moves away from its place in the first half of the time and comes back in the second half, and each half is slow at its start and at its end. The text fades out in the last part of the time.

One emoji image stands above the middle of the caption, with a gap between the two, and it floats with the caption. Its width is a part of the width of the widest line of the caption. It does not fade. An animated emoji plays from its first frame at the start of each caption.

ASS moves a text only in a straight line at one speed. So the time of a caption is cut into events that follow one another, and each event is one straight move from one place of the float to the next. An event in the fade has the fade tags of its part of the time. 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 line that is too wide for the room between the side margins, and the width of each line, come from the caption measure. The common part of the effects is in effect_common.py.

Source file: captionbob/effects/floating_color_shift_emoji.py

Settings

The command line and the HTTP API call this effect the style floating_color_shift_emoji. Its settings class is FloatingColorShiftEmojiSettings. 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	`0.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 a caption that starts in an odd second of the video, as "#RRGGBB".
`secondary_stroke_color`	string	`"#FFFFFF"`	The color of the outline of such a caption, as "#RRGGBB".
`secondary_stroke_width`	number	`2.0`	The width of that outline in pixels. 0 gives no outline.
`float_distance`	number	`50.0`	How far a caption and its emoji float up and to the left in the middle of the time of the caption, in pixels. 0 gives a caption that stays in its place.
`fade_out_part`	number	`0.3`	The part of the time of a caption, at its end, in which its text fades out, from 0 to 1. 0 gives no fade.
`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	`10.0`	Room in pixels between the emoji and the top of 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.

float_part

def float_part(time_part: float) -> float

Give how far a caption has floated at a part of its time.

The old effect floats away in the first half of the time and back in the second half, each half on the in-out quad curve. The way back is the way out run backwards, and the curve has the same shape from its end, so the float is the curve of the part of the way out that is over.

Args:

time_part: The part of the time of the caption that is over, 0 to 1.

Returns:

The part of the float distance: 0 at the start and at the end of the time, and 1 in its middle.

float_part_expression

def float_part_expression(start_seconds: float, length_seconds: float) -> str

Write float_part of the time t of a frame as ffmpeg reads it.

Args:

start_seconds: The start of the time of the caption, in seconds of the video.
length_seconds: The length of the time of the caption, above 0.

Returns:

An ffmpeg expression of the time t: 0 up to the start of the time, the float in the time and 0 from its end on.

FloatingEmojiLayer

class FloatingEmojiLayer(NamedTuple)

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

The emoji is a square of one size. It floats with its caption, up and to the left by the float distance and back, in the time of the caption. 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.
middle_x: The middle of the emoji at the start and at the end of the caption, in pixels from the left edge of the video. It is the middle of the caption.
bottom_edge: The bottom edge of the emoji at the start and at the end of the caption: the emoji fills the rows above this row. It is the emoji gap above the top of the caption.
float_distance: How far the emoji floats up and to the left in the middle of the time of the caption, in pixels.

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

FloatingEmojiLayer.left_expression

def left_expression(self) -> str

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

Returns:

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

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

FloatingEmojiLayer.float_expression

def float_expression(self) -> str

Write how far the emoji has floated at the time t, in pixels.

Returns:

An ffmpeg expression of the time t.

FloatingColorShiftEmojiLayers

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

FloatingColorShiftEmojiSettings

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

The look and the timing of the floating color shift 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, its primary color is red, and its stroke width is 0, so a caption of the primary color has no outline. These settings follow them.

Args:

words_per_line: The words of one line of a caption.
secondary_color: The color of a caption that starts in an odd second of the video, as "#RRGGBB".
secondary_stroke_color: The color of the outline of such a caption, as "#RRGGBB".
secondary_stroke_width: The width of that outline in pixels. 0 gives no outline.
float_distance: How far a caption and its emoji float up and to the left in the middle of the time of the caption, in pixels. 0 gives a caption that stays in its place.
fade_out_part: The part of the time of a caption, at its end, in which its text fades out, from 0 to 1. 0 gives no fade.
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.
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.

FloatingColorShiftEmojiEffect

class FloatingColorShiftEmojiEffect
    def __init__(
            self, settings: FloatingColorShiftEmojiSettings,
            caption_measure: CaptionMeasure) -> None

Builds the ASS script and the emoji layers of the floating color shift 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.

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

FloatingColorShiftEmojiEffect.build_layers

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

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. Its time is cut into events that follow one another, and each event moves its lines in a straight line.

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.