captionbob.effects.silk - captionbob docs

The silk effect: white sentence case, the spoken line bold.

Each caption shows its words in white letters, in the case in which they are spoken and with no end marks. A caption holds up to four words, and it ends at each end mark, such as a comma. A caption stays on one line up to the line letters, and a longer caption is cut into two lines. The line whose words are spoken is in the bold font, and the other line is in the light font, at the same size. A faint soft shadow lies under the letters. A caption fades in at its start, and it goes with no fade.

The time of a caption is cut into one turn for each of its lines. The turn of a line starts with its first word and ends when the turn of the next line starts, or with the caption. libass cannot change a font inside an event, so each line of each turn has two events with the times of the turn. The shadow event draws the letters in the shadow color, with a blur that fades out. The text event draws the letters over it. The fade starts with the caption, so a turn that starts in the fade starts with the strength that the fade has at that time. Each space of a line gets the word gap.

The settings of the lines, the captions with their lines, the places of the lines, the turns of the lines, the fade in and the check that the shadow is seen come from LineSettings, line_captions, line_turns, fade_in_tags and shadow_is_seen of effect_common.

Source file: captionbob/effects/silk.py

Settings

The command line and the HTTP API call this effect the style silk. Its settings class is SilkSettings. 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	`76`	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	`0.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.662`	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.16`	The width of the letters of the spoken line 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.
`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.
`word_gap`	number	`-6.0`	Room in pixels that is added to each space between two words, at the letter width of the line. A value below 0 puts the words closer. 0 keeps the space of the font.
`light_font_name`	string	`"Ubuntu Light"`	Name of the font of the line that is not spoken. It is never bold.
`light_letter_width`	number	`1.1`	The width of the letters of the light font as a part of the width that the font gives them, above 0.
`fade_seconds`	number	`0.13`	The time in which a caption fades in from its start. 0 shows it at its full strength at once.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`0.0`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`5.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.6`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`0.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`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.

SilkSettings

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

The look and the timing of the silk 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 word gap, the settings of the light font, of the fade and of the shadow, and the hold time. The effect changes the defaults of some of them. The font, the bold and the letter width are those of the spoken line. The stroke is the outline of the letters. The bottom position is the bottom of the top line.

Args:

letter_width: The width of the letters of the spoken line 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 of the line. A value below 0 puts the words closer. 0 keeps the space of the font.
light_font_name: Name of the font of the line that is not spoken. It is never bold.
light_letter_width: The width of the letters of the light font as a part of the width that the font gives them, above 0.
fade_seconds: The time in which a caption fades in from its start. 0 shows it at its full strength at once.
shadow_color: The color of the shadow, as "#RRGGBB".
shadow_spread: How far the shadow reaches past the outline, in pixels.
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 the shadow above them.
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 a font name is empty or holds a backslash, a curly bracket or a comma.

SilkSettings.has_shadow

def has_shadow(self) -> bool

True when the shadow has strength and reaches past the letters: it spreads, it is blurred or it is below or above them.

SilkSettings.line_letter_width

def line_letter_width(self, spoken: bool) -> float

Give the letter width of a line.

Args:

spoken: True for the line whose words are spoken.

Returns:

The letter width of the spoken line, or of the light font.

SilkSettings.line_font_tags

def line_font_tags(self, spoken: bool) -> str

Write the tags of the font, the weight and the size of a line.

Args:

spoken: True for the line whose words are spoken.

Returns:

The tags with no curly brackets. The spoken line has the font and the bold of the settings, and the other line the light font.

SilkEffect

class SilkEffect
    def __init__(self, settings: SilkSettings) -> None

Builds the ASS script of white words in sentence case whose spoken line is bold and whose other line is light.

Args:

settings: The look and the timing of the effect.

SilkEffect.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 turn of each caption has a shadow event, when the shadow can be seen, and a text event. The first turn starts with the first word of its caption. The last turn 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.