heif_sequences.h

Go to the documentation of this file.

/*
 * HEIF codec.
 * Copyright (c) 2025 Dirk Farin <dirk.farin@gmail.com>
 *
 * This file is part of libheif.
 *
 * libheif is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * libheif is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef LIBHEIF_HEIF_SEQUENCES_H
#define LIBHEIF_HEIF_SEQUENCES_H
 
#include "libheif/heif.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
// forward declaration of structs defined in heif_tai_timestamps.h
typedef struct heif_tai_clock_info heif_tai_clock_info;
typedef struct heif_tai_timestamp_packet heif_tai_timestamp_packet;
 
 
// --- reading sequence tracks

LIBHEIF_API
int heif_context_has_sequence(const heif_context*);

LIBHEIF_API
uint32_t heif_context_get_sequence_timescale(const heif_context*);

LIBHEIF_API
uint64_t heif_context_get_sequence_duration(const heif_context*);
 
 
// A track, which may be an image sequence, a video track or a metadata track.
typedef struct heif_track heif_track;

LIBHEIF_API
void heif_track_release(heif_track*);

LIBHEIF_API
int heif_context_number_of_sequence_tracks(const heif_context*);

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

LIBHEIF_API
uint32_t heif_track_get_id(const heif_track* track);

// Use id=0 for the first visual track.
LIBHEIF_API
heif_track* heif_context_get_track(const heif_context*, uint32_t id);
 
 
typedef uint32_t heif_track_type;
 
typedef 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')
} heif_track_type_4cc;

LIBHEIF_API
heif_track_type heif_track_get_track_handler_type(const heif_track*);
 
 
typedef enum heif_auxiliary_track_info_type
{
  heif_auxiliary_track_info_type_unknown = 0,
  heif_auxiliary_track_info_type_alpha = 1
} heif_auxiliary_track_info_type;
 
LIBHEIF_API
enum heif_auxiliary_track_info_type heif_track_get_auxiliary_info_type(const heif_track*);
 
LIBHEIF_API
const char* heif_track_get_auxiliary_info_type_urn(const heif_track*);
 
LIBHEIF_API
int heif_track_has_alpha_channel(const heif_track*);

LIBHEIF_API
uint32_t heif_track_get_timescale(const heif_track*);

#define heif_sequence_track_number_of_repetitions_infinite 0xFFFFFFFFu

LIBHEIF_API
uint32_t heif_track_get_number_of_repetitions(const heif_track*);
 
 
// --- reading visual tracks

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

LIBHEIF_API
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);

LIBHEIF_API
uint32_t heif_image_get_duration(const heif_image*);
 
 
// --- reading metadata track samples

LIBHEIF_API
uint32_t heif_track_get_sample_entry_type_of_first_cluster(const heif_track*);

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

typedef struct heif_raw_sequence_sample heif_raw_sequence_sample;

LIBHEIF_API
heif_error heif_track_get_next_raw_sequence_sample(heif_track*,
                                                   heif_raw_sequence_sample** out_sample);

LIBHEIF_API
void heif_raw_sequence_sample_release(heif_raw_sequence_sample*);

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

LIBHEIF_API
size_t heif_raw_sequence_sample_get_data_size(const heif_raw_sequence_sample*);

LIBHEIF_API
uint32_t heif_raw_sequence_sample_get_duration(const heif_raw_sequence_sample*);
 
 
// --- writing sequences

LIBHEIF_API
void heif_context_set_sequence_timescale(heif_context*, uint32_t timescale);
 
// Number of times the sequence should be played in total (default = 1).
// Can be set to heif_sequence_maximum_number_of_repetitions.
LIBHEIF_API
void heif_context_set_number_of_sequence_repetitions(heif_context*, uint32_t number_of_repetitions);
 
#define heif_sequence_maximum_number_of_repetitions 0

typedef 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
} heif_sample_aux_info_presence;
 
 
typedef struct heif_track_options heif_track_options;

LIBHEIF_API
heif_track_options* heif_track_options_alloc(void);
 
LIBHEIF_API
void heif_track_options_release(heif_track_options*);

LIBHEIF_API
void heif_track_options_set_timescale(heif_track_options*, uint32_t timescale);

LIBHEIF_API
void heif_track_options_set_interleaved_sample_aux_infos(heif_track_options*, int interleaved_flag);
 
LIBHEIF_API
heif_error heif_track_options_enable_sample_tai_timestamps(heif_track_options*,
                                                           const heif_tai_clock_info*,
                                                           enum heif_sample_aux_info_presence);
 
LIBHEIF_API
void heif_track_options_enable_sample_gimi_content_ids(heif_track_options*,
                                                       enum heif_sample_aux_info_presence);

LIBHEIF_API
void heif_track_options_set_gimi_track_id(heif_track_options*,
                                          const char* track_id);
 
 
// --- writing visual tracks
 
typedef enum heif_sequence_gop_structure
{
  // Only independently decodable keyframes.
  heif_sequence_gop_structure_intra_only,
 
  // No frame reordering, usually an IPPPP structure.
  heif_sequence_gop_structure_lowdelay,
 
  // All frame types are allowed, including frame reordering, to achieve
  // the best compression ratio.
  heif_sequence_gop_structure_unrestricted
} heif_sequence_gop_structure;
 
 
// Describes the intent of the encoded sequence content. Encoder plugins may
// use this to choose different default tunings (e.g. perceptual quality vs.
// rate-distortion) for slide-show-style image sequences vs. video.
//
// Pass `_auto` to let libheif pick a value. Today libheif derives the kind
// from the track's handler type (`pict` -> image_sequence, `vide` -> video);
// in the future it may use additional input signals (e.g. frame rate or
// frame-to-frame similarity). Plugins never see `_auto`: libheif resolves it
// to a concrete kind before passing the options to the encoder plugin.
typedef enum heif_sequence_content_kind
{
  heif_sequence_content_kind_auto = 0,
  heif_sequence_content_kind_image_sequence = 1,
  heif_sequence_content_kind_video = 2
} heif_sequence_content_kind;
 
 
typedef struct heif_sequence_encoding_options
{
  uint8_t version;
 
  // version 1 options
 
  // Set this to the NCLX parameters to be used in the output images or set to NULL
  // when the same parameters as in the input images should be used.
  const heif_color_profile_nclx* output_nclx_profile;
 
  heif_color_conversion_options color_conversion_options;
 
  // version 2 options
 
  enum heif_sequence_gop_structure gop_structure;
  int keyframe_distance_min; // 0 - undefined
  int keyframe_distance_max; // 0 - undefined
 
  int save_alpha_channel;
 
  // version 3 options
 
  // Intent of the encoded content. Encoder plugins may use this to choose
  // different tunings for slide-show-style image sequences vs. video.
  // Set to `_auto` (the default) to let libheif pick. libheif resolves the
  // value to a concrete kind before passing the options to the encoder
  // plugin, so plugins never see `_auto`.
  enum heif_sequence_content_kind content_kind;
} heif_sequence_encoding_options;
 
 
LIBHEIF_API
heif_sequence_encoding_options* heif_sequence_encoding_options_alloc(void);

LIBHEIF_API
void heif_sequence_encoding_options_copy(heif_sequence_encoding_options* dst,
                                         const heif_sequence_encoding_options* src);
 
LIBHEIF_API
void heif_sequence_encoding_options_release(heif_sequence_encoding_options*);

LIBHEIF_API
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);

LIBHEIF_API
void heif_image_set_duration(heif_image*, uint32_t duration);

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

LIBHEIF_API
heif_error heif_track_encode_end_of_sequence(heif_track*,
                                             heif_encoder* encoder);
 
// --- metadata tracks

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

LIBHEIF_API
heif_raw_sequence_sample* heif_raw_sequence_sample_alloc(void);

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

LIBHEIF_API
void heif_raw_sequence_sample_set_duration(heif_raw_sequence_sample*, uint32_t duration);

LIBHEIF_API
heif_error heif_track_add_raw_sequence_sample(heif_track*,
                                              const heif_raw_sequence_sample*);
 
 
// --- sample auxiliary data

typedef struct heif_sample_aux_info_type
{
  uint32_t type;
  uint32_t parameter;
} heif_sample_aux_info_type;

LIBHEIF_API
int heif_track_get_number_of_sample_aux_infos(const heif_track*);

LIBHEIF_API
void heif_track_get_sample_aux_info_types(const heif_track*, heif_sample_aux_info_type out_types[]);
 
 
// --- GIMI content IDs

LIBHEIF_API
const char* heif_track_get_gimi_track_content_id(const heif_track*);

LIBHEIF_API
const char* heif_image_get_gimi_sample_content_id(const heif_image*);

LIBHEIF_API
const char* heif_raw_sequence_sample_get_gimi_sample_content_id(const heif_raw_sequence_sample*);

LIBHEIF_API
void heif_image_set_gimi_sample_content_id(heif_image*, const char* contentID);

LIBHEIF_API
void heif_raw_sequence_sample_set_gimi_sample_content_id(heif_raw_sequence_sample*, const char* contentID);
 
 
// --- TAI timestamps
 
// Note: functions for setting timestamps on images are in heif_tai_timestamps.h

LIBHEIF_API
int heif_raw_sequence_sample_has_tai_timestamp(const heif_raw_sequence_sample*);

LIBHEIF_API
const heif_tai_timestamp_packet* heif_raw_sequence_sample_get_tai_timestamp(const heif_raw_sequence_sample*);

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

LIBHEIF_API
const heif_tai_clock_info* heif_track_get_tai_clock_info_of_first_cluster(heif_track*);
 
 
// --- track references
 
typedef enum heif_track_reference_type
{
  heif_track_reference_type_description = heif_fourcc('c', 'd', 's', 'c'), // track_description
  heif_track_reference_type_thumbnails = heif_fourcc('t', 'h', 'm', 'b'), // thumbnails
  heif_track_reference_type_auxiliary = heif_fourcc('a', 'u', 'x', 'l') // auxiliary data (e.g. depth maps or alpha channel)
} heif_track_reference_type;

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

LIBHEIF_API
size_t heif_track_get_number_of_track_reference_types(const heif_track*);

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

LIBHEIF_API
size_t heif_track_get_number_of_track_reference_of_type(const heif_track*, uint32_t reference_type);

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

LIBHEIF_API
size_t heif_track_find_referring_tracks(const heif_track*, uint32_t reference_type, uint32_t out_track_id[], size_t array_size);
 
#ifdef __cplusplus
}
#endif
 
#endif