captionbob.effects.scribe - captionbob docs

The scribe effect: bold yellow words that lean, typed letter by letter.

Each caption shows its words as they are spoken, with no end marks, in bold yellow letters that lean to the right, and a soft yellow glow lies around the letters. A caption holds two to four words, and it ends at each end mark, such as a comma. A caption with the line letters or fewer stays on one line. A longer caption is cut into two lines, and the top line holds the larger half of the words. The top line stands on the bottom position, and the second line hangs the line gap below it. The top line of a caption of two lines has a lighter look of its own: its font, its weight and its stroke. A caption of two lines stands the two line lift higher than a caption of one line.

The letters of a caption are typed one by one at their places. The letters of a word share the time in which the word is spoken evenly, and the first letter appears when the word starts. A caption fades in at its start in the appear time, and it leaves at once when it ends.

Each line of a caption has a glow event and a text event with the times of the caption. In them each letter is a run of its own and is hidden until its time, so no letter moves when the next letter appears. The glow events are under the text events.

The settings of the lines, the lines of a caption by its letters, the caption groups that end at each end mark, the words with no end marks, the times of the captions, the spoken time of each word, the typed letters of a word with their times and their text, the lean of the letters, the font tags of the top line, the spacing tag of the word gap and the check and the tags of the glow come from LineSettings, lines_by_letters, caption_groups_at_marks, shown_group, shown_captions, word_spoken_seconds, typed_letters, letter_block, tag_milliseconds, lean_tags, font_tags, spacing_tag, require_glow, shadow_is_seen, border_tag, blur_tag, fill_and_outline_tags and opacity_alpha of effect_common.

Source file: captionbob/effects/scribe.py

Settings

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

Setting	Type	Default	Description
`most_words`	integer	`4`	The most words that one caption shows.
`fewest_words`	integer	`2`	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	`74`	Height of the font in pixels.
`bold`	boolean	`true`	True for bold text.
`primary_color`	string	`"#FAFF3E"`	Color of the text, as "#RRGGBB".
`stroke_color`	string	`"#FAFF3E"`	Color of the outline of the text, as "#RRGGBB".
`stroke_width`	number	`1.0`	Width of the outline in pixels. 0 gives no outline.
`bottom_position`	number	`0.6542`	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.2`	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	`4.0`	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	`false`	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	`18`	The most letters, with the spaces, of a caption that stays on one line, 1 or above.
`slant`	number	`0.13`	How far the top of a letter is to the right of its bottom, as a part of the height of the letter at the width of the font. 0 gives upright letters, and a value below 0 leans them to the left.
`word_gap`	number	`-0.6`	Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
`top_line_font_name`	string	`"Ubuntu"`	The font of the top line of a caption of two lines.
`top_line_bold`	boolean	`false`	True for bold letters on the top line of a caption of two lines.
`top_line_stroke_width`	number	`0.0`	The width of the outline of the letters on the top line of a caption of two lines, in pixels. 0 gives no outline.
`two_line_lift`	number	`6.0`	How far a caption of two lines stands above the place of a caption of one line, in pixels. A value below 0 puts it lower.
`glow_color`	string	`"#FAFF3E"`	The color of the glow, as "#RRGGBB".
`glow_spread`	number	`3.0`	How far the glow reaches past the outline of the letters before it is blurred, in pixels.
`glow_blur`	number	`5.0`	How far the edge of the glow fades out, in pixels.
`glow_opacity`	number	`0.5`	The strength of the glow, from 0 for no glow to 1.
`appear_seconds`	number	`0.1`	The time in which a caption fades in at its start. 0 shows each caption in full at once.
`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.

LineLook

class LineLook(NamedTuple)

The look of one line of a caption.

Args:

font_tags: The tags of the font and the weight of the line, with no curly brackets. No tags keep the font of the style.
stroke_tags: The tags of the stroke of the letters of the line, with no curly brackets. No tags keep the stroke of the style.
stroke_width: The width of the outline of the letters of the line, in pixels.

ScribeSettings

@dataclass(frozen=True)
class ScribeSettings(LineSettings)

The look and the timing of the scribe 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 LineSettings follow them, from the letter width to the line letters, and then the slant, the word gap, the look of the top line of a caption of two lines, the two line lift, the settings of the glow, the appear time and the hold time. The effect changes the defaults of some of them. The stroke is the outline of the letters in their own color, which makes them heavier. 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.
slant: How far the top of a letter is to the right of its bottom, as a part of the height of the letter at the width of the font. 0 gives upright letters, and a value below 0 leans them to the left.
word_gap: Room in pixels that is added after each space, at the letter width. A value below 0 puts the words closer.
top_line_font_name: The font of the top line of a caption of two lines.
top_line_bold: True for bold letters on the top line of a caption of two lines.
top_line_stroke_width: The width of the outline of the letters on the top line of a caption of two lines, in pixels. 0 gives no outline.
two_line_lift: How far a caption of two lines stands above the place of a caption of one line, in pixels. A value below 0 puts it lower.
glow_color: The color of the glow, as "#RRGGBB".
glow_spread: How far the glow reaches past the outline of the letters before it is blurred, 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.
appear_seconds: The time in which a caption fades in at its start. 0 shows each caption in full 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 or the line letters is not a whole number.
ValueError: When a value is outside its range, when a color is not in the form "#RRGGBB", or when a font name is empty or holds a comma.

ScribeSettings.line_words

def line_words(self, words: Sequence[Word]) -> list[list[Word]]

Cut the words of a caption into one line or two lines.

Args:

words: The words of the caption, as the effect shows them.

Returns:

The lines of lines_by_letters with the line letters of the settings.

ScribeSettings.has_glow

def has_glow(self) -> bool

Say if the glow can be seen: it has strength, and it reaches past the letters.

ScribeSettings.text_x

def text_x(self, middle_x: float) -> float

Give the column of the place of the lines of a caption.

libass leans the letters around the top of their row, so a line moves to the left by its lean. The place moves back to the right by the same room, so the lines stay in the middle of the video.

Args:

middle_x: The column of the middle of the video.

Returns:

The column of the middle of the lines.

ScribeSettings.line_look

def line_look(self, line_index: int, line_count: int) -> LineLook

Give the look of one line of a caption.

Args:

line_index: The line, 0 for the top line.
line_count: The number of lines of the caption.

Returns:

The look of the top line for the top line of a caption of two lines, and else the look of the style.

ScribeSettings.appear_tags

def appear_tags(self) -> str

Write the tag that fades a caption in at its start.

Returns:

The tag with no curly brackets, or no tags for an appear time of less than half a millisecond.

ScribeLayer

class ScribeLayer(NamedTuple)

One of the two events of a line: the glow or the letters.

Args:

layer: The layer of the event.
tags: The tags of the look of the event, with no curly brackets.
shown_alpha: The value of the alpha tag of a shown letter.

ScribeCaptionEvents

class ScribeCaptionEvents(NamedTuple)

The events of one caption, with the number of its letters.

Args:

events: The dialogue lines of the caption.
letters: The number of the letters that the caption types.

ScribeEffect

class ScribeEffect
    def __init__(self, settings: ScribeSettings) -> None

Builds the ASS script of bold yellow words that lean, with a soft glow, whose letters are typed one by one.

Args:

settings: The look and the timing of the effect.

ScribeEffect.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 event and a text event. These 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. A glow that cannot be seen has no events.

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.