captionbob.effects.solo - captionbob docs

Solo effect: one or two bold rounded words that pop in, with an emoji.

Each caption shows one word, or two short words, in bold rounded white letters with a black outline and a soft black shadow below them. The words are in the case in which they are spoken, with no end marks. A word with five letters or more is a caption of its own, and a caption ends at each end mark, such as a comma.

Each caption pops in: it starts a little smaller and grows around its middle to its full size in a short time, with its outline and its shadow. A keyword is green or cyan, in turn. Its outline and its shadow are a dark form of its color.

Each 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, a little below the letters. The text event draws the letters over it.

A caption with a keyword has an emoji in the middle below the caption. The emoji starts a little larger and shrinks to its full size in the pop time, and it keeps its bottom row. It goes with its caption. The ffmpeg filters scale and overlay draw the emoji under the ASS script. The effect gives the place of the emoji as ffmpeg expressions on an emoji layer, and it reads no image.

The effect draws nothing itself. It builds the text of an ASS script and the emoji layers, and ffmpeg draws them on the video. The common part of the effects is in effect_common.py.

The defaults are the look of the source video of the effect, measured on its frames and scaled to a video of 1080x1920.

Source file: captionbob/effects/solo.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`2`	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	`106`	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	`4.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.729`	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.08`	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.
`alone_letters`	integer	`5`	The fewest letters of a word that is a caption of its own, 1 or above. The end marks at the end of a word are not counted.
`end_at_marks`	boolean	`true`	True to end a caption at each end mark, such as a comma.
`keyword_colors`	list	`["#5DFF42", "#4AF2F3"]`	The colors of the letters of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
`keyword_stroke_colors`	list	`["#0E3406", "#033034"]`	The colors of the outline and of the shadow of the keywords, as "#RRGGBB", one for each keyword color.
`pop_scale`	number	`0.9`	The size of a caption at its start, as a part of its full size, above 0.
`pop_seconds`	number	`0.1`	The time in which a caption and its emoji change to their full size. 0 shows them at their full size at once.
`shadow_color`	string	`"#000000"`	The color of the shadow of the plain words, as "#RRGGBB".
`shadow_spread`	number	`1.0`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`5.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.9`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`6.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`emoji_size`	number	`168.0`	The side of the emoji in pixels at its full size, above 0.
`emoji_gap`	number	`16.0`	Room in pixels between the bottom of the caption and the top of the emoji at its full size.
`emoji_pop_scale`	number	`1.1`	The size of the emoji at its start, as a part of its full size, above 0. Above 1 the emoji shrinks to its full size.
`hold_seconds`	number	`0.3`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

KeywordLook

class KeywordLook(NamedTuple)

The colors of one keyword.

Args:

color: Color of the letters, as "#RRGGBB".
stroke_color: Color of the outline and of the shadow, as "#RRGGBB".

SoloLayers

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

SoloSettings

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

The look and the timing of the solo 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. The primary color is the color of the plain words, and the stroke is their outline.

Args:

letter_width: 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.
alone_letters: The fewest letters of a word that is a caption of its own, 1 or above. The end marks at the end of a word are not counted.
end_at_marks: True to end a caption at each end mark, such as a comma.
keyword_colors: The colors of the letters of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
keyword_stroke_colors: The colors of the outline and of the shadow of the keywords, as "#RRGGBB", one for each keyword color.
pop_scale: The size of a caption at its start, as a part of its full size, above 0.
pop_seconds: The time in which a caption and its emoji change to their full size. 0 shows them at their full size at once.
shadow_color: The color of the shadow of the plain words, as "#RRGGBB".
shadow_spread: How far the shadow reaches past the outline, in pixels.
shadow_blur: How far the edge of the shadow fades out, in pixels.
shadow_opacity: The strength of the shadow, from 0 for no shadow to 1.
shadow_drop: How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
emoji_size: The side of the emoji in pixels at its full size, above 0.
emoji_gap: Room in pixels between the bottom of the caption and the top of the emoji at its full size.
emoji_pop_scale: The size of the emoji at its start, as a part of its full size, above 0. Above 1 the emoji shrinks to its full size.
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 alone letters is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", when the keyword colors and the keyword stroke colors differ in number, or when the font name is empty or holds a comma.

solo_caption_groups

def solo_caption_groups(
        settings: CaptionSettings, words: Sequence[Word], alone_letters: int,
        end_at_marks: bool) -> tuple[CaptionGroup, ...]

Build the caption groups of the words, with each long word alone.

A word with the alone letters or more is a caption of its own. The end marks at the end of a word are not counted. The shorter words between two such words take the caption groups of the settings, with an end at each end mark when end_at_marks is True.

Args:

settings: The settings of the effect, with the word counts.
words: The words of the video in time order.
alone_letters: The fewest letters of a word that is a caption of its own.
end_at_marks: True to end a group also at each word that ends with an end mark, such as a comma.

Returns:

The caption groups in time order. Together they hold every word one time, in the order of the words.

SoloEffect

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

Builds the ASS script and the emoji layers of one or two bold rounded words that pop in, with green or cyan keywords and an emoji below.

Args:

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

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

SoloEffect.build_layers

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

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.