Add EmbeddedAndSidecar XMP writeback mode

Added new XmpWritebackMode::EmbeddedAndSidecar to support writing generated XMP both embedded and as a sibling .xmp sidecar. Update public docs and README to document the new option. Adjust core logic so sidecar output is requested whenever the mode is not EmbeddedOnly and only strips embedded XMP blocks in SidecarOnly mode; in dual mode the embedded carrier is preserved and a sidecar is emitted. Expose the new enum value to the Python binding and Python CLI, extend argument validation to require --output for non-embedded modes, and update the metatransfer tool help/parser/messages. Add a unit test verifying embedded+sidecar behavior.

Author: ssh4net

README.md

@@ -101,8 +101,9 @@ In practice:
   source-embedded existing XMP.
 - File-helper execution, `metatransfer`, and the Python transfer wrapper now
   share a bounded XMP carrier choice:
-  embedded XMP only, or sidecar-only writeback to a sibling `.xmp` when a
-  generated XMP packet exists for the prepared transfer.
+  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.
 - 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

docs/metadata_transfer_plan.md

@@ -235,13 +235,14 @@ Current controls:
 - `xmp_writeback_mode` on the file-helper execution path:
   - `EmbeddedOnly`
   - `SidecarOnly`
+  - `EmbeddedAndSidecar`
 - 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>`
+  - `--xmp-writeback <embedded|sidecar|embedded_and_sidecar>`
 
 Current behavior:
 - existing XMP can still be included independently
@@ -259,14 +260,16 @@ Current behavior:
   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 writeback is
-  selected
+  that generated XMP as a sibling `.xmp` sidecar when sidecar or dual-write
+  XMP writeback is selected
 
 This is deliberately narrower than a full sync engine. It does not yet define:
 - full EXIF vs XMP precedence rules
 - MWG-style reconciliation
-- canonical sidecar vs embedded writeback policy
+- canonical destination embedded-vs-sidecar reconciliation policy
 - namespace-wide deduplication and normalization rules beyond the current
   generated-XMP path
 

src/include/openmeta/metadata_transfer.h

@@ -1165,6 +1165,7 @@ struct ExecutePreparedTransferResult final {
 enum class XmpWritebackMode : uint8_t {
     EmbeddedOnly,
     SidecarOnly,
+    EmbeddedAndSidecar,
 };
 
 /// Options for \ref execute_prepared_transfer_file.

src/openmeta/metadata_transfer.cc

@@ -21413,7 +21413,7 @@ execute_prepared_transfer_file(
 {
     ExecutePreparedTransferFileResult out;
     out.xmp_sidecar_requested
-        = options.xmp_writeback_mode == XmpWritebackMode::SidecarOnly;
+        = options.xmp_writeback_mode != XmpWritebackMode::EmbeddedOnly;
     const bool c2pa_stage_requested = options.c2pa_stage_requested
                                       || options.c2pa_signed_package_provided;
     out.execute.c2pa_stage_requested = c2pa_stage_requested;
@@ -21437,12 +21437,20 @@ execute_prepared_transfer_file(
             if (!out.prepared.bundle.generated_xmp_sidecar.empty()) {
                 out.xmp_sidecar_output = out.prepared.bundle.generated_xmp_sidecar;
                 out.xmp_sidecar_status = TransferStatus::Ok;
-                const uint32_t removed_xmp = remove_prepared_blocks_by_kind(
-                    &out.prepared.bundle, TransferBlockKind::Xmp);
-                if (removed_xmp == 0U) {
+                if (options.xmp_writeback_mode
+                    == XmpWritebackMode::SidecarOnly) {
+                    const uint32_t removed_xmp
+                        = remove_prepared_blocks_by_kind(
+                            &out.prepared.bundle, TransferBlockKind::Xmp);
+                    if (removed_xmp == 0U) {
+                        out.xmp_sidecar_message
+                            = "prepared xmp sidecar bytes available without "
+                              "embedded xmp carrier blocks";
+                    }
+                } else {
                     out.xmp_sidecar_message
-                        = "prepared xmp sidecar bytes available without "
-                          "embedded xmp carrier blocks";
+                        = "prepared xmp sidecar bytes will be written "
+                          "alongside embedded xmp carriers";
                 }
             } else {
                 out.xmp_sidecar_status  = TransferStatus::Ok;

src/python/openmeta/python/metatransfer.py

@@ -199,7 +199,7 @@ def main(argv: list[str]) -> int:
     ap.add_argument("--xmp-no-exif-projection", action="store_true", help="do not mirror EXIF-derived properties into generated XMP")
     ap.add_argument("--xmp-no-iptc-projection", action="store_true", help="do not mirror IPTC-derived properties into generated XMP")
     ap.add_argument("--xmp-conflict-policy", choices=["current", "existing_wins", "generated_wins"], default="current", help="conflict policy between existing decoded XMP and generated portable EXIF/IPTC XMP")
-    ap.add_argument("--xmp-writeback", choices=["embedded", "sidecar"], default="embedded", help="keep generated XMP embedded, or persist it as a sibling .xmp sidecar when --output is used")
+    ap.add_argument("--xmp-writeback", choices=["embedded", "sidecar", "embedded_and_sidecar"], default="embedded", help="keep generated XMP embedded, persist it only as a sibling .xmp sidecar, or do both when --output is used")
     ap.add_argument("--xmp-exiftool-gpsdatetime-alias", action="store_true", help="emit exif:GPSDateTime alias for GPS time in portable mode")
     ap.add_argument("--no-exif", action="store_true", help="skip EXIF APP1 preparation")
     ap.add_argument("--no-xmp", action="store_true", help="skip XMP APP1 preparation")
@@ -432,8 +432,8 @@ def main(argv: list[str]) -> int:
             "--target-png, --target-jp2, --target-jxl, --target-heif, "
             "--target-avif, or --target-cr3"
         )
-    if args.xmp_writeback == "sidecar" and not args.output:
-        ap.error("--xmp-writeback sidecar requires --output")
+    if args.xmp_writeback != "embedded" and not args.output:
+        ap.error("--xmp-writeback sidecar or embedded_and_sidecar requires --output")
     if args.dump_c2pa_binding and (
         args.target_tiff
         or args.target_webp
@@ -727,6 +727,8 @@ def main(argv: list[str]) -> int:
     xmp_writeback_mode = openmeta.XmpWritebackMode.EmbeddedOnly
     if args.xmp_writeback == "sidecar":
         xmp_writeback_mode = openmeta.XmpWritebackMode.SidecarOnly
+    elif args.xmp_writeback == "embedded_and_sidecar":
+        xmp_writeback_mode = openmeta.XmpWritebackMode.EmbeddedAndSidecar
     xmp_existing_sidecar_mode = openmeta.XmpExistingSidecarMode.Ignore
     if args.xmp_include_existing_sidecar:
         xmp_existing_sidecar_mode = (

src/python/src/openmeta_module.cc

@@ -3342,7 +3342,9 @@ NB_MODULE(_openmeta, m)
 
     nb::enum_<XmpWritebackMode>(m, "XmpWritebackMode")
         .value("EmbeddedOnly", XmpWritebackMode::EmbeddedOnly)
-        .value("SidecarOnly", XmpWritebackMode::SidecarOnly);
+        .value("SidecarOnly", XmpWritebackMode::SidecarOnly)
+        .value("EmbeddedAndSidecar",
+               XmpWritebackMode::EmbeddedAndSidecar);
 
     nb::enum_<XmpExistingSidecarMode>(m, "XmpExistingSidecarMode")
         .value("Ignore", XmpExistingSidecarMode::Ignore)

src/tools/metatransfer.cc

@@ -53,9 +53,10 @@ namespace {
             "  --xmp-conflict-policy <current|existing_wins|generated_wins>\n"
             "                         Conflict policy between existing decoded XMP and\n"
             "                         generated portable EXIF/IPTC XMP properties\n"
-            "  --xmp-writeback <embedded|sidecar>\n"
+            "  --xmp-writeback <embedded|sidecar|embedded_and_sidecar>\n"
             "                         Keep generated XMP embedded, or strip embedded XMP\n"
-            "                         carriers and persist a sibling .xmp sidecar when --output is used\n"
+            "                         carriers and persist a sibling .xmp sidecar when --output is used,\n"
+            "                         or keep both embedded and sidecar XMP carriers\n"
             "  --xmp-exiftool-gpsdatetime-alias\n"
             "                         Emit exif:GPSDateTime alias in portable mode\n"
             "  --no-exif              Skip EXIF APP1 preparation\n"
@@ -378,6 +379,10 @@ namespace {
             *out = XmpWritebackMode::SidecarOnly;
             return true;
         }
+        if (std::strcmp(s, "embedded_and_sidecar") == 0) {
+            *out = XmpWritebackMode::EmbeddedAndSidecar;
+            return true;
+        }
         return false;
     }
 
@@ -1366,7 +1371,7 @@ main(int argc, char** argv)
                                           &xmp_writeback_mode)) {
                 std::fprintf(stderr,
                              "invalid --xmp-writeback value "
-                             "(expected embedded|sidecar)\n");
+                             "(expected embedded|sidecar|embedded_and_sidecar)\n");
                 return 2;
             }
             i += 1;
@@ -2154,10 +2159,11 @@ main(int argc, char** argv)
         std::fprintf(stderr, "--output is not supported for --target-exr\n");
         return 2;
     }
-    if (xmp_writeback_mode == XmpWritebackMode::SidecarOnly
+    if (xmp_writeback_mode != XmpWritebackMode::EmbeddedOnly
         && output_path.empty()) {
         std::fprintf(stderr,
-                     "--xmp-writeback sidecar requires --output\n");
+                     "--xmp-writeback sidecar or embedded_and_sidecar "
+                     "requires --output\n");
         return 2;
     }
     const bool c2pa_wrapper_target_ok

tests/metadata_transfer_api_test.cc

@@ -7239,6 +7239,69 @@ TEST(MetadataTransferApi,
         "OpenMeta Transfer Source"));
 }
 
+TEST(MetadataTransferApi,
+     ExecutePreparedTransferFileJpegEmbeddedAndSidecarKeepsEmbeddedXmp)
+{
+    std::vector<std::byte> source_jpeg;
+    ASSERT_TRUE(build_test_transfer_source_jpeg_bytes(&source_jpeg));
+    const std::string source_path = unique_temp_path(".jpg");
+    ASSERT_TRUE(write_bytes_file(
+        source_path,
+        std::span<const std::byte>(source_jpeg.data(), source_jpeg.size())));
+
+    const std::vector<std::byte> target_jpeg = make_jpeg_with_segments({});
+    const std::string target_path            = unique_temp_path(".jpg");
+    ASSERT_TRUE(write_bytes_file(
+        target_path,
+        std::span<const std::byte>(target_jpeg.data(), target_jpeg.size())));
+
+    openmeta::ExecutePreparedTransferFileOptions options;
+    options.prepare.prepare.target_format = openmeta::TransferTargetFormat::Jpeg;
+    options.prepare.prepare.include_icc_app2   = false;
+    options.prepare.prepare.include_iptc_app13 = false;
+    options.edit_target_path                   = target_path;
+    options.execute.edit_apply                 = true;
+    options.xmp_writeback_mode
+        = openmeta::XmpWritebackMode::EmbeddedAndSidecar;
+
+    const openmeta::ExecutePreparedTransferFileResult result
+        = openmeta::execute_prepared_transfer_file(source_path.c_str(), options);
+    std::remove(source_path.c_str());
+    std::remove(target_path.c_str());
+
+    ASSERT_EQ(result.prepared.file_status, openmeta::TransferFileStatus::Ok);
+    ASSERT_EQ(result.prepared.prepare.status, openmeta::TransferStatus::Ok);
+    ASSERT_EQ(result.execute.edit_apply.status, openmeta::TransferStatus::Ok);
+    EXPECT_TRUE(result.xmp_sidecar_requested);
+    EXPECT_EQ(result.xmp_sidecar_status, openmeta::TransferStatus::Ok);
+    EXPECT_FALSE(result.xmp_sidecar_output.empty());
+    EXPECT_EQ(count_blocks_with_route(result.prepared.bundle, "jpeg:app1-xmp"),
+              1U);
+
+    openmeta::MetaStore edited_store;
+    ASSERT_TRUE(decode_transfer_roundtrip_store(
+        std::span<const std::byte>(result.execute.edited_output.data(),
+                                   result.execute.edited_output.size()),
+        &edited_store));
+    EXPECT_TRUE(store_has_text_entry(edited_store,
+                                     exif_key_view("exififd", 0x9003U),
+                                     "2024:01:02 03:04:05"));
+    EXPECT_TRUE(store_has_text_entry(
+        edited_store,
+        xmp_key_view("http://ns.adobe.com/xap/1.0/", "CreatorTool"),
+        "OpenMeta Transfer Source"));
+
+    openmeta::MetaStore sidecar_store;
+    ASSERT_TRUE(decode_transfer_roundtrip_store(
+        std::span<const std::byte>(result.xmp_sidecar_output.data(),
+                                   result.xmp_sidecar_output.size()),
+        &sidecar_store));
+    EXPECT_TRUE(store_has_text_entry(
+        sidecar_store,
+        xmp_key_view("http://ns.adobe.com/xap/1.0/", "CreatorTool"),
+        "OpenMeta Transfer Source"));
+}
+
 TEST(MetadataTransferApi,
      ExecutePreparedTransferFileSidecarOnlyRequiresEditTargetPath)
 {