captionbob.effects.mist - captionbob docs

The mist effect: small white capitals with a soft glow, whose words fade in one by one.

Each caption shows its words in small, heavy white capitals with no end marks, and a soft white glow lies around the letters. 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 when it has the line letters or fewer. A longer caption is cut into two lines: the top line holds up to the 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.

The words of a caption show one by one at their places in the caption. A word fades in from its start in the fade time, slowly at first and fast at the end, and its glow fades in with it. The caption leaves at once when it ends.

Each line of a caption has a glow event and a text event with the times of the caption. In them each word is hidden until its fade is over, and then it shows. Each word has a glow fade event and a text fade event from the start of its word to the end of its fade. A fade event writes the whole line of the word with the other words hidden, so the word has its place in the line. The four kinds of events are on four layers, and the glow events are under all the text events.

The settings of the lines, the lines of a caption by the words of its top line, the caption groups that end at each end mark, the words in capitals with no end marks, the fade of each word with the time at which it shows and the tags of its fade, the tags that show a word at a time, the check and the tags of the glow and the text of a line with a word gap come from LineSettings, lines_by_top_words, caption_groups_at_marks, shown_group, word_rises, rise_appear_centiseconds, power_fade_tags, appear_at_alpha_tags, require_glow, shadow_is_seen, border_tag, blur_tag, fill_and_outline_tags and word_gap_line_text of effect_common.

Source file: captionbob/effects/mist.py

Settings

The command line and the HTTP API call this effect the style mist. Its settings class is MistSettings. 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	`51`	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	`1.9`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6385`	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.98`	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	`12.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	`28`	The most letters, with the spaces, of a top line, 1 or above. A caption of the top line words or fewer with this many letters or fewer stays on one line.
`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. The second line holds at least one word.
`word_gap`	number	`2.2`	Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
`fade_seconds`	number	`0.2`	The time in which a word fades in. 0 shows each word in full at once.
`fade_power`	number	`1.8`	The power of the part of the fade time that gives the strength of a word, above 0. 1 gives a fade at one speed, and a power above 1 a fade that is slow at the start.
`glow_color`	string	`"#FFFFFF"`	The color of the glow, as "#RRGGBB".
`glow_spread`	number	`7.9`	How far the glow reaches past the letters before it is blurred, in pixels.
`glow_blur`	number	`11.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.45`	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.

MistSettings

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

The look and the timing of the mist 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 fade and of the glow, 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 top line, 1 or above. A caption of the top line words or fewer with this many letters or fewer stays on one line.
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. The second line holds at least one word.
word_gap: Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
fade_seconds: The time in which a word fades in. 0 shows each word in full at once.
fade_power: The power of the part of the fade time that gives the strength of a word, above 0. 1 gives a fade at one speed, and a power above 1 a fade that is slow at the start.
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".

MistSettings.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:

The lines of lines_by_top_words with the top line words and the line letters of the settings.

MistSettings.has_glow

def has_glow(self) -> bool

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

MistSettings.fade_tags

def fade_tags(self, shown_alpha: str) -> str

Write the tags of a word that fades in from the start of its fade event.

Args:

shown_alpha: The value of the alpha tag of the word when it is shown, such as SHOWN_ALPHA or the alpha of the glow.

Returns:

The tags with no curly brackets. The word is hidden at the start, and its strength grows with the fade power of the part of the fade time that is over.

MistLook

class MistLook(NamedTuple)

One look of the words of a line: the glow or the letters.

Args:

layer: The layer of the events of the lines.
fade_layer: The layer of the fade events of the words.
tags: The tags of the look, with no curly brackets.
shown_alpha: The value of the alpha tag of a word that is shown.

MistCaptionEvents

class MistCaptionEvents(NamedTuple)

The events of one caption.

Args:

events: The dialogue lines: the events of each line from the top, then the fade events of each word in the order of the words.
word_fades: The number of words that have a fade.

MistEffect

class MistEffect
    def __init__(self, settings: MistSettings) -> None

Builds the ASS script of small white capitals with a soft glow, whose words fade in one by one.

Args:

settings: The look and the timing of the effect.

MistEffect.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. These 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. Each word whose fade has time has a glow fade event and a text fade event. A glow that cannot be seen has no events.

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.