Optimizing Docker Images for FFmpeg Workloads

ERROR: worker-03 transcode failed s3://ingest/raw/ep-2087.wav
ffmpeg: error while loading shared libraries: libfdk-aac.so.2:
        cannot open shared object file: No such file or directory
ffmpeg_exit_code_total{code="127"} 1  (rising)
image_size_bytes{tag="ffmpeg:latest"} 8.41e8

# syntax=docker/dockerfile:1.7
# FFmpeg 7.1 on Debian bookworm-slim (glibc), multi-stage

# Stage 1: build environment (discarded — never shipped)
FROM debian:bookworm-slim AS builder
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential nasm yasm pkg-config libx264-dev libfdk-aac-dev \
    libmp3lame-dev libopus-dev libvpx-dev zlib1g-dev wget ca-certificates \
    && rm -rf /var/lib/apt/lists/*

RUN wget -qO- https://ffmpeg.org/releases/ffmpeg-7.1.tar.xz | tar -xJ -C /opt
WORKDIR /opt/ffmpeg-7.1

# set -ex makes any configure/make failure abort the build loudly
RUN set -ex; \
    ./configure \
        --prefix=/usr/local \
        --enable-gpl --enable-nonfree \
        --enable-libx264 --enable-libfdk-aac --enable-libmp3lame \
        --enable-libopus --enable-libvpx \
        --disable-debug --disable-doc --disable-ffplay \
        --disable-static --enable-shared \
        --extra-cflags="-O3 -fPIC" \
        --extra-ldflags="-Wl,-rpath,/usr/local/lib" && \
    make -j"$(nproc)" && \
    make install && \
    # strip symbols from binaries and every shared object to cut footprint
    strip /usr/local/bin/ffmpeg /usr/local/bin/ffprobe && \
    find /usr/local/lib -name "*.so*" -exec strip --strip-unneeded {} +

# Stage 2: runtime (the only image that ships)
FROM debian:bookworm-slim AS runtime
# runtime codec packages only — no -dev headers, no compiler
RUN apt-get update && apt-get install -y --no-install-recommends \
    libx264-164 libfdk-aac2 libmp3lame0 libopus0 libvpx7 \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /usr/local/bin/ffmpeg  /usr/local/bin/ffmpeg
COPY --from=builder /usr/local/bin/ffprobe /usr/local/bin/ffprobe
COPY --from=builder /usr/local/lib/libav*.so*     /usr/local/lib/
COPY --from=builder /usr/local/lib/libsw*.so*     /usr/local/lib/
COPY --from=builder /usr/local/lib/libpostproc.so* /usr/local/lib/

# refresh the linker cache, then FAIL THE BUILD if anything is unresolved
RUN ldconfig && \
    ffmpeg -version > /dev/null 2>&1 \
      || (echo "FFmpeg runtime validation failed" && exit 1)

# stamp the codec matrix into image metadata for provenance
LABEL org.mediapipeline.ffmpeg.version="7.1" \
      org.mediapipeline.codecs="h264,aac,opus,mp3,vp9" \
      org.mediapipeline.base="debian:bookworm-slim"

# never run media jobs as root
RUN useradd -m -u 1000 media-worker && \
    chown -R media-worker:media-worker /usr/local/bin /usr/local/lib
USER media-worker

ENTRYPOINT ["ffmpeg"]

# Python 3.10+
# ffmpeg/ffprobe from the runtime image above must be on PATH
import subprocess
import logging
from pathlib import Path

logger = logging.getLogger(__name__)


def run_ffmpeg_transcode(
    input_path: Path,
    output_path: Path,
    args: list[str],
    timeout: int = 3600,      # hard wall-clock ceiling per job (seconds)
    max_retries: int = 2,     # only transient faults consume a retry
) -> dict:
    """Run FFmpeg with a hard timeout and deterministic exit-code mapping."""
    cmd = [
        "ffmpeg", "-y", "-hide_banner", "-loglevel", "warning",
        "-i", str(input_path), *args, str(output_path),
    ]

    for attempt in range(max_retries + 1):
        try:
            logger.info("ffmpeg attempt %d/%d: %s",
                        attempt + 1, max_retries + 1, " ".join(cmd))
            result = subprocess.run(
                cmd, capture_output=True, text=True,
                timeout=timeout, check=True,
            )
            return {"status": "success", "stderr": result.stderr}

        except subprocess.TimeoutExpired as e:
            # transient: the node was starved, not the asset — retry
            logger.error("timeout after %ds (attempt %d)", timeout, attempt + 1)
            if attempt == max_retries:
                raise RuntimeError("ffmpeg exhausted retries on timeout") from e

        except subprocess.CalledProcessError as e:
            err = (e.stderr or "").strip()
            # deterministic corruption: retrying burns the same cycles — fail now
            if "Invalid data found" in err or "moov atom not found" in err:
                raise ValueError(f"Corrupt input, do not retry: {input_path}") from e
            if attempt == max_retries:
                raise RuntimeError(f"ffmpeg failed after retries: {err}") from e

    return {"status": "failed"}

# image should land near ~150MB, not 800MB+
docker images ffmpeg:7.1 --format '{{.Size}}'

# any "not found" line here means a shared object is missing -> fail
docker run --rm ffmpeg:7.1 -hide_banner -version
docker run --rm --entrypoint ldd ffmpeg:7.1 /usr/local/bin/ffmpeg | grep "not found" \
  && echo "BROKEN LINKAGE" || echo "linkage OK"

# every contracted codec must be present; a miss exits non-zero
docker run --rm --entrypoint ffmpeg ffmpeg:7.1 -hide_banner -codecs 2>/dev/null \
  | grep -E '\b(aac|mp3|opus|libx264|libvpx)\b' \
  || { echo "CRITICAL: required codec missing"; exit 1; }