heif_sequences.h File Reference

#include "libheif/heif.h"

Include dependency graph for heif_sequences.h:

Go to the source code of this file.

Data Structures
struct	heif_sequence_encoding_options
struct	heif_sample_aux_info_type
	Contains the type of sample auxiliary data assigned to the track samples. More...

Macros
#define	heif_sequence_track_number_of_repetitions_infinite   0xFFFFFFFFu
	Special return value of heif_track_get_number_of_repetitions() indicating that the editlist requests indefinite repetition (the mvhd duration is the ISOBMFF "duration unknown" sentinel and the editlist is in repeat mode).
#define	heif_sequence_maximum_number_of_repetitions   0

Typedefs
typedef struct heif_tai_clock_info	heif_tai_clock_info
typedef struct heif_tai_timestamp_packet	heif_tai_timestamp_packet
typedef struct heif_track	heif_track
typedef uint32_t	heif_track_type
typedef enum heif_track_type_4cc	heif_track_type_4cc
typedef enum heif_auxiliary_track_info_type	heif_auxiliary_track_info_type
typedef struct heif_raw_sequence_sample	heif_raw_sequence_sample
	Sequence sample object that can hold any raw byte data.
typedef enum heif_sample_aux_info_presence	heif_sample_aux_info_presence
	Specifies whether a 'sample auxiliary info' is stored with the samples.
typedef struct heif_track_options	heif_track_options
typedef enum heif_sequence_gop_structure	heif_sequence_gop_structure
typedef enum heif_sequence_content_kind	heif_sequence_content_kind
typedef struct heif_sequence_encoding_options	heif_sequence_encoding_options
typedef struct heif_sample_aux_info_type	heif_sample_aux_info_type
	Contains the type of sample auxiliary data assigned to the track samples.
typedef enum heif_track_reference_type	heif_track_reference_type

Enumerations
enum	heif_track_type_4cc { heif_track_type_video = heif_fourcc('v', 'i', 'd', 'e') , heif_track_type_image_sequence = heif_fourcc('p', 'i', 'c', 't') , heif_track_type_auxiliary = heif_fourcc('a', 'u', 'x', 'v') , heif_track_type_metadata = heif_fourcc('m', 'e', 't', 'a') }
enum	heif_auxiliary_track_info_type { heif_auxiliary_track_info_type_unknown = 0 , heif_auxiliary_track_info_type_alpha = 1 }
enum	heif_sample_aux_info_presence { heif_sample_aux_info_presence_none = 0 , heif_sample_aux_info_presence_optional = 1 , heif_sample_aux_info_presence_mandatory = 2 }
	Specifies whether a 'sample auxiliary info' is stored with the samples. More...
enum	heif_sequence_gop_structure { heif_sequence_gop_structure_intra_only , heif_sequence_gop_structure_lowdelay , heif_sequence_gop_structure_unrestricted }
enum	heif_sequence_content_kind { heif_sequence_content_kind_auto = 0 , heif_sequence_content_kind_image_sequence = 1 , heif_sequence_content_kind_video = 2 }
enum	heif_track_reference_type { heif_track_reference_type_description = heif_fourcc('c', 'd', 's', 'c') , heif_track_reference_type_thumbnails = heif_fourcc('t', 'h', 'm', 'b') , heif_track_reference_type_auxiliary = heif_fourcc('a', 'u', 'x', 'l') }

Functions
int	heif_context_has_sequence (const heif_context *)
	Check whether there is an image sequence in the HEIF file.
uint32_t	heif_context_get_sequence_timescale (const heif_context *)
	Get the timescale (clock ticks per second) for timing values in the sequence.
uint64_t	heif_context_get_sequence_duration (const heif_context *)
	Get the total duration of the sequence in timescale clock ticks.
void	heif_track_release (heif_track *)
	Free a heif_track object received from libheif.
int	heif_context_number_of_sequence_tracks (const heif_context *)
	Get the number of tracks in the HEIF file.
void	heif_context_get_track_ids (const heif_context *ctx, uint32_t out_track_id_array[])
	Returns the IDs for each of the tracks stored in the HEIF file.
uint32_t	heif_track_get_id (const heif_track *track)
	Get the ID of the passed track.
heif_track *	heif_context_get_track (const heif_context *, uint32_t id)
	Get the heif_track object for the given track ID.
heif_track_type	heif_track_get_track_handler_type (const heif_track *)
	Get the four-cc track handler type.
enum heif_auxiliary_track_info_type	heif_track_get_auxiliary_info_type (const heif_track *)
const char *	heif_track_get_auxiliary_info_type_urn (const heif_track *)
int	heif_track_has_alpha_channel (const heif_track *)
uint32_t	heif_track_get_timescale (const heif_track *)
	Get the timescale (clock ticks per second) for this track.
uint32_t	heif_track_get_number_of_repetitions (const heif_track *)
	How many times the media segment should be played according to the track's edit list.
heif_error	heif_track_get_image_resolution (const heif_track *, uint16_t *out_width, uint16_t *out_height)
	Get the image resolution of the track.
heif_error	heif_track_decode_next_image (heif_track *track, heif_image **out_img, heif_colorspace colorspace, heif_chroma chroma, const heif_decoding_options *options)
	Decode the next image in the passed sequence track.
uint32_t	heif_image_get_duration (const heif_image *)
	Get the image display duration in clock ticks of this track.
uint32_t	heif_track_get_sample_entry_type_of_first_cluster (const heif_track *)
	Get the "sample entry type" of the first sample sample cluster in the track.
heif_error	heif_track_get_urim_sample_entry_uri_of_first_cluster (const heif_track *, const char **out_uri)
	Get the URI of the first sample cluster in an 'urim' track.
heif_error	heif_track_get_next_raw_sequence_sample (heif_track *, heif_raw_sequence_sample **out_sample)
	Get the next raw sample from the (metadata) sequence track.
void	heif_raw_sequence_sample_release (heif_raw_sequence_sample *)
	Release a heif_raw_sequence_sample object.
const uint8_t *	heif_raw_sequence_sample_get_data (const heif_raw_sequence_sample *, size_t *out_array_size)
	Get a pointer to the data of the (metadata) sample.
size_t	heif_raw_sequence_sample_get_data_size (const heif_raw_sequence_sample *)
	Return the size of the raw data contained in the sample.
uint32_t	heif_raw_sequence_sample_get_duration (const heif_raw_sequence_sample *)
	Get the sample duration in clock ticks of this track.
void	heif_context_set_sequence_timescale (heif_context *, uint32_t timescale)
	Set an independent global timescale for the sequence.
void	heif_context_set_number_of_sequence_repetitions (heif_context *, uint32_t number_of_repetitions)
heif_track_options *	heif_track_options_alloc (void)
	Allocate track options object that is required to set options for a new track.
void	heif_track_options_release (heif_track_options *)
void	heif_track_options_set_timescale (heif_track_options *, uint32_t timescale)
	Set the track specific timescale.
void	heif_track_options_set_interleaved_sample_aux_infos (heif_track_options *, int interleaved_flag)
	Set whether the aux-info data should be stored interleaved with the sequence samples.
heif_error	heif_track_options_enable_sample_tai_timestamps (heif_track_options *, const heif_tai_clock_info *, enum heif_sample_aux_info_presenceheif_sample_aux_info_presence)
void	heif_track_options_enable_sample_gimi_content_ids (heif_track_options *, enum heif_sample_aux_info_presenceheif_sample_aux_info_presence)
void	heif_track_options_set_gimi_track_id (heif_track_options *, const char *track_id)
	Set the GIMI format track ID string.
heif_sequence_encoding_options *	heif_sequence_encoding_options_alloc (void)
void	heif_sequence_encoding_options_copy (heif_sequence_encoding_options *dst, const heif_sequence_encoding_options *src)
	Copy fields from src into dst, respecting both structs' version numbers.
void	heif_sequence_encoding_options_release (heif_sequence_encoding_options *)
heif_error	heif_context_add_visual_sequence_track (heif_context *, uint16_t width, uint16_t height, heif_track_type track_type, const heif_track_options *track_options, const heif_sequence_encoding_options *encoding_options, heif_track **out_track)
	Add a visual track to the sequence.
void	heif_image_set_duration (heif_image *, uint32_t duration)
	Set the image display duration in the track's timescale units.
heif_error	heif_track_encode_sequence_image (heif_track *, const heif_image *image, heif_encoder *encoder, const heif_sequence_encoding_options *sequence_encoding_options)
	Encode the image into a visual track.
heif_error	heif_track_encode_end_of_sequence (heif_track *, heif_encoder *encoder)
	When all sequence frames have been sent, you can to call this function to let the library know that no more frames will follow.
heif_error	heif_context_add_uri_metadata_sequence_track (heif_context *, const char *uri, const heif_track_options *options, heif_track **out_track)
	Add a metadata track.
heif_raw_sequence_sample *	heif_raw_sequence_sample_alloc (void)
	Allocate a new heif_raw_sequence_sample object.
heif_error	heif_raw_sequence_sample_set_data (heif_raw_sequence_sample *, const uint8_t *data, size_t size)
	Set the raw sequence sample data.
void	heif_raw_sequence_sample_set_duration (heif_raw_sequence_sample *, uint32_t duration)
	Set the sample duration in track timescale units.
heif_error	heif_track_add_raw_sequence_sample (heif_track *, const heif_raw_sequence_sample *)
	Add a raw sequence sample (usually a metadata sample) to the (metadata) track.
int	heif_track_get_number_of_sample_aux_infos (const heif_track *)
	Returns how many different types of sample auxiliary data units are assigned to this track's samples.
void	heif_track_get_sample_aux_info_types (const heif_track *, heif_sample_aux_info_type out_types[])
	Get get the list of sample auxiliary data types used in the track.
const char *	heif_track_get_gimi_track_content_id (const heif_track *)
	Get the GIMI content ID for the track (as a whole).
const char *	heif_image_get_gimi_sample_content_id (const heif_image *)
	Get the GIMI content ID stored in the image sample.
const char *	heif_raw_sequence_sample_get_gimi_sample_content_id (const heif_raw_sequence_sample *)
	Get the GIMI content ID stored in the metadata sample.
void	heif_image_set_gimi_sample_content_id (heif_image *, const char *contentID)
	Set the GIMI content ID for an image sample.
void	heif_raw_sequence_sample_set_gimi_sample_content_id (heif_raw_sequence_sample *, const char *contentID)
	Set the GIMI content ID for a (metadata) sample.
int	heif_raw_sequence_sample_has_tai_timestamp (const heif_raw_sequence_sample *)
	Returns whether the raw (metadata) sample has a TAI timestamp attached to it (stored as SAI).
const heif_tai_timestamp_packet *	heif_raw_sequence_sample_get_tai_timestamp (const heif_raw_sequence_sample *)
	Get the TAI timestamp of the (metadata) sample.
void	heif_raw_sequence_sample_set_tai_timestamp (heif_raw_sequence_sample *sample, const heif_tai_timestamp_packet *timestamp)
	Set the TAI timestamp for a raw sequence sample.
const heif_tai_clock_info *	heif_track_get_tai_clock_info_of_first_cluster (heif_track *)
	Returns the TAI clock info of the track.
void	heif_track_add_reference_to_track (heif_track *, uint32_t reference_type, const heif_track *to_track)
	Add a reference between tracks.
size_t	heif_track_get_number_of_track_reference_types (const heif_track *)
	Return the number of different reference types used in this track's tref box.
void	heif_track_get_track_reference_types (const heif_track *, uint32_t out_reference_types[])
	List the reference types used in this track.
size_t	heif_track_get_number_of_track_reference_of_type (const heif_track *, uint32_t reference_type)
	Get the number of references of the passed type.
size_t	heif_track_get_references_from_track (const heif_track *, uint32_t reference_type, uint32_t out_to_track_id[])
	List the track ids this track points to with the passed reference type.
size_t	heif_track_find_referring_tracks (const heif_track *, uint32_t reference_type, uint32_t out_track_id[], size_t array_size)
	Find tracks that are referring to the current track through the passed reference_type.

Macro Definition Documentation

heif_sequence_maximum_number_of_repetitions

#define heif_sequence_maximum_number_of_repetitions   0

heif_sequence_track_number_of_repetitions_infinite

#define heif_sequence_track_number_of_repetitions_infinite   0xFFFFFFFFu

Special return value of heif_track_get_number_of_repetitions() indicating that the editlist requests indefinite repetition (the mvhd duration is the ISOBMFF "duration unknown" sentinel and the editlist is in repeat mode).

Typedef Documentation

heif_auxiliary_track_info_type

typedef enum heif_auxiliary_track_info_type heif_auxiliary_track_info_type

heif_raw_sequence_sample

typedef struct heif_raw_sequence_sample heif_raw_sequence_sample

Sequence sample object that can hold any raw byte data.

Use this to store and read raw metadata samples.

heif_sample_aux_info_presence

typedef enum heif_sample_aux_info_presence heif_sample_aux_info_presence

Specifies whether a 'sample auxiliary info' is stored with the samples.

The difference between heif_sample_aux_info_presence_optional and heif_sample_aux_info_presence_mandatory is that heif_sample_aux_info_presence_mandatory will throw an error if the data is missing when writing a sample.

heif_sample_aux_info_type

typedef struct heif_sample_aux_info_type heif_sample_aux_info_type

Contains the type of sample auxiliary data assigned to the track samples.

heif_sequence_content_kind

typedef enum heif_sequence_content_kind heif_sequence_content_kind

heif_sequence_encoding_options

typedef struct heif_sequence_encoding_options heif_sequence_encoding_options

heif_sequence_gop_structure

typedef enum heif_sequence_gop_structure heif_sequence_gop_structure

heif_tai_clock_info

typedef struct heif_tai_clock_info heif_tai_clock_info

heif_tai_timestamp_packet

typedef struct heif_tai_timestamp_packet heif_tai_timestamp_packet

heif_track

typedef struct heif_track heif_track

heif_track_options

typedef struct heif_track_options heif_track_options

heif_track_reference_type

typedef enum heif_track_reference_type heif_track_reference_type

heif_track_type

typedef uint32_t heif_track_type

heif_track_type_4cc

typedef enum heif_track_type_4cc heif_track_type_4cc

Enumeration Type Documentation

heif_auxiliary_track_info_type

enum heif_auxiliary_track_info_type

Enumerator
heif_auxiliary_track_info_type_unknown
heif_auxiliary_track_info_type_alpha

heif_sample_aux_info_presence

enum heif_sample_aux_info_presence

Specifies whether a 'sample auxiliary info' is stored with the samples.

The difference between heif_sample_aux_info_presence_optional and heif_sample_aux_info_presence_mandatory is that heif_sample_aux_info_presence_mandatory will throw an error if the data is missing when writing a sample.

Enumerator
heif_sample_aux_info_presence_none
heif_sample_aux_info_presence_optional
heif_sample_aux_info_presence_mandatory

heif_sequence_content_kind

enum heif_sequence_content_kind

Enumerator
heif_sequence_content_kind_auto
heif_sequence_content_kind_image_sequence
heif_sequence_content_kind_video

heif_sequence_gop_structure

enum heif_sequence_gop_structure

Enumerator
heif_sequence_gop_structure_intra_only
heif_sequence_gop_structure_lowdelay
heif_sequence_gop_structure_unrestricted

heif_track_reference_type

enum heif_track_reference_type

Enumerator
heif_track_reference_type_description
heif_track_reference_type_thumbnails
heif_track_reference_type_auxiliary

heif_track_type_4cc

enum heif_track_type_4cc

Enumerator
heif_track_type_video
heif_track_type_image_sequence
heif_track_type_auxiliary
heif_track_type_metadata

Function Documentation

heif_context_add_uri_metadata_sequence_track()

heif_error heif_context_add_uri_metadata_sequence_track	(	heif_context *	,
		const char *	uri,
		const heif_track_options *	options,
		heif_track **	out_track )

Add a metadata track.

The track is created as a 'urim' "URI Meta Sample Entry". The track content type is specified by the 'uri' parameter.

Parameters

uri	Track content type.
options	Optional track creation options. If NULL, default options will be used.
out_track	Returns the created track object. If this is not NULL, you have to free the returned track with heif_track_release.

heif_context_add_visual_sequence_track()

heif_error heif_context_add_visual_sequence_track	(	heif_context *	,
		uint16_t	width,
		uint16_t	height,
		heif_track_type	track_type,
		const heif_track_options *	track_options,
		const heif_sequence_encoding_options *	encoding_options,
		heif_track **	out_track )

Add a visual track to the sequence.

The track ID is assigned automatically.

Parameters

width	Image resolution width
height	Image resolution height
track_type	Has to be heif_track_type_video or heif_track_type_image_sequence
track_options	Optional track creation options. If NULL, default options will be used.
encoding_options	Options for sequence encoding. If NULL, default options will be used.
out_track	Output parameter to receive the track object for the just created track.

Returns

heif_context_get_sequence_duration()

uint64_t heif_context_get_sequence_duration

(

const heif_context *

)

Get the total duration of the sequence in timescale clock ticks.

Use heif_context_get_sequence_timescale() to get the clock ticks per second.

Returns

Sequence duration in clock ticks. Returns 0 if there is no sequence in the file.

heif_context_get_sequence_timescale()

uint32_t heif_context_get_sequence_timescale

(

const heif_context *

)

Get the timescale (clock ticks per second) for timing values in the sequence.

Note

Each track may have its independent timescale.

Returns

Clock ticks per second. Returns 0 if there is no sequence in the file.

heif_context_get_track()

heif_track * heif_context_get_track	(	const heif_context *	,
		uint32_t	id )

Get the heif_track object for the given track ID.

If you pass id=0, the first visual track will be returned. If there is no track with the given ID or if 0 is passed and there is no visual track, NULL will be returned.

Note

Tracks never have a zero ID. This is why we can use this as a special value to find the first visual track.

Parameters

id	Track id or 0 for the first visual track.

Returns

heif_track object. You must free this after use.

heif_context_get_track_ids()

void heif_context_get_track_ids	(	const heif_context *	ctx,
		uint32_t	out_track_id_array[] )

Returns the IDs for each of the tracks stored in the HEIF file.

The caller MUST allocate out_track_id_array with exactly heif_context_number_of_sequence_tracks() entries. The function writes that many IDs unconditionally. Passing a smaller array results in a buffer overflow (undefined behavior); there is no capacity parameter and no truncation.

heif_context_has_sequence()

int heif_context_has_sequence

(

const heif_context *

)

Check whether there is an image sequence in the HEIF file.

Returns

A boolean whether there is an image sequence in the HEIF file.

heif_context_number_of_sequence_tracks()

int heif_context_number_of_sequence_tracks

(

const heif_context *

)

Get the number of tracks in the HEIF file.

Returns

Number of tracks or 0 if there is no sequence in the HEIF file.

heif_context_set_number_of_sequence_repetitions()

void heif_context_set_number_of_sequence_repetitions	(	heif_context *	,
		uint32_t	number_of_repetitions )

heif_context_set_sequence_timescale()

void heif_context_set_sequence_timescale	(	heif_context *	,
		uint32_t	timescale )

Set an independent global timescale for the sequence.

If no timescale is set with this function, the timescale of the first track will be used.

heif_image_get_duration()

uint32_t heif_image_get_duration

(

const heif_image *

)

Get the image display duration in clock ticks of this track.

Make sure to use the timescale of the track and not the timescale of the total sequence.

heif_image_get_gimi_sample_content_id()

const char * heif_image_get_gimi_sample_content_id

(

const heif_image *

)

Get the GIMI content ID stored in the image sample.

If there is no content ID, NULL is returned.

Returns

heif_image_set_duration()

void heif_image_set_duration	(	heif_image *	,
		uint32_t	duration )

Set the image display duration in the track's timescale units.

heif_image_set_gimi_sample_content_id()

void heif_image_set_gimi_sample_content_id	(	heif_image *	,
		const char *	contentID )

Set the GIMI content ID for an image sample.

It will be stored as SAI. When passing NULL, a previously set ID will be removed.

heif_raw_sequence_sample_alloc()

heif_raw_sequence_sample * heif_raw_sequence_sample_alloc

(

void

)

Allocate a new heif_raw_sequence_sample object.

Free with heif_raw_sequence_sample_release().

heif_raw_sequence_sample_get_data()

const uint8_t * heif_raw_sequence_sample_get_data	(	const heif_raw_sequence_sample *	,
		size_t *	out_array_size )

Get a pointer to the data of the (metadata) sample.

The data pointer stays valid until the heif_raw_sequence_sample object is released.

Parameters

out_array_size

Size of the returned array (may be NULL).

heif_raw_sequence_sample_get_data_size()

size_t heif_raw_sequence_sample_get_data_size

(

const heif_raw_sequence_sample *

)

Return the size of the raw data contained in the sample.

This is the same as returned through the 'out_array_size' parameter of 'heif_raw_sequence_sample_get_data()'.

heif_raw_sequence_sample_get_duration()

uint32_t heif_raw_sequence_sample_get_duration

(

const heif_raw_sequence_sample *

)

Get the sample duration in clock ticks of this track.

Make sure to use the timescale of the track and not the timescale of the total sequence.

heif_raw_sequence_sample_get_gimi_sample_content_id()

const char * heif_raw_sequence_sample_get_gimi_sample_content_id

(

const heif_raw_sequence_sample *

)

Get the GIMI content ID stored in the metadata sample.

If there is no content ID, NULL is returned.

Returns

heif_raw_sequence_sample_get_tai_timestamp()

const heif_tai_timestamp_packet * heif_raw_sequence_sample_get_tai_timestamp

(

const heif_raw_sequence_sample *

)

Get the TAI timestamp of the (metadata) sample.

If there is no timestamp assigned to it, NULL will be returned.

Note

You should NOT free the returned timestamp with 'heif_tai_timestamp_packet_release()'. The returned struct stays valid until the heif_raw_sequence_sample is released.

heif_raw_sequence_sample_has_tai_timestamp()

int heif_raw_sequence_sample_has_tai_timestamp

(

const heif_raw_sequence_sample *

)

Returns whether the raw (metadata) sample has a TAI timestamp attached to it (stored as SAI).

Returns

boolean flag whether a TAI exists for this sample.

heif_raw_sequence_sample_release()

void heif_raw_sequence_sample_release

(

heif_raw_sequence_sample *

)

Release a heif_raw_sequence_sample object.

You may pass NULL.

heif_raw_sequence_sample_set_data()

heif_error heif_raw_sequence_sample_set_data	(	heif_raw_sequence_sample *	,
		const uint8_t *	data,
		size_t	size )

Set the raw sequence sample data.

heif_raw_sequence_sample_set_duration()

void heif_raw_sequence_sample_set_duration	(	heif_raw_sequence_sample *	,
		uint32_t	duration )

Set the sample duration in track timescale units.

heif_raw_sequence_sample_set_gimi_sample_content_id()

void heif_raw_sequence_sample_set_gimi_sample_content_id	(	heif_raw_sequence_sample *	,
		const char *	contentID )

Set the GIMI content ID for a (metadata) sample.

It will be stored as SAI. When passing NULL, a previously set ID will be removed.

heif_raw_sequence_sample_set_tai_timestamp()

void heif_raw_sequence_sample_set_tai_timestamp	(	heif_raw_sequence_sample *	sample,
		const heif_tai_timestamp_packet *	timestamp )

Set the TAI timestamp for a raw sequence sample.

The timestamp will be copied, you can release it after calling this function.

heif_sequence_encoding_options_alloc()

heif_sequence_encoding_options * heif_sequence_encoding_options_alloc

(

void

)

heif_sequence_encoding_options_copy()

void heif_sequence_encoding_options_copy	(	heif_sequence_encoding_options *	dst,
		const heif_sequence_encoding_options *	src )

Copy fields from src into dst, respecting both structs' version numbers.

Only fields present in min(dst->version, src->version) are copied, so this is safe when libheif and the caller were built against different header versions of heif_sequence_encoding_options. Pass NULL src to leave dst unchanged.

heif_sequence_encoding_options_release()

void heif_sequence_encoding_options_release

(

heif_sequence_encoding_options *

)

heif_track_add_raw_sequence_sample()

heif_error heif_track_add_raw_sequence_sample	(	heif_track *	,
		const heif_raw_sequence_sample *	)

Add a raw sequence sample (usually a metadata sample) to the (metadata) track.

heif_track_add_reference_to_track()

void heif_track_add_reference_to_track	(	heif_track *	,
		uint32_t	reference_type,
		const heif_track *	to_track )

Add a reference between tracks.

'reference_type' can be one of the four-cc codes listed in heif_track_reference_type or any other type.

heif_track_decode_next_image()

heif_error heif_track_decode_next_image	(	heif_track *	track,
		heif_image **	out_img,
		heif_colorspace	colorspace,
		heif_chroma	chroma,
		const heif_decoding_options *	options )

Decode the next image in the passed sequence track.

If there is no more image in the sequence, heif_error_End_of_sequence is returned. The parameters colorspace, chroma and options are similar to heif_decode_image(). If you want to let libheif decide the output colorspace and chroma, set these parameters to heif_colorspace_undefined / heif_chroma_undefined. Usually, libheif will return the image in the input colorspace, but it may also modify it for example when it has to rotate the image. If you want to get the image in a specific colorspace/chroma format, you can specify this and libheif will convert the image to match this format.

heif_track_encode_end_of_sequence()

heif_error heif_track_encode_end_of_sequence	(	heif_track *	,
		heif_encoder *	encoder )

When all sequence frames have been sent, you can to call this function to let the library know that no more frames will follow.

This is strongly recommended, but optional for backwards compatibility. If you do not end the sequence explicitly with this function, it will be closed automatically when the HEIF file is written. Using this function has the advantage that you can free the heif_encoder afterwards (with heif_encoder_release). If you do not use call function, you have to keep the heif_encoder alive until the HEIF file is written.

heif_track_encode_sequence_image()

heif_error heif_track_encode_sequence_image	(	heif_track *	,
		const heif_image *	image,
		heif_encoder *	encoder,
		const heif_sequence_encoding_options *	sequence_encoding_options )

Encode the image into a visual track.

If the passed track is no visual track, an error will be returned.

Parameters

image	The input image to append to the sequence.
encoder	The encoder used for encoding the image.
sequence_encoding_options	Options for sequence encoding. If NULL, default options will be used.

heif_track_find_referring_tracks()

size_t heif_track_find_referring_tracks	(	const heif_track *	,
		uint32_t	reference_type,
		uint32_t	out_track_id[],
		size_t	array_size )

Find tracks that are referring to the current track through the passed reference_type.

The found track IDs will be filled into the passed array, but no more than array_size entries will be filled.

Returns

number of tracks found. If this is equal to 'array_size', you should ask again with a larger array size to be sure you got all tracks.

heif_track_get_auxiliary_info_type()

enum heif_auxiliary_track_info_type heif_track_get_auxiliary_info_type

(

const heif_track *

)

heif_track_get_auxiliary_info_type_urn()

const char * heif_track_get_auxiliary_info_type_urn

(

const heif_track *

)

heif_track_get_gimi_track_content_id()

const char * heif_track_get_gimi_track_content_id

(

const heif_track *

)

Get the GIMI content ID for the track (as a whole).

If there is no content ID, nullptr is returned.

Returns

The returned string has to be released with heif_string_release().

heif_track_get_id()

uint32_t heif_track_get_id

(

const heif_track *

track

)

Get the ID of the passed track.

The track ID will never be 0.

heif_track_get_image_resolution()

heif_error heif_track_get_image_resolution	(	const heif_track *	,
		uint16_t *	out_width,
		uint16_t *	out_height )

Get the image resolution of the track.

If the passed track is no visual track, an error is returned.

heif_track_get_next_raw_sequence_sample()

heif_error heif_track_get_next_raw_sequence_sample	(	heif_track *	,
		heif_raw_sequence_sample **	out_sample )

Get the next raw sample from the (metadata) sequence track.

You have to free the returned sample with heif_raw_sequence_sample_release().

heif_track_get_number_of_repetitions()

uint32_t heif_track_get_number_of_repetitions

(

const heif_track *

)

How many times the media segment should be played according to the track's edit list.

Returns:

• 0 if an edit list box is present but follows a pattern libheif does not interpret as a loop count. Callers should fall back to a single playback in that case.
• 1 when no edit list is present. The media plays exactly once.
• heif_sequence_track_number_of_repetitions_infinite (= UINT32_MAX) when the file signals indefinite playback (mvhd duration is the all-1s sentinel together with an editlist in repeat mode), or when the repetition count does not fit in uint32_t.
• Otherwise the number of times the media segment is played.

The reported value is informational; it does not change how heif_track_decode_next_image() walks samples. By default, that function applies the edit list and (for repeated playback) returns samples for every requested repetition; iterating until end-of-sequence on an infinite-loop file therefore never terminates.

Clients that want to handle repetition themselves (e.g. to honor an "infinite" value with their own looping policy or to enforce an application-level cap) should set heif_decoding_options::ignore_sequence_editlist when calling heif_track_decode_next_image(). With that flag set, libheif plays the media timeline exactly once. Use the value returned by this function to decide how often to replay the track at the application level.

heif_track_get_number_of_sample_aux_infos()

int heif_track_get_number_of_sample_aux_infos

(

const heif_track *

)

Returns how many different types of sample auxiliary data units are assigned to this track's samples.

heif_track_get_number_of_track_reference_of_type()

size_t heif_track_get_number_of_track_reference_of_type	(	const heif_track *	,
		uint32_t	reference_type )

Get the number of references of the passed type.

heif_track_get_number_of_track_reference_types()

size_t heif_track_get_number_of_track_reference_types

(

const heif_track *

)

Return the number of different reference types used in this track's tref box.

heif_track_get_references_from_track()

size_t heif_track_get_references_from_track	(	const heif_track *	,
		uint32_t	reference_type,
		uint32_t	out_to_track_id[] )

List the track ids this track points to with the passed reference type.

The passed array must have heif_track_get_number_of_track_reference_of_type() entries.

heif_track_get_sample_aux_info_types()

void heif_track_get_sample_aux_info_types	(	const heif_track *	,
		heif_sample_aux_info_type	out_types[] )

Get get the list of sample auxiliary data types used in the track.

The passed array has to have heif_track_get_number_of_sample_aux_infos() entries.

heif_track_get_sample_entry_type_of_first_cluster()

uint32_t heif_track_get_sample_entry_type_of_first_cluster

(

const heif_track *

)

Get the "sample entry type" of the first sample sample cluster in the track.

In the case of metadata tracks, this will usually be "urim" for "URI Meta Sample Entry". The exact URI can then be obtained with 'heif_track_get_urim_sample_entry_uri_of_first_cluster'.

heif_track_get_tai_clock_info_of_first_cluster()

const heif_tai_clock_info * heif_track_get_tai_clock_info_of_first_cluster

(

heif_track *

)

Returns the TAI clock info of the track.

If there is no TAI clock info, NULL is returned. You should NOT free the returned heif_tai_clock_info. The structure stays valid until the heif_track object is released.

heif_track_get_timescale()

uint32_t heif_track_get_timescale

(

const heif_track *

)

Get the timescale (clock ticks per second) for this track.

Note that this can be different from the timescale used at sequence level.

Returns

clock ticks per second

heif_track_get_track_handler_type()

heif_track_type heif_track_get_track_handler_type

(

const heif_track *

)

Get the four-cc track handler type.

Typical codes are "vide" for video sequences, "pict" for image sequences, "meta" for metadata tracks. These are defined in heif_track_type_4cc, but files may also contain other types.

Returns

four-cc handler type

heif_track_get_track_reference_types()

void heif_track_get_track_reference_types	(	const heif_track *	,
		uint32_t	out_reference_types[] )

List the reference types used in this track.

The caller MUST allocate out_reference_types with exactly heif_track_get_number_of_track_reference_types() entries. The function writes that many values unconditionally. Passing a smaller array results in a buffer overflow (undefined behavior); there is no capacity parameter and no truncation.

heif_track_get_urim_sample_entry_uri_of_first_cluster()

heif_error heif_track_get_urim_sample_entry_uri_of_first_cluster	(	const heif_track *	,
		const char **	out_uri )

Get the URI of the first sample cluster in an 'urim' track.

Only call this for tracks with 'urim' sample entry types. It will return an error otherwise.

Parameters

out_uri

A string with the URI will be returned. Free this string with heif_string_release().

heif_track_has_alpha_channel()

int heif_track_has_alpha_channel

(

const heif_track *

)

heif_track_options_alloc()

heif_track_options * heif_track_options_alloc

(

void

)

Allocate track options object that is required to set options for a new track.

When you create a new track, you can also pass a NULL heif_track_options pointer, in which case the default options are used.

heif_track_options_enable_sample_gimi_content_ids()

void heif_track_options_enable_sample_gimi_content_ids	(	heif_track_options *	,
		enum	heif_sample_aux_info_presence )

heif_track_options_enable_sample_tai_timestamps()

heif_error heif_track_options_enable_sample_tai_timestamps	(	heif_track_options *	,
		const heif_tai_clock_info *	,
		enum	heif_sample_aux_info_presence )

heif_track_options_release()

void heif_track_options_release

(

heif_track_options *

)

heif_track_options_set_gimi_track_id()

void heif_track_options_set_gimi_track_id	(	heif_track_options *	,
		const char *	track_id )

Set the GIMI format track ID string.

If NULL is passed, no track ID is saved.

Parameters

track_id

heif_track_options_set_interleaved_sample_aux_infos()

void heif_track_options_set_interleaved_sample_aux_infos	(	heif_track_options *	,
		int	interleaved_flag )

Set whether the aux-info data should be stored interleaved with the sequence samples.

Default is: false.

If 'true', the aux_info data blocks will be interleaved with the compressed image. This has the advantage that the aux_info is localized near the image data.

If 'false', all aux_info will be written as one block after the compressed image data. This has the advantage that no aux_info offsets have to be written.

Note: currently ignored. Interleaved writing is disabled.

heif_track_options_set_timescale()

void heif_track_options_set_timescale	(	heif_track_options *	,
		uint32_t	timescale )

Set the track specific timescale.

This is the number of clock ticks per second. The default is 90,000 Hz.

Parameters

timescale

heif_track_release()

void heif_track_release

(

heif_track *

)

Free a heif_track object received from libheif.

Passing NULL is ok.