captionbob.effects.zest

Zest effect: bold white capitals that drift, with a larger keyword.

A caption ends at the end of a sentence and, by default, at each other end mark, such as a comma. It shows its words in capitals in one line, with no end marks. The keyword of a caption, which the keyword picker gives, is larger than the other words, and it has its own color for the whole time of the caption. The keywords of a video take the keyword colors in turn.

Each caption has three layers. The shadow layer draws the letters in the shadow color, with a wide border that fades out, a little below the letters. The glow layer draws each word in its color, with a border that reaches past the spread of the letters and fades out. The text layer draws the letters, each with a border of its own color as wide as the letter spread, which makes them heavier.

A caption pops in: it grows from the pop scale to its full size in the pop time. It drifts on the line from the top left to the bottom right. It starts at one end, moves to the other end in the drift time, slow at the two ends, and moves back. The first caption starts at the top left end, and the captions take the two ends in turn. ASS moves a text only in a straight line, so the time of a caption is cut into events, and each event is one straight move between two places of the curve.

Source file: captionbob/effects/zest.py

Settings

The command line and the HTTP API call this effect the style zest. Its settings class is ZestSettings. 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	70	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	0.0	Width of the outline in pixels. 0 gives no outline.
bottom_position	number	0.669	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.
capitals	boolean	true	True to write the words in capitals.
letter_width	number	1.19	The width of the letters as a part of the width that the font gives them, above 0.
letter_spread	number	3.0	How far the letters spread past the shapes of the font, in pixels. Each letter has an outline of its own color this wide, which makes it heavier. 0 gives the letters of the font.
keyword_scale	number	1.2	The size of a keyword as a part of the size of the other words, above 0. Its spread grows with it.
keyword_colors	list	["#F8FF24", "#E9011D", "#70FF22"]	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
glow_width	number	3.0	How far the glow reaches past the spread of the letters, in pixels, before it fades out.
glow_blur	number	5.0	How far the edge of the glow fades out, in pixels.
glow_opacity	number	0.3	The strength of the glow, from 0 for no glow to 1.
shadow_color	string	"#000000"	The color of the shadow, as "#RRGGBB".
shadow_spread	number	12.0	How far the shadow reaches past the spread of the letters, in pixels, before it fades out.
shadow_blur	number	16.0	How far the edge of the shadow fades out, in pixels.
shadow_opacity	number	0.5	The strength of the shadow, from 0 for no shadow to 1.
shadow_drop	number	10.0	How far the shadow is below the letters, in pixels. A value below 0 puts it above them.
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.09	The time in which a caption grows to its full size. 0 gives a caption that starts at its full size.
drift_reach	number	13.1	How far a caption moves to the left and up, and to the right and down, from its middle place, in pixels. 0 gives a caption that stays at its middle place.
drift_seconds	number	0.675	The time of one move of a caption from one end of the drift to the other, above 0.
end_at_marks	boolean	true	True to end a caption at each end mark, such as a comma. A caption always ends at the end of a sentence.
hold_seconds	number	0.15	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

ZestSettings

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

The look and the timing of the zest effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The primary color is the color of the words that are not keywords. The stroke color and the stroke width give the outline of the style line, which the events of the effect do not use. The bottom position is the bottom of the row of a caption in the middle of the drift. These settings follow them.

Args:

• capitals: True to write the words in capitals.
• letter_width: The width of the letters as a part of the width that the font gives them, above 0.
• letter_spread: How far the letters spread past the shapes of the font, in pixels. Each letter has an outline of its own color this wide, which makes it heavier. 0 gives the letters of the font.
• keyword_scale: The size of a keyword as a part of the size of the other words, above 0. Its spread grows with it.
• keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
• glow_width: How far the glow reaches past the spread of the letters, in pixels, before it fades out.
• glow_blur: How far the edge of the glow fades out, in pixels.
• glow_opacity: The strength of the glow, from 0 for no glow to 1.
• shadow_color: The color of the shadow, as "#RRGGBB".
• shadow_spread: How far the shadow reaches past the spread of the letters, in pixels, before it fades out.
• 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 it above them.
• 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 grows to its full size. 0 gives a caption that starts at its full size.
• drift_reach: How far a caption moves to the left and up, and to the right and down, from its middle place, in pixels. 0 gives a caption that stays at its middle place.
• drift_seconds: The time of one move of a caption from one end of the drift to the other, above 0.
• end_at_marks: True to end a caption at each end mark, such as a comma. A caption always ends at the end of a sentence.
• 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 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.

ZestEffect

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

Builds the ASS script of the zest effect.

Args:

• settings: The look and the timing of the effect.
• keyword_picker: Gives the places of the keywords of a caption. The default gives the longest word of a caption when it has KEYWORD_FEWEST_LETTERS letters or more.

ZestEffect.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 starts with 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.

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 the place of a word of a caption.