captionbob.effects.sunny - captionbob docs

The sunny effect: white title case words that rise in, keywords yellow.

Each caption shows its words in white title case with no end marks: each word starts with a capital, and its other letters keep their case. A caption holds up to five words, and it ends at each end mark, such as a comma. A caption stays on one line up to the line letters. A longer caption is cut into two lines, and the top line holds the larger half of the words. The top line stands on the bottom position, and the second line hangs the line gap below it.

The keywords of a caption are yellow, in a bold font and a little wider. A space next to a keyword is wider by the keyword gap, so that the glow of the keyword keeps a clear space from the words next to it. Each word has a soft glow in the color of its letters.

The words of a caption show one by one at their places in the caption. A word shows at the start of its word: it fades in, slowly at the start, and it rises from the rise height below its place into its place in the fade time. The caption leaves at once when it ends.

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

The settings of the lines, the captions with their lines and keywords, the places of the lines, the rise of each word with the time at which it shows and the tags of its fade, the keyword colors in turn and the tags of the words with keywords, the font and glow tags and the text of a line with tags for each word and each gap come from LineSettings, line_captions, rise_place_tags, word_rises, rise_appear_centiseconds, power_fade_tags, keywords_in_turn, keyword_word_tags, font_tags, blurred_look_tags and word_lines_text of effect_common.

Source file: captionbob/effects/sunny.py

Settings

The command line and the HTTP API call this effect the style sunny. Its settings class is SunnySettings. 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 Medium"`	Name of the font of the text.
`font_size`	integer	`72`	Height of the font in pixels.
`bold`	boolean	`false`	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	`0.8`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6578`	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.02`	The width of the plain letters as a part of the width that the font gives them, above 0. 1 keeps the width of the font.
`line_gap`	number	`0.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. It wins over the title case.
`end_at_marks`	boolean	`true`	True to end a caption at each end mark, such as a comma.
`line_letters`	integer	`30`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`title_case`	boolean	`true`	True to write the first letter of each word as a capital.
`keyword_font_name`	string	`"Ubuntu"`	Name of the font of the keywords.
`keyword_bold`	boolean	`true`	True for bold keywords.
`keyword_letter_width`	number	`1.08`	The width of the letters of a keyword as a part of the width that its font gives them, above 0.
`keyword_colors`	list	`["#F1FD71"]`	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn. A keyword has an outline of the stroke width in its color.
`keyword_gap`	number	`11.0`	Room in pixels that is added to a space in front of a keyword and to a space behind one, at the plain letter width. A space between two keywords gets it twice.
`glow_spread`	number	`4.5`	How far the glow reaches past the outline, in pixels.
`glow_blur`	number	`8.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.38`	The strength of the glow, from 0 for no glow to 1. The glow of a word has the color of its letters.
`rise_height`	number	`25.0`	How far below its place a word shows at the start of its rise, in pixels. 0 gives no rise, and a value below 0 shows the word above its place.
`fade_seconds`	number	`0.125`	The time in which a word fades in and rises into its place. 0 shows each word in full at its place at once.
`fade_power`	number	`2.6`	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.
`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.

SunnySettings

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

The look and the timing of the sunny 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 title case, the settings of the keywords, of the glow, of the rise and the fade, and the hold time. The effect changes the defaults of some of them. The stroke is the outline of the plain 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 plain 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. It wins over the title case.
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.
title_case: True to write the first letter of each word as a capital.
keyword_font_name: Name of the font of the keywords.
keyword_bold: True for bold keywords.
keyword_letter_width: The width of the letters of a keyword as a part of the width that its font gives them, above 0.
keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn. A keyword has an outline of the stroke width in its color.
keyword_gap: Room in pixels that is added to a space in front of a keyword and to a space behind one, at the plain letter width. A space between two keywords gets it twice.
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. The glow of a word has the color of its letters.
rise_height: How far below its place a word shows at the start of its rise, in pixels. 0 gives no rise, and a value below 0 shows the word above its place.
fade_seconds: The time in which a word fades in and rises into its place. 0 shows each word in full at its place 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.
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 font name cannot stand in a tag, or when a color is not in the form "#RRGGBB".

SunnySettings.has_glow

def has_glow(self) -> bool

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

SunnySettings.plain_font_tags

def plain_font_tags(self) -> str

Write the tags of the font, the weight and the letter width of a plain word, with no curly brackets.

SunnySettings.keyword_font_tags

def keyword_font_tags(self) -> str

Write the tags of the font, the weight and the letter width of a keyword, with no curly brackets.

title_case_text

def title_case_text(text: str) -> str

Write a word with a capital first letter.

Args:

text: The text of one word.

Returns:

The text with its first letter as a capital. The marks in front of the first letter, such as a quote, and the other letters keep their case. A text with no letter stays the same.

SunnyEffect

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

Builds the ASS script of white title case words with a soft glow, which fade in one by one and rise into their places, with bold yellow 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.

SunnyEffect.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 rise has time has a rise glow event and a rise event.

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.