captionbob.effects.ollie

Ollie effect: heavy off-white words that build up to two lines.

Each caption shows up to four words in heavy off-white letters with a soft dark glow around them. The words are in the case in which they are spoken, with their end marks, and a caption ends at each end mark, such as a comma. A caption with more letters than the line letters has two lines, and the top line has the larger half of the words.

All the words of a caption have their places from the start of the caption, and each word appears in its place when it starts. A keyword is larger than the other words, and its line is as high as the keyword. The top line of each caption starts at the same row, so a second line goes below the first.

The caption grows slowly while it is shown. It starts at its full size and grows in a straight line around its middle to the zoom scale at its end.

Each line must fit between the side margins at the largest size of the caption. The caption measure gives the width of each line. A keyword that makes its line too wide gets smaller, down to the size of the other words. A caption with a line that is still too wide gets smaller as a whole.

Each 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 text event draws the letters 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/ollie.py

Settings

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

Setting	Type	Default	Description
most_words	integer	4	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	103	Height of the font in pixels.
bold	boolean	true	True for bold text.
primary_color	string	"#E8E5E1"	Color of the text, as "#RRGGBB".
stroke_color	string	"#E8E5E1"	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.7172	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.97	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_letters	integer	14	The most letters, with the spaces, of a caption that stays on one line, 1 or above. A caption with more letters and two words or more has two lines.
end_at_marks	boolean	true	True to end a caption at each end mark, such as a comma.
keyword_scale	number	1.45	The size of a keyword as a part of the size of the other words, above 0, when its line fits between the side margins.
zoom_scale	number	1.1	The size of a caption at its end as a part of its size at its start, above 0. 1 gives a caption that keeps its size.
shadow_color	string	"#000000"	The color of the shadow, as "#RRGGBB".
shadow_spread	number	5.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.8	The strength of the shadow, from 0 for no shadow to 1.
shadow_drop	number	0.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.

OllieSettings

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

The look and the timing of the ollie 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, and the stroke is their outline. The bottom position is where the bottom of the top line sits when the top line has its normal size. A second line goes below 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_letters: The most letters, with the spaces, of a caption that stays on one line, 1 or above. A caption with more letters and two words or more has two lines.
• end_at_marks: True to end a caption at each end mark, such as a comma.
• keyword_scale: The size of a keyword as a part of the size of the other words, above 0, when its line fits between the side margins.
• zoom_scale: The size of a caption at its end as a part of its size at its start, above 0. 1 gives a caption that keeps its size.
• 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.
• 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 color is not in the form "#RRGGBB", or when the font name is empty or holds a comma.

LayerLook

class LayerLook(NamedTuple)

The look of the events of one layer.

Args:

• layer: The layer of the events.
• drop: How far the events are below the place of the caption, in pixels.
• border_width: The width of the border of a word at its normal size, in pixels.
• shown_alpha: The value of the alpha tag of a word that is shown.
• tags: More tags of the whole caption, with no curly brackets.

OllieEffect

class OllieEffect
    def __init__(
            self, settings: OllieSettings, caption_measure: PlaceMeasure,
            keyword_picker: KeywordPicker = DEFAULT_KEYWORD_PICKER) -> None

Builds the ASS script of heavy off-white words that appear in their places in up to two lines, with a larger keyword and a slow growth.

Args:

• settings: The look and the timing of the effect.
• caption_measure: The measure that says where libass draws each word of a line. It runs ffmpeg once for all the lines of a video.
• keyword_picker: Names the keywords of each caption. With no value, the keyword of a caption is its longest word when that word has eight letters or more.

OllieEffect.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, when the keyword picker gives a place that is not a word of its caption, or when libass draws no pixel for a word.
• RuntimeError: When the ffmpeg of the caption measure fails.