captionbob.effects.tiger - captionbob docs

The tiger effect: heavy orange capitals that lean, shown word by word.

Each caption shows up to two words in one line, in capitals, with their end marks, such as a comma or a full stop. A caption also ends at each end mark. The letters are heavy orange capitals that lean to the right. They spread past the shapes of the font in their own orange, with a thin dark red outline around the spread and a soft dark shadow a little below them. The first word of a caption shows when the caption starts, and each other word shows at its own start, at its place in the whole line, so the line does not move. A caption has no animation. It leaves at once when it ends.

Each caption is a shadow event on the bottom layer, an outline event above it and a letter event on the top layer. The events hold the same words in the same runs, so each word has the same place in each event, and each word shows at the same time in each event. With a shadow that cannot be seen, a caption has no shadow event.

The caption groups that end at each end mark, the words in capitals, the lean of the letters, the place of a caption whose letters lean, the times at which the words show, the tags that show them, the shadow check, the blur, the colors and the border of the events and the text of a line with a word gap come from caption_groups_at_marks, group_in_capitals, lean_tags, LEAN_MIDDLE_PART, word_tag_times, appear_at_alpha_tags, require_shadow, shadow_is_seen, blur_tag, fill_and_outline_tags, border_tag and word_gap_line_text of effect_common.

Source file: captionbob/effects/tiger.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`2`	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	`70`	Height of the font in pixels.
`bold`	boolean	`true`	True for bold text.
`primary_color`	string	`"#BE5808"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#5A0A00"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`3.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6563`	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.185`	The width of the letters as a part of the width that the font gives them, above 0.
`slant`	number	`0.19`	How far the top of a letter is to the right of its bottom, as a part of the height of the letter. 0 gives upright letters, and a value below 0 leans them to the left.
`letter_spread`	number	`2.0`	How far the letters spread past the shapes of the font in their own color, in pixels. 0 gives the shapes of the font.
`word_gap`	number	`4.3`	Room in pixels that is added to each space between two words. A value below 0 puts the words closer.
`capitals`	boolean	`true`	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.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`4.0`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`8.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.65`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`5.0`	How far the shadow is below the letters, in pixels. A value below 0 puts it above them.
`hold_seconds`	number	`0.0`	The longest time that a caption stays after its last word ends.

TigerSettings

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

The look and the timing of the tiger effect.

The primary color is the color of the letters and of their spread. The stroke color and the stroke width are the color and the width of the outline around the spread. The bottom position is the bottom of the line of text.

Args:

letter_width: The width of the letters as a part of the width that the font gives them, above 0.
slant: How far the top of a letter is to the right of its bottom, as a part of the height of the letter. 0 gives upright letters, and a value below 0 leans them to the left.
letter_spread: How far the letters spread past the shapes of the font in their own color, in pixels. 0 gives the shapes of the font.
word_gap: Room in pixels that is added to each space between two words. A value below 0 puts the words 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.
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 it above them.
hold_seconds: The longest time that a caption stays after its last word ends.

Raises:

TypeError: When a word count is not a whole number.
ValueError: When a value is outside its range, or when a color is not in the form "#RRGGBB".

TigerSettings.shadow_tags

def shadow_tags(self) -> str

Write the tags of the blur, the color and the border of the shadow, with no curly brackets. Each word of the shadow gets the strength of the shadow when it shows.

TigerSettings.outline_tags

def outline_tags(self) -> str

Write the tags of the outline around the spread of the letters, with no curly brackets.

TigerSettings.letter_tags

def letter_tags(self) -> str

Write the tags of the letters and their spread, with no curly brackets.

TigerSettings.text_x

def text_x(self, middle_x: float) -> float

Give the column of the place of a caption.

libass leans the letters around the top of their row, so a caption moves to the left by its lean. The place moves back to the right by the same room, so the caption stays in the middle of the video.

Args:

middle_x: The column of the middle of the video.

Returns:

The column of the bottom middle of the caption.

TigerEffect

class TigerEffect
    def __init__(self, settings: TigerSettings) -> None

Builds the ASS script of heavy orange capitals that lean, with a dark red outline and a soft shadow, shown word by word.

Args:

settings: The look and the timing of the effect.

TigerEffect.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 has a shadow event, an outline event and a letter 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.

TigerEffect.caption_events

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

Write the events of one caption.

Args:

caption: The caption with the times of its events and its words as spoken.
text_x: The column of the bottom middle of the caption.
caption_bottom: The row of the bottom of the line.

Returns:

The shadow event, the outline event and the letter event, in this order, with no shadow event when the shadow cannot be seen.