Skip to content

Meta and IFF/HEIF

Meta and HEIF Options

IsoMedia files can be used as generic meta-data containers, for examples storing XML information and sample images for a movie. The resulting file may not always contain a movie as is the case with some HEIF files or MPEG-21 files.

These information can be stored at the file root level, as is the case for HEIF/IFF and MPEG-21 file formats, or at the movie or track level for a regular movie.

-set-meta ABCD[:tk=tkID]: set meta box type, with ABCD the four char meta type (NULL or 0 to remove meta)

  • tk not set: use root (file) meta
  • tkID == 0: use moov meta
  • tkID != 0: use meta of given track

-add-item (string): add resource to meta, with parameter syntax file_path[:opt1:optN]

  • file_path this or self: item is the file itself
  • tk=tkID: meta location (file, moov, track)
  • name=str: item name, none if not set
  • type=itype: item 4cc type (not needed if mime is provided)
  • mime=mtype: item mime type, none if not set
  • encoding=enctype: item content-encoding type, none if not set
  • id=ID: item ID
  • ref=4cc,id: reference of type 4cc to an other item (can be set multiple times)
  • group=id,type: indicate the id and type of an alternate group for this item
  • replace: replace existing item by new item

-add-image (string): add the given file as HEIF image item, with parameter syntax file_path[:opt1:optN]. If filepath is omitted, source is the input MP4 file

  • name, id, ref: see -add-item
  • primary: indicate that this item should be the primary item
  • time=t[-e][/i]: use the next sync sample after time t (float, in sec, default 0). A negative time imports ALL intra frames as items

    • If e is set (float, in sec), import all sync samples between t and e
    • If i is set (float, in sec), sets time increment between samples to import
  • split_tiles: for an HEVC tiled image, each tile is stored as a separate item

  • image-size=wxh: force setting the image size and ignoring the bitstream info, used for grid, overlay and identity derived images also
  • rotation=a: set the rotation angle for this image to 90*a degrees anti-clockwise
  • mirror-axis=axis: set the mirror axis: vertical, horizontal
  • clap=Wn,Wd,Hn,Hd,HOn,HOd,VOn,VOd: see track clap
  • image-pasp=axb: force the aspect ratio of the image
  • image-pixi=(a|a,b,c): force the bit depth (1 or 3 channels)
  • hidden: indicate that this image item should be hidden
  • icc_path: path to icc data to add as color info
  • alpha: indicate that the image is an alpha image (should use ref=auxl also)
  • depth: indicate that the image is a depth image (should use ref=auxl also)
  • it=ID: indicate the item ID of the source item to import
  • itp=ID: same as it= but copy over all properties of the source item
  • tk=tkID: indicate the track ID of the source sample. If 0, uses the first video track in the file
  • samp=N: indicate the sample number of the source sample
  • ref: do not copy the data but refer to the final sample/item location, ignored if filepath is set
  • agrid[=AR]: creates an automatic grid from the image items present in the file, in their declaration order. The grid will try to have AR aspect ratio if specified (float), or the aspect ratio of the source otherwise. The grid will be the primary item and all other images will be hidden
  • av1_op_index: select the AV1 operating point to use via a1op box
  • replace: replace existing image by new image, keeping props listed in keep_props
  • keep_props=4CCs: coma-separated list of properties types to keep when replacing the image, e.g. keep_props=auxC
  • auxt=URN: mark image as auxiliary using given URN
  • auxd=FILE: use data from FILE as auxiliary extensions (cf auxC box)
  • any other options will be passed as options to the media importer, see -add

-add-derived-image (string): create an image grid, overlay or identity item, with parameter syntax :type=(grid|iovl|iden)[:opt1:optN]

  • image-grid-size=rxc: set the number of rows and columns of the grid
  • image-overlay-offsets=h,v[,h,v]*: set the horizontal and vertical offsets of the images in the overlay
  • image-overlay-color=r,g,b,a: set the canvas color of the overlay [0-65535]
  • any other options from -add-image can be used

-rem-item,-rem-image item_ID[:tk=tkID]: remove resource from meta
-set-primary item_ID[:tk=tkID]: set item as primary for meta
-set-xml xml_file_path[:tk=tkID][:binary]: set meta XML data
-rem-xml [tk=tkID]: remove meta XML data
-dump-xml file_path[:tk=tkID]: dump meta XML to file
-dump-item item_ID[:tk=tkID][:path=fileName]: dump item to file
-package (string): package input XML file into an ISO container, all media referenced except hyperlinks are added to file
-mgt (string): package input XML file into an MPEG-U widget with ISO container, all files contained in the current folder are added to the widget package