feat(metadata): strip container metadata from WebM/MP3/WAV/FLAC/OGG via ffmpeg (v0.6.4)

remove_ai_metadata now handles non-ISOBMFF audio/video (which the box walker
can't reach) by shelling out to ffmpeg with a lossless stream copy
(`-map_metadata -1 -map_chapters -1 -c copy`): codec data is untouched, only
container tags/chapters (ID3 / RIFF / Vorbis comments / EBML tags) are dropped.
Requires ffmpeg on PATH; raises a clear RuntimeError if absent or if ffmpeg
can't parse the input (instead of crashing in the image path).

Verified end-to-end: a real ffmpeg-made WAV/MP3 with a "Suno AI" title tag ->
tag gone, audio bytes preserved.

NOT built (evaluated, deliberate): Resemble PerTh audio *detection* --
`get_watermark()` returns a raw bit array with no presence/confidence flag, so
reliably telling watermarked from clean needs Resemble's fixed payload or a
confidence API (neither public; no real sample to calibrate). Same wall as the
SynthID pixel detector. AVIF/HEIF meta-box EXIF/XMP stripping also stays a gap
(needs exiftool, a non-installed binary). Both documented in CLAUDE.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "remove-ai-watermarks"
-version = "0.6.3"
+version = "0.6.4"
 description = "Remove visible and invisible AI watermarks from images (Gemini / Nano Banana, ChatGPT, Stable Diffusion)"
 readme = "README.md"
 requires-python = ">=3.10"

src/remove_ai_watermarks/__init__.py

@@ -1,3 +1,3 @@
 """Remove-AI-Watermarks: Unified tool for removing visible and invisible AI watermarks."""
 
-__version__ = "0.6.3"
+__version__ = "0.6.4"

src/remove_ai_watermarks/metadata.py

@@ -90,10 +90,10 @@ IPTC_AI_FIELD_MARKERS: tuple[bytes, ...] = (
 # (``ftyp``) is also accepted, so this is a fast-path hint, not the sole gate.
 _ISOBMFF_EXTS: frozenset[str] = frozenset({".avif", ".heif", ".heic", ".jxl", ".mp4", ".mov", ".m4v", ".m4a"})
 
-# Non-ISOBMFF audio/video we can DETECT (binary scan) but not strip at the
-# container level (EBML / framed / RIFF need re-encoding). remove_ai_metadata
-# fails clearly on these rather than crashing in the image path.
-_UNSUPPORTED_CONTAINER_EXTS: frozenset[str] = frozenset(
+# Non-ISOBMFF audio/video the ISOBMFF box walker can't reach (EBML / framed /
+# RIFF / Vorbis). remove_ai_metadata strips their container metadata losslessly
+# via ffmpeg (`-c copy`), so it needs ffmpeg on PATH for these.
+_FFMPEG_STRIP_EXTS: frozenset[str] = frozenset(
     {".webm", ".mkv", ".mka", ".mp3", ".wav", ".flac", ".ogg", ".oga", ".opus", ".aac"}
 )
 
@@ -487,6 +487,39 @@ def get_ai_metadata(image_path: Path) -> dict[str, str]:
     return result
 
 
+def _strip_with_ffmpeg(source_path: Path, output_path: Path) -> Path:
+    """Strip container metadata from a non-ISOBMFF audio/video file via ffmpeg.
+
+    Uses a lossless stream copy (``-c copy``), so codec data is untouched and only
+    container-level tags/chapters are dropped -- the metadata strip for WebM /
+    Matroska (EBML), MP3 (ID3), WAV / FLAC / OGG (RIFF / Vorbis comments) that the
+    ISOBMFF box walker cannot reach. Requires ffmpeg on PATH (raises if absent).
+    The output extension should match the source so ``-c copy`` can re-mux.
+    """
+    import shutil
+    import subprocess
+
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        raise RuntimeError(
+            f"ffmpeg is required to strip metadata from {source_path.suffix} files but was not found on "
+            "PATH; install ffmpeg (e.g. `brew install ffmpeg`) or re-encode the file with another tool"
+        )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    cmd = [
+        ffmpeg, "-y", "-loglevel", "error",
+        "-i", str(source_path),
+        "-map_metadata", "-1", "-map_chapters", "-1",
+        "-c", "copy",
+        str(output_path),
+    ]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)  # noqa: S603
+    if result.returncode != 0:
+        raise RuntimeError(f"ffmpeg failed to strip metadata from {source_path}: {result.stderr.strip()[:300]}")
+    logger.info("Stripped container metadata via ffmpeg -> %s", output_path)
+    return output_path
+
+
 def remove_ai_metadata(
     source_path: Path,
     output_path: Path | None = None,
@@ -530,15 +563,11 @@ def remove_ai_metadata(
         logger.info("Stripped %d AI-provenance box(es) → %s", stripped, output_path)
         return output_path
 
-    # Containers we can detect (via identify's byte scan) but cannot strip at the
-    # container level: non-ISOBMFF audio/video (Matroska/WebM are EBML; MP3 is
-    # framed; WAV is RIFF). Re-encoding them is out of scope, so fail clearly
-    # rather than crash in the PIL image path below.
-    if source_path.suffix.lower() in _UNSUPPORTED_CONTAINER_EXTS:
-        raise ValueError(
-            f"container-level metadata removal is not supported for {source_path.suffix} "
-            "(detection via `identify` still works); re-encode it with a media tool to strip metadata"
-        )
+    # Non-ISOBMFF audio/video (WebM/Matroska EBML, MP3 ID3, WAV/FLAC/OGG): the
+    # box walker can't reach these, so strip container metadata losslessly via
+    # ffmpeg (-c copy -- codec data untouched, only tags/chapters dropped).
+    if source_path.suffix.lower() in _FFMPEG_STRIP_EXTS:
+        return _strip_with_ffmpeg(source_path, output_path)
 
     # Read image and filter metadata
     with Image.open(source_path) as img:

tests/test_metadata.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import shutil
+import subprocess
 from pathlib import Path
 
 import piexif
@@ -699,9 +701,35 @@ class TestIsobmffMetadataRemoval:
         remove_ai_metadata(src, out)
         assert out.read_bytes() == _MP4_FTYP + _MP4_MDAT
 
-    def test_unsupported_container_raises(self, tmp_path: Path):
+    def test_unparseable_audio_raises(self, tmp_path: Path):
+        # Garbage that ffmpeg can't parse must raise a clear error, not crash in
+        # the image path. (When ffmpeg is absent this still raises RuntimeError.)
         src = tmp_path / "audio.mp3"
-        src.write_bytes(b"ID3\x04\x00\x00\x00\x00\x00\x00 fake mp3 frames")
+        src.write_bytes(b"ID3\x04\x00\x00\x00\x00\x00\x00 not real mp3 frames")
         out = tmp_path / "out.mp3"
-        with pytest.raises(ValueError, match="not supported"):
+        with pytest.raises(RuntimeError):
             remove_ai_metadata(src, out)
+
+
+@pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg not installed")
+class TestFfmpegMetadataStrip:
+    """Lossless container-metadata strip for non-ISOBMFF audio/video via ffmpeg."""
+
+    def _wav_with_tag(self, path: Path, tag: str = "Suno AI") -> None:
+        subprocess.run(  # noqa: S603
+            [
+                shutil.which("ffmpeg"), "-y", "-loglevel", "error",
+                "-f", "lavfi", "-i", "sine=frequency=440:duration=0.1",
+                "-metadata", f"title={tag}", str(path),
+            ],
+            check=True,
+        )
+
+    def test_strips_wav_title_metadata(self, tmp_path: Path):
+        src = tmp_path / "in.wav"
+        self._wav_with_tag(src, "Suno AI generated")
+        assert b"Suno AI generated" in src.read_bytes()  # tag is present pre-strip
+        out = tmp_path / "clean.wav"
+        remove_ai_metadata(src, out)
+        assert out.exists()
+        assert b"Suno AI generated" not in out.read_bytes()  # tag stripped, audio kept

uv.lock

@@ -2865,7 +2865,7 @@ wheels = [
 
 [[package]]
 name = "remove-ai-watermarks"
-version = "0.6.3"
+version = "0.6.4"
 source = { editable = "." }
 dependencies = [
     { name = "click" },