CoralBit

captionbob docs

Version 1.0.0
Contents ↓

Python: captionbob.effects

captionbob.effects.candy

The candy effect: two heavy words with a keyword color and an emoji.

Each caption shows one or two words in heavy white letters with a black edge, in the case in which they are spoken and with their end marks. A caption ends at each end mark, such as a comma. The keyword of a caption is purple, green or orange, and the keywords of a video take these colors in turn. A caption with a keyword has its emoji below it, in the middle of the video. The caption and its emoji show at their full size at once.

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, with an outline in the color of the letters that makes them heavier. An emoji is not drawn by ASS: the effect gives one emoji layer for each caption with a keyword, and the ffmpeg filters draw it.

Source file: captionbob/effects/candy.py

Settings

The command line and the HTTP API call this effect the style candy. Its settings class is CandySettings. 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 88 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 1.5 Width of the outline in pixels. 0 gives no outline.
bottom_position number 0.7036 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.
end_at_marks boolean true True to end a caption at each end mark, such as a comma.
keyword_colors list ["#DC3BFF", "#56FF17", "#FA7A15"] The colors of the letters and of the outline of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
shadow_color string "#000000" The color of the shadow, as "#RRGGBB".
shadow_spread number 4.5 How far the shadow reaches past the outline, in pixels.
shadow_blur number 1.0 How far the edge of the shadow fades out, in pixels.
shadow_opacity number 0.95 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.
emoji_size number 132.0 The side of the emoji in pixels, above 0.
emoji_gap number 11.0 Room in pixels between the bottom of the caption and the top of the emoji.
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.

CandyLayers

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

CandySettings

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

The look and the timing of the candy 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 plain words. The stroke is their outline, which makes the letters heavier in the stroke color.

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.
  • end_at_marks: True to end a caption at each end mark, such as a comma.
  • keyword_colors: The colors of the letters and of the outline of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
  • 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.
  • emoji_size: The side of the emoji in pixels, above 0.
  • emoji_gap: Room in pixels between the bottom of the caption and the top of the emoji.
  • 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.

CandyEffect

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

Builds the ASS script and the emoji layers of one or two heavy white words with a black edge, with purple, green or orange keywords and an emoji below.

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.

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

CandyEffect.build_layers

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

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.