captionbob.effects.lumen - captionbob docs

The lumen effect: small bold white capitals with a soft glow.

Each caption shows up to five words in bold white capitals, with their end marks, such as commas. A caption ends at each end mark. A caption stays on one line up to the line letters. A longer caption has two lines: the top line holds the first top line words, and the second line holds the other words. The top line stands on the bottom position, and the second line hangs the line gap below it. Each line is centred in the video with all its words, and the letters are narrower than the font gives them. Each space is narrower by the word gap.

Each word shows at its start time, at its place in the whole caption. A word that is not due yet is hidden and keeps its room, so the words never move. The caption shows its first word when it starts.

Each line has two events, one above the other. The lower one is the glow: the words in the glow color with a border that is blurred and partly seen. The upper one is the letters in the primary color, with no outline. The words of the glow show at the times of the letters.

The settings of the lines and their places, the caption groups that end at each end mark, the times of the captions, the tag time of each word, the tags that show a word at its time, the text of a line with the word gap in each space, the checks and the tags of the glow and the size tags of the letter width come from effect_common.

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

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`5`	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	`77`	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	`"#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.6554`	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.875`	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	`-19.0`	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	`true`	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	`15`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`top_line_words`	integer	`3`	The words of the top line of a caption that has two lines, 1 or above. A caption with no more words stays on one line.
`word_gap`	number	`-6.125`	Room in pixels that is added to each space, at the letter width. A value below 0 puts the words closer.
`glow_color`	string	`"#FFFFFF"`	The color of the glow, as "#RRGGBB".
`glow_spread`	number	`3.0`	How far the glow reaches past the letters before it is blurred, in pixels.
`glow_blur`	number	`5.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.5`	The strength of the glow, from 0 for no glow to 1.
`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.

LumenSettings

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

The look and the timing of the lumen 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 settings of the top line, the word gap and the glow, and the hold time. The effect changes the defaults of some of them. 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 caption that stays on one line, 1 or above.
top_line_words: The words of the top line of a caption that has two lines, 1 or above. A caption with no more words stays on one line.
word_gap: Room in pixels that is added to each space, at the letter width. A value below 0 puts the words closer.
glow_color: The color of the glow, as "#RRGGBB".
glow_spread: How far the glow reaches past the letters before it is blurred, 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.
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".

LumenSettings.has_glow

def has_glow(self) -> bool

True when the glow has strength and reaches past the letters: it spreads or it is blurred.

LumenSettings.caption_lines

def caption_lines(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 line letters or fewer, with its spaces, or when it has no more words than the top line words. Else two lines: the top line with the top line words, and the second line with the other words.

LumenEffect

class LumenEffect
    def __init__(self, settings: LumenSettings) -> None

Builds the ASS script of up to five words in small bold white capitals with a soft glow, shown word by word at their places.

Args:

settings: The look and the timing of the effect.

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