captionbob.effects.wisp - captionbob docs

Wisp effect: two words at a time in tight letters with a soft glow.

Each caption shows up to two words in one line, in bold white letters that stand close together. The words are in the case in which they are spoken, and a caption ends at each end mark, such as a comma. The end marks at the ends of the words are not shown.

The letters have a soft glow in their own color: the stroke is an outline that is blurred and partly seen. A soft dark shadow lies a little below them. A keyword has a color of its own, with a glow in that color, and the keywords of a video take the keyword colors in turn.

When a caption comes, its letters stand closer together than their normal spacing, and they spread apart to it in the squeeze time. When the caption goes, they close up again in the last squeeze time. The change is slow at first and fast at the end.

Each caption has two events with the times of the caption. The shadow event draws the words in the shadow color, with a border that fades out. The text event draws the words with their glow over it.

The effect draws nothing itself. It builds the text of an ASS script, and ffmpeg draws it on the video. The common part of the effects is in effect_common.py.

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/wisp.py

Settings

The command line and the HTTP API call this effect the style wisp. Its settings class is WispSettings. 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 Sans"`	Name of the font of the text.
`font_size`	integer	`104`	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	`3.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.7063`	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.
`letter_spacing`	number	`-10.0`	The room in pixels that each letter adds to the spacing of the font. A value below 0 puts the letters closer together.
`end_at_marks`	boolean	`true`	True to end a caption at each end mark, such as a comma.
`glow_blur`	number	`6.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.4`	The strength of the glow, from 0 for no glow to 1.
`keyword_colors`	list	`["#6BC4C0", "#D868E1", "#72FF29"]`	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
`squeeze_spacing`	number	`3.2`	How much closer together the letters stand when a caption comes and when it goes, in pixels of spacing. 0 gives letters that keep their spacing.
`squeeze_seconds`	number	`0.1`	The time in which the letters spread apart at the start of a caption, and the time in which they close up at its end. 0 gives letters that keep their spacing.
`shadow_color`	string	`"#000000"`	The color of the shadow, as "#RRGGBB".
`shadow_spread`	number	`3.0`	How far the shadow reaches past the glow outline, in pixels.
`shadow_blur`	number	`20.0`	How far the edge of the shadow fades out, in pixels.
`shadow_opacity`	number	`0.8`	The strength of the shadow, from 0 for no shadow to 1.
`shadow_drop`	number	`2.0`	How far the shadow is below the letters, in pixels. A value below 0 puts the shadow above them.
`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.

WispSettings

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

The look and the timing of the wisp effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. These settings follow them. The primary color is the color of the letters. The stroke is their glow: an outline in the stroke color that fades out over the glow blur and is seen at the glow opacity. A keyword has its keyword color in its letters and in its glow.

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.
letter_spacing: The room in pixels that each letter adds to the spacing of the font. A value below 0 puts the letters closer together.
end_at_marks: True to end a caption at each end mark, such as a comma.
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.
keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
squeeze_spacing: How much closer together the letters stand when a caption comes and when it goes, in pixels of spacing. 0 gives letters that keep their spacing.
squeeze_seconds: The time in which the letters spread apart at the start of a caption, and the time in which they close up at its end. 0 gives letters that keep their spacing.
shadow_color: The color of the shadow, as "#RRGGBB".
shadow_spread: How far the shadow reaches past the glow 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 is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", or when the font name is empty or holds a comma.

spacing_tag

def spacing_tag(spacing: float) -> str

Write the tag of the spacing of the letters in pixels.

squeeze_tags

def squeeze_tags(
        letter_spacing: float, squeeze_spacing: float,
        squeeze_milliseconds: int, event_milliseconds: int) -> str

Write the tags of letters that spread apart when their event starts and close up when it ends.

The letters start closer together by the squeeze spacing and spread to the letter spacing in the squeeze time. In the last squeeze time of the event they close up again. Each change goes with the square of its time. An event that is shorter than two squeeze times closes up only after the spread is over, and an event that is shorter than one squeeze time does not close up.

Args:

letter_spacing: The spacing of the letters in pixels between the two changes.
squeeze_spacing: How much closer together the letters stand at the start and at the end, in pixels of spacing.
squeeze_milliseconds: The time of each change.
event_milliseconds: The length of the event, above 0.

Returns:

The tags with no curly brackets. No squeeze time or no squeeze spacing gives the letter spacing alone.

WispEffect

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

Builds the ASS script of two words at a time in tight letters with a soft glow, a drop shadow and keywords in color.

Args:

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

WispEffect.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 group has 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, or when the keyword picker gives a place that is not a word of its caption.