captionbob.effect_common.ass_script - captionbob docs

ASS script text: the subtitle format that the ffmpeg filter ass draws.

An effect draws nothing itself. It gives the text of an ASS script, and ffmpeg draws the script on the video with libass in the same pass that encodes the video. This file holds the parts of the format that each effect needs: the times, the colors, the text of a word, one style line, one dialogue line and the whole script.

Source file: captionbob/effect_common/ass_script.py

seconds_to_centiseconds

def seconds_to_centiseconds(seconds: float) -> int

Give a time in whole centiseconds. ASS writes event times in them.

Args:

seconds: The time in seconds, 0 or above.

Returns:

The nearest whole number of centiseconds.

Raises:

TypeError: When the time is not a number.
ValueError: When the time is not finite or is below 0.

seconds_to_milliseconds

def seconds_to_milliseconds(seconds: float) -> int

Give a time in whole milliseconds. ASS tags take their times in them.

Args:

seconds: The time in seconds, 0 or above.

Returns:

The nearest whole number of milliseconds.

Raises:

TypeError: When the time is not a number.
ValueError: When the time is not finite or is below 0.

ass_time

def ass_time(centiseconds: int) -> str

Write an event time in the form of ASS: H:MM:SS.CC.

Args:

centiseconds: The time in whole centiseconds, 0 or above.

Returns:

The time text, for example "0:00:41.99".

Raises:

ValueError: When the time is not a whole number of 0 or above.

require_hex_color

def require_hex_color(name: str, color: str) -> None

Refuse a color that is not in the form "#RRGGBB".

Args:

name: Name of the value, for the error text.
color: The color to check.

Raises:

ValueError: When the color is not a string in the form "#RRGGBB".

ass_color

def ass_color(color: str) -> str

Write a color in the form of ASS. ASS puts blue first and red last.

Args:

color: The color as "#RRGGBB".

Returns:

The color text of a style line, with no transparency. "#FF8000" gives "&H000080FF".

Raises:

ValueError: When the color is not in the form "#RRGGBB".

ass_tag_color

def ass_tag_color(color: str) -> str

Write a color in the form of an ASS color tag, such as \1c.

Args:

color: The color as "#RRGGBB".

Returns:

The color text of a tag. A tag color has no transparency, and it ends with the mark &. "#FF8000" gives "&H0080FF&".

Raises:

ValueError: When the color is not in the form "#RRGGBB".

escape_ass_text

def escape_ass_text(text: str) -> str

Make a text safe to show, so that libass reads no command in it.

libass reads a text in curly brackets as commands, and it reads a backslash with the next letter as a command too.

Args:

text: The text to show, for example one word.

Returns:

The text for a dialogue line. libass shows it as the same letters. A line break in the text becomes the line break command of ASS.

ass_style_line

def ass_style_line(
        *, name: str, font_name: str, font_size: int, bold: bool,
        primary_color: str, outline_color: str, outline_width: float,
        alignment: int, margin_left: int, margin_right: int,
        margin_vertical: int,
        border_style: int = OUTLINE_BORDER_STYLE) -> str

Write one style line of an ASS script.

The style has no shadow. Its text is not italic, not underlined and not struck out, and it has no extra spacing or angle.

Args:

name: Name of the style. The dialogue lines name it.
font_name: Name of the font.
font_size: Height of the font in pixels of the script.
bold: True for bold text.
primary_color: Color of the text, as "#RRGGBB".
outline_color: Color of the outline, as "#RRGGBB". With the box border style it is the color of the box.
outline_width: Width of the outline in pixels. 0 gives no outline. With the box border style it is the room in pixels between the text and each edge of the box, and 0 gives no box.
alignment: Where the text sits, as on a number pad: 1 to 3 are the bottom row, 4 to 6 the middle row and 7 to 9 the top row.
margin_left: Room in pixels between the text and the left edge.
margin_right: Room in pixels between the text and the right edge.
margin_vertical: Room in pixels between the text and the top or the bottom edge, for the row that the alignment gives.
border_style: OUTLINE_BORDER_STYLE for an outline around the letters. BOX_BORDER_STYLE for a filled box behind the text, in place of the outline. The box is as wide as the text and as high as the text line, plus the outline width. BACKGROUND_BORDER_STYLE for the outline and one filled box behind the whole event. The style gives a black box that is as large as the text lines plus the outline width. The tags \4c, \4a, \xshad and \yshad of an event set the color, the transparency and the room of its box.

Returns:

The style line, with no line break at its end.

Raises:

ValueError: When a name is empty or holds a comma, when a color is not in the form "#RRGGBB", when a number is outside its range, or when the border style is not one of BORDER_STYLES.

ass_dialogue_line

def ass_dialogue_line(
        *, start_centiseconds: int, end_centiseconds: int, style_name: str,
        text: str, layer: int = BOTTOM_LAYER) -> str

Write one dialogue line of an ASS script. It is one caption event.

Args:

start_centiseconds: Time at which the event starts to show.
end_centiseconds: Time at which the event stops to show. It must be after the start, because an event with no length never shows.
style_name: Name of the style of the event.
text: The text of the event with its tags. Each text that is shown must come from escape_ass_text.
layer: The layer of the event, 0 or above. libass draws an event over the events of the lower layers. It moves an event out of the way of another event only when the two are on one layer, so two events that must sit at one place need two layers.

Returns:

The dialogue line, with no line break at its end.

Raises:

ValueError: When a time or the layer is not a whole number of 0 or above, when the end is not after the start, when the style name is empty or holds a comma, or when the text holds a line break.

build_ass_script

def build_ass_script(
        video: VideoInfo, style_lines: Sequence[str],
        dialogue_lines: Sequence[str]) -> str

Write a whole ASS script for one video.

The script has the frame size of the video, so a pixel of the script is a pixel of the video.

Args:

video: The video on which the script is drawn.
style_lines: The style lines, each from ass_style_line.
dialogue_lines: The dialogue lines, each from ass_dialogue_line. No line is right for a video with no speech.

Returns:

The text of the script. Save it with the encoding UTF-8.

Raises:

ValueError: When the script has no style line.