Models¶

Frames¶

class compuglobal.Frame¶

A single frame of an episode at a point in time of a TV Show.

Variables:

id (int) – The unique identifier of the frame
key (str) – The episode key (S01E01)
timestamp (int) – The timestamp of the frame

property timecode¶

A readable timecode for the frame’s timestamp in format mm:ss.

Returns:: A readable timecode in format mm:ss
Return type:: str

class compuglobal.FrameResult¶

Bases: Frame

Extend Frame with additional context from a search result.

Variables:

content (str) – The subtitle content of the frame of this search result
title (str) – The title of the episode for this frame

Screencaps¶

class compuglobal.Screencap¶

A Screencap of an episode at a point in time of a TV Show.

Variables:

episode (EpisodeMetadata) – The metadata of the episode in the screencap
frame (Frame) – The primary frame of the screencap
subtitles (list[Subtitle]) – The subtitles of the screencap
nearby (list[Frame]) – A list of nearby frames
min_timestamp (int) – The minimum timestamp of the episode of the screencap
max_timestamp (int) – The maximum timestamp of the episode of the screencap

property key¶

The episode key of the screencap (S01E01).

Returns:: The episode key (S01E01)
Return type:: str

property timestamp¶

The timestamp of the screencap frame.

Returns:: The timestamp
Return type:: int

property timecode¶

A readable timecode for the frame’s timestamp in format mm:ss.

Returns:: A readable timecode in format mm:ss.
Return type:: str

property duration¶

Duration of screencap subtitles in milliseconds.

Returns:: Duration in milliseconds
Return type:: int

property captions¶

A list of captions for the screencap from all subtitles.

Returns:: A list of captions from the subtitles
Return type:: list[str]

property caption¶

The entire caption for the screencap from all subtitles as a string.

Returns:: The entire caption of the screencap
Return type:: str

property start¶

The earliest start timestamp from the subtitles.

Returns:: The start timestamp
Return type:: int

property end¶

The latest end timestamp from the subtitles.

Returns:: The end timestamp
Return type:: int

class compuglobal.ScreencapMoment¶

A moment from an episode with the episode title and a single subtitle.

Variables:

episode (str) – The episode key (S01E01)
timestamp (int) – The timestamp of the snapshot
content (str) – The content of the subtitle
title (str) – The title of the episode in the snapshot

property key¶

The episode key of the screencap (S01E01). Just an alias for episode.

Returns:: The episode key (S01E01)
Return type:: str

property timecode¶

A readable timecode for the frame’s timestamp in format mm:ss.

Returns:: A readable timecode in format mm:ss
Return type:: str

Episodes¶

class compuglobal.EpisodeMetadata¶

The metadata for an episode of a TV show.

Variables:

id (int) – The unique identifier of the episode
key (str) – The episode key (S01E01)
season (int) – The season number
episode_number (int) – The episode number
title (str) – The title of the episode.
director (str) – The director of the episode.
writer (str) – The writer(s) of the episode.
original_air_date (str) – The original air date of the episode (yyyy-mm-dd)
wiki_link (str) – The wikipedia link for the episode

class compuglobal.EpisodeSummary¶

A summary of an episode of a TV show.

Variables:

key (str) – The episode key (S01E01)
season (int) – The season number
episode_number (int) – The episode number
title (str) – The title of the episode
original_air_date (str) – The original air date of the episode (yyyy-mm-dd)
frames (list[int]) – A list of 20 frame IDs distributed throughout the episode.

class compuglobal.Episode¶

An entire episode of a TV show.

Variables:

episode (EpisodeMetadata) – The metadata of the episode
subtitles (list[Subtitle]) – A list of subtitles for the entire episode

Subtitles¶

class compuglobal.Subtitle¶

A Subtitle for a given period of time in a TV show.

Variables:

id (int) – The unique identifier of the subtitle
representative_timestamp (int) – The primary timestamp of the subtitle
key (str) – The episode key (S01E01)
start_timestamp (int) – The timestamp where the subtitle begins
end_timestamp (int) – The timestamp where the subtitle ends
content (str) – The content/text of the subtitle
language (str) – The language of the subtitle

property duration¶

The duration of the subtitle in milliseconds.

Returns:: The duration in milliseconds.
Return type:: int

property timecode¶

A readable timecode for the subtitle’s representative timestamp in format mm:ss.

Returns:: A readable timecode in format mm:ss
Return type:: str

Overlays¶

class compuglobal.OverlayFormat¶

The formatting style to use in an overlay.

Variables:

font_family (FontFamily) – The font to use for the text in the overlay
font_size (int) – The size of the font in the overlay
font_color (FontColor) – The color of the font as an RGBA tuple (0-255, 0-255, 0-255, 0-255)
text_position_x (int) – The position of the text on the X-axis
text_position_y (int) – The position of the text on the Y-axis
text_alignment (FontAlignment) – How to align the text of the overlay
all_caps (bool) – Whether to have all text in uppercase

property font_color_hex¶

The font color as a hex string.

Returns:: The color hex code
Return type:: str

property font_color_rgba¶

The font color as a a list of rgba values.

Returns:: The color in rgba
Return type:: list[int]

staticmethod normalise(overlay_format, size)¶

Normalise the given overlay formats into a list of given size.

Parameters:

overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The format(s) to use in the overlays:
- If None, default formatting is applied to all overlays
- If a single OverlayFormat, it is applied to all overlays
- If a list, each format is applied to the corresponding overlay in order
- If fewer formats are given than subtitles, default formatting is used for the remainder
- If more formats are given than subtitles, the extras are ignored
size (int) – The size of the desired list

Returns:

The normalised list of formats with the given size

Return type:

list[OverlayFormat]

Comics¶

class compuglobal.ComicPanel¶

Defines a comic panel of a TV show.

Variables:

key (str) – The episode key (S01E01)
timestamp (int) – The timestamp of the panel
overlays (list[ComicOverlay]) – The text overlays to use in the panel

classmethod from_screencap(*, screencap, overlay_format=None)¶

Build a comic panel from a Screencap.

Parameters:

screencap (Screencap) – Screencap to use for the comic panel
overlay_format (OverlayFormat | None, optional) – The format to use in the comic panel overlay.

Returns:

The comic panel of the screencap

Return type:

ComicPanel

property encoded¶

The base 64 encoded representation of this panel.

Returns:: A base 64 string
Return type:: str

class compuglobal.ComicStrip¶

A comic strip composed of multiple comic panels in a given layout.

Variables:

panels (list[ComicPanel]) – The list of ComicPanels to use in the comic strip
layout (ComicLayout | None, optional) – The layout to use when displaying the panels

classmethod from_screencap(*, screencap, overlay_format=None)¶

Build a comic strip from a Screencap object.

Parameters:

screencap (Screencap) – The screencap to use for the comic strip
overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The format(s) to use in the overlays. See OverlayFormat.normalise() for full details on how formats are resolved.

Returns:

The comic strip depicting the given screencap

Return type:

ComicStrip

staticmethod build_comic_overlays(subtitles, overlay_format=None)¶

Build a list comic overlays using the given subtitles and font.

Parameters:

subtitles (list[Subtitle]) – The subtitles to use for the overlays
overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The format(s) to use in the overlays. See OverlayFormat.normalise() for full details on how formats are resolved.

Returns:

A list of comic overlays

Return type:

list[ComicOverlay]

property encoded¶

The base 64 encoded representation of this comic strip.

Returns:: A base 64 string
Return type:: str

set_default_layout()¶

Set the default layout for the comic strip based on the number of panels.

Returns:: The comic strip with default layout.
Return type:: ComicStrip

class compuglobal.ComicOverlay¶

Defines an overlay to display text in a comic.

Variables:

text (str) – Text to overlay in the comic
font_family (FontFamily) – Font family to use for the text
font_size (int) – Size of the font
font_color (str) – Font color as a hex string
text_position_x (int) – Position of the text overlay on the X-axis
text_position_y (int) – Position of the text overlay on the Y-axis
text_alignment (FontAlignment) – Alignment of the text overlay
all_caps (int) – Whether to have overlay text in all uppercase
b (int) – Unknown b attribute
d (int) – Unknown d attribute

classmethod build_with_format(*, text, overlay_format)¶

Build a ComicOverlay using an OverlayFormat.

Parameters:

text (str) – The content/text of the subtitle in the overlay
overlay_format (OverlayFormat) – The format to use for all formatting in the overlay

Returns:

The comic overlay with the given formatting

Return type:

ComicOverlay

classmethod from_subtitles(*, subtitles, overlay_format=None)¶

Build a comic overlay using a list of Subtitles.

Parameters:

subtitles (list[Subtitle]) – A list of subtitles
overlay_format (OverlayFormat | None, optional) – The format to use in the overlay

Returns:

The overlay to display on a ComicPanel

Return type:

ComicOverlay

class compuglobal.ComicLayout(*values)¶

Defines a layout to be used by ComicStrip.

SINGLE = 'single'¶: A single comic panel only

WIDE = 'wide'¶: All comic panels laid out horizontally

TALL = 'tall'¶: All comic panels laid out vertically

ONE_OVER_TWO = '1over2'¶: The first panel will be laid out above the next two panels

TWO_OVER_ONE = '2x2'¶: The panels will be laid out in a 2x2 grid layout

Streams¶

class compuglobal.Stream¶

A stream/gif of a TV show.

Variables:

key (str) – The episode key (S01E01)
start (int) – The timestamp of the start the stream
end (int) – The timestamp of the end of the stream
overlays (list[StreamOverlay]) – A list of stream overlays to use throughout the stream
check_only (bool) – Whether to only check locally, or render the stream for others

classmethod from_screencap(*, screencap, overlay_format=None)¶

Build a stream using a screencap object.

Parameters:

screencap (Screencap) – The screencap to use for the Stream
overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The format(s) to use in the overlays. See OverlayFormat.normalise() for full details on how formats are resolved.

Returns:

The stream with overlays for the given screencap.

Return type:

Stream

staticmethod build_stream_overlays(screencap, overlay_format=None)¶

Build stream overlays with the given screencap, subtitles, timestamp, and font.

Parameters:

screencap (Screencap) – The screencap to use for the overlays
overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The format(s) to use in the overlays. See OverlayFormat.normalise() for full details on how formats are resolved.

Returns:

The built list of overlays for the stream

Return type:

list[StreamOverlay]

property caption¶

The entire caption of the Stream (all overlays) as a string.

Returns:: The entire caption of the stream
Return type:: str

property encoded¶

The base 64 encoded representation of this stream’s overlays.

Returns:: A base 64 string
Return type:: str

class compuglobal.StreamOverlay¶

A subtitle overlay to use in a gif for a given period of time in a TV show.

Variables:

text (str) – The content/text of the subtitle in the overlay
font_family (FontFamily) – The font to use for the text in the overlay
font_size (int) – The size of the font in the overlay
font_color (list[int]) – The color of the font as an RGB list [0-255, 0-255, 0-255]
text_position_x (int) – The position of the text on the X-axis
text_position_y (int) – The position of the text on the Y-axis
text_alignment (FontAlignment) – How to align the text of the overlay
all_caps (bool) – Whether to have all text in uppercase
start (int) – The time where the overlay begins
end (int) – The time where the overlay ends

classmethod build_with_format(*, text, start, end, overlay_format)¶

Build a StreamOverlay using an OverlayFormat.

Parameters:

text (str) – The content/text of the subtitle in the overlay
start (int) – The time where the overlay begins
end (int) – The time where the overlay ends
overlay_format (OverlayFormat) – The format to use for all formatting in the overlay

Returns:

The overlay with the given formatting

Return type:

StreamOverlay

dump_minified()¶

Dump a minified version of the overlay for use in base64.

Returns:: The minified dump for use in base64.
Return type:: dict[str, Any]

Fonts¶

class compuglobal.FontColor¶

A color for a font.

Variables:

red (int) – The amount of red in the color (0-255)
green (int) – The amount of green in the color (0-255)
blue (int) – The amount of blue in the color (0-255)
alpha (int, optional) – The amount of alpha transparency in the color (0-255)

property rgba¶

The font color as a list of the rgba values.

Returns:: A list of the rgba values in that order [red, green, blue, alpha]
Return type:: list[int]

property hex¶

The font color as a hex string.

Returns:: The color hex code
Return type:: str

classmethod from_rgba(r, g, b, a)¶

Create a FontColor from rgba.

Parameters:

r (int) – Red (0-255)
g (int) – Green (0-255)
b (int) – Blue (0-255)
a (int) – Alpha (0-255)

Returns:

The font color

Return type:

FontColor

classmethod from_hex(hex_str)¶

Create a FontColor from a hex string.

Parameters:: hex_str (str) – A hex color string, with or without a leading #. Supports 6-character (RRGGBB) or 8-character (RRGGBBAA) formats. Alpha is 255 if not given.
Returns:: The color represented by the hex string
Return type:: FontColor
Raises:: ValueError – If the hex string is not 6 or 8 characters (excluding #)

class compuglobal.FontAlignment(*values)¶

An enumeration of font alignments.

ALIGN_LEFT = 'l'¶: Align the text to the left

ALIGN_RIGHT = 'r'¶: Align the text to the right

ALIGN_CENTER = 'c'¶: Align the text to the center

class compuglobal.FontFamily(*values)¶

An enumeration of font families.

IMPACT = 'impact'¶: The impact font family

COMIC_NEUE = 'comicneue'¶: The Comic Neue font family

JOST = 'jost'¶: The Jost font family

PACIFICO = 'pacifico'¶: The Pacifico font family

AKBAR = 'akbar'¶: The Akbar font family (Frinkiac default)

FR_BOLD = 'fr'¶: The Fr Bold font family (Morbotron default)

staticmethod universal_fonts()¶

Get a list of universal fonts that work across all APIs.

Returns:: List of universal fonts
Return type:: list[FontFamily]

Timestamp¶

class compuglobal.Timestamp¶

Helper class for working with timestamps.

staticmethod get_minutes_seconds(milliseconds)¶

Get minutes and seconds from milliseconds.

Parameters:: milliseconds (int) – The length of time in milliseconds
Returns:: The minutes, and seconds as a tuple
Return type:: tuple[int, int]

staticmethod get_timecode(timestamp)¶

Get a readable timestamp for the frame in format mm:ss.

Parameters:: timestamp (int) – The timestamp to convert to readable string
Returns:: A readable timestamp for the frame in format mm:ss.
Return type:: str

staticmethod get_duration(start_timestamp, end_timestamp)¶

Get the duration of the subtitle in milliseconds.

Parameters:

start_timestamp (int) – The start timestamp used in calculating the duration
end_timestamp (int) – The start timestamp used in calculating the duration

Returns:

The duration in milliseconds.

Return type:

int

staticmethod get_subtitles_duration(subtitles)¶

Get the duration between the start of the earliest subtitle, and the end of the latest subtitle.

Parameters:: subtitles (list[Subtitle]) – The subtitles
Returns:: The duration in milliseconds
Return type:: int

Base Model:

class compuglobal.models.base.BaseCompuGlobalModel

Base model class used for all API models.

model_config = ConfigDict(
    extra="forbid",
    frozen=True,
    serialize_by_alias=True,
    validate_by_alias=True,
    validate_by_name=True,
)