captionbob.effects.amber

Amber effect: cream serif words with an orange, larger spoken word.

A caption ends at the end of a sentence and, by default, at each other end mark, such as a comma. It shows its words in the case in which they are spoken, with their end marks. A caption whose text is short enough stays on one line. A longer caption puts the words per line on each line from the top, and each next line is one line step below the line above it.

The keyword of a caption, which the keyword picker gives, has its own color for the whole time of the caption. The keywords of a video take the keyword colors in turn. While a word is spoken it is larger, and it has the spoken color, or its keyword color when it is a keyword. It grows around its own middle, and the other words do not move.

Each line of a caption has four events with the times of the caption. The line events draw the words that are not spoken, and they hide the spoken word. The spoken events draw the spoken word alone, larger, with the other words hidden. In each pair, one event draws the shadow and the other draws the letters. The shadow is the letters in the shadow color, with a border that fades out, a little below the letters. The two shadow events are under the two letter events, so no shadow falls on a letter.

libass centres a line on its place. When one word of a line is larger, the line is wider by the growth of that word, and libass moves the words in front of it to the left by half of that growth. So the spoken word grows by the same width on its two sides, and the hidden words, which move, are not seen.

Source file: captionbob/effects/amber.py

Settings

The command line and the HTTP API call this effect the style amber. Its settings class is AmberSettings. 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	"DejaVu Serif"	Name of the font of the text.
font_size	integer	82	Height of the font in pixels.
bold	boolean	true	True for bold text.
primary_color	string	"#E9D9BF"	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.681	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.91	The width of the letters as a part of the width that the font gives them, above 0.
spoken_color	string	"#F19D57"	The color of a spoken word that is not a keyword, as "#RRGGBB".
spoken_scale	number	1.1	The size of a spoken word as a part of the size of the other words, above 0.
keyword_colors	list	["#F6CF8F", "#E8594D"]	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
line_letters	integer	14	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
words_per_line	integer	3	The words of each line of a caption that does not stay on one line, 1 or above. The last line has the words that are left.
line_step	number	93.0	How far the middle of a line is below the middle of the line above it, in pixels.
shadow_color	string	"#000000"	The color of the shadow, as "#RRGGBB".
shadow_spread	number	4.0	How far the shadow reaches past the letters, in pixels, before it fades out.
shadow_blur	number	18.0	How far the edge of the shadow fades out, in pixels.
shadow_opacity	number	0.25	The strength of the shadow, from 0 for no shadow to 1.
shadow_drop	number	7.0	How far the shadow is below the letters, in pixels. A value below 0 puts it above them.
end_at_marks	boolean	true	True to end a caption at each end mark, such as a comma. A caption always ends at the end of a sentence.
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.

AmberSettings

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

The look and the timing of the amber effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The primary color is the color of the words that are not keywords. The stroke color and the stroke width give the outline of the style line, which the events of the effect do not use. The bottom position is the bottom of the first row of a caption. These settings follow them.

Args:

• letter_width: The width of the letters as a part of the width that the font gives them, above 0.
• spoken_color: The color of a spoken word that is not a keyword, as "#RRGGBB".
• spoken_scale: The size of a spoken word as a part of the size of the other words, above 0.
• keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
• line_letters: The most letters, with the spaces, of a caption that stays on one line, 1 or above.
• words_per_line: The words of each line of a caption that does not stay on one line, 1 or above. The last line has the words that are left.
• line_step: How far the middle of a line is below the middle of the line above it, in pixels.
• shadow_color: The color of the shadow, as "#RRGGBB".
• shadow_spread: How far the shadow reaches past the letters, in pixels, before it fades out.
• shadow_blur: How far the edge of the shadow fades out, in pixels.
• shadow_opacity: The strength of the shadow, from 0 for no shadow to 1.
• shadow_drop: How far the shadow is below the letters, in pixels. A value below 0 puts it above them.
• end_at_marks: True to end a caption at each end mark, such as a comma. A caption always ends at the end of a sentence.
• 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.

caption_lines

def caption_lines(
        words: Sequence[Word], line_letters: int,
        words_per_line: int) -> list[list[Word]]

Cut the words of a caption into its lines.

Args:

• words: The words of the caption, as the effect shows them.
• line_letters: The most letters, with the spaces, of a caption that stays on one line.
• words_per_line: The words of each line of a longer caption.

Returns:

One line when the caption is short enough. Else the lines from the top, each with the words per line, the last line with the words that are left.

AmberEffect

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

Builds the ASS script of the amber effect.

Args:

• settings: The look and the timing of the effect.
• keyword_picker: Gives the places of the keywords of a caption. The default gives the longest word of a caption when it has KEYWORD_FEWEST_LETTERS letters or more.

AmberEffect.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 caption starts with its first word. It ends 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 the place of a word of a caption.