jwlib.media

Wrappers for the “mediator” API used in the video section at jw.org.

The common way to start is to create a Session in your language of choice, use get_category() to get the root and work your way from there using get_subcategories() and get_media():

>>> import jwlib.media as jw
>>> session = jw.Session(language='E')
>>> broadcasting = session.get_category('VODStudio')
>>> for subcategory in broadcasting.get_subcategories():
>>>     for media in subcategory.get_media():
>>>         file = media.get_file()
>>>         print(media.title, file.url)

class jwlib.media.Session(language='E', client_type: str = 'firetv')

Used to fetch Category and Media from the server.

__init__(language='E', client_type: str = 'firetv')

Set up a session used to fetch Category and Media.

Fetched categories are cached within the session.

Parameters:

• language – JW language code.

• client_type – The default is CLIENT_FIRETV. To get as much data as possible use CLIENT_NONE.

cached_categories() → Iterable[Category]

Read-only list of the cached categories.

Clearing the cache is not supported. If you want to refresh single category you may call Category.refresh(), or you can start a new Session to refresh everything.

Categories are intimately tied to their session. Removing them from the cache would create problems when retrieving child or parent classes.

load_categories(cache: Iterable[dict]) → None

Load category data from a cache dump.

This updates existing categories similar to dict.update().

dump_categories() → list[dict]

Dump category cache to a format that may be serialized to JSON etc.

get_category(key='All', *, include_media=True) → Category

Get a Category from cache or from the server.

Parameters:

• key – Code name.

• include_media – Setting this to False may speed up JSON parsing significantly for some categories, but will result in extra requests if get_media() is called later.

request_category(key: str, *, include_media=True) → Category

Same as get_category() but always requests new data from the server.

create_category(category_data: dict, *, parent_key: str | None = None) → Category

Create or update a cached Category using the given data.

request_media(key: str) → Media

Request a Media object from the server.

Unlike get_category() this returns a new instance each time.

class jwlib.media.Category(session: Session, data: dict, parent_key: str | None = None)

Information about a category and its subcategories and media.

You wouldn’t normally initialize this yourself. Use Session.get_category() instead.

__init__(session: Session, data: dict, parent_key: str | None = None)

get_media() → Iterator[Media]

Iterate over Media items.

More items will be requested from the server on-the-fly, if needed.

Note

The iterator returns new instances of Media on each run, so they cannot be compared by identity, but their underlying dictionary Media.data can because it remains the same.

get_parent() → Category | None

Return parent Category.

If the parent is unknown, a request will be sent to the server.

get_subcategories(*, include_media=True) → Iterator[Category]

Iterate over subcategories.

If subcategories are unknown, a request will be sent to the server.

Parameters:

include_media – see Session.get_category()

property description: str

property key: str

Code name.

property name: str

Display name.

refresh(*, include_media=True)

Requests new category data

Calling this on a category that has been removed from Session.cached_categories raises a RuntimeError.

property type: str

Category type.

container if it has subcategories or ondemand if it has media.

get_image(ratios: Iterable[str] = (), sizes: Iterable[str] = ()) → str | None

Return URL to first matching image.

Parameters:

• ratios – list of image ratios.

• sizes – list of image sizes.

To select the desired image use RATIOS_* and SIZES_* found in the const module. Alternatively hand pick ratios and sizes from the imagetable.

By default return the largest 16:9 image, or 1:1 if the item is tagged TAG_PREFER_SQUARE_IMAGES.

Note

The client type affects what images are available.

property tags: list[str]

Return list of tags, see const.

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.media.Media(session: Session, data: dict, parent: Category | None)

Information about a media item.

You wouldn’t normally initialize this yourself. Use Session.request_media() or Category.get_media() instead.

__init__(session: Session, data: dict, parent: Category | None)

property description: str

property duration: int

Duration in seconds.

property duration_HHMM: str

Duration as a string, like 2:16.

property duration_min_sec: str

Duration as a string, like 2m 16s.

get_file(*, resolution=1080, subtitles=False) → File

Return the File that best matches these criteria.

Parameters:

• resolution – max resolution

• subtitles – whether file should have subtitles (soft is preferred over hard)

Raises IndexError if no file is found.

Note

New instances of File are returned on each run, so they cannot be compared by identity, but their underlying dictionary File.data can because it remains the same.

get_files() → Iterator[File]

Iterate over Files.

Note

New instances of File are returned on each run, so they cannot be compared by identity, but their underlying dictionary File.data can because it remains the same.

property guid: str

24 character long hexadecimal identifier.

property key: str

Code name, language agnostic.

This is the key you use to request media info from the server.

property key_with_language: str

Code name, including language code.

Looks similar to the filename, but not the same. Use case unknown.

property languages: list[str]

List of languages in which this item is available.

get_primary_category(*, include_media=False) → Category

Return the primary parent category.

If the category is not in the cache, a request will be sent to the server.

Parameters:

include_media – see Session.get_category()

property primary_category_key: str

Code name of the primary parent category.

property published: str

Date when first published, formatted according to TIME_FORMAT.

property subtitle_url: str | None

Convenience method to get first available subtitle URL.

property title: str

Display name.

property type: str

Media type, like audio or video.

get_image(ratios: Iterable[str] = (), sizes: Iterable[str] = ()) → str | None

Return URL to first matching image.

Parameters:

• ratios – list of image ratios.

• sizes – list of image sizes.

To select the desired image use RATIOS_* and SIZES_* found in the const module. Alternatively hand pick ratios and sizes from the imagetable.

By default return the largest 16:9 image, or 1:1 if the item is tagged TAG_PREFER_SQUARE_IMAGES.

Note

The client type affects what images are available.

property tags: list[str]

Return list of tags, see const.

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.media.File(data: dict)

Information about a downloadable file.

property bitrate: float

Bitrate in kb/s.

property checksum: str | None

MD5 checksum.

property duration: int

Duration in seconds.

property filename

File name of downloadable file.

property frame_rate: float

property height: int

Frame height.

property mimetype: str

property modified: str

Modification time, formatted according to TIME_FORMAT.

property print_references: list[str]

List of code names that may be found in the literature.

property resolution: int

Video resolution.

This is the human readable value and not the actual video height. Common values are 240, 360, 480, 720, 1080, or 0 if it’s an audio file.

property size: int

File size in bytes.

property subtitle_checksum: str | None

MD5 checksum for the subtitle file.

property subtitle_date: str | None

Subtitle modification time, formatted according to TIME_FORMAT.

property subtitle_url: str | None

property subtitled_hard: bool

Has subtitles hardcoded in the video frame.

property subtitled_soft: bool

Has external subtitles.

property url: str

URL for downloading.

__init__(data: dict)

property width: int

Frame width.

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

class jwlib.media.Language(data: dict)

Information about a language

property code: str

JW language code

The one that can be passed to Session etc.

property iso: str

ISO 639 language code

property name: str

Display name

property rtl: bool

True if written right to left

property script: str

Type of script, like ‘ROMAN’ or ‘CYRILLIC’

property signed: bool

True if it’s a sign language

property vernacular: str

Display name in the language itself

__init__(data: dict)

data: dict

Object data as returned by the server.

If you need access to information that has no getter method, you can get it here.

Note

Editing this directory is an untested feature.

jwlib.media.request_languages(language='E') → list[Language]

Return list of available Languages

jwlib.media.request_translations(language: str) → dict

Return a dict of string IDs and translated string used at the website

exception jwlib.media.NotFoundError

Raised when the server returns HTTP 404

__init__(*args, **kwargs)

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.