captionbob.effects.halo - captionbob docs

The halo effect: two words in bold gold serif letters with a glow.

Each caption shows up to two words in bold gold serif letters, in the case of the transcript and with their end marks, such as commas. A caption ends at each end mark. A caption stays on one line up to the line letters. A longer caption is cut into two lines, and the top line holds the larger half of the words. The top line stands on the bottom position, and the second line hangs the line gap below it. The letters stand closer together than the font gives them by the letter gap, and each space too.

Each line has three events, one above the other. The lowest is the glow: the words in the glow color with a wide border that is blurred and partly seen. The middle one is the shadow: the words in the shadow color, a little blurred, the shadow drop below the letters. The top one is the letters in the primary color, with a thin blurred stroke that is partly seen.

When a caption comes, its letters stand the pop spacing closer together, and they go to their normal spacing in the pop time. In the last squeeze time of the caption they close up again, slowly at first and faster to its end. The caption drifts a few pixels into its place: the first caption of a video and every second caption after it comes from the odd drift, the others from the even drift. The drift waits a part of the caption time and then moves in a straight line, and it ends when the squeeze starts. Each word and each space is a run with the tags of its spacing.

The settings of the lines and their places, the caption groups that end at each end mark, the times of the captions, the lines of a caption by its letters, the text of a line with tags for each word and each gap, the checks and the tags of the glow and of the shadow, the pop of the spacing, the drift of each caption in turn, the tags of a line that drifts into its place, the time at which the letters close up and the spacing tag of a room come from effect_common.

The effect draws nothing itself. It builds the text of an ASS script, and ffmpeg draws it on the video. The defaults are the look of the source video of the effect, measured on its frames and scaled to a video of 1080x1920.

Source file: captionbob/effects/halo.py

Settings

The command line and the HTTP API call this effect the style halo. Its settings class is HaloSettings. 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	`"DejaVu Serif"`	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	`"#F7C52A"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#FF8800"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`2.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.5859`	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.928`	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	`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	`26`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`letter_gap`	number	`-5.75`	Room in pixels that is added after each letter and each space, at the letter width. A value below 0 puts the letters closer.
`word_gap`	number	`0.0`	Room in pixels that is added to each space on top of the letter gap, at the letter width.
`stroke_blur`	number	`2.0`	How far the edge of the stroke fades out, in pixels.
`stroke_opacity`	number	`0.3`	The strength of the stroke, from 0 for no stroke to 1.
`glow_color`	string	`"#FFAA00"`	The color of the glow, as "#RRGGBB".
`glow_spread`	number	`20.0`	How far the glow reaches past the letters before it is blurred, in pixels.
`glow_blur`	number	`60.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.42`	The strength of the glow, from 0 for no glow to 1.
`shadow_color`	string	`"#4A2A00"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`0.0`	How far the shadow reaches past the letters before it is blurred, in pixels.
`shadow_blur`	number	`2.0`	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	`8.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`pop_spacing`	number	`2.6`	How much closer together the letters stand when a caption comes, in pixels of room between two letters.
`pop_seconds`	number	`0.09`	The time in which the letters go from the pop spacing to their normal spacing. 0 gives the normal spacing at once.
`squeeze_spacing`	number	`3.2`	How much closer together the letters stand at the end of a caption, in pixels.
`squeeze_seconds`	number	`0.125`	The time at the end of a caption in which the letters close up. It starts after the pop time.
`odd_drift_x`	number	`-4.4`	How far to the right of its place the first caption of a video, and every second caption after it, starts, in pixels. A value below 0 starts it on the left.
`odd_drift_y`	number	`-2.9`	How far below its place such a caption starts, in pixels. A value below 0 starts it above.
`even_drift_x`	number	`3.5`	How far to the right of its place each other caption starts, in pixels.
`even_drift_y`	number	`5.8`	How far below its place each other caption starts, in pixels.
`drift_delay`	number	`0.3`	The part of the drift time in which a caption waits before it moves, from 0 up to 1. The drift time runs from the start of the caption to the start of its squeeze.
`hold_seconds`	number	`0.1`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

HaloSettings

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

The look and the timing of the halo 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 settings of the gaps, the stroke, the glow, the shadow, the pop, the squeeze and the drift, and the hold time. The effect changes the defaults of some of them. The stroke is a thin edge around the letters that is blurred and partly seen. The bottom position is the bottom of the top line when the caption is at rest.

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.
letter_gap: Room in pixels that is added after each letter and each space, at the letter width. A value below 0 puts the letters closer.
word_gap: Room in pixels that is added to each space on top of the letter gap, at the letter width.
stroke_blur: How far the edge of the stroke fades out, in pixels.
stroke_opacity: The strength of the stroke, from 0 for no stroke to 1.
glow_color: The color of the glow, as "#RRGGBB".
glow_spread: How far the glow reaches past the letters before it is blurred, 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.
shadow_color: The color of the shadow, as "#RRGGBB".
shadow_spread: How far the shadow reaches past the letters before it is blurred, 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.
pop_spacing: How much closer together the letters stand when a caption comes, in pixels of room between two letters.
pop_seconds: The time in which the letters go from the pop spacing to their normal spacing. 0 gives the normal spacing at once.
squeeze_spacing: How much closer together the letters stand at the end of a caption, in pixels.
squeeze_seconds: The time at the end of a caption in which the letters close up. It starts after the pop time.
odd_drift_x: How far to the right of its place the first caption of a video, and every second caption after it, starts, in pixels. A value below 0 starts it on the left.
odd_drift_y: How far below its place such a caption starts, in pixels. A value below 0 starts it above.
even_drift_x: How far to the right of its place each other caption starts, in pixels.
even_drift_y: How far below its place each other caption starts, in pixels.
drift_delay: The part of the drift time in which a caption waits before it moves, from 0 up to 1. The drift time runs from the start of the caption to the start of its squeeze.
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 font name cannot stand in a tag, or when a color is not in the form "#RRGGBB".

HaloSettings.has_glow

def has_glow(self) -> bool

True when the glow has strength and reaches past the letters: it spreads or it is blurred.

HaloSettings.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 them.

HaloSettings.drift

def drift(self, caption_index: int) -> tuple[float, float]

Give how far from its place a caption starts.

Args:

caption_index: The place of the caption in the captions of the video, 0 for the first.

Returns:

The pixels to the right and the pixels down. The first caption and every second caption after it have the odd drift, the others the even drift.

HaloEffect

class HaloEffect
    def __init__(self, settings: HaloSettings) -> None

Builds the ASS script of up to two words in bold gold serif letters with a wide glow and a dark shadow, whose letters pop and close up.

Args:

settings: The look and the timing of the effect.

HaloEffect.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 glow event, a shadow event 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.

HaloEffect.spacing_tags

def spacing_tags(
        self, room: float, pop_milliseconds: int,
        squeeze_start: int | None, event_milliseconds: int) -> str

Write the tags of the spacing of the letters of one run.

The letters start the pop spacing closer together than normal and go to normal in a straight line in the pop time. From the squeeze start to the end of the event they close up by the squeeze spacing, with the square of the time. Each run gets these tags with its own room.

Args:

room: Room in pixels added after each letter of the run, at the letter width.
pop_milliseconds: The pop time from the start of the event.
squeeze_start: The time at which the letters start to close up, or None for no squeeze.
event_milliseconds: The length of the event.

Returns:

The tags with no curly brackets.