imflib.cpl

st2067-2-2020: Composition Playlist

Composition Playlist and its related classes

Based on st-2067-3-2020: https://ieeexplore.ieee.org/document/9097510/

The Composition Playlist (Cpl) combines the assets in an IMF to a timeline. A CPL is divided into one or more Segments.

Each Segment contains one or more Sequences, which are more or less analogous to tracks in a traditional NLE.

Each Sequencereferences one or more Resources, which are analogous to subclips in a traditional NLE.

Resources comprised of external files are TrackFileResources. The file path to each TrackFileResouces can be resolved by cross-referencing the UUID in TrackFileResource.track_file_id with the UUID in imflib.pkl.Asset.id and imflib.assetmap.Asset.id.

class imflib.cpl.AudioResource(intrinsic_duration: int, id: ~uuid.UUID = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, edit_rate: ~typing.Optional[~imflib.cpl.EditRate] = None, entry_point: int = 0, source_duration: ~typing.Optional[int] = None, repeat_count: int = 1, _src_sequence: ~typing.Optional[~imflib.cpl.Sequence] = None, _src_offset: int = 0, source_encoding: ~uuid.UUID = <factory>, track_file_id: ~uuid.UUID = <factory>, key_id: ~typing.Optional[~uuid.UUID] = None, hash: ~typing.Optional[str] = None, hash_algorithm: ~typing.Optional[str] = None, edit_units_label: str = 'Hz')

Bases: TrackFileResource

A main audio resource

edit_units_label: str = 'Hz'

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → AudioResource: Parse an audio resource from XML

class imflib.cpl.BaseResource(intrinsic_duration: int, id: ~uuid.UUID = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, edit_rate: ~typing.Optional[~imflib.cpl.EditRate] = None, entry_point: int = 0, source_duration: ~typing.Optional[int] = None, repeat_count: int = 1, _src_sequence: ~typing.Optional[~imflib.cpl.Sequence] = None, _src_offset: int = 0)

Bases: ABC

A BaseResource XSD within a sequence

annotation: Optional[UserText] = None: Description of this resource

property duration: int: Duration in frames for now

property edit_range: TimecodeRange: In/out point of subclip

edit_rate: Optional[EditRate] = None: The edit rate of this resource

entry_point: int = 0: The desired start of the playable region (in-point) in resource edit units

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → BaseResource

id: UUID: UUID of the resource

intrinsic_duration: int: The native duration of the full source asset, in resource edit units

repeat_count: int = 1: The number of times the playable region is to be repeated

source_duration: Optional[int] = None: The desired duration of the playable region past the entry_point, in resource edit units

property timecode_range: TimecodeRange: Timecode range relative to CPL

class imflib.cpl.ContentKind(kind: str, scope: Optional[str] = 'http://www.smpte-ra.org/schemas/2067-3/2013#content-kind')

Bases: object

The kind of content undelying the composition

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → ContentKind: Parse ContentKind from XML

kind: str: The kind of content

scope: Optional[str] = 'http://www.smpte-ra.org/schemas/2067-3/2013#content-kind': The defined set of possible kind values

class imflib.cpl.ContentMaturityRating(rating: str, agency: str, audiences: dict[str, str] = <factory>)

Bases: object

Content maturity rating and info

agency: str: The agency issuing the rating

audiences: dict[str, str]

classmethod from_xml(xml: Element, ns: Optional[dict]) → ContentMaturityRating: Parse a ContentMaturtyRatingType from a ContentMaturityRatingList

rating: str: Human-readable rating issued by the Agency

class imflib.cpl.ContentVersion(label: ~imflib.UserText, id: ~uuid.UUID = <factory>, additional_properties: list[xml.etree.ElementTree.Element] = <factory>)

Bases: object

A version of the content represented in the CPL

additional_properties: list[xml.etree.ElementTree.Element]: Additional properties of this content version

classmethod from_xml(xml: ElementTree, ns: Optional[dict] = None) → ContentVersion: Parse a ContentVersion from XML

id: UUID: UUID of the content represented by the CPL

label: UserText: Description of the version of the content

class imflib.cpl.Cpl(title: ~imflib.UserText, edit_rate: ~imflib.cpl.EditRate, id: ~uuid.UUID = <factory>, issue_date: ~datetime.datetime = <factory>, _segments: list['Segment'] = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, issuer: ~typing.Optional[~imflib.UserText] = None, creator: ~typing.Optional[~imflib.UserText] = None, content_originator: ~typing.Optional[~imflib.UserText] = None, content_kind: ~typing.Optional[~imflib.cpl.ContentKind] = None, total_runtime: ~typing.Optional[~datetime.timedelta] = None, tc_start: ~typing.Optional[~posttools.timecode.Timecode] = None, content_versions: set['ContentVersion'] = <factory>, locales: list['Locale'] = <factory>, essence_descriptors: list['EssenceDescriptor'] = <factory>, extension_properties: list['ExtensionProperty'] = <factory>, security: ~typing.Optional[~imflib.Security] = None)

Bases: object

An IMF Composition Playlist

annotation: Optional[UserText] = None: Optional description of this CPL

content_kind: Optional[ContentKind] = None: The kind of work represented by this CPL

content_originator: Optional[UserText] = None: The person or company that produced the content used in this CPL

content_versions: set['ContentVersion']: The specific version or revision of the content in this CPL

creator: Optional[UserText] = None: The facility or system that created this CPL

property duration: int: Duration in frames for now

edit_rate: EditRate: The granularity of time-related parameters used in this CPL

essence_descriptors: list['EssenceDescriptor']: Descriptors intended for scheduling and tracking content referenced by this CPL

extension_properties: list['ExtensionProperty']: Additional metadata describing this CPL

classmethod from_file(path: str) → Cpl: Parse an existing CPL from a given file path.

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → Cpl: Parse an existing CPL from a given root XMLElementTree Element Intended to be called from Cpl.from_file(), but you do you.

id: UUID: Unique identifier for this CPL encoded as a urn:UUID [RFC 4122]

issue_date: datetime: Datetime this asset map was issued

issuer: Optional[UserText] = None: The person or company that issued this CPL

locales: list['Locale']: The intended audiences for this CPL

property resources: Iterator[BaseResource]

security: Optional[Security] = None: XML signer and signature

property segments: Iterator[Segment]

property sequences: Iterator[Sequence]

tc_start: Optional[Timecode] = None: The starting timecode of this CPL

property timecode_range: TimecodeRange: Timecode range of the CPL

title: UserText: The title of the content in this CPL

total_runtime: Optional[timedelta] = None: The approximate runtime of the content in this CPL, for informational purposes only

static xsd_optional_compositiontimecode(xml: Element, ns: Optional[dict] = None, default: Optional[Timecode] = None) → Timecode: Return a Timecode object from an XSD CompositionTimecodeType

static xsd_optional_runtime(xml: Element, ns: Optional[dict] = None, default: Optional[timedelta] = None) → timedelta: Return a datetime.timedelta object based on a given runtime

class imflib.cpl.EditRate(edit_rate: tuple[int, int])

Bases: object

A rational edit rate

property decimal: float: Edit rate as a float

edit_rate: tuple[int, int]: The edit rate as a ratio of two integers

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → EditRate: Parse EditRateType from XML

class imflib.cpl.EssenceDescriptor(id: ~uuid.UUID = <factory>, descriptor_data: list[xml.etree.ElementTree.Element] = <factory>)

Bases: object

A description of an essence

descriptor_data: list[xml.etree.ElementTree.Element]: The raw XML data for this essence descriptor

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → EssenceDescriptor: Parse an essence descriptor from its XML

id: UUID: Unique identifier for this CPL encoded as a urn:UUID [RFC 4122]

class imflib.cpl.ExtensionProperty(raw_xml: str)

Bases: object

Application extension

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → ExtensionProperty: Capture an extention property from the list

raw_xml: str

class imflib.cpl.ISXDSequence(id: ~uuid.UUID = <factory>, track_id: ~uuid.UUID = <factory>, _resources: ~typing.List[~imflib.cpl.BaseResource] = <factory>, _src_segment: ~typing.Optional[~imflib.cpl.Segment] = None, _src_offset: int = 0)

Bases: Sequence

SMPTE RDD 47-2018 isochronous sequence

See: https://ieeexplore.ieee.org/document/8552735/

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → ISXDSequence: Parse ISXDSequence from XML

id: UUID: UUID of the sequence

track_id: UUID: UUID of the virtual track to which the sequence belongs

class imflib.cpl.ImageResource(intrinsic_duration: int, id: ~uuid.UUID = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, edit_rate: ~typing.Optional[~imflib.cpl.EditRate] = None, entry_point: int = 0, source_duration: ~typing.Optional[int] = None, repeat_count: int = 1, _src_sequence: ~typing.Optional[~imflib.cpl.Sequence] = None, _src_offset: int = 0, source_encoding: ~uuid.UUID = <factory>, track_file_id: ~uuid.UUID = <factory>, key_id: ~typing.Optional[~uuid.UUID] = None, hash: ~typing.Optional[str] = None, hash_algorithm: ~typing.Optional[str] = None, edit_units_label: str = 'fps')

Bases: TrackFileResource

A main image resource

edit_units_label: str = 'fps'

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → ImageResource: Parse an image resource from XML

class imflib.cpl.Locale(languages: list[str] = <factory>, regions: list[str] = <factory>, content_maturity_ratings: list[imflib.cpl.ContentMaturityRating] = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None)

Bases: object

Locale-specific information

annotation: Optional[UserText] = None: Description of this locale

content_maturity_ratings: list[imflib.cpl.ContentMaturityRating]: Content maturity ratings for this locale

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → Locale: Parse a LocaleType from a LocaleListType

languages: list[str]: RFC 5646 language tags of the audiences in this locale

regions: list[str]: RFC 5646 region subtags in this locale

class imflib.cpl.MainAudioSequence(id: ~uuid.UUID = <factory>, track_id: ~uuid.UUID = <factory>, _resources: ~typing.List[~imflib.cpl.BaseResource] = <factory>, _src_segment: ~typing.Optional[~imflib.cpl.Segment] = None, _src_offset: int = 0)

Bases: Sequence

Main audio sequence of a segment

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → MainImageSequence: Parse from XML

id: UUID: UUID of the sequence

track_id: UUID: UUID of the virtual track to which the sequence belongs

class imflib.cpl.MainImageSequence(id: ~uuid.UUID = <factory>, track_id: ~uuid.UUID = <factory>, _resources: ~typing.List[~imflib.cpl.BaseResource] = <factory>, _src_segment: ~typing.Optional[~imflib.cpl.Segment] = None, _src_offset: int = 0)

Bases: Sequence

An XSD MainImageSequenceType from IMF Core Constraints

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → MainImageSequence: Parse from XML

id: UUID: UUID of the sequence

track_id: UUID: UUID of the virtual track to which the sequence belongs

class imflib.cpl.MarkerResource(intrinsic_duration: int, id: ~uuid.UUID = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, edit_rate: ~typing.Optional[~imflib.cpl.EditRate] = None, entry_point: int = 0, source_duration: ~typing.Optional[int] = None, repeat_count: int = 1, _src_sequence: ~typing.Optional[~imflib.cpl.Sequence] = None, _src_offset: int = 0, label: ~imflib.cpl.MarkerResource.MarkerLabel = <factory>, offset: int = 0)

Bases: BaseResource

A CPL Marker

class MarkerLabel(label_text: str = '', scope: str = 'http://www.smpte-ra.org/schemas/2067-3/2013#standardmarkers')

Bases: object

The marker label

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → MarkerLabel: Parse Label from XML

label_text: str = '': The kind of marker

scope: str = 'http://www.smpte-ra.org/schemas/2067-3/2013#standardmarkers': The defined set of possible labels

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → MarkerResource: Parse a Marker resource from XML

label: MarkerLabel: The textual representation of the marker

offset: int = 0: The offset from the beginning of the timeline, in resource edit units

class imflib.cpl.MarkerSequence(id: ~uuid.UUID = <factory>, track_id: ~uuid.UUID = <factory>, _resources: ~typing.List[~imflib.cpl.BaseResource] = <factory>, _src_segment: ~typing.Optional[~imflib.cpl.Segment] = None, _src_offset: int = 0)

Bases: Sequence

Marker sequence

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → MarkerSequence: Parse a Marker sequence from XML

id: UUID: UUID of the sequence

track_id: UUID: UUID of the virtual track to which the sequence belongs

class imflib.cpl.Segment(annotation: ~typing.Optional[~imflib.UserText] = None, id: ~uuid.UUID = <factory>, _sequences: ~typing.List[~imflib.cpl.Sequence] = <factory>, _src_cpl: ~typing.Optional[~imflib.cpl.Cpl] = None, _src_offset: int = 0)

Bases: object

A CPL segment

annotation: Optional[UserText] = None: Description of this segment

property duration: int: Duration in frames for now

classmethod from_xml(xml: Element, ns: Optional[dict]) → Segment: Parse a Segment from XML

id: UUID: UUID of the segment

property resources: List[BaseResource]

property sequences: Iterator[Sequence]: A list of sequences belonging to this segment

property timecode_range: TimecodeRange: Timecode range relative to CPL

class imflib.cpl.Sequence(id: ~uuid.UUID = <factory>, track_id: ~uuid.UUID = <factory>, _resources: ~typing.List[~imflib.cpl.BaseResource] = <factory>, _src_segment: ~typing.Optional[~imflib.cpl.Segment] = None, _src_offset: int = 0)

Bases: object

A sequence within a segment

property duration: int: Duration in frames for now

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → Sequence: Parse from XML

id: UUID: UUID of the sequence

property resources: Iterator[BaseResource]

property timecode_range: TimecodeRange: Timecode range relative to CPL

track_id: UUID: UUID of the virtual track to which the sequence belongs

class imflib.cpl.TrackFileResource(intrinsic_duration: int, id: ~uuid.UUID = <factory>, annotation: ~typing.Optional[~imflib.UserText] = None, edit_rate: ~typing.Optional[~imflib.cpl.EditRate] = None, entry_point: int = 0, source_duration: ~typing.Optional[int] = None, repeat_count: int = 1, _src_sequence: ~typing.Optional[~imflib.cpl.Sequence] = None, _src_offset: int = 0, source_encoding: ~uuid.UUID = <factory>, track_file_id: ~uuid.UUID = <factory>, key_id: ~typing.Optional[~uuid.UUID] = None, hash: ~typing.Optional[str] = None, hash_algorithm: ~typing.Optional[str] = None)

Bases: BaseResource

A file-based resource

classmethod from_xml(xml: Element, ns: Optional[dict] = None) → TrackFileResource: Parse a file-based resource from XML

hash: Optional[str] = None: Base64-encoded message digest of the track file

hash_algorithm: Optional[str] = None: Name of the digest type used by the track file

key_id: Optional[UUID] = None: UUID of the key used to encrypt the track file, if encrpyted

source_encoding: UUID: UUID of a known EssenceDescriptor

track_file_id: UUID: UUID of the underlying track file