captionbob.effects.ghost - captionbob docs

The ghost effect: hollow white capitals with a soft glow.

Each caption shows up to two words in one line, in capitals and with no end marks. A caption also ends at each end mark, such as a comma or a full stop. The words are narrow capitals drawn only as a white outline, so the video shows through the letters, and a soft white glow lies around them and inside them. The keywords of a caption are filled in a color, with an outline in that color that is thin at the sides of the letters, and a glow in that color. Their letters are wider than the other letters, so that they keep the size of the source. The keywords of a video take the keyword colors in turn. A caption shows at once with its first word, a little below its place, and it rises to its place in a straight line. It leaves at once when it ends.

Each caption is a glow event on the bottom layer and a text event on the top layer. The two events hold the same words in the same runs and move in the same way, so each word has the same place in the two events.

The caption groups that end at each end mark, the words in capitals with no end marks, the keywords and their colors in turn, the look tags, the blur and the border of a glow, the size tags, the spacing tag, the rise of a line into its place and the text of a line with a word gap come from caption_groups_at_marks, shown_group, keyword_places, keywords_in_turn, keyword_word_tags, look_tags, fill_and_outline_tags, blurred_look_tags, border_tag, size_tags, spacing_tag, rise_place_tags and word_gap_line_text of effect_common.

Source file: captionbob/effects/ghost.py

Settings

The command line and the HTTP API call this effect the style ghost. Its settings class is GhostSettings. 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	`"Ubuntu"`	Name of the font of the text.
`font_size`	integer	`158`	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	`6.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.7677`	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.565`	The width of the letters as a part of the width that the font gives them, above 0.
`letter_spacing`	number	`2.2`	Room in pixels after each letter. A value below 0 puts the letters closer.
`word_gap`	number	`15.2`	Room in pixels that is added to each space between two words. A value below 0 puts the words 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.
`rise`	number	`20.0`	How far below its place a caption shows at its start, in pixels. A value below 0 shows it above its place, and 0 shows it at its place.
`rise_seconds`	number	`0.1`	The time in which a caption rises to its place.
`glow_color`	string	`"#FFFFFF"`	The color of the glow of a word, as "#RRGGBB".
`glow_spread`	number	`14.0`	How far the glow of a word reaches past its outline, in pixels.
`glow_blur`	number	`32.0`	How far the edge of the glow of a word fades out, in pixels.
`glow_opacity`	number	`0.42`	The strength of the glow of a word, from 0 for no glow to 1.
`keyword_colors`	list	`["#97ED5C", "#F8EB4A", "#FFFFFF"]`	The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
`keyword_stroke_width`	number	`2.0`	The width of the outline of a keyword in its color at the sides of its letters, in pixels. 0 gives no outline there. At the top and the bottom of the letters, the outline has the stroke width.
`keyword_letter_width`	number	`0.595`	The width of the letters of a keyword as a part of the width that the font gives them, above 0.
`keyword_glow_spread`	number	`10.0`	How far the glow of a keyword reaches past the stroke width, in pixels.
`keyword_glow_blur`	number	`28.0`	How far the edge of the glow of a keyword fades out, in pixels.
`keyword_glow_opacity`	number	`0.55`	The strength of the glow of a keyword, from 0 for no glow to 1.
`hold_seconds`	number	`0.0`	The longest time that a caption stays after its last word ends.

GhostSettings

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

The look and the timing of the ghost effect.

The stroke color is the color of the outline of a word. The fill of a word is not drawn, so the primary color is not seen. The stroke width is the width of the outline of a word. The bottom position is the bottom of the line of text.

Args:

letter_width: The width of the letters as a part of the width that the font gives them, above 0.
letter_spacing: Room in pixels after each letter. A value below 0 puts the letters closer.
word_gap: Room in pixels that is added to each space between two words. A value below 0 puts the words 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.
rise: How far below its place a caption shows at its start, in pixels. A value below 0 shows it above its place, and 0 shows it at its place.
rise_seconds: The time in which a caption rises to its place.
glow_color: The color of the glow of a word, as "#RRGGBB".
glow_spread: How far the glow of a word reaches past its outline, in pixels.
glow_blur: How far the edge of the glow of a word fades out, in pixels.
glow_opacity: The strength of the glow of a word, from 0 for no glow to 1.
keyword_colors: The colors of the keywords, as "#RRGGBB". The keywords of a video take them in turn.
keyword_stroke_width: The width of the outline of a keyword in its color at the sides of its letters, in pixels. 0 gives no outline there. At the top and the bottom of the letters, the outline has the stroke width.
keyword_letter_width: The width of the letters of a keyword as a part of the width that the font gives them, above 0.
keyword_glow_spread: How far the glow of a keyword reaches past the stroke width, in pixels.
keyword_glow_blur: How far the edge of the glow of a keyword fades out, in pixels.
keyword_glow_opacity: The strength of the glow of a keyword, from 0 for no glow to 1.
hold_seconds: The longest time that a caption stays after its last word ends.

Raises:

TypeError: When a word count is not a whole number.
ValueError: When a value is outside its range, or when a color is not in the form "#RRGGBB".

GhostSettings.glow_tags

def glow_tags(self) -> str

Write the tags of the glow of a word at the size of the words, with no curly brackets.

GhostSettings.keyword_glow_tags

def keyword_glow_tags(self, color: str) -> str

Write the tags of the glow of a keyword in its color, at the letter width of a keyword.

Args:

color: The color of the keyword, as "#RRGGBB".

Returns:

The tags with no curly brackets.

GhostSettings.hollow_tags

def hollow_tags(self) -> str

Write the tags of a word drawn as its outline alone, at the size of the words, with no curly brackets.

GhostSettings.filled_tags

def filled_tags(self, color: str) -> str

Write the tags of a keyword filled in its color, with its outline in that color, at the letter width of a keyword.

The outline has the keyword stroke width at the sides of the letters and the stroke width at their top and bottom.

Args:

color: The color of the keyword, as "#RRGGBB".

Returns:

The tags with no curly brackets.

GhostEffect

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

Builds the ASS script of hollow white capitals with a soft glow, with keywords filled in color.

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.

GhostEffect.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 has a glow 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.

GhostEffect.caption_events

def caption_events(
        self, caption: ShownCaption, keyword_colors: Mapping[int, str],
        middle_x: float, caption_bottom: int) -> list[str]

Write the events of one caption.

Args:

caption: The caption with the times of its events and its words as spoken.
keyword_colors: The color of each keyword place in the words of the caption.
middle_x: The column of the middle of the video.
caption_bottom: The row of the bottom of the line.

Returns:

The glow event and the text event, in this order.