signal-bot/signal_bot/media_tracks.py

# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Dropping the tracks a video carries besides its picture and its sound.

An iPhone video is not one stream. Measured on a clip already sitting in the
album, ``IMG_6924.mp4`` carries two ``mebx`` timed-metadata tracks, and after a
*complete* ``exiftool -all= -time:all=`` pass its bytes still contain::

    com.apple.quicktime.detected - face
    com.apple.quicktime.detected - face.bounds
    com.apple.quicktime.detected - face.face - id
    com.apple.quicktime.detected - face.roll - angle
    com.apple.quicktime.detected - face.yaw - angle

Per-frame face bounding boxes and a face identity number -- biometric data
about the people in a private album. exiftool cannot remove it and is not
broken for failing to: ``mebx`` samples live in ``mdat`` as opaque payload, not
in a tag. A tag allowlist is structurally incapable of seeing this class, which
is why removing the whole track is the only answer.

**This is not the ffmpeg mistake media_strip.py warns about.** That warning is
about using ffmpeg to remove *tags*, where ``-map_metadata -1 -c copy`` returned
a byte-identical JPEG with its GPS marker intact and exited 0. Here ffmpeg
removes *tracks*, exiftool still does every tag removal afterwards, and the
check below is a positive read-back of which streams survived rather than an
exit code. Do not collapse the two jobs back together.

``-c copy`` is safe for this job precisely because nothing is being claimed
about the frames: the assertion is about which tracks exist, and ffprobe
answers that directly.
"""

from __future__ import annotations

import logging
import shutil
import tempfile
from pathlib import Path
from typing import Final

from signal_bot.external import run

logger = logging.getLogger(__name__)

FFMPEG: Final = "ffmpeg"
FFPROBE: Final = "ffprobe"

# The containers that can carry a metadata track at all. Everything else the
# album accepts is a still image and goes straight past this module.
ISO_SUFFIXES: Final = frozenset({".mp4", ".mov", ".m4v"})

# The only stream kinds a stored file may have once it is flattened.
KEPT: Final = frozenset({"video", "audio"})

# Same reasoning as media_strip.FALLBACK_PATHS: a systemd unit's PATH is
# "/usr/local/bin:/usr/bin" and nothing else.
FALLBACK_DIRS: Final = ("/usr/local/bin", "/usr/bin", "/opt/homebrew/bin")

TIMEOUT_SECONDS: Final = 120


def locate(binary: str) -> str | None:
    """One tool's absolute path, or None when it is not installed."""
    found = shutil.which(binary)
    if found is not None:
        return found
    candidates = (Path(directory) / binary for directory in FALLBACK_DIRS)
    return next((str(path) for path in candidates if path.is_file()), None)


def flatten(payload: bytes, suffix: str) -> bytes | None:
    """Re-mux one video keeping only its picture and sound.

    Args:
        payload: The file exactly as it arrived.
        suffix: The sniffed suffix, which decides the container ffmpeg writes.

    Returns:
        The re-muxed file, or None when either tool is missing, ffmpeg fails,
        or the result still reports a stream that is not video or audio.
    """
    ffmpeg = locate(FFMPEG)
    ffprobe = locate(FFPROBE)
    if ffmpeg is None or ffprobe is None:
        logger.error("ffmpeg/ffprobe not found; refusing to store %s", suffix)
        return None
    with tempfile.TemporaryDirectory(prefix="signal-bot-tracks-") as workspace:
        return _run(Path(workspace), payload, suffix, ffmpeg, ffprobe)


def _run(workspace: Path, payload: bytes, suffix: str, ffmpeg: str, ffprobe: str) -> bytes | None:
    """Do the re-mux inside a temp directory that is removed either way."""
    source = workspace / f"in{suffix}"
    destination = workspace / f"out{suffix}"
    source.write_bytes(payload)
    result = run(
        [
            ffmpeg,
            "-v",
            "error",
            "-i",
            str(source),
            # "0:a?" and not "0:a": a clip with no sound is still a clip, and
            # a hard mapping would refuse it.
            "-map",
            "0:v",
            "-map",
            "0:a?",
            "-c",
            "copy",
            "-map_metadata",
            "-1",
            "-map_chapters",
            "-1",
            "-y",
            str(destination),
        ],
        timeout=TIMEOUT_SECONDS,
    )
    if not result.ok or not destination.is_file():
        logger.error("ffmpeg could not re-mux %s: %s", suffix, result.stderr.strip())
        return None
    kinds = streams(destination, ffprobe)
    if kinds is None or not kinds or not set(kinds) <= KEPT:
        logger.error("refusing %s: streams after re-mux were %s", suffix, kinds)
        return None
    return destination.read_bytes()


def streams(path: Path, ffprobe: str) -> tuple[str, ...] | None:
    """Every stream's kind, in order, or None when they cannot be read.

    The positive check this module rests on. An empty result is treated as a
    failure by the caller rather than as "no bad streams": a file ffprobe
    cannot describe is one nobody can vouch for.
    """
    result = run(
        [
            ffprobe,
            "-v",
            "error",
            "-show_entries",
            "stream=codec_type",
            "-of",
            "csv=p=0",
            str(path),
        ],
        timeout=TIMEOUT_SECONDS,
    )
    if not result.ok:
        return None
    return tuple(line.strip().rstrip(",") for line in result.stdout.splitlines() if line.strip())