cs-iso14496 20200229

Facilities for ISO14496 files - the ISO Base Media File Format, the basis for several things including MP4 and MOV.

Latest release 20200229: ILST: recognise @cpy as copyright, sfID as itunes_store_country_code. ILST: new SFID_ISO_3166_1_ALPHA_3_CODE and STIK_MEDIA_TYPES providing context data for various field values, as yet unused. Make various list fields of some boxes deferred because they are expensive to parse (uses new cs.binary deferred_field). add_generic_sample_boxbody: drop iter, causes dumb iterators to parse the samples. ILST: iTunes "Date" metadata seem to contain plain years or ISO8601 datestamps. mp4 autotag: add -n (no action) and -p,--prefix (set tag prefix, default 'mp4') options. mp4 autotag: use "mp4." as the tag prefix.

Facilities for ISO14496 files - the ISO Base Media File Format, the basis for several things including MP4 and MOV.

ISO make the standard available here:

• link
• link

Function add_body_class(klass)

Register a box body class in KNOWN_BOXBODY_CLASSES.

Function add_body_subclass(superclass, box_type, section, desc)

Create and register a new BoxBody class that is simply a subclass of another. Returns the new class.

Function add_generic_sample_boxbody(box_type, section, desc, struct_format_v0, sample_fields, struct_format_v1=None, has_inferred_entry_count=False)

Create and add a specific Time to Sample box - section 8.6.1.

Function add_time_to_sample_boxbody(box_type, section, desc)

Add a Time to Sample box - section 8.6.1.

Class Box(cs.binary.Packet,cs.binary.PacketField)

Base class for all boxes - ISO14496 section 4.2.

This has the following PacketFields:

• header: a BoxHeader
• body: a BoxBody instance, usually a specific subclass
• unparsed: if there are unconsumed bytes from the Box they are stored as here as a BytesesField; note that this field is not present if there were no unparsed bytes

Class BoxBody(cs.binary.Packet,cs.binary.PacketField)

Abstract basis for all Box bodies.

Class BoxHeader(cs.binary.Packet,cs.binary.PacketField)

An ISO14496 Box header packet.

Class BTRTBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

BitRateBoxBody - section 8.5.2.2.

Class CO64BoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'c064' Chunk Offset box - section 8.7.5.

Class ContainerBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

A base class for pure container boxes.

Class CPRTBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'cprt' Copyright box - section 8.10.2.

Class CSLGBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'cslg' Composition to Decode box - section 8.6.1.4.

Function deref_box(B, path)

Dereference a path with respect to this Box.

Class DREFBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'dref' Data Reference box containing Data Entry boxes - section 8.7.2.1.

Function dump_box(B, indent='', fp=None, crop_length=170, indent_incr=None)

Recursively dump a Box.

Class ELNGBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A ELNGBoxBody is a Extended Language Tag box - ISO14496 section 8.4.6.

Class FREEBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'free' or 'skip' box - ISO14496 section 8.1.2. Note the length and discard the data portion.

Class FTYPBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'ftyp' File Type box - ISO14496 section 4.3. Decode the major_brand, minor_version and compatible_brands.

Class FullBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

A common extension of a basic BoxBody, with a version and flags field. ISO14496 section 4.2.

Class HDLRBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A HDLRBoxBody is a Handler Reference box - ISO14496 section 8.4.3.

Class ILSTBoxBody(ContainerBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

iTunes Information List, container for iTunes metadata fields.

The basis of the format knowledge here comes from AtomicParsley's documentation here:

http://atomicparsley.sourceforge.net/mpeg-4files.html

and additional information from:

https://github.com/sergiomb2/libmp4v2/wiki/iTunesMetadata

Function main(argv=None)

Command line mode.

Class MDATBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

A Media Data Box - ISO14496 section 8.1.1.

Class MDHDBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A MDHDBoxBody is a Media Header box - ISO14496 section 8.4.2.

Class METABoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'meta' Meta BoxBody - section 8.11.1.

Class MOOVBoxBody(ContainerBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'moov' Movie box - ISO14496 section 8.2.1. Decode the contained boxes.

Class MVHDBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'mvhd' Movie Header box - ISO14496 section 8.2.2.

Class OverBox(cs.binary.Packet,cs.binary.PacketField)

A fictitious Box encompassing all the Boxes in an input buffer.

Function parse(o, **kw)

Return the OverBoxes from source (str, int, file).

The leading o parameter may be one of:

• str: a filesystem file pathname
• int: a OS file descriptor
• file: if not int or str the presumption is that this is a file-like object

Keyword arguments are as for OverBox.from_buffer.

Function parse_buffer(bfr, copy_offsets=None, **kw)

Parse an ISO14496 stream from the CornuCopyBuffer bfr, yield top level OverBoxes.

Parameters:

• bfr: a CornuCopyBuffer provided the stream data, preferably seekable
• discard_data: whether to discard unparsed data, default False
• copy_offsets: callable to receive Box offsets

Function parse_chunks(chunks, **kw)

Parse an ISO14496 stream from the iterator of data chunks, yield top level Boxes.

Parameters:

• chunks: an iterator yielding bytes objects
• discard_data: whether to discard unparsed data, default False
• copy_offsets: callable to receive BoxBody offsets

Function parse_deref_path(path, offset=0)

Parse a path string from offset. Return the path components and the offset where the parse stopped.

Path components:

• identifier: an identifier represents a Box field or if such a field is not present, a the first subbox of this type
• [index]: the subbox with index index

Examples:

>>> parse_deref_path('.abcd[5]')
['abcd', 5]

Function parse_fd(fd, discard_data=False, **kw)

Parse an ISO14496 stream from the file descriptor fd, yield top level Boxes.

Parameters:

• fd: a file descriptor open for read
• discard_data: whether to discard unparsed data, default False
• copy_offsets: callable to receive BoxBody offsets

Function parse_file(fp, **kw)

Parse an ISO14496 stream from the file fp, yield top level Boxes.

Parameters:

• fp: a file open for read
• discard_data: whether to discard unparsed data, default False
• copy_offsets: callable to receive BoxBody offsets

Class PDINBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'pdin' Progressive Download Information box - ISO14496 section 8.1.3.

Function pick_boxbody_class(box_type, default_type=None)

Infer a Python BoxBody subclass from the bytes box_type.

• box_type: the 4 byte box type
• default_type: the default BoxBody subclass if there is no specific mapping, default None; if None, use BoxBody.

Function report(box, indent='', fp=None, indent_incr=None)

Report some human friendly information about a box.

Class SMHDBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'smhd' Sound Media Headerbox - section 12.2.2.

Class STCOBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'stco' Chunk Offset box - section 8.7.5.

Class STSCBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

'stsc' (Sample Table box - section 8.7.4.1.

Class STSZBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'stsz' Sample Size box - section 8.7.3.2.

Class STZ2BoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'stz2' Compact Sample Size box - section 8.7.3.3.

Class SubBoxesField(cs.binary.ListField,cs.binary.PacketField)

A field which is itself a list of Boxes.

Class TimeStamp32(cs.binary.UInt32BE,cs.binary.PacketField,TimeStampMixin)

The 32 bit form of an ISO14496 timestamp.

Class TimeStamp64(cs.binary.UInt64BE,cs.binary.PacketField,TimeStampMixin)

The 64 bit form of an ISO14496 timestamp.

Class TimeStampMixin

Methods to assist with ISO14496 timestamps.

Class TKHDBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'tkhd' Track Header box - ISO14496 section 8.2.2.

Class TrackGroupTypeBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A TrackGroupTypeBoxBody contains a track group id - ISO14496 section 8.3.3.2.

Class TrackReferenceTypeBoxBody(BoxBody,cs.binary.Packet,cs.binary.PacketField)

A TrackReferenceTypeBoxBody contains references to other tracks - ISO14496 section 8.3.3.2.

Class TREFBoxBody(ContainerBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

Track Reference BoxBody, container for trackReferenceTypeBoxes - ISO14496 section 8.3.3.

Class TTSB_Sample(builtins.tuple)

TTSB_Sample(count, delta)

Class URL_BoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'url ' Data Entry URL BoxBody - section 8.7.2.1.

Class URN_BoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

An 'urn ' Data Entry URL BoxBody - section 8.7.2.1.

Class UTF8or16Field(cs.binary.PacketField)

An ISO14496 UTF8 or UTF16 encoded string.

Class VMHDBoxBody(FullBoxBody,BoxBody,cs.binary.Packet,cs.binary.PacketField)

A 'vmhd' Video Media Headerbox - section 12.1.2.

Release Log

Release 20200229: ILST: recognise @cpy as copyright, sfID as itunes_store_country_code. ILST: new SFID_ISO_3166_1_ALPHA_3_CODE and STIK_MEDIA_TYPES providing context data for various field values, as yet unused. Make various list fields of some boxes deferred because they are expensive to parse (uses new cs.binary deferred_field). add_generic_sample_boxbody: drop iter, causes dumb iterators to parse the samples. ILST: iTunes "Date" metadata seem to contain plain years or ISO8601 datestamps. mp4 autotag: add -n (no action) and -p,--prefix (set tag prefix, default 'mp4') options. mp4 autotag: use "mp4." as the tag prefix.

Release 20200130: Parsing of ILST boxes (iTunes metadata). Command line: new "info" subcommand reporting metadata, "autotag" applying metadata to fstags. Box tree walk, ancestor, iteration. Assorted cleanups and internal changes.

Release 20190220: parse_buffer yields instead of returns; some small bugfixes.

Release 20180810: parse_fd(): use a mmap to access the descriptor if a regular file and not discard_data; this lets us use the mmapped file as backing store for the data, a big win for the media sections.

Release 20180805: Initial PyPI release.