captionbob.effects.linen

Linen effect: plain white words on a black box with a soft shadow.

A caption shows a few words on one line, in plain white letters, on a black box with small round corners. A soft shadow spreads out around the box. The words have no end marks, such as commas and full stops. The caption grows from a little below its full size to its full size in the pop time, and it goes with no fade.

A caption is three events of the script at one place: the shadow on the lowest layer, the box above it and the text on the top layer. libass draws no box with round corners behind a text, so the box is a drawing, and the shadow is the same drawing blurred. The caption measure gives the columns of the text, and the box is as wide as the text plus the side padding on each side. It is as high as the rows of the text, each row as high as the font size, plus the vertical padding above and below. The middle of the box is its place, so the box grows from its middle. 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/linen.py

Settings

The command line and the HTTP API call this effect the style linen. Its settings class is LinenSettings. 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	"DejaVu Sans"	Name of the font of the text.
font_size	integer	80	Height of the font in pixels.
bold	boolean	false	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.688	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.
box_color	string	"#000000"	Color of the box behind the caption, as "#RRGGBB".
shadow_color	string	"#000000"	Color of the shadow around the box, as "#RRGGBB".
box_side_padding	number	17.0	Room in pixels between the text and the left and the right edge of the box.
box_vertical_padding	number	12.0	Room in pixels between the rows of the text and the top and the bottom edge of the box. A row is as high as the font size.
corner_radius	number	8.0	Radius of the round corners of the box in pixels. 0 gives square corners.
shadow_blur	number	20.0	Strength of the blur of the shadow, the value of the tag \blur. 0 gives no shadow.
pop_start_scale	number	0.975	Size of a caption at its start, as a part of its full size, above 0. 1 gives no pop.
pop_seconds	number	0.07	Time in which a caption grows to its full size. 0 shows it at its full size at once.
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.

LinenSettings

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

The look and the timing of the linen 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 box reaches into the side margins by its side padding.

Args:

• box_color: Color of the box behind the caption, as "#RRGGBB".
• shadow_color: Color of the shadow around the box, as "#RRGGBB".
• box_side_padding: Room in pixels between the text and the left and the right edge of the box.
• box_vertical_padding: Room in pixels between the rows of the text and the top and the bottom edge of the box. A row is as high as the font size.
• corner_radius: Radius of the round corners of the box in pixels. 0 gives square corners.
• shadow_blur: Strength of the blur of the shadow, the value of the tag \blur. 0 gives no shadow.
• pop_start_scale: Size of a caption at its start, as a part of its full size, above 0. 1 gives no pop.
• pop_seconds: Time in which a caption grows to its full size. 0 shows it 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", or when the font name is empty or holds a comma.

LinenSettings.shadow_style_line

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

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

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 of the captions.

Raises:

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

LinenSettings.box_style_line

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

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

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 box of the captions.

Raises:

• ValueError: When the font name, the font size, the box color or a margin is outside its range.

LinenEffect

class LinenEffect
    def __init__(
            self, settings: LinenSettings,
            caption_measure: PlaceMeasure) -> None

Builds the ASS script of white words on a black box with a shadow.

Args:

• settings: The look and the timing of the effect.
• caption_measure: The measure that says where libass draws each word of a caption.

LinenEffect.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 three events with the same times: the shadow, the box and the text, from the lowest layer up. There is no shadow event when the shadow blur is 0. 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 libass draws no pixel for a word.
• RuntimeError: When the ffmpeg of the caption measure fails.