captionbob.effects.lime - captionbob docs

The lime effect: white words on black boxes, one line on a green box.

Each caption shows its words in white sentence case with no end marks. A caption holds up to five words, and it ends at each end mark, such as a comma. A caption of the top line words or fewer stays on one line. A longer caption is cut into two lines: the top line holds the first top line words, and the second line holds the rest. The top line stands on the bottom position, and the second line hangs the line gap below it.

Each line stands on a box of its own with square corners. The box of a caption of one line is black. In a caption of two lines the top line is on a black box, and the second line is on a green box that is tilted a little with its words. The boxes of the two lines touch. A caption pops in: it shows at the pop scale of its size and grows to its full size in the pop time, around the middle of its boxes. It leaves at once when it ends.

Each line of a caption has a box event and a text event with the times of the caption. The box event draws the box with the box border style of libass, with its letters hidden, so the box is as wide as the words of the line and the side padding on each side. The text event draws the words over the boxes. The green box is on a layer above the black box, and the words are on the layer above both.

The settings of the lines, the places of the lines, the caption groups that end at each end mark, the words with no end marks, the cut of a caption into lines by the words of its top line, the style line of the boxes, the size tags, the pop tags, the move of a line into its place and the text of a line with a word gap come from LineSettings, caption_groups_at_marks, shown_group, lines_by_top_words, box_border_style_line, size_tags, pop_tags, rise_place_tags and word_gap_line_text of effect_common.

Source file: captionbob/effects/lime.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`5`	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	`74`	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.7`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6615`	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	`1.17`	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.
`line_gap`	number	`41.3`	Room in pixels between the bottom of the top line and the top of the second line. A value below 0 puts the lines 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.
`line_letters`	integer	`20`	The most letters, with the spaces, of a line, 1 or above. A line with one word holds that word.
`top_line_words`	integer	`3`	The most words of a caption that stays on one line, and of the top line of a caption of two lines, 1 or above.
`word_gap`	number	`-0.8`	Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
`box_color`	string	`"#000000"`	Color of the box of a line, as "#RRGGBB".
`highlight_color`	string	`"#1CEA05"`	Color of the box of the second line of a caption of two lines, as "#RRGGBB".
`box_side_padding`	number	`13.4`	Room in pixels between the words of a line and the left and the right edge of its box, past the room that the font gives the letters.
`box_vertical_padding`	number	`20.65`	Room in pixels between the rows of the font and the top and the bottom edge of the box.
`text_drop`	number	`-1.4`	How far the words are below the place that the font gives them in their box, in pixels. A value below 0 puts them higher.
`highlight_tilt`	number	`0.97`	The angle of the green box and its words in degrees. A value above 0 puts the right end up.
`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.08`	The time in which a caption grows to its full size. 0 shows it at its full size at once.
`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.

LimeSettings

@dataclass(frozen=True)
class LimeSettings(LineSettings)

The look and the timing of the lime effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The settings of LineSettings follow them, from the letter width to the line letters, and then the top line words, the word gap, the settings of the boxes, the tilt, the pop and the hold time. 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 top 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.
line_gap: Room in pixels between the bottom of the top line and the top of the second line. A value below 0 puts the lines 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.
line_letters: The most letters, with the spaces, of a line, 1 or above. A line with one word holds that word.
top_line_words: The most words of a caption that stays on one line, and of the top line of a caption of two lines, 1 or above.
word_gap: Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
box_color: Color of the box of a line, as "#RRGGBB".
highlight_color: Color of the box of the second line of a caption of two lines, as "#RRGGBB".
box_side_padding: Room in pixels between the words of a line and the left and the right edge of its box, past the room that the font gives the letters.
box_vertical_padding: Room in pixels between the rows of the font and the top and the bottom edge of the box.
text_drop: How far the words are below the place that the font gives them in their box, in pixels. A value below 0 puts them higher.
highlight_tilt: The angle of the green box and its words in degrees. A value above 0 puts the right end up.
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 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, the line letters or the top line words is not a whole number.
ValueError: When a value is outside its range, or when a color is not in the form "#RRGGBB".

LimeSettings.box_style_line

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

Write the ASS style line of the boxes 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 boxes: the box border style in the box color, with the vertical padding as its room.

Raises:

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

LimeSettings.line_words

def line_words(self, words: Sequence[Word]) -> list[list[Word]]

Cut the words of a caption into one line or two lines.

Args:

words: The words of the caption, as the effect shows them.

Returns:

One line when the caption has the top line words or fewer and the line letters or fewer, with its spaces, or when it has one word. Else two lines: the top line with the first words, up to the top line words and the line letters and at least one word, and the second line with the rest. The second line holds at least one word.

LimeEffect

class LimeEffect
    def __init__(self, settings: LimeSettings) -> None

Builds the ASS script of white words on black boxes, with the second line of two on a tilted green box.

Args:

settings: The look and the timing of the effect.

LimeEffect.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 line of each caption has one box event and one text event. 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.

LimeEffect.caption_events

def caption_events(
        self, caption: ShownCaption, lines: Sequence[Sequence[Word]],
        middle_x: float, caption_bottom: int) -> list[str]

Write the box events and the text events of one caption.

Args:

caption: The caption with the times of its events.
lines: The lines of the caption from the top, with the words as the effect shows them. One line or two lines.
middle_x: The column of the middle of the video.
caption_bottom: The row of the bottom of the top line.

Returns:

The box event and the text event of each line from the top.