CmafHam

A Python library for the parsing, manipulation and creation of HLS and DASH manifests using the CMAF ‘Hypothetical Application Model’ as defined in ISO/IEC 23000-19.

Inspired by the Common Media Library CMAF-HAM project:
copyright:

  1. 2024 Shayne Reese.

license:

MIT, see LICENSE for more details.

version:

0.0.1

exception cmafham.InputManifestError[source]

Bases: Exception

Exception to be raised when input is missing or for invalid manifest formats.

exception cmafham.MissingSegmentError[source]

Bases: Exception

Exception to be raised when segment files cannot be found or loaded properly.

cmafham.from_segments(base_uri: str = None, segments: list[str] = None) → HAM[source]

NOT IMPLEMENTED! Create a ‘HAM’ object based on the segment files.

Parameters:

  • base_uri (str) – base path location for segments.

  • segments – list of segment filenames.

Returns:

A ‘HAM’ object representing the media presentation.

Return type:

cmafham.ham.HAM

Raises:

MissingSegmentError – when segment files are missing or loading fails.

cmafham.load(manifest_uri: str) → HAM[source]

Create a ‘HAM’ object from a uri/url.

Parameters:

manifest_uri (str) – file path or url of the manifest to use.

Returns:

‘HAM’ of the source presentation containing the ‘Presentation’, ‘HLS’, and ‘DASH’ objects.

Return type:

cmafham.ham.HAM

Raises:

InputManifestError – When an invalid file extension is given.

cmafham.loads(manifest_string: str, hls_renditions: list[str] = None, hls_media: list[str] = None, file_uri: str = None) → HAM[source]

Create a ‘HAM’ object from string(s).

Parameters:

  • manifest_string (str) – string representation of manifest.

  • hls_renditions (list[str]) – strings of the HLS variant playlists, optional.

  • hls_media (list[str]) – strings of HLS media playlists, optional.

  • file_uri (str) – path to the media files.

Returns:

Object model of the source presentation containing the CMAF ‘Presentation’, ‘HLS’, and ‘DASH’ objects.

Return type:

cmafham.ham.HAM

Raises:

InputManifestError – When the manifest type can’t be parsed or is invalid.

cmafham.ham

This module contains the core objects and functions to perform the parsing and mapping to the models.

copyright:

  1. 2024 Shayne Reese.

license:

MIT, see LICENSE for more details.

class cmafham.ham.CmafSegmentMapper[source]

Bases: object

NOT IMPLEMENTED! Class to map CMAF file iso box data into CMAF-HAM model format.

classmethod create_swset(data)[source]

Create a CMAF ‘SwitchingSet’ for a set of files. Need to split the file box data into some subset of groups before this step most likely.

classmethod map(data) → List[SwitchingSet][source]

Try to create and return CMAF ‘SwitchingSet’s for the given data. Need to filter the data at this point…

classmethod parse_tracks(data)[source]

Create CMAF ‘Track’ objects from the file data. Need to parse track type to determine the relevant data to parse.

classmethod subtitle(data)[source]

Parse a single subtitle file? TODO: Think of the best way to handle subtitles here, may need a second function to create the actual track…

class cmafham.ham.DashSegmentParser[source]

Bases: object

NOT IMPLEMENTED! Class to parse data from different types of DASH manifest segment types, to return the data in a uniform way for the ‘DashTrackMapper’ functions.

static base(data1, data2)[source]

Parse segment_base data, format and return.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

static list(data1, data2)[source]

Parse segment_list data, format and return.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

static template(data1, data2)[source]

Parse segment_template data, format and return.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

class cmafham.ham.DashTrackMapper[source]

Bases: object

NOT IMPLEMENTED! Class for mapping ‘MPEGDASH’ objects to CMAF ‘Track’ objects.

classmethod audio(data1, data2, data3) → AudioTrack[source]

Create an ‘AudioTrack’ from the data.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

  • data3 – placeholder parameter.

Returns:

Audio track object

Return type:

cmafham.models.AudioTrack

static iso_time(time_str: str) → float[source]

Return an ISO 8601 time string as a float value in seconds.

Parameters:

time_str (str) – ISO-8601 formatted time string from DASH manifest ex. (“PT10M34.533S”).

Returns:

time as a float value in seconds.

Return type:

float

classmethod map(adaptation: AdaptationSet, representation: Representation, duration: float = None) → AudioTrack | TextTrack | VideoTrack | None[source]

Master track mapping function, determines the type and employs the appropriate mapper and returns the assembled track.

Parameters:

  • adaptation (mpegdash.nodes.AdaptationSet) – adaptation set object.

  • representation (mpegdash.nodes.Representation) – representation object.

  • duration – DASH period duration.

Returns:

CMAF track object if parsed, else None.

Return type:

AudioTrack or TextTrack or VideoTrack or None

classmethod text(data1, data2, data3) → TextTrack[source]

Create an ‘TextTrack’ from the data.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

  • data3 – placeholder parameter.

Returns:

Text track object

Return type:

cmafham.models.TextTrack

classmethod video(data1, data2, data3) → VideoTrack[source]

Create an ‘VideoTrack’ from the data.

Parameters:

  • data1 – placeholder parameter.

  • data2 – placeholder parameter.

  • data3 – placeholder parameter.

Returns:

Video track object

Return type:

cmafham.models.VideoTrack

class cmafham.ham.HAM(presentation: Presentation, hls_obj: HLS = None, dash_obj: DASH = None)[source]

Bases: object

The ‘Hypothetical Application Model’ object is the container for the CMAF ‘Presentation’, ‘HLS’ and ‘DASH’ objects.

Parameters:

  • presentation (cmafham.models.Presentation) – The CMAF ‘Presentation’ object representation of the media presentation.

  • hls_obj (cmafham.models.HLS) – the ‘HLS’ wrapper object that contains the HLS presentation data.

  • dash_obj (cmafham.models.DASH) – the ‘DASH’ wrapper object that contains the DASH presentation data.

render_dash(save_to: str = None, filename: str = None) → None[source]

Create a manifest file for the DASH presentation.

TODO: clean up the filename, possibly use other defaults or self.presentation.id.

Parameters:

  • save_to (str) – location to save the manifest file, optional, defaults to cwd.

  • filename (str) – filename for the manifest, optional, defaults to ‘main’.

render_ham(save_to: str = None, filename: str = None) → None[source]

Create a JSON manifest file of the CMAF ‘Presentation’.

render_hls(save_to: str = None, filename: str = None) → None[source]

Create the manifest files for the HLS presentation.

TODO: clean up the filename, possibly use other defaults or self.presentation.id.

Parameters:

  • save_to (str) – path to save the manifest files to, optional, defaults to cwd.

  • filename (str) – filename for the manifest, optional, defaults to ‘main’.

update() → None[source]

Create the missing object(s) from the CMAF ‘Presentation’.

class cmafham.ham.HamMapper[source]

Bases: object

HLS <–> Presentation <–> DASH

static dash_to_ham(dash_obj: DASH) → HAM[source]

Create a ‘HAM’ object from the ‘DASH’ object.

TODO: write functions to parse for each dash segment type

(segment list, segment template, segment base..).

Parameters:

dash_obj (cmafham.models.DASH) – ‘DASH’ object of the media presentation.

Returns:

‘HAM’ object for the media presentation.

Return type:

cmafham.ham.HAM

static ham_manifest(uri: str = None, string: str = None) → HAM[source]

Create a HAM object from a saved CMAF ‘Presentation’ ‘manifest’ file or string.

Parameters:

  • uri (str) – path to the manifest json file.

  • string (str) – string representation of the manifest.

Returns:

HAM object for the media presentation.

Return type:

cmafham.ham.HAM

static ham_to_dash(presentation: Presentation) → DASH[source]

Map the properties of a CMAF ‘Presentation’ to a ‘DASH’ object.

static ham_to_hls(presentation: Presentation) → HLS[source]

Map the properties of a CMAF ‘Presentation’ to an ‘HLS’ object.

Parameters:

presentation (cmafham.models.Presentation) – CMAF ‘Presentation’ object for the media presentation.

Returns:

‘HLS’ representation of the CMAF ‘Presentation’

Return type:

cmafham.models.Presentation

static hls_to_ham(hls_obj: HLS) → HAM[source]

Create a ‘HAM’ object from the ‘HLS’ object.

Parameters:

hls_obj (cmafham.models.HLS) – object representation of HLS manifest/presentation.

Returns:

HAM object containing the CMAF ‘Presentation’, ‘HLS’, and ‘DASH’ representations.

Return type:

cmafham.ham.HAM

static segments_to_ham(base_uri: str = None, segments: list[str] = None) → HAM[source]

NOT IMPLEMENTED! Create a ‘Presentation’ from CMAF encoded segments, then return a ‘HAM’ object from that.

Parameters:

  • base_uri (str) – base path location for segments.

  • segments – list of segment filenames.

Returns:

A ‘HAM’ object representing the media presentation.

Return type:

cmafham.ham.HAM

class cmafham.ham.HlsPresentationMapper[source]

Bases: object

NOT IMPLEMENTED! Class for mapping CMAF ‘Presentation’ data to an ‘HLS’ object.

classmethod audio(track: AudioTrack) → Media[source]

Create audio ‘m3u8.model.Media’ objects.

TODO: possibly set other attr’s with defaults, ie. ‘default’, ‘autoselect’, ‘name’…

Parameters:

track (cmafham.models.AudioTrack) – audio track object.

Returns:

m3u8 media object.

Return type:

m3u8.model.Media

classmethod manifest(playlists: PlaylistList, media: MediaList = None) → M3U8[source]

Create and assemble the ‘m3u8.model.M3U8’ for the data.

TODO: possibly set defaults for version etc.; use ‘flag’ attrs to determine any other neccesary options could be necesary if coming from dash/ham to enable certain features…

Parameters:

  • playlists (m3u8.model.PlaylistList) – variant playlists.

  • media (m3u8.model.MediaList) – hls media information.

classmethod media(tracks: List[AudioTrack] | List[TextTrack]) → MediaList[source]

Maps AudioTrack or TextTrack into HLS EXT-X-MEDIA data.

Parameters:

tracks (list[AudioTrack] or list[TextTrack]) – media track data.

Returns:

M3U8 media data

Return type:

m3u8.model.MediaList

classmethod text(track: TextTrack) → Media[source]

Create CLOSED-CAPTION or SUBTITLE ‘m3u8.model.Media’ objects.

Parameters:

track (cmafham.models.TextTrack) – subtitle/closed caption data.

Returns:

subtitle/closed caption media data.

Return type:

m3u8.model.Media

classmethod variant(track: AudioTrack | TextTrack | VideoTrack, playlist: Playlist = None, media: Media = None) → M3U8[source]

Create a ‘m3u8.model.M3U8’ object for media/variant playlist, to create a manifest file…

Parameters:
Returns:

media playlist ‘M3U8’ object.

Return type:

m3u8.model.M3U8

classmethod video(tracks: list[VideoTrack], media: MediaList) → PlaylistList[source]

Create ‘m3u8.model.Playlist’ objects for video.

Parameters:

  • tracks (list[VideoTrack]) – list of video tracks.

  • media (m3u8.model.MediaList) – list of media objects.

Returns:

list of variant playlists.

Return type:

m3u8.model.PlaylistList

class cmafham.ham.HlsTrackMapper[source]

Bases: object

Class for the mapping of HLS variant stream properties to CMAF ‘Track’ objects .

classmethod audio(media: Media, base_uri: str = '', audiolist: M3U8 = None, playlists: PlaylistList = None) → AudioTrack[source]

Map the properties of ‘M3U8’ objects to a CMAF ‘AudioTrack’ object.

TODO: parse sample rate and bandwidth.

Parameters:

  • media (m3u8.model.Media) – HLS EXT-X-MEDIA data.

  • base_uri (str) – base uri path for the files, optional.

  • audiolist (m3u8.model.M3U8) – HLS manifest of audio data, optional.

  • playlists (m3u8.model.PlaylistList) – list of variant playlists, optional.

Returns:

CMAF audio track object.

Return type:

cmafham.models.AudioTrack

classmethod text(media: Media, base_uri: str = '', playlist: M3U8 = None) → TextTrack[source]

Maps the properties of HLS subtitles to a CMAF ‘TextTrack’ object.

Parameters:

  • media (m3u8.model.Media) – HLS EXT-X-MEDIA data.

  • base_uri (str) – base uri path for the files. (optional)

  • playlist (m3u8.model.M3U8) – HLS media playlist. (optional)

Returns:

CMAF text track object of subtitles.

Return type:

cmafham.models.TextTrack

classmethod video(playlist: Playlist, base_uri: str = '', variant: M3U8 = None) → VideoTrack[source]

Map the properties of M3U8 objects to a CMAF ‘VideoTrack’ object.

Parameters:

  • playlist (m3u8.model.Playlist) – variant playlist data from multivariant playlist.

  • base_uri (str) – base uri path for the files. (optional)

  • variant (m3u8.model.M3U8) – HLS media playlist. (optional)

Returns:

CMAF video track object.

Return type:

cmafham.models.VideoTrack

cmafham.models

CmafHam object models for the CMAF Presentation structure and the HLS and DASH containers.

[CMAF] ISO/IEC 23000-19:2020, Information technology — Coding of audio-visual objects — Part 19: Common media application format (CMAF) for segmented media.

copyright:

  1. 2024 Shayne Reese.

license:

MIT, see LICENSE for more details.

class cmafham.models.AudioTrack(id_: str = '', codec: str = '', channels: int = 0, duration: float | int = 0.0, language: str = '', segments: List[Segment] = None, sample_rate: float | int = 0.0, bandwidth: int = 0, url_init: str = '', filename: str = '', base_uri: str = '', **flags)[source]

Bases: object

CMAF Audio Track

(from [CMAF]) Sequence of CMAF Fragments that are consecutive in presentation time, contain one media stream, conform to at least one structural CMAF brand, including an associated CMAF Header that can initialize playback.

Parameters:

  • id (str) – track id, hls=group_id.

  • codec (str) – audio codec.

  • channels (int) – number of audio channels.

  • duration (float or int) – track duration in seconds.

  • language (str) – audio language.

  • segments (list[cmafham.models.Segment]) – CMAF Segment objects for the track.

  • sample_rate (float or int) – audio sample rate.

  • bandwidth (int) – track bandwith.

  • url_init (str) – uri/url of initilization segment.

  • flags – helper/optional flags for format specfic mapping.

as_dict()[source]

Return as a dictionary.

class cmafham.models.DASH(uri: str = None, string: str = None, mpd_obj: MPEGDASH = None)[source]

Bases: object

Base class to contain all DASH data.

Parameters:

  • uri (str) – uri/url of the mpd manifest.

  • string (str) – string of the mpd manifest.

  • mpd_obj (mpegdash.nodes.MPEGDASH) – MPEGDASH object already created from manifest.

class cmafham.models.HLS(uri: str = None, string: str = None, variants: List[str] = None, media: List[str] = None, m3u8_obj: M3U8 = None)[source]

Bases: object

Base class for containing all HLS data.

Parameters:

  • uri (str) – uri/url of the m3u8 manifest.

  • string (str) – string of the m3u8 manifest.

  • variants (list[str]) – strings of the variant playlists.

  • media (list[str]) – strings of the media playlists.

  • m3u8_obj (m3u8.model.M3U8) – a m3u8.model.M3U8 object that has already been created.

Raises:

InputMissingError – when no input manifest or object is provided.

class cmafham.models.HlsMedia(media: Media, medialist: M3U8)[source]

Bases: object

Container for a ‘m3u8.model.Media’ object and its corresponding ‘m3u8.model.M3U8’ playlist object.

Parameters:

  • media (m3u8.model.Media) – EXT-X-MEDIA object from the multivariant playlist.

  • medialist (m3u8.model.M3U8) – ‘M3U8’ playlist for the ‘Media’ object content.

class cmafham.models.HlsVariant(plist: Playlist, playlist: M3U8)[source]

Bases: object

Container for a ‘m3u8.model.Playlist’ object and its corresponding ‘m3u8.model.M3U8’ playlist object.

Parameters:

  • plist (m3u8.model.Playlist) – ‘Playlist’ object representing a variant playlist.

  • playlist (m3u8.model.M3U8) – ‘M3U8’ playlist object for the variant playlist.

exception cmafham.models.InputMissingError[source]

Bases: Exception

Raised when no manifest is supplied for object creation.

class cmafham.models.Presentation(id_: str, selection_sets: list[SelectionSet])[source]

Bases: object

CMAF Presentation

(from [CMAF]) Set of one or more CMAF Selection Sets that can be simultaneously decoded to produce a multimedia user experience, potentially including synchronized audio, video, and subtitles.

Parameters:

  • id (str) – presentation id, version 4 uuid.

  • selection_sets (list[SelectionSet]) – ‘SelectionSet’(s) for the Presentation.

as_dict()[source]

Return as dictionary.

class cmafham.models.Segment(filename: str = '', duration: float | int = 0.0, url: str = '', byterange: str = None, **flags)[source]

Bases: object

CMAF Segment

(from [CMAF]) CMAF Addressable Media Object consisting of one or more consecutive CMAF Fragments from the same CMAF Track.

Parameters:

  • filename (str) – filename of the segment

  • duration (float or int) – segment duration in seconds.

  • url (str) – full url/uri of segment.

  • byterange (str) – byterange of segment.

  • flags – helper/optional flags for format specfic mapping.

as_dict()[source]

Return as a dictionary.

class cmafham.models.SelectionSet(id_: str, switching_sets: list[SwitchingSet])[source]

Bases: object

CMAF Selection Set

(from [CMAF]) Set of one or more CMAF Switching Sets, where each CMAF Switching Set encodes an alternative aspect of the same presentation over the same time period, only one of which is intended to be played at a time, e.g. an alternative language or codec.

Parameters:

  • id (str) – switching set id, version 4 uuid.

  • switching_sets (list[cmafham.models.SwitchingSet]) – ‘SwitchingSet’(s) for the ‘SelectionSet’.

as_dict()[source]

Return as dictionary.

class cmafham.models.SwitchingSet(id_: str, track_type: str, tracks: List[AudioTrack] | List[TextTrack] | List[VideoTrack])[source]

Bases: object

CMAF Switching Set

(from [CMAF]) Set of one or more CMAF Tracks, where each track is an alternative encoding of the same source content, and are constrained to enable seamless track switching.

Parameters:
as_dict()[source]

Return as a dictionary.

class cmafham.models.TextTrack(id_: str = '', codec: str = '', duration: float | int = 0.0, language: str = '', segments: List[Segment] = None, filename: str = '', base_uri: str = '', **flags)[source]

Bases: object

CMAF Text Track

(from [CMAF]) Sequence of CMAF Fragments that are consecutive in presentation time, contain one media stream, conform to at least one structural CMAF brand, including an associated CMAF Header that can initialize playback.

Parameters:

  • id (str) – track id, hls=group_id.

  • codec (str) – subtitle codec or embedded captions.

  • duration (float or int) – track duration.

  • language (str) – subtitle language.

  • segments (cmafham.models.Segment) – CMAF Segment objects for the track.

  • flags – helper/optional flags for format specfic mapping.

as_dict()[source]

Return as a dictionary.

class cmafham.models.VideoTrack(id_: str = '', codec: str = '', duration: float | int = 0.0, language: str = '', bandwidth: int = 0, segments: list[Segment] = None, width: int = 0, height: int = 0, framerate: float | int = 0.0, par: str = '', sar: str = '', scan_type: str = '', filename: str = '', base_uri: str = '', **flags)[source]

Bases: object

CMAF Video Track

(from [CMAF]) Sequence of CMAF Fragments that are consecutive in presentation time, contain one media stream, conform to at least one structural CMAF brand, including an associated CMAF Header that can initialize playback.

Parameters:

  • id (str) – video track id, hls=version 4 uuid.

  • codec (str) – video codec.

  • duration (float or int) – track duration.

  • language (str) – video language.

  • bandwidth (int) – track bandwidth.

  • segments (cmafham.models.Segment) – CMAF Segment objects for the track.

  • width (int) – video width.

  • height (int) – video height.

  • framerate (float or int.) – video frame rate.

  • par (str) – video par.

  • sar (str) – video sar.

  • scan_type (str) – video scan type (“interlaced” | “progressive”).

  • flags – helper/optional flags for format specfic mapping.

as_dict()[source]

Return as a dictionary.

cmafham.utils

CmafHam helper functions.

copyright:

  1. 2024 Shayne Reese.

license:

MIT, see LICENSE for more details.

cmafham.utils.float_fr(framerate: float | int | str) → float[source]

Parse various frame rate representations and return as float value.

Parameters:

framerate (float or int or str) – video frame rate.

Returns:

float value of framerate if parsed, else 0.0.

Return type:

float

cmafham.utils.gen_uuid() → str[source]

Generate a random uuid string. :returns: version 4(random) uuid string. :rtype: str

cmafham.utils.get_manifest_string(manifest_uri: str) → str[source]

Load a manifest as a string from a file or url.

Parameters:

manifest_uri (str) – web url or uri path of manifest.

Returns:

string of the manifest or an empty string.

Return type:

str

cmafham.utils.get_path(file_path: str = '') → str[source]

Obtain the base path by removing the filename, otherwise, return the current dir.

Parameters:

file_path (str) – uri of the file

Returns:

base path to parent file, or cwd

Return type:

str

cmafham.utils.load_file(file_uri: str) → BufferedReader | BytesIO | None[source]

Download or open a file-like object.

:param str file_uri : str - url or path to file. :returns: file like object or nothing if unsucessful. :rtype: io.BufferedReader or io.BytesIO or None

cmafham.utils.parse_codec(codec_string: str) → List[tuple][source]

Return the codec(s) and their type from a string.

TODO: Implement the ‘codec_strings’ parser module eventually for more meaningful data.

Parameters:

codec_string (str) – mime type codec string.

Returns:

list of present codecs and their type.

Return type:

list[tuple]

cmafham.utils.remove_ext(filename: str) → str[source]

Remove the extension of a filename.

Parameters:

filename (str) – full uri of file.

Returns:

tail of path(filename) without extension.

Return type:

str

cmafham.cmaf

NOT IMPLEMENTED! This module parses CMAF encoded files for mapping to a CMAF Presentation.

copyright:

  1. 2024 Shayne Reese.

license:

MIT, see LICENSE for more details.

class cmafham.cmaf.BoxParser[source]

Bases: object

NOT IMPLEMENTED! Class for Parsing ISOBMFF boxes, returns any relevant data.

classmethod parse(box) → dict[source]

Parse the box by using the parser for its type.

class cmafham.cmaf.CMAF[source]

Bases: object

NOT IMPLEMENTED! Core container for CMAF file box data.

TODO: Needs to be flexible for file type, and data types, etc. * init files contain more attribute data. * classify between init or media. * need to find a way to group media files within their init file group.

class cmafham.cmaf.CmafInitSegment[source]

Bases: object

NOT IMPLEMENTED! Container for CMAF initilization segment files.

TODO: try to group the content files here as well.

class cmafham.cmaf.CmafMediaSegment[source]

Bases: object

NOT IMPLEMENTED! Container for CMAF media files.

TODO: extract meaningful data, how to match with an init segment..

cmafham.cmaf.parse_children(box) → dict[source]

NOT IMPLEMENTED! Parse a box and all of it’s child boxes, return the extracted data as a dict for further parsing/analysis.

TODO: think of how to best handle/present the return data.

cmafham.cmaf.parse_cmaf_file(filename: str)[source]

NOT IMPLEMENTED!

TODO: Think of the best way to do this, seems like the init files will be the only way to get the properties right.

TODO: work on getting the proper files aligned with the init file, probably parse all files, and then create a function to add matching content objects to an init object…