API Reference

This page is generated from the public C++ headers via Doxygen (XML) + Breathe.

struct AppendPreparedJpegJumbfOptions
#include <metadata_transfer.h>

Options for explicit raw JUMBF append into a prepared JPEG bundle.

Public Members

bool replace_existing = false

If true, remove existing prepared jpeg:app11-jumbf blocks first.

struct ApplyTimePatchOptions
#include <metadata_transfer.h>

Options for apply_time_patches.

Public Members

bool strict_width = true

If true, update value size must match slot width exactly.

bool require_slot = false

If true, each requested field must have at least one slot.

struct ApplyTimePatchResult
#include <metadata_transfer.h>

Result for apply_time_patches.

Public Members

TransferStatus status = TransferStatus::Ok
uint32_t patched_slots = 0
uint32_t skipped_slots = 0
uint32_t errors = 0
std::string message
struct BlockInfo
#include <meta_store.h>

Container-block identity used to associate Entry::origin with a source block.

Public Members

uint32_t format = 0
uint32_t container = 0
uint32_t id = 0
struct BlockSpan
#include <meta_store.h>

Public Members

uint32_t start = 0
uint32_t count = 0
struct BmffField
#include <meta_key.h>

Public Members

ByteSpan field
struct BmffField
#include <meta_key.h>

Public Members

std::string_view field
class BmffTransferEmitter
#include <metadata_transfer.h>

Backend contract for ISO-BMFF metadata item emission.

Public Functions

virtual ~BmffTransferEmitter() = default
virtual TransferStatus add_item(uint32_t item_type, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus add_mime_xmp_item(std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus add_property(uint32_t property_type, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus close_items() noexcept = 0
struct BuildExrAttributeBatchFileOptions
#include <exr_adapter.h>

File-helper options for build_exr_attribute_batch_from_file.

Public Members

PrepareTransferFileOptions prepare
ExrAdapterOptions adapter
struct BuildExrAttributeBatchFileResult
#include <exr_adapter.h>

File-helper result for build_exr_attribute_batch_from_file.

Public Members

PrepareTransferFileResult prepared
ExrAdapterResult adapter
struct BuildInfo
#include <build_info.h>

OpenMeta build information.

Values are compiled into the binary at build time.

Public Members

std::string_view version

OpenMeta version string (e.g. “0.4.0”).

std::string_view build_timestamp_utc

Build timestamp in UTC (ISO-8601), or empty if not recorded.

std::string_view build_type

Build type string (e.g. “Release”, “Debug”, “multi-config”).

std::string_view cmake_generator

CMake generator used to configure the build (e.g. “Ninja”).

std::string_view system_name

Target platform (e.g. “Linux”, “Darwin”, “Windows”).

std::string_view system_processor

Target CPU architecture (e.g. “x86_64”, “arm64”).

std::string_view cxx_compiler_id

Compiler ID (e.g. “Clang”, “GNU”, “MSVC”).

std::string_view cxx_compiler_version

Compiler version string.

std::string_view cxx_compiler

Compiler executable path, if available.

bool linkage_static = false

True if this binary was built from the static library target.

bool linkage_shared = false

True if this binary was built from the shared library target.

bool option_with_zlib = false

Whether zlib decompression was enabled at configure time.

bool option_with_brotli = false

Whether brotli decompression was enabled at configure time.

bool option_with_expat = false

Whether Expat-based XMP parsing was enabled at configure time.

bool has_zlib = false

Whether zlib support is compiled in (linked).

bool has_brotli = false

Whether brotli support is compiled in (linked).

bool has_expat = false

Whether Expat support is compiled in (linked).

struct BuildPreparedC2paBindingResult
#include <metadata_transfer.h>

Result for materializing the exact content-binding byte stream.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t written = 0
uint32_t errors = 0
std::string message
class ByteArena
#include <byte_arena.h>

Append-only storage for bytes and strings.

Note

ByteSpan values remain meaningful as long as the arena content is not cleared. However, any pointer/span returned by span() may be invalidated by subsequent arena growth (vector reallocation). Do not retain the returned span across arena mutations.

Public Functions

ByteArena() = default
void clear() noexcept

Discards all stored bytes.

void reserve(size_t size_bytes)

Reserves at least size_bytes capacity (may allocate).

ByteSpan append(std::span<const std::byte> bytes)

Appends raw bytes and returns a ByteSpan to the stored copy. Returns an empty span if the payload would exceed ByteSpan limits. Source bytes may alias the current arena buffer.

ByteSpan append_string(std::string_view text)

Appends the raw bytes of text (no terminator) and returns a span. Returns an empty span if the payload would exceed ByteSpan limits.

ByteSpan allocate(uint32_t size_bytes, uint32_t alignment)

Allocates size_bytes with alignment and returns the written span. Returns an empty span if the allocation cannot be represented.

std::span<const std::byte> bytes() const noexcept

Returns a view of the full buffer.

std::span<std::byte> bytes_mut() noexcept

Returns a mutable view of the full buffer.

std::span<const std::byte> span(ByteSpan view) const noexcept

Returns a view for view, or an empty span if out of range.

std::span<std::byte> span_mut(ByteSpan view) noexcept

Returns a mutable view for view, or an empty span if out of range.

Private Members

std::vector<std::byte> buffer_
struct ByteSpan
#include <byte_arena.h>

A span (offset,size) into a ByteArena buffer.

Public Members

uint32_t offset = 0
uint32_t size = 0
struct CcmField
#include <ccm_query.h>

One normalized CCM/white-balance/calibration field.

Public Members

std::string name

Canonical field name (e.g. ColorMatrix1).

std::string ifd

Source EXIF IFD token (e.g. ifd0).

uint16_t tag = 0

Source EXIF tag id.

uint32_t rows = 0

Logical row count (matrix/vector layout hint).

uint32_t cols = 0

Logical column count (matrix/vector layout hint).

std::vector<double> values

Normalized numeric values (row-major for matrices).

struct CcmIssue
#include <ccm_query.h>

Validation issue emitted by collect_dng_ccm_fields.

Public Members

CcmIssueSeverity severity = CcmIssueSeverity::Warning
CcmIssueCode code = CcmIssueCode::DecodeFailed
std::string ifd
std::string name
uint16_t tag = 0
std::string message
struct CcmQueryLimits
#include <ccm_query.h>

Limits for CCM query extraction.

Public Members

uint32_t max_fields = 128U
uint32_t max_values_per_field = 256U
struct CcmQueryOptions
#include <ccm_query.h>

Options for collect_dng_ccm_fields.

Public Members

bool require_dng_context = true

Require DNG context marker (DNGVersion) in the source IFD.

bool include_reduction_matrices = true

Include ReductionMatrix* tags.

CcmValidationMode validation_mode = CcmValidationMode::DngSpecWarnings

Validation mode for DNG matrix/tag coherency diagnostics.

CcmQueryLimits limits
struct CcmQueryResult
#include <ccm_query.h>

Query result for collect_dng_ccm_fields.

Public Members

CcmQueryStatus status = CcmQueryStatus::Ok
uint32_t fields_found = 0
uint32_t fields_dropped = 0
uint32_t issues_reported = 0
struct Comment
#include <meta_key.h>

Public Members

uint8_t reserved = 0
struct Comment
#include <meta_key.h>

Public Members

uint8_t reserved = 0
struct ContainerBlockRef
#include <container_scan.h>

Reference to a metadata payload within container bytes.

All offsets are relative to the start of the full file byte buffer passed to the scanner.

Note

Scanners are intentionally shallow: they locate blocks and annotate compression/chunking but do not decompress or parse the inner formats.

Public Members

ContainerFormat format = ContainerFormat::Unknown
ContainerBlockKind kind = ContainerBlockKind::Unknown
BlockCompression compression = BlockCompression::None
BlockChunking chunking = BlockChunking::None
uint64_t outer_offset = 0
uint64_t outer_size = 0
uint64_t data_offset = 0
uint64_t data_size = 0
uint32_t id = 0
uint32_t part_index = 0
uint32_t part_count = 0
uint64_t logical_offset = 0
uint64_t logical_size = 0
uint64_t group = 0
uint32_t aux_u32 = 0
union Data
#include <meta_key.h>

Public Functions

inline Data() noexcept

Public Members

struct openmeta::MetaKey::Data::ExifTag exif_tag
struct openmeta::MetaKey::Data::Comment comment
struct openmeta::MetaKey::Data::ExrAttribute exr_attribute
struct openmeta::MetaKey::Data::IptcDataset iptc_dataset
struct openmeta::MetaKey::Data::XmpProperty xmp_property
struct openmeta::MetaKey::Data::IccHeaderField icc_header_field
struct openmeta::MetaKey::Data::IccTag icc_tag
struct openmeta::MetaKey::Data::PhotoshopIrb photoshop_irb
struct openmeta::MetaKey::Data::PhotoshopIrbField photoshop_irb_field
struct openmeta::MetaKey::Data::GeotiffKey geotiff_key
struct openmeta::MetaKey::Data::PrintImField printim_field
struct openmeta::MetaKey::Data::BmffField bmff_field
struct openmeta::MetaKey::Data::JumbfField jumbf_field
struct openmeta::MetaKey::Data::JumbfCborKey jumbf_cbor_key
struct openmeta::MetaKey::Data::PngText png_text
union Data
#include <meta_key.h>

Public Functions

inline Data() noexcept

Public Members

struct openmeta::MetaKeyView::Data::ExifTag exif_tag
struct openmeta::MetaKeyView::Data::Comment comment
struct openmeta::MetaKeyView::Data::ExrAttribute exr_attribute
struct openmeta::MetaKeyView::Data::IptcDataset iptc_dataset
struct openmeta::MetaKeyView::Data::XmpProperty xmp_property
struct openmeta::MetaKeyView::Data::IccHeaderField icc_header_field
struct openmeta::MetaKeyView::Data::IccTag icc_tag
struct openmeta::MetaKeyView::Data::PhotoshopIrb photoshop_irb
struct openmeta::MetaKeyView::Data::PhotoshopIrbField photoshop_irb_field
struct openmeta::MetaKeyView::Data::GeotiffKey geotiff_key
struct openmeta::MetaKeyView::Data::PrintImField printim_field
struct openmeta::MetaKeyView::Data::BmffField bmff_field
struct openmeta::MetaKeyView::Data::JumbfField jumbf_field
struct openmeta::MetaKeyView::Data::JumbfCborKey jumbf_cbor_key
struct openmeta::MetaKeyView::Data::PngText png_text
union Data
#include <meta_value.h>

Public Functions

inline Data() noexcept

Public Members

uint64_t u64
int64_t i64
uint32_t f32_bits

Raw IEEE-754 bits for MetaElementType::F32.

uint64_t f64_bits

Raw IEEE-754 bits for MetaElementType::F64.

URational ur
SRational sr
ByteSpan span
struct EditOp
#include <meta_edit.h>

A single edit operation recorded by MetaEdit.

Public Members

EditOpKind kind = EditOpKind::AddEntry
EntryId target = kInvalidEntryId
Entry entry
MetaValue value
struct EmittedBmffItemSummary
#include <metadata_transfer.h>

One emitted ISO-BMFF metadata item summary entry.

Public Members

uint32_t item_type = 0U
uint32_t count = 0U
uint64_t bytes = 0U
bool mime_xmp = false
struct EmittedBmffPropertySummary
#include <metadata_transfer.h>

One emitted ISO-BMFF metadata property summary entry.

Public Members

uint32_t property_type = 0U
uint32_t property_subtype = 0U
uint32_t count = 0U
uint64_t bytes = 0U
struct EmittedExrAttributeSummary
#include <metadata_transfer.h>

One emitted EXR attribute summary entry.

Public Members

std::string name
std::string type_name
uint32_t count = 0
uint64_t bytes = 0
struct EmittedJp2BoxSummary
#include <metadata_transfer.h>

One emitted JP2 box summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}
uint32_t count = 0
uint64_t bytes = 0
struct EmittedJpegMarkerSummary
#include <metadata_transfer.h>

One emitted JPEG marker summary entry.

Public Members

uint8_t marker = 0
uint32_t count = 0
uint64_t bytes = 0
struct EmittedJxlBoxSummary
#include <metadata_transfer.h>

One emitted JPEG XL box summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}
uint32_t count = 0
uint64_t bytes = 0
struct EmittedPngChunkSummary
#include <metadata_transfer.h>

One emitted PNG chunk summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}
uint32_t count = 0
uint64_t bytes = 0
struct EmittedTiffTagSummary
#include <metadata_transfer.h>

One emitted TIFF tag summary entry.

Public Members

uint16_t tag = 0
uint32_t count = 0
uint64_t bytes = 0
struct EmittedWebpChunkSummary
#include <metadata_transfer.h>

One emitted WebP chunk summary entry.

Public Members

std::array<char, 4> type = {'\0', '\0', '\0', '\0'}
uint32_t count = 0
uint64_t bytes = 0
struct EmitTransferOptions
#include <metadata_transfer.h>

Emission options shared by backend emit entry points.

Public Members

bool skip_empty_payloads = true
bool stop_on_error = true
struct EmitTransferResult
#include <metadata_transfer.h>

Result details for bundle emission.

Public Members

TransferStatus status = TransferStatus::Ok
EmitTransferCode code = EmitTransferCode::None
uint32_t emitted = 0
uint32_t skipped = 0
uint32_t errors = 0
uint32_t failed_block_index = 0xFFFFFFFFU
std::string message
struct Entry
#include <meta_store.h>

A single metadata entry (key/value) with provenance.

Note

Duplicate keys are allowed and preserved.

Public Members

MetaKey key
MetaValue value
Origin origin
EntryFlags flags = EntryFlags::None
struct ExecutePreparedTransferFileOptions
#include <metadata_transfer.h>

Options for execute_prepared_transfer_file.

Public Members

PrepareTransferFileOptions prepare
ExecutePreparedTransferOptions execute
std::string edit_target_path
std::string xmp_sidecar_base_path
XmpWritebackMode xmp_writeback_mode = XmpWritebackMode::EmbeddedOnly
XmpDestinationEmbeddedMode xmp_destination_embedded_mode = XmpDestinationEmbeddedMode::PreserveExisting
XmpDestinationSidecarMode xmp_destination_sidecar_mode = XmpDestinationSidecarMode::PreserveExisting
bool c2pa_stage_requested = false
PreparedTransferC2paSignerInput c2pa_signer_input
bool c2pa_signed_package_provided = false
PreparedTransferC2paSignedPackage c2pa_signed_package
struct ExecutePreparedTransferFileResult
#include <metadata_transfer.h>

Result for execute_prepared_transfer_file.

Public Members

PrepareTransferFileResult prepared
ExecutePreparedTransferResult execute
bool xmp_sidecar_requested = false
TransferStatus xmp_sidecar_status = TransferStatus::Unsupported
std::string xmp_sidecar_message
std::string xmp_sidecar_path
std::vector<std::byte> xmp_sidecar_output
bool xmp_sidecar_cleanup_requested = false
TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported
std::string xmp_sidecar_cleanup_message
std::string xmp_sidecar_cleanup_path
struct ExecutePreparedTransferOptions
#include <metadata_transfer.h>

Options for execute_prepared_transfer.

Public Members

std::vector<TransferTimePatchInput> time_patches
ApplyTimePatchOptions time_patch
bool time_patch_auto_nul = true
EmitTransferOptions emit
uint32_t emit_repeat = 1
TransferByteWriter *emit_output_writer = nullptr
bool edit_requested = false
bool edit_apply = false
TransferByteWriter *edit_output_writer = nullptr
bool strip_existing_xmp = false
PlanJpegEditOptions jpeg_edit
PlanTiffEditOptions tiff_edit
struct ExecutePreparedTransferResult
#include <metadata_transfer.h>

Result for execute_prepared_transfer.

Public Members

bool c2pa_stage_requested = false
ValidatePreparedC2paSignResult c2pa_stage_validation
EmitTransferResult c2pa_stage
ApplyTimePatchResult time_patch
EmitTransferResult compile
uint32_t compiled_ops = 0
EmitTransferResult emit
std::vector<EmittedJpegMarkerSummary> marker_summary
std::vector<EmittedTiffTagSummary> tiff_tag_summary
std::vector<EmittedJxlBoxSummary> jxl_box_summary
std::vector<EmittedWebpChunkSummary> webp_chunk_summary
std::vector<EmittedPngChunkSummary> png_chunk_summary
std::vector<EmittedJp2BoxSummary> jp2_box_summary
std::vector<EmittedExrAttributeSummary> exr_attribute_summary
std::vector<EmittedBmffItemSummary> bmff_item_summary
std::vector<EmittedBmffPropertySummary> bmff_property_summary
bool tiff_commit = false
uint64_t emit_output_size = 0
bool strip_existing_xmp = false
bool edit_requested = false
TransferStatus edit_plan_status = TransferStatus::Unsupported
std::string edit_plan_message
JpegEditPlan jpeg_edit_plan
TiffEditPlan tiff_edit_plan
EmitTransferResult edit_apply
uint64_t edit_input_size = 0
uint64_t edit_output_size = 0
std::vector<std::byte> edited_output
struct ExifDecodeLimits
#include <exif_tiff_decode.h>

Resource limits applied during decode to bound hostile inputs.

Public Members

uint32_t max_ifds = 128
uint32_t max_entries_per_ifd = 4096
uint32_t max_total_entries = 200000
uint64_t max_value_bytes = 16ULL * 1024ULL * 1024ULL
struct ExifDecodeOptions
#include <exif_tiff_decode.h>

Decoder options for decode_exif_tiff.

Public Members

bool include_pointer_tags = true

If true, pointer tags are preserved as entries in addition to being followed.

bool decode_printim = true

If true, decode EXIF PrintIM (0xC4A5) into MetaKeyKind::PrintImField.

bool decode_geotiff = true

If true, decode GeoTIFF GeoKeyDirectoryTag (0x87AF) into MetaKeyKind::GeotiffKey entries (best-effort).

bool decode_makernote = false

If true, attempt best-effort MakerNote decoding (vendor blocks).

bool decode_embedded_containers = false

If true, attempt best-effort decoding of embedded containers stored as EXIF tag byte blobs (for example, Panasonic RW2 JpgFromRaw).

ExifIfdTokenPolicy tokens

IFD token naming policy (affects emitted EXIF key IFD strings).

ExifDecodeLimits limits
struct ExifDecodeResult
#include <exif_tiff_decode.h>

Aggregated decode statistics.

Public Members

ExifDecodeStatus status = ExifDecodeStatus::Ok
uint32_t ifds_written = 0
uint32_t ifds_needed = 0
uint32_t entries_decoded = 0
ExifLimitReason limit_reason = ExifLimitReason::None
uint64_t limit_ifd_offset = 0
uint16_t limit_tag = 0
struct ExifIfdRef
#include <exif_tiff_decode.h>

Reference to a decoded IFD within the input TIFF byte stream.

Public Members

ExifIfdKind kind = ExifIfdKind::Ifd
uint32_t index = 0
uint64_t offset = 0
BlockId block = kInvalidBlockId
struct ExifIfdTokenPolicy
#include <exif_tiff_decode.h>

Token strings used to label decoded IFD blocks.

Public Members

std::string_view ifd_prefix = "ifd"

Prefix used for generic IFD chain blocks (e.g. ifd0, ifd1).

std::string_view subifd_prefix = "subifd"

Prefix used for SubIFD blocks (e.g. subifd0, subifd1).

std::string_view exif_ifd_token = "exififd"

Token used for the EXIF sub-IFD pointer directory.

std::string_view gps_ifd_token = "gpsifd"

Token used for the GPS sub-IFD pointer directory.

std::string_view interop_ifd_token = "interopifd"

Token used for the Interop sub-IFD pointer directory.

struct ExifTag
#include <meta_key.h>

Public Members

ByteSpan ifd
uint16_t tag = 0
struct ExifTag
#include <meta_key.h>

Public Members

std::string_view ifd
uint16_t tag = 0
struct ExportItem
#include <interop_export.h>

A single exported metadata item.

The name view is valid only for the duration of MetadataSink::on_item.

Public Members

std::string_view name
const Entry *entry = nullptr
const Origin *origin = nullptr
EntryFlags flags = EntryFlags::None
struct ExportOptions
#include <interop_export.h>

Export controls for visit_metadata.

Public Members

ExportNameStyle style = ExportNameStyle::Canonical
ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias
bool include_origin = false
bool include_flags = false
bool include_makernotes = true
struct ExrAdapterAttribute
#include <exr_adapter.h>

One owned EXR-native attribute payload.

Public Members

uint32_t part_index = 0
std::string name
std::string type_name
std::vector<std::byte> value
bool is_opaque = false
struct ExrAdapterBatch
#include <exr_adapter.h>

One owned EXR-native attribute batch.

Public Members

uint32_t encoding_version = kExrCanonicalEncodingVersion
ExrAdapterOptions options
std::vector<ExrAdapterAttribute> attributes
struct ExrAdapterOptions
#include <exr_adapter.h>

Options for EXR attribute batch export.

Public Members

bool include_opaque = true

Include opaque/custom EXR attributes when type name is preserved.

bool fail_on_unencodable = true

If false, unencodable entries are skipped instead of failing.

struct ExrAdapterPartSpan
#include <exr_adapter.h>

One contiguous per-part span inside ExrAdapterBatch::attributes.

Public Members

uint32_t part_index = 0
uint32_t first_attribute = 0
uint32_t attribute_count = 0
struct ExrAdapterPartView
#include <exr_adapter.h>

One zero-copy per-part attribute view over ExrAdapterBatch.

Public Members

uint32_t part_index = 0
std::span<const ExrAdapterAttribute> attributes
struct ExrAdapterReplayCallbacks
#include <exr_adapter.h>

Replay callbacks for replay_exr_attribute_batch.

Public Members

ExrAdapterStatus (*begin_part)(void *user, uint32_t part_index, uint32_t attribute_count) noexcept = nullptr
ExrAdapterStatus (*emit_attribute)(void *user, uint32_t part_index, const ExrAdapterAttribute *attribute) noexcept = nullptr
ExrAdapterStatus (*end_part)(void *user, uint32_t part_index) noexcept = nullptr
void *user = nullptr
struct ExrAdapterReplayResult
#include <exr_adapter.h>

Result for EXR adapter batch replay.

Public Members

ExrAdapterStatus status = ExrAdapterStatus::Ok
uint32_t replayed_parts = 0
uint32_t replayed_attributes = 0
uint32_t failed_part_index = std::numeric_limits<uint32_t>::max()
uint32_t failed_attribute_index = std::numeric_limits<uint32_t>::max()
std::string message
struct ExrAdapterResult
#include <exr_adapter.h>

Result for EXR adapter batch export.

Public Members

ExrAdapterStatus status = ExrAdapterStatus::Ok
uint32_t exported = 0
uint32_t skipped = 0
uint32_t errors = 0
EntryId failed_entry = kInvalidEntryId
std::string message
struct ExrAttribute
#include <meta_key.h>

Public Members

uint32_t part_index = 0
ByteSpan name
struct ExrAttribute
#include <meta_key.h>

Public Members

uint32_t part_index = 0
std::string_view name
struct ExrDecodeLimits
#include <exr_decode.h>

Resource limits applied during EXR header decode.

Public Members

uint32_t max_parts = 64
uint32_t max_attributes_per_part = 1U << 16
uint32_t max_attributes = 200000
uint32_t max_name_bytes = 1024
uint32_t max_type_name_bytes = 1024
uint32_t max_attribute_bytes = 8U * 1024U * 1024U
uint64_t max_total_attribute_bytes = 64ULL * 1024ULL * 1024ULL
struct ExrDecodeOptions
#include <exr_decode.h>

Decoder options for decode_exr_header.

Public Members

bool decode_known_types = true

If true, decodes known scalar/vector EXR attribute types into typed values. Unknown and complex attribute types are always preserved as raw bytes.

bool preserve_unknown_type_name = true

If true, preserves original EXR type name for unknown/custom attrs in Origin::wire_type_name.

ExrDecodeLimits limits
struct ExrDecodeResult
#include <exr_decode.h>

Public Members

ExrDecodeStatus status = ExrDecodeStatus::Ok
uint32_t parts_decoded = 0
uint32_t entries_decoded = 0
struct ExrPreparedAttribute
#include <metadata_transfer.h>

EXR attribute payload for transfer emission.

Public Members

std::string name
std::string type_name
std::vector<std::byte> value
bool is_opaque = false
struct ExrPreparedAttributeView
#include <metadata_transfer.h>

Zero-copy EXR attribute view for prepared transfer emission.

Public Members

std::string_view name
std::string_view type_name
std::span<const std::byte> value
bool is_opaque = false
class ExrTransferEmitter
#include <metadata_transfer.h>

Backend contract for OpenEXR header attribute emission.

Public Functions

virtual ~ExrTransferEmitter() = default
virtual TransferStatus set_attribute(const ExrPreparedAttribute &attr) noexcept = 0
inline virtual TransferStatus set_attribute_view(const ExrPreparedAttributeView &attr) noexcept
struct GeotiffKey
#include <meta_key.h>

Public Members

uint16_t key_id = 0
struct GeotiffKey
#include <meta_key.h>

Public Members

uint16_t key_id = 0
struct IccDecodeLimits
#include <icc_decode.h>

Resource limits applied during ICC decode to bound hostile inputs.

Public Members

uint32_t max_tags = 1U << 16
uint32_t max_tag_bytes = 32U * 1024U * 1024U
uint64_t max_total_tag_bytes = 64ULL * 1024ULL * 1024ULL
struct IccDecodeOptions
#include <icc_decode.h>

Decoder options for decode_icc_profile.

Public Members

IccDecodeLimits limits
struct IccDecodeResult
#include <icc_decode.h>

Public Members

IccDecodeStatus status = IccDecodeStatus::Ok
uint32_t entries_decoded = 0
struct IccHeaderField
#include <meta_key.h>

Public Members

uint32_t offset = 0
struct IccHeaderField
#include <meta_key.h>

Public Members

uint32_t offset = 0
struct IccTag
#include <meta_key.h>

Public Members

uint32_t signature = 0
struct IccTag
#include <meta_key.h>

Public Members

uint32_t signature = 0
struct IccTagInterpretation
#include <icc_interpret.h>

Best-effort decoded view of an ICC tag payload.

Public Members

uint32_t signature = 0

ICC tag signature (from tag table).

std::string_view name

Tag display name for signature, when known.

std::string type

ICC tag type signature as text/fourcc (for example desc, XYZ, curv).

std::string text

Decoded text (for text-like tags).

std::vector<double> values

Decoded numeric values (for XYZ/curve/parametric forms).

uint32_t rows = 0

Optional layout hint for matrix-like values.

uint32_t cols = 0

Optional layout hint for matrix-like values.

struct IccTagInterpretLimits
#include <icc_interpret.h>

Limits for ICC tag interpretation helpers.

Public Members

uint32_t max_values = 512U
uint32_t max_text_bytes = 4096U
struct IccTagInterpretOptions
#include <icc_interpret.h>

Options for interpret_icc_tag.

Public Members

IccTagInterpretLimits limits
struct InteropSafetyError
#include <interop_export.h>

Structured error details returned by strict safe interop exports.

Public Members

InteropSafetyReason reason = InteropSafetyReason::None
std::string field_name
std::string key_path
std::string message
struct IptcDataset
#include <meta_key.h>

Public Members

uint16_t record = 0
uint16_t dataset = 0
struct IptcDataset
#include <meta_key.h>

Public Members

uint16_t record = 0
uint16_t dataset = 0
struct IptcIimDecodeLimits
#include <iptc_iim_decode.h>

Resource limits applied during IPTC-IIM decode to bound hostile inputs.

Public Members

uint32_t max_datasets = 200000
uint32_t max_dataset_bytes = 8U * 1024U * 1024U
uint64_t max_total_bytes = 64ULL * 1024ULL * 1024ULL
struct IptcIimDecodeOptions
#include <iptc_iim_decode.h>

Decoder options for decode_iptc_iim.

Public Members

IptcIimDecodeLimits limits
struct IptcIimDecodeResult
#include <iptc_iim_decode.h>

Public Members

IptcIimDecodeStatus status = IptcIimDecodeStatus::Ok
uint32_t entries_decoded = 0
class Jp2TransferEmitter
#include <metadata_transfer.h>

Backend contract for JP2 metadata box emission.

Public Functions

virtual ~Jp2TransferEmitter() = default
virtual TransferStatus add_box(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus close_boxes() noexcept = 0
struct JpegEditPlan
#include <metadata_transfer.h>

Planned JPEG edit summary (draft API).

Public Members

TransferStatus status = TransferStatus::Ok
JpegEditMode requested_mode = JpegEditMode::Auto
JpegEditMode selected_mode = JpegEditMode::MetadataRewrite
bool in_place_possible = false
bool strip_existing_xmp = false
uint32_t emitted_segments = 0
uint32_t replaced_segments = 0
uint32_t appended_segments = 0
uint32_t removed_existing_segments = 0
uint32_t removed_existing_jumbf_segments = 0
uint32_t removed_existing_c2pa_segments = 0
uint64_t input_size = 0
uint64_t output_size = 0
uint64_t leading_scan_end = 0
std::string message
class JpegTransferEmitter
#include <metadata_transfer.h>

Backend contract for JPEG metadata emission.

Public Functions

virtual ~JpegTransferEmitter() = default
virtual TransferStatus write_app_marker(uint8_t marker_code, std::span<const std::byte> payload) noexcept = 0
struct JumbfCborKey
#include <meta_key.h>

Public Members

ByteSpan key
struct JumbfCborKey
#include <meta_key.h>

Public Members

std::string_view key
struct JumbfDecodeLimits
#include <jumbf_decode.h>

Resource limits for JUMBF/C2PA decode.

Public Members

uint64_t max_input_bytes = 64ULL * 1024ULL * 1024ULL

Maximum input bytes to accept (0 = unlimited).

uint32_t max_box_depth = 32

Maximum BMFF box depth. 0 is normalized to a safe default (32).

uint32_t max_boxes = 1U << 16

Maximum BMFF boxes to traverse. 0 is normalized to a safe default (65536).

uint32_t max_entries = 200000

Maximum emitted entries. 0 is normalized to a safe default (200000).

uint32_t max_cbor_depth = 64

Maximum CBOR recursion depth. 0 is normalized to a safe default (64).

uint32_t max_cbor_items = 200000

Maximum CBOR items to parse. 0 is normalized to a safe default (200000).

uint32_t max_cbor_key_bytes = 1024

Maximum CBOR string key bytes.

uint32_t max_cbor_text_bytes = 8U * 1024U * 1024U

Maximum CBOR text value bytes.

uint32_t max_cbor_bytes_bytes = 8U * 1024U * 1024U

Maximum CBOR byte-string value bytes.

struct JumbfDecodeOptions
#include <jumbf_decode.h>

Decoder options for decode_jumbf_payload.

Public Members

bool decode_cbor = true

If true, traverse cbor boxes and emit decoded CBOR key/value entries.

bool detect_c2pa = true

If true, emit a c2pa.detected marker when C2PA-like payload is seen.

bool verify_c2pa = false

If true, request draft C2PA verification scaffold fields.

C2paVerifyBackend verify_backend = C2paVerifyBackend::Auto

Verification backend preference (used when verify_c2pa is true).

bool verify_require_trusted_chain = false

If true, require the certificate chain to validate against the system trust store. Untrusted or missing chains fail verification even when the signature matches.

bool verify_require_resolved_references = false

If true, explicit claim references must resolve deterministically: unresolved or ambiguous explicit-reference signatures fail verification.

JumbfDecodeLimits limits
struct JumbfDecodeResult
#include <jumbf_decode.h>

JUMBF decode result summary.

Public Members

JumbfDecodeStatus status = JumbfDecodeStatus::Unsupported
uint32_t boxes_decoded = 0
uint32_t cbor_items = 0
uint32_t entries_decoded = 0
C2paVerifyStatus verify_status = C2paVerifyStatus::NotRequested
C2paVerifyBackend verify_backend_selected = C2paVerifyBackend::None
struct JumbfField
#include <meta_key.h>

Public Members

ByteSpan field
struct JumbfField
#include <meta_key.h>

Public Members

std::string_view field
struct JumbfStructureEstimate
#include <jumbf_decode.h>

Preflight structural estimate for a JUMBF/C2PA payload.

This is a scan-only estimate: it does not emit metadata entries.

Public Members

JumbfDecodeStatus status = JumbfDecodeStatus::Unsupported
uint32_t boxes_scanned = 0
uint32_t max_box_depth = 0
uint32_t cbor_payloads = 0
uint32_t cbor_items = 0
uint32_t max_cbor_depth = 0
class JxlTransferEmitter
#include <metadata_transfer.h>

Backend contract for JPEG XL metadata box emission.

Public Functions

virtual ~JxlTransferEmitter() = default
virtual TransferStatus set_icc_profile(std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus add_box(std::array<char, 4> type, std::span<const std::byte> payload, bool compress) noexcept = 0
virtual TransferStatus close_boxes() noexcept = 0
struct KeySpan
#include <meta_store.h>

Public Members

uint32_t start = 0
uint32_t count = 0
EntryId repr = kInvalidEntryId
class MappedFile
#include <mapped_file.h>

Read-only, whole-file memory mapping.

This is a utility used by tools/bindings to avoid copying multi-GB files into memory while still exposing a std::span<const std::byte> view that OpenMeta’s decoders can operate on.

Public Functions

MappedFile() noexcept
~MappedFile() noexcept
MappedFile(const MappedFile&) = delete
MappedFile &operator=(const MappedFile&) = delete
MappedFile(MappedFile &&other) noexcept
MappedFile &operator=(MappedFile &&other) noexcept
MappedFileStatus open(const char *path, uint64_t max_file_bytes = 0) noexcept

Opens and maps path (read-only). max_file_bytes is a hard cap (0 = unlimited).

void close() noexcept

Unmaps/closes the file (idempotent).

bool is_open() const noexcept
uint64_t size() const noexcept
std::span<const std::byte> bytes() const noexcept

Private Members

int fd_ = -1
const std::byte *data_ = nullptr
uint64_t size_ = 0
class MetadataSink
#include <interop_export.h>

Public Functions

virtual ~MetadataSink() = default
virtual void on_item(const ExportItem &item) noexcept = 0
class MetaEdit
#include <meta_edit.h>

A batch of metadata edits to apply to a MetaStore.

Designed for multi-threaded production via per-thread edit buffers: build edits without mutating the base store, then apply with commit.

New keys/values that require storage use this edit’s ByteArena.

Public Functions

MetaEdit() = default
ByteArena &arena() noexcept
const ByteArena &arena() const noexcept
void reserve_ops(size_t count)

Reserves space for count operations (may allocate).

void add_entry(const Entry &entry)

Appends a new entry.

void set_value(EntryId target, const MetaValue &value)

Updates the value of an existing entry id.

void tombstone(EntryId target)

Marks an entry as deleted (tombstone).

std::span<const EditOp> ops() const noexcept

Private Members

ByteArena arena_
std::vector<EditOp> ops_
struct MetaKey
#include <meta_key.h>

An owned metadata key.

Uses ByteSpan fields for string-like components so keys can be stored compactly in a ByteArena (e.g. IFD token, XMP schema namespace).

Public Members

MetaKeyKind kind = MetaKeyKind::ExifTag
union openmeta::MetaKey::Data data
struct MetaKeyView
#include <meta_key.h>

A borrowed metadata key view.

Intended for lookups and comparisons without allocating/copying strings.

Public Members

MetaKeyKind kind = MetaKeyKind::ExifTag
union openmeta::MetaKeyView::Data data
class MetaStore
#include <meta_store.h>

Stores decoded metadata entries grouped into blocks.

Lifecycle:

  • Build phase: call add_block and add_entry (not thread-safe).

  • Finalize: call finalize to build lookup indices; treat as read-only.

Indices:

Public Functions

MetaStore() = default
BlockId add_block(const BlockInfo &info)

Adds a new block and returns its id.

EntryId add_entry(const Entry &entry)

Appends an entry and returns its id.

ByteArena &arena() noexcept
const ByteArena &arena() const noexcept
void finalize()

Builds lookup indices and marks the store as finalized.

void rehash()

Rebuilds indices after an edit pipeline (invalidates previous spans).

uint32_t block_count() const noexcept
const BlockInfo &block_info(BlockId id) const noexcept
std::span<const Entry> entries() const noexcept
const Entry &entry(EntryId id) const noexcept
std::span<const EntryId> entries_in_block(BlockId block) const noexcept

Returns all entries in block, ordered by Origin::order_in_block.

std::span<const EntryId> find_all(const MetaKeyView &key) const noexcept

Returns all entry ids matching key (excluding tombstones).

Private Functions

void rebuild_block_index()
void rebuild_key_index()
void clear_indices() noexcept

Private Members

ByteArena arena_
std::vector<Entry> entries_
std::vector<BlockInfo> blocks_
std::vector<EntryId> entries_by_block_
std::vector<BlockSpan> block_spans_
std::vector<EntryId> entries_by_key_
std::vector<KeySpan> key_spans_
bool finalized_ = false

Friends

friend MetaStore commit(const MetaStore &base, std::span<const MetaEdit> edits)

Applies edits to base and returns a new MetaStore snapshot.

friend MetaStore compact(const MetaStore &base)

Compacts a store by removing tombstones and rewriting indices.

struct MetaValue
#include <meta_value.h>

A typed metadata value.

Storage rules:

  • Scalar values are stored inline in MetaValue::data.

  • Array/Bytes/Text values store their payload in MetaValue::data.span (a ByteSpan into a ByteArena). Text payload is not nul-terminated.

The count field is:

  • 1 for scalars

  • number of elements for arrays

  • number of bytes for bytes/text

Public Members

MetaValueKind kind = MetaValueKind::Empty
MetaElementType elem_type = MetaElementType::U8
TextEncoding text_encoding = TextEncoding::Unknown
uint32_t count = 0
union openmeta::MetaValue::Data data
struct OcioAdapterOptions
#include <ocio_adapter.h>

Options for build_ocio_metadata_tree.

Public Functions

inline OcioAdapterOptions() noexcept

Public Members

ExportOptions export_options
uint32_t max_value_bytes = 1024
bool include_empty = false
bool include_normalized_ccm = true

Append derived normalized DNG CCM fields under dngnorm:*.

struct OcioAdapterRequest
#include <ocio_adapter.h>

Stable flat request for OCIO adapter export.

Public Members

ExportNameStyle style = ExportNameStyle::XmpPortable
ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias
bool include_makernotes = false
bool include_origin = false
bool include_flags = false
uint32_t max_value_bytes = 1024
bool include_empty = false
bool include_normalized_ccm = true
struct OcioMetadataNode
#include <ocio_adapter.h>

Minimal tree node similar to OCIO FormatMetadata composition.

Public Members

std::string name
std::string value
std::vector<OcioMetadataNode> children
struct OiioAdapterOptions
#include <oiio_adapter.h>

Options for collect_oiio_attributes.

Public Functions

inline OiioAdapterOptions() noexcept

Public Members

ExportOptions export_options
uint32_t max_value_bytes = 1024
bool include_empty = false
bool include_normalized_ccm = true

Append derived normalized DNG CCM fields (e.g. DNGNorm:*) to typed exports.

struct OiioAdapterRequest
#include <oiio_adapter.h>

Stable flat request for OIIO adapter export.

Public Members

ExportNamePolicy name_policy = ExportNamePolicy::ExifToolAlias
bool include_makernotes = true
bool include_origin = false
bool include_flags = false
uint32_t max_value_bytes = 1024
bool include_empty = false
bool include_normalized_ccm = true
struct OiioAttribute
#include <oiio_adapter.h>

Flattened metadata attribute used by the OIIO adapter.

Public Members

std::string name
std::string value
struct OiioTransferPackageReplayCallbacks
#include <oiio_adapter.h>

Replay callbacks for replay_oiio_transfer_package_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t chunk_count) noexcept = nullptr
TransferStatus (*emit_chunk)(void *user, const OiioTransferPackageView *view) noexcept = nullptr
TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr
void *user = nullptr
struct OiioTransferPackageReplayResult
#include <oiio_adapter.h>

Result for OIIO package-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok
EmitTransferCode code = EmitTransferCode::None
uint32_t replayed = 0
uint32_t failed_chunk_index = std::numeric_limits<uint32_t>::max()
std::string message
struct OiioTransferPackageView
#include <oiio_adapter.h>

One zero-copy packaged transfer view for OIIO-style hosts.

Public Members

OiioTransferPayloadKind semantic_kind = OiioTransferPayloadKind::Unknown
std::string_view semantic_name
std::string_view route
TransferPackageChunkKind package_kind = TransferPackageChunkKind::SourceRange
uint64_t output_offset = 0
uint8_t jpeg_marker_code = 0U
std::span<const std::byte> bytes
struct OiioTransferPayload
#include <oiio_adapter.h>

One owned prepared transfer payload for OIIO-style hosts.

Public Members

OiioTransferPayloadKind semantic_kind = OiioTransferPayloadKind::Unknown
std::string semantic_name
std::string route
PreparedTransferAdapterOp op
std::vector<std::byte> payload
struct OiioTransferPayloadBatch
#include <oiio_adapter.h>

One owned OIIO-facing transfer payload batch.

Public Members

uint32_t contract_version = 0
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
EmitTransferOptions emit
std::vector<OiioTransferPayload> payloads
struct OiioTransferPayloadReplayCallbacks
#include <oiio_adapter.h>

Replay callbacks for replay_oiio_transfer_payload_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t payload_count) noexcept = nullptr
TransferStatus (*emit_payload)(void *user, const OiioTransferPayloadView *view) noexcept = nullptr
TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr
void *user = nullptr
struct OiioTransferPayloadReplayResult
#include <oiio_adapter.h>

Result for OIIO payload-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok
EmitTransferCode code = EmitTransferCode::None
uint32_t replayed = 0
uint32_t failed_payload_index = std::numeric_limits<uint32_t>::max()
std::string message
struct OiioTransferPayloadView
#include <oiio_adapter.h>

One zero-copy prepared transfer payload view for OIIO-style hosts.

Public Members

OiioTransferPayloadKind semantic_kind = OiioTransferPayloadKind::Unknown
std::string_view semantic_name
std::string_view route
PreparedTransferAdapterOp op
std::span<const std::byte> payload
struct OiioTypedAttribute
#include <oiio_adapter.h>

Flattened typed metadata attribute used by the OIIO adapter.

Public Members

std::string name
OiioTypedValue value
struct OiioTypedValue
#include <oiio_adapter.h>

Typed metadata payload for OIIO-style adapters.

Public Members

MetaValueKind kind = MetaValueKind::Empty
MetaElementType elem_type = MetaElementType::U8
TextEncoding text_encoding = TextEncoding::Unknown
uint32_t count = 0
MetaValue::Data data
std::vector<std::byte> storage
struct OpenMetaResourcePolicy
#include <resource_policy.h>

Draft, storage-agnostic resource limits for untrusted metadata input.

This policy intentionally favors parser/output budgets over hard file-size caps, so large legitimate assets (for example RAW/EXR) can still be processed when decode limits are respected.

Public Members

uint64_t max_file_bytes = 0

Optional file mapping cap (0 = unlimited).

PayloadLimits payload_limits

Reassembly/decompression budgets.

ExifDecodeLimits exif_limits

EXIF/TIFF decode budgets.

XmpDecodeLimits xmp_limits

XMP RDF/XML decode budgets.

ExrDecodeLimits exr_limits

OpenEXR header decode budgets.

JumbfDecodeLimits jumbf_limits

JUMBF/C2PA decode budgets.

IccDecodeLimits icc_limits

ICC profile decode budgets.

IptcIimDecodeLimits iptc_limits

IPTC-IIM decode budgets.

PhotoshopIrbDecodeLimits photoshop_irb_limits

Photoshop IRB decode budgets.

PreviewScanLimits preview_scan_limits

Embedded preview discovery/extraction budgets.

uint64_t max_preview_output_bytes = 128ULL * 1024ULL * 1024ULL
XmpDumpLimits xmp_dump_limits

XMP sidecar dump budgets.

uint32_t max_decode_millis = 0

Draft future budget hooks (not enforced yet).

uint32_t max_decompression_ratio = 0
uint64_t max_total_decode_work_bytes = 0
struct Origin
#include <meta_store.h>

Where an Entry came from inside the original container.

Public Members

BlockId block = kInvalidBlockId
uint32_t order_in_block = 0
WireType wire_type
uint32_t wire_count = 0
ByteSpan wire_type_name

Optional wire type name (for formats with named types, e.g. OpenEXR custom attrs).

EntryNameContextKind name_context_kind = EntryNameContextKind::None
uint8_t name_context_variant = 0
struct PayloadLimits
#include <container_payload.h>

Resource limits applied during payload extraction to bound hostile inputs.

Public Members

uint32_t max_parts = 1U << 14
uint64_t max_output_bytes = 64ULL * 1024ULL * 1024ULL
struct PayloadOptions
#include <container_payload.h>

Options for payload extraction.

Public Members

bool decompress = true

If true, attempt to decompress payloads marked with BlockCompression.

PayloadLimits limits
struct PayloadResult
#include <container_payload.h>

Public Members

PayloadStatus status = PayloadStatus::Ok
uint64_t written = 0
uint64_t needed = 0
struct PersistPreparedTransferFileOptions
#include <metadata_transfer.h>

Options for persist_prepared_transfer_file_result.

Public Members

std::string output_path
bool write_output = true
bool overwrite_output = false
uint64_t prewritten_output_bytes = 0
bool overwrite_xmp_sidecar = false
bool remove_destination_xmp_sidecar = true
struct PersistPreparedTransferFileResult
#include <metadata_transfer.h>

Result for persist_prepared_transfer_file_result.

Public Members

TransferStatus status = TransferStatus::Unsupported
std::string message
TransferStatus output_status = TransferStatus::Unsupported
std::string output_message
std::string output_path
uint64_t output_bytes = 0
TransferStatus xmp_sidecar_status = TransferStatus::Unsupported
std::string xmp_sidecar_message
std::string xmp_sidecar_path
uint64_t xmp_sidecar_bytes = 0
TransferStatus xmp_sidecar_cleanup_status = TransferStatus::Unsupported
std::string xmp_sidecar_cleanup_message
std::string xmp_sidecar_cleanup_path
bool xmp_sidecar_cleanup_removed = false
struct PhotoshopIrb
#include <meta_key.h>

Public Members

uint16_t resource_id = 0
struct PhotoshopIrb
#include <meta_key.h>

Public Members

uint16_t resource_id = 0
struct PhotoshopIrbDecodeLimits
#include <photoshop_irb_decode.h>

Resource limits applied during IRB decode to bound hostile inputs.

Public Members

uint32_t max_resources = 1U << 16
uint64_t max_total_bytes = 64ULL * 1024ULL * 1024ULL
uint32_t max_resource_len = 32U * 1024U * 1024U
struct PhotoshopIrbDecodeOptions
#include <photoshop_irb_decode.h>

Decoder options for decode_photoshop_irb.

Public Members

bool decode_iptc_iim = true
PhotoshopIrbStringCharset string_charset = PhotoshopIrbStringCharset::Latin
PhotoshopIrbDecodeLimits limits
IptcIimDecodeOptions iptc
struct PhotoshopIrbDecodeResult
#include <photoshop_irb_decode.h>

Public Members

PhotoshopIrbDecodeStatus status = PhotoshopIrbDecodeStatus::Ok
uint32_t resources_decoded = 0
uint32_t entries_decoded = 0
uint32_t iptc_entries_decoded = 0
struct PhotoshopIrbField
#include <meta_key.h>

Public Members

uint16_t resource_id = 0
ByteSpan field
struct PhotoshopIrbField
#include <meta_key.h>

Public Members

uint16_t resource_id = 0
std::string_view field
struct PlanJpegEditOptions
#include <metadata_transfer.h>

Options for JPEG edit planning.

Public Members

JpegEditMode mode = JpegEditMode::Auto
bool require_in_place = false
bool skip_empty_payloads = true
bool strip_existing_xmp = false
struct PlanTiffEditOptions
#include <metadata_transfer.h>

Options for TIFF edit planning.

Public Members

bool require_updates = true

If true, fail planning when the bundle has no TIFF-applicable updates.

bool strip_existing_xmp = false
struct PngText
#include <meta_key.h>

Public Members

ByteSpan keyword
ByteSpan field
struct PngText
#include <meta_key.h>

Public Members

std::string_view keyword
std::string_view field
class PngTransferEmitter
#include <metadata_transfer.h>

Backend contract for PNG metadata chunk emission.

Public Functions

virtual ~PngTransferEmitter() = default
virtual TransferStatus add_chunk(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus close_chunks() noexcept = 0
struct PreparedBmffEmitOp
#include <metadata_transfer.h>

One precompiled ISO-BMFF metadata emit operation.

Public Members

PreparedBmffEmitKind kind = PreparedBmffEmitKind::Item
uint32_t block_index = 0
uint32_t item_type = 0U
uint32_t property_type = 0U
uint32_t property_subtype = 0U
struct PreparedBmffEmitPlan
#include <metadata_transfer.h>

Reusable precompiled ISO-BMFF metadata emit plan.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedBmffEmitOp> ops
struct PreparedExrEmitOp
#include <metadata_transfer.h>

One precompiled EXR emit operation (prepared block -> EXR attribute).

Public Members

uint32_t block_index = 0
struct PreparedExrEmitPlan
#include <metadata_transfer.h>

Reusable precompiled EXR emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedExrEmitOp> ops
struct PreparedJp2EmitOp
#include <metadata_transfer.h>

One precompiled JP2 emit operation (route -> JP2 box mapping).

Public Members

uint32_t block_index = 0
std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}
struct PreparedJp2EmitPlan
#include <metadata_transfer.h>

Reusable precompiled JP2 emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedJp2EmitOp> ops
struct PreparedJpegEmitOp
#include <metadata_transfer.h>

One precompiled JPEG emit operation (route -> marker mapping).

Public Members

uint32_t block_index = 0
uint8_t marker_code = 0
struct PreparedJpegEmitPlan
#include <metadata_transfer.h>

Reusable precompiled JPEG emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedJpegEmitOp> ops
struct PreparedJxlEmitOp
#include <metadata_transfer.h>

One precompiled JPEG XL emit operation (route -> backend mapping).

Public Members

PreparedJxlEmitKind kind = PreparedJxlEmitKind::Box
uint32_t block_index = 0
std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}
bool compress = false
struct PreparedJxlEmitPlan
#include <metadata_transfer.h>

Reusable precompiled JPEG XL emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedJxlEmitOp> ops
struct PreparedJxlEncoderHandoff
#include <metadata_transfer.h>

Owned JXL encoder-side handoff independent from bundle payload storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
bool has_icc_profile = false
uint32_t icc_block_index = 0xFFFFFFFFU
uint32_t box_count = 0U
uint64_t box_payload_bytes = 0U
std::vector<std::byte> icc_profile
struct PreparedJxlEncoderHandoffIoResult
#include <metadata_transfer.h>

Result for serializing or parsing persisted JXL encoder handoff data.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t bytes = 0U
uint32_t errors = 0U
std::string message
struct PreparedJxlEncoderHandoffView
#include <metadata_transfer.h>

Encoder-side handoff view for prepared JPEG XL metadata.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
bool has_icc_profile = false
uint32_t icc_block_index = 0xFFFFFFFFU
uint64_t icc_profile_bytes = 0U
std::span<const std::byte> icc_profile
uint32_t box_count = 0U
uint64_t box_payload_bytes = 0U
struct PreparedPngEmitOp
#include <metadata_transfer.h>

One precompiled PNG emit operation (route -> PNG chunk mapping).

Public Members

uint32_t block_index = 0
std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}
struct PreparedPngEmitPlan
#include <metadata_transfer.h>

Reusable precompiled PNG emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedPngEmitOp> ops
struct PreparedTiffEmitOp
#include <metadata_transfer.h>

One precompiled TIFF emit operation (route -> TIFF tag mapping).

Public Members

uint32_t block_index = 0
uint16_t tiff_tag = 0
struct PreparedTiffEmitPlan
#include <metadata_transfer.h>

Reusable precompiled TIFF emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedTiffEmitOp> ops
struct PreparedTransferAdapterOp
#include <metadata_transfer.h>

One compiled adapter-facing operation derived from a prepared bundle.

Public Members

TransferAdapterOpKind kind = TransferAdapterOpKind::JpegMarker
uint32_t block_index = 0U
uint64_t payload_size = 0U
uint64_t serialized_size = 0U
uint8_t jpeg_marker_code = 0U
uint16_t tiff_tag = 0U
std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}
std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}
uint32_t bmff_item_type = 0U
uint32_t bmff_property_type = 0U
uint32_t bmff_property_subtype = 0U
bool bmff_mime_xmp = false
bool compress = false
struct PreparedTransferAdapterView
#include <metadata_transfer.h>

One target-neutral adapter view over prepared transfer operations.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
EmitTransferOptions emit
std::vector<PreparedTransferAdapterOp> ops
struct PreparedTransferArtifactInfo
#include <metadata_transfer.h>

Common summary for one persisted transfer artifact.

Public Members

PreparedTransferArtifactKind kind = PreparedTransferArtifactKind::Unknown
bool has_contract_version = false
uint32_t contract_version = 0U
bool has_target_format = false
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
uint32_t entry_count = 0U
uint64_t payload_bytes = 0U
uint64_t binding_bytes = 0U
uint64_t signed_payload_bytes = 0U
bool has_icc_profile = false
uint32_t icc_block_index = 0xFFFFFFFFU
uint64_t icc_profile_bytes = 0U
uint64_t box_payload_bytes = 0U
std::string carrier_route
std::string manifest_label
struct PreparedTransferArtifactIoResult
#include <metadata_transfer.h>

Result for identifying and inspecting one persisted transfer artifact.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t bytes = 0U
uint32_t errors = 0U
std::string message
struct PreparedTransferBlock
#include <metadata_transfer.h>

One container-ready payload in emit order.

Public Members

TransferBlockKind kind = TransferBlockKind::Other
uint32_t order = 0
std::string route

Route token for backend dispatch, for example: jpeg:app1-exif.

std::array<char, 4> box_type = {'\0', '\0', '\0', '\0'}

Optional 4CC when route is box-based (Exif, xml, jumb…).

std::vector<std::byte> payload

Payload bytes as prepared by the transfer packager.

struct PreparedTransferBundle
#include <metadata_transfer.h>

Immutable prepared metadata transfer artifact.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
TransferProfile profile
PreparedTransferC2paRewriteRequirements c2pa_rewrite
std::vector<PreparedTransferPolicyDecision> policy_decisions
std::vector<PreparedTransferBlock> blocks
std::vector<TimePatchSlot> time_patch_map
std::vector<std::byte> generated_xmp_sidecar
struct PreparedTransferC2paHandoffPackage
#include <metadata_transfer.h>

Structured external-signer handoff package for one prepared rewrite.

Public Members

PreparedTransferC2paSignRequest request
BuildPreparedC2paBindingResult binding
std::vector<std::byte> binding_bytes
struct PreparedTransferC2paPackageIoResult
#include <metadata_transfer.h>

Result for serializing or parsing persisted C2PA transfer packages.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t bytes = 0
uint32_t errors = 0
std::string message
struct PreparedTransferC2paRewriteChunk
#include <metadata_transfer.h>

One deterministic chunk in the rewrite-without-C2PA byte stream.

Public Members

TransferC2paRewriteChunkKind kind = TransferC2paRewriteChunkKind::SourceRange
uint64_t source_offset = 0
uint64_t size = 0
uint32_t block_index = 0xFFFFFFFFU
uint8_t jpeg_marker_code = 0U
struct PreparedTransferC2paRewriteRequirements
#include <metadata_transfer.h>

Future-facing signer prerequisites for C2PA rewrite.

Public Members

TransferC2paRewriteState state = TransferC2paRewriteState::NotApplicable
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
TransferC2paSourceKind source_kind = TransferC2paSourceKind::NotApplicable
uint32_t matched_entries = 0
uint32_t existing_carrier_segments = 0
bool target_carrier_available = false
bool content_change_invalidates_existing = false
bool requires_manifest_builder = false
bool requires_content_binding = false
bool requires_certificate_chain = false
bool requires_private_key = false
bool requires_signing_time = false
uint64_t content_binding_bytes = 0
std::vector<PreparedTransferC2paRewriteChunk> content_binding_chunks
std::string message
struct PreparedTransferC2paSignedPackage
#include <metadata_transfer.h>

Persistable external-signer result package for one prepared rewrite.

Public Members

PreparedTransferC2paSignRequest request
PreparedTransferC2paSignerInput signer_input
struct PreparedTransferC2paSignerInput
#include <metadata_transfer.h>

External signer material returned for one prepared C2PA rewrite request.

Public Members

std::string signing_time
std::vector<std::byte> certificate_chain_bytes
std::string private_key_reference
std::vector<std::byte> manifest_builder_output
std::vector<std::byte> signed_c2pa_logical_payload
struct PreparedTransferC2paSignRequest
#include <metadata_transfer.h>

Derived external signer input request for prepared C2PA rewrite.

Public Members

TransferStatus status = TransferStatus::Unsupported
TransferC2paRewriteState rewrite_state = TransferC2paRewriteState::NotApplicable
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
TransferC2paSourceKind source_kind = TransferC2paSourceKind::NotApplicable
std::string carrier_route
std::string manifest_label
uint32_t existing_carrier_segments = 0
uint32_t source_range_chunks = 0
uint32_t prepared_segment_chunks = 0
uint64_t content_binding_bytes = 0
std::vector<PreparedTransferC2paRewriteChunk> content_binding_chunks
bool requires_manifest_builder = false
bool requires_content_binding = false
bool requires_certificate_chain = false
bool requires_private_key = false
bool requires_signing_time = false
std::string message
struct PreparedTransferExecutionPlan
#include <metadata_transfer.h>

Reusable compiled execution plan for high-throughput transfer workflows.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
EmitTransferOptions emit
PreparedJpegEmitPlan jpeg_emit
PreparedTiffEmitPlan tiff_emit
PreparedJxlEmitPlan jxl_emit
PreparedWebpEmitPlan webp_emit
PreparedPngEmitPlan png_emit
PreparedJp2EmitPlan jp2_emit
PreparedExrEmitPlan exr_emit
PreparedBmffEmitPlan bmff_emit
struct PreparedTransferPackageBatch
#include <metadata_transfer.h>

One owned final-output batch independent from input bytes or bundle storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
uint64_t input_size = 0
uint64_t output_size = 0
std::vector<PreparedTransferPackageBlob> chunks
struct PreparedTransferPackageBlob
#include <metadata_transfer.h>

One owned output chunk materialized from a package plan.

Public Members

TransferPackageChunkKind kind = TransferPackageChunkKind::SourceRange
uint64_t output_offset = 0
uint64_t source_offset = 0
uint32_t block_index = 0xFFFFFFFFU
uint8_t jpeg_marker_code = 0U
std::string route
std::vector<std::byte> bytes
struct PreparedTransferPackageChunk
#include <metadata_transfer.h>

One deterministic output chunk for a packaged transfer write.

Public Members

TransferPackageChunkKind kind = TransferPackageChunkKind::SourceRange
uint64_t output_offset = 0
uint64_t source_offset = 0
uint64_t size = 0
uint32_t block_index = 0xFFFFFFFFU
uint8_t jpeg_marker_code = 0U
std::vector<std::byte> inline_bytes
struct PreparedTransferPackageIoResult
#include <metadata_transfer.h>

Result for serializing or parsing persisted transfer package batches.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t bytes = 0
uint32_t errors = 0
std::string message
struct PreparedTransferPackagePlan
#include <metadata_transfer.h>

Deterministic chunk plan for a final transfer output.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
uint64_t input_size = 0
uint64_t output_size = 0
std::vector<PreparedTransferPackageChunk> chunks
struct PreparedTransferPackageReplayCallbacks
#include <metadata_transfer.h>

Replay callbacks for replay_prepared_transfer_package_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t chunk_count) noexcept = nullptr
TransferStatus (*emit_chunk)(void *user, const PreparedTransferPackageView *view) noexcept = nullptr
TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr
void *user = nullptr
struct PreparedTransferPackageReplayResult
#include <metadata_transfer.h>

Result for target-neutral package-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok
EmitTransferCode code = EmitTransferCode::None
uint32_t replayed = 0
uint32_t failed_chunk_index = 0xFFFFFFFFU
std::string message
struct PreparedTransferPackageView
#include <metadata_transfer.h>

One zero-copy semantic view over a persisted transfer package chunk.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown
std::string_view route
TransferPackageChunkKind package_kind = TransferPackageChunkKind::SourceRange
uint64_t output_offset = 0
uint8_t jpeg_marker_code = 0U
std::span<const std::byte> bytes
struct PreparedTransferPayload
#include <metadata_transfer.h>

One owned semantic payload copied from a prepared transfer bundle.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown
std::string semantic_name
std::string route
PreparedTransferAdapterOp op
std::vector<std::byte> payload
struct PreparedTransferPayloadBatch
#include <metadata_transfer.h>

One owned semantic payload batch independent from bundle payload storage.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
TransferTargetFormat target_format = TransferTargetFormat::Jpeg
EmitTransferOptions emit
std::vector<PreparedTransferPayload> payloads
struct PreparedTransferPayloadIoResult
#include <metadata_transfer.h>

Result for serializing or parsing persisted transfer payload batches.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
uint64_t bytes = 0
uint32_t errors = 0
std::string message
struct PreparedTransferPayloadReplayCallbacks
#include <metadata_transfer.h>

Replay callbacks for replay_prepared_transfer_payload_batch.

Public Members

TransferStatus (*begin_batch)(void *user, TransferTargetFormat target_format, uint32_t payload_count) noexcept = nullptr
TransferStatus (*emit_payload)(void *user, const PreparedTransferPayloadView *view) noexcept = nullptr
TransferStatus (*end_batch)(void *user, TransferTargetFormat target_format) noexcept = nullptr
void *user = nullptr
struct PreparedTransferPayloadReplayResult
#include <metadata_transfer.h>

Result for target-neutral payload-batch replay.

Public Members

TransferStatus status = TransferStatus::Ok
EmitTransferCode code = EmitTransferCode::None
uint32_t replayed = 0
uint32_t failed_payload_index = 0xFFFFFFFFU
std::string message
struct PreparedTransferPayloadView
#include <metadata_transfer.h>

One zero-copy semantic payload view over a prepared transfer bundle.

Public Members

TransferSemanticKind semantic_kind = TransferSemanticKind::Unknown
std::string_view semantic_name
std::string_view route
PreparedTransferAdapterOp op
std::span<const std::byte> payload
struct PreparedTransferPolicyDecision
#include <metadata_transfer.h>

Effective policy decision captured during bundle preparation.

Public Members

TransferPolicySubject subject = TransferPolicySubject::MakerNote
TransferPolicyAction requested = TransferPolicyAction::Keep
TransferPolicyAction effective = TransferPolicyAction::Keep
TransferPolicyReason reason = TransferPolicyReason::Default
TransferC2paMode c2pa_mode = TransferC2paMode::NotApplicable
TransferC2paSourceKind c2pa_source_kind = TransferC2paSourceKind::NotApplicable
TransferC2paPreparedOutput c2pa_prepared_output = TransferC2paPreparedOutput::NotApplicable
uint32_t matched_entries = 0
std::string message
struct PreparedWebpEmitOp
#include <metadata_transfer.h>

One precompiled WebP emit operation (route -> RIFF chunk mapping).

Public Members

uint32_t block_index = 0
std::array<char, 4> chunk_type = {'\0', '\0', '\0', '\0'}
struct PreparedWebpEmitPlan
#include <metadata_transfer.h>

Reusable precompiled WebP emit plan for a prepared transfer bundle.

Public Members

uint32_t contract_version = kMetadataTransferContractVersion
std::vector<PreparedWebpEmitOp> ops
struct PrepareTransferFileOptions
#include <metadata_transfer.h>

File-read + decode options for prepare_metadata_for_target_file.

Public Members

bool include_pointer_tags = true
bool decode_makernote = false
bool decode_embedded_containers = true
bool decompress = true
std::string xmp_existing_sidecar_base_path
XmpExistingSidecarMode xmp_existing_sidecar_mode = XmpExistingSidecarMode::Ignore
XmpExistingSidecarPrecedence xmp_existing_sidecar_precedence = XmpExistingSidecarPrecedence::SidecarWins
OpenMetaResourcePolicy policy
PrepareTransferRequest prepare
struct PrepareTransferFileResult
#include <metadata_transfer.h>

High-level file read/prepare result.

Public Members

TransferFileStatus file_status = TransferFileStatus::Ok
PrepareTransferFileCode code = PrepareTransferFileCode::None
uint64_t file_size = 0
uint32_t entry_count = 0
bool xmp_existing_sidecar_loaded = false
TransferStatus xmp_existing_sidecar_status = TransferStatus::Unsupported
std::string xmp_existing_sidecar_message
std::string xmp_existing_sidecar_path
SimpleMetaResult read
PrepareTransferResult prepare
PreparedTransferBundle bundle
struct PrepareTransferRequest
#include <metadata_transfer.h>

Request options for preparation.

Public Members

TransferTargetFormat target_format = TransferTargetFormat::Jpeg
TransferProfile profile
bool include_exif_app1 = true
bool include_xmp_app1 = true
bool include_icc_app2 = true
bool include_iptc_app13 = true
bool xmp_portable = true
bool xmp_project_exif = true
bool xmp_project_iptc = true
bool xmp_include_existing = true
XmpConflictPolicy xmp_conflict_policy = XmpConflictPolicy::CurrentBehavior
bool xmp_exiftool_gpsdatetime_alias = false
struct PrepareTransferResult
#include <metadata_transfer.h>

Result details for preparation.

Public Members

TransferStatus status = TransferStatus::Ok
PrepareTransferCode code = PrepareTransferCode::None
uint32_t warnings = 0
uint32_t errors = 0
std::string message
struct PreviewCandidate
#include <preview_extract.h>

Preview candidate discovered in a container.

Public Members

PreviewKind kind = PreviewKind::ExifJpegInterchange
ContainerFormat format = ContainerFormat::Unknown
uint32_t block_index = 0
uint16_t offset_tag = 0
uint16_t length_tag = 0
uint64_t file_offset = 0
uint64_t size = 0
bool has_jpeg_soi_signature = false
struct PreviewExtractOptions
#include <preview_extract.h>

Options for preview extraction.

Public Members

uint64_t max_output_bytes = 128ULL * 1024ULL * 1024ULL
bool require_jpeg_soi = false
struct PreviewExtractResult
#include <preview_extract.h>

Result for preview extraction.

Public Members

PreviewExtractStatus status = PreviewExtractStatus::Ok
uint64_t written = 0
uint64_t needed = 0
struct PreviewScanLimits
#include <preview_extract.h>

Limits for preview candidate discovery.

Public Members

uint32_t max_ifds = 256
uint32_t max_total_entries = 8192
uint64_t max_preview_bytes = 512ULL * 1024ULL * 1024ULL
struct PreviewScanOptions
#include <preview_extract.h>

Options for preview candidate discovery.

Public Members

bool include_exif_jpeg_interchange = true
bool include_jpg_from_raw = true
bool include_cr3_prvw_jpeg = true
bool require_jpeg_soi = false
PreviewScanLimits limits
struct PreviewScanResult
#include <preview_extract.h>

Result for preview candidate discovery.

Public Members

PreviewScanStatus status = PreviewScanStatus::Ok
uint32_t written = 0
uint32_t needed = 0
struct PrintImDecodeLimits
#include <printim_decode.h>

Resource limits for decoding a PrintIM block.

Public Members

uint32_t max_entries = 4096

Maximum number of PrintIM entries to decode.

uint64_t max_bytes = 256ULL * 1024ULL

Maximum input bytes to accept (0 = unlimited).

struct PrintImDecodeResult
#include <printim_decode.h>

PrintIM decode result summary.

Public Members

PrintImDecodeStatus status = PrintImDecodeStatus::Unsupported
uint32_t entries_decoded = 0
struct PrintImField
#include <meta_key.h>

Public Members

ByteSpan field
struct PrintImField
#include <meta_key.h>

Public Members

std::string_view field
struct ScanResult
#include <container_scan.h>

Public Members

ScanStatus status = ScanStatus::Ok
uint32_t written = 0
uint32_t needed = 0
struct SimpleMetaDecodeOptions
#include <simple_meta.h>

Full decoder option set for simple_meta_read.

Public Members

ExifDecodeOptions exif
PayloadOptions payload
XmpDecodeOptions xmp
ExrDecodeOptions exr
JumbfDecodeOptions jumbf
IccDecodeOptions icc
IptcIimDecodeOptions iptc
PhotoshopIrbDecodeOptions photoshop_irb
struct SimpleMetaResult
#include <simple_meta.h>

Public Members

ScanResult scan
PayloadResult payload
ExrDecodeResult exr
ExifDecodeResult exif
JumbfDecodeResult jumbf
XmpDecodeResult xmp
class SpanTransferByteWriter : public openmeta::TransferByteWriter
#include <metadata_transfer.h>

Fixed-buffer writer for encoder integrations with preallocated memory.

Public Functions

inline explicit SpanTransferByteWriter(std::span<std::byte> buffer) noexcept
inline virtual TransferStatus write(std::span<const std::byte> bytes) noexcept override
inline void reset() noexcept
inline size_t capacity() const noexcept
inline size_t bytes_written() const noexcept
inline size_t remaining() const noexcept
inline TransferStatus status() const noexcept
inline virtual uint64_t remaining_capacity_hint() const noexcept override
inline std::span<const std::byte> written_bytes() const noexcept

Private Members

std::span<std::byte> buffer_
size_t written_ = 0U
TransferStatus status_ = TransferStatus::Ok
struct SRational
#include <meta_value.h>

Signed rational (numerator/denominator), typically used by EXIF/TIFF.

Public Members

int32_t numer = 0
int32_t denom = 1
struct TiffEditPlan
#include <metadata_transfer.h>

Planned TIFF edit summary (draft API).

Public Members

TransferStatus status = TransferStatus::Ok
uint32_t tag_updates = 0
bool has_exif_ifd = false
bool strip_existing_xmp = false
uint64_t input_size = 0
uint64_t output_size = 0
std::string message
class TiffTransferEmitter
#include <metadata_transfer.h>

Backend contract for TIFF metadata emission.

Public Functions

virtual ~TiffTransferEmitter() = default
virtual TransferStatus set_tag_u32(uint16_t tag, uint32_t value) noexcept = 0
virtual TransferStatus set_tag_bytes(uint16_t tag, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus commit_exif_directory(uint64_t *out_ifd_offset) noexcept = 0
struct TimePatchSlot
#include <metadata_transfer.h>

One fixed-width patch location in a prepared payload block.

Public Members

TimePatchField field = TimePatchField::DateTime
uint32_t block_index = 0
uint32_t byte_offset = 0
uint16_t width = 0
struct TimePatchUpdate
#include <metadata_transfer.h>

One time patch update payload for apply_time_patches.

Public Members

TimePatchField field = TimePatchField::DateTime
std::vector<std::byte> value
struct TimePatchView
#include <metadata_transfer.h>

Non-owning time patch view for hot-path transfer execution.

Public Members

TimePatchField field = TimePatchField::DateTime
std::span<const std::byte> value
class TransferAdapterSink
#include <metadata_transfer.h>

Generic host-side sink for adapter-view transfer operations.

Public Functions

virtual ~TransferAdapterSink() = default
virtual TransferStatus emit_op(const PreparedTransferAdapterOp &op, std::span<const std::byte> payload) noexcept = 0
class TransferByteWriter
#include <metadata_transfer.h>

Streaming byte sink for edit/write transfer paths.

Subclassed by openmeta::SpanTransferByteWriter

Public Functions

virtual ~TransferByteWriter() = default
virtual TransferStatus write(std::span<const std::byte> bytes) noexcept = 0
inline virtual uint64_t remaining_capacity_hint() const noexcept
struct TransferProfile
#include <metadata_transfer.h>

Transfer policy profile for initial no-edits workflows.

Public Members

TransferPolicyAction makernote = TransferPolicyAction::Keep
TransferPolicyAction jumbf = TransferPolicyAction::Keep
TransferPolicyAction c2pa = TransferPolicyAction::Keep
bool allow_time_patch = true
struct TransferTimePatchInput
#include <metadata_transfer.h>

One high-level time patch input for transfer execution helpers.

Public Members

TimePatchField field = TimePatchField::DateTime
std::vector<std::byte> value
bool text_value = false
struct URational
#include <meta_value.h>

Unsigned rational (numerator/denominator), typically used by EXIF/TIFF.

Public Members

uint32_t numer = 0
uint32_t denom = 1
struct ValidateIssue
#include <validate.h>

One validation issue emitted by validate_file.

Public Members

ValidateIssueSeverity severity = ValidateIssueSeverity::Warning
std::string category

Domain/category (scan, exif, ccm, file, …).

std::string code

Stable issue token (malformed, limit_exceeded, …).

std::string ifd

Optional source IFD token (for CCM issues).

std::string name

Optional source field/tag name (for CCM issues).

uint16_t tag = 0

Optional source tag id (for CCM issues).

std::string message

Human-readable details.

struct ValidateOptions
#include <validate.h>

Options for validate_file.

Public Members

bool include_pointer_tags = true
bool decode_makernote = false
bool decode_printim = true
bool decompress = true
bool include_xmp_sidecar = false
bool verify_c2pa = false
C2paVerifyBackend verify_backend = C2paVerifyBackend::Auto
bool verify_require_resolved_references = false
bool warnings_as_errors = false

Treat warnings as failures in ValidateResult::failed.

CcmQueryOptions ccm

DNG/CCM query + validation options.

OpenMetaResourcePolicy policy

Resource budgets for decode/scans.

struct ValidatePreparedC2paSignResult
#include <metadata_transfer.h>

Result for validating one externally signed C2PA payload before staging.

Public Members

TransferStatus status = TransferStatus::Unsupported
EmitTransferCode code = EmitTransferCode::None
TransferC2paSignedPayloadKind payload_kind = TransferC2paSignedPayloadKind::NotApplicable
TransferC2paSemanticStatus semantic_status = TransferC2paSemanticStatus::NotChecked
uint64_t logical_payload_bytes = 0
uint64_t staged_payload_bytes = 0
uint64_t semantic_manifest_present = 0
uint64_t semantic_manifest_count = 0
uint64_t semantic_claim_generator_present = 0
uint64_t semantic_assertion_count = 0
uint64_t semantic_primary_claim_assertion_count = 0
uint64_t semantic_primary_claim_referenced_by_signature_count = 0
uint64_t semantic_primary_signature_linked_claim_count = 0
uint64_t semantic_primary_signature_reference_key_hits = 0
uint64_t semantic_primary_signature_explicit_reference_present = 0
uint64_t semantic_primary_signature_explicit_reference_resolved_claim_count = 0
uint64_t semantic_claim_count = 0
uint64_t semantic_signature_count = 0
uint64_t semantic_signature_linked = 0
uint64_t semantic_signature_orphan = 0
uint64_t semantic_explicit_reference_signature_count = 0
uint64_t semantic_explicit_reference_unresolved_signature_count = 0
uint64_t semantic_explicit_reference_ambiguous_signature_count = 0
uint32_t staged_segments = 0
uint32_t errors = 0
std::string semantic_reason
std::string message
struct ValidateResult
#include <validate.h>

Result of validate_file.

Public Members

ValidateStatus status = ValidateStatus::Ok
uint64_t file_size = 0
SimpleMetaResult read

Decode summary from simple_meta_read.

CcmQueryResult ccm

CCM query summary from collect_dng_ccm_fields.

uint32_t ccm_fields = 0

Number of extracted CCM fields.

uint32_t entries = 0

Final decoded entry count.

uint32_t warning_count = 0
uint32_t error_count = 0
bool failed = false
std::vector<ValidateIssue> issues
class WebpTransferEmitter
#include <metadata_transfer.h>

Backend contract for WebP metadata chunk emission.

Public Functions

virtual ~WebpTransferEmitter() = default
virtual TransferStatus add_chunk(std::array<char, 4> type, std::span<const std::byte> payload) noexcept = 0
virtual TransferStatus close_chunks() noexcept = 0
struct WireType
#include <meta_store.h>

Wire-format element type + family (e.g. TIFF type code).

Public Members

WireFamily family = WireFamily::None
uint16_t code = 0
struct XmpDecodeLimits
#include <xmp_decode.h>

Resource limits applied during XMP decode to bound hostile inputs.

Public Members

uint32_t max_depth = 128
uint32_t max_properties = 200000
uint64_t max_input_bytes = 64ULL * 1024ULL * 1024ULL

Caps the input XMP packet size (0 = unlimited).

uint32_t max_path_bytes = 1024

Max bytes per decoded property path string.

uint32_t max_value_bytes = 8U * 1024U * 1024U

Max text bytes per decoded value (element/attribute).

uint64_t max_total_value_bytes = 64ULL * 1024ULL * 1024ULL

Max total text bytes accumulated across values (0 = unlimited).

struct XmpDecodeOptions
#include <xmp_decode.h>

Decoder options for decode_xmp_packet.

Public Members

bool decode_description_attributes = true

If true, decodes attributes on rdf:Description as XMP properties.

XmpDecodeMalformedMode malformed_mode = XmpDecodeMalformedMode::Malformed

Controls whether malformed XML should be reported as Malformed or as best-effort OutputTruncated.

XmpDecodeLimits limits
struct XmpDecodeResult
#include <xmp_decode.h>

Public Members

XmpDecodeStatus status = XmpDecodeStatus::Ok
uint32_t entries_decoded = 0
struct XmpDumpLimits
#include <xmp_dump.h>

Resource limits applied during dump to bound output generation.

Public Members

uint64_t max_output_bytes = 0

If non-zero, refuse to generate output larger than this many bytes.

uint32_t max_entries = 0

If non-zero, refuse to emit more than this many entries.

struct XmpDumpOptions
#include <xmp_dump.h>

Dump options for dump_xmp_lossless.

Public Members

XmpDumpLimits limits
bool include_origin = true
bool include_wire = true

Includes wire family/code/count and EXR-specific wire type name when available.

bool include_flags = true
bool include_names = true
struct XmpDumpResult
#include <xmp_dump.h>

Dump result (size stats + how many entries were emitted).

Public Members

XmpDumpStatus status = XmpDumpStatus::Ok
uint64_t written = 0
uint64_t needed = 0
uint32_t entries = 0
struct XmpPortableOptions
#include <xmp_dump.h>

Options for dump_xmp_portable.

Public Members

XmpDumpLimits limits
bool include_exif = true

Include TIFF/EXIF/GPS derived properties.

bool include_iptc = true

Include IPTC-IIM derived portable XMP properties.

bool include_existing_xmp = false

Include MetaKeyKind::XmpProperty entries already present in the store.

Note

Currently only simple property_path values are emitted (no / nesting).

XmpConflictPolicy conflict_policy = XmpConflictPolicy::CurrentBehavior

Conflict policy between existing decoded XMP and generated portable EXIF/IPTC mappings.

bool exiftool_gpsdatetime_alias = false

Emit exif:GPSDateTime instead of exif:GPSTimeStamp for GPS time.

Default keeps standard portable naming. This compatibility mode is useful for tools that normalize XMP GPS time under GPSDateTime.

struct XmpProperty
#include <meta_key.h>

Public Members

ByteSpan schema_ns
ByteSpan property_path
struct XmpProperty
#include <meta_key.h>

Public Members

std::string_view schema_ns
std::string_view property_path
struct XmpSidecarOptions
#include <xmp_dump.h>

High-level sidecar options for dump_xmp_sidecar.

Public Members

XmpSidecarFormat format = XmpSidecarFormat::Lossless
XmpDumpOptions lossless
XmpPortableOptions portable
uint64_t initial_output_bytes = 0

Initial output buffer size before automatic growth (0 uses default).

struct XmpSidecarRequest
#include <xmp_dump.h>

Stable flat request for sidecar export.

This shape is intended for wrapper/front-end APIs that need one option set independent of selected format.

Public Members

XmpSidecarFormat format = XmpSidecarFormat::Lossless
XmpDumpLimits limits
bool include_exif = true

Portable mode options (applied when format == Portable).

bool include_iptc = true
bool include_existing_xmp = false
XmpConflictPolicy portable_conflict_policy = XmpConflictPolicy::CurrentBehavior
bool portable_exiftool_gpsdatetime_alias = false
bool include_origin = true

Lossless mode options (applied when format == Lossless).

bool include_wire = true
bool include_flags = true
bool include_names = true
uint64_t initial_output_bytes = 0

Initial output buffer size before automatic growth (0 uses default).

namespace openmeta

Scalar constructors

MetaValue make_u8(uint8_t value) noexcept
MetaValue make_i8(int8_t value) noexcept
MetaValue make_u16(uint16_t value) noexcept
MetaValue make_i16(int16_t value) noexcept
MetaValue make_u32(uint32_t value) noexcept
MetaValue make_i32(int32_t value) noexcept
MetaValue make_u64(uint64_t value) noexcept
MetaValue make_i64(int64_t value) noexcept
MetaValue make_f32_bits(uint32_t bits) noexcept
MetaValue make_f64_bits(uint64_t bits) noexcept
MetaValue make_urational(uint32_t numer, uint32_t denom) noexcept
MetaValue make_srational(int32_t numer, int32_t denom) noexcept

Arena-backed constructors

MetaValue make_bytes(ByteArena &arena, std::span<const std::byte> bytes)
MetaValue make_text(ByteArena &arena, std::string_view text, TextEncoding encoding)
MetaValue make_array(ByteArena &arena, MetaElementType elem_type, std::span<const std::byte> raw_elements, uint32_t element_size)

Convenience array constructors

MetaValue make_u8_array(ByteArena &arena, std::span<const uint8_t> values)
MetaValue make_i8_array(ByteArena &arena, std::span<const int8_t> values)
MetaValue make_u16_array(ByteArena &arena, std::span<const uint16_t> values)
MetaValue make_i16_array(ByteArena &arena, std::span<const int16_t> values)
MetaValue make_u32_array(ByteArena &arena, std::span<const uint32_t> values)
MetaValue make_i32_array(ByteArena &arena, std::span<const int32_t> values)
MetaValue make_u64_array(ByteArena &arena, std::span<const uint64_t> values)
MetaValue make_i64_array(ByteArena &arena, std::span<const int64_t> values)
MetaValue make_f32_bits_array(ByteArena &arena, std::span<const uint32_t> bits)
MetaValue make_f64_bits_array(ByteArena &arena, std::span<const uint64_t> bits)
MetaValue make_urational_array(ByteArena &arena, std::span<const URational> values)
MetaValue make_srational_array(ByteArena &arena, std::span<const SRational> values)

Typedefs

using BlockId = uint32_t
using EntryId = uint32_t

Enums

enum class CcmQueryStatus : uint8_t

Query status for collect_dng_ccm_fields.

Values:

enumerator Ok
enumerator LimitExceeded

Input was valid but query limits were exceeded.

enum class CcmValidationMode : uint8_t

Validation mode for CCM query normalization.

Values:

enumerator None

Do not emit spec-level diagnostics.

enumerator DngSpecWarnings

Emit DNG-oriented structure/coherency diagnostics as warnings.

enum class CcmIssueSeverity : uint8_t

Validation issue severity.

Values:

enumerator Warning
enumerator Error

Field-level hard-invalid issue (the field is skipped).

enum class CcmIssueCode : uint16_t

Validation issue code for CcmIssue.

Values:

enumerator DecodeFailed
enumerator NonFiniteValue
enumerator UnexpectedCount
enumerator MatrixCountNotDivisibleBy3
enumerator NonPositiveValue
enumerator AsShotConflict
enumerator MissingCompanionTag
enumerator TripleIlluminantRule
enumerator CalibrationSignatureMismatch
enumerator MissingIlluminantData
enumerator InvalidIlluminantCode
enumerator WhiteXYOutOfRange
enum class PayloadStatus : uint8_t

Payload extraction result status.

Values:

enumerator Ok
enumerator OutputTruncated

Output buffer was too small; PayloadResult::needed reports required size.

enumerator Unsupported

The payload encoding requires an optional dependency that is not available.

enumerator Malformed

The container data is malformed or inconsistent.

enumerator LimitExceeded

Resource limits were exceeded (e.g. too many parts or too large output).

enum class ScanStatus : uint8_t

Scanner result status.

Values:

enumerator Ok
enumerator OutputTruncated

Output buffer was too small; ScanResult::needed reports required size.

enumerator Unsupported

The bytes do not match the container format handled by the scanner.

enumerator Malformed

The container structure is malformed or inconsistent.

enum class ContainerFormat : uint8_t

Supported high-level container formats for block scanning.

Values:

enumerator Unknown
enumerator Jpeg
enumerator Png
enumerator Webp
enumerator Gif
enumerator Tiff
enumerator Crw
enumerator Raf
enumerator X3f
enumerator Jp2
enumerator Jxl
enumerator Heif
enumerator Avif
enumerator Cr3
enum class ContainerBlockKind : uint8_t

Logical kind of a discovered metadata block.

Values:

enumerator Unknown
enumerator Exif
enumerator Ciff

Canon CRW (CIFF) directory tree (non-TIFF metadata container).

enumerator MakerNote
enumerator Xmp
enumerator XmpExtended
enumerator Jumbf

JPEG Universal Metadata Box Format payload (including C2PA manifests).

enumerator Icc
enumerator IptcIim
enumerator PhotoshopIrB
enumerator Mpf
enumerator Comment
enumerator Text
enumerator CompressedMetadata
enum class BlockCompression : uint8_t

Compression type for the block payload bytes (if any).

Values:

enumerator None
enumerator Deflate
enumerator Brotli
enum class BlockChunking : uint8_t

Chunking scheme used to represent a logical stream split across blocks.

Values:

enumerator None
enumerator JpegApp2SeqTotal
enumerator JpegXmpExtendedGuidOffset
enumerator GifSubBlocks
enumerator BmffExifTiffOffsetU32Be
enumerator BrobU32BeRealTypePrefix
enumerator Jp2UuidPayload
enumerator PsIrB8Bim
enum class ExifTagNamePolicy : uint8_t

Values:

enumerator Canonical
enumerator ExifToolCompat
enum class ExifDecodeStatus : uint8_t

EXIF/TIFF decode result status.

Values:

enumerator Ok
enumerator OutputTruncated
enumerator Unsupported
enumerator Malformed
enumerator LimitExceeded
enum class ExifLimitReason : uint8_t

Best-effort reason for ExifDecodeStatus::LimitExceeded.

Values:

enumerator None
enumerator MaxIfds
enumerator MaxEntriesPerIfd
enumerator MaxTotalEntries
enumerator ValueCountTooLarge
enum class ExifIfdKind : uint8_t

Logical IFD kinds exposed by decode_exif_tiff().

Values:

enumerator Ifd
enumerator ExifIfd
enumerator GpsIfd
enumerator InteropIfd
enumerator SubIfd
enum class ExrAdapterStatus : uint8_t

Result status for EXR adapter export.

Values:

enumerator Ok
enumerator InvalidArgument
enumerator Unsupported
enum class ExrDecodeStatus : uint8_t

OpenEXR decode result status.

Values:

enumerator Ok
enumerator Unsupported

The bytes do not look like an OpenEXR file.

enumerator Malformed

The EXR header is malformed or inconsistent.

enumerator LimitExceeded

Resource limits were exceeded.

enum class IccDecodeStatus : uint8_t

ICC decode result status.

Values:

enumerator Ok
enumerator Unsupported

The bytes do not look like an ICC profile.

enumerator Malformed

The profile is malformed or inconsistent.

enumerator LimitExceeded

Resource limits were exceeded.

enum class IccTagInterpretStatus : uint8_t

Best-effort status for interpret_icc_tag.

Values:

enumerator Ok
enumerator Unsupported
enumerator Malformed
enumerator LimitExceeded
enum class InteropSafetyStatus : uint8_t

Status for strict safe interop export APIs.

Values:

enumerator Ok
enumerator InvalidArgument
enumerator UnsafeData
enumerator InternalError
enum class InteropSafetyReason : uint8_t

Reason code for InteropSafetyError.

Values:

enumerator None
enumerator UnsafeBytes
enumerator InvalidTextEncoding
enumerator UnsafeTextControlCharacter
enumerator InternalMismatch
enum class ExportNameStyle : uint8_t

Key naming policy used by visit_metadata.

Values:

enumerator Canonical

Stable, key-space-aware names (for example: exif:ifd0:0x010F).

enumerator XmpPortable

Portable XMP-like names (for example: tiff:Make, exif:ExposureTime).

enumerator Oiio

OIIO-style names (for example: Make, Exif:ExposureTime).

enum class ExportNamePolicy : uint8_t

Name normalization policy for interop exports.

Values:

enumerator Spec

Preserve native OpenMeta/EXIF naming (spec-oriented).

enumerator ExifToolAlias

Apply ExifTool-compatible aliases and filtering for parity workflows.

enum class IptcIimDecodeStatus : uint8_t

IPTC-IIM decode result status.

Values:

enumerator Ok
enumerator Unsupported

The bytes do not look like an IPTC-IIM dataset stream.

enumerator Malformed

The stream is malformed or inconsistent.

enumerator LimitExceeded

Resource limits were exceeded.

enum class JumbfDecodeStatus : uint8_t

JUMBF decode result status.

Values:

enumerator Ok
enumerator Unsupported

Input does not look like a JUMBF payload.

enumerator Malformed

Input is truncated or structurally invalid.

enumerator LimitExceeded

Refused due to configured resource limits.

enum class C2paVerifyBackend : uint8_t

Draft C2PA verification backend selection.

Values:

enumerator None
enumerator Auto
enumerator Native
enumerator OpenSsl
enum class C2paVerifyStatus : uint8_t

Draft C2PA verification status.

Values:

enumerator NotRequested
enumerator DisabledByBuild
enumerator BackendUnavailable
enumerator NoSignatures
enumerator InvalidSignature
enumerator VerificationFailed
enumerator Verified
enumerator NotImplemented
enum class MappedFileStatus : uint8_t

Status code for MappedFile operations.

Values:

enumerator Ok
enumerator OpenFailed
enumerator StatFailed
enumerator TooLarge
enumerator MapFailed
enum class EditOpKind : uint8_t

The operation kind for a MetaEdit command stream.

Values:

enumerator AddEntry
enumerator SetValue
enumerator Tombstone
enum class EntryFlags : uint8_t

Per-entry flags used during edits and provenance tracking.

Values:

enumerator None
enumerator Deleted

Entry is logically removed (kept for stable ids / provenance).

enumerator Dirty

Entry was modified or added relative to an origin snapshot.

enumerator Derived

Entry was derived from other data (e.g. EXIF->XMP mapping).

enumerator Truncated

Value payload was truncated or omitted due to configured limits.

enumerator Unreadable

Value payload could not be read from the underlying container.

enumerator ContextualName

Entry name has a decode-time contextual display variant.

enum class MetaKeyKind : uint8_t

Namespace for different metadata key spaces.

Values:

enumerator ExifTag
enumerator Comment
enumerator ExrAttribute
enumerator IptcDataset
enumerator XmpProperty
enumerator IccHeaderField
enumerator IccTag
enumerator PhotoshopIrb
enumerator PhotoshopIrbField
enumerator GeotiffKey
enumerator PrintImField
enumerator BmffField
enumerator JumbfField
enumerator JumbfCborKey
enumerator PngText
enum class WireFamily : uint8_t

The wire-format family a value came from (used for round-trip encoding).

Values:

enumerator None
enumerator Tiff
enumerator Other
enum class EntryNameContextKind : uint8_t

Decode-time contextual-name selector for compatibility/display surfaces.

Values:

enumerator None
enumerator CasioType2Legacy
enumerator FujifilmMain1304
enumerator OlympusFocusInfo1600
enumerator KodakMain0028
enumerator MinoltaMainCompat
enumerator MotorolaMain6420
enumerator SonyMainCompat
enumerator SonyTag94060005
enumerator SigmaMainCompat
enumerator RicohMainCompat
enumerator NikonSettingsMain
enumerator NikonMainZ
enumerator NikonMainCompactType2
enumerator NikonFlashInfoGroups
enumerator NikonFlashInfoLegacy
enumerator NikonShotInfoD800
enumerator NikonShotInfoD850
enumerator NikonShotInfoZ8
enumerator PentaxMain0062
enumerator CanonMain0038
enumerator CanonShotInfo000E
enumerator CanonCameraSettings0021
enumerator CanonColorData4PSInfo
enumerator CanonColorData7PSInfo2
enumerator CanonColorData400EA
enumerator CanonColorData400EE
enumerator CanonColorData402CF
enumerator CanonColorCalib0038
enumerator CanonCameraInfo1D0048
enumerator CanonCameraInfo600D00EA
enumerator CanonCustomFunctions20103
enumerator CanonCustomFunctions2010C
enumerator CanonCustomFunctions20510
enumerator CanonCustomFunctions20701
enum class MetaValueKind : uint8_t

Top-level value storage kind.

Values:

enumerator Empty
enumerator Scalar

An inline scalar stored in MetaValue::data.

enumerator Array

An array stored as raw bytes in a ByteArena span.

enumerator Bytes

Raw uninterpreted bytes in a ByteArena span.

enumerator Text

Text bytes in a ByteArena span with an associated encoding.

enum class MetaElementType : uint8_t

Element type used for scalar and array values.

Values:

enumerator U8
enumerator I8
enumerator U16
enumerator I16
enumerator U32
enumerator I32
enumerator U64
enumerator I64
enumerator F32
enumerator F64
enumerator URational
enumerator SRational
enum class TextEncoding : uint8_t

Encoding hint for text values.

Values:

enumerator Unknown
enumerator Ascii
enumerator Utf8
enumerator Utf16LE
enumerator Utf16BE
enum class TransferTargetFormat : uint8_t

Target container family for prepared transfer bundles.

Values:

enumerator Jpeg
enumerator Tiff
enumerator Jxl
enumerator Webp
enumerator Heif
enumerator Avif
enumerator Cr3
enumerator Exr
enumerator Png
enumerator Jp2
enum class TransferBlockKind : uint8_t

Prepared payload block category.

Values:

enumerator Exif
enumerator Xmp
enumerator IptcIim
enumerator PhotoshopIrb
enumerator Icc
enumerator Jumbf
enumerator C2pa
enumerator ExrAttribute
enumerator Other
enum class TransferStatus : uint8_t

Status for transfer preparation and emit APIs.

Values:

enumerator Ok
enumerator InvalidArgument
enumerator Unsupported
enumerator LimitExceeded
enumerator Malformed
enumerator UnsafeData
enumerator InternalError
enum class PrepareTransferCode : uint16_t

Stable preparation error code for PrepareTransferResult.

Values:

enumerator None
enumerator NullOutBundle
enumerator UnsupportedTargetFormat
enumerator ExifPackFailed
enumerator XmpPackFailed
enumerator IccPackFailed
enumerator IptcPackFailed
enumerator RequestedMetadataNotSerializable
enum class EmitTransferCode : uint16_t

Stable emit error code for EmitTransferResult.

Values:

enumerator None
enumerator InvalidArgument
enumerator BundleTargetNotJpeg
enumerator UnsupportedRoute
enumerator InvalidPayload
enumerator ContentBoundPayloadUnsupported
enumerator BackendWriteFailed
enumerator PlanMismatch
enum class PrepareTransferFileCode : uint16_t

Stable file/read/prepare error code for PrepareTransferFileResult.

Values:

enumerator None
enumerator EmptyPath
enumerator MapFailed
enumerator PayloadBufferPlatformLimit
enumerator DecodeFailed
enum class TransferFileStatus : uint8_t

Status for high-level file-to-bundle transfer preparation.

Values:

enumerator Ok
enumerator InvalidArgument
enumerator OpenFailed
enumerator StatFailed
enumerator TooLarge
enumerator MapFailed
enumerator ReadFailed
enum class TransferPolicySubject : uint8_t

Transfer-policy subject handled during bundle preparation.

Values:

enumerator MakerNote
enumerator Jumbf
enumerator C2pa
enumerator XmpExifProjection
enumerator XmpIptcProjection
enum class TransferPolicyAction : uint8_t

Requested/effective action for a metadata family during transfer.

Values:

enumerator Keep
enumerator Drop
enumerator Invalidate
enumerator Rewrite
enum class TransferPolicyReason : uint8_t

Reason attached to one prepared transfer policy decision.

Values:

enumerator Default
enumerator NotPresent
enumerator ExplicitDrop
enumerator CarrierDisabled
enumerator ProjectedPayload
enumerator DraftInvalidationPayload
enumerator ExternalSignedPayload
enumerator ContentBoundTransferUnavailable
enumerator SignedRewriteUnavailable
enumerator PortableInvalidationUnavailable
enumerator RewriteUnavailablePreservedRaw
enumerator TargetSerializationUnavailable
enum class TransferC2paMode : uint8_t

Explicit current C2PA transfer mode resolved during prepare.

Values:

enumerator NotApplicable
enumerator NotPresent
enumerator Drop
enumerator DraftUnsignedInvalidation
enumerator PreserveRaw
enumerator SignedRewrite
enum class TransferC2paSourceKind : uint8_t

Classified C2PA source state observed during prepare.

Values:

enumerator NotApplicable
enumerator NotPresent
enumerator DecodedOnly
enumerator ContentBound
enumerator DraftUnsignedInvalidation
enum class TransferC2paPreparedOutput : uint8_t

Prepared C2PA output contract selected during prepare.

Values:

enumerator NotApplicable
enumerator NotPresent
enumerator Dropped
enumerator PreservedRaw
enumerator GeneratedDraftUnsignedInvalidation
enumerator SignedRewrite
enum class TransferC2paRewriteState : uint8_t

Current rewrite-signing readiness for C2PA transfer.

Values:

enumerator NotApplicable
enumerator NotRequested
enumerator SigningMaterialRequired
enumerator Ready
enum class TransferC2paRewriteChunkKind : uint8_t

One deterministic chunk in the future C2PA rewrite binding sequence.

Values:

enumerator SourceRange
enumerator PreparedJpegSegment
enumerator PreparedJxlBox
enumerator PreparedBmffMetaBox
enum class TransferC2paSignedPayloadKind : uint8_t

Classified logical C2PA payload kind supplied by an external signer.

Values:

enumerator NotApplicable
enumerator GenericJumbf
enumerator DraftUnsignedInvalidation
enumerator ContentBound
enum class TransferC2paSemanticStatus : uint8_t

Semantic validation status for a staged logical C2PA payload.

Values:

enumerator NotChecked
enumerator Ok
enumerator Invalid
enum class TimePatchField : uint8_t

Optional fixed-width patch field identifiers for per-frame updates.

Values:

enumerator DateTime
enumerator DateTimeOriginal
enumerator DateTimeDigitized
enumerator SubSecTime
enumerator SubSecTimeOriginal
enumerator SubSecTimeDigitized
enumerator OffsetTime
enumerator OffsetTimeOriginal
enumerator OffsetTimeDigitized
enumerator GpsDateStamp
enumerator GpsTimeStamp
enum class JpegEditMode : uint8_t

Draft JPEG edit strategy selection.

Values:

enumerator Auto
enumerator InPlace
enumerator MetadataRewrite
enum class TransferPackageChunkKind : uint8_t

One chunk in a packaged transfer output plan.

Values:

enumerator SourceRange
enumerator PreparedTransferBlock
enumerator PreparedJpegSegment
enumerator InlineBytes
enum class TransferSemanticKind : uint8_t

Semantic metadata family carried by one transfer payload or package chunk.

Values:

enumerator Unknown
enumerator Exif
enumerator Xmp
enumerator Icc
enumerator Iptc
enumerator Jumbf
enumerator C2pa
enum class PreparedJxlEmitKind : uint8_t

Kind of precompiled JPEG XL emit operation.

Values:

enumerator Box
enumerator IccProfile
enum class PreparedTransferArtifactKind : uint8_t

Persisted transfer artifact family recognized by the generic inspect path.

Values:

enumerator Unknown
enumerator TransferPayloadBatch
enumerator TransferPackageBatch
enumerator C2paHandoffPackage
enumerator C2paSignedPackage
enumerator JxlEncoderHandoff
enum class PreparedBmffEmitKind : uint8_t

Kind of precompiled ISO-BMFF metadata emit operation.

Values:

enumerator Item
enumerator MimeXmp
enumerator Property
enum class TransferAdapterOpKind : uint8_t

One normalized adapter operation for external encoder or host integration.

Values:

enumerator JpegMarker
enumerator TiffTagBytes
enumerator JxlBox
enumerator JxlIccProfile
enumerator WebpChunk
enumerator PngChunk
enumerator Jp2Box
enumerator ExrAttribute
enumerator BmffItem
enumerator BmffProperty
enum class XmpExistingSidecarMode : uint8_t

Existing sibling XMP sidecar handling for transfer preparation.

Values:

enumerator Ignore
enumerator MergeIfPresent
enum class XmpExistingSidecarPrecedence : uint8_t

Conflict precedence between a merged destination-side .xmp and source-embedded existing XMP.

Values:

enumerator SidecarWins
enumerator SourceWins
enum class XmpWritebackMode : uint8_t

XMP carrier preference for file-helper transfer execution.

Values:

enumerator EmbeddedOnly
enumerator SidecarOnly
enumerator EmbeddedAndSidecar
enum class XmpDestinationEmbeddedMode : uint8_t

Destination embedded-XMP handling for file-helper transfer execution.

Values:

enumerator PreserveExisting
enumerator StripExisting
enum class XmpDestinationSidecarMode : uint8_t

Destination sibling XMP sidecar handling for file-helper transfer execution.

Values:

enumerator PreserveExisting
enumerator StripExisting
enum class OiioTransferPayloadKind : uint8_t

Semantic block kind for OIIO-facing transfer payload export.

Values:

enumerator Unknown
enumerator ExifBlob
enumerator XmpPacket
enumerator IccProfile
enumerator IptcBlock
enumerator Jumbf
enumerator C2pa
enum class PhotoshopIrbDecodeStatus : uint8_t

Photoshop IRB decode result status.

Values:

enumerator Ok
enumerator Unsupported

The bytes do not look like an IRB stream.

enumerator Malformed

The stream is malformed or inconsistent.

enumerator LimitExceeded

Resource limits were exceeded.

enum class PhotoshopIrbStringCharset : uint8_t

Charset policy for legacy 8-bit Photoshop IRB text payloads.

Values:

enumerator Latin
enumerator Ascii
enum class PreviewKind : uint8_t

Candidate preview source kind.

Values:

enumerator ExifJpegInterchange

EXIF/TIFF pair JPEGInterchangeFormat (0x0201) + length (0x0202).

enumerator ExifJpgFromRaw

EXIF/TIFF blob tag JpgFromRaw (0x002E).

enumerator ExifJpgFromRaw2

EXIF/TIFF blob tag JpgFromRaw2 (0x0127).

enumerator Cr3PrvwJpeg

Canon CR3 preview JPEG stored in a PRVW stream inside a UUID box.

enum class PreviewScanStatus : uint8_t

Status for preview candidate discovery.

Values:

enumerator Ok
enumerator OutputTruncated
enumerator Unsupported
enumerator Malformed
enumerator LimitExceeded
enum class PreviewExtractStatus : uint8_t

Status for preview extraction.

Values:

enumerator Ok
enumerator OutputTruncated
enumerator Malformed
enumerator LimitExceeded
enum class PrintImDecodeStatus : uint8_t

PrintIM decode result status.

Values:

enumerator Ok
enumerator Unsupported

Input does not look like a PrintIM block.

enumerator Malformed

Input is truncated or structurally invalid.

enumerator LimitExceeded

Refused due to size/entry-count limits.

enum class ValidateStatus : uint8_t

Top-level validation status for validate_file.

Values:

enumerator Ok
enumerator OpenFailed
enumerator TooLarge
enumerator ReadFailed
enum class ValidateIssueSeverity : uint8_t

Validation issue severity.

Values:

enumerator Warning
enumerator Error
enum class XmpDecodeStatus : uint8_t

XMP decode result status.

Values:

enumerator Ok
enumerator OutputTruncated
enumerator Unsupported
enumerator Malformed
enumerator LimitExceeded
enum class XmpDecodeMalformedMode : uint8_t

Controls how malformed XMP packets are reported to callers.

Some workflows prefer treating malformed XML as “best-effort partial output” rather than a hard failure.

Values:

enumerator Malformed

Report malformed XML as XmpDecodeStatus::Malformed.

enumerator OutputTruncated

Report malformed XML as XmpDecodeStatus::OutputTruncated.

enum class XmpConflictPolicy : uint8_t

Conflict policy for existing XMP versus generated portable XMP properties.

This currently applies to portable XMP generation only.

Values:

enumerator CurrentBehavior

Preserve the historical OpenMeta order: EXIF-derived properties first, then existing XMP, then IPTC-derived properties.

enumerator ExistingWins

Existing decoded XMP properties win over generated EXIF/IPTC mappings.

enumerator GeneratedWins

Generated EXIF/IPTC mappings win over existing decoded XMP properties.

enum class XmpDumpStatus : uint8_t

XMP dump result status.

Values:

enumerator Ok
enumerator OutputTruncated

Output buffer was too small; XmpDumpResult::needed reports required size.

enumerator LimitExceeded

Caller-specified limits prevented generating a complete dump.

enum class XmpSidecarFormat : uint8_t

Sidecar format selection for dump_xmp_sidecar.

Values:

enumerator Lossless
enumerator Portable

Functions

const BuildInfo &build_info() noexcept

Returns build information for the linked OpenMeta library.

void format_build_info_lines(const BuildInfo &info, std::string *line1, std::string *line2) noexcept

Formats a stable, human-readable build info header (2 lines).

Output format:

  • OpenMeta vX.Y.Z <build_type> [features] <linkage>

  • built with <compiler> for <system>/<arch> (<timestamp>)

void format_build_info_lines(std::string *line1, std::string *line2) noexcept

Convenience overload for the linked OpenMeta library build.

CcmQueryResult collect_dng_ccm_fields(const MetaStore &store, std::vector<CcmField> *out, const CcmQueryOptions &options = CcmQueryOptions{}, std::vector<CcmIssue> *issues = nullptr) noexcept

Extracts normalized DNG/RAW CCM-related fields from a MetaStore.

The query scans EXIF tags and emits stable field names for:

  • ColorMatrix*, ForwardMatrix*, CameraCalibration*

  • ReductionMatrix* (optional)

  • AsShotNeutral, AsShotWhiteXY, AnalogBalance

  • CalibrationIlluminant*

bool append_console_escaped_ascii(std::string_view s, uint32_t max_bytes, std::string *out) noexcept
void append_hex_bytes(std::span<const std::byte> bytes, uint32_t max_bytes, std::string *out) noexcept
PayloadResult extract_payload(std::span<const std::byte> file_bytes, std::span<const ContainerBlockRef> blocks, uint32_t seed_index, std::span<std::byte> out_payload, std::span<uint32_t> scratch_indices, const PayloadOptions &options) noexcept

Extracts the logical payload for a discovered block.

The function uses seed_index to identify the logical stream to extract and, when applicable, gathers additional parts from blocks to reassemble it.

Supported reassembly:

Supported decompression (optional):

Callers provide buffers to keep data flow explicit and allocation-free.

static constexpr uint32_t fourcc(char a, char b, char c, char d) noexcept

Packs four ASCII characters into a big-endian FourCC integer.

ScanResult scan_auto(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept
ScanResult measure_scan_auto(std::span<const std::byte> bytes) noexcept

Measures discovered metadata block count for scan_auto.

Performs the same bounded scan logic and reports ScanResult::needed without requiring output block storage.

ScanResult scan_jpeg(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a JPEG byte stream and returns all metadata segments found.

ScanResult measure_scan_jpeg(std::span<const std::byte> bytes) noexcept
ScanResult scan_png(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a PNG byte stream and returns all metadata chunks found.

ScanResult measure_scan_png(std::span<const std::byte> bytes) noexcept
ScanResult scan_webp(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a RIFF/WebP byte stream and returns all metadata chunks found.

ScanResult measure_scan_webp(std::span<const std::byte> bytes) noexcept
ScanResult scan_gif(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a GIF byte stream and returns all metadata extension blocks found.

ScanResult measure_scan_gif(std::span<const std::byte> bytes) noexcept
ScanResult scan_tiff(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a TIFF/DNG byte stream; the whole file is exposed as an EXIF/TIFF-IFD block.

ScanResult measure_scan_tiff(std::span<const std::byte> bytes) noexcept
ScanResult scan_jp2(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a JPEG 2000 (JP2) byte stream and returns metadata boxes found.

ScanResult measure_scan_jp2(std::span<const std::byte> bytes) noexcept
ScanResult scan_jxl(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans a JPEG XL container byte stream and returns metadata boxes found.

ScanResult measure_scan_jxl(std::span<const std::byte> bytes) noexcept
ScanResult scan_bmff(std::span<const std::byte> bytes, std::span<ContainerBlockRef> out) noexcept

Scans an ISO-BMFF (ftyp) container (e.g. HEIF/AVIF/CR3) and returns metadata items found within meta boxes.

ScanResult measure_scan_bmff(std::span<const std::byte> bytes) noexcept
std::string_view exif_tag_name(std::string_view ifd, uint16_t tag) noexcept

Returns a human-readable EXIF/TIFF tag name for a given IFD token and tag id.

The IFD token matches the decoder output (e.g. "ifd0", "exififd", "gpsifd").

Returns:

An empty view for unknown tags.

std::string_view exif_entry_name(const MetaStore &store, const Entry &entry, ExifTagNamePolicy policy) noexcept

Returns a human-readable name for an EXIF-tag entry.

Canonical names come from the static tag registry. Compatibility policy may use decode-time contextual variants for ambiguous MakerNote tags.

ExifDecodeResult decode_exif_tiff(std::span<const std::byte> tiff_bytes, MetaStore &store, std::span<ExifIfdRef> out_ifds, const ExifDecodeOptions &options) noexcept

Decodes a TIFF header + IFD chain and appends tags into store.

The decoded entries use:

  • MetaKeyKind::ExifTag

  • an IFD token string such as "ifd0", "exififd", "gpsifd", "subifd0"

  • the numeric TIFF tag id.

Provenance is recorded in Origin (block + order + wire type/count).

Parameters:

  • tiff_bytes – TIFF header + IFD stream (from an EXIF blob or a TIFF/DNG file).

  • store – Destination MetaStore (entries are appended).

  • out_ifds – Optional output array for decoded IFD references (may be empty).

  • options – Decode options + limits.

ExifDecodeResult measure_exif_tiff(std::span<const std::byte> tiff_bytes, const ExifDecodeOptions &options = ExifDecodeOptions{}) noexcept

Estimates EXIF/TIFF decode counts using the same limits/options.

This function performs a bounded decode pass into an internal scratch store and returns the same status/counter model as decode_exif_tiff. Callers can use this to preflight entry counts before full decode/export.

ExrAdapterResult build_exr_attribute_batch(const MetaStore &store, ExrAdapterBatch *out, const ExrAdapterOptions &options = ExrAdapterOptions{}) noexcept

Builds one owned EXR-native attribute batch from a MetaStore.

Only MetaKeyKind::ExrAttribute entries are exported. Known scalar and vector EXR types are encoded back into EXR little-endian attribute bytes. Unknown/custom attributes are preserved as opaque raw bytes when the original type name is available in Origin::wire_type_name.

ExrAdapterResult build_prepared_exr_attribute_batch(const PreparedTransferBundle &bundle, ExrAdapterBatch *out, const ExrAdapterOptions &options = ExrAdapterOptions{}) noexcept

Builds one EXR-native attribute batch from a prepared EXR transfer bundle.

This bridges the transfer pipeline with EXR host integrations: callers can prepare metadata once with prepare_metadata_for_target using TransferTargetFormat::Exr, then materialize a host-facing ExrAdapterBatch without re-projecting from the source MetaStore.

Current EXR prepared transfer blocks serialize one logical string attribute per block and target part 0.

BuildExrAttributeBatchFileResult build_exr_attribute_batch_from_file(const char *path, ExrAdapterBatch *out, const BuildExrAttributeBatchFileOptions &options = BuildExrAttributeBatchFileOptions{}) noexcept

Reads one file, prepares EXR transfer metadata, then materializes a host-facing ExrAdapterBatch.

This is the direct public file-helper for thin bindings and host tools. Internally it wraps prepare_metadata_for_target_file, forces the prepared target format to TransferTargetFormat::Exr, then calls build_prepared_exr_attribute_batch.

ExrAdapterStatus build_exr_attribute_part_spans(const ExrAdapterBatch &batch, std::vector<ExrAdapterPartSpan> *out) noexcept

Builds contiguous per-part spans over one ExrAdapterBatch.

The batch must keep attributes grouped by nondecreasing part index. Batches built by build_exr_attribute_batch satisfy this contract.

ExrAdapterStatus build_exr_attribute_part_views(const ExrAdapterBatch &batch, std::vector<ExrAdapterPartView> *out) noexcept

Builds zero-copy per-part views over one ExrAdapterBatch.

ExrAdapterReplayResult replay_exr_attribute_batch(const ExrAdapterBatch &batch, const ExrAdapterReplayCallbacks &callbacks) noexcept

Replays one ExrAdapterBatch through explicit host callbacks.

ExrAdapterReplayCallbacks::emit_attribute must be non-null. ExrAdapterReplayCallbacks::begin_part and ExrAdapterReplayCallbacks::end_part are optional.

ExrDecodeResult decode_exr_header(std::span<const std::byte> exr_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const ExrDecodeOptions &options = ExrDecodeOptions{}) noexcept

Decodes OpenEXR header attributes and appends entries into store.

Each decoded header attribute becomes one Entry with:

Duplicate attribute names are preserved.

ExrDecodeResult measure_exr_header(std::span<const std::byte> exr_bytes, const ExrDecodeOptions &options = ExrDecodeOptions{}) noexcept

Estimates EXR header decode counts using the same limits/options.

std::string_view geotiff_key_name(uint16_t key_id) noexcept

Returns a best-effort GeoTIFF key name for a numeric GeoKey id.

IccDecodeResult decode_icc_profile(std::span<const std::byte> icc_bytes, MetaStore &store, const IccDecodeOptions &options = IccDecodeOptions{}) noexcept

Decodes an ICC profile header and tag table into store.

The decoder emits:

IccDecodeResult measure_icc_profile(std::span<const std::byte> icc_bytes, const IccDecodeOptions &options = IccDecodeOptions{}) noexcept

Estimates ICC decode entry count using the same limits/options.

std::string_view icc_tag_name(uint32_t signature) noexcept

Returns a short display name for an ICC tag signature.

IccTagInterpretStatus interpret_icc_tag(uint32_t signature, std::span<const std::byte> tag_bytes, IccTagInterpretation *out, const IccTagInterpretOptions &options = IccTagInterpretOptions{}) noexcept

Best-effort interpretation for selected ICC tag payload types.

Supported payload type signatures:

  • desc (ASCII profile description)

  • text (ASCII text payload)

  • sig (embedded 4-byte signature)

  • data (ASCII/binary data payload summary)

  • mluc (multi-localized Unicode)

  • ncl2 (named-color table summary)

  • dtim (date/time number)

  • view (viewing conditions summary + numeric values)

  • meas (measurement summary + backing/flare values)

  • chrm (chromaticity coordinates + colorant summary)

  • sf32 (s15Fixed16 array)

  • uf32 (u16Fixed16 array)

  • ui08 (uInt8 array)

  • ui16 (uInt16 array)

  • ui32 (uInt32 array)

  • mft1 / mft2 (LUT summaries)

  • mAB / mBA (LUT-A/B structural summaries)

  • XYZ (s15Fixed16 XYZ triplets)

  • curv (TRC curves)

  • para (parametric curves)

bool format_icc_tag_display_value(uint32_t signature, std::span<const std::byte> tag_bytes, uint32_t max_values, uint32_t max_text_bytes, std::string *out) noexcept

Formats a best-effort human-readable value string for an ICC tag.

This helper is intended for CLI/Python display paths. It uses interpret_icc_tag and returns false for unsupported/malformed payloads.

void visit_metadata(const MetaStore &store, const ExportOptions &options, MetadataSink &sink) noexcept

Visits exported metadata entries in store order.

Deleted entries are skipped. Name mapping depends on ExportOptions::style.

IptcIimDecodeResult decode_iptc_iim(std::span<const std::byte> iptc_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const IptcIimDecodeOptions &options = IptcIimDecodeOptions{}) noexcept

Decodes an IPTC-IIM dataset stream and appends datasets into store.

Each dataset becomes one Entry with:

Duplicate datasets are preserved.

IptcIimDecodeResult measure_iptc_iim(std::span<const std::byte> iptc_bytes, const IptcIimDecodeOptions &options = IptcIimDecodeOptions{}) noexcept

Estimates IPTC-IIM dataset count using the same limits/options.

JumbfDecodeResult decode_jumbf_payload(std::span<const std::byte> bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const JumbfDecodeOptions &options = JumbfDecodeOptions{}) noexcept

Decodes a JUMBF/C2PA payload and appends entries into store.

Emitted entries use:

Duplicate keys are preserved.

JumbfDecodeResult measure_jumbf_payload(std::span<const std::byte> bytes, const JumbfDecodeOptions &options = JumbfDecodeOptions{}) noexcept

Estimates JUMBF decode entry count using the same limits/options.

JumbfStructureEstimate measure_jumbf_structure(std::span<const std::byte> bytes, const JumbfDecodeLimits &limits = JumbfDecodeLimits{}) noexcept

Estimates structural nesting for a JUMBF/C2PA payload.

Performs bounded BMFF box traversal and bounded CBOR structural parsing to report maximum observed nesting depth and item counts. This function is intended for preflight risk checks before full decode.

MetaStore commit(const MetaStore &base, std::span<const MetaEdit> edits)

Applies edits to base and returns a new MetaStore snapshot.

MetaStore compact(const MetaStore &base)

Compacts a store by removing tombstones and rewriting indices.

constexpr EntryFlags operator|(EntryFlags a, EntryFlags b) noexcept
constexpr EntryFlags operator&(EntryFlags a, EntryFlags b) noexcept
constexpr EntryFlags &operator|=(EntryFlags &a, EntryFlags b) noexcept
constexpr bool any(EntryFlags flags, EntryFlags test) noexcept

Returns true if any bits in test are present in flags.

MetaKey make_exif_tag_key(ByteArena &arena, std::string_view ifd, uint16_t tag)

Creates a key for an EXIF/TIFF tag within a named IFD token (e.g. “ifd0”, “exififd”).

MetaKey make_comment_key() noexcept
MetaKey make_exr_attribute_key(ByteArena &arena, uint32_t part_index, std::string_view name)

Creates a key for an OpenEXR attribute name in a specific part.

MetaKey make_iptc_dataset_key(uint16_t record, uint16_t dataset) noexcept
MetaKey make_xmp_property_key(ByteArena &arena, std::string_view schema_ns, std::string_view property_path)
MetaKey make_icc_header_field_key(uint32_t offset) noexcept
MetaKey make_icc_tag_key(uint32_t signature) noexcept
MetaKey make_photoshop_irb_key(uint16_t resource_id) noexcept
MetaKey make_photoshop_irb_field_key(ByteArena &arena, uint16_t resource_id, std::string_view field)
MetaKey make_geotiff_key(uint16_t key_id) noexcept
MetaKey make_printim_field_key(ByteArena &arena, std::string_view field)
MetaKey make_bmff_field_key(ByteArena &arena, std::string_view field)
MetaKey make_jumbf_field_key(ByteArena &arena, std::string_view field)
MetaKey make_jumbf_cbor_key(ByteArena &arena, std::string_view key)
MetaKey make_png_text_key(ByteArena &arena, std::string_view keyword, std::string_view field)
int compare_key(const ByteArena &arena, const MetaKey &a, const MetaKey &b) noexcept

Orders keys for deterministic storage/indexing.

int compare_key_view(const ByteArena &arena, const MetaKeyView &a, const MetaKey &b) noexcept

Orders a borrowed key against an owned key using the same ordering as compare_key.

PersistPreparedTransferFileResult persist_prepared_transfer_file_result(const ExecutePreparedTransferFileResult &prepared, const PersistPreparedTransferFileOptions &options) noexcept

Persists edited output, generated XMP sidecar output, and any requested destination-sidecar cleanup from execute_prepared_transfer_file.

This is a bounded file helper for host applications that want the same output/sidecar behavior as the CLI or Python wrapper without reimplementing write and cleanup logic.

EmitTransferResult build_executed_transfer_package_batch(std::span<const std::byte> edit_input, const PreparedTransferBundle &bundle, const ExecutePreparedTransferResult &execute, PreparedTransferPackageBatch *out_batch) noexcept

Materializes the final persisted package batch for one executed transfer state.

For direct emit targets this builds the target-neutral emit package batch. For JPEG/TIFF/BMFF edit flows this builds the rewrite package batch from the selected edit state and input bytes.

PrepareTransferResult prepare_metadata_for_target(const MetaStore&, const PrepareTransferRequest&, PreparedTransferBundle *out_bundle) noexcept

Draft bundle preparation entry point.

EmitTransferResult append_prepared_bundle_jpeg_jumbf(PreparedTransferBundle *bundle, std::span<const std::byte> logical_payload, const AppendPreparedJpegJumbfOptions &options = AppendPreparedJpegJumbfOptions{}) noexcept

Append one logical raw JUMBF payload as JPEG APP11 transfer blocks.

The input must be a logical JUMBF BMFF payload (jumb/jumd…), not an already wrapped APP11 marker payload. C2PA content-bound payloads are rejected by this helper; they require a dedicated invalidation/re-sign path.

On success, the bundle policy decision for JUMBF is updated to explicit Keep, and one or more jpeg:app11-jumbf prepared blocks are appended.

EmitTransferResult emit_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, JpegTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a JPEG backend.

Route mapping:

  • jpeg:app1-exif -> APP1 (0xE1)

  • jpeg:app1-xmp -> APP1 (0xE1)

  • jpeg:app2-icc -> APP2 (0xE2)

  • jpeg:app13-iptc -> APP13 (0xED)

  • jpeg:appN / jpeg:appN-* where N in [0,15]

  • jpeg:com -> COM (0xFE)

EmitTransferResult emit_prepared_bundle_tiff(const PreparedTransferBundle &bundle, TiffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a TIFF backend.

Route mapping:

  • tiff:tag-700-xmp -> TIFF tag 700 (XMP packet)

  • tiff:ifd-exif-app1 -> serialized EXIF APP1 input for ExifIFD materialization

  • tiff:tag-34675-icc -> TIFF tag 34675 (ICC profile)

  • tiff:tag-33723-iptc -> TIFF tag 33723 (IPTC IIM stream)

EmitTransferResult emit_prepared_bundle_jxl(const PreparedTransferBundle &bundle, JxlTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a JPEG XL backend.

Route mapping:

  • jxl:icc-profile -> encoder ICC profile

  • jxl:box-exif -> Exif

  • jxl:box-xml -> xml

  • jxl:box-jumb -> jumb

  • jxl:box-c2pa -> c2pa

EmitTransferResult emit_prepared_bundle_webp(const PreparedTransferBundle &bundle, WebpTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a WebP backend.

Route mapping:

  • webp:chunk-exif -> EXIF

  • webp:chunk-xmp -> XMP

  • webp:chunk-iccp -> ICCP

  • webp:chunk-c2pa -> C2PA

EmitTransferResult emit_prepared_bundle_png(const PreparedTransferBundle &bundle, PngTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a PNG backend.

Route mapping:

  • png:chunk-exif -> eXIf

  • png:chunk-xmp -> iTXt

  • png:chunk-iccp -> iCCP

EmitTransferResult emit_prepared_bundle_jp2(const PreparedTransferBundle &bundle, Jp2TransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into a JP2 backend.

Route mapping:

  • jp2:box-exif -> Exif

  • jp2:box-xml -> xml

  • jp2:box-jp2h-colr -> jp2h carrying one colr ICC child box

EmitTransferResult emit_prepared_bundle_exr(const PreparedTransferBundle &bundle, ExrTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into an EXR backend.

Route mapping:

  • exr:attribute-string -> EXR string header attribute

This first-class EXR target is intentionally bounded to safe flattened string attributes. It does not rewrite complete EXR files.

EmitTransferResult emit_prepared_bundle_bmff(const PreparedTransferBundle &bundle, BmffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit prepared metadata blocks into an ISO-BMFF metadata backend.

Route mapping:

  • bmff:item-exif -> Exif item payload

  • bmff:item-xmp -> mime item carrying XMP

  • bmff:item-jumb -> jumb item payload

  • bmff:item-c2pa -> c2pa item payload

  • bmff:property-colr-icc -> colr property payload with prof ICC data

EmitTransferResult compile_prepared_bundle_tiff(const PreparedTransferBundle &bundle, PreparedTiffEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable TIFF emit plan from a prepared bundle.

This maps route strings to TIFF tags once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_tiff_compiled(const PreparedTransferBundle &bundle, const PreparedTiffEmitPlan &plan, TiffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled TIFF emit plan.

EmitTransferResult compile_prepared_bundle_jxl(const PreparedTransferBundle &bundle, PreparedJxlEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable JPEG XL emit plan from a prepared bundle.

This maps route strings to JPEG XL box types once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_jxl_compiled(const PreparedTransferBundle &bundle, const PreparedJxlEmitPlan &plan, JxlTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled JPEG XL emit plan.

EmitTransferResult build_prepared_jxl_encoder_handoff_view(const PreparedTransferBundle &bundle, PreparedJxlEncoderHandoffView *out_view, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Builds one encoder-side handoff view for prepared JPEG XL metadata.

This exposes the single encoder ICC profile separately from the normal JXL box path. Boxes remain on the regular jxl:box-* route contract.

EmitTransferResult build_prepared_jxl_encoder_handoff(const PreparedTransferBundle &bundle, PreparedJxlEncoderHandoff *out_handoff, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept
PreparedJxlEncoderHandoffIoResult serialize_prepared_jxl_encoder_handoff(const PreparedJxlEncoderHandoff &handoff, std::vector<std::byte> *out_bytes) noexcept
PreparedJxlEncoderHandoffIoResult deserialize_prepared_jxl_encoder_handoff(std::span<const std::byte> bytes, PreparedJxlEncoderHandoff *out_handoff) noexcept
EmitTransferResult compile_prepared_bundle_webp(const PreparedTransferBundle &bundle, PreparedWebpEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable WebP emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_png(const PreparedTransferBundle &bundle, PreparedPngEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable PNG emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_jp2(const PreparedTransferBundle &bundle, PreparedJp2EmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable JP2 emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_exr(const PreparedTransferBundle &bundle, PreparedExrEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable EXR emit plan from a prepared bundle.

EmitTransferResult compile_prepared_bundle_bmff(const PreparedTransferBundle &bundle, PreparedBmffEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable ISO-BMFF metadata emit plan from a prepared bundle.

EmitTransferResult emit_prepared_bundle_webp_compiled(const PreparedTransferBundle &bundle, const PreparedWebpEmitPlan &plan, WebpTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled WebP emit plan.

EmitTransferResult emit_prepared_bundle_png_compiled(const PreparedTransferBundle &bundle, const PreparedPngEmitPlan &plan, PngTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled PNG emit plan.

EmitTransferResult emit_prepared_bundle_jp2_compiled(const PreparedTransferBundle &bundle, const PreparedJp2EmitPlan &plan, Jp2TransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled JP2 emit plan.

EmitTransferResult emit_prepared_bundle_exr_compiled(const PreparedTransferBundle &bundle, const PreparedExrEmitPlan &plan, ExrTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled EXR emit plan.

EmitTransferResult emit_prepared_bundle_bmff_compiled(const PreparedTransferBundle &bundle, const PreparedBmffEmitPlan &plan, BmffTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled ISO-BMFF metadata emit plan.

EmitTransferResult compile_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, PreparedJpegEmitPlan *out_plan, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Compile a reusable JPEG emit plan from a prepared bundle.

This maps route strings to marker codes once for high-throughput “prepare once, emit many” workflows.

EmitTransferResult emit_prepared_bundle_jpeg_compiled(const PreparedTransferBundle &bundle, const PreparedJpegEmitPlan &plan, JpegTransferEmitter &emitter, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Emit a prepared bundle using a precompiled JPEG emit plan.

EmitTransferResult write_prepared_bundle_jpeg(const PreparedTransferBundle &bundle, TransferByteWriter &writer, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Write prepared JPEG metadata marker bytes directly to a byte sink.

This emits serialized APP/COM marker records only. It does not write SOI, SOS/image data, or EOI.

EmitTransferResult write_prepared_bundle_jpeg_compiled(const PreparedTransferBundle &bundle, const PreparedJpegEmitPlan &plan, TransferByteWriter &writer, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Write prepared JPEG metadata marker bytes using a precompiled plan.

PrepareTransferFileResult prepare_metadata_for_target_file(const char *path, const PrepareTransferFileOptions &options = PrepareTransferFileOptions{}) noexcept

High-level helper: read file, decode metadata, and prepare transfer bundle.

This helper is intended for thin wrappers (CLI/Python) that need read -> prepare with consistent resource policies.

TransferStatus build_prepared_c2pa_sign_request(const PreparedTransferBundle &bundle, PreparedTransferC2paSignRequest *out_request) noexcept

Derive an external signer request from a prepared C2PA rewrite bundle.

The returned request is preparation-only. It does not build a manifest or perform signing. For supported targets, it exposes the deterministic rewrite-without-C2PA byte sequence as preserved source ranges plus prepared target carrier chunks.

TransferStatus build_prepared_c2pa_handoff_package(const PreparedTransferBundle &bundle, std::span<const std::byte> target_input, PreparedTransferC2paHandoffPackage *out_package) noexcept

Build a structured external-signer handoff package.

This wraps build_prepared_c2pa_sign_request and build_prepared_c2pa_sign_request_binding into one reusable core result.

TransferStatus build_prepared_c2pa_signed_package(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignerInput &input, PreparedTransferC2paSignedPackage *out_package) noexcept

Build a persistable signed-result package from a prepared bundle.

This wraps build_prepared_c2pa_sign_request and copies the external signer material into one reusable core object.

EmitTransferResult apply_prepared_c2pa_sign_result(PreparedTransferBundle *bundle, const PreparedTransferC2paSignRequest &request, const PreparedTransferC2paSignerInput &input) noexcept

Stage externally signed C2PA rewrite output into a prepared bundle.

This consumes the request built by build_prepared_c2pa_sign_request and replaces prepared target C2PA carrier blocks with the external signed logical payload. OpenMeta does not perform signing here; it only validates the input contract and re-packs the logical payload into the prepared target carrier.

EmitTransferResult apply_prepared_c2pa_signed_package(PreparedTransferBundle *bundle, const PreparedTransferC2paSignedPackage &package) noexcept

Stage one persisted signed C2PA package into a prepared bundle.

BuildPreparedC2paBindingResult build_prepared_c2pa_sign_request_binding(const PreparedTransferBundle &bundle, std::span<const std::byte> target_input, const PreparedTransferC2paSignRequest &request, std::vector<std::byte> *out_bytes) noexcept

Materialize the exact content-binding byte stream for a C2PA sign request.

This reconstructs the deterministic rewrite-without-C2PA byte sequence described by request by combining preserved source ranges from target_input with prepared target carrier chunks from bundle.

ValidatePreparedC2paSignResult validate_prepared_c2pa_sign_result(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignRequest &request, const PreparedTransferC2paSignerInput &input) noexcept

Validate one externally signed C2PA payload before staging it.

This performs the same input and payload checks used by apply_prepared_c2pa_sign_result, but does not mutate bundle.

ValidatePreparedC2paSignResult validate_prepared_c2pa_signed_package(const PreparedTransferBundle &bundle, const PreparedTransferC2paSignedPackage &package) noexcept

Validate one persisted signed C2PA package before staging it.

PreparedTransferC2paPackageIoResult serialize_prepared_c2pa_handoff_package(const PreparedTransferC2paHandoffPackage &package, std::vector<std::byte> *out_bytes) noexcept

Serialize one C2PA handoff package into a stable binary transport.

PreparedTransferC2paPackageIoResult deserialize_prepared_c2pa_handoff_package(std::span<const std::byte> bytes, PreparedTransferC2paHandoffPackage *out_package) noexcept

Parse one serialized C2PA handoff package.

PreparedTransferC2paPackageIoResult serialize_prepared_c2pa_signed_package(const PreparedTransferC2paSignedPackage &package, std::vector<std::byte> *out_bytes) noexcept

Serialize one persisted signed C2PA package into a stable binary transport.

PreparedTransferC2paPackageIoResult deserialize_prepared_c2pa_signed_package(std::span<const std::byte> bytes, PreparedTransferC2paSignedPackage *out_package) noexcept

Parse one serialized signed C2PA package.

EmitTransferResult compile_prepared_transfer_execution(const PreparedTransferBundle &bundle, const EmitTransferOptions &options, PreparedTransferExecutionPlan *out_plan) noexcept

Compile a reusable execution plan for execute_prepared_transfer_compiled.

This performs route-to-backend compilation once and stores the selected emit options inside the plan for repeated runtime execution.

EmitTransferResult build_prepared_transfer_adapter_view(const PreparedTransferBundle &bundle, PreparedTransferAdapterView *out_view, const EmitTransferOptions &options = {}) noexcept

Build one target-neutral adapter view over prepared transfer ops.

This compiles the same target-specific route mappings used by emit execution, then flattens them into one explicit operation list for host integrations that want to consume prepared blocks without parsing routes.

EmitTransferResult emit_prepared_transfer_adapter_view(const PreparedTransferBundle &bundle, const PreparedTransferAdapterView &view, TransferAdapterSink &sink) noexcept

Emit one prepared adapter view into a generic host-side sink.

This lets host integrations consume the flattened adapter operation list without re-parsing routes or target-specific dispatch tokens.

ApplyTimePatchResult apply_time_patches(PreparedTransferBundle *bundle, std::span<const TimePatchUpdate> updates, const ApplyTimePatchOptions &options = ApplyTimePatchOptions{}) noexcept

Apply fixed-width time patch updates in-place on a prepared bundle.

Patches are applied to byte ranges listed in bundle.time_patch_map (typically filled for EXIF APP1 during prepare).

ApplyTimePatchResult apply_time_patches_view(PreparedTransferBundle *bundle, std::span<const TimePatchView> updates, const ApplyTimePatchOptions &options = ApplyTimePatchOptions{}) noexcept

Apply fixed-width time patch views in-place on a prepared bundle.

This overload avoids owned patch buffers and is intended for high-throughput prepare once -> compile once -> patch/emit many integrations.

ExecutePreparedTransferResult execute_prepared_transfer(PreparedTransferBundle *bundle, std::span<const std::byte> edit_input = {}, const ExecutePreparedTransferOptions &options = ExecutePreparedTransferOptions{}) noexcept

Execute the high-level transfer flow on a prepared bundle.

This helper applies optional time patches, compiles/emits prepared blocks, and optionally plans/applies a target-stream edit using edit_input. It is intended for thin wrappers and high-throughput “prepare once, reuse” integrations.

ExecutePreparedTransferResult execute_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, std::span<const std::byte> edit_input = {}, const ExecutePreparedTransferOptions &options = ExecutePreparedTransferOptions{}) noexcept

Execute the transfer flow using a precompiled execution plan.

This is intended for high-throughput integrations that want prepare once -> compile once -> patch/emit many.

ExecutePreparedTransferResult write_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, TransferByteWriter &writer, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and stream emit bytes.

This is a thin encoder-integration helper for prepare once -> compile once -> patch -> write workflows. It reuses execute_prepared_transfer_compiled for plan validation and emission, but accepts non-owning patch views to avoid per-call owned patch buffers.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, JpegTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a JPEG backend.

This is the direct backend-emitter path for prepare once -> compile once -> patch -> emit integrations that already own a JPEG encoder/backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, TiffTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a TIFF backend.

TIFF intentionally uses backend-emitter or rewrite/edit paths instead of a metadata-only byte-writer emit contract.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, JxlTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a JPEG XL backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, WebpTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a WebP backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, PngTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a PNG backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, Jp2TransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through a JP2 backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, ExrTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through an EXR backend.

ExecutePreparedTransferResult emit_prepared_transfer_compiled(PreparedTransferBundle *bundle, const PreparedTransferExecutionPlan &plan, BmffTransferEmitter &emitter, std::span<const TimePatchView> time_patches = {}, const ApplyTimePatchOptions &time_patch = ApplyTimePatchOptions{}, uint32_t emit_repeat = 1U) noexcept

Hot-path helper: apply non-owning time patches and emit through an ISO-BMFF metadata backend.

ExecutePreparedTransferFileResult execute_prepared_transfer_file(const char *path, const ExecutePreparedTransferFileOptions &options = ExecutePreparedTransferFileOptions{}) noexcept

High-level helper: read file, prepare a bundle, then execute transfer.

This wraps prepare_metadata_for_target_file plus execute_prepared_transfer for CLI/Python entry points that want a single file-based execution path.

JpegEditPlan plan_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const PlanJpegEditOptions &options = PlanJpegEditOptions{}) noexcept

Plan JPEG metadata injection/edit strategy for a prepared bundle.

Auto selects InPlace when all emitted payloads can replace existing leading JPEG metadata segments with exact size match; otherwise it selects MetadataRewrite.

EmitTransferResult apply_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, std::vector<std::byte> *out_jpeg) noexcept

Apply a planned JPEG metadata edit and produce edited output bytes.

For InPlace, this replaces matched existing segment payload bytes in a copy of the input stream. For MetadataRewrite, this rewrites leading metadata segments and preserves the remaining codestream bytes unchanged.

EmitTransferResult write_prepared_bundle_jpeg_edit(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, TransferByteWriter &writer) noexcept

Apply a planned JPEG metadata edit and stream output bytes to a writer.

TiffEditPlan plan_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const PlanTiffEditOptions &options = PlanTiffEditOptions{}) noexcept

Plan TIFF metadata rewrite for a prepared bundle.

This computes the expected output size and validates that TIFF-applicable prepared blocks can be materialized on the target stream.

EmitTransferResult apply_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, std::vector<std::byte> *out_tiff) noexcept

Apply a planned TIFF metadata rewrite and produce edited output bytes.

EmitTransferResult write_prepared_bundle_tiff_edit(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, TransferByteWriter &writer) noexcept

Apply a planned TIFF metadata rewrite and stream output bytes to a writer.

Current implementation uses the same rewrite path as apply_prepared_bundle_tiff_edit and then writes the final bytes to the supplied sink.

EmitTransferResult build_prepared_transfer_emit_package(const PreparedTransferBundle &bundle, PreparedTransferPackagePlan *out_plan, const EmitTransferOptions &options = {}) noexcept

Build one deterministic direct-emit package plan for a prepared bundle.

Current implementation supports JPEG marker emission and JPEG XL box emission without requiring an input container byte stream.

EmitTransferResult build_prepared_bundle_jpeg_package(std::span<const std::byte> input_jpeg, const PreparedTransferBundle &bundle, const JpegEditPlan &plan, PreparedTransferPackagePlan *out_plan) noexcept
EmitTransferResult build_prepared_bundle_tiff_package(std::span<const std::byte> input_tiff, const PreparedTransferBundle &bundle, const TiffEditPlan &plan, PreparedTransferPackagePlan *out_plan) noexcept
EmitTransferResult write_prepared_transfer_package(std::span<const std::byte> input, const PreparedTransferBundle &bundle, const PreparedTransferPackagePlan &plan, TransferByteWriter &writer) noexcept
EmitTransferResult build_prepared_transfer_package_batch(std::span<const std::byte> input, const PreparedTransferBundle &bundle, const PreparedTransferPackagePlan &plan, PreparedTransferPackageBatch *out_batch) noexcept
EmitTransferResult write_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, TransferByteWriter &writer) noexcept
TransferSemanticKind classify_transfer_route_semantic_kind(std::string_view route) noexcept

Classifies one prepared transfer route into a target-neutral semantic kind.

std::string_view transfer_semantic_name(TransferSemanticKind kind) noexcept

Stable display name for one semantic transfer kind.

std::string_view prepared_transfer_artifact_kind_name(PreparedTransferArtifactKind kind) noexcept

Stable display name for one persisted transfer artifact kind.

EmitTransferResult collect_prepared_transfer_payload_views(const PreparedTransferBundle &bundle, std::vector<PreparedTransferPayloadView> *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Builds zero-copy semantic payload views over one prepared transfer bundle.

EmitTransferResult collect_prepared_transfer_payload_views(const PreparedTransferPayloadBatch &batch, std::vector<PreparedTransferPayloadView> *out) noexcept

Builds zero-copy semantic payload views over one persisted payload batch.

EmitTransferResult build_prepared_transfer_payload_batch(const PreparedTransferBundle &bundle, PreparedTransferPayloadBatch *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Builds one owned semantic payload batch from one prepared transfer bundle.

PreparedTransferPayloadIoResult serialize_prepared_transfer_payload_batch(const PreparedTransferPayloadBatch &batch, std::vector<std::byte> *out_bytes) noexcept
PreparedTransferArtifactIoResult inspect_prepared_transfer_artifact(std::span<const std::byte> bytes, PreparedTransferArtifactInfo *out_info) noexcept
PreparedTransferPayloadIoResult deserialize_prepared_transfer_payload_batch(std::span<const std::byte> bytes, PreparedTransferPayloadBatch *out_batch) noexcept
PreparedTransferPayloadReplayResult replay_prepared_transfer_payload_batch(const PreparedTransferPayloadBatch &batch, const PreparedTransferPayloadReplayCallbacks &callbacks) noexcept
EmitTransferResult collect_prepared_transfer_package_views(const PreparedTransferPackageBatch &batch, std::vector<PreparedTransferPackageView> *out) noexcept

Builds zero-copy semantic package views over one persisted package batch.

PreparedTransferPackageReplayResult replay_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, const PreparedTransferPackageReplayCallbacks &callbacks) noexcept
PreparedTransferPackageIoResult serialize_prepared_transfer_package_batch(const PreparedTransferPackageBatch &batch, std::vector<std::byte> *out_bytes) noexcept
PreparedTransferPackageIoResult deserialize_prepared_transfer_package_batch(std::span<const std::byte> bytes, PreparedTransferPackageBatch *out_batch) noexcept
void build_ocio_metadata_tree(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterOptions &options) noexcept

Builds a deterministic metadata tree for OCIO-style consumers.

Mapping rules:

  • Item names with a prefix:name form become namespace nodes (prefix) with leaf children (name=value).

  • Other names are added as direct leaves under the root.

InteropSafetyStatus build_ocio_metadata_tree_safe(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterOptions &options, InteropSafetyError *error) noexcept

Strict safe export for OCIO-style metadata tree.

Unlike build_ocio_metadata_tree, this API fails when unsafe payloads are encountered (for example raw bytes or invalid/unsafe text sequences).

OcioAdapterOptions make_ocio_adapter_options(const OcioAdapterRequest &request) noexcept

Converts OcioAdapterRequest into OcioAdapterOptions.

void build_ocio_metadata_tree(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterRequest &request) noexcept

Builds metadata tree via the stable request model.

InteropSafetyStatus build_ocio_metadata_tree_safe(const MetaStore &store, OcioMetadataNode *root, const OcioAdapterRequest &request, InteropSafetyError *error) noexcept

Request-based strict safe export for OCIO-style metadata tree.

void collect_oiio_attributes(const MetaStore &store, std::vector<OiioAttribute> *out, const OiioAdapterOptions &options) noexcept

Collects OIIO-style name/value attributes from a MetaStore.

InteropSafetyStatus collect_oiio_attributes_safe(const MetaStore &store, std::vector<OiioAttribute> *out, const OiioAdapterOptions &options, InteropSafetyError *error) noexcept

Strict safe export for OIIO-style name/value attributes.

Unlike collect_oiio_attributes, this API fails when unsafe payloads are encountered (for example invalid/unsafe text sequences). Byte payloads are normalized to safe textual form when possible and otherwise emitted as ASCII hex text.

void collect_oiio_attributes_typed(const MetaStore &store, std::vector<OiioTypedAttribute> *out, const OiioAdapterOptions &options) noexcept

Collects OIIO-style typed attributes from a MetaStore.

InteropSafetyStatus collect_oiio_attributes_typed_safe(const MetaStore &store, std::vector<OiioTypedAttribute> *out, const OiioAdapterOptions &options, InteropSafetyError *error) noexcept

Strict safe export for OIIO-style typed attributes.

Text values are validated and normalized to UTF-8 with TextEncoding::Utf8. Byte payloads are accepted only when they can be normalized to safe UTF-8 text; otherwise they are rejected.

OiioAdapterOptions make_oiio_adapter_options(const OiioAdapterRequest &request) noexcept

Converts OiioAdapterRequest into OiioAdapterOptions.

void collect_oiio_attributes(const MetaStore &store, std::vector<OiioAttribute> *out, const OiioAdapterRequest &request) noexcept

Collects OIIO-style attributes via the stable request model.

InteropSafetyStatus collect_oiio_attributes_safe(const MetaStore &store, std::vector<OiioAttribute> *out, const OiioAdapterRequest &request, InteropSafetyError *error) noexcept

Request-based strict safe export for OIIO-style name/value attributes.

void collect_oiio_attributes_typed(const MetaStore &store, std::vector<OiioTypedAttribute> *out, const OiioAdapterRequest &request) noexcept

Collects OIIO-style typed attributes via the stable request model.

InteropSafetyStatus collect_oiio_attributes_typed_safe(const MetaStore &store, std::vector<OiioTypedAttribute> *out, const OiioAdapterRequest &request, InteropSafetyError *error) noexcept

Request-based strict safe export for OIIO-style typed attributes.

EmitTransferResult collect_oiio_transfer_payload_views(const PreparedTransferBundle &bundle, std::vector<OiioTransferPayloadView> *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Builds one OIIO-facing zero-copy transfer payload list from a prepared bundle.

The returned payload views borrow both route strings and payload bytes from bundle. The caller must keep bundle alive while consuming the views.

EmitTransferResult build_oiio_transfer_payload_batch(const PreparedTransferBundle &bundle, OiioTransferPayloadBatch *out, const EmitTransferOptions &options = EmitTransferOptions{}) noexcept

Builds one owned OIIO-facing transfer payload batch from a prepared bundle.

Unlike collect_oiio_transfer_payload_views, the resulting payloads own their bytes and can outlive bundle.

EmitTransferResult collect_oiio_transfer_payload_views(const PreparedTransferPayloadBatch &batch, std::vector<OiioTransferPayloadView> *out) noexcept

Builds one zero-copy OIIO-facing payload view list from a persisted transfer payload batch.

The returned views borrow route strings and payload bytes from batch.

OiioTransferPayloadReplayResult replay_oiio_transfer_payload_batch(const PreparedTransferPayloadBatch &batch, const OiioTransferPayloadReplayCallbacks &callbacks) noexcept

Replays one persisted transfer payload batch through explicit host callbacks.

OiioTransferPayloadReplayCallbacks::emit_payload must be non-null. OiioTransferPayloadReplayCallbacks::begin_batch and OiioTransferPayloadReplayCallbacks::end_batch are optional.

EmitTransferResult collect_oiio_transfer_package_views(const PreparedTransferPackageBatch &batch, std::vector<OiioTransferPackageView> *out) noexcept

Builds one zero-copy OIIO-facing package view list from a persisted transfer package batch.

The returned views borrow route strings and chunk bytes from batch. This is the host-facing path for stable packaged transfer output that no longer depends on the original prepared bundle lifetime.

OiioTransferPackageReplayResult replay_oiio_transfer_package_batch(const PreparedTransferPackageBatch &batch, const OiioTransferPackageReplayCallbacks &callbacks) noexcept

Replays one persisted transfer package batch through explicit host callbacks.

OiioTransferPackageReplayCallbacks::emit_chunk must be non-null. OiioTransferPackageReplayCallbacks::begin_batch and OiioTransferPackageReplayCallbacks::end_batch are optional.

PhotoshopIrbDecodeResult decode_photoshop_irb(std::span<const std::byte> irb_bytes, MetaStore &store, const PhotoshopIrbDecodeOptions &options = PhotoshopIrbDecodeOptions{}) noexcept

Decodes a Photoshop IRB stream and appends resources into store.

Each resource becomes one Entry with:

A bounded interpreted subset is additionally emitted as MetaKeyKind::PhotoshopIrbField entries for fixed-layout resources:

  • ResolutionInfo (0x03ED)

  • VersionInfo (0x0421)

  • PrintFlags (0x03F3)

  • EffectiveBW (0x03FB)

  • TargetLayerID (0x0400)

  • LayersGroupInfo (0x0402)

  • JPEG_Quality (0x0406)

  • CopyrightFlag (0x040A)

  • URL (0x040B)

  • GlobalAngle (0x040D)

  • Watermark (0x0410)

  • ICC_Untagged (0x0411)

  • EffectsVisible (0x0412)

  • IDsBaseValue (0x0414)

  • IndexedColorTableCount (0x0416)

  • TransparentIndex (0x0417)

  • GlobalAltitude (0x0419)

  • SliceInfo (0x041A)

  • WorkflowURL (0x041B)

  • URL_List (0x041E)

  • IPTCDigest (0x0425)

  • PrintScaleInfo (0x0426)

  • PixelInfo / PixelAspectRatio (0x0428)

  • LayerSelectionIDs (0x042D)

  • LayerGroupsEnabledID (0x0430)

  • ChannelOptions (0x0435)

  • PrintFlagsInfo (0x2710)

  • ClippingPathName (0x0BB7)

If enabled, IPTC-IIM is additionally decoded from resource id 0x0404 (IPTC/NAA) into separate MetaKeyKind::IptcDataset entries marked as EntryFlags::Derived.

PhotoshopIrbDecodeResult measure_photoshop_irb(std::span<const std::byte> irb_bytes, const PhotoshopIrbDecodeOptions &options = PhotoshopIrbDecodeOptions{}) noexcept

Estimates Photoshop IRB decode counts using the same limits/options.

std::string_view photoshop_irb_resource_name(uint16_t resource_id) noexcept
PreviewScanResult find_preview_candidates(std::span<const std::byte> file_bytes, std::span<const ContainerBlockRef> blocks, std::span<PreviewCandidate> out, const PreviewScanOptions &options) noexcept

Finds preview candidates from already scanned blocks.

This function currently analyzes EXIF/TIFF blocks and discovers:

  • JPEGInterchangeFormat/JPEGInterchangeFormatLength pairs

  • JpgFromRaw and JpgFromRaw2 byte blobs

  • Canon CR3 PRVW UUID stream preview JPEGs

Candidates are file-relative (file_offset + size) and can be copied with extract_preview_candidate.

PreviewScanResult scan_preview_candidates(std::span<const std::byte> file_bytes, std::span<ContainerBlockRef> blocks_scratch, std::span<PreviewCandidate> out, const PreviewScanOptions &options) noexcept

Convenience wrapper that runs scan_auto first, then find_preview_candidates.

PreviewExtractResult extract_preview_candidate(std::span<const std::byte> file_bytes, const PreviewCandidate &candidate, std::span<std::byte> out, const PreviewExtractOptions &options) noexcept

Extracts bytes for one preview candidate into out.

PrintImDecodeResult decode_printim(std::span<const std::byte> bytes, MetaStore &store, const PrintImDecodeLimits &limits) noexcept

Decodes a PrintIM block and appends fields into store.

On success, this creates a new block in store containing MetaKeyKind::PrintImField entries. The original EXIF tag should still be preserved separately by the EXIF/TIFF decoder.

Field naming:

  • version for the header version (ASCII, 4 bytes)

  • 0xNNNN for each 16-bit entry id

inline void normalize_resource_policy(OpenMetaResourcePolicy *policy) noexcept

Normalizes traversal/recursion-related limits to safe defaults.

OpenMeta design goal: recursion/traversal limits should never become “unlimited” through a zero value in user policy. This helper keeps decode paths bounded for untrusted metadata.

inline OpenMetaResourcePolicy recommended_resource_policy() noexcept
inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, ExifDecodeOptions *exif, PayloadOptions *payload) noexcept
inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpDecodeOptions *xmp, ExrDecodeOptions *exr, JumbfDecodeOptions *jumbf, IccDecodeOptions *icc, IptcIimDecodeOptions *iptc, PhotoshopIrbDecodeOptions *irb) noexcept
inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpDecodeOptions *xmp, ExrDecodeOptions *exr, IccDecodeOptions *icc, IptcIimDecodeOptions *iptc, PhotoshopIrbDecodeOptions *irb) noexcept
inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, PreviewScanOptions *scan, PreviewExtractOptions *extract) noexcept
inline void apply_resource_policy(const OpenMetaResourcePolicy &policy, XmpSidecarRequest *request) noexcept
SimpleMetaResult simple_meta_read(std::span<const std::byte> file_bytes, MetaStore &store, std::span<ContainerBlockRef> out_blocks, std::span<ExifIfdRef> out_ifds, std::span<std::byte> payload, std::span<uint32_t> payload_scratch_indices, const SimpleMetaDecodeOptions &options) noexcept

Scans a file container and decodes supported metadata payloads.

Current decode support:

Caller provides the scratch buffers (blocks + decoded IFD list) to keep the data flow explicit and allocation-free.

Parameters:

  • file_bytes – Full file bytes in memory.

  • store – Destination MetaStore (entries are appended).

  • out_blocks – Scratch buffer for block scanning results.

  • out_ifds – Scratch buffer for decoded IFD references.

  • payload – Scratch buffer for reassembled EXIF payload bytes.

  • payload_scratch_indices – Scratch buffer for payload part indices.

  • options – Full decode option set (EXIF/payload/XMP/EXR/JUMBF/ICC/IPTC/IRB).

SimpleMetaResult simple_meta_read(std::span<const std::byte> file_bytes, MetaStore &store, std::span<ContainerBlockRef> out_blocks, std::span<ExifIfdRef> out_ifds, std::span<std::byte> payload, std::span<uint32_t> payload_scratch_indices, const ExifDecodeOptions &exif_options, const PayloadOptions &payload_options) noexcept

Backward-compatible overload using EXIF and payload options only.

ValidateResult validate_file(const char *path, const ValidateOptions &options = ValidateOptions{}) noexcept

Validate one file using normal OpenMeta decode + CCM checks.

Validation covers:

  • decoder status health (scan/payload/exif/xmp/exr/jumbf/c2pa)

  • optional sidecar XMP read status (--xmp-sidecar equivalent)

  • DNG/CCM query/validation issues (collect_dng_ccm_fields)

XmpDecodeResult decode_xmp_packet(std::span<const std::byte> xmp_bytes, MetaStore &store, EntryFlags flags = EntryFlags::None, const XmpDecodeOptions &options = XmpDecodeOptions{}) noexcept

Decodes an XMP packet and appends properties into store.

The decoder emits one Entry per decoded property value with:

Duplicate properties are preserved.

XmpDecodeResult measure_xmp_packet(std::span<const std::byte> xmp_bytes, const XmpDecodeOptions &options = XmpDecodeOptions{}) noexcept

Estimates XMP decode counts using the same limits/options.

This function performs a bounded decode pass into an internal scratch store and returns the same status/counter model as decode_xmp_packet.

XmpDumpResult dump_xmp_lossless(const MetaStore &store, std::span<std::byte> out, const XmpDumpOptions &options) noexcept

Emits a lossless OpenMeta dump as a valid XMP RDF/XML packet.

The output is safe-by-default:

  • Text fields are XML-escaped and additionally restricted to a safe ASCII subset.

  • Binary payloads (bytes/text/arrays/scalars) are stored as base64.

This dump is intended as a storage-agnostic sidecar format for debugging and offline workflows. It uses a private namespace (urn:openmeta:dump:1.0) and is not meant to replace standard, interoperable XMP mappings.

XmpDumpResult dump_xmp_portable(const MetaStore &store, std::span<std::byte> out, const XmpPortableOptions &options) noexcept

Emits a portable XMP sidecar packet (standard XMP schemas).

The output is safe-by-default:

  • XML reserved characters are escaped.

  • Invalid control bytes are emitted as deterministic ASCII escapes.

This mode is intended for interoperability (e.g. XMP sidecars alongside RAW/JPEG files). It emits a best-effort mapping from decoded EXIF/TIFF/GPS/IPTC-IIM fields to standard XMP properties (e.g. tiff:Make, exif:ExposureTime, exif:GPSLatitude, dc:subject, photoshop:City, Iptc4xmpCore:Location).

XmpDumpResult dump_xmp_sidecar(const MetaStore &store, std::vector<std::byte> *out, const XmpSidecarOptions &options) noexcept

Emits an XMP sidecar into a resizable byte buffer.

This is a high-level wrapper around dump_xmp_lossless and dump_xmp_portable that:

XmpSidecarOptions make_xmp_sidecar_options(const XmpSidecarRequest &request) noexcept

Converts XmpSidecarRequest into XmpSidecarOptions.

Useful for wrappers and adapters that expose one flattened option model.

XmpDumpResult dump_xmp_sidecar(const MetaStore &store, std::vector<std::byte> *out, const XmpSidecarRequest &request) noexcept

Emits an XMP sidecar using the stable XmpSidecarRequest model.

Variables

constexpr uint32_t kExrCanonicalEncodingVersion = 1U

Stable EXR canonical value encoding contract version.

constexpr uint32_t kInteropExportContractVersion = 1U

Stable interop export naming contract version.

static constexpr BlockId kInvalidBlockId = 0xffffffffU
static constexpr EntryId kInvalidEntryId = 0xffffffffU
constexpr uint32_t kMetadataTransferContractVersion = 1U

Stable metadata transfer contract version.

file exr_canonical_value_encoding.md
file development.md
file doxygen.md
file metadata_backend_matrix.md
file metadata_support.md
file metadata_transfer_plan.md
file openexr_metadata_fit.md
file README.md
file build_info.h
#include <string>
#include <string_view>

Runtime information about how OpenMeta was built.

file byte_arena.h
#include <cstddef>
#include <cstdint>
#include <span>
#include <string_view>
#include <vector>

Append-only byte arena used to store metadata payloads and strings.

file ccm_query.h
#include “openmeta/meta_store.h”
#include <cstdint>
#include <string>
#include <vector>

Query helpers for normalized DNG/RAW color matrix metadata.

file console_format.h
#include <cstddef>
#include <cstdint>
#include <span>
#include <string>
#include <string_view>
file container_payload.h
#include “openmeta/container_scan.h”
#include <cstddef>
#include <cstdint>
#include <span>

Reassembles and optionally decompresses logical metadata payloads.

file container_scan.h
#include <cstddef>
#include <cstdint>
#include <span>

Container scanners that locate metadata blocks within file bytes.

file exif_tag_names.h
#include <cstdint>
#include <string_view>

Human-readable names for common EXIF/TIFF tags.

file exif_tiff_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>
#include <string_view>

Decoder for TIFF-IFD tag streams (used by EXIF and TIFF/DNG).

file exr_adapter.h
#include “openmeta/exr_decode.h”
#include “openmeta/meta_store.h”
#include “openmeta/metadata_transfer.h”
#include <cstddef>
#include <cstdint>
#include <limits>
#include <string>
#include <vector>

EXR-native attribute bridge for OpenEXR-style host integrations.

file exr_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for OpenEXR header attributes.

file geotiff_key_names.h
#include <cstdint>
#include <string_view>

GeoTIFF GeoKey name lookup.

file icc_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for ICC profile blobs (header + tag table).

file icc_interpret.h
#include <cstddef>
#include <cstdint>
#include <span>
#include <string>
#include <string_view>
#include <vector>

Selected ICC tag-name and tag-payload interpretation helpers.

file interop_export.h
#include “openmeta/meta_store.h”
#include <cstdint>
#include <string>
#include <string_view>

Metadata export traversal API for interop adapters.

file iptc_iim_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for IPTC-IIM dataset streams.

file jumbf_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for JUMBF/C2PA payload blocks.

file mapped_file.h
#include <cstddef>
#include <cstdint>
#include <span>

Read-only file mapping helper.

file meta_edit.h
#include “openmeta/meta_store.h”
#include <span>
#include <vector>

Batch edit operations for MetaStore (append/set/tombstone).

file meta_flags.h
#include <cstdint>

Flags attached to metadata entries.

file meta_key.h
#include “openmeta/byte_arena.h”
#include <cstdint>
#include <string_view>

Normalized key identifiers for EXIF/IPTC/XMP/etc. metadata entries.

file meta_store.h
#include “openmeta/byte_arena.h”
#include “openmeta/meta_flags.h”
#include “openmeta/meta_key.h”
#include “openmeta/meta_value.h”
#include <cstdint>
#include <span>
#include <vector>

In-memory representation of decoded metadata (keys/values + provenance).

file meta_value.h
#include “openmeta/byte_arena.h”
#include <cstdint>
#include <span>
#include <string_view>

Typed metadata value representation (scalar/array/bytes/text).

file metadata_transfer.h
#include “openmeta/meta_store.h”
#include “openmeta/resource_policy.h”
#include “openmeta/simple_meta.h”
#include “openmeta/xmp_dump.h”
#include <array>
#include <cstddef>
#include <cstdint>
#include <cstring>
#include <span>
#include <string>
#include <string_view>
#include <vector>

Draft metadata transfer bundle and backend emitter contracts.

This header defines a stable draft contract for “prepare once, emit many” metadata transfer workflows.

file ocio_adapter.h
#include “openmeta/interop_export.h”
#include <cstdint>
#include <string>
#include <vector>

Adapter helpers for OCIO-style metadata trees.

file oiio_adapter.h
#include “openmeta/interop_export.h”
#include “openmeta/metadata_transfer.h”
#include <cstddef>
#include <cstdint>
#include <limits>
#include <span>
#include <string>
#include <string_view>
#include <vector>

Adapter helpers for OIIO-style metadata export.

file photoshop_irb_decode.h
#include “openmeta/iptc_iim_decode.h”
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>
#include <string_view>

Decoder for Photoshop Image Resource Blocks (IRB / 8BIM resources).

file preview_extract.h
#include “openmeta/container_scan.h”
#include <cstddef>
#include <cstdint>
#include <span>

Read-only preview/thumbnail candidate discovery and extraction.

file printim_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for the EXIF PrintIM (0xC4A5) embedded block.

file resource_policy.h
#include “openmeta/container_payload.h”
#include “openmeta/exif_tiff_decode.h”
#include “openmeta/exr_decode.h”
#include “openmeta/icc_decode.h”
#include “openmeta/iptc_iim_decode.h”
#include “openmeta/jumbf_decode.h”
#include “openmeta/photoshop_irb_decode.h”
#include “openmeta/preview_extract.h”
#include “openmeta/xmp_decode.h”
#include “openmeta/xmp_dump.h”
#include <cstdint>

Draft resource-budget policy for OpenMeta read/dump workflows.

file simple_meta.h
#include “openmeta/container_payload.h”
#include “openmeta/container_scan.h”
#include “openmeta/exif_tiff_decode.h”
#include “openmeta/exr_decode.h”
#include “openmeta/icc_decode.h”
#include “openmeta/iptc_iim_decode.h”
#include “openmeta/jumbf_decode.h”
#include “openmeta/meta_store.h”
#include “openmeta/photoshop_irb_decode.h”
#include “openmeta/xmp_decode.h”
#include <cstddef>
#include <span>

High-level “read” helper for scanning containers and decoding metadata.

file validate.h
#include “openmeta/ccm_query.h”
#include “openmeta/jumbf_decode.h”
#include “openmeta/resource_policy.h”
#include “openmeta/simple_meta.h”
#include <cstdint>
#include <string>
#include <vector>

High-level metadata validation API (decode health + DNG/CCM checks).

file xmp_decode.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>

Decoder for XMP packets (RDF/XML).

file xmp_dump.h
#include “openmeta/meta_store.h”
#include <cstddef>
#include <cstdint>
#include <span>
#include <vector>

XMP sidecar generation for a decoded MetaStore.

page Canonical EXR Value Encoding in OpenMeta

Status: baseline contract (v1)

Scope

This defines how OpenEXR attribute values should be represented in MetaValue and Origin/WireType so decode/edit/write logic stays deterministic and lossless.

Keying is handled separately by MetaKeyKind::ExrAttribute with:

  • part_index (EXR part id)

  • name (attribute name)

Wire Type Contract

  • Origin::wire_type.family = WireFamily::Other

  • Origin::wire_type.code = exr_attribute_type_t numeric value

  • Origin::wire_count stores raw attribute byte size (current implementation)

For unknown/user-defined EXR attribute types, preserve:

  • raw payload bytes in MetaValueKind::Bytes

  • type string in Origin::wire_type_name (optional decode behavior)

Canonical Mapping Table

  • EXR_ATTR_INT -> Scalar + I32

  • EXR_ATTR_FLOAT -> Scalar + F32

  • EXR_ATTR_DOUBLE -> Scalar + F64

  • EXR_ATTR_RATIONAL -> Scalar + SRational (num, denom)

  • EXR_ATTR_STRING -> Text + Utf8 (best effort, fallback Unknown)

  • EXR_ATTR_STRING_VECTOR -> Bytes (current), planned structured helper API for element iteration

  • EXR_ATTR_V2I/V3I -> Array + I32 (count 2/3)

  • EXR_ATTR_V2F/V3F -> Array + F32 (count 2/3)

  • EXR_ATTR_V2D/V3D -> Array + F64 (count 2/3)

  • EXR_ATTR_M33F -> Array + F32 (count 9, row-major)

  • EXR_ATTR_M33D -> Array + F64 (count 9, row-major)

  • EXR_ATTR_M44F -> Array + F32 (count 16, row-major)

  • EXR_ATTR_M44D -> Array + F64 (count 16, row-major)

  • EXR_ATTR_BOX2I -> Array + I32 (count 4: min.x,min.y,max.x,max.y)

  • EXR_ATTR_BOX2F -> Array + F32 (count 4: min.x,min.y,max.x,max.y)

  • Enum-like attrs (compression, lineorder, envmap, deepImageState) -> Scalar + U8

  • Struct/blob attrs (chlist, preview, bytes, opaque) -> Bytes for lossless core storage; typed helper decode APIs should be layered on top.

  • Current decode additionally normalizes:

    • EXR_ATTR_TIMECODE -> Array + U32 (2 values)

    • EXR_ATTR_KEYCODE -> Array + I32 (7 values)

    • EXR_ATTR_TILEDESC -> Array + U8 (9 raw bytes)

Rationale

  1. Keep MetaStore compact and storage-agnostic.

  2. Guarantee lossless round-trip for all EXR attributes, including unknown ones.

  3. Avoid hard-coding large per-type structs in core until a stable EXR read/write adapter lands.

Open Questions

  1. Whether string_vector should become first-class Array + Text rather than a packed-bytes representation.

  2. Where to attach EXR type_name for unknown/custom attrs without bloating all entries.

  3. Whether chlist should get a dedicated typed view API in v1 or remain bytes in core with helper parsing only.

page development

#Development

See also: docs/metadata_support.md for current container/block/decode support.

page Documentation

OpenMeta uses Doxygen for API extraction. For the “site” style docs (like OIIO), we render Doxygen XML via Sphinx + Breathe.

Requirements

  • doxygen (optional: graphviz for diagrams)

  • For Sphinx docs: Python packages listed in docs/requirements.txt

Generate API docs (CMake)

Enable docs and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENMETA_BUILD_DOCS=ON
cmake --build build --target openmeta_docs

Output goes to build/docs/doxygen/html/index.html inside the build directory.

When OPENMETA_BUILD_DOCS=ON, docs are also generated during install:

cmake --build build --target install

Generate site docs (Sphinx)

Enable Sphinx docs and build:

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DOPENMETA_BUILD_SPHINX_DOCS=ON
cmake --build build --target openmeta_docs_sphinx

Output goes to build/docs/html/index.html. Doxygen XML goes to build/docs/doxygen/xml/index.xml.

Publish on GitHub Pages

The repository includes a GitHub Actions workflow at .github/workflows/docs-pages.yml that builds the Sphinx site and publishes it to GitHub Pages.

Recommended setup:

  • In the repository settings, set Pages to GitHub Actions as the source. This is a one-time repository setting.

  • Pull requests build the docs but do not deploy.

  • Pushes to main and tag pushes build and deploy the site.

The workflow only runs when docs inputs change: docs/**, src/include/**, README.md, SECURITY.md, NOTICE.md, CMakeLists.txt, or the workflow itself.

Generate API docs (manual)

From the OpenMeta/ repo root:

doxygen docs/Doxyfile

Output goes to build/docs/doxygen/html/index.html.

What gets documented

  • Markdown: README.md is used as the main page.

  • Public API: everything under src/include/openmeta/.

If you add new public headers or APIs, prefer documenting at the header or type/function level so the docs stay accurate as code moves.

page Metadata Backend Matrix (Draft)

Date: March 5, 2026

Goal

Define one OpenMeta write/transfer contract that can target multiple container backends without per-backend metadata logic duplication.

Capability Matrix

Backend

Native metadata write primitives

Best use in OpenMeta

libjpeg-turbo

jpeg_write_marker, jpeg_write_m_header, jpeg_write_m_byte, jpeg_write_icc_profile

Primary JPEG metadata emitter (APP1/APP2/APP13 direct control)

libtiff

TIFFSetField, TIFFCreateEXIFDirectory, TIFFCreateGPSDirectory, TIFFWriteCustomDirectory, TIFFMergeFieldInfo

Primary TIFF metadata emitter (native tag and IFD path)

libjxl

JxlEncoderUseBoxes, JxlEncoderAddBox, JxlEncoderCloseBoxes, JxlEncoderSetICCProfile

Primary JXL metadata emitter (Exif, xml, jumb, optional brob) plus encoder ICC profile

OpenImageIO

Plugin-level writes use backend APIs (JPEG/TIFF/JXL/OpenEXR)

Optional adapter layer when host app already writes through OIIO

OpenEXR

Header::insert, typed attributes, OpaqueAttribute for unknown attr types

EXR header attribute path (not EXIF block packaging)

Container-Level Notes

JPEG (libjpeg-turbo)

  • Write EXIF as APP1 (Exif\\0\\0 + TIFF payload).

  • Write XMP as APP1 (\\0 + packet).

  • Write IPTC/IRB as APP13 (Photoshop 3.0 resource block layout).

  • Write ICC as APP2 chunk chain (ICC_PROFILE header + sequence index/count).

  • OpenMeta should own marker ordering policy and payload splitting limits.

TIFF (libtiff)

  • EXIF/GPS should be written as directories and linked from root IFD pointers.

  • XMP uses TIFFTAG_XMLPACKET (700).

  • IPTC uses TIFFTAG_RICHTIFFIPTC / TIFFTAG_EP_IPTC_NAA (33723 alias).

  • Photoshop IRB uses TIFFTAG_PHOTOSHOP (34377).

  • ICC uses TIFFTAG_ICCPROFILE (34675).

  • OpenMeta should own EXIF serializer policy before TIFFSetField.

  • Public OpenMeta fast path is backend-emitter or rewrite/edit based: emit_prepared_transfer_compiled(..., TiffTransferEmitter&) or write_prepared_bundle_tiff_edit(...).

  • TIFF intentionally does not expose a metadata-only byte-writer emit API.

JXL (libjxl)

  • Metadata requires container boxes enabled.

  • Add Exif, xml, jumb boxes through JxlEncoderAddBox.

  • Set ICC through JxlEncoderSetICCProfile; ICC is not a JXL metadata box.

  • Exif box content must include the 4-byte TIFF header offset prefix.

  • Optional Brotli-compressed box storage (brob) is backend-controlled.

  • OpenMeta should prepare box payloads once and reuse in emit path.

  • Current OpenMeta transfer support on this path is intentionally bounded: EXIF/XMP are prepared and emitted through JxlTransferEmitter, ICC is prepared as jxl:icc-profile and emitted through the encoder ICC path, file-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as JXL boxes, can generate a draft unsigned invalidation payload for content-bound source C2PA, and store-only prepare can project decoded non-C2PA JumbfCborKey roots into generic JXL jumb boxes. IPTC requested for JXL is projected into the xml XMP box; there is no raw IPTC-IIM JXL route. build_prepared_jxl_encoder_handoff_view(...) is the explicit OpenMeta encoder-side ICC contract for JXL, and build_prepared_jxl_encoder_handoff(...) / serialize_prepared_jxl_encoder_handoff(...) add the owned persisted form of that handoff: one optional jxl:icc-profile payload plus the remaining JXL box counts. The JXL compile/emit path rejects multiple prepared ICC profiles so that handoff contract matches backend execution. inspect_prepared_transfer_artifact(...) is the shared persisted-artifact inspect path across payload batches, package batches, persisted C2PA handoff/signed packages, and persisted JXL encoder handoffs. build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can also serialize direct JXL box bytes from prepared bundles, and execute_prepared_transfer(...) can use that same box-only serializer through emit_output_writer. OpenMeta also supports a bounded file-level JXL edit path that preserves the signature and non-managed top-level boxes, replaces only the metadata families present in the prepared bundle, and appends the prepared JXL boxes to an existing container file. Unrelated source JXL metadata boxes are preserved, and uncompressed source jumb boxes are distinguished as generic JUMBF vs C2PA for that replacement decision. When Brotli support is available, the same family check also covers compressed brob(realtype=jumb) source boxes. The byte-writer/file-edit path still does not serialize jxl:icc-profile; ICC remains encoder-only. The bounded external-signer path now also supports JXL jumb staging for content-bound C2PA rewrite on top of that edit path; full in-process re-sign remains out of scope.

WebP (RIFF metadata chunks)

  • Metadata is carried as RIFF chunks, not TIFF tags or BMFF boxes.

  • Standard chunk carriers:

    • EXIF

    • XMP

    • ICCP

    • bounded C2PA

  • OpenMeta now has a bounded WebP transfer path on the core transfer API: prepare_metadata_for_target(..., TransferTargetFormat::Webp, ...), compile_prepared_bundle_webp(...), emit_prepared_bundle_webp(...), emit_prepared_bundle_webp_compiled(...), and emit_prepared_transfer_compiled(..., WebpTransferEmitter&).

  • IPTC requested for WebP is projected into the existing XMP chunk; OpenMeta does not create a raw IPTC-IIM WebP carrier.

  • build_prepared_transfer_emit_package(...) plus write_prepared_transfer_package(...) can serialize direct WebP chunk bytes from prepared bundles, and the owned package batch/replay path can persist or hand off those bytes without keeping the source bundle alive.

  • Full WebP file rewrite/edit and signed C2PA rewrite/re-sign are still outside the current WebP transfer contract.

ISO-BMFF metadata items (HEIF / AVIF / CR3)

  • This bounded transfer path is metadata-item/property oriented. OpenMeta now also supports a bounded append-style BMFF metadata edit path over an existing BMFF target file.

  • Current prepared item routes:

    • bmff:item-exif

    • bmff:item-xmp

    • bmff:item-jumb

    • bmff:item-c2pa

  • Current prepared property routes:

    • bmff:property-colr-icc

  • EXIF item payloads use the BMFF Exif item shape:

    • 4-byte big-endian TIFF offset prefix

    • followed by full Exif\0\0 bytes

  • IPTC requested for BMFF is projected into bmff:item-xmp; OpenMeta does not create a raw IPTC-IIM BMFF carrier.

  • ICC requested for BMFF uses the bounded property path:

    • bmff:property-colr-icc

    • payload bytes are u32be(‘prof) + <icc-profile>

    • this is acolrproperty payload, not a metadata item

  • File-based prepare can preserve source generic JUMBF payloads and raw OpenMeta draft C2PA invalidation payloads as BMFF metadata items.

  • Store-only prepare can project decoded non-C2PAJumbfCborKeyroots into bmff:item-jumbwhen no raw source payload is available.

  • Core emitter surface: -compile_prepared_bundle_bmff(…) -emit_prepared_bundle_bmff(…) -emit_prepared_bundle_bmff_compiled(…) -emit_prepared_transfer_compiled(…, BmffTransferEmitter&)

  • The shared package-batch persistence/replay layer can own and hand off stable BMFF item and property payload bytes. -metatransfer/openmeta.transfer_probe(…)expose BMFF summaries, includingbmff_property colr/prof …. -metatransfer &#8212;target-heif|&#8212;target-avif|&#8212;target-cr3 &#8212;source-meta … -o … now performs bounded metadata-only edit by appending one OpenMeta-authored metadata-only top-levelmetabox and replacing any prior OpenMeta-authored metadata-onlymetabox from the same bounded contract.

  • The same bounded BMFF edit contract now also participates in the core / file-helper C2PA signer path:

  • Out of scope for the current BMFF contract:

EXR (OpenEXR)

Unified Workaround (Single Contract)

Use one two-phase pipeline for all backends:

This keeps heavy work out of hot per-frame loops.

Backend Interface Shape (Draft)

Define narrow backend interfaces:

OpenMeta core emits backend-neutral prepared payloads. Backends only perform container call mapping.

Policy Defaults (Draft)

Recommended Integration Order

This order aligns with fast transfer requirements and minimal overhead in high-FPS pipelines.

page Metadata Support Matrix (Draft)

This document summarizes the current read-path coverage in OpenMeta.

It is meant to answer four basic questions:

  • which containers are scanned

  • which metadata families are decoded into MetaStore

  • where display-name mapping exists

  • what can be dumped or exported today

Status Labels

  • Yes: supported in current code

  • Partial: supported, but still bounded or best-effort

  • No: not supported yet

Coverage Snapshot

Current tracked-gate status:

  • EXIF tag-id compare gates are passing on tracked HEIC/HEIF, CR3, and mixed RAW corpora.

  • EXR header metadata compare is passing for the documented name/type/value-class contract.

  • Sidecar export paths (lossless and portable) are covered by baseline and smoke tests.

  • MakerNote coverage is tracked by baseline gates with broad vendor support; unknown vendor tags are preserved as raw metadata for lossless workflows.

  • BMFF edge-path tests include iloc construction-method-2 relation variants and safe-skip handling for invalid references.

Container Coverage

Container / input type

Block discovery

Structured decode in simple_meta_read(...)

Notes

JPEG

Yes

Yes

EXIF, XMP, extended XMP, ICC, MPF, Photoshop IRB, comments, vendor APP blocks, and bounded JUMBF/C2PA

PNG

Yes

Yes

EXIF, XMP, ICC, structured PNG text, and bounded JUMBF/C2PA

WebP

Yes

Yes

EXIF, XMP, ICC, and bounded JUMBF/C2PA

GIF

Yes

Partial

XMP, ICC, and structured comments

TIFF / DNG / TIFF-based RAW

Yes

Yes

EXIF, MakerNote, XMP, IPTC, Photoshop IRB, ICC, GeoTIFF, and bounded JUMBF/C2PA

CRW / CIFF

Yes

Partial

Derived EXIF bridge plus bounded native Canon CIFF naming and projection

RAF / X3F

Partial

Partial

Mainly embedded-TIFF follow path with best-effort extras

JP2

Yes

Yes

EXIF, XMP, IPTC, ICC, and GeoTIFF

JXL

Yes

Yes

EXIF, XMP, and bounded JUMBF/C2PA; supported brob wrapped metadata is decoded

HEIF / AVIF / CR3

Yes

Partial

EXIF, XMP, ICC, CR3 maker blocks, BMFF derived fields, and bounded JUMBF/C2PA

EXR

n/a via scan_auto(...)

Yes

Header attributes only; no pixel decode

Metadata Family Coverage

Metadata family

Decode

Name mapping

Dump / export

Notes

EXIF (MetaKeyKind::ExifTag)

Yes

Yes

Yes

Standard EXIF plus pointer IFDs

MakerNote

Partial / Yes

Partial / Yes

Lossless yes; portable limited

Broad vendor coverage; unknown tags may remain raw

XMP (MetaKeyKind::XmpProperty)

Yes

Native schema/path

Yes

Requires Expat at build time

ICC (IccHeaderField, IccTag)

Yes

Yes

Yes

Header fields plus tag table; raw tag payload preserved

IPTC-IIM (IptcDataset)

Yes

Yes

Yes

Raw dataset bytes preserved

Photoshop IRB (PhotoshopIrb)

Yes

Partial / Yes

Yes

Raw resources preserved plus a bounded interpreted subset

MPF

Yes

Yes

Yes

Basic TIFF-IFD decode

GeoTIFF (GeotiffKey)

Yes

Yes

Yes

GeoKeyDirectoryTag decode

BMFF derived fields (BmffField)

Yes

Yes

Yes

ftyp, item-info, iref, graph summaries, aux semantics, and bounded primary-linked image roles

JUMBF / C2PA (JumbfField, JumbfCborKey)

Partial

Yes

Yes

Draft structural and semantic layer; not full conformance

EXR attributes (ExrAttribute)

Yes

Native names

Yes

Header attributes only

Important Bounded Areas

CRW / CIFF

OpenMeta now does more than a pure derived-EXIF bridge:

  • common native CIFF tags are named

  • a bounded set of native subtables is projected

  • stable scalar native CIFF fields are decoded where the layout is clear

It is still a partial lane compared to the deepest legacy Canon tooling.

Photoshop IRB

OpenMeta preserves raw IRB resources and also decodes a bounded interpreted subset. That subset includes common fixed-layout resources such as:

  • ResolutionInfo

  • VersionInfo

  • PrintFlags

  • JPEG_Quality

  • PrintScaleInfo

  • PixelInfo

  • ChannelOptions

  • PrintFlagsInfo

  • ClippingPathName

This is useful, but it is still not full Photoshop-resource parity.

BMFF (<tt>HEIF</tt> / <tt>AVIF</tt> / <tt>CR3</tt>)

OpenMeta now has a bounded semantic model on top of raw item discovery:

  • ftyp.*

  • primary item properties

  • iinf/infe item-info rows

  • typed iref.<type>.* rows

  • graph summaries

  • auxC-typed auxiliary semantics

  • bounded primary-linked image-role fields

This is intentionally smaller than a full QuickTime/BMFF semantic model.

JXL

OpenMeta decodes:

  • direct Exif

  • direct xml

  • direct jumb

  • direct c2pa

  • wrapped brob forms for those same realtypes

Other brob realtypes are still out of scope.

JUMBF / C2PA

Current support is intentionally draft:

  • structural BMFF box decode

  • bounded CBOR traversal

  • draft c2pa.semantic.* projection

  • draft verify scaffolding

What this means in practice:

  • OpenMeta can expose useful manifest / claim / signature / ingredient shape information

  • OpenMeta does not yet claim full C2PA manifest semantics, trust semantics, or full policy validation

Tool-Level Behavior

Tool

Purpose

Current state

metaread

Human-readable metadata listing

Shows decoded entries with mapped names where available

metavalidate

Metadata validation

Reports decode-status and validation issues with machine-readable issue codes

metadump

Sidecar and preview dump tool

Supports lossless and portable sidecar output plus preview extraction

thumdump

Preview extractor

Extracts embedded preview candidates

metatransfer

Transfer/edit smoke tool

Exercises the transfer core for supported target families

Main Current Gaps

  • HEIF/AVIF scene semantics beyond the current bounded primary-linked role surface

  • additional JXL brob realtypes beyond Exif, xml, jumb, and c2pa

  • full JUMBF/C2PA semantics and policy validation

  • deeper RAF / X3F native semantics beyond embedded-TIFF follow paths

  • broader Photoshop IRB interpretation beyond the current bounded subset

Related Docs

page Metadata Transfer Plan (Draft)

Date: March 5, 2026

Related:

Goal

The transfer core is for metadata-only workflows:

  • source: camera RAW and other supported inputs

  • target: export-oriented container metadata

  • scope: prepare once, then emit or edit many times

Pixel transcoding is out of scope.

Design Rule

Transfer should not bottleneck high-throughput pipelines.

The core rule is:

  • do the expensive work once during prepare

  • reuse prebuilt metadata payloads during compile and emit

  • keep per-frame work limited to optional time patching plus final container write calls

Current Status

Current planning estimate for this lane: about 80-85%.

Source-side readiness is already strong:

  • tracked EXIF read gates are green on HEIC/HEIF, CR3, and mixed RAW corpora

  • tracked MakerNote gates are green

  • portable XMP gates are green

  • EXR header interop gates are green

The main remaining work is now on the target side.

The first public write-side sync controls are also in place:

  • generated XMP can explicitly suppress EXIF-derived projection

  • generated XMP can explicitly suppress IPTC-derived projection

  • prepared bundles record those resolved projection decisions alongside the existing preservation policies

Target Status Matrix

Target

Status

Current shape

Main limits

JPEG

First-class

Prepared bundle, compiled emit, byte-writer emit, edit planning/apply, file helper, bounded JUMBF/C2PA staging

Not a full arbitrary metadata editor yet

TIFF

First-class

Prepared bundle, compiled emit, classic-TIFF and BigTIFF edit planning/apply, bounded ifd1 chain rewrite with preserved downstream page tails, bounded TIFF/DNG-style SubIFD rewrite with preserved downstream auxiliary tails and preserved trailing existing children when only the front subset is replaced, file helper, streaming edit path

Broader TIFF/DNG rewrite coverage is still narrower than JPEG

PNG

Bounded but real

Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip

Not a general PNG chunk editor

WebP

Bounded but real

Prepared bundle, compiled emit, bounded chunk rewrite/edit, file-helper roundtrip

Not a general WebP chunk editor

JP2

Bounded but real

Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip

jp2h synthesis is still out of scope

JXL

Bounded but real

Prepared bundle, compiled emit, bounded box rewrite/edit, file-helper roundtrip

Still narrower than JPEG/TIFF

HEIF / AVIF / CR3

Bounded but real

Prepared bundle, compiled emit, bounded BMFF item/property edit, file-helper roundtrip

Not broad BMFF writer parity

EXR

Bounded but real

Prepared bundle, compiled emit, direct backend attribute emit, prepared-bundle to ExrAdapterBatch bridge, CLI/Python transfer surface

No file rewrite/edit path yet; current transfer payload is safe string attributes only

What Is Already Implemented

Core API

The shared transfer core already provides:

  • prepare_metadata_for_target(...)

  • prepare_metadata_for_target_file(...)

  • compile_prepared_transfer_execution(...)

  • execute_prepared_transfer(...)

  • execute_prepared_transfer_compiled(...)

  • execute_prepared_transfer_file(...)

This supports both:

  • prepare -> compile -> emit

  • prepare -> compile -> patch -> emit/edit

Core Utility Layers

These support the public transfer flow:

  • TransferByteWriter

  • SpanTransferByteWriter

  • prepared payload and package batch persistence

  • adapter views for host integrations

  • explicit time-patch support for fixed-width EXIF date/time fields

  • transfer-policy decisions for MakerNote, JUMBF, C2PA, EXIF-to-XMP projection, and IPTC-to-XMP projection

Current File-Helper Regression Coverage

OpenMeta now has explicit end-to-end read-backed transfer tests for:

  • source JPEG -> JPEG edit/apply -> read-back

  • source JPEG -> TIFF edit/apply -> read-back

  • source JPEG -> TIFF edit/apply with ifd1 -> read-back

  • source TIFF/BigTIFF with existing multi-page ifd1 -> next chain -> replace ifd1 -> preserve downstream tail

  • source DNG-like TIFF with subifd0 + ifd1 -> TIFF edit/apply -> read-back

  • source DNG-like TIFF with subifd0 + ifd1 -> BigTIFF edit/apply -> read-back

  • source TIFF/BigTIFF with existing subifd0 -> next auxiliary chain -> replace subifd0 -> preserve downstream auxiliary tail

  • source JPEG -> PNG edit/apply -> read-back

  • source JPEG -> WebP edit/apply -> read-back

  • source JPEG -> JP2 edit/apply -> read-back

  • source JPEG -> JXL edit/apply -> read-back

  • source JPEG -> HEIF edit/apply -> read-back

  • source JPEG -> AVIF edit/apply -> read-back

  • source JPEG -> CR3 edit/apply -> read-back

That does not make all targets equally mature, but it does mean the transfer core has real roundtrip regression gates across the primary supported export families.

Per-Target Notes

JPEG

Strongest current target.

Implemented:

  • EXIF as APP1

  • XMP as APP1

  • ICC as APP2

  • IPTC as APP13

  • edit planning and apply

  • byte-writer emit

  • bounded JUMBF/C2PA staging

TIFF

Also a first-class target.

Implemented:

  • EXIF, XMP, ICC, and IPTC transfer

  • edit planning and apply

  • classic-TIFF and BigTIFF rewrite support

  • bounded ifd1 chain rewrite support, including preserving an existing downstream page tail when ifd1 is replaced

  • bounded TIFF/DNG-style SubIFD rewrite support, including preserving an existing downstream auxiliary tail when subifdN is replaced

  • bounded front-subset SubIFD replacement that preserves trailing existing children from the target file

  • bounded DNG-style merge policy in the file-helper path: source-supplied preview/aux front structures replace the target front structures, while existing target page tails and trailing auxiliary children are preserved

  • file-based helper flow

  • streaming edit output

PNG

Implemented as a bounded chunk target:

  • eXIf

  • XMP iTXt

  • iCCP

  • bounded rewrite/edit for managed metadata chunks

WebP

Implemented as a bounded RIFF metadata target:

  • EXIF

  • XMP

  • ICCP

  • bounded C2PA

  • bounded rewrite/edit for managed metadata chunks

JP2

Implemented as a bounded box target:

  • Exif

  • xml

  • bounded jp2h / colr

  • bounded rewrite/edit for top-level managed metadata

  • replacement of managed colr in an existing jp2h

JXL

Implemented as a bounded box target:

  • Exif

  • xml

  • bounded jumb

  • bounded c2pa

  • encoder ICC handoff

  • bounded box-based edit path

HEIF / AVIF / CR3

Implemented as a bounded BMFF target family:

  • bmff:item-exif

  • bmff:item-xmp

  • bounded bmff:item-jumb

  • bounded bmff:item-c2pa

  • bounded bmff:property-colr-icc

  • bounded metadata-only meta rewrite path

EXR

Implemented today as a bounded first-class target:

  • prepare_metadata_for_target(...)

  • prepare_metadata_for_target_file(...)

  • compile_prepared_transfer_execution(...)

  • emit_prepared_bundle_exr(...)

  • emit_prepared_transfer_compiled(...)

  • public CLI/Python --target-exr transfer surface

It still keeps the older integration bridge:

  • build_exr_attribute_batch(...)

  • build_exr_attribute_part_spans(...)

  • build_exr_attribute_part_views(...)

  • replay_exr_attribute_batch(...)

The transfer lane now also exposes:

  • build_prepared_exr_attribute_batch(...)

  • build_exr_attribute_batch_from_file(...)

  • Python build_exr_attribute_batch_from_file(...) for direct file-to-batch host-side inspection without going through the generic transfer probe

  • Python helper wrappers: openmeta.python.probe_exr_attribute_batch(...) and openmeta.python.get_exr_attribute_batch(...)

That keeps EXR host integrations on the transfer path: callers can prepare one TransferTargetFormat::Exr bundle, then materialize a native ExrAdapterBatch without re-projecting from the source MetaStore.

Current EXR transfer scope is intentionally conservative:

  • safe flattened string header attributes

  • backend emission through ExrTransferEmitter

  • no general file-based EXR metadata rewrite/edit path yet

  • no typed EXR attribute synthesis beyond the current safe string projection

Transfer Policies

The public transfer contract now models five policy subjects:

  • MakerNote

  • JUMBF

  • C2PA

  • XMP EXIF projection

  • XMP IPTC projection

Each uses explicit TransferPolicyAction values:

  • Keep

  • Drop

  • Invalidate

  • Rewrite

Prepared bundles also record the resolved policy decisions and reasons so callers do not have to infer behavior from warning text alone.

For the XMP projection subjects, the current public knobs are intentionally simple:

  • EXIF-derived properties can be mirrored into generated XMP or suppressed

  • IPTC-derived properties can be mirrored into generated XMP or suppressed

  • generated portable XMP can choose how existing decoded XMP conflicts with generated EXIF/IPTC mappings

This gives callers stable write-side control over the most important projection behavior without forcing them to reverse-engineer the transfer output.

Write-Side Sync Controls

OpenMeta now has a bounded public sync-policy layer for generated XMP.

Current controls:

  • xmp_project_exif

  • xmp_project_iptc

  • xmp_conflict_policy

  • xmp_existing_sidecar_mode on the file-read/prepare path:

    • Ignore

    • MergeIfPresent

  • xmp_existing_sidecar_precedence on the file-read/prepare path:

    • SidecarWins

    • SourceWins

  • xmp_writeback_mode on the file-helper execution path:

    • EmbeddedOnly

    • SidecarOnly

    • EmbeddedAndSidecar

  • xmp_destination_embedded_mode on the file-helper execution path:

    • PreserveExisting

    • StripExisting

  • CLI:

    • --xmp-include-existing-sidecar

    • --xmp-existing-sidecar-precedence <sidecar_wins|source_wins>

    • --xmp-no-exif-projection

    • --xmp-no-iptc-projection

    • --xmp-conflict-policy <current|existing_wins|generated_wins>

    • --xmp-writeback <embedded|sidecar|embedded_and_sidecar>

    • --xmp-destination-embedded <preserve_existing|strip_existing>

    • --xmp-destination-sidecar <preserve_existing|strip_existing>

Current behavior:

  • existing XMP can still be included independently

  • EXIF payload emission stays independent from EXIF-to-XMP projection

  • IPTC native carrier emission stays independent from IPTC-to-XMP projection

  • portable generated XMP can keep the historical mixed order, prefer existing decoded XMP, or prefer generated EXIF/IPTC mappings when the same portable property would collide

  • existing sibling .xmp sidecars from the destination path can be merged into generated portable XMP before transfer packaging when explicitly requested

  • that sidecar merge path now has explicit precedence against source-embedded existing XMP instead of relying on implicit decode order

  • some targets without a native IPTC carrier can still use XMP as the bounded fallback carrier when IPTC projection is enabled

  • file-helper export can now strip prepared embedded XMP blocks and return canonical sidecar output guidance instead

  • file-helper export can also keep generated embedded XMP while emitting the same generated packet as a sibling .xmp sidecar

  • the public metatransfer CLI and Python transfer wrapper can now persist that generated XMP as a sibling .xmp sidecar when sidecar or dual-write XMP writeback is selected

  • sidecar-only writeback now has an explicit destination embedded-XMP policy:

    • preserve existing embedded XMP by default

    • strip existing embedded XMP for jpeg, tiff, png, webp, jp2, and jxl

  • embedded-only writeback now has an explicit destination sidecar policy:

    • preserve an existing sibling .xmp by default

    • strip an existing sibling .xmp when explicitly requested

  • the C++ API now also has a bounded persistence helper for execute_prepared_transfer_file(...) results, so applications can write the edited file, write the generated .xmp sidecar, and remove a stale sibling .xmp without reimplementing wrapper-side file logic

  • the Python binding now exposes the same persistence path through transfer_file(...) and unsafe_transfer_file(...), and the public Python wrapper uses that core helper instead of maintaining its own sidecar write and cleanup implementation

This is deliberately narrower than a full sync engine. It does not yet define:

  • full EXIF vs XMP precedence rules

  • MWG-style reconciliation

  • full destination embedded-vs-sidecar reconciliation policy beyond the current bounded carrier modes and strip rules

  • namespace-wide deduplication and normalization rules beyond the current generated-XMP path

Time Patch Plan

Time patching is intentionally narrow and fixed-width.

Current model:

  • build EXIF payloads once

  • record patch slots in the bundle

  • patch only the affected bytes during execution

Primary fields:

  • DateTime

  • DateTimeOriginal

  • DateTimeDigitized

  • SubSecTime*

  • OffsetTime*

This is meant for fast repeated transfer, not general metadata editing.

Main Blockers

1. General edit UX

OpenMeta still does not present one fully mature, general-purpose metadata editor across all formats. The current transfer core is real, but still more bounded than ExifTool or Exiv2.

2. Broader EXIF / IPTC / XMP sync policy

This remains one of the biggest product gaps for writer adoption, even though the first public projection controls now exist.

Missing pieces include:

  • conflict resolution rules

  • broader sidecar vs embedded policy beyond the current bounded writeback mode

  • canonical writeback policy

  • broader namespace reconciliation behavior

3. MakerNote-safe rewrite expectations

Read parity is strong, but broad rewrite guarantees for vendor metadata are not yet at the level of mature editing tools.

4. EXR depth

The architectural question is now how far to deepen the current bounded EXR target:

  • keep EXR as a backend-emitter target plus bridge helpers, or

  • add a broader EXR file rewrite/edit path

Recommended Next Priorities

  1. Keep transfer ahead of further read-breadth work.

  2. Stabilize the current target family:

    • JPEG

    • TIFF

    • PNG

    • WebP

    • JP2

    • JXL

    • bounded BMFF

  3. Decide how deep EXR should go beyond the current bounded target.

  4. Add more transfer-focused roundtrip and compare gates where they improve confidence for adopters.

  5. Add an explicit EXIF / IPTC / XMP sync policy.

Postponed Work

Still out of scope for the current milestone:

  • full arbitrary metadata editing parity

  • full C2PA signed rewrite / trust-policy parity

  • full EXIF / IPTC / XMP sync engine

  • broad TIFF/DNG and BMFF rewrite parity beyond the bounded current targets

Practical Summary

OpenMeta is no longer blocked by read-path quality for adoption-oriented transfer work.

The main opportunity now is to make the current bounded transfer core easier to use and easier to trust across the primary export targets, instead of continuing to expand read-only surface area first.

page OpenEXR Metadata Fit for OpenMeta Core

Status: baseline contract (v1)

Goal

Assess whether the current OpenMeta metadata core can represent OpenEXR metadata well enough for read/edit workflows, and identify required API/model changes for good interoperability with OpenEXR and OpenImageIO.

What OpenEXR Metadata Looks Like

OpenEXR metadata is a per-part attribute map (name + typed value), not EXIF-like numeric tag tables. Attribute types are strongly typed in the SDK and include:

  • Scalars and enums (int, float, double, compression, lineOrder, envmap)

  • Geometric/math types (v2*, v3*, m33*, m44*, box2*)

  • Structured payloads (chlist, preview, tiledesc, timecode, keycode)

  • Strings and string vectors

  • Rational and opaque/custom attribute types

OpenEXR C APIs expose:

  • Count/list/get attribute by name or index (file order or sorted order)

  • Explicit typed getters/setters for built-in attribute types

  • Header write lifecycle (declare/set then write_header)

  • In-place header update mode with size constraints

OpenImageIO / OpenColorIO Integration Signals

  • OpenImageIO treats EXR metadata as arbitrary key/value attributes and maps many EXR names to generic names (DateTime, Copyright, etc.) while preserving EXR-specific names under openexr:*.

  • OpenImageIO reports EXIF/IPTC support for EXR via arbitrary metadata transport, not because EXR natively stores EXIF/IPTC blocks.

  • OpenColorIO metadata model is mostly string-based transform/config metadata; it is useful for selected color-related fields, not as a full EXR container model.

Fit Against Current OpenMeta Core

Current OpenMeta strengths:

  • MetaStore already supports duplicate keys, per-block origin, deterministic indexing, and binary-search lookups.

  • MetaValue already supports scalar, array, bytes, text, and rational values.

  • Existing block model can represent per-part metadata boundaries.

Current implementation snapshot:

  • MetaKeyKind::ExrAttribute is available (part_index + name).

  • decode_exr_header(...) is implemented and wired into simple_meta_read fallback path (metadata-only header decode).

  • Common EXR scalar/vector/matrix types decode to typed MetaValue; unknown and complex payloads are preserved as raw bytes.

  • Unknown/custom EXR attrs can preserve original type name in Origin::wire_type_name (optional decode behavior).

  • Origin::wire_type carries EXR type code (WireFamily::Other), and wire_count currently stores attribute byte size.

Remaining gaps for production-level EXR workflows:

  • Persisting original EXR type_name for unknown/custom attrs (beyond numeric code).

  • Full canonical policy for complex structured attrs (chlist, preview, stringvector) and helper views.

  • EXR-aware write/edit lifecycle, including in-place header size constraints.

  • Optional EXR scanner integration in container_scan (today handled by fallback decode in simple_meta_read).

Design Direction (v1)

  1. Add EXR key space and provenance:

    • MetaKeyKind::ExrAttribute with fields: part_index, name.

    • Reserve block format/container code for EXR header metadata blocks.

  2. Add EXR wire typing:

    • Extend wire metadata to carry EXR type id + type_name string when needed.

    • Keep unknown/custom attributes as raw bytes + declared type name.

  3. Define canonical value encodings:

    • vectors/matrices/boxes as typed arrays with fixed element counts.

    • chlist, preview, and other complex structs as bytes + structured decode helpers (opt-in) to keep core storage compact and lossless.

  4. Add EXR decode entry point:

    • decode_exr_header(...) that fills MetaStore from EXR parts/attributes.

    • Keep image pixel I/O out of scope; metadata only.

  5. Add integration adapters:

    • OpenImageIO adapter: map EXR attrs to OIIO-style names plus openexr:*.

    • OpenColorIO adapter: expose selected color metadata subset only.

Canonical encoding details for compound EXR values are tracked in: OpenMeta/docs/design/exr_canonical_value_encoding.md.

Practical Conclusion

OpenMeta core is close enough to support EXR metadata without redesigning the store. Main work is key-space/type modeling and a container-specific EXR decode frontend with clear canonical encoding rules for EXR compound attribute types.

dir docs/design
dir docs
dir src/include
dir src/include/openmeta
dir docs/research
dir src
page OpenMeta

OpenMeta is a metadata processing library for image files.

The current focus is safe, format-agnostic reads: find metadata blocks in common containers, decode them into a normalized in-memory model, and expose stable transfer/edit building blocks for export workflows.

Status

Read-path coverage is broad and regression-gated. Write/edit support is real for the main transfer targets, but parts of that API surface are still draft and may change as the transfer contract stabilizes.

Current planning estimate:

Milestone

Status

Read parity on tracked still-image corpora

About 99-100%

Transfer / export milestone

About 80-85%

Overall product milestone

About 97-98%

Current baseline-gated snapshot on tracked corpora:

  • HEIC/HEIF, CR3, and mixed RAW EXIF tag-id compare gates are passing.

  • EXR header metadata compare is passing for name/type/value-class checks.

  • Portable and lossless sidecar export paths are covered by baseline and smoke gates.

  • MakerNote decode is baseline-gated with broad vendor support; unknown tags are preserved losslessly when no structured mapping exists.

What OpenMeta Does

  • Scan containers to locate metadata blocks in jpeg, png, webp, gif, tiff/dng, crw/ciff, raf, x3f, jp2, jxl, and heif/avif/cr3 (ISO-BMFF).

  • Reassemble chunked payloads and optionally decompress supported carriers.

  • Decode metadata into a normalized MetaStore.

  • Export sidecars and previews.

  • Prepare, compile, emit, and edit metadata transfers for bounded target families.

Metadata Families

OpenMeta currently covers these major families:

  • EXIF, including pointer IFDs and broad MakerNote support.

  • Legacy Canon CRW/CIFF bridge with bounded native CIFF naming and projection.

  • XMP as RDF/XML properties.

  • ICC profile header and tag table.

  • Photoshop IRB, with raw preservation plus a bounded interpreted subset.

  • IPTC-IIM datasets.

  • JPEG comments, GIF comments, and PNG text chunks.

  • ISO-BMFF derived fields for primary-item, relation, and auxiliary semantics.

  • JUMBF / C2PA draft structural and semantic projection.

  • EXR header attributes.

For the detailed support matrix, see docs/metadata_support.md.

Naming Model

EXIF and MakerNote display names have two layers:

  • Canonical names from exif_tag_name(...)

  • ExifTool-compatible display names from exif_entry_name(..., ExifTagNamePolicy::ExifToolCompat)

That split lets OpenMeta keep stable internal naming while still matching common external tooling where compatibility matters.

Transfer and Edit

OpenMeta now has a real transfer core built around:

  • prepare_metadata_for_target(...)

  • compile_prepared_transfer_execution(...)

  • execute_prepared_transfer(...)

  • execute_prepared_transfer_file(...)

Current target status:

Target

Status

JPEG

First-class

TIFF

First-class

PNG

Bounded but real

WebP

Bounded but real

JP2

Bounded but real

JXL

Bounded but real

HEIF / AVIF / CR3

Bounded but real

EXR

Bounded but real

In practice:

  • JPEG and TIFF are the strongest transfer targets today.

  • TIFF edit support now covers classic TIFF, BigTIFF, bounded ifd1 chain rewrite with preserved downstream page tails, and bounded TIFF/DNG-style SubIFD rewrite with preserved downstream auxiliary tails and preserved trailing existing children when only the front subset is replaced.

  • For DNG-like TIFF sources, the current bounded merge policy is: replace the source-supplied front preview/aux structures, preserve existing target page tails and trailing auxiliary children.

  • PNG, WebP, JP2, JXL, bounded BMFF, and EXR all have real first-class transfer entry points.

  • EXR is still narrower than the container-edit targets: it emits safe string header attributes through the transfer core, can materialize a prepared ExrAdapterBatch for host exporters, and Python can inspect that prepared EXR attribute batch through the direct build_exr_attribute_batch_from_file binding or the helper-layer openmeta.python.get_exr_attribute_batch(...), but OpenMeta does not rewrite full EXR files yet.

  • Writer-side sync behavior is now partially explicit instead of implicit: generated XMP can independently keep or suppress EXIF-derived and IPTC-derived projection during transfer preparation.

  • Generated portable XMP also has an explicit conflict policy for existing decoded XMP versus generated EXIF/IPTC mappings: current behavior, existing_wins, or generated_wins.

  • Transfer preparation can also fold an existing sibling .xmp sidecar from the destination path into generated portable XMP when that bounded mode is requested, with explicit sidecar_wins or source_wins precedence against source-embedded existing XMP.

  • File-helper execution, metatransfer, and the Python transfer wrapper now share a bounded XMP carrier choice: embedded XMP only, sidecar-only writeback to a sibling .xmp, or dual embedded-plus-sidecar writeback when a generated XMP packet exists for the prepared transfer.

  • Sidecar-only writeback also has an explicit destination embedded-XMP policy: preserve existing embedded XMP by default, or strip it for jpeg, tiff, png, webp, jp2, and jxl.

  • Embedded-only writeback can also strip an existing sibling .xmp destination sidecar explicitly, so exports can move back to embedded-only XMP without leaving stale sidecar state behind.

  • C++ hosts now also have a bounded persistence helper for file-helper results, so edited output bytes, generated sidecars, and stale-sidecar cleanup can be applied without copying wrapper logic.

  • Python hosts also have matching transfer_file(...) and unsafe_transfer_file(...) bindings, and the public Python transfer wrapper now uses that same core-backed persistence path for real writes.

  • Prepared bundles record resolved policy decisions for MakerNote, JUMBF, C2PA, EXIF-to-XMP projection, and IPTC-to-XMP projection.

  • This is still not a full MWG-style sync engine. OpenMeta does not yet try to solve all EXIF/IPTC/XMP conflict resolution or canonical writeback policy.

For transfer details, see docs/metadata_transfer_plan.md.

Tools

OpenMeta ships a small set of CLI tools:

Tool

Purpose

metaread

Human-readable metadata dump

metavalidate

Metadata validation and issue reporting

metadump

Sidecar and preview dump tool

metatransfer

Transfer/edit smoke tool over the core transfer APIs

thumdump

Preview extractor

The Python bindings expose the same read and transfer core through thin wrapper helpers in src/python/.

Layout

  • src/include/openmeta/: public headers

  • src/openmeta/: library implementation

  • src/tools/: CLI tools

  • src/python/: Python bindings and helper scripts

  • tests/: unit tests and fuzz targets

  • docs/: design notes and developer documentation

Build

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

Useful options:

  • -DOPENMETA_BUILD_TOOLS=ON|OFF

  • -DOPENMETA_BUILD_TESTS=ON for GoogleTest-based unit tests

  • -DOPENMETA_BUILD_FUZZERS=ON for Clang + libFuzzer targets

  • -DOPENMETA_USE_LIBCXX=ON when linking against dependencies built with libc++

  • -DOPENMETA_BUILD_DOCS=ON for Doxygen HTML docs

  • -DOPENMETA_BUILD_SPHINX_DOCS=ON for Sphinx + Breathe HTML docs

Developer notes live in docs/development.md.

Quick Usage

simple_meta_read(...) performs scan_auto(...), payload extraction, and decode in one call.

  • Input: whole-file bytes

  • Output: MetaStore plus discovered ContainerBlockRef[]

  • Scratch: caller-provided block list, IFD list, payload buffer, and part-index buffer

Documentation