captionbob.effects.iris - captionbob docs

Iris effect: capitals with a gradient, a blue spoken word and keywords.

Each caption shows its words in capitals with no end marks. Each word has a gradient from the top of its capitals to their baseline: white to purple for a plain word. The word that is spoken has a gradient from cyan to blue and a soft purple glow, from its start to the end of its spoken time. A keyword keeps a gradient of its own the whole time, and it gets the glow while it is spoken. The keywords of a video take the keyword colors in turn. A light outline goes around all the letters.

The top row of a caption stays at one place: its bottom sits at the bottom position. A caption that libass breaks into more rows grows down from it.

ASS has no gradient. So the effect cuts each row of a caption into strips across the video. A strip is one event of the whole caption with a clip to the rows of the strip, and its words have the colors of the gradient at the middle of the strip. libass draws the strips over the outline, and the outline over the glow. The effect draws nothing itself. It builds the text of an ASS script, and the ffmpeg filter ass draws the script 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/iris.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`3`	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	`92`	Height of the font in pixels.
`bold`	boolean	`true`	True for bold text.
`primary_color`	string	`"#F9F7FA"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#EAE3F3"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`4.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.69`	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	`147`	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.
`capitals`	boolean	`true`	True to show the words in capitals.
`primary_bottom_color`	string	`"#522BAB"`	The bottom of the gradient of a plain word, as "#RRGGBB".
`spoken_top_color`	string	`"#20B0C2"`	The top of the gradient of the spoken word.
`spoken_bottom_color`	string	`"#2724A3"`	The bottom of the gradient of the spoken word.
`keyword_colors`	list	`[["#F2EAEE", "#A03680"], ["#EEF8F8", "#56D5D6"]]`	The top color and the bottom color of each keyword look, one pair or more. The keywords of a video take them in turn.
`gradient_top`	number	`0.174`	Where the gradient starts, as a part of the height of a row from its top, from 0 to 1. A row is as high as the font size. It is the top of the capitals of the font.
`gradient_bottom`	number	`0.794`	Where the gradient ends, as a part of the height of a row from its top. It is the baseline of the font. The rows above the start have the top color and the rows below the end have the bottom color.
`strip_height`	integer	`2`	The height in pixels of a strip of the gradient, 1 or above. A lower strip gives a smoother gradient and more events.
`glow_color`	string	`"#8A4CFF"`	Color of the glow of the spoken word, as "#RRGGBB".
`glow_radius`	number	`12.0`	Size of the glow in pixels. The glow is at half of its strength this far out from the outline. 0 gives no glow.
`glow_opacity`	number	`0.4`	Strength of the glow, from 0 for no glow to 1 for the strongest glow.
`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.

Strip

class Strip(NamedTuple)

One strip of a row of a caption.

Args:

row: The row of the caption, 0 for the top row.
top: The first row of the video of the strip.
bottom: The row of the video below the strip.
part: The part of the gradient at the middle of the strip, from 0 at the top of the capitals to 1 at the baseline.

IrisSettings

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

The look and the timing of the iris 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 top of the gradient of a plain word, and the stroke is the outline around all the letters. The bottom position is the place of the bottom of the top row of a caption. The glow reaches into the side margins.

Args:

capitals: True to show the words in capitals.
primary_bottom_color: The bottom of the gradient of a plain word, as "#RRGGBB".
spoken_top_color: The top of the gradient of the spoken word.
spoken_bottom_color: The bottom of the gradient of the spoken word.
keyword_colors: The top color and the bottom color of each keyword look, one pair or more. The keywords of a video take them in turn.
gradient_top: Where the gradient starts, as a part of the height of a row from its top, from 0 to 1. A row is as high as the font size. It is the top of the capitals of the font.
gradient_bottom: Where the gradient ends, as a part of the height of a row from its top. It is the baseline of the font. The rows above the start have the top color and the rows below the end have the bottom color.
strip_height: The height in pixels of a strip of the gradient, 1 or above. A lower strip gives a smoother gradient and more events.
glow_color: Color of the glow of the spoken word, as "#RRGGBB".
glow_radius: Size of the glow in pixels. The glow is at half of its strength this far out from the outline. 0 gives no glow.
glow_opacity: Strength of the glow, from 0 for no glow to 1 for the strongest glow.
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 strip height is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", when the keyword colors are not pairs of colors, or when the font name is empty or holds a comma.

IrisSettings.has_glow

@property
def has_glow(self) -> bool

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

IrisSettings.glow_style_line

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

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

The glow is the text in the glow color, with an outline that is wider than the stroke by the glow radius. The event of the glow blurs this outline.

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 glow of the spoken word.

Raises:

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

IrisEffect

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

Builds the ASS script of capitals with a gradient and a blue spoken word.

Args:

settings: The look and the timing of the effect.
caption_measure: The measure that says where libass draws each word of a caption.
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.

IrisEffect.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 glow, the outline and the strips of its rows, from the lowest layer up, all with the same times. There is no glow event when the glow 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, 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.