captionbob.effects.torch - captionbob docs

The torch effect: heavy white capitals with the spoken word on a box.

Each caption shows its words in heavy white capitals with no end marks, with a thin dark outline under the letters. A caption holds up to three words, and it ends at each end mark, such as a comma. A caption with the line letters or fewer stays on one line. A caption that ends with an end mark and has the long line letters or fewer also stays on one line. Another caption is cut into two lines, and the top line holds the top line words, or fewer when they have more than the long line letters. The top line stands on the bottom position, and the second line hangs the line gap below it. libass breaks a line that is wider than the room between the side margins.

The word that is spoken stands on a filled box with square corners, in the box color of the caption. The captions take the box colors in turn. The box shows while its word is spoken, and no box shows between two words that do not follow at once. A caption shows and leaves at once.

The box is the border style 3 of libass, which draws a box behind a run of text. The box event of a line holds the words of the line with hidden letters, so its boxes stand behind the words of the text event. Each word shows its box in its spoken time, and each space hides its box.

Each line of a caption has a box event, an outline event and a text event, from the bottom layer up. The outline event is the text in black with a wider border, a light blur and a small drop.

A caption with a keyword has an emoji above or below it in the middle of the video. The captions with a keyword take the emoji places in turn. The emoji starts at the pop scale of its full size and changes to its full size in the pop time, and it stays for the time of its caption.

The settings of the lines, the box colors and the outline, the caption groups that end at each end mark, the words with no end marks in capitals, the times of the captions, the spoken time of each word, its tags, the lines by their letters and end mark, the place of a line, the edge of an emoji, the tags of the size, the border and the outline look, the text of a line and the style line of the box come from SpokenLineSettings, caption_groups_at_marks, shown_group, shown_captions, spoken_times, spoken_look_tags, lines_by_end_mark, ends_with_end_mark, size_tags, border_tag, shadow_is_seen, one_line_text, word_lines_text, box_border_style_line, keyword_places and PopEmojiLayer of effect_common.

Source file: captionbob/effects/torch.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`3`	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	`72`	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	`2.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.675`	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.15`	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	`8.7`	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	`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.
`line_letters`	integer	`11`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`line_colors`	list	`["#BA3307"]`	The colors of the line that is spoken, as "#RRGGBB". The captions take them in turn.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`3.5`	How far the shadow reaches past the outline, in pixels.
`shadow_blur`	number	`0.5`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`1.0`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`0.7`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`long_line_letters`	integer	`16`	The most letters, with the spaces, of a caption that ends with an end mark and stays on one line, and of the top line of a caption of two lines.
`top_line_words`	integer	`2`	The most words of the top line of a caption of two lines, 1 or above.
`box_side_padding`	number	`9.5`	Room in pixels between a word and the left and the right side of its box.
`box_vertical_padding`	number	`5.0`	Room in pixels between the text line and the top and the bottom of the box, above 0.
`box_shift`	number	`4.3`	How far the boxes stand left of the words, in pixels. A value below 0 moves them right.
`emoji_places`	list	`["below", "below", "above", "above"]`	The places of the emojis, one or more of EMOJI_ABOVE and EMOJI_BELOW. The captions with a keyword take them in turn.
`emoji_size`	number	`115.0`	The side of an emoji in pixels at its full size.
`emoji_gap_above`	number	`25.0`	Room in pixels between the top of the top line and an emoji above the caption.
`emoji_gap_below`	number	`5.0`	Room in pixels between the bottom of the last line and an emoji below the caption.
`emoji_pop_scale`	number	`1.2`	The size of an emoji at its start, as a part of its full size. Above 1 it shrinks to its full size.
`emoji_pop_seconds`	number	`0.1`	The time in which an emoji changes to its full size.
`hold_seconds`	number	`0.1`	The longest time that a caption stays after its last word ends.

TorchLayers

class TorchLayers(NamedTuple)

What the effect gives for the words of one video.

Args:

ass_text: The text of the ASS script.
emojis: One emoji layer for each caption with a keyword, in time order.

TorchSettings

@dataclass(frozen=True)
class TorchSettings(SpokenLineSettings)

The settings of the torch effect.

The settings of SpokenLineSettings give the look of the letters, the lines and the outline under the letters. The line colors are the box colors, which the captions take in turn. The shadow settings are the outline under the letters.

Args:

long_line_letters: The most letters, with the spaces, of a caption that ends with an end mark and stays on one line, and of the top line of a caption of two lines.
top_line_words: The most words of the top line of a caption of two lines, 1 or above.
box_side_padding: Room in pixels between a word and the left and the right side of its box.
box_vertical_padding: Room in pixels between the text line and the top and the bottom of the box, above 0.
box_shift: How far the boxes stand left of the words, in pixels. A value below 0 moves them right.
emoji_places: The places of the emojis, one or more of EMOJI_ABOVE and EMOJI_BELOW. The captions with a keyword take them in turn.
emoji_size: The side of an emoji in pixels at its full size.
emoji_gap_above: Room in pixels between the top of the top line and an emoji above the caption.
emoji_gap_below: Room in pixels between the bottom of the last line and an emoji below the caption.
emoji_pop_scale: The size of an emoji at its start, as a part of its full size. Above 1 it shrinks to its full size.
emoji_pop_seconds: The time in which an emoji changes to its full size.
hold_seconds: The longest time that a caption stays after its last word ends.

Raises:

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

TorchSettings.box_style_line

def box_style_line(self, margin_vertical: int) -> str

Write the style line of the box behind the spoken word.

Args:

margin_vertical: Room in pixels between the bottom of the caption and the bottom edge of the video.

Returns:

The style line of the box, in the first box color, with the vertical padding as its outline width.

Raises:

ValueError: When a value of the style is outside its range.

TorchSettings.line_words

def line_words(
        self, words: Sequence[Word],
        ends_with_mark: bool) -> list[list[Word]]

Cut the words of a caption into one line or two lines.

Args:

words: The words of the caption, as the effect shows them. At least one word.
ends_with_mark: True when the caption, as spoken, ends with an end mark, such as a full stop.

Returns:

One line when the caption has the line letters or fewer, with its spaces, or when it ends with an end mark and has the long line letters or fewer. Else the lines of lines_by_top_words with the top line words and the long line letters.

TorchSettings.emoji_gap

def emoji_gap(self, place: str) -> float

Give the room between the caption and an emoji at a place.

Args:

place: EMOJI_ABOVE or EMOJI_BELOW.

Returns:

The emoji gap above or the emoji gap below.

TorchCaption

class TorchCaption(NamedTuple)

One caption of the torch effect.

Args:

caption: The caption with the times of its events and its words as spoken.
lines: The lines of the caption from the top, with the words as the effect shows them.
spoken: The spoken time of each word of the caption in its events, in the order of the words.
box_color: The box color of the caption, as "#RRGGBB".
emoji_place: EMOJI_ABOVE or EMOJI_BELOW for a caption with a keyword, or None for a caption with no keyword.

TorchEffect

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

Builds the ASS script and the emoji layers of heavy white capitals with the spoken word on a box, with an emoji above or below a caption with a keyword.

Args:

settings: The look and the timing of the effect.
keyword_picker: Names the keywords of each caption. A caption with a keyword has an emoji. With no value, the keyword of a caption is its longest word when that word has seven letters or more.

TorchEffect.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 box event, an outline event, when the outline can be seen, and a text 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.

TorchEffect.build_layers

def build_layers(
        self, words: Sequence[Word], video: VideoInfo,
        emoji_path: Path) -> TorchLayers

Build the ASS script and the emoji layers for one video.

The script is the script of build_ass_text. Each caption with a keyword has one emoji layer with the times of the caption.

Args:

words: The words of the video in time order, each with its times.
video: The frame size and the duration of the video.
emoji_path: The emoji image, such as an animated GIF or a PNG with a see-through background. The effect does not read the image. ffmpeg reads it when it draws the layers.

Returns:

The script and the emoji layers.

Raises:

TypeError: When the emoji path is not a Path.
FileNotFoundError: When the emoji image is not a file.
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.