captionbob.effects.azure - captionbob docs

Azure effect: white words on a dark box, with the spoken word in blue.

Each caption shows up to five words in one line, in the case in which they are spoken and with their end marks. A caption also ends at each end mark, such as a comma or a full stop. The words are white, in a medium weight of the font, and they stand on a black box with round corners that lets the video show through.

Each word turns pale blue while it is spoken and white again after it. A keyword of a caption is bold, in a heavier font with a thin outline in its own color. The keywords of a video take the keyword colors in turn. A keyword also turns pale blue while it is spoken, with its outline, and it has its keyword color before and after it.

The caption measure gives the width of each line in the font of the words, and the width of each keyword in the font of the keywords. The box is as wide as the line plus the side padding on each side, from middle_line_box of effect_common. A caption whose line does not fit between the side margins gets smaller as a whole, with its box.

A caption leaves at once when the next caption starts, and at the latest the hold time after its last word. Each caption is one box event and one text event over it.

Source file: captionbob/effects/azure.py

Settings

The command line and the HTTP API call this effect the style azure. Its settings class is AzureSettings. 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 Medium"`	Name of the font of the text.
`font_size`	integer	`78`	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.6802`	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.88`	The width of the letters, as a part of the width that the font gives them.
`end_at_marks`	boolean	`true`	True to end a caption also at each word that ends with an end mark, such as a comma.
`spoken_color`	string	`"#93E4FB"`	Color of a word while it is spoken, as "#RRGGBB". A keyword and its outline have this color too while it is spoken.
`keyword_colors`	list	`["#FFFFFF", "#B5F2FF"]`	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
`keyword_font_name`	string	`"Ubuntu"`	Name of the font of a keyword.
`keyword_bold`	boolean	`true`	True for a bold keyword.
`keyword_letter_width`	number	`0.89`	The width of the letters of a keyword, as a part of the width that its font gives them.
`keyword_stroke_width`	number	`1.2`	Width in pixels of the outline of a keyword, which has the color of the keyword. 0 gives no outline.
`box_color`	string	`"#000000"`	Color of the box behind a caption, as "#RRGGBB".
`box_opacity`	number	`0.38`	The strength of the box, from 0 for no box to 1 for a box that hides the video.
`box_side_padding`	number	`35.0`	Room in pixels between the text and the left and the right edge of the box.
`box_vertical_padding`	number	`16.0`	Room in pixels between the line of the text and the top and the bottom edge of the box.
`box_radius`	number	`12.0`	The radius of the corners of the box in pixels.
`hold_seconds`	number	`0.1`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

AzureSettings

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

The look and the timing of the azure 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 primary color is the color of a word that is not spoken, and the bottom position is the bottom of the line of a caption.

Args:

letter_width: The width of the letters, as a part of the width that the font gives them.
end_at_marks: True to end a caption also at each word that ends with an end mark, such as a comma.
spoken_color: Color of a word while it is spoken, as "#RRGGBB". A keyword and its outline have this color too while it is spoken.
keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
keyword_font_name: Name of the font of a keyword.
keyword_bold: True for a bold keyword.
keyword_letter_width: The width of the letters of a keyword, as a part of the width that its font gives them.
keyword_stroke_width: Width in pixels of the outline of a keyword, which has the color of the keyword. 0 gives no outline.
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 text and the left and the right edge of the box.
box_vertical_padding: Room in pixels between the line of the text and the top 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, when a color is not in the form "#RRGGBB", or when a font name is empty or holds a mark that it cannot hold.

AzureSettings.has_box

@property
def has_box(self) -> bool

True when the box behind a caption can be seen.

AzureSettings.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.

AzureEffect

class AzureEffect
    def __init__(
            self, settings: AzureSettings, caption_measure: PlaceMeasure,
            keyword_picker: KeywordPicker = DEFAULT_KEYWORD_PICKER) -> None

Builds the ASS script of white words on a dark box, with the spoken word in pale blue and bold keywords.

Args:

settings: The look and the timing of the effect.
caption_measure: The measure that says where libass draws each word of a caption. Its ffmpeg must be the ffmpeg that draws the video.
keyword_picker: Names the keywords of each caption. With no value, the keyword of a caption is its longest word when that word has seven letters or more.

AzureEffect.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, when the keyword picker gives a place that is not a word of its caption, or when libass draws no pixel for a word in the caption measure.
RuntimeError: When the ffmpeg of the caption measure fails.