captionbob.effects.blaze - captionbob docs

The blaze effect: large narrow yellow capitals.

Each caption shows its words in heavy narrow capitals, yellow, with no end marks. A caption holds up to two words, and it ends at each end mark, such as a comma. A caption of one word is larger: it grows down from the top of its line, so its top stays near the top of the other captions. A caption stays on one line up to the line letters, and a longer caption is cut into two lines. A keyword is white for the whole caption. A soft dark shadow lies under the letters, a little below them. A caption rises a few pixels into its place when it shows.

Each line of a caption has two events with the times of the caption. The shadow event draws the letters in the shadow color, with a border that fades out, the shadow drop below the line. The text event draws the letters over it, with an outline in the color of the letters that makes them heavier. Both events of a line rise into their place, and each space of a line gets the word gap.

An emoji is not drawn by ASS. build_layers gives one emoji layer for each caption with a keyword, with the times of the caption. The emoji is above the caption in the middle of the video. It shows a little smaller and grows to its full size in the emoji pop time, and it keeps its bottom row.

The settings of the lines, the captions with their lines and keywords, the places of the lines, the edge of the emoji, the rise and the check that the shadow is seen come from LineSettings, line_captions, rise_place_tags and shadow_is_seen of effect_common. The emoji layer is PopEmojiLayer of effect_common.

Source file: captionbob/effects/blaze.py

Settings

The command line and the HTTP API call this effect the style blaze. Its settings class is BlazeSettings. 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 Condensed"`	Name of the font of the text.
`font_size`	integer	`150`	Height of the font in pixels.
`bold`	boolean	`false`	True for bold text.
`primary_color`	string	`"#F8E450"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#F8E450"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`5.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.761`	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.84`	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	`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	`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	`20`	The most letters, with the spaces, of a caption that stays on one line, 1 or above. A one-word caption grows only up to the size at which its letters fill the line letters.
`word_gap`	number	`12.5`	Room in pixels that is added to each space between two words, at the letter width. A value below 0 puts the words closer. 0 keeps the space of the font.
`keyword_color`	string	`"#FFFFFF"`	The color of the letters and of the outline of a keyword, as "#RRGGBB".
`one_word_scale`	number	`1.42`	The size of a caption of one word as a part of the size of the other captions, above 0.
`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	`14.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.5`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`4.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`rise`	number	`4.3`	How far below its place a caption shows at its start, in pixels. A value below 0 shows it above its place. 0 shows it at its place at once.
`rise_seconds`	number	`0.12`	The time in which a caption moves into its place. 0 shows it at its place at once.
`emoji_size`	number	`192.0`	The side of the emoji in pixels at its full size, above 0.
`emoji_gap`	number	`276.0`	Room in pixels between the bottom of the emoji and the top of the top line.
`emoji_pop_scale`	number	`0.88`	The size of the emoji at its start, as a part of its full size, above 0. 1 shows it at its full size at once.
`emoji_pop_seconds`	number	`0.1`	The time in which the emoji grows to its full size. 0 shows it at its full size at once.
`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.

BlazeLayers

class BlazeLayers(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.

BlazeSettings

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

The look and the timing of the blaze 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 keyword color, the one-word scale, the settings of the shadow, of the rise and of the emoji, and the hold time. The effect changes the defaults of some of them. The stroke is the outline of the letters, which makes them heavier. The bottom position is the bottom of the top line.

Args:

letter_width: 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: 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. A one-word caption grows only up to the size at which its letters fill the line letters.
word_gap: Room in pixels that is added to each space between two words, at the letter width. A value below 0 puts the words closer. 0 keeps the space of the font.
keyword_color: The color of the letters and of the outline of a keyword, as "#RRGGBB".
one_word_scale: The size of a caption of one word as a part of the size of the other captions, above 0.
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.
rise: How far below its place a caption shows at its start, in pixels. A value below 0 shows it above its place. 0 shows it at its place at once.
rise_seconds: The time in which a caption moves into its place. 0 shows it at its place at once.
emoji_size: The side of the emoji in pixels at its full size, above 0.
emoji_gap: Room in pixels between the bottom of the emoji and the top of the top line.
emoji_pop_scale: The size of the emoji at its start, as a part of its full size, above 0. 1 shows it at its full size at once.
emoji_pop_seconds: The time in which the emoji grows to its full size. 0 shows it at its full size at once.
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, or when a color is not in the form "#RRGGBB".

BlazeSettings.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.

BlazeEffect

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

Builds the ASS script and the emoji layers of large narrow yellow capitals with a soft shadow and white keywords, which rise into their place, with an emoji above 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.

BlazeEffect.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 shadow event, when the shadow 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.

BlazeEffect.build_layers

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

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.