captionbob.effects.riot - captionbob docs

The riot effect: heavy capitals whose spoken line has a bright color.

Each caption shows its words in heavy white capitals, with no end marks. A caption ends at each end mark, such as a comma. A short caption stays on one line, and so does a caption that ends with an end mark and is not much longer. Another caption is cut into two lines, and the top line takes the first two words. The line whose words are spoken has the line color of the caption, and the other line is white. The captions take the line colors cyan, green and red in turn.

Each letter has a dark outline and a soft glow around it. The glow has the color of the letters, and the outline lets a part of the glow through, so it is dark in the color of its line. Each line of a caption has three events: the glow, the outline and the letters. The top line stands on the caption bottom, and the second line hangs from the line gap below it.

Some captions tilt: the captions take the tilts in turn, and a tilted caption turns around the middle of its lines as one piece. Each caption floats to and fro on the line from the top left to the bottom right, on a cosine curve around its place. The captions take the float turns in turn. ASS moves a text only in a straight line at one speed, so the time of a caption that floats is cut into events of about FLOAT_PIECE_CENTISECONDS, and each event is one straight move from one place of the curve to the next.

A caption with a keyword has an emoji above it, in the middle of the video. The emoji pops in from a smaller size, and it floats with its caption. 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.

The settings of the lines and of the outline, the caption groups that end at each end mark, the lines by their letters and end mark, the times of the lines, the tags of the spoken line, the place of a line, the edge of an emoji, the float and the emoji layer that floats come from effect_common. The defaults are the look of the source video of the effect, measured on its frames and scaled to a video 1080 pixels wide.

Source file: captionbob/effects/riot.py

Settings

The command line and the HTTP API call this effect the style riot. Its settings class is RiotSettings. 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	`"Ubuntu"`	Name of the font of the text.
`font_size`	integer	`82`	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.5`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.726`	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	`1.18`	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_gap`	number	`10.3`	Room in pixels between the bottom of the top line and the top of the second line. A value below 0 puts the lines closer.
`capitals`	boolean	`true`	True to write the words in capitals.
`end_at_marks`	boolean	`true`	True to end a caption at each end mark, such as a comma.
`line_letters`	integer	`10`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`line_colors`	list	`["#2DFFFA", "#81FF22", "#EA1A34"]`	The colors of the line that is spoken, as "#RRGGBB". The captions take them in turn.
`shadow_color`	string	`"#000000"`	The color of the dark outline, as "#RRGGBB".
`shadow_spread`	number	`8.75`	How far the dark outline reaches past the outline of the letters, in pixels.
`shadow_blur`	number	`1.5`	How far the edge of the dark outline fades out, in pixels.
`shadow_opacity`	number	`0.6`	The strength of the dark outline, from 0 for no outline to 1.
`shadow_drop`	number	`0.0`	How far the dark outline is below the letters, in pixels. A value below 0 puts it above them.
`long_line_letters`	integer	`16`	The most letters, with the spaces, of a caption that ends with an end mark and stays on one line, and of a top line, 1 or above.
`top_line_words`	integer	`2`	The most words of a top line, 1 or above.
`glow_spread`	number	`6.0`	How far the glow reaches past the dark outline, in pixels.
`glow_blur`	number	`6.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.8`	The strength of the glow, from 0 for no glow to 1.
`tilts`	list	`[7.0, 0.0, 0.0, 0.0, -7.0, 0.0, 0.0, -7.0, 0.0, 7.0, -7.0, 0.0, 7.0, 0.0, 0.0, 7.0]`	The tilts of the captions in degrees clockwise. The captions take them in turn. 0 keeps a caption level.
`turns`	list	`["float down", "float up"]`	The float turns of the captions, each "float down", "float up" or "still". The captions take them in turn.
`float_reach`	number	`14.0`	How far a caption that floats goes from its place to each side, to the right and down, in pixels.
`float_seconds`	number	`1.4`	The time of one swing of the float, there and back, above 0.
`emoji_size`	number	`140.0`	The side of the emoji in pixels, above 0.
`emoji_gap`	number	`64.0`	Room in pixels between the top line and the emoji.
`emoji_float_reach`	number	`25.0`	How far the emoji goes from its place to each side, to the right and down, while its caption floats, in pixels.
`emoji_pop_scale`	number	`0.8`	The size of an emoji at the start of its caption, as a part of its full size, above 0.
`emoji_pop_seconds`	number	`0.1`	The time in which an emoji grows to its full size. 0 shows it at its full size at once.
`hold_seconds`	number	`0.2`	The longest time that a caption stays after its last word ends. The caption goes earlier when the next caption starts.

RiotLayers

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

RiotCaption

class RiotCaption(NamedTuple)

One caption of the riot effect.

Args:

caption: The caption with the times of its events and its words as spoken.
lines: The lines of the caption from the top, with the words as the effect shows them.
line_color: The line color of the caption.
tilt: The tilt of the caption in degrees clockwise.
turn: The float turn of the caption, one of FLOAT_TURNS.
has_keyword: True when the caption has a keyword, and so an emoji.

RiotSettings

@dataclass(frozen=True)
class RiotSettings(SpokenLineSettings)

The look and the timing of the riot effect.

The settings of CaptionSettings come first: the word counts, the font, the colors, the stroke, the bottom position and the side margin. The settings of SpokenLineSettings follow them, from the letter width to the shadow drop, and then the settings of the effect and the hold time. The effect changes the defaults of some of them. The primary color is the color of the white lines. The stroke is the outline of the letters, which makes them heavier in the color of their line. The shadow is the dark outline past it. The bottom position is the bottom of 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_gap: Room in pixels between the bottom of the top line and the top of the second line. A value below 0 puts the lines closer.
capitals: True to write the words in capitals.
end_at_marks: True to end a caption at each end mark, such as a comma.
line_letters: The most letters, with the spaces, of a caption that stays on one line, 1 or above.
line_colors: The colors of the line that is spoken, as "#RRGGBB". The captions take them in turn.
shadow_color: The color of the dark outline, as "#RRGGBB".
shadow_spread: How far the dark outline reaches past the outline of the letters, in pixels.
shadow_blur: How far the edge of the dark outline fades out, in pixels.
shadow_opacity: The strength of the dark outline, from 0 for no outline to 1.
shadow_drop: How far the dark outline is below the letters, in pixels. A value below 0 puts it above them.
long_line_letters: The most letters, with the spaces, of a caption that ends with an end mark and stays on one line, and of a top line, 1 or above.
top_line_words: The most words of a top line, 1 or above.
glow_spread: How far the glow reaches past the dark outline, in pixels.
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.
tilts: The tilts of the captions in degrees clockwise. The captions take them in turn. 0 keeps a caption level.
turns: The float turns of the captions, each "float down", "float up" or "still". The captions take them in turn.
float_reach: How far a caption that floats goes from its place to each side, to the right and down, in pixels.
float_seconds: The time of one swing of the float, there and back, above 0.
emoji_size: The side of the emoji in pixels, above 0.
emoji_gap: Room in pixels between the top line and the emoji.
emoji_float_reach: How far the emoji goes from its place to each side, to the right and down, while its caption floats, in pixels.
emoji_pop_scale: The size of an emoji at the start of its caption, as a part of its full size, above 0.
emoji_pop_seconds: The time in which an emoji grows to its full size. 0 shows it at its full size at once.
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, the line letters, the long line letters or the top line words is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", when a turn is not known, or when the font name is empty or holds a comma.

RiotSettings.glow_width

def glow_width(self) -> float

Give the width of the border of the glow: the outline of the letters, the dark outline and the glow spread, in pixels.

RiotEffect

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

Builds the ASS script and the emoji layers of heavy capitals with a dark outline and a glow, whose spoken line is cyan, green or red, that tilt and float, with an emoji above.

Args:

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

RiotEffect.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 line of each caption has a glow, an outline and a text event for each piece of the float of its caption. The events of a caption start with its first word. 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.

RiotEffect.build_layers

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

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.