captionbob.effects.olive - captionbob docs

Olive effect: serif sentence case on a dark box, the spoken word on a green box.

Each caption shows a few words in one line of white serif letters, in the case and with the end marks of the speech. A caption ends at each end mark, such as a comma. The line stands on a dark box with square corners. A green box stands behind each word while the word is spoken, and no word has it in a pause between two words. A caption shows at once when its first word starts, and it goes at once when its last word ends, so the screen is empty in a pause between two captions.

The letters are those of the font, made taller by the letter height. So the widths of the words stay the widths that libass gives for the font, and the caption measure gives them. The dark box is as wide as the line plus the box side padding on each side, and a green box is as wide as its word plus the word box side padding on each side. Each box has its own top padding and bottom padding around the rows of the text.

A caption is events of three kinds at one place: the dark box on the lowest layer, one green box for each spoken word on the layer above it, and the text on the top layer. libass draws no box behind one word of a text, so the boxes are drawings. libass breaks a caption that is too wide for the room between the side margins into rows, as the caption measure gives them. Each row of the text is an event of its own, placed by the middle of its row, so the rows of the text and of the boxes are one row height apart.

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

Settings

The command line and the HTTP API call this effect the style olive. Its settings class is OliveSettings. Each setting has the default below.

Setting	Type	Default	Description
`most_words`	integer	`3`	The most words that one caption shows.
`fewest_words`	integer	`2`	The fewest words that one caption shows, when its sentence is long enough for that.
`font_name`	string	`"DejaVu Serif"`	Name of the font of the text.
`font_size`	integer	`66`	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.677`	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	`false`	True to write the words in capitals.
`end_at_marks`	boolean	`true`	True to end a caption also at each word that ends with an end mark, such as a comma.
`letter_height`	number	`1.12`	The height of the letters as a part of the height that the font gives them. A row of a caption is the font size times this part high.
`box_color`	string	`"#18181A"`	Color of the box behind the caption, as "#RRGGBB".
`box_side_padding`	number	`21.0`	Room in pixels between the text, with no outline, and the left and the right edge of the box.
`box_top_padding`	number	`14.2`	Room in pixels between the top of the rows of the text and the top edge of the box.
`box_bottom_padding`	number	`23.5`	Room in pixels between the bottom of the rows of the text and the bottom edge of the box.
`word_box_color`	string	`"#73880D"`	Color of the box behind the spoken word, as "#RRGGBB".
`word_box_side_padding`	number	`5.4`	Room in pixels between the spoken word, with no outline, and the left and the right edge of its box.
`word_box_top_padding`	number	`7.8`	Room in pixels between the top of the row of the spoken word and the top edge of its box.
`word_box_bottom_padding`	number	`16.0`	Room in pixels between the bottom of the row of the spoken word and the bottom edge of its box.
`corner_radius`	number	`0.0`	The radius of the corners of both boxes in pixels. 0 gives square corners.
`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.

OliveSettings

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

The look and the timing of the olive 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 bottom position is the place of the bottom of the rows of the text. The stroke is the outline of the letters.

Args:

capitals: True to write the words in capitals.
end_at_marks: True to end a caption also at each word that ends with an end mark, such as a comma.
letter_height: The height of the letters as a part of the height that the font gives them. A row of a caption is the font size times this part high.
box_color: Color of the box behind the caption, as "#RRGGBB".
box_side_padding: Room in pixels between the text, with no outline, and the left and the right edge of the box.
box_top_padding: Room in pixels between the top of the rows of the text and the top edge of the box.
box_bottom_padding: Room in pixels between the bottom of the rows of the text and the bottom edge of the box.
word_box_color: Color of the box behind the spoken word, as "#RRGGBB".
word_box_side_padding: Room in pixels between the spoken word, with no outline, and the left and the right edge of its box.
word_box_top_padding: Room in pixels between the top of the row of the spoken word and the top edge of its box.
word_box_bottom_padding: Room in pixels between the bottom of the row of the spoken word and the bottom edge of its box.
corner_radius: The radius of the corners of both boxes in pixels. 0 gives square corners.
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.

OliveSettings.row_height

def row_height(self) -> float

Give the height of one row of a caption in pixels.

OliveSettings.box_style_line

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

Write the ASS style line of the box behind a caption.

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.

OliveSettings.word_box_style_line

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

Write the ASS style line of the box behind the spoken word.

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 spoken words.

Raises:

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

OliveEffect

class OliveEffect
    def __init__(
            self, settings: OliveSettings,
            caption_measure: PlaceMeasure) -> None

Builds the ASS script of white serif words on a dark box, with a green box behind the spoken word.

Args:

settings: The look and the timing of the effect.
caption_measure: The measure that says where libass draws each word of a caption. It runs ffmpeg once for all the captions of a video.

OliveEffect.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 is a box event, a green box event for each word with a spoken time and a text event for each row. The boxes come first, then the green boxes and then the text. The box and the text 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.
RuntimeError: When the ffmpeg of the caption measure fails.