captionbob.effects.verse - captionbob docs

The verse effect: white words that fade in one by one, with keywords in a slanted serif or with a soft white glow.

Each caption shows up to four words, as spoken, with their end marks. A caption also ends at each end mark, such as a comma or a full stop. A caption with more words than the top line words, or with more letters than the line letters, has two lines: the top line holds the first words, and the second line hangs below it. The whole caption is laid out when it starts, and each word fades in at its place when it is spoken. A caption leaves at once when it ends.

The words are a bold sans serif with the letters a little closer than the font sets them. A keyword is in a slanted serif, or it keeps the look of the words and has a soft white glow. The keywords of a video take the keyword turns in order.

Each line of a caption is one text event on the top layer. A line with a glowing keyword also has a glow event on the layer below it. The glow event holds all the words of its line in the same runs as the text event, so the glow keyword has the same place in both events, and it shows only the glow of that keyword.

The caption groups that end at each end mark, the line split by the words and the letters of the top line, the places of the lines, the tag times of the words and their fade in, the keywords and their turns, the font, size, spacing, border, blur and color tags, and the text of a line with tags for each word and each gap come from caption_groups_at_marks, lines_by_top_words, LineSettings, word_tag_times, fade_in_tags, keyword_places, keywords_in_turn, keyword_word_tags, font_tags, size_tags, spacing_tag, border_tag, blur_tag, fill_and_outline_tags and word_lines_text of effect_common.

Source file: captionbob/effects/verse.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`4`	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	`112`	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	`0.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.7271`	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.92`	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	`-21.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	`16`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`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.
`letter_spacing`	number	`-1.84`	Room in pixels after each letter of a word, at the letter width. A value below 0 puts the letters closer.
`fade_seconds`	number	`0.08`	The time in which a word fades in, 0 or above. 0 shows a word at once.
`keyword_font_name`	string	`"DejaVu Serif"`	Name of the font of a serif keyword.
`keyword_bold`	boolean	`false`	True for a bold serif keyword.
`keyword_italic`	boolean	`true`	True to slant the letters of a serif keyword.
`keyword_scale`	number	`0.98`	The size of a serif keyword as a part of the font size, above 0.
`keyword_letter_width`	number	`0.755`	The width of the letters of a serif keyword as a part of the width that its font gives them at its size, above 0.
`keyword_stroke_width`	number	`0.7`	Width in pixels of the stroke of a serif keyword, in the stroke color, 0 or above.
`keyword_turns`	list	`["serif", "glow", "serif"]`	The looks of the keywords, each SERIF_LOOK or GLOW_LOOK. The keywords of a video take them in order, and the order starts again when it ends.
`glow_color`	string	`"#FFFFFF"`	The color of the glow of a glow keyword, as "#RRGGBB".
`glow_spread`	number	`0.0`	How far the glow reaches past the letters before it fades out, in pixels.
`glow_blur`	number	`10.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.5`	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, 0 or above.

VerseSettings

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

The look and the timing of the verse effect.

The settings of LineSettings come first: the word counts, the font, the colors, the stroke, the bottom position, the side margin, the letter width, the line gap, the capitals, the end at marks and the line letters. The top line words, the letter spacing, the fade time, the settings of the keywords, of their turns and of the glow, and the hold time follow them. The effect changes the defaults of some of them. The bottom position is the bottom of the top line, and the line letters are the most letters, with the spaces, of a top line.

Args:

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.
letter_spacing: Room in pixels after each letter of a word, at the letter width. A value below 0 puts the letters closer.
fade_seconds: The time in which a word fades in, 0 or above. 0 shows a word at once.
keyword_font_name: Name of the font of a serif keyword.
keyword_bold: True for a bold serif keyword.
keyword_italic: True to slant the letters of a serif keyword.
keyword_scale: The size of a serif keyword as a part of the font size, above 0.
keyword_letter_width: The width of the letters of a serif keyword as a part of the width that its font gives them at its size, above 0.
keyword_stroke_width: Width in pixels of the stroke of a serif keyword, in the stroke color, 0 or above.
keyword_turns: The looks of the keywords, each SERIF_LOOK or GLOW_LOOK. The keywords of a video take them in order, and the order starts again when it ends.
glow_color: The color of the glow of a glow keyword, as "#RRGGBB".
glow_spread: How far the glow reaches past the letters before it fades out, 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, 0 or above.

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, when a color is not in the form "#RRGGBB", when the keyword font name cannot stand in a tag, or when a keyword turn is not a known look.

VerseSettings.word_font_tags

def word_font_tags(self) -> str

Write the tags of the font, the size, the room and the stroke of a word that is not a serif keyword, with no curly brackets.

VerseSettings.keyword_font_tags

def keyword_font_tags(self) -> str

Write the tags of the font, the slant, the size, the room and the stroke of a serif keyword, with no curly brackets.

VerseSettings.glow_look_tags

def glow_look_tags(self) -> str

Write the tags of the border, the blur and the color of the glow of a glow keyword, with no curly brackets.

VerseEffect

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

Builds the ASS script of white words that fade in one by one, with keywords in a slanted serif or with a soft white glow.

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.

VerseEffect.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 a caption has a text event, and a line with a glow keyword also has a glow 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.

VerseEffect.caption_events

def caption_events(
        self, caption: ShownCaption, keyword_looks: Mapping[int, str],
        middle_x: float, caption_bottom: int) -> list[str]

Write the glow events and the text events of one caption.

Args:

caption: The caption with the times of its events and its words as spoken.
keyword_looks: The look of each keyword place of the caption, SERIF_LOOK or GLOW_LOOK.
middle_x: The column of the middle of the video.
caption_bottom: The row of the bottom of the top line.

Returns:

The dialogue lines of the caption: for each line from the top, its glow event when it has a glow keyword, then its text event.