captionbob.effects.chalk - captionbob docs

The chalk effect: one or two white words on a gray see-through box.

Each caption shows up to two words in one line, in the case in which they are spoken and with no end marks. A caption also ends at each end mark, such as a comma or a full stop. The words are white, and they stand on a gray box with round corners that lets the video show through. A caption shows at once with its first word, and it leaves at once when it ends.

The caption measure gives the width of the line of each caption in the font of the words. The box is as wide as the line plus the side padding on each side, and it reaches its own paddings above and below the line. A caption whose line does not fit between the side margins gets smaller as a whole, with its box. Each caption is one box event and one text event over it.

The caption groups that end at each end mark, the words with no end marks, the width of a measured line, the box behind one line, the box drawing placed by its middle, the style line of a drawing and the text of a line with a word gap come from caption_groups_at_marks, shown_group, line_width, middle_line_box, middle_box_text, drawing_style_line and word_gap_line_text of effect_common.

Source file: captionbob/effects/chalk.py

Settings

The command line and the HTTP API call this effect the style chalk. Its settings class is ChalkSettings. 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	`80`	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	`0.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6604`	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	`0.84`	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.
`word_gap`	number	`-2.3`	Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
`capitals`	boolean	`false`	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.
`box_color`	string	`"#323434"`	Color of the box behind a caption, as "#RRGGBB".
`box_opacity`	number	`0.45`	The strength of the box, from 0 for no box to 1 for a box that hides the video.
`box_side_padding`	number	`21.5`	Room in pixels between the line and the left and the right edge of the box.
`box_top_padding`	number	`6.5`	Room in pixels between the top of the line of the font and the top edge of the box.
`box_bottom_padding`	number	`13.3`	Room in pixels between the bottom of the line of the font and the bottom edge of the box.
`box_radius`	number	`14.0`	The radius of the corners of the box in pixels.
`hold_seconds`	number	`0.0`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

ChalkSettings

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

The look and the timing of the chalk effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The letter width, the word gap, the switches of the words, the settings of the box and the hold time follow them. The effect changes the defaults of some of them. The stroke is the outline of the letters in their own color, which makes them heavier. The bottom position is the bottom of the line.

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.
word_gap: Room in pixels that is added after each space, at the letter width. A value below 0 puts the words 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.
box_color: Color of the box behind a caption, as "#RRGGBB".
box_opacity: The strength of the box, from 0 for no box to 1 for a box that hides the video.
box_side_padding: Room in pixels between the line and the left and the right edge of the box.
box_top_padding: Room in pixels between the top of the line of the font and the top edge of the box.
box_bottom_padding: Room in pixels between the bottom of the line of the font and the bottom edge of the box.
box_radius: The radius of the corners of the box in pixels.
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, or when a color is not in the form "#RRGGBB".

ChalkSettings.has_box

@property
def has_box(self) -> bool

True when the box behind a caption can be seen.

ChalkSettings.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 behind the captions.

Raises:

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

ChalkEffect

class ChalkEffect
    def __init__(
            self, settings: ChalkSettings,
            caption_measure: PlaceMeasure) -> None

Builds the ASS script of one or two white words on a gray see-through box with round corners.

Args:

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

ChalkEffect.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 has a box event and a text event over it. 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 libass draws no pixel for a word in the caption measure.
RuntimeError: When the ffmpeg of the caption measure fails.