captionbob.effects.spark - captionbob docs

The spark effect: small heavy capitals whose spoken line is larger and has a strong color.

Each caption shows its words in small heavy white capitals with a thin black edge, with no end marks. A caption ends at each end mark, such as a comma. A short caption stays on one line. A longer caption is cut into two lines, and the top line takes the larger half of the words. The line whose words are spoken is a little larger and has the line color of the caption, and the other line is white. The captions take the line colors yellow, green and red in turn. Each caption pops in: it starts a little small, grows past its full size and settles. A caption with a keyword has an emoji that starts behind the line next to it and slides out above or below the caption, fast at first and slow at the end.

Each line of a caption has two events with the times of the caption. The shadow event draws the letters in the shadow color, with a border that fades out. The text event draws the letters over it, with an outline in the color of the letters that makes them heavier. The top line stands on the caption bottom and grows up, and the second line hangs from the line gap below it and grows down. The settings of the lines and of the shadow, the captions with their lines and line colors, the places of the lines and the edge of an emoji come from SpokenLineSettings and spoken_line_captions of effect_common. An emoji is not drawn by ASS: the effect gives one emoji layer for each caption with a keyword, and the ffmpeg filters draw it under the captions, so the captions hide it at the start of its slide.

Source file: captionbob/effects/spark.py

Settings

The command line and the HTTP API call this effect the style spark. Its settings class is SparkSettings. 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	`"Ubuntu"`	Name of the font of the text.
`font_size`	integer	`47`	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	`"#FFFFFF"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`2.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.631`	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.
`letter_width`	number	`1.28`	The width of the letters as a part of the width that the font gives them, above 0. 1 keeps the width of the font.
`line_gap`	number	`14.0`	Room in pixels between the bottom of the top line and the top of the second line. A value below 0 puts the lines closer.
`capitals`	boolean	`true`	True to write the words in capitals.
`end_at_marks`	boolean	`true`	True to end a caption at each end mark, such as a comma.
`line_letters`	integer	`13`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`line_colors`	list	`["#FAFF31", "#4AFF41", "#DE1B2F"]`	The colors of the line that is spoken, as "#RRGGBB". The captions take them in turn.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`4.0`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`3.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`1.0`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`2.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`spoken_scale`	number	`1.05`	The size of the spoken line as a part of the size of a line that is not spoken, above 0.
`pop_scale`	number	`0.9`	The size of a caption at its start, as a part of its full size, above 0.
`peak_scale`	number	`1.1`	The size of a caption at the end of the pop time, as a part of its full size, above 0.
`pop_seconds`	number	`0.04`	The time in which a caption grows from the pop scale to the peak scale. 0 starts it at the peak scale.
`settle_seconds`	number	`0.06`	The time after the pop time in which a caption changes from the peak scale to its full size. 0 gives it its full size at the end of the pop time.
`emoji_size`	number	`84.0`	The side of the emoji in pixels, above 0.
`emoji_gap`	number	`6.0`	Room in pixels between the caption and the emoji at the end of its slide.
`emoji_places`	list	`["below", "below", "below", "above", "below", "below"]`	The places of the emojis, one or more of "above" and "below". The captions with an emoji take them in turn.
`emoji_shifts`	list	`[80.0, 125.0, 0.0, -75.0, -80.0, 0.0]`	How far the middle of each emoji ends to the right of the middle of the video, in pixels. A value below 0 is to the left. The captions with an emoji take them in turn.
`emoji_slide_seconds`	number	`0.8`	The time in which an emoji slides from behind the caption to its place. 0 shows it at its place at once.
`hold_seconds`	number	`0.1`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

SparkEmojiLayer

class SparkEmojiLayer(NamedTuple)

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

The emoji is a square that keeps its size. In the slide time it moves from its start place to its end place on the curve that is fast at the start and slow at the end, and it stays at its end place after it.

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.
size: The side of the emoji in pixels.
start_middle_x: The column of the middle of the emoji at the start.
start_top: The top row of the emoji at the start.
end_middle_x: The column of the middle of the emoji at the end of the slide.
end_top: The top row of the emoji at the end of the slide.
slide_seconds: The slide time from the start of the caption. 0 shows the emoji at its end place at once.

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

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

SparkEmojiLayer.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 of a frame.

SparkLayers

class SparkLayers(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 with a keyword, in time order.

SparkSettings

@dataclass(frozen=True)
class SparkSettings(SpokenLineSettings)

The look and the timing of the spark effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The settings of SpokenLineSettings follow them, from the letter width to the shadow drop, and then the settings of the spoken line, the pop, the emoji and the hold time. The effect changes the defaults of some of them. The primary color is the color of the white lines. The stroke is the outline of the letters, which makes them heavier in the color of their line. The bottom position is the bottom of the top line.

Args:

spoken_scale: The size of the spoken line as a part of the size of a line that is not spoken, above 0.
pop_scale: The size of a caption at its start, as a part of its full size, above 0.
peak_scale: The size of a caption at the end of the pop time, as a part of its full size, above 0.
pop_seconds: The time in which a caption grows from the pop scale to the peak scale. 0 starts it at the peak scale.
settle_seconds: The time after the pop time in which a caption changes from the peak scale to its full size. 0 gives it its full size at the end of the pop time.
emoji_size: The side of the emoji in pixels, above 0.
emoji_gap: Room in pixels between the caption and the emoji at the end of its slide.
emoji_places: The places of the emojis, one or more of "above" and "below". The captions with an emoji take them in turn.
emoji_shifts: How far the middle of each emoji ends to the right of the middle of the video, in pixels. A value below 0 is to the left. The captions with an emoji take them in turn.
emoji_slide_seconds: The time in which an emoji slides from behind the caption to its place. 0 shows it at its place at once.
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 line letters is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", when an emoji place is not known, when the emoji shifts are not a tuple of numbers, or when the font name is empty or holds a comma.

SparkEffect

class SparkEffect
    def __init__(
            self, settings: SparkSettings,
            keyword_picker: KeywordPicker = DEFAULT_KEYWORD_PICKER) -> None

Builds the ASS script and the emoji layers of small heavy capitals with a black edge that pop in, whose spoken line is larger and yellow, green or red, with an emoji that slides out above or below.

Args:

settings: The look and the timing of the effect.
keyword_picker: Names the keywords of each caption. A caption with a keyword has an emoji. With no value, the keyword of a caption is its longest word when that word has seven letters or more.

SparkEffect.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 line of each caption group has a shadow event and a text event. The events start with the first word of their caption. 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.

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 the keyword picker gives a place that is not a word of its caption.

SparkEffect.build_layers

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

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

The script is the script of build_ass_text. Each caption with a keyword has one emoji layer with the times of the caption.

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 the emoji layers.

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 the keyword picker gives a place that is not a word of its caption.