captionbob.effects.arcade

The arcade effect: bold white words with a teal neon glow.

Each caption shows up to three words in bold white letters, in the case of the transcript and with no end marks, such as commas. A caption ends at each end mark. The letters spread a little past the shapes of the font, which makes them heavier, and a thin dark stroke lies around them.

Each word glows in the glow color. The glow of the word that is spoken is wider, softer and stronger than the glow of the other words, and it goes back to the glow of the other words when the next word starts. The keyword of a caption, its longest word when that word is long enough, has the keyword colors in turn and glows in the keyword glow color. A caption with no such word has no keyword.

A caption shows whole from the start of its first word, with no move and no fade. It stays on one line up to the line letters, and a longer caption has two lines: 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 and has three events: the glow under the stroke under the letters.

The settings of the lines and their places, the captions with their lines, their times and their keywords, the keyword colors in turn, the tags of each word with a keyword, the spoken time of each word and its look in that time, the tags of the colors of the letters and of their spread, the tags of a glow, the text of a line 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/arcade.py

Settings

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

Setting	Type	Default	Description
most_words	integer	3	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"	Name of the font of the text.
font_size	integer	78	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	2.0	Width of the outline in pixels. 0 gives no outline.
bottom_position	number	0.6714	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	1.15	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	13.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	false	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	13	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
letter_spread	number	1.5	How far the letters spread past the shapes of the font, in pixels, in their own color.
keyword_colors	list	["#F3FF6B", "#EB1D9A", "#2DFFFE"]	The colors of the letters of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
glow_color	string	"#00FFF0"	The color of the glow of the words, as "#RRGGBB".
keyword_glow_color	string	"#FF0A96"	The color of the glow of a keyword, as "#RRGGBB".
glow_spread	number	8.0	How far the glow of a word that is not spoken reaches past the stroke, in pixels.
glow_blur	number	14.0	How far the edge of that glow fades out, in pixels.
glow_opacity	number	0.36	The strength of that glow, from 0 to 1.
spoken_glow_spread	number	16.0	How far the glow of the spoken word reaches past the stroke, in pixels.
spoken_glow_blur	number	32.0	How far the edge of that glow fades out, in pixels.
spoken_glow_opacity	number	0.95	The strength of that glow, from 0 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.

ArcadeSettings

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

The look and the timing of the arcade 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 effect and the hold time. The effect changes the defaults of some of them. The stroke is a dark edge past the spread of the letters. 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.
• letter_spread: How far the letters spread past the shapes of the font, in pixels, in their own color.
• keyword_colors: The colors of the letters of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
• glow_color: The color of the glow of the words, as "#RRGGBB".
• keyword_glow_color: The color of the glow of a keyword, as "#RRGGBB".
• glow_spread: How far the glow of a word that is not spoken reaches past the stroke, in pixels.
• glow_blur: How far the edge of that glow fades out, in pixels.
• glow_opacity: The strength of that glow, from 0 to 1.
• spoken_glow_spread: How far the glow of the spoken word reaches past the stroke, in pixels.
• spoken_glow_blur: How far the edge of that glow fades out, in pixels.
• spoken_glow_opacity: The strength of that glow, from 0 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 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 keyword colors are not a tuple of one color or more.

ArcadeEffect

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

Builds the ASS script of up to three bold white words with a teal neon glow that grows on the spoken word, and colored keywords.

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.

ArcadeEffect.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 three events. 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.