API Reference

CompuGlobal allows for both random and searchable screencaps, images, comics strips, and gifs embedded with default or custom captions for the following TV shows:

The Simpsons, Futurama, Rick and Morty, and West Wing

AsyncCompuGlobalAPI

class compuglobal.AsyncCompuGlobalAPI(session, default_format=None, max_retries=0)

Represents a base API of the CGHMC family.

Parameters:

  • session (aiohttp.ClientSession) – The client session to use for all API calls

  • default_format (OverlayFormat | None, optional) – The default overlay format to use for all overlays/subtitles

  • max_retries (int, optional) – The maximum number of retries for all API requests

Variables:

  • BASE_URL (str) – The base url of the API

  • TITLE (str) – The title of the API

  • EXTRA_FONTS (frozenset[FontFamily]) – A frozenset of any extra fonts permitted by the API

  • discovery (DiscoveryAPI) – The discovery API with all discovery endpoints

  • media (MediaAPI) – The media API with all media endpoints

  • metadata (MetadataAPI) – The metadataAPI with all metadata endpoints

await get_screencap(*, episode=None, timestamp=None)

Get the screencap for the given episode & timestamp.

Parameters:

  • episode (str | None, optional) – An episode key

  • timestamp (int | None, optional) – A timestamp of the screencap

Returns:

The screencap for the given episode key and timestamp.

Return type:

Screencap

await search(search_text, season_minimum=None, season_maximum=None)

Perform a search of the given search text and returns a list of all the Frames.

Parameters:

  • search_text (str) – The search text to query

  • season_minimum (int | None, optional) – The minimum season allowed in the search results

  • season_maximum (int | None, optional) – The maximum season allowed in the search results

Returns:

A list of all frames found containing the search text.

Return type:

list[FrameResult]

Raises:

NoSearchResultsFoundError – Raises an error if no search results are found

await search_for_screencap(search_text, season_minimum=None, season_maximum=None)

Perform a search of the given search text and returns the top result.

Parameters:

  • search_text (str) – The search text to query

  • season_minimum (int | None, optional) – The minimum season allowed in the search

  • season_maximum (int | None, optional) – The maximum season allowed in the search

Returns:

The screencap of the top search result

Return type:

Screencap

await get_random_screencap(season_minimum=None, season_maximum=None)

Get a random TV Show screencap.

Parameters:

  • season_minimum (int | None, optional) – Minimum season number allowed in random result

  • season_maximum (int | None, optional) – Maximum season number allowed in random result

Returns:

A random screencap object.

Return type:

Screencap

await browse_episode(episode)

Get all episode metadata and subtitles for a given episode.

Parameters:

episode (str) – Episode key (S01E01)

Returns:

The episode containing all metadata and subtitles

Return type:

Episode

await get_transcript(episode, timestamp)

Get a transcript of subtitles around the given episode key and timestamp.

Parameters:

  • episode (str) – Episode key (S01E01)

  • timestamp (int) – Timestamp in the episode

Returns:

The list of subtitles

Return type:

list[Subtitle]

await discover()

Discover random moments with their screencap and caption.

Returns:

List of random screencap moments

Return type:

list[ScreencapMoment]

await navigator()

Get a summary for every single episode containing distributed frame IDs throughout the episode.

Returns:

A list of episode summaries

Return type:

list[EpisodeSummary]

await get_frames(key, timestamp, before, after)

Get a list of all valid frames before and after the timestamp of the episode.

Parameters:

  • key (str) – The episode key of the screencap.

  • timestamp (int) – The timestamp of the screencap.

  • before (int) – The number of milliseconds before the timestamp.

  • after (int) – The number of milliseconds after the timestamp.

Returns:

A list of valid frames before and after the timestamp of the episode.

Return type:

list[Frame]

await get_image_url(screencap)

Get the direct image url for the screencap without any caption.

Parameters:

screencap (Screencap) – The screencap to use for generating the image url

Returns:

The image url for the screencap without any caption.

Return type:

str

await get_comic_panel_url(screencap, subtitles=None, overlay_format=None)

Get the URL for a single comic panel showing the given screencap with subtitles.

Parameters:

  • screencap (Screencap) – The screencap to use in the comic panel

  • subtitles (list[Subtitle] | None, optional) – A list of subtitles to overlay in the comic panel

  • overlay_format (OverlayFormat | None, optional) – The formatting to use in the comic panel overlay (subtitle)

Returns:

The url of the comic panel

Return type:

str

await get_comic_strip_url(screencap, subtitles=None, overlay_format=None)

Get the URL for a comic strip showing the given screencap with subtitles.

Parameters:

  • screencap (Screencap) – The screencap to use in the comic strip

  • subtitles (list[Subtitle] | None, optional) – The subtitles to overlay in the comic strip

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

Returns:

The url of the comic strip

Return type:

str

await get_comic_maker_url(screencap, subtitles=None, overlay_format=None)

Get a url for making a comic with the given screencap, subtitles, and overlay format(s).

Parameters:

  • screencap (Screencap) – The screencap to make the comic with

  • subtitles (list[Subtitle] | None, optional) – The subtitles to override in the comic maker, by default None

  • overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The subtitle/overlay formatting to override in the comic maker, by default None

Returns:

The url for making the comic

Return type:

str

await get_gif_url(screencap, subtitles=None, overlay_format=None)

Get the URL for a gif of the given screencap with default or given subtitles.

Parameters:

  • screencap (Screencap) – The screencap to use for the gif

  • subtitles (list[Subtitle] | None, optional) – The subtitles to overlay in the gif

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

Returns:

The URL of the gif, or a comic strip as a fallback if gif rendering fails.

Return type:

str

await get_gif_maker_url(screencap, subtitles=None, overlay_format=None)

Get a url for making a comic with the given screencap, subtitles, and overlay format(s).

Parameters:

  • screencap (Screencap) – The screencap to make the comic with

  • subtitles (list[Subtitle] | None, optional) – The subtitles to override in the comic maker, by default None

  • overlay_format (OverlayFormat | list[OverlayFormat] | None, optional) – The subtitle/overlay formatting to override in the comic maker, by default None

Returns:

The url for making the comic

Return type:

str