fleetmesh-node 0.2.0__py3-none-any.whl

node/planes/services/compute/executors/media.py

@@ -0,0 +1,898 @@
+"""FfmpegTranscodeExecutor: deterministic & progressive media transcoding on the Mesh Compute plane.
+
+Executes NIP-90 kind=5201 and ComputeWire 1.1 video/audio transcode jobs on any
+meshnode with `ffmpeg` installed (or in mock_mode for deterministic unit tests).
+Verifies input and output blobs using 1024-byte `RhioBaoTree` Merkle roots.
+"""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import ipaddress
+import json
+import os
+import shutil
+import socket
+import ssl
+import subprocess
+import tempfile
+import time
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Mapping, Optional, TypedDict
+
+from fleetmesh_core.crypto import crypto
+from node.protocols.rhio.store import RhioBaoTree
+from ..common import ComputeError
+from ..sandbox import ComputeLimits
+from .base import ComputeExecutionResult, ComputeExecutor, ComputeQuote
+
+FFMPEG_PROFILE_DIGEST: str = crypto.sha256(b'fleetmesh-ffmpeg-transcode-v1')
+DETERMINISTIC_FFMPEG_THREADS: int = 1
+BITEXACT_MUX_FLAGS: tuple[str, ...] = (
+    '-fflags', '+bitexact',
+    '-flags:v', '+bitexact',
+    '-flags:a', '+bitexact',
+    '-map_metadata', '-1',
+    '-map_chapters', '-1',
+)
+MAX_MEDIA_DOWNLOAD_BYTES: int = 256 * 1024 * 1024
+# Verified downloads kept for reuse, oldest evicted past this total.
+MEDIA_CACHE_MAX_BYTES: int = 2 * 1024 * 1024 * 1024
+
+
+class MediaProfileSpec(TypedDict):
+    width: int
+    height: int
+    video_bitrate_kbps: int
+    audio_sample_rate_hz: int
+    audio_bitrate_kbps: int
+    is_audio: bool
+    fuel_per_sec: int
+
+
+class MediaProbeResult(TypedDict, total=False):
+    video_codec: str
+    pix_fmt: str
+    audio_codec: str
+    has_audio: bool
+    width: int
+    height: int
+    duration_sec: float
+    format_name: str
+
+
+def _validate_remote_media_url(url: str, *, allow_local: bool = False) -> None:
+    """Validate that an HTTP(S) media source URL does not target loopback, link-local, or private IPs."""
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ('http', 'https'):
+        raise ComputeError(f'unsupported media URL scheme: {parsed.scheme!r}')
+    host = (parsed.hostname or '').strip()
+    if not host:
+        raise ComputeError('media source_url is missing hostname')
+    if allow_local:
+        return
+    if host.lower() in ('localhost', 'localhost.localdomain'):
+        raise ComputeError(f'refusing local media source_url host: {host}')
+    try:
+        addrs = [ipaddress.ip_address(host)]
+    except ValueError:
+        try:
+            infos = socket.getaddrinfo(host, parsed.port or (443 if parsed.scheme == 'https' else 80), proto=socket.IPPROTO_TCP)
+        except OSError as exc:
+            raise ComputeError(f'failed to resolve media source_url host {host}: {exc}') from exc
+        addrs = [ipaddress.ip_address(info[4][0]) for info in infos if info[4]]
+    for ip in addrs:
+        if (
+            ip.is_loopback
+            or ip.is_private
+            or ip.is_link_local
+            or ip.is_multicast
+            or ip.is_reserved
+            or ip.is_unspecified
+        ):
+            raise ComputeError(f'refusing non-public media source_url address: {ip}')
+
+
+# Input fields only the node itself may set. A job's requester is a remote
+# peer: a path would read or write any file on this host, and the rest would
+# lift the SSRF guard, the download cap or ship fixture output as a result.
+# run_job strips these before the node adds its own source_path.
+NODE_ONLY_INPUT_KEYS: tuple[str, ...] = (
+    'source_path', 'output_path', 'allow_local_http', 'max_download_bytes', 'allow_synthetic',
+)
+
+
+def requester_input(spec: Mapping[str, Any]) -> Mapping[str, Any]:
+    """`spec` without the fields a remote requester may not set."""
+    return {k: v for k, v in spec.items() if k not in NODE_ONLY_INPUT_KEYS}
+
+
+def _public_peer(sock: socket.socket, allow_local: bool) -> None:
+    """Refuse a connection whose peer turned out non-public.
+
+    Checked on the connected socket, so a DNS answer that changed after
+    _validate_remote_media_url ran, or a redirect to an internal host, is
+    caught where the bytes would come from."""
+    if allow_local:
+        return
+    ip = ipaddress.ip_address(sock.getpeername()[0])
+    if (ip.is_loopback or ip.is_private or ip.is_link_local or ip.is_multicast
+            or ip.is_reserved or ip.is_unspecified):
+        sock.close()
+        raise ComputeError(f'refusing non-public media source_url address: {ip}')
+
+
+def _media_opener(allow_local: bool) -> urllib.request.OpenerDirector:
+    """An opener whose every connection, redirects included, must reach a public address."""
+    import http.client
+
+    class _HTTP(http.client.HTTPConnection):
+        def connect(self) -> None:
+            super().connect()
+            _public_peer(self.sock, allow_local)
+
+    class _HTTPS(http.client.HTTPSConnection):
+        def connect(self) -> None:
+            super().connect()
+            _public_peer(self.sock, allow_local)
+
+    class _HTTPHandler(urllib.request.HTTPHandler):
+        def http_open(self, req: urllib.request.Request) -> Any:
+            return self.do_open(_HTTP, req)
+
+    tls = ssl.create_default_context()
+
+    class _HTTPSHandler(urllib.request.HTTPSHandler):
+        def https_open(self, req: urllib.request.Request) -> Any:
+            return self.do_open(_HTTPS, req, context=tls)
+
+    class _Redirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, req: Any, fp: Any, code: int, msg: str, headers: Any, newurl: str) -> Any:
+            _validate_remote_media_url(newurl, allow_local=allow_local)
+            return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+    return urllib.request.build_opener(_HTTPHandler(), _HTTPSHandler(), _Redirect())
+
+
+MEDIA_PROFILES: dict[str, MediaProfileSpec] = {
+    'remux_faststart_copy': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 160,
+        'is_audio': False,
+        'fuel_per_sec': 150,
+    },
+    'cmaf_segment_2s': {
+        'width': 1280,
+        'height': 720,
+        'video_bitrate_kbps': 2200,
+        'audio_sample_rate_hz': 44100,
+        'audio_bitrate_kbps': 128,
+        'is_audio': False,
+        'fuel_per_sec': 500,
+    },
+    'extract_frame_jpeg': {
+        'width': 480,
+        'height': 270,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 0,
+        'audio_bitrate_kbps': 0,
+        'is_audio': False,
+        'fuel_per_sec': 100,
+    },
+    'normalize_faststart': {
+        'width': 1280,
+        'height': 720,
+        'video_bitrate_kbps': 2800,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 128,
+        'is_audio': False,
+        'fuel_per_sec': 800,
+    },
+    '1080p': {
+        'width': 1920,
+        'height': 1080,
+        'video_bitrate_kbps': 4500,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 192,
+        'is_audio': False,
+        'fuel_per_sec': 1000,
+    },
+    '720p': {
+        'width': 1280,
+        'height': 720,
+        'video_bitrate_kbps': 2500,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 160,
+        'is_audio': False,
+        'fuel_per_sec': 650,
+    },
+    '480p': {
+        'width': 854,
+        'height': 480,
+        'video_bitrate_kbps': 1100,
+        'audio_sample_rate_hz': 44100,
+        'audio_bitrate_kbps': 128,
+        'is_audio': False,
+        'fuel_per_sec': 350,
+    },
+    '360p': {
+        'width': 640,
+        'height': 360,
+        'video_bitrate_kbps': 600,
+        'audio_sample_rate_hz': 24000,
+        'audio_bitrate_kbps': 64,
+        'is_audio': False,
+        'fuel_per_sec': 200,
+    },
+    '320k': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 320,
+        'is_audio': True,
+        'fuel_per_sec': 120,
+    },
+    '256k': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 48000,
+        'audio_bitrate_kbps': 256,
+        'is_audio': True,
+        'fuel_per_sec': 100,
+    },
+    '192k': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 44100,
+        'audio_bitrate_kbps': 192,
+        'is_audio': True,
+        'fuel_per_sec': 80,
+    },
+    '128k': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 44100,
+        'audio_bitrate_kbps': 128,
+        'is_audio': True,
+        'fuel_per_sec': 60,
+    },
+    '64k': {
+        'width': 0,
+        'height': 0,
+        'video_bitrate_kbps': 0,
+        'audio_sample_rate_hz': 24000,
+        'audio_bitrate_kbps': 64,
+        'is_audio': True,
+        'fuel_per_sec': 40,
+    },
+    'vod_1080p_h264': {'width': 1920, 'height': 1080, 'video_bitrate_kbps': 4500, 'audio_sample_rate_hz': 48000, 'audio_bitrate_kbps': 192, 'is_audio': False, 'fuel_per_sec': 1000},
+    'vod_720p_h264': {'width': 1280, 'height': 720, 'video_bitrate_kbps': 2500, 'audio_sample_rate_hz': 48000, 'audio_bitrate_kbps': 160, 'is_audio': False, 'fuel_per_sec': 650},
+    'vod_480p_h264': {'width': 854, 'height': 480, 'video_bitrate_kbps': 1100, 'audio_sample_rate_hz': 44100, 'audio_bitrate_kbps': 128, 'is_audio': False, 'fuel_per_sec': 350},
+    'vod_360p_h264': {'width': 640, 'height': 360, 'video_bitrate_kbps': 600, 'audio_sample_rate_hz': 24000, 'audio_bitrate_kbps': 64, 'is_audio': False, 'fuel_per_sec': 200},
+    'audio_mp3_320k': {'width': 0, 'height': 0, 'video_bitrate_kbps': 0, 'audio_sample_rate_hz': 48000, 'audio_bitrate_kbps': 320, 'is_audio': True, 'fuel_per_sec': 120},
+    'audio_mp3_128k': {'width': 0, 'height': 0, 'video_bitrate_kbps': 0, 'audio_sample_rate_hz': 44100, 'audio_bitrate_kbps': 128, 'is_audio': True, 'fuel_per_sec': 60},
+}
+
+
+def ffmpeg_available() -> bool:
+    """Return True if the host has the `ffmpeg` binary installed on PATH."""
+    return shutil.which('ffmpeg') is not None
+
+
+def compute_deterministic_ffmpeg_job_key(
+    source_tree_root: str = '',
+    profile: str = '720p',
+    start_sec: float = 0.0,
+    duration_limit_sec: Optional[float] = None,
+    *,
+    source_sha256: str = '',
+    width: int = 0,
+    height: int = 0,
+    video_bitrate_kbps: int = 0,
+    audio_bitrate_kbps: int = 0,
+    audio_sample_rate_hz: int = 0,
+) -> str:
+    """Compute the canonical content-addressed deterministic job key for an ffmpeg compute job."""
+    prof = MEDIA_PROFILES.get(profile, MEDIA_PROFILES['720p'])
+    eff_w = int(width or prof['width'] or 0)
+    eff_h = int(height or prof['height'] or 0)
+    eff_v = int(video_bitrate_kbps or prof['video_bitrate_kbps'] or 0)
+    eff_a = int(audio_bitrate_kbps or prof['audio_bitrate_kbps'] or 0)
+    eff_ar = int(audio_sample_rate_hz or prof['audio_sample_rate_hz'] or 0)
+    dur_str = (
+        f'{float(duration_limit_sec):.3f}'
+        if duration_limit_sec is not None and float(duration_limit_sec) > 0
+        else 'full'
+    )
+    src_id = (source_tree_root or source_sha256 or '').strip().lower()
+    canon = (
+        f'fleetmesh-ffmpeg-job-v1:{FFMPEG_PROFILE_DIGEST}:{src_id}:{profile}:'
+        f'{float(start_sec):.3f}:{dur_str}:{eff_w}x{eff_h}:{eff_v}k:{eff_a}k:{eff_ar}hz'
+    )
+    return crypto.sha256(canon.encode('utf-8'))
+
+
+def _probe_media_file(path: str) -> MediaProbeResult:
+    """Probe codec, dimensions, and duration via `ffprobe` when available."""
+    ffprobe_bin = shutil.which('ffprobe')
+    if not ffprobe_bin or not os.path.isfile(path):
+        return {}
+    try:
+        proc = subprocess.run(
+            [
+                ffprobe_bin, '-v', 'error',
+                '-show_entries', 'stream=codec_type,codec_name,pix_fmt,width,height:format=format_name,duration',
+                '-of', 'json', path,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+            start_new_session=True,
+        )
+        if proc.returncode != 0 or not proc.stdout:
+            return {}
+        info = json.loads(proc.stdout)
+        v_codec = ''
+        pix_fmt = ''
+        a_codec = ''
+        has_audio = False
+        width = 0
+        height = 0
+        for st in (info.get('streams') or []):
+            ctype = str(st.get('codec_type') or '')
+            if ctype == 'video' and not v_codec:
+                v_codec = str(st.get('codec_name') or '').lower()
+                pix_fmt = str(st.get('pix_fmt') or '').lower()
+                width = int(st.get('width') or 0)
+                height = int(st.get('height') or 0)
+            elif ctype == 'audio' and not a_codec:
+                has_audio = True
+                a_codec = str(st.get('codec_name') or '').lower()
+        fmt = info.get('format') or {}
+        duration_sec = float(fmt.get('duration') or 0.0)
+        return {
+            'video_codec': v_codec,
+            'pix_fmt': pix_fmt,
+            'audio_codec': a_codec,
+            'has_audio': has_audio,
+            'width': width,
+            'height': height,
+            'duration_sec': duration_sec,
+            'format_name': str(fmt.get('format_name') or '').lower(),
+        }
+    except Exception:
+        return {}
+
+
+class FfmpegTranscodeExecutor(ComputeExecutor):
+    """Media transcoding runtime driver for H.264/AAC faststart MP4 and MP3 renditions."""
+
+    engine_id: str = 'ffmpeg'
+    wasi_profile_digest: str = FFMPEG_PROFILE_DIGEST
+
+    def __init__(
+        self,
+        mock_mode: bool = False,
+        *,
+        allow_local_http: bool = False,
+        max_download_bytes: int = MAX_MEDIA_DOWNLOAD_BYTES,
+        allow_synthetic: bool = False,
+        cache_dir: Optional[str] = None,
+        cache_max_bytes: int = MEDIA_CACHE_MAX_BYTES,
+    ) -> None:
+        self.mock_mode: bool = mock_mode
+        # Where verified source downloads are kept (the node's data dir, made
+        # owner-only); None keeps nothing between jobs.
+        self.cache_dir: Optional[str] = cache_dir
+        self.cache_max_bytes: int = cache_max_bytes
+        # Operator settings, never read from a job (NODE_ONLY_INPUT_KEYS).
+        self.allow_local_http: bool = allow_local_http
+        self.max_download_bytes: int = max_download_bytes
+        self.allow_synthetic: bool = allow_synthetic
+
+    def is_live_runnable(self) -> bool:
+        return self.mock_mode or ffmpeg_available()
+
+    def quote(
+        self,
+        module_spec: Mapping[str, Any],
+        input_spec: Mapping[str, Any],
+        limits: ComputeLimits,
+    ) -> ComputeQuote:
+        profile_name = str(input_spec.get('profile') or '720p')
+        prof = MEDIA_PROFILES.get(profile_name, MEDIA_PROFILES['720p'])
+        dur = float(input_spec.get('duration_limit_sec') or input_spec.get('duration_sec') or 30.0)
+        dur = max(1.0, dur)
+        w = int(input_spec.get('width') or prof['width'] or 0)
+        h = int(input_spec.get('height') or prof['height'] or 0)
+        if w > 0 and h > 0:
+            pixel_ratio = max(0.15, (w * h) / float(1920 * 1080))
+            fuel_est = max(1000, int(dur * pixel_ratio * 1000))
+        else:
+            fuel_est = max(500, int(dur * int(prof.get('fuel_per_sec', 100))))
+        fuel_est = min(fuel_est, limits.max_fuel)
+        return ComputeQuote(
+            fuel_estimate=fuel_est,
+            rate_unit='msat_per_mfuel',
+            rate_amount=15,
+            engine_id=self.engine_id,
+        )
+
+    def _cache_get(self, sha256: str) -> Optional[str]:
+        """A cached source whose bytes still hash to `sha256`, or None."""
+        if not self.cache_dir:
+            return None
+        path = os.path.join(self.cache_dir, f'{sha256}.bin')
+        if not os.path.isfile(path) or os.path.islink(path) or os.path.getsize(path) == 0:
+            return None
+        if RhioBaoTree.compute_file_root(path)[0].lower() != sha256:
+            return None
+        os.utime(path)  # recently used: evicted last
+        return path
+
+    def _cache_put(self, sha256: str, staged: str) -> None:
+        """Keep a verified download, then evict the least recently used past cache_max_bytes."""
+        if not self.cache_dir:
+            return
+        with contextlib.suppress(OSError):
+            os.makedirs(self.cache_dir, mode=0o700, exist_ok=True)
+            target = os.path.join(self.cache_dir, f'{sha256}.bin')
+            if not os.path.isfile(target):
+                tmp = f'{target}.{os.getpid()}.tmp'
+                shutil.copy2(staged, tmp)
+                os.replace(tmp, target)
+            entries = sorted(
+                (os.stat(p).st_mtime, os.path.getsize(p), p)
+                for p in (os.path.join(self.cache_dir, fn) for fn in os.listdir(self.cache_dir))
+                if p.endswith('.bin') and os.path.isfile(p)
+            )
+            total = sum(size for _, size, _ in entries)
+            for _, size, old in entries:
+                if total <= self.cache_max_bytes or old == target:
+                    continue
+                os.remove(old)
+                total -= size
+
+    def _resolve_input_to_file(
+        self,
+        input_spec: Mapping[str, Any],
+        work_dir: str,
+    ) -> tuple[str, int]:
+        """Resolve input specification to a local file path and byte size."""
+        src_path = str(input_spec.get('source_path') or '').strip()
+        if src_path and os.path.isfile(src_path):
+            return src_path, os.path.getsize(src_path)
+
+        raw = input_spec.get('raw')
+        if raw is not None:
+            if isinstance(raw, str):
+                try:
+                    raw_bytes = bytes.fromhex(raw)
+                except ValueError:
+                    raw_bytes = raw.encode('utf-8')
+            elif isinstance(raw, (bytes, bytearray)):
+                raw_bytes = bytes(raw)
+            else:
+                raw_bytes = b''
+            if raw_bytes:
+                staged_in = os.path.join(work_dir, 'input_raw.bin')
+                with open(staged_in, 'wb') as f:
+                    f.write(raw_bytes)
+                return staged_in, len(raw_bytes)
+
+        src_url = str(input_spec.get('source_url') or '').strip()
+        expected_sha = str(input_spec.get('source_sha256') or '').strip().lower()
+        expected_root = str(input_spec.get('source_tree_root') or '').strip().lower()
+        if len(expected_sha) == 64:
+            cached_bin = self._cache_get(expected_sha)
+            if cached_bin is not None:
+                return cached_bin, os.path.getsize(cached_bin)
+
+        if src_url:
+            # Only http(s): a file:// URL or a bare path would read this host's files.
+            if not src_url.startswith(('http://', 'https://')):
+                raise ComputeError('media source_url must be http(s)')
+            _validate_remote_media_url(src_url, allow_local=self.allow_local_http)
+            max_bytes = self.max_download_bytes
+            staged_in = os.path.join(work_dir, 'input_download.bin')
+            req = urllib.request.Request(src_url, headers={'User-Agent': 'FleetMesh-Compute/1.1'})
+            total_read = 0
+            opener = _media_opener(self.allow_local_http)
+            with opener.open(req, timeout=180) as resp, open(staged_in, 'wb') as out_f:
+                while True:
+                    chunk = resp.read(256 * 1024)
+                    if not chunk:
+                        break
+                    total_read += len(chunk)
+                    if total_read > max_bytes:
+                        raise ComputeError(f'media input download exceeded {max_bytes} byte limit')
+                    out_f.write(chunk)
+            if len(expected_sha) == 64 or len(expected_root) == 64:
+                got_sha, got_root, _ = RhioBaoTree.compute_file_root(staged_in)
+                if len(expected_sha) == 64 and got_sha.lower() != expected_sha:
+                    raise ComputeError(f'input sha256 mismatch: expected {expected_sha}, got {got_sha}')
+                if len(expected_root) == 64 and got_root.lower() != expected_root:
+                    raise ComputeError(f'input tree_root mismatch: expected {expected_root}, got {got_root}')
+                if len(expected_sha) == 64:
+                    self._cache_put(expected_sha, staged_in)
+            return staged_in, os.path.getsize(staged_in)
+
+        if self.mock_mode or self.allow_synthetic:
+            staged_in = os.path.join(work_dir, 'input_synthetic.bin')
+            seed_bytes = json.dumps(dict(input_spec), sort_keys=True).encode('utf-8')
+            with open(staged_in, 'wb') as f:
+                f.write(seed_bytes)
+            return staged_in, len(seed_bytes)
+
+        raise ComputeError('ffmpeg job requires a valid source_path, raw input, or reachable source_url')
+
+    @staticmethod
+    def _build_synthetic_output(
+        src_path: str,
+        out_path: str,
+        profile_name: str,
+        w: int,
+        h: int,
+        v_kbps: int,
+        a_kbps: int,
+        ar_hz: int,
+        is_audio: bool,
+    ) -> None:
+        """Produce a deterministic tagged container payload in mock_mode or for synthetic fixtures."""
+        with open(src_path, 'rb') as f:
+            raw_in = f.read(32 * 1024 * 1024)
+        meta_box = json.dumps({
+            'engine': 'ffmpeg',
+            'profile': profile_name,
+            'resolution': f'{w}x{h}' if not is_audio else f'Audio {a_kbps}kbps',
+            'video_bitrate_kbps': v_kbps,
+            'audio_bitrate_kbps': a_kbps,
+            'audio_sample_rate_hz': ar_hz,
+        }, sort_keys=True).encode('utf-8')
+        if profile_name == 'extract_frame_jpeg':
+            payload = b'\xff\xd8\xff\xe0\x00\x10JFIF\x00\x01\x01\x00\x00\x01\x00\x01\x00\x00' + meta_box + hashlib.sha256(raw_in).digest() + b'\xff\xd9'
+        elif is_audio:
+            tag = b'TAG' + f'{profile_name}:{a_kbps}k:{ar_hz}'.encode('utf-8').ljust(125, b'\x00')[:125]
+            payload = raw_in + tag
+        else:
+            uuid_hdr = b'uuid' + hashlib.md5(f'fleetmesh:{profile_name}'.encode('utf-8')).digest() + meta_box
+            payload = raw_in + (len(uuid_hdr) + 4).to_bytes(4, 'big') + uuid_hdr
+        with open(out_path, 'wb') as out_f:
+            out_f.write(payload)
+
+    def execute(
+        self,
+        job_payload: Mapping[str, Any],
+        fuel_cap: int,
+    ) -> ComputeExecutionResult:
+        v_mode = self.verification_mode(job_payload, default='delivery')
+        raw_inp = job_payload.get('input')
+        input_spec = dict(raw_inp) if isinstance(raw_inp, Mapping) else {}
+        for k in (
+            'raw', 'profile', 'source_path', 'source_url', 'source_sha256', 'source_tree_root',
+            'output_path', 'duration_sec', 'duration_limit_sec', 'start_sec',
+            'width', 'height', 'video_bitrate_kbps', 'audio_bitrate_kbps',
+            'audio_sample_rate_hz', 'is_audio', 'vod_id', 'threads',
+        ):
+            if k not in input_spec and k in job_payload:
+                input_spec[k] = job_payload[k]
+
+        profile_name = str(input_spec.get('profile') or '720p')
+        prof = MEDIA_PROFILES.get(profile_name, MEDIA_PROFILES['720p'])
+        is_audio = bool(input_spec.get('is_audio', prof['is_audio']))
+        w = int(input_spec.get('width') or prof['width'] or (0 if is_audio else 1280))
+        h = int(input_spec.get('height') or prof['height'] or (0 if is_audio else 720))
+        v_kbps = int(input_spec.get('video_bitrate_kbps') or prof['video_bitrate_kbps'] or (0 if is_audio else 2500))
+        a_kbps = int(input_spec.get('audio_bitrate_kbps') or prof['audio_bitrate_kbps'] or 128)
+        ar_hz = int(input_spec.get('audio_sample_rate_hz') or prof['audio_sample_rate_hz'] or 48000)
+        start_sec = float(input_spec.get('start_sec') or 0.0)
+        dur_limit_raw = input_spec.get('duration_limit_sec')
+        dur_limit: Optional[float] = float(dur_limit_raw) if dur_limit_raw is not None and float(dur_limit_raw) > 0 else None
+        timeout_s = int(job_payload.get('timeout_seconds') or input_spec.get('timeout_seconds') or 3600)
+        raw_threads = input_spec.get('threads')
+        max_threads = max(1, int(raw_threads)) if raw_threads is not None else DETERMINISTIC_FFMPEG_THREADS
+        x264_det_params = f'threads={max_threads}:deterministic=1:sliced-threads=0'
+        job_key = compute_deterministic_ffmpeg_job_key(
+            source_tree_root=str(input_spec.get('source_tree_root') or ''),
+            source_sha256=str(input_spec.get('source_sha256') or input_spec.get('sha256') or ''),
+            profile=profile_name,
+            start_sec=start_sec,
+            duration_limit_sec=dur_limit,
+            width=int(input_spec.get('width') or 0),
+            height=int(input_spec.get('height') or 0),
+            video_bitrate_kbps=int(input_spec.get('video_bitrate_kbps') or 0),
+            audio_bitrate_kbps=int(input_spec.get('audio_bitrate_kbps') or 0),
+            audio_sample_rate_hz=int(input_spec.get('audio_sample_rate_hz') or 0),
+        )
+        progress_cb: Optional[Callable[[str, float, Mapping[str, Any]], None]] = job_payload.get('progress_callback')
+        cb_errors = 0
+
+        t0_wall = time.monotonic()
+        t0_cpu = time.process_time()
+
+        with tempfile.TemporaryDirectory(prefix='fm_ffmpeg_') as work_dir:
+            src_path, input_bytes = self._resolve_input_to_file(input_spec, work_dir)
+            ext = 'jpg' if profile_name == 'extract_frame_jpeg' else ('mp3' if is_audio else 'mp4')
+            staged_out = os.path.join(work_dir, f'output_{profile_name}.{ext}')
+
+            ffmpeg_bin = shutil.which('ffmpeg')
+            ran_ffmpeg = False
+
+            if not self.mock_mode and ffmpeg_bin and input_bytes > 256:
+                pre_probe = _probe_media_file(src_path)
+                v_codec = str(pre_probe.get('video_codec') or '')
+                pix_fmt = str(pre_probe.get('pix_fmt') or '')
+                a_codec = str(pre_probe.get('audio_codec') or '')
+                has_audio = bool(pre_probe.get('has_audio', True))
+
+                def _nice_child() -> None:
+                    if hasattr(os, 'nice'):
+                        with contextlib.suppress(OSError):
+                            os.nice(2)
+
+                preexec = _nice_child if os.name == 'posix' else None
+                pre_input_args: list[str] = []
+                post_input_args: list[str] = []
+                if start_sec > 0:
+                    pre_input_args.extend(['-ss', f'{start_sec:.3f}'])
+                if dur_limit is not None:
+                    post_input_args.extend(['-t', f'{int(dur_limit) if dur_limit.is_integer() else dur_limit}'])
+
+                if callable(progress_cb):
+                    try:
+                        progress_cb('running', 0.1, {'profile': profile_name, 'input_bytes': input_bytes})
+                    except Exception:
+                        cb_errors += 1
+
+                # Fast remux path when normalizing an already 8-bit H.264 stream without duration clipping
+                if (
+                    profile_name in ('normalize_faststart', 'remux_faststart_copy')
+                    and not is_audio
+                    and dur_limit is None
+                    and start_sec <= 0
+                    and v_codec == 'h264'
+                    and pix_fmt in ('yuv420p', 'yuvj420p', '')
+                ):
+                    remux_cmd = [
+                        ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                        '-i', src_path,
+                        *BITEXACT_MUX_FLAGS,
+                        '-map', '0:v:0', '-map', '0:a:0?',
+                        '-c:v', 'copy',
+                        *(['-c:a', 'copy'] if (not has_audio or a_codec == 'aac') else ['-c:a', 'aac', '-b:a', f'{a_kbps}k', '-ac', '2']),
+                        '-movflags', '+faststart', staged_out,
+                    ]
+                    try:
+                        proc = subprocess.run(
+                            remux_cmd,
+                            capture_output=True,
+                            timeout=min(timeout_s, 600),
+                            check=False,
+                            preexec_fn=preexec,
+                            start_new_session=True,
+                        )
+                    except subprocess.TimeoutExpired:
+                        ran_ffmpeg = False
+                    else:
+                        if proc.returncode == 0 and os.path.isfile(staged_out) and os.path.getsize(staged_out) > 256:
+                            ran_ffmpeg = True
+
+                if not ran_ffmpeg:
+                    if profile_name == 'extract_frame_jpeg':
+                        frame_w = w if w > 0 else 480
+                        cmd = [
+                            ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                            *pre_input_args,
+                            '-i', src_path,
+                            *BITEXACT_MUX_FLAGS,
+                            '-frames:v', '1',
+                            '-vf', f'scale={frame_w}:-2:flags=fast_bilinear',
+                            '-q:v', '5',
+                            '-f', 'image2',
+                            staged_out,
+                        ]
+                    elif is_audio:
+                        cmd = [
+                            ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                            *pre_input_args,
+                            '-i', src_path,
+                            *post_input_args,
+                            *BITEXACT_MUX_FLAGS,
+                            '-vn', '-c:a', 'libmp3lame', '-ar', str(ar_hz), '-b:a', f'{a_kbps}k',
+                            '-write_xing', '0', '-id3v2_version', '0',
+                            staged_out,
+                        ]
+                    elif profile_name in ('normalize_faststart', 'remux_faststart_copy', 'cmaf_segment_2s'):
+                        scale_vf = "scale='min(1280,trunc(iw/2)*2)':-2:flags=fast_bilinear"
+                        mov_flags = (
+                            'frag_keyframe+empty_moov+default_base_moof'
+                            if profile_name == 'cmaf_segment_2s'
+                            else '+faststart'
+                        )
+                        cmd = [
+                            ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                            *pre_input_args,
+                            '-i', src_path,
+                            *post_input_args,
+                            *BITEXACT_MUX_FLAGS,
+                            '-map', '0:v:0', '-map', '0:a:0?',
+                            '-vf', scale_vf,
+                            '-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'fastdecode', '-crf', '24',
+                            '-x264-params', x264_det_params,
+                            '-profile:v', 'high', '-level', '4.1', '-pix_fmt', 'yuv420p',
+                            '-video_track_timescale', '90000',
+                            '-c:a', 'aac', '-ar', str(ar_hz), '-b:a', f'{a_kbps}k', '-ac', '2',
+                            '-movflags', mov_flags, staged_out,
+                        ]
+                    else:
+                        scale_vf = f'scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2'
+                        cmd = [
+                            ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                            *pre_input_args,
+                            '-i', src_path,
+                            *post_input_args,
+                            *BITEXACT_MUX_FLAGS,
+                            '-map', '0:v:0', '-map', '0:a:0?',
+                            '-vf', scale_vf,
+                            '-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'fastdecode',
+                            '-x264-params', x264_det_params,
+                            '-b:v', f'{v_kbps}k', '-maxrate', f'{v_kbps}k', '-bufsize', f'{v_kbps * 2}k',
+                            '-pix_fmt', 'yuv420p', '-video_track_timescale', '90000',
+                            '-c:a', 'aac', '-ar', str(ar_hz), '-b:a', f'{a_kbps}k', '-ac', '2',
+                            '-movflags', '+faststart', staged_out,
+                        ]
+
+                    try:
+                        proc = subprocess.run(
+                            cmd,
+                            capture_output=True,
+                            timeout=timeout_s,
+                            check=False,
+                            preexec_fn=preexec,
+                            start_new_session=True,
+                        )
+                        if proc.returncode == 0 and os.path.isfile(staged_out) and os.path.getsize(staged_out) > 256:
+                            ran_ffmpeg = True
+                    except subprocess.TimeoutExpired as exc:
+                        raise ComputeError(f'ffmpeg transcode timed out after {timeout_s}s') from exc
+
+                    # Video-only fallback if source audio track is absent or corrupt
+                    if not ran_ffmpeg and not is_audio and profile_name != 'extract_frame_jpeg':
+                        scale_vf = (
+                            "scale='min(1280,trunc(iw/2)*2)':-2:flags=fast_bilinear"
+                            if profile_name in ('normalize_faststart', 'remux_faststart_copy', 'cmaf_segment_2s')
+                            else f'scale={w}:{h}:force_original_aspect_ratio=decrease,pad={w}:{h}:(ow-iw)/2:(oh-ih)/2'
+                        )
+                        fallback_cmd = [
+                            ffmpeg_bin, '-y', '-v', 'error', '-threads', str(max_threads),
+                            *pre_input_args,
+                            '-i', src_path,
+                            *post_input_args,
+                            *BITEXACT_MUX_FLAGS,
+                            '-map', '0:v:0', '-an',
+                            '-vf', scale_vf,
+                            '-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'fastdecode', '-crf', '24',
+                            '-x264-params', x264_det_params,
+                            '-profile:v', 'baseline', '-level', '3.0', '-pix_fmt', 'yuv420p',
+                            '-video_track_timescale', '90000',
+                            '-movflags', '+faststart', staged_out,
+                        ]
+                        try:
+                            proc2 = subprocess.run(
+                                fallback_cmd,
+                                capture_output=True,
+                                timeout=timeout_s,
+                                check=False,
+                                preexec_fn=preexec,
+                                start_new_session=True,
+                            )
+                            if proc2.returncode == 0 and os.path.isfile(staged_out) and os.path.getsize(staged_out) > 256:
+                                ran_ffmpeg = True
+                        except subprocess.TimeoutExpired as exc:
+                            raise ComputeError(f'ffmpeg fallback transcode timed out after {timeout_s}s') from exc
+
+            if not ran_ffmpeg:
+                if self.mock_mode or self.allow_synthetic:
+                    self._build_synthetic_output(src_path, staged_out, profile_name, w, h, v_kbps, a_kbps, ar_hz, is_audio)
+                else:
+                    raise ComputeError(f'ffmpeg failed to transcode media for profile {profile_name}')
+
+            out_sha, out_root, out_size = RhioBaoTree.compute_file_root(staged_out)
+            if len(out_sha) == 64:
+                self._cache_put(out_sha, staged_out)
+                bstore = job_payload.get('_blob_store')
+                if bstore is not None and hasattr(bstore, 'store_blob_from_file'):
+                    with contextlib.suppress(Exception):
+                        bstore.store_blob_from_file(staged_out, move=False)
+            post_probe: MediaProbeResult = _probe_media_file(staged_out) if ran_ffmpeg else {}
+            out_dur = float(post_probe.get('duration_sec') or dur_limit or input_spec.get('duration_sec') or 15.0)
+            out_w = int(post_probe.get('width') or w)
+            out_h = int(post_probe.get('height') or h)
+            out_res = f'{out_w}x{out_h}' if (out_w > 0 and out_h > 0 and not is_audio) else (f'Audio {a_kbps}kbps' if is_audio else '1280x720')
+
+            dest_out_path = str(input_spec.get('output_path') or '').strip()
+            if dest_out_path:
+                os.makedirs(os.path.dirname(os.path.abspath(dest_out_path)), exist_ok=True)
+                shutil.move(staged_out, dest_out_path)
+
+            wall_s = max(0.001, round(time.monotonic() - t0_wall, 4))
+            cpu_s = max(0.001, round(time.process_time() - t0_cpu, 4))
+
+            if callable(progress_cb):
+                try:
+                    progress_cb('finalizing', 1.0, {'output_sha256': out_sha, 'output_size': out_size})
+                except Exception:
+                    cb_errors += 1
+
+            pixel_factor = max(0.15, (out_w * out_h) / float(1920 * 1080)) if not is_audio else 0.1
+            fuel_used = max(
+                10,
+                int(max(1.0, out_dur) * pixel_factor * 100) + int(out_size // 4096),
+            )
+            if fuel_cap > 0 and fuel_used > fuel_cap:
+                raise ComputeError(f'media job exceeded fuel cap ({fuel_used} > {fuel_cap})')
+
+            manifest = {
+                'engine': self.engine_id,
+                'job_key': job_key,
+                'profile': profile_name,
+                'vod_id': str(input_spec.get('vod_id') or ''),
+                'output_sha256': out_sha,
+                'output_tree_root': out_root,
+                'output_size': out_size,
+                'output_path': dest_out_path,
+                'resolution': out_res,
+                'width': out_w,
+                'height': out_h,
+                'duration_sec': round(out_dur, 2),
+                'video_bitrate_kbps': v_kbps,
+                'audio_bitrate_kbps': a_kbps,
+                'audio_sample_rate_hz': ar_hz,
+                'is_audio': is_audio,
+                'ran_ffmpeg': ran_ffmpeg,
+                'deterministic': True,
+                'threads': max_threads,
+                'cpu_seconds': cpu_s,
+                'wall_seconds': wall_s,
+                'fuel_used': fuel_used,
+            }
+            raw_output = json.dumps(manifest, sort_keys=True, separators=(',', ':')).encode('utf-8')
+            return ComputeExecutionResult(
+                result_hash=out_sha,
+                raw_output=raw_output,
+                fuel_used=fuel_used,
+                engine_id=self.engine_id,
+                wasi_profile_digest=self.wasi_profile_digest,
+                counters={
+                    'cpu_seconds': cpu_s,
+                    'wall_seconds': wall_s,
+                    'input_bytes': input_bytes,
+                    'output_bytes': out_size,
+                    'duration_sec': round(out_dur, 2),
+                    'callback_errors': cb_errors,
+                },
+                verification_mode=v_mode,
+            )
+
+
+__all__ = [
+    'BITEXACT_MUX_FLAGS',
+    'DETERMINISTIC_FFMPEG_THREADS',
+    'FFMPEG_PROFILE_DIGEST',
+    'MAX_MEDIA_DOWNLOAD_BYTES',
+    'MEDIA_PROFILES',
+    'MediaProbeResult',
+    'MediaProfileSpec',
+    'compute_deterministic_ffmpeg_job_key',
+    'ffmpeg_available',
+    'FfmpegTranscodeExecutor',
+]