captionbob.effects.volt - captionbob docs

The volt effect: heavy narrow light blue capitals with a blue glow.

Each caption shows its words in heavy narrow capitals, light blue, with no end marks. A caption ends at each end mark, such as a comma. A short caption stays on one line. A longer caption is cut into two lines, and the top line takes the larger half of the words. A keyword is white for the whole caption. A blue glow lies around the letters. A caption rises a few pixels into its place when it shows, and its letters get a little narrower while it shows.

Each line of a caption has two events with the times of the caption. The glow event draws the letters in the glow color, with a border that fades out. The text event draws the letters over it, with an outline in the color of the letters that makes them heavier. The top line stands on the caption bottom, and the second line hangs from the line gap below it. Both events of a line move up by the rise in the rise time, and both get narrower in the shrink time. The settings of the lines, the captions with their lines and keywords, the places of the lines and the tags of the rise come from LineSettings, line_captions and rise_place_tags of effect_common.

Source file: captionbob/effects/volt.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`5`	The most words that one caption shows.
`fewest_words`	integer	`4`	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	`121`	Height of the font in pixels.
`bold`	boolean	`true`	True for bold text.
`primary_color`	string	`"#63B5FA"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#63B5FA"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`3.6`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.717`	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.585`	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	`-14.4`	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	`20`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`word_gap`	number	`14.3`	Room in pixels that is added to each space between two words, at the letter width. 0 keeps the space of the font.
`keyword_colors`	list	`["#FFFFFF"]`	The colors of the keywords, as "#RRGGBB". The letters of a keyword and their outline take the color. The keywords take the colors in turn.
`glow_color`	string	`"#549CFF"`	The color of the glow, as "#RRGGBB".
`glow_spread`	number	`6.7`	How far the glow reaches past the outline, in pixels.
`glow_blur`	number	`9.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.65`	The strength of the glow, from 0 for no glow to 1.
`rise`	number	`6.6`	How far below its place a caption shows at its start, in pixels. A value below 0 puts it above its place.
`rise_seconds`	number	`0.3`	The time in which a caption moves into its place. 0 shows it in its place at once.
`shrink`	number	`0.973`	The width of the letters at the end of the shrink time, as a part of their width at the start of the caption, above 0. 1 keeps their width, and a value above 1 makes them wider.
`shrink_delay_seconds`	number	`0.2`	The time from the start of a caption to the start of the shrink.
`shrink_seconds`	number	`2.0`	The time in which the letters change to the shrink width. 0 keeps their width.
`shrink_ease`	number	`0.5`	The power of the curve of the shrink, above 0. 1 gives one speed. A value below 1 is fast at the start and slow at the end.
`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.

VoltSettings

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

The look and the timing of the volt 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 keywords, of the glow, of the rise and of the shrink, and the hold time. The effect changes the defaults of some of them. The primary color is the color of the words that are not keywords. The stroke is the outline of the letters, 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 caption that stays on one line, 1 or above.
word_gap: Room in pixels that is added to each space between two words, at the letter width. 0 keeps the space of the font.
keyword_colors: The colors of the keywords, as "#RRGGBB". The letters of a keyword and their outline take the color. The keywords take the colors in turn.
glow_color: The color of the glow, as "#RRGGBB".
glow_spread: How far the glow reaches past the outline, 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.
rise: How far below its place a caption shows at its start, in pixels. A value below 0 puts it above its place.
rise_seconds: The time in which a caption moves into its place. 0 shows it in its place at once.
shrink: The width of the letters at the end of the shrink time, as a part of their width at the start of the caption, above 0. 1 keeps their width, and a value above 1 makes them wider.
shrink_delay_seconds: The time from the start of a caption to the start of the shrink.
shrink_seconds: The time in which the letters change to the shrink width. 0 keeps their width.
shrink_ease: The power of the curve of the shrink, above 0. 1 gives one speed. A value below 1 is fast at the start and slow at the end.
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 or the line letters 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.

VoltSettings.has_glow

def has_glow(self) -> bool

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

VoltSettings.glow_width

def glow_width(self) -> float

Give the width of the border of the glow: the stroke and the spread, in pixels.

VoltEffect

class VoltEffect
    def __init__(
            self, settings: VoltSettings,
            keyword_picker: KeywordPicker = DEFAULT_KEYWORD_PICKER) -> None

Builds the ASS script of heavy narrow light blue capitals with a blue glow and white keywords, which rise into their place and get narrower.

Args:

settings: The look and the timing of the effect.
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.

VoltEffect.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, or when the keyword picker gives a place that is not a word of its caption.