captionbob.effects.cherry - captionbob docs

The cherry effect: two words in bold white capitals with a soft glow.

Each caption shows up to two words in bold white capitals with no end marks, and it ends at each end mark, such as a comma. A caption stays on one line up to the line letters. A longer caption is cut into two lines, and the top line holds the larger half of the words. The top line stands on the bottom position, and the second line hangs the line gap below it. The spaces are narrower than the font gives them by the word gap.

The letters have a soft glow in their own color: the stroke is an outline that is blurred and partly seen. The keywords of a video take the keyword colors in turn, in their letters and in their glow, and their glow is a little stronger. A space next to a keyword is wider by the keyword gap, so that the glow of the keyword keeps a clear space from the words next to it.

When a caption comes, its letters stand closer together than their normal spacing. They spread apart a little past it and come back to it in the pop time. In the last squeeze time of the caption they stand closer together again. The caption drifts a few pixels into its place: the first caption of a video and every second caption after it comes from the odd drift, the others from the even drift. The drift waits a part of the caption time and then moves in a straight line, and it ends when the squeeze starts.

Each line of a caption has one event with the times of the caption. Each word and each space is a run with the tags of its spacing, so a space can be narrower or wider than the others and still pop with them.

The settings of the lines, the captions with their lines and keywords, the places of the lines, the keyword colors in turn and the tags of the words with keywords, and the text of a line with tags for each word and each gap come from LineSettings, line_captions, keywords_in_turn, keyword_word_tags and word_lines_text of effect_common. The drift of each caption in turn, the tags of a line that drifts into its place, the time at which the letters close up and the spacing tag of a room come from turn_drift, drift_tags, squeeze_start_milliseconds and spacing_tag of effect_common.

The effect draws nothing itself. It builds the text of an ASS script, and ffmpeg draws it on the video. 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/cherry.py

Settings

The command line and the HTTP API call this effect the style cherry. Its settings class is CherrySettings. 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	`56`	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	`9.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.5745`	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.09`	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	`0.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	`26`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`word_gap`	number	`-4.4`	Room in pixels that is added to each space, at the letter width. A value below 0 makes the spaces narrower.
`keyword_colors`	list	`["#9EFFFA", "#E60223", "#9EFFFA", "#ED57F2"]`	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn, in their letters and in their glow.
`keyword_gap`	number	`24.0`	Room in pixels that is added to a space in front of a keyword and to a space behind one, at the letter width. A space between two keywords gets it twice.
`glow_blur`	number	`18.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.32`	The strength of the glow of a plain word, from 0 for no glow to 1.
`keyword_glow_opacity`	number	`0.37`	The strength of the glow of a keyword, from 0 for no glow to 1.
`pop_spacing`	number	`2.4`	How much closer together the letters stand when a caption comes, in pixels of room between two letters.
`spread_spacing`	number	`1.0`	How much farther apart than normal the letters stand at two thirds of the pop time, in pixels.
`pop_seconds`	number	`0.1`	The time in which the letters go from the pop spacing to the spread spacing and back to their normal spacing. 0 gives the normal spacing at once.
`squeeze_spacing`	number	`3.0`	How much closer together the letters stand in the last squeeze time of a caption, in pixels.
`squeeze_seconds`	number	`0.1`	The time at the end of a caption in which the letters stand closer. It starts after the pop time.
`odd_drift_x`	number	`-5.4`	How far to the right of its place the first caption of a video, and every second caption after it, starts, in pixels. A value below 0 starts it on the left.
`odd_drift_y`	number	`-5.7`	How far below its place such a caption starts, in pixels. A value below 0 starts it above.
`even_drift_x`	number	`3.7`	How far to the right of its place each other caption starts, in pixels.
`even_drift_y`	number	`2.8`	How far below its place each other caption starts, in pixels.
`drift_delay`	number	`0.25`	The part of the drift time in which a caption waits before it moves, from 0 up to 1. The drift time runs from the start of the caption to the start of its squeeze.
`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.

CherrySettings

@dataclass(frozen=True)
class CherrySettings(LineSettings)

The look and the timing of the cherry 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 LineSettings follow them, from the letter width to the line letters, and then the settings of the spaces, the keywords, the glow, the pop, the squeeze and the drift, and the hold time. The effect changes the defaults of some of them. The stroke is the glow: an outline in the stroke color that fades out over the glow blur. The bottom position is the bottom of the top line when the caption is at rest.

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.
line_gap: 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: True to write the words in capitals.
end_at_marks: True to end a caption at each end mark, such as a comma.
line_letters: The most letters, with the spaces, of a caption that stays on one line, 1 or above.
word_gap: Room in pixels that is added to each space, at the letter width. A value below 0 makes the spaces narrower.
keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn, in their letters and in their glow.
keyword_gap: Room in pixels that is added to a space in front of a keyword and to a space behind one, at the letter width. A space between two keywords gets it twice.
glow_blur: How far the edge of the glow fades out, in pixels.
glow_opacity: The strength of the glow of a plain word, from 0 for no glow to 1.
keyword_glow_opacity: The strength of the glow of a keyword, from 0 for no glow to 1.
pop_spacing: How much closer together the letters stand when a caption comes, in pixels of room between two letters.
spread_spacing: How much farther apart than normal the letters stand at two thirds of the pop time, in pixels.
pop_seconds: The time in which the letters go from the pop spacing to the spread spacing and back to their normal spacing. 0 gives the normal spacing at once.
squeeze_spacing: How much closer together the letters stand in the last squeeze time of a caption, in pixels.
squeeze_seconds: The time at the end of a caption in which the letters stand closer. It starts after the pop time.
odd_drift_x: How far to the right of its place the first caption of a video, and every second caption after it, starts, in pixels. A value below 0 starts it on the left.
odd_drift_y: How far below its place such a caption starts, in pixels. A value below 0 starts it above.
even_drift_x: How far to the right of its place each other caption starts, in pixels.
even_drift_y: How far below its place each other caption starts, in pixels.
drift_delay: The part of the drift time in which a caption waits before it moves, from 0 up to 1. The drift time runs from the start of the caption to the start of its squeeze.
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 font name cannot stand in a tag, or when a color is not in the form "#RRGGBB".

CherrySettings.drift

def drift(self, caption_index: int) -> tuple[float, float]

Give how far from its place a caption starts.

Args:

caption_index: The place of the caption in the captions of the video, 0 for the first.

Returns:

The pixels to the right and the pixels down. The first caption and every second caption after it have the odd drift, the others the even drift.

CherryEffect

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

Builds the ASS script of up to two words in bold white capitals with a soft glow, whose letters pop apart, and keywords in color.

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.

CherryEffect.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 has one 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.

CherryEffect.spacing_tags

def spacing_tags(
        self, room: float, pop_milliseconds: int,
        squeeze_start: int | None) -> str

Write the tags of the spacing of the letters of one run.

The letters start the pop spacing closer together than normal. They spread to the spread spacing past normal at two thirds of the pop time and come back to normal at its end. From the squeeze start they stand the squeeze spacing closer together. Each run gets these tags with its own room, so a space keeps its room through the pop.

Args:

room: Room in pixels added to the normal spacing of the run, at the letter width.
pop_milliseconds: The pop time from the start of the event.
squeeze_start: The time at which the letters close up, or None for no squeeze.

Returns:

The tags with no curly brackets.