captionbob.effects.brick - captionbob docs

Brick effect: narrow capitals, a soft shadow and keywords that glow.

Each caption shows one or two words in narrow white capitals with no end marks, a thin black outline and a soft dark shadow that lies a little below the letters. A keyword has its letters and a thin outline in one strong color, with a blur on the outline. So it shows in its color with a soft glow, and its letters can be read. The keywords of a video take the keyword colors in turn. Each caption pops in: it starts a little smaller and grows to its full size in a short time.

The shadow is an event on the layer under the caption: the caption in the shadow color with a wider outline, moved down and blurred. The effect draws nothing itself. It builds the text of an ASS script, and the ffmpeg filter ass draws the script 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/brick.py

Settings

The command line and the HTTP API call this effect the style brick. Its settings class is BrickSettings. 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 Condensed"`	Name of the font of the text.
`font_size`	integer	`118`	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	`3.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.69`	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 show the words in capitals.
`letter_width`	number	`0.77`	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.
`keyword_colors`	list	`["#E50006", "#F9FF24", "#E50006", "#14FF08"]`	The colors of the keywords, one or more. The keywords of a video take them in turn.
`keyword_border`	number	`2.0`	The width of the outline of a keyword in pixels. The outline has the color of the keyword.
`keyword_blur`	number	`3.0`	The blur of the outline of a keyword in pixels. 0 gives a hard edge.
`shadow_color`	string	`"#000000"`	Color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`7.0`	How far the shadow reaches out from the outline of the letters before its blur, in pixels.
`shadow_blur`	number	`9.0`	The blur of the shadow in pixels.
`shadow_opacity`	number	`0.65`	Strength of the shadow, from 0 for no shadow to 1 for the full shadow color.
`shadow_drop`	number	`6.0`	How far the shadow lies below the caption, in pixels. A value below 0 puts it above the caption.
`pop_scale`	number	`0.91`	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 grows to its full size. 0 shows each caption at its full size at once.
`hold_seconds`	number	`0.4`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

BrickSettings

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

The look and the timing of the brick 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. The shadow and the color of a keyword reach into the side margins.

Args:

capitals: True to show the words in capitals.
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.
keyword_colors: The colors of the keywords, one or more. The keywords of a video take them in turn.
keyword_border: The width of the outline of a keyword in pixels. The outline has the color of the keyword.
keyword_blur: The blur of the outline of a keyword in pixels. 0 gives a hard edge.
shadow_color: Color of the shadow, as "#RRGGBB".
shadow_spread: How far the shadow reaches out from the outline of the letters before its blur, in pixels.
shadow_blur: The blur of the shadow in pixels.
shadow_opacity: Strength of the shadow, from 0 for no shadow to 1 for the full shadow color.
shadow_drop: How far the shadow lies below the caption, in pixels. A value below 0 puts it above the caption.
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 shows each caption at its full size 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 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 are not a tuple of one color or more, or when the font name is empty or holds a comma.

BrickSettings.has_shadow

@property
def has_shadow(self) -> bool

True when the settings give a shadow that can be seen.

BrickSettings.shadow_style_line

def shadow_style_line(self, margin_vertical: int) -> str

Write the ASS style line of the shadow of these settings.

The shadow is the text in the shadow color, with an outline that is wider than the stroke by the shadow spread. The event of the shadow blurs this outline.

Args:

margin_vertical: Room in pixels between the bottom of the caption and the bottom edge of the video.

Returns:

The style line of the shadow.

Raises:

ValueError: When the font name, the font size, the shadow color, the outline width or a margin is outside its range.

BrickEffect

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

Builds the ASS script of narrow capitals with a shadow and keywords that glow.

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.

BrickEffect.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 is the shadow and the caption, from the lower layer up, with the same times. There is no shadow event when the shadow cannot be seen. An event starts with the first word of its caption. 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 a word of its caption.