Loading...
Searching...
No Matches
exif.h
Go to the documentation of this file.
/*
* EXIF metadata parser
* Copyright (c) 2013 Thilo Borgmann <thilo.borgmann _at_ mail.de>
* Copyright (c) 2024-2025 Leo Izen <leo.izen@gmail.com>
*
* This file is part of FFmpeg.
*
* FFmpeg 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 2.1 of the License, or (at your option) any later version.
*
* FFmpeg 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 FFmpeg; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/**
* @file
* EXIF metadata parser
* @author Thilo Borgmann <thilo.borgmann _at_ mail.de>
* @author Leo Izen <leo.izen@gmail.com>
*/
#ifndef AVCODEC_EXIF_H
#define AVCODEC_EXIF_H
#include <stddef.h>
#include <stdint.h>
#include "libavutil/buffer.h"
#include "libavutil/dict.h"
#include "libavutil/rational.h"
#include "version_major.h"
/** Data type identifiers for TIFF tags */
enum AVTiffDataType {
AV_TIFF_BYTE = 1,
AV_TIFF_STRING,
AV_TIFF_SHORT,
AV_TIFF_LONG,
AV_TIFF_RATIONAL,
AV_TIFF_SBYTE,
AV_TIFF_UNDEFINED,
AV_TIFF_SSHORT,
AV_TIFF_SLONG,
AV_TIFF_SRATIONAL,
AV_TIFF_FLOAT,
AV_TIFF_DOUBLE,
AV_TIFF_IFD,
};
enum AVExifHeaderMode {
/**
* The TIFF header starts with 0x49492a00, or 0x4d4d002a.
* This one is used internally by FFmpeg.
*/
AV_EXIF_TIFF_HEADER,
/** skip the TIFF header, assume little endian */
AV_EXIF_ASSUME_LE,
/** skip the TIFF header, assume big endian */
AV_EXIF_ASSUME_BE,
/** The first four bytes point to the actual start, then it's AV_EXIF_TIFF_HEADER */
AV_EXIF_T_OFF,
/** The first six bytes contain "Exif\0\0", then it's AV_EXIF_TIFF_HEADER */
AV_EXIF_EXIF00,
};
typedef struct AVExifEntry AVExifEntry;
typedef struct AVExifMetadata {
/* array of EXIF metadata entries */
AVExifEntry *entries;
/* number of entries in this array */
unsigned int count;
/* size of the buffer, used for av_fast_realloc */
unsigned int size;
} AVExifMetadata;
struct AVExifEntry {
uint16_t id;
enum AVTiffDataType type;
uint32_t count;
/*
* These are for IFD-style MakerNote
* entries which occur after a fixed
* offset rather than at the start of
* the entry. The ifd_lead field contains
* the leading bytes which typically
* identify the type of MakerNote.
*/
uint32_t ifd_offset;
uint8_t *ifd_lead;
/*
* An array of entries of size count
* Unless it's an IFD, in which case
* it's not an array and count = 1
*/
union {
void *ptr;
int64_t *sint;
uint64_t *uint;
double *dbl;
char *str;
uint8_t *ubytes;
int8_t *sbytes;
AVRational *rat;
AVExifMetadata ifd;
} value;
};
/**
* Retrieves the tag name associated with the provided tag ID.
* If the tag ID is unknown, NULL is returned.
*
* For example, av_exif_get_tag_name(0x112) returns "Orientation".
*/
const char *av_exif_get_tag_name(uint16_t id);
/**
* Retrieves the tag ID associated with the provided tag string name.
* If the tag name is unknown, a negative number is returned. Otherwise
* it always fits inside a uint16_t integer.
*
* For example, av_exif_get_tag_id("Orientation") returns 274 (0x0112).
*/
int32_t av_exif_get_tag_id(const char *name);
/**
* Add an entry to the provided EXIF metadata struct. If one already exists with the provided
* ID, it will set the existing one to have the other information provided. Otherwise, it
* will allocate a new entry.
*
* This function reallocates ifd->entries using av_realloc and allocates (using av_malloc)
* a new value member of the entry, then copies the contents of value into that buffer.
*/
int av_exif_set_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, enum AVTiffDataType type,
uint32_t count, const uint8_t *ifd_lead, uint32_t ifd_offset, const void *value);
/**
* Also check subdirectories.
*/
#define AV_EXIF_FLAG_RECURSIVE (1 << 0)
/**
* Get an entry with the tagged ID from the EXIF metadata struct. A pointer to the entry
* will be written into *value.
*
* If the entry was present and returned successfully, a positive number is returned.
* If the entry was not found, *value is left untouched and zero is returned.
* If an error occurred, a negative number is returned.
*/
int av_exif_get_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags, AVExifEntry **value);
/**
* Remove an entry from the provided EXIF metadata struct.
*
* If the entry was present and removed successfully, a positive number is returned.
* If the entry was not found, zero is returned.
* If an error occurred, a negative number is returned.
*/
int av_exif_remove_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags);
/**
* Decodes the EXIF data provided in the buffer and writes it into the
* struct *ifd. If this function succeeds, the IFD is owned by the caller
* and must be cleared after use by calling av_exif_free(); If this function
* fails and returns a negative value, it will call av_exif_free(ifd) before
* returning.
*/
int av_exif_parse_buffer(void *logctx, const uint8_t *data, size_t size,
AVExifMetadata *ifd, enum AVExifHeaderMode header_mode);
/**
* Allocates a buffer using av_malloc of an appropriate size and writes the
* EXIF data represented by ifd into that buffer.
*
* Upon error, *buffer will be NULL. The buffer becomes owned by the caller upon
* success. The *buffer argument must be NULL before calling.
*/
int av_exif_write(void *logctx, const AVExifMetadata *ifd, AVBufferRef **buffer, enum AVExifHeaderMode header_mode);
/**
* Frees all resources associated with the given EXIF metadata struct.
* Does not free the pointer passed itself, in case it is stack-allocated.
* The pointer passed to this function must be freed by the caller,
* if it is heap-allocated. Passing NULL is permitted.
*/
void av_exif_free(AVExifMetadata *ifd);
/**
* Recursively reads all tags from the IFD and stores them in the
* provided metadata dictionary.
*/
int av_exif_ifd_to_dict(void *logctx, const AVExifMetadata *ifd, AVDictionary **metadata);
/**
* Allocates a duplicate of the provided EXIF metadata struct. The caller owns
* the duplicate and must free it with av_exif_free. Returns NULL if the duplication
* process failed.
*/
AVExifMetadata *av_exif_clone_ifd(const AVExifMetadata *ifd);
/**
* Convert a display matrix used by AV_FRAME_DATA_DISPLAYMATRIX
* into an orientation constant used by EXIF's orientation tag.
*
* Returns an EXIF orientation between 1 and 8 (inclusive) depending
* on the rotation and flip factors. Returns 0 if the matrix is singular.
*/
int av_exif_matrix_to_orientation(const int32_t *matrix);
/**
* Convert an orientation constant used by EXIF's orientation tag
* into a display matrix used by AV_FRAME_DATA_DISPLAYMATRIX.
*
* Returns 0 on success and negative if the orientation is invalid,
* i.e. not between 1 and 8 (inclusive).
*/
int av_exif_orientation_to_matrix(int32_t *matrix, int orientation);
#endif /* AVCODEC_EXIF_H */
buffer.h
refcounted data buffer API
dict.h
Public dictionary API.
av_exif_get_entry
int av_exif_get_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags, AVExifEntry **value)
Get an entry with the tagged ID from the EXIF metadata struct.
AVTiffDataType
AVTiffDataType
Data type identifiers for TIFF tags.
Definition exif.h:42
AV_TIFF_SLONG
@ AV_TIFF_SLONG
Definition exif.h:51
AV_TIFF_STRING
@ AV_TIFF_STRING
Definition exif.h:44
AV_TIFF_FLOAT
@ AV_TIFF_FLOAT
Definition exif.h:53
AV_TIFF_SBYTE
@ AV_TIFF_SBYTE
Definition exif.h:48
AV_TIFF_SHORT
@ AV_TIFF_SHORT
Definition exif.h:45
AV_TIFF_SRATIONAL
@ AV_TIFF_SRATIONAL
Definition exif.h:52
AV_TIFF_SSHORT
@ AV_TIFF_SSHORT
Definition exif.h:50
AV_TIFF_RATIONAL
@ AV_TIFF_RATIONAL
Definition exif.h:47
AV_TIFF_LONG
@ AV_TIFF_LONG
Definition exif.h:46
AV_TIFF_IFD
@ AV_TIFF_IFD
Definition exif.h:55
AV_TIFF_DOUBLE
@ AV_TIFF_DOUBLE
Definition exif.h:54
AV_TIFF_BYTE
@ AV_TIFF_BYTE
Definition exif.h:43
AV_TIFF_UNDEFINED
@ AV_TIFF_UNDEFINED
Definition exif.h:49
av_exif_set_entry
int av_exif_set_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, enum AVTiffDataType type, uint32_t count, const uint8_t *ifd_lead, uint32_t ifd_offset, const void *value)
Add an entry to the provided EXIF metadata struct.
av_exif_ifd_to_dict
int av_exif_ifd_to_dict(void *logctx, const AVExifMetadata *ifd, AVDictionary **metadata)
Recursively reads all tags from the IFD and stores them in the provided metadata dictionary.
av_exif_free
void av_exif_free(AVExifMetadata *ifd)
Frees all resources associated with the given EXIF metadata struct.
av_exif_matrix_to_orientation
int av_exif_matrix_to_orientation(const int32_t *matrix)
Convert a display matrix used by AV_FRAME_DATA_DISPLAYMATRIX into an orientation constant used by EXI...
av_exif_parse_buffer
int av_exif_parse_buffer(void *logctx, const uint8_t *data, size_t size, AVExifMetadata *ifd, enum AVExifHeaderMode header_mode)
Decodes the EXIF data provided in the buffer and writes it into the struct *ifd.
av_exif_get_tag_name
const char * av_exif_get_tag_name(uint16_t id)
Retrieves the tag name associated with the provided tag ID.
av_exif_orientation_to_matrix
int av_exif_orientation_to_matrix(int32_t *matrix, int orientation)
Convert an orientation constant used by EXIF's orientation tag into a display matrix used by AV_FRAME...
av_exif_clone_ifd
AVExifMetadata * av_exif_clone_ifd(const AVExifMetadata *ifd)
Allocates a duplicate of the provided EXIF metadata struct.
av_exif_write
int av_exif_write(void *logctx, const AVExifMetadata *ifd, AVBufferRef **buffer, enum AVExifHeaderMode header_mode)
Allocates a buffer using av_malloc of an appropriate size and writes the EXIF data represented by ifd...
av_exif_get_tag_id
int32_t av_exif_get_tag_id(const char *name)
Retrieves the tag ID associated with the provided tag string name.
AVExifHeaderMode
AVExifHeaderMode
Definition exif.h:58
AV_EXIF_EXIF00
@ AV_EXIF_EXIF00
The first six bytes contain "Exif\0\0", then it's AV_EXIF_TIFF_HEADER.
Definition exif.h:71
AV_EXIF_TIFF_HEADER
@ AV_EXIF_TIFF_HEADER
The TIFF header starts with 0x49492a00, or 0x4d4d002a.
Definition exif.h:63
AV_EXIF_ASSUME_BE
@ AV_EXIF_ASSUME_BE
skip the TIFF header, assume big endian
Definition exif.h:67
AV_EXIF_ASSUME_LE
@ AV_EXIF_ASSUME_LE
skip the TIFF header, assume little endian
Definition exif.h:65
AV_EXIF_T_OFF
@ AV_EXIF_T_OFF
The first four bytes point to the actual start, then it's AV_EXIF_TIFF_HEADER.
Definition exif.h:69
av_exif_remove_entry
int av_exif_remove_entry(void *logctx, AVExifMetadata *ifd, uint16_t id, int flags)
Remove an entry from the provided EXIF metadata struct.
AVDictionary
struct AVDictionary AVDictionary
Definition dict.h:95
version_major.h
Libavcodec version macros.
rational.h
Utilities for rational number calculation.
AVBufferRef
A reference to a data buffer.
Definition buffer.h:82
AVExifEntry
Definition exif.h:85
AVExifEntry::ifd
AVExifMetadata ifd
Definition exif.h:115
AVExifEntry::ifd_offset
uint32_t ifd_offset
Definition exif.h:98
AVExifEntry::sbytes
int8_t * sbytes
Definition exif.h:113
AVExifEntry::type
enum AVTiffDataType type
Definition exif.h:87
AVExifEntry::ubytes
uint8_t * ubytes
Definition exif.h:112
AVExifEntry::sint
int64_t * sint
Definition exif.h:108
AVExifEntry::str
char * str
Definition exif.h:111
AVExifEntry::id
uint16_t id
Definition exif.h:86
AVExifEntry::ptr
void * ptr
Definition exif.h:107
AVExifEntry::count
uint32_t count
Definition exif.h:88
AVExifEntry::value
union AVExifEntry::@325220332140161067313112036135003363017341144014 value
AVExifEntry::rat
AVRational * rat
Definition exif.h:114
AVExifEntry::dbl
double * dbl
Definition exif.h:110
AVExifEntry::ifd_lead
uint8_t * ifd_lead
Definition exif.h:99
AVExifEntry::uint
uint64_t * uint
Definition exif.h:109
AVExifMetadata
Definition exif.h:76
AVExifMetadata::count
unsigned int count
Definition exif.h:80
AVExifMetadata::entries
AVExifEntry * entries
Definition exif.h:78
AVExifMetadata::size
unsigned int size
Definition exif.h:82
AVRational
Rational number (pair of numerator and denominator).
Definition rational.h:58