captionbob.effects.grace - captionbob docs

Grace effect: white serif words that fade in one by one, with a glow.

Each caption shows up to six words in white serif letters, 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. A caption of up to five words stands in one line when that line fits between the side margins. A longer caption, or a caption whose one line does not fit, is cut into lines of four words, one below the other.

Each word fades in at its place when it starts, so the caption builds up word by word and its lines do not move. A caption leaves at once when the next caption starts, and at the latest the hold time after its last word.

The letters have a thin outline in their own color, which makes them a little heavier, and a soft glow. The glow is the text in the glow color under the letters, with an outline that is wider than the stroke by the glow radius and that fades out over the glow blur. A keyword is larger than the other words, and a line that holds a keyword is higher by the growth of the font.

The caption measure gives the width of each line. A keyword that makes its line too wide gets smaller, down to the size of the other words. A caption with a line that is still too wide gets smaller as a whole.

Each line of a caption is one glow event and one text event. Each event places the top middle of its line, so the lines stand the line height apart.

Source file: captionbob/effects/grace.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`6`	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	`"DejaVu Serif"`	Name of the font of the text.
`font_size`	integer	`112`	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	`"#FFFFFF"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`1.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.7219`	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.83`	The width of the letters, as a part of the width that the font gives them.
`line_height`	number	`94.6`	The rows from the top of one line of a caption to the top of the next line.
`end_at_marks`	boolean	`true`	True to end a caption also at each word that ends with an end mark, such as a comma.
`most_line_words`	integer	`5`	The most words of a caption that stands in one line.
`line_words`	integer	`4`	The words of each line of a longer caption. The last line holds the words that are left.
`fade_seconds`	number	`0.1`	The time in which a word fades in. 0 shows each word at once.
`glow_color`	string	`"#FFFFFF"`	Color of the glow, as "#RRGGBB".
`glow_radius`	number	`1.0`	How far the glow reaches past the stroke before it fades out, in pixels.
`glow_blur`	number	`11.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.8`	The strength of the glow, from 0 for no glow to 1.
`keyword_scale`	number	`1.43`	The size of a keyword as a part of the size of the other words.
`hold_seconds`	number	`0.2`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

GraceSettings

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

The look and the timing of the grace 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 stroke is a thin outline of the letters. The bottom position is the bottom of the top line of a caption, and the lines below it stand the line height apart.

Args:

letter_width: The width of the letters, as a part of the width that the font gives them.
line_height: The rows from the top of one line of a caption to the top of the next line.
end_at_marks: True to end a caption also at each word that ends with an end mark, such as a comma.
most_line_words: The most words of a caption that stands in one line.
line_words: The words of each line of a longer caption. The last line holds the words that are left.
fade_seconds: The time in which a word fades in. 0 shows each word at once.
glow_color: Color of the glow, as "#RRGGBB".
glow_radius: How far the glow reaches past the stroke before it fades out, in pixels.
glow_blur: How far the edge of the glow fades out, in pixels.
glow_opacity: The strength of the glow, from 0 for no glow to 1.
keyword_scale: The size of a keyword as a part of the size of the other words.
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.

GraceSettings.has_glow

@property
def has_glow(self) -> bool

True when the glow reaches past the letters and can be seen.

GraceSettings.glow_style_line

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

Write the ASS style line of the glow 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 glow of the captions.

Raises:

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

GraceEffect

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

Builds the ASS script of white serif words that fade in one by one, with a soft glow and a larger keyword.

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 nine letters or more.

GraceEffect.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 a caption has a glow event and a 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, 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.