aigc_image_metadata

简体中文

A pure Dart package for reading, embedding, transplanting, and verifying GB 45438-2025 / TC260 AIGC metadata in PNG and JPEG images.

Use it when an image is re-encoded—for example, after adding a visible watermark—and the original AIGC metadata needs to be restored to the resulting file.

Features

Reads TC260 AIGC metadata from PNG and JPEG images.
Embeds the standard seven-field AIGC declaration.
Transplants metadata after image re-encoding.
Verifies canonical container structure, metadata, format, and dimensions.
Reports failures through stable typed error codes.
Applies configurable limits to untrusted image and XMP data.

Installation

dependencies:
  aigc_image_metadata: ^0.1.0

import 'package:aigc_image_metadata/aigc_image_metadata.dart';

Preserve metadata after re-encoding

const codec = AigcImageMetadataCodec();

final result = codec.transplant(
  sourceBytes: originalBytes,
  reencodedBytes: reencodedBytes,
  expectedFormat: AigcImageFormat.jpeg,
);

final outputBytes = result.bytes;

By default, the source and re-encoded image must use the same format and dimensions. For an intentional resize or crop:

final result = codec.transplant(
  sourceBytes: originalBytes,
  reencodedBytes: resizedBytes,
  dimensionPolicy: AigcDimensionPolicy.allowChange,
);

Embed metadata for the first time

const metadata = Tc260AigcMetadata(
  label: '1',
  contentProducer: 'ExampleService',
  produceId: 'IMG-123-1',
  reservedCode1: '',
  contentPropagator: 'ExampleService',
  propagateId: 'IMG-123-1',
  reservedCode2: '',
);

final result = codec.embed(
  encodedBytes: encodedBytes,
  metadata: metadata,
  expectedFormat: AigcImageFormat.png,
  propagationPolicy:
      AigcPropagationPolicy.requireProducerAsPropagator,
);

Read and verify

final info = codec.read(imageBytes);

print(info.format);
print(info.width);
print(info.height);
print(info.metadata.toJson());
print(info.container.isCanonical);

To require canonical output:

final verified = codec.verifyCanonical(
  bytes: imageBytes,
  expectedMetadata: expectedMetadata,
  expectedFormat: AigcImageFormat.png,
);

Policies

AigcContainerPolicy.compatible accepts supported compatible TC260 representations while requiring exactly one AIGC payload.
AigcContainerPolicy.canonical requires one standard XMP container and no legacy PNG AIGC text container.
AigcPropagationPolicy.requireProducerAsPropagator requires the producer and propagator fields, and their IDs, to match.
AigcExistingXmpPolicy.reject prevents accidental removal of existing target XMP. Use replace only when replacement is intentional.

Error handling

All public operations throw AigcMetadataException on failure. Use its code for application logic and map it to your own user-facing message.

try {
  codec.read(imageBytes);
} on AigcMetadataException catch (error) {
  switch (error.code) {
    case AigcMetadataErrorCode.metadataMissing:
      // Handle a missing AIGC declaration.
      break;
    default:
      // Handle an invalid or unsupported image.
      break;
  }
}

message and offset are intended for developer diagnostics and should not be displayed directly to end users.

Scope

Version 0.1.0 supports PNG and JPEG on Dart VM and Flutter Android/iOS. Web is not supported.

The package handles TC260 AIGC metadata only. It does not render visible watermarks, re-encode pixels, save images, or copy EXIF, ICC, IPTC, GPS, C2PA, or arbitrary third-party XMP metadata.

This package provides engineering utilities and does not constitute legal or regulatory advice.

License

MIT