II. HEIF Writer Executable and Configuration Examples
In v3.0 there is no longer executable or json configuration. Instead writer library / API is provided for frame-by-frame file writing,
HEIF Writer Library depends on a simple configuration data structure (Configuration structure defined in isomediafile.hpp). Configuration holds all the necessary information and external media data pointers. The Example HEIF Writer Application uses a JSON configuration file (of file type .cfg) in order to populate the Configuration data structure.
The usage is simply as follows: writer "JSON Configuration File".cfg
Here are some example JSON configurations: # Single Image with Thumbnails: > { "general": { "output": { "file_path" : "autumn_1440x960.heic" }, "brands": { "major" : "mif1", "other" : ["mif1", "heic", "hevc"] }, "prim_refr" : "1", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1", "file_path" : "autumn_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "thumbs": [ { "uniq_bsid" : "2", "file_path" : "autumn_240x160.265", "code_type" : "hvc1", "disp_xdim" : "240", "disp_ydim" : "160", "sync_rate" : "1" } ] } ] }
> { "general": { "output": { "file_path" : "season_collection_1440x960.heic" }, "brands": { "major" : "mif1", "other" : ["mif1", "heic", "hevc"] }, "prim_refr" : "1", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1", "file_path" : "winter_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "thumbs": [ { "uniq_bsid" : "2", "file_path" : "winter_240x160.265", "code_type" : "hvc1", "disp_xdim" : "240", "disp_ydim" : "160", "sync_rate" : "1" } ] }, { "master": { "uniq_bsid" : "3", "file_path" : "spring_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "thumbs": [ { "uniq_bsid" : "4", "file_path" : "spring_240x160.265", "code_type" : "hvc1", "disp_xdim" : "240", "disp_ydim" : "160", "sync_rate" : "1" } ] }, { "master": { "uniq_bsid" : "4", "file_path" : "summer_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "thumbs": [ { "uniq_bsid" : "4", "file_path" : "summer_240x160.265", "code_type" : "hvc1", "disp_xdim" : "240", "disp_ydim" : "160", "sync_rate" : "1" } ] }, { "master": { "uniq_bsid" : "5", "file_path" : "autumn_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "thumbs": [ { "uniq_bsid" : "6", "file_path" : "autumn_240x160.265", "code_type" : "hvc1", "disp_xdim" : "240", "disp_ydim" : "160", "sync_rate" : "1" } ] } ] }
> { "general": { "output": { "file_path" : "skateboard_burst.heic" }, "brands": { "major" : "msf1", "other" : ["msf1", "mif1","heic", "hevc"] }, "prim_refr" : "3", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1", "file_path" : "Skateboard_640x360_ipp_ip16_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "trak", "disp_xdim" : "640", "disp_ydim" : "360", "disp_rate" : "25" }, "thumbs": [ { "uniq_bsid" : "2", "file_path" : "Skateboard_128x72_ai27.265", "code_type" : "hvc1", "disp_xdim" : "128", "disp_ydim" : "72", "sync_rate" : "1" } ] }, { "master": { "uniq_bsid" : "3", "file_path" : "Skateboard_1920x1080_fr12_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1920", "disp_ydim" : "1080", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "4", "file_path" : "Skateboard_1920x1080_fr22_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1920", "disp_ydim" : "1080", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "5", "file_path" : "Skateboard_1920x1080_fr46_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1920", "disp_ydim" : "1080", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "6", "file_path" : "Skateboard_1920x1080_fr138_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1920", "disp_ydim" : "1080", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "7", "file_path" : "Skateboard_1920x1080_fr161_qp22.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1920", "disp_ydim" : "1080", "disp_rate" : "1" } } ] }
> { "general": { "output": { "file_path" : "grid_960x640.heic" }, "brands": { "major" : "mif1", "other" : ["mif1", "heic", "hevc"] }, "prim_refr" : "5000", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1000", "file_path" : "winter_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "2000", "file_path" : "spring_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "3000", "file_path" : "summer_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "4000", "file_path" : "autumn_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" }, "derived": { "grid": [ { "uniq_bsid" : "5000", "refs_list" : ["1000", "2000", "3000", "4000"], "idxs_list" : [["1"], ["1"], ["1"], ["1"]], "output_width" : "960", "output_height" : "640", "rows" : "2", "columns" : "2" } ] } } ] }
> { "general": { "output": { "file_path" : "overlay_1000x680.heic" }, "brands": { "major" : "mif1", "other" : ["mif1", "heic", "hevc"] }, "prim_refr" : "3000", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1000", "file_path" : "winter_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "2000", "file_path" : "spring_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "3000", "file_path" : "summer_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "4000", "file_path" : "autumn_480x320.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "480", "disp_ydim" : "320", "disp_rate" : "1" }, "derived": { "iovl": [ { "uniq_bsid" : "5000", "refs_list" : ["1000", "2000", "3000", "4000"], "idxs_list" : [["1"], ["1"], ["1"], ["1"]], "canvas_fill" : ["0", "0", "0", "65535"], //RGBA "output_width" : "1000", "output_height" : "680", "offsets" : [["260", "0"], ["520", "180"], ["260", "360"], ["0", "180"]] } ] } } ] }
> { "general": { "output": { "file_path" : "alpha_1440x960.heic" }, "brands": { "major" : "mif1", "other" : ["mif1", "heic", "hevc"] }, "prim_refr" : "3000", "prim_indx" : "1" }, "content": [ { "master": { "uniq_bsid" : "1000", "file_path" : "summer_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" } }, { "master": { "uniq_bsid" : "2000", "file_path" : "winter_1440x960.265", "hdlr_type" : "pict", "code_type" : "hvc1", "encp_type" : "meta", "disp_xdim" : "1440", "disp_ydim" : "960", "disp_rate" : "1" }, "auxiliary": [ { "file_path" : "alpha_mask_1440_960_modif2.265", "disp_xdim" : "1440", "disp_ydim" : "960", "urn" : "urn:mpeg:hevc:2015:auxid:1", "refs_list" : ["2000"], "idxs_list" : [["1"]] } ], "derived": { "iovl": [ { "uniq_bsid" : "3000", "refs_list" : ["1000", "2000"], "idxs_list" : [["1"], ["1"]], "canvas_fill" : ["0", "0", "0", "65535"], // RGBA - should have no effect in this example "output_width" : "1440", "output_height" : "960", "offsets" : [["0", "0"], ["0", "0"]] } ] } } ] }
> { "general": { "output": { "file_path": "multilayer001.heic" }, "brands": { "major": "heis", "other": ["mif1", "heic", "heis"] } }, "content": [ { "master": { "uniq_bsid": "1", "file_path": "B020.265", "hdlr_type": "pict", "code_type": "hvc1", "encp_type": "meta" }, "layers": [ { "uniq_bsid" : "2", "base_refr" : "1", "hdlr_type" : "pict", "code_type" : "lhv1", "tols_value" : 1 } ] } ], "egroups": [ { "altr": [ { "idxs_list": [["2", "1"], ["1", "1"]] } ] } ] }
Two 2x2 grid of SHVC coded images. The first grid contains images of the base layer, and the second grid contains images with enhanced SNR:
> { "general": { "output": { "file_path": "multilayer002.heic" }, "brands": { "major": "heis", "other": ["mif1", "heic", "heis"] } }, "content": [ { "master": { "uniq_bsid": "1", "file_path": "B021.265", "hdlr_type": "pict", "code_type": "hvc1", "encp_type": "meta" }, "layers": [ { "uniq_bsid" : "2", "base_refr" : "1", "hdlr_type" : "pict", "code_type" : "lhv1", "tols_value" : 1 } ], "derived": { "grid": [ { "uniq_bsid" : "3", "refs_list" : ["1"], "idxs_list" : [["1", "2", "3", "4"]], "output_width" : "1024", "output_height" : "512", "rows" : "2", "columns" : "2" }, { "uniq_bsid" : "4", "refs_list" : ["2"], "idxs_list" : [["1", "2", "3", "4"]], "output_width" : "1024", "output_height" : "512", "rows" : "2", "columns" : "2" } ] } } ] }
> { "general": { "output": { "file_path": "multilayer003.heic" }, "brands": { "major": "heic", "other": ["mif1", "heic"] } }, "content": [ { "master": { "uniq_bsid": "1", "file_path": "B022.265", "hdlr_type": "pict", "code_type": "hvc1", "encp_type": "meta" } } ], "egroups": [ { "ster": [ { "idxs_list": [["1", "1"], ["1", "2"]] } ] } ] }
> { "general": { "output": { "file_path": "multilayer004.heic" }, "brands": { "major": "heis", "other": ["mif1", "heic", "heis", "avci"] } }, "content": [ { "master": { "uniq_bsid": "1", "file_path": "B024.264", "hdlr_type": "pict", "code_type": "avc1", "encp_type": "meta" }, "layers": [ { "file_path" : "B023.265", "uniq_bsid" : "2", "base_refr" : "1", "hdlr_type" : "pict", "code_type" : "lhv1", "tols_value" : 1 } ] } ], "egroups": [ { "altr": [ { "idxs_list": [["2", "1"], ["1", "1"]] } ] } ] }
Note that the generation of the HEVC encoded bitstream is out of the scope of HEIF Implementation and this repository. JSON Configuration also supports advanced features such as alternate groupings, auxiliary images and edit lists. Full list of JSON configuration options are as follows: # HEIF JSON Configuration Format: > # HEIF JSON Configuration Format # This file lists the fields that are used by the writer. # Every keys and values are input as strings. # Note that this is an un-usable configuration file. # All four-character codes (4CCs) are inherited from the HEIF and ISOBMFF standard.
{
"general": # This section contains all generic infomation about the file to be created
{
"output": # This section contains all infomation related to the output file to be created by the writer.
{
"file_path" : "outputfile.heic" # The full path of the output file. A proper file extension must be given.
},
"brands": # This section contains all information related to the brand conformance of the generated output file.
{
"major" : "msf1", # 4CC value of the major brand.
"other" : ["msf1", "heic", "hevc"] # an array of 4CC values that list the compatible brands.
}
"prim_refr" : "1000", # Reference ID for the primary item source (coming from the relevant uniq_bsid field)
"prim_indx" : "2" # 1-based index ID of the frame/image referenced by prim_refr bitstream. This item represents the primary item.
},
"content": # This section contains all information of the contents to be written in this file. The values used are for example purposes only...
[
{ # Each member of this array shall contain at least one "master" image or image sequence encoded bitstream. There can be multiple "master" entries in one content member.
"master": # This section contains all information related to the master bitstream for this content. In a multi-layered context, the master section defines the base-layer of the multi-layered stream.
{
"uniq_bsid" : "1000", # A configuration-file-unique integer identifier for the bitstream of this content.
"file_path" : "test_master1.265", # Full path of the master encoded bitstream.
"edit_file" : "test_master1.edt", # Full path of the edit list json file, if edit list applies. Only used if "enc_type" is "trak".
"hdlr_type" : "pict", # Handler type of the track or root level metabox as defined in te HEIF standard.
"code_type" : "hvc1", # The 4CC value of the codec used to encode the input bitstream. "hvc1" is for HEVC bitstreams
"encp_type" : "trak", # The encapsulation type used in the output file for this master content. Valid values are {trak, meta}. trak refers to media track, meta refers to root metabox.
"disp_xdim" : "1920", # The display width of the samples/items; always an integer.
"disp_ydim" : "1080", # The display height of the samples/items; always an integer.
"tick_rate" : "90000", # The ticks per second used to compute timing information. Only used if "enc_type" is "trak".
"disp_rate" : "60" # The display frame rate of the coded video.
},
"thumbs": # This section contains all information related to the thumbnail bitstreams for this content. It is an array.
[
{
"uniq_bsid" : "2000", # A configuration-file-unique integer identifier for the bitstream of this content.
"file_path" : "test_master1.265", # Full path of the thumbnail encoded bitstream.
"edit_file" : "test_master1.edt", # Full path of the edit list json file, if edit list applies. This should be the same as in the master. Only used if "enc_type" is "trak".
"hdlr_type" : "pict", # Handler type of the track or root level metabox as defined in te HEIF standard.
"code_type" : "hvc1", # The 4CC value of the codec used to encode the input bitstream. "hvc1" is for HEVC bitstreams
"disp_xdim" : "320", # The display width of the samples/items; always an integer.
"disp_ydim" : "240", # The display height of the samples/items; always an integer.
"tick_rate" : "90000", # The ticks per second used to compute timing information. Only used if "enc_type" is "trak".
"sync_rate" : "1", # The syncronization rate of the thumbnail samples with respect to the master. A value of "N" means "skip N-1 frames and take the next sample.". Only used if "enc_type" is "meta".
"sync_idxs" : ["1", "10"] # Indicates 1-based indexes of the samples/frames to be taken from the bitstream and written as thumbnail items. Only used if "enc_type" is "meta".
},
{
# Another thumbnail element can be listed here.
}
]
"layers": # This section contains all information related to layers in a scalable bitstream. It is an array.
[
{
"uniq_bsid" : "2", # A configuration-file-unique integer identifier for the layer of a bitstream of this content.
"base_refr" : "1", # A value used internally, and this value must be set equal to the uniq_bsid value of the base layer in the master section.
"hdlr_type" : "pict", # Handler type of the track or root level metabox as defined in te HEIF standard.
"code_type" : "lhv1", # The 4CC value of the codec used to encode the input bitstream. "lhv1" is for a layered HEVC (SHVC, MV-HEVC) bitstreams.
"tols_value" : 1, # The output layer set index value of the layer.
}
],
"property": # Item properties can be listed here. These values only apply if the master's "encp_type" is "meta".
{ # Currently only 'irot' and 'rloc' are defined. The other descriptive properties may be added here.
"irot":
[ # Image rotation property as defined in the HEIF standard.
{
"essential" : "true", # essential property indicator as defined in the HEIF standard. If not present, essential value is "true" by default.
"refs_list" : ["1000"], # The list of references. Their values come from the uniq_bsid fields.
"idxs_list" : [["1", "2","5"]], # 1-based indexes of the items in the referenced bitstreams. This is an array where each array element is also an array. The array elements map one-to-one to the references listed in the refs_list field.
"angle" : "90" # Rotation angle as defied in the HEIF standard. Can be 0, 90, 180 and 270.
},
{ # another 'irot' property can be listed here....
"essential" : "false",
"refs_list" : ["1000"],
"idxs_list" : [["3"]],
"angle" : "180"
}
],
"rloc":
[ # Relative location property as defined in the HEIF standard.
{
"essential" : "true",
"refs_list" : ["1000"],
"idxs_list" : [["3", "4"]],
"horizontal_offset" : "100", # horizontal offset value as integer
"vertical_offset" : "200" # vertical offset value as integer
},
{ # another 'rloc' property can be listed here....
"refs_list" : ["1000"],
"idxs_list" : [["6", "7","8"]],
"horizontal_offset" : "250",
"vertical_offset" : "350"
}
],
"imir":
[ # Image mirroring property as defined in the HEIF standard.
{
"refs_list" : ["1000"],
"idxs_list" : [["1"]],
"horiz_axis" : "false", # "false" specifies a vertical axis for mirroring, "true" specifies a horizontal axis.
"essential" : "false"
}
]
}
"derived": #Derived image definitions can be listed here. References can be given to master and thumbnail bitstreams as well as other derived images
{
"clap":
[ # Clean aperture derived image as defined in the HEIF & ISOBMFF standard.
{
"uniq_bsid": "5000", # A configuration-file-unique integer identifier for this item.
"refs_list" : ["1000"], # The list of references. Their values come from the uniq_bsid fields.
"idxs_list" : [["1", "2","3"]], # 1-based indexes of the items in the referenced bitstreams. This is an array where each array element is also an array. The array elements map one-to-one to the references listed in the refs_list field.
"clapWidthN" : "1", # cleanApertureWidthN as defined in ISOBMFF standard.
"clapWidthD" : "2", # cleanApertureWidthD as defined in ISOBMFF standard.
"clapHeightN" : "3", # cleanApertureHeight as defined in ISOBMFF standard.
"clapHeightD" : "4", # cleanApertureHeightD as defined in ISOBMFF standard.
"horizOffN" : "60", # horizOffN as defined in ISOBMFF standard.
"horizOffD" : "70", # horizOffD as defined in ISOBMFF standard.
"vertOffN" : "80", # vertOffN as defined in ISOBMFF standard.
"vertOffD" : "90" # vertOffD as defined in ISOBMFF standard.
},
{
# another clean aperture item
}
],
"irot":
[ # Image rotation property as defined in the HEIF standard.
{
"uniq_bsid": "5001",
"refs_list" : ["1000"],
"idxs_list" : [["1", "2","5"]],
"angle" : "180"
},
{
# another image rotation item
}
],
"imir":
[ # Image mirroring property as defined in the HEIF standard.
{
"uniq_bsid" : ["5003"],
"refs_list" : ["1000"],
"idxs_list" : [["1"]],
"horiz_axis" : "false" # "false" specifies a vertical axis for mirroring, "true" specifies a horizontal axis.
}
],
"iovl":
[ # Image Overlay derived image item as defined in the HEIF standard.
{
"uniq_bsid": "5002",
"refs_list": ["1000", "2000"], # Two bitstream inputs are defined
"idxs_list": [["1"], ["1", "2", "5"]], # from 1000, 1st image and from 2000 1st, 2nd and 5th images are to be taken
"canvas_fill": ["128", "128", "128", "0"], # canvas fill value as defined in HEIF standard
"output_width": "480", # output width value as defined in HEIF standard
"output_height": "360", # output height value as defined in HEIF standard
"offsets": [["0", "0"],["160", "0"],["0", "200"],["240", "240"]] # the X,Y offset values of each item as defined in the HEIF standard
},
{
# another image overlay item
}
],
"grid":
[ # Grid derived image item as defined in the HEIF standard.
{
"uniq_bsid": "7000",
"refs_list": ["1000", "5002"], # One bitstream input and a derived image input are defined
"idxs_list": [["1", "2", "5"],["1"]], # 4 item references are defined, 3 from 1000 and 5002 itself (1-based index refers to the item itself)
"output_width": "640", # output width value as defined in HEIF standard
"output_height": "480", # output height value as defined in HEIF standard
"rows": "2", # number of rows as defined in the HEIF standard
"columns": "2" # number of columns as defined in the HEIF standard
},
{
# another grid item
}
],
"pre-derived":
[ # Pre-derived coded images as defined in the HEIF standard.
{
"uniq_bsid": "8000",
"pre_refs_list" : ["2000"], # Here, a pre-derived coded image is defined for the first image of the bitstream of id 2000
"pre_idxs_list" : [["1"]],
"base_refs_list" : ["1000","5002"], # It is assumed that these two bitstreams contain the pre-drived coded images.
"base_idxs_list" : [["1", "2", "5"],["1"]] # The indexes of the images that are used to derive this pre-derived coded image.
},
{
# another pre-derived coded image item
}
]
}
},
{
# Another content can be listed here... It has to contain a master bitstream and may contain thumbnails and more derived images and properties.
}
],
"egroups": # This section provides all entity and track grouping information in this file. It is an array.
[
{
"altr": # This section provide all information of the group of type "altr". More groups can be defined in the future.
[ # The list below is a pair of numbers, the first in the pair identifies content with a matching uniq_bsid, and the second identifies sample/item.
{
idxs_list: [["1000", "0"], ["2000", "1"]] # 0 as an index means that the whole track is being grouped.
},
{
idxs_list: [["1000", "0"], ["2000", "0"]] # In this example, if both 1000 and 2000 are tracks, then they are made alternate tracks of each other.
}
]
}
]
}
Edit Lists are provided externally to the configuration. The format of an edit list is very similar to the Edit list definition in ISOBMFF. # Edit List Configuration Format: > # Edit List configuration Format # Edit List information is provided as an external file to the HEIF configuration. # There can be 3 types of edit units: empty, shift and dwell as defined in the ISOBMFF standard. { "numb_rept": "2", # defines the number of times this edit list should be applied. "N" meand, this list is applied N times. "-1" means it is applied indefinitely (infinite loop) "edit_unit": [ { "edit_type": "empty", # type of the edit. Can be empty, shift or dwell "mdia_time": "-1", # media time this edit applies to . -1 means to the beginning of the media timeline and in milliseconds. "time_span": "5000" # the amount in presentation time that this edit applies to, in milliseconds. }, { "edit_type": "shift", "mdia_time": "0", "time_span": "300" }, { "edit_type": "dwell", "mdia_time": "300", "time_span": "5000" }, { "edit_type": "shift", "mdia_time": "300", "time_span": "30000" } ] }