captionbob.effects.honey - captionbob docs

Honey effect: yellow bold serif words with a soft dark shadow.

Each caption shows one or two words in yellow bold serif letters, in the case in which they are spoken and with no end marks. The letters have no outline. A soft dark shadow lies a little down and to the right of the letters. A caption shows at once when its first word starts, and it goes at once.

The shadow is an event on the layer under the caption: the caption in the shadow color, moved down and to the right, and blurred.

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

Settings

The command line and the HTTP API call this effect the style honey. Its settings class is HoneySettings. 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	`87`	Height of the font in pixels.
`bold`	boolean	`true`	True for bold text.
`primary_color`	string	`"#F7F428"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#000000"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`0.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.582`	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.
`shadow_color`	string	`"#000000"`	Color of the shadow, as "#RRGGBB".
`shadow_shift`	number	`2.0`	How far the shadow lies to the right of the caption, in pixels. A value below 0 puts it on the left.
`shadow_drop`	number	`3.0`	How far the shadow lies below the caption, in pixels. A value below 0 puts it above.
`shadow_blur`	number	`2.0`	The blur of the shadow in pixels.
`shadow_opacity`	number	`0.875`	Strength of the shadow, from 0 for no shadow to 1 for the full shadow color.
`hold_seconds`	number	`0.3`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

HoneySettings

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

The look and the timing of the honey 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 stroke is the outline of the letters, and the shadow has the shape of the letters with their outline.

Args:

shadow_color: Color of the shadow, as "#RRGGBB".
shadow_shift: How far the shadow lies to the right of the caption, in pixels. A value below 0 puts it on the left.
shadow_drop: How far the shadow lies below the caption, in pixels. A value below 0 puts it above.
shadow_blur: The blur of the shadow in pixels.
shadow_opacity: Strength of the shadow, from 0 for no shadow to 1 for the full shadow color.
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.

HoneySettings.has_shadow

@property
def has_shadow(self) -> bool

True when the settings give a shadow that can be seen.

HoneySettings.shadow_style_line

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

Write the ASS style line of the shadow of these settings.

The shadow is the text and its outline in the shadow color. It reaches no farther out than the outline of the text.

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

Raises:

ValueError: When the font name, the font size, the shadow color, the outline width or a margin is outside its range.

HoneyEffect

class HoneyEffect
    def __init__(self, settings: HoneySettings) -> None

Builds the ASS script of yellow bold serif words with a soft shadow.

Args:

settings: The look and the timing of the effect.

HoneyEffect.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 is the shadow and the caption, from the lower layer up, with the same times. There is no shadow event when the shadow cannot be seen. An event starts with the first word of its caption. It ends 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.