feat: complete product video watermark pipeline

docs/python-api.md

@@ -128,10 +128,62 @@ path preserves the pixels but drops standard metadata. Treat a nonempty
 undecodable input through unchanged, so its return alone must not be presented
 as proof that metadata was removed.
 
+## Identify and clean video
+
+The high level video API supports MP4, MOV, M4V, WebM, MKV, AVI, and FLV:
+
+```python
+import remove_ai_watermarks as raiw
+
+report = raiw.identify_video("input.mp4")
+print(report.is_ai_generated)
+print(report.platform)
+print(report.visible_mark)
+print(report.metadata_markers)
+```
+
+`identify_video` uses the same full-clip temporal arbiter as visible removal.
+It reports a recurring registered mark and supported AI metadata as positive
+signals. When neither is present, `is_ai_generated` is `None`, never `False`.
+The absence of a public local video SynthID decoder is included in `caveats`.
+Pass `check_visible=False` for a bounded metadata-only inspection.
+
+For normal product integration, use the complete locally verifiable pipeline:
+
+```python
+result = raiw.remove_video_all("input.mp4", "clean.mp4")
+if result.remaining_metadata:
+    raise RuntimeError(f"AI metadata remains: {result.remaining_metadata}")
+```
+
+The default removes one stable supported visible provider mark when present,
+always strips verified AI metadata, and writes a same-container output even
+when neither signal is found. This gives callers one predictable output path.
+It does not run lossy invisible regeneration by default.
+
+`include_invisible=True` explicitly adds VAE regeneration for MP4, MOV, or M4V.
+`VideoAllResult.invisible_removed` reports whether the oracle-certified SynthID
+stage ran.
+
+Process a top-level directory sequentially:
+
+```python
+batch = raiw.remove_video_batch("videos", "videos_clean", mode="all")
+if batch.failed:
+    for item in batch.items:
+        if item.error:
+            print(item.source, item.error)
+```
+
+Batch modes are `all`, `visible`, and `metadata`. Successful visible no-ops are
+copied byte-for-byte, keeping the output directory complete. Per-file failures
+are returned in `VideoBatchItem.error`; they do not discard successful outputs.
+The invisible stage is available only as an explicit opt-in in `all` mode and
+reuses one loaded VAE runtime across the batch.
+
 ## Inspect and strip video metadata
 
-The experimental high level video API supports MP4, MOV, M4V, WebM, MKV, AVI,
-and FLV:
+Metadata inspection and removal use the same supported video containers:
 
 ```python
 import remove_ai_watermarks as raiw
@@ -151,23 +203,23 @@ The returned `VideoMetadataResult` records the source, output, metadata detected
 before removal, and any markers remaining after the verified strip. MP4/MOV
 inspection recognizes the native TC260 `AIGC` entry in
 `moov.udta.meta.keys/ilst`; its removal preserves container size and encoded
-stream bytes. MKV/WebM inspection recognizes the corresponding
+stream bytes. MP4/MOV/M4V are copied in bounded chunks, so a large `mdat` is not
+loaded into memory; publication is atomic. MKV/WebM inspection recognizes the corresponding
 `Segment.Tags.Tag.SimpleTag` representation; its removal requires ffmpeg for a
 stream-copy remux. AVI inspection reads `LIST/INFO/AIGC`, and FLV inspection
 reads `script.onMetaData.AIGC`; both use the same verified ffmpeg stream-copy
 removal path.
 
-## Generate a video SynthID candidate
+## Remove video SynthID
 
 ```python
 import remove_ai_watermarks as raiw
 
 result = raiw.remove_video_invisible(
     "input.mp4",
-    "candidate.mp4",
+    "clean.mp4",
     device="auto",
 )
-assert result.requires_external_verification
 if result.remaining_metadata:
     raise RuntimeError(f"AI metadata remains: {result.remaining_metadata}")
 ```
@@ -176,14 +228,19 @@ if result.remaining_metadata:
 video through a VAE in bounded batches, shares one seeded latent-noise field
 across all frames, streams pixels to ffmpeg, copies complete audio, strips
 source metadata, and publishes atomically. The default output is
-`input_synthid_candidate.mp4`; a distinct same-container output is required.
+`input_clean.mp4`; a distinct same-container output is required.
 
 The returned `VideoInvisibleResult` includes output geometry, frame rate, frame
 count, paired PSNR, and the motion-compensated temporal-residual ratio. Those
 fields measure fidelity and flicker only. They are not a SynthID detector.
-`requires_external_verification` is always true because Google does not publish
-a local decoder for this video payload. Verify the candidate with Gemini
-Flash's built-in content verification before treating it as watermark-negative.
+The default `noise_std=0.15` is the current full-clip oracle floor; `0.10`
+remained detected on the public eight-second Veo calibration carrier.
+The default profile is oracle-certified. Google does not publish a local
+decoder for this video payload, so a fresh source-positive, output-negative
+pair from Gemini's built-in SynthID verifier remains an optional per-file audit.
+A response inferred from a visible logo or metadata is not such a verdict, and
+an adversarial follow-up asking ordinary Gemini to reinterpret the verifier is
+not a second oracle run.
 
 ## Remove a supported visible video mark
 
@@ -195,6 +252,7 @@ result = raiw.remove_video_visible(
     "clean.mp4",
     backend="cv2",
     strip_metadata=True,
+    temporal_consistency=True,
 )
 if result.output is None:
     print("No temporally stable supported mark was found")
@@ -241,13 +299,24 @@ legacy `Veo` text. Seedance recognizes the boxed `AI` label, Dola recognizes
 its compact text label, Hailuo recognizes the composite MINIMAX/Hailuo label,
 and Kling recognizes its bottom-right logo, wordmark, and version suffix. Each
 variant has an independent synthetic silhouette and calibrated temporal policy.
+After each accepted frame is filled, `temporal_consistency=True` motion-aligns
+the preceding accepted fill and blends it only when the warped prior mask
+covers the current mask and a surrounding source-context ring agrees. Scene
+cuts and disjoint masks keep the independent current fill. Pass
+`temporal_consistency=False` for the frame-local baseline.
 
 The returned `VideoVisibleResult` records the selected `mark`, the total,
 detected, and removed frame counts, plus any AI metadata that survived the
 output encode. The function returns `output=None` and writes no file when no
 stable mark is selected. Video pixels are transcoded through ffmpeg while the
-complete source audio stream is copied. A failed encode preserves any existing
-output; only a completed result is published atomically.
+complete source audio stream is copied. The encoder preserves supported 8-bit
+source chroma sampling, color tags, MP4/MOV track timescale, and relative
+variable-frame timestamps. It also retains a non-zero source start PTS and the
+copied audio offset. A failed encode preserves any existing output; only a
+completed result is published atomically.
+SDR 8-bit video is the supported pixel contract. High-bit-depth, PQ, and HLG
+sources raise `RuntimeError` before encoding instead of being silently reduced
+to 8-bit SDR.
 
 ## Remove invisible watermarks