feat(b-roll): improve semantic selection and speaker layouts

skills/video-add-b-roll/examples/example-broll-plan.json

@@ -21,51 +21,78 @@
     "review_video_sha256": "5555555555555555555555555555555555555555555555555555555555555555"
   },
   "brief": {
-    "density": "selective",
+    "density": "dynamic-social",
+    "search_context": {
+      "topic": "Manufacturing automation workflow",
+      "visual_direction": "Visible precision manufacturing and operations software",
+      "keywords": [
+        "manufacturing",
+        "automation",
+        "precision parts",
+        "assembly line",
+        "operations dashboard",
+        "industrial software"
+      ]
+    },
     "style": "literal documentary footage",
     "avoid": [
       "logos",
       "unreadable screens",
       "generic office footage"
     ]
   },
-  "review_status": "approved",
-  "decision": {
-    "mode": "agent",
-    "actor": "Example Agent",
-    "rationale": "Selected the literal manufacturing process shot and skipped the weak software visual."
+  "speaker_inset_style": {
+    "enabled": true,
+    "shape": "rounded-rectangle",
+    "width_ratio": 0.39,
+    "aspect_ratio": 0.8,
+    "border": {
+      "width_px": 3,
+      "color": "#9E9E9E"
+    },
+    "corner_radius_ratio": 0.1,
+    "margin_ratio": 0.04,
+    "reserved_bottom_ratio": 0.2
+  },
+  "presentation": {
+    "status": "chosen",
+    "mode": "speaker-inset",
+    "path": "b-roll/presentation-decision.json",
+    "sha256": "9999999999999999999999999999999999999999999999999999999999999999",
+    "decision_id": "123e4567-e89b-12d3-a456-426614174009",
+    "actor": "Actual user",
+    "timestamp": "2026-08-04T11:30:00Z"
   },
-  "review": {
-    "status": "approved",
+  "decision": null,
+  "review": null,
+  "selection": {
+    "status": "prepared",
+    "submission_intent": "prepare_composite",
+    "path": "b-roll/broll-selection.json",
+    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
     "review_id": "123e4567-e89b-12d3-a456-426614174000",
-    "mode": "agent",
-    "actor": "Example Agent",
-    "rationale": "Selected the literal manufacturing process shot and skipped the weak software visual.",
-    "timestamp": "2026-07-23T12:00:00Z",
-    "plan_sha256": "278fe37aa4ac3bf528ebd0161bdb19a917158bd707debd19090f69b0f81fa2df",
-    "candidate_manifest_sha256": "4d46ef77624f6c2dfc1e0b2c62d54aba8bdac44609be6bc3ef5c1e8a625ab616",
-    "review_video_sha256": "5555555555555555555555555555555555555555555555555555555555555555",
-    "decisions": [
-      {
-        "id": "example-manufacturing-process",
-        "decision": "select",
-        "candidate_id": "example-owned-factory-video",
-        "source_trim": {
-          "start_s": 0.5,
-          "end_s": 3.5
-        }
-      },
-      {
-        "id": "example-software-claim",
-        "decision": "skip"
-      }
-    ],
-    "decision_skipped_shot_ids": [
-      "example-software-claim"
-    ],
-    "selected_asset_sha256": [
-      "6666666666666666666666666666666666666666666666666666666666666666"
-    ]
+    "mode": "human",
+    "actor": "Actual user",
+    "timestamp": "2026-08-04T12:00:00Z",
+    "style_sha256": "ab2a11307eabc99255f230422a4c0fe99ebc46fe7287808bd25d47423f730c72"
+  },
+  "speaker_inset": {
+    "analysis": {
+      "path": "b-roll/speaker-inset-analysis.json",
+      "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
+    },
+    "agent_input": {
+      "path": "b-roll/speaker-inset-agent-input.json",
+      "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+    },
+    "preview": {
+      "path": "b-roll/speaker-inset-preview.json",
+      "sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+    },
+    "clearance": {
+      "path": "b-roll/speaker-inset-clearance.json",
+      "sha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee"
+    }
   },
   "shots": [
     {
@@ -98,10 +125,12 @@
         ]
       },
       "editorial_reason": "Shows the physical process named in the claim.",
-      "visual_intent": "A wide, readable view of precision parts moving through a factory line.",
+      "visual_intent": "A readable view of precision parts moving through a factory line.",
+      "semantic_role": "direct",
       "queries": [
         "precision parts factory line",
-        "manufacturing assembly process wide shot"
+        "manufacturing assembly process wide shot",
+        "industrial automation workflow detail"
       ],
       "candidates": [
         {
@@ -121,72 +150,61 @@
             "source_type": "local",
             "creator": "Example Studio",
             "license": "Example owned footage - replace with real rights statement",
-            "retrieval_time": "2026-07-23T10:00:00Z",
+            "retrieval_time": "2026-08-04T10:00:00Z",
             "original_path": "input/example-owned-factory-video.mp4"
           }
+        },
+        {
+          "id": "example-owned-factory-detail-video",
+          "media_type": "video",
+          "cache_path": "cache/b-roll/candidates/example-owned-factory-detail-video.mp4",
+          "sha256": "6767676767676767676767676767676767676767676767676767676767676767",
+          "bytes": 1123456,
+          "duration_s": 4.0,
+          "probe": {
+            "duration_s": 4.0,
+            "width": 1920,
+            "height": 1080,
+            "codec": "h264"
+          },
+          "provenance": {
+            "source_type": "local",
+            "creator": "Example Studio",
+            "license": "Example owned footage - replace with real rights statement",
+            "retrieval_time": "2026-08-04T10:00:00Z",
+            "original_path": "input/example-owned-factory-detail-video.mp4"
+          }
         }
       ],
       "selected": {
-        "candidate_id": "example-owned-factory-video",
-        "source_trim": {
-          "start_s": 0.5,
-          "end_s": 3.5
-        }
-      },
-      "status": "verified",
-      "normalized": {
-        "path": "cache/b-roll/normalized/broll-001.mp4",
-        "source_path": "cache/b-roll/candidates/example-owned-factory-video.mp4",
-        "source_sha256": "6666666666666666666666666666666666666666666666666666666666666666",
-        "sha256": "7777777777777777777777777777777777777777777777777777777777777777",
-        "probe": {
-          "duration_s": 3.0,
-          "width": 1920,
-          "height": 1080,
-          "fps": {
-            "num": 30000,
-            "den": 1001
-          },
-          "sar": "1:1",
-          "codec": "h264",
-          "pix_fmt": "yuv420p",
-          "has_audio": false,
-          "has_subtitles": false,
-          "has_data": false
-        },
-        "grade_plan_sha256": "3333333333333333333333333333333333333333333333333333333333333333",
-        "selected_lut_sha256": "4444444444444444444444444444444444444444444444444444444444444444"
-      },
-      "verification": {
-        "status": "pass",
-        "normalized_sha256": "7777777777777777777777777777777777777777777777777777777777777777",
-        "stills": {
-          "first": {
-            "path": "review/03-b-roll/stills/001-example-manufacturing-process-first.png",
-            "sha256": "8888888888888888888888888888888888888888888888888888888888888888"
-          },
-          "middle": {
-            "path": "review/03-b-roll/stills/001-example-manufacturing-process-middle.png",
-            "sha256": "9999999999999999999999999999999999999999999999999999999999999999"
+        "segments": [
+          {
+            "candidate_id": "example-owned-factory-video",
+            "source_range": {
+              "start_s": 0.5,
+              "end_s": 1.5
+            },
+            "program_range": {
+              "start_s": 6.0,
+              "end_s": 7.0
+            },
+            "playback_rate": 1.0
           },
-          "last": {
-            "path": "review/03-b-roll/stills/001-example-manufacturing-process-last.png",
-            "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+          {
+            "candidate_id": "example-owned-factory-detail-video",
+            "source_range": {
+              "start_s": 0.5,
+              "end_s": 3.5
+            },
+            "program_range": {
+              "start_s": 7.0,
+              "end_s": 9.0
+            },
+            "playback_rate": 1.5
           }
-        },
-        "contact_sheet": {
-          "path": "review/03-b-roll/contact-sheet.jpg",
-          "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
-        },
-        "boundary_reel": {
-          "path": "review/03-b-roll/boundary-reel.mp4",
-          "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
-        },
-        "report": {
-          "path": "review/03-b-roll/b-roll-summary.md",
-          "sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
-        }
-      }
+        ]
+      },
+      "status": "composite_pending"
     },
     {
       "id": "example-software-claim",
@@ -219,9 +237,11 @@
       },
       "editorial_reason": "A literal interface could clarify the software claim.",
       "visual_intent": "A readable product interface showing the exact workflow described.",
+      "semantic_role": "supportive",
       "queries": [
         "manufacturing workflow software interface",
-        "factory operations dashboard close up"
+        "factory operations dashboard close up",
+        "industrial data flow screen"
       ],
       "candidates": [],
       "selected": null,