Package: cs.iso14496
Facilities for ISO14496 files - the ISO Base Media File Format,
the basis for several things including MP4 and MOV.Latest release 20231129:
Small updates and fixes.ISO make the standard available here:linklinkFunctionadd_body_class(klass)Register a box body class in KNOWN_BOXBODY_CLASSES.Functionadd_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.Functionadd_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.Functionadd_time_to_sample_boxbody(box_type, section, desc)Add a Time to Sample box - section 8.6.1.ClassBox(cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)Base class for all boxes - ISO14496 section 4.2.This has the following fields:header: aBoxHeaderbody: aBoxBodyinstance, usually a specific subclassunparsed: any unconsumed bytes from theBoxare stored as hereClassBoxBody(cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)Abstract basis for allBoxbodies.ClassBoxHeader(cs.binary.BoxHeader, cs.binary._BinaryMultiValue_Base, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An ISO14496 Box header packet.ClassBTRTBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)BitRateBoxBody - section 8.5.2.2.ClassCO64BoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'c064' Chunk Offset box - section 8.7.5.ClassContainerBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)Common subclass of several things with.boxes.ClassCPRTBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'cprt' Copyright box - section 8.10.2.ClassCSLGBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'cslg' Composition to Decode box - section 8.6.1.4.Functiondecode_itunes_date_field(data)The iTunes 'Date' meta field: a year or an ISO timestamp.Functionderef_box(B, path)Dereference a path with respect to this Box.ClassDREFBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'dref' Data Reference box containing Data Entry boxes - section 8.7.2.1.Functiondump_box(B, indent='', fp=None, crop_length=170, indent_incr=None)Recursively dump a Box.ClassELNGBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A ELNGBoxBody is a Extended Language Tag box - ISO14496 section 8.4.6.ClassELSTBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'elst' Edit List FullBoxBody - section 8.6.6.ClassFallbackBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)ABoxBodysubclass which parses nothing for unimplementedBoxtypes,
used bypick_boxbody_class().ClassFREEBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'free' or 'skip' box - ISO14496 section 8.1.2.
Note the length and discard the data portion.ClassFTYPBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'ftyp' File Type box - ISO14496 section 4.3.
Decode the major_brand, minor_version and compatible_brands.ClassFullBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A common extension of a basic BoxBody, with a version and flags field.
ISO14496 section 4.2.ClassHDLRBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A HDLRBoxBody is a Handler Reference box - ISO14496 section 8.4.3.FunctionILSTAofBSchema(attribute_name)Attribute name and type for ILST "A of B" schema.ClassILSTBoxBody(ContainerBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)Apple 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.htmland additional information from:https://github.com/sergiomb2/libmp4v2/wiki/iTunesMetadataFunctionILSTISOFormatSchema(attribute_name)Attribute name and type for ILST ISO format schema.FunctionILSTRawSchema(attribute_name)Attribute name and type for ILST raw schema.FunctionILSTTextSchema(attribute_name)Attribute name and type for ILST text schema.FunctionILSTUInt32BESchema(attribute_name)Attribute name and type for ILST UInt32BE schema.FunctionILSTUInt8Schema(attribute_name)Attribute name and type for ILST UInt8BE schema.Classitunes_media_type(builtins.tuple)itunes_media_type(type, stik)Methoditunes_media_type.__new__(_cls, type, stik):
Create new instance of itunes_media_type(type, stik)Classitunes_store_country_code(builtins.tuple)itunes_store_country_code(country_name, iso_3166_1_code, itunes_store_code)Methoditunes_store_country_code.__new__(_cls, country_name, iso_3166_1_code, itunes_store_code):
Create new instance of itunes_store_country_code(country_name, iso_3166_1_code, itunes_store_code)Functionmain(argv=None)Command line mode.ClassMDATBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A Media Data Box - ISO14496 section 8.1.1.ClassMDHDBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A MDHDBoxBody is a Media Header box - ISO14496 section 8.4.2.ClassMETABoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'meta' Meta BoxBody - section 8.11.1.ClassMOOVBoxBody(ContainerBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'moov' Movie box - ISO14496 section 8.2.1.
Decode the contained boxes.ClassMP4Command(cs.cmdutils.BaseCommand)Command line usage:Usage: mp4 subcommand [...]
Subcommands:
autotag autotag [-n] [-p prefix] [--prefix=prefix] paths...
Tag paths based on embedded MP4 metadata.
-n  No action.
-p prefix, --prefix=prefix
Set the prefix of added tags, default: 'mp4'
deref ...
Dereference a Box specification against ISO14496 files.
extract extract [-H] filename boxref output
Extract the referenced Box from the specified filename into output.
-H  Skip the Box header.
help [-l] [subcommand-names...]
Print the full help for the named subcommands,
or for all subcommands if no names are specified.
-l  Long help even if no subcommand-names provided.
info info [{-|filename}]...]
Print informative report about each source.
parse [parse [{-|filename}]...]
Parse the named files (or stdin for "-").
shell
Run a command prompt via cmd.Cmd using this command's subcommands.
tags path
Report the tags ofpathbased on embedded MP4 metadata.
test [testnames...]
Run self tests.ClassMVHDBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'mvhd' Movie Header box - ISO14496 section 8.2.2.ClassOverBox(cs.binary.BinaryListValues, cs.binary.AbstractBinary, cs.binary.BinaryMixin, HasBoxesMixin)A fictitiousBoxencompassing all the Boxes in an input buffer.Functionparse(o)Return theOverBoxfrom a source (str, int, bytes, file).The leadingoparameter may be one of:str: a filesystem file pathnameint: a OS file descriptorbytes: abytesobjectfile: if notintorstrthe presumption
is that this is a file-like objectKeyword arguments are as forOverBox.from_buffer.Functionparse_deref_path(path, offset=0)Parse apathstring fromoffset.
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 indexindexExamples:>>> parse_deref_path('.abcd[5]')
['abcd', 5]Functionparse_fields(bfr, copy_offsets=None, **kw)Parse an ISO14496 stream from the CornuCopyBufferbfr,
yield top level OverBoxes.Parameters:bfr: aCornuCopyBufferprovided the stream data,
preferably seekablediscard_data: whether to discard unparsed data, defaultFalsecopy_offsets: callable to receive Box offsetsFunctionparse_tags(path, tag_prefix=None)Parse the tags frompath.
Yield(box,tags)for each subbox with tags.The optionaltag_prefixparameter
may be specified to prefix each tag name with a prefix.
Other keyword arguments are passed toparse()(typical example:discard_data=True).ClassPDINBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'pdin' Progressive Download Information box - ISO14496 section 8.1.3.Functionpick_boxbody_class(box_type: bytes)Infer aBoxBodysubclass from the 4-byte bytesbox_type.
ReturnsFallbackBoxBodyfor unimplemented types.Functionreport(box, indent='', fp=None, indent_incr=None)Report some human friendly information about a box.ClassSMHDBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'smhd' Sound Media Headerbox - section 12.2.2.ClassSTCOBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'stco' Chunk Offset box - section 8.7.5.ClassSTSCBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)'stsc' (Sample Table box - section 8.7.4.1.ClassSTSZBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'stsz' Sample Size box - section 8.7.3.2.ClassSTZ2BoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'stz2' Compact Sample Size box - section 8.7.3.3.ClassTimeStamp32(cs.binary.UInt32BE, cs.binary.UInt32BE, builtins.tuple, cs.binary.AbstractBinary, cs.binary.BinaryMixin, TimeStampMixin)The 32 bit form of an ISO14496 timestamp.ClassTimeStamp64(cs.binary.UInt64BE, cs.binary.UInt64BE, builtins.tuple, cs.binary.AbstractBinary, cs.binary.BinaryMixin, TimeStampMixin)The 64 bit form of an ISO14496 timestamp.ClassTimeStampMixinMethods to assist with ISO14496 timestamps.ClassTKHDBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'tkhd' Track Header box - ISO14496 section 8.2.2.ClassTrackGroupTypeBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A TrackGroupTypeBoxBody contains a track group id - ISO14496 section 8.3.3.2.ClassTrackReferenceTypeBoxBody(BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A TrackReferenceTypeBoxBody contains references to other tracks - ISO14496 section 8.3.3.2.ClassTREFBoxBody(ContainerBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)Track Reference BoxBody, container for trackReferenceTypeBoxes - ISO14496 section 8.3.3.ClassTTSB_Sample(builtins.tuple)TTSB_Sample(count, delta)MethodTTSB_Sample.__new__(_cls, count, delta):
Create new instance of TTSB_Sample(count, delta)ClassURL_BoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'url ' Data Entry URL BoxBody - section 8.7.2.1.ClassURN_BoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An 'urn ' Data Entry URL BoxBody - section 8.7.2.1.ClassUTF8or16Field(cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)An ISO14496 UTF8 or UTF16 encoded string.ClassVMHDBoxBody(FullBoxBody, BoxBody, cs.binary.SimpleBinary, types.SimpleNamespace, cs.binary.AbstractBinary, cs.binary.BinaryMixin)A 'vmhd' Video Media Headerbox - section 12.1.2.Release LogRelease 20231129:
Small updates and fixes.Release 20230212:Drop cs.context.StackableState in favour of cs.threads.State.MP4Command.cmd_autotag: use @uses_fstags for the fstags parameter.Release 20220606:
Update obsolete use of Tag.with_prefix.Release 20210306:Huge refactor of the Box classes to the new Binary* classes from cs.binary.mp4: new "tags" subcommand to print the tags parsed from a file.BoxHeader: fix the definition of MAX_BOX_SIZE_32.BoxBody: new parse_boxes utility method to part the remainder of a Box as subBoxes.MP4.cmd_parse: run the main parse in discard_data=True mode.METABoxBody.getattr: fix ILST typo.MP4Command: update for new cs.cmdutils.BaseCommand API.Many small fixes and tweaks.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: dropiter, 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.