captionbob.effects.ribbon - captionbob docs

The ribbon effect: bold white words with a colored bar under the line that is spoken.

Each caption shows its words as they are spoken, with their end marks, in bold white letters with a soft dark shadow. A caption holds two to six words, and it ends at each end mark, such as a comma. A caption that ends with an end mark and has the line letters or fewer stays on one line. A caption with the top line words or fewer and the line letters or fewer also stays on one line. Another caption is cut into two lines, and the top line holds the top line words, or fewer when they have more than the line letters. A line that is wider than the room between the side margins gets smaller as a whole. The top line stands on the bottom position, and the second line hangs the line gap below it.

The line that is spoken has a bar under each of its words, in the line color of the caption. The captions take the line colors in turn. The bars of the top line show from the start of the caption. The bars of the second line show when its first word is spoken, and the bars of the top line go at that time. A bar is as wide as its word with the stroke, and it is the bar drop below the line. The bars of the spoken line take the bar room below it, so a line below the spoken line stands the bar room lower. A caption shows and leaves at once.

The places of the words come from the caption measure, which draws each line at the width of the font. The measure draws on a clip twice as wide as the video, so that libass draws each line as one row. The effect moves each place by the letter width and the word gap of the settings.

Each line of a caption has a shadow event and a text event for each place that it takes, and each bar is an event of its own. The shadows are under the bars, and the bars are under the text.

The settings of the lines, the line colors and the shadow, the caption groups that end at each end mark, the words in capitals, the times of the captions, the time of each line, the lines by their top words, the width of a measured line, the place of a line, the tags of the size, the stroke, the shadow and the color, the text of a line with the word gap and the boxes of the bars come from SpokenLineSettings, caption_groups_at_marks, group_in_capitals, shown_captions, line_turns, lines_by_top_words, ends_with_end_mark, line_size, line_width, size_tags, border_tag, shadow_is_seen, fill_and_outline_tags, word_gap_line_text, drawing_style_line, CaptionBox and middle_box_text of effect_common.

Source file: captionbob/effects/ribbon.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`6`	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	`"Ubuntu"`	Name of the font of the text.
`font_size`	integer	`68`	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	`2.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6667`	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	`40`	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.25`	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	`17.7`	Room in pixels between the bottom of the top line and the top of the second line, when the second line is spoken. 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	`27`	The most letters, with the spaces, of a caption that stays on one line and of the top line of a caption of two lines, 1 or above.
`line_colors`	list	`["#8A2717", "#5F551A", "#171615"]`	The colors of the bars of the spoken line, as "#RRGGBB". The captions take them in turn.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`6.0`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`12.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.25`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`5.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`word_gap`	number	`-3.5`	Room in pixels that is added to each space, at the letter width. A value below 0 puts the words closer.
`top_line_words`	integer	`3`	The most words of a caption that stays on one line when it does not end with an end mark, and of the top line of a caption of two lines, 1 or above.
`bar_height`	number	`8.6`	The height of a bar in pixels, above 0.
`bar_drop`	number	`6.7`	Room in pixels between the bottom of a line and the top of its bars. A value below 0 puts the bars higher.
`bar_room`	number	`5.7`	Room in pixels that the bars of the spoken line take below it. A line below the spoken line stands this room lower. 0 keeps the lines at their places.
`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.

RibbonSettings

@dataclass(frozen=True)
class RibbonSettings(SpokenLineSettings)

The look and the timing of the ribbon 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, then the line colors and the shadow of SpokenLineSettings, and then the word gap, the top line words, the settings of the bars 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, when the second line is spoken. 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 caption that stays on one line and of the top line of a caption of two lines, 1 or above.
line_colors: The colors of the bars of the spoken line, as "#RRGGBB". The captions take them in turn.
shadow_color: The color of the shadow, as "#RRGGBB".
shadow_spread: How far the shadow reaches past the outline, in pixels.
shadow_blur: How far the edge of the shadow fades out, in pixels.
shadow_opacity: The strength of the shadow, from 0 for no shadow to 1.
shadow_drop: How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
word_gap: Room in pixels that is added to each space, at the letter width. A value below 0 puts the words closer.
top_line_words: The most words of a caption that stays on one line when it does not end with an end mark, and of the top line of a caption of two lines, 1 or above.
bar_height: The height of a bar in pixels, above 0.
bar_drop: Room in pixels between the bottom of a line and the top of its bars. A value below 0 puts the bars higher.
bar_room: Room in pixels that the bars of the spoken line take below it. A line below the spoken line stands this room lower. 0 keeps the lines at their places.
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".

RibbonSettings.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. At least one word.

Returns:

One line when the caption ends with an end mark and has the line letters or fewer, with its spaces. Else the lines of lines_by_top_words with the top line words and the line letters.

RibbonSettings.line_scale

def line_scale(
        self, places: Sequence[MeasuredPlace], video: VideoInfo) -> float

Give the size of one line, so that it fits between the side margins.

The width of the line is the width of its letters at the letter width, the word gaps and the stroke on each side.

Args:

places: The place of each word of the line, as the caption measure gives them at the width of the font.
video: The video on which the captions are drawn.

Returns:

WHOLE for a line that fits, else the part of the full size at which it fits.

RibbonSettings.line_text_bottom

def line_text_bottom(
        self, line_index: int, caption_bottom: int,
        scale: float) -> float

Give the row of the bottom of one line at its own place.

The top line keeps its bottom when it gets smaller, and a line below it keeps its top.

Args:

line_index: The line, TOP_LINE for the top line.
caption_bottom: The row of the bottom of the top line.
scale: The size of the line as a part of its full size.

Returns:

The row of the bottom of the line.

RibbonSettings.has_shadow

def has_shadow(self) -> bool

Say if the shadow can be seen: it has strength, and it reaches past the letters.

RibbonLine

class RibbonLine(NamedTuple)

One line of a caption, with the places of its words.

Args:

words: The words of the line, as the effect shows them.
places: The place of each word, as the caption measure gives them at the width of the font.
scale: The size of the line as a part of its full size.

RibbonCaption

class RibbonCaption(NamedTuple)

One caption of the ribbon effect.

Args:

caption: The caption with the times of its events and its words as the effect shows them.
lines: The lines of the caption from the top.
bar_color: The line color of the caption, the color of its bars.

PlaceSpan

class PlaceSpan(NamedTuple)

A time in which one line of a caption stands at one place.

Args:

start_centiseconds: Time at which the line takes the place.
end_centiseconds: Time at which the line leaves the place.
drop: How far the line is below its own place, in pixels.

RibbonEffect

class RibbonEffect
    def __init__(
            self, settings: RibbonSettings,
            caption_measure: PlaceMeasure) -> None

Builds the ASS script of the ribbon effect.

Args:

settings: The look and the timing of the effect.
caption_measure: Gives the places at which libass draws the words.

RibbonEffect.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 a shadow event and a text event for each place that it takes, and each word of the spoken line has a bar event. A caption starts with its first word. 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, when libass draws no pixel for a word, or when the caption measure draws a line in more than one row.
RuntimeError: When the ffmpeg of the caption measure fails.