Add word-by-word motivational captions template

app/api/media.py

@@ -33,6 +33,18 @@ async def stream_file(path: Path) -> AsyncIterator[bytes]:
             yield chunk
 
 
+def _download_headers(path: Path, request_id: str) -> dict[str, str]:
+    return {
+        "Content-Disposition": f'attachment; filename="{path.name}"',
+        "Content-Length": str(path.stat().st_size),
+        "X-Request-ID": request_id,
+        "X-Content-Type-Options": "nosniff",
+        # Media links are capabilities or workspace-scoped resources. Avoid
+        # intermediary/browser cache retention beyond their authorization.
+        "Cache-Control": "private, no-store",
+    }
+
+
 @router.get("/v1/media/{request_id}/{filename}", name="download_media")
 async def download_media(request: Request, request_id: str, filename: str) -> StreamingResponse:
     request.state.operation = "media.download"
@@ -57,12 +69,9 @@ async def download_media(request: Request, request_id: str, filename: str) -> St
     else:
         path = container.cleanup.resolve_download(request_id, filename)
     media_type = container.validator.infer_mime(path)
-    headers = {
-        "Content-Disposition": f'attachment; filename="{path.name}"',
-        "Content-Length": str(path.stat().st_size),
-        "X-Request-ID": request_id,
-    }
-    return StreamingResponse(stream_file(path), media_type=media_type, headers=headers)
+    return StreamingResponse(
+        stream_file(path), media_type=media_type, headers=_download_headers(path, request_id)
+    )
 
 
 @router.get("/v1/media/signed/{request_id}/{filename}", name="download_signed_media")
@@ -80,15 +89,12 @@ async def download_signed_media(
     signature is bound to the exact request ID and filename.
     """
     request.state.operation = "media.signed_download"
-    signer = MediaURLSigner(request.app.state.container.settings)
+    container = request.app.state.container
+    signer = MediaURLSigner(container.settings)
     if not signer.verify(request_id, filename, expires, signature):
         raise NotFoundError("Output file not found")
-    path = request.app.state.container.cleanup.resolve_download(request_id, filename)
-    media_type = request.app.state.container.validator.infer_mime(path)
-    headers = {
-        "Content-Disposition": f'attachment; filename="{path.name}"',
-        "Content-Length": str(path.stat().st_size),
-        "X-Request-ID": request_id,
-        "Cache-Control": "private, max-age=60",
-    }
-    return StreamingResponse(stream_file(path), media_type=media_type, headers=headers)
+    path = container.cleanup.resolve_download(request_id, filename)
+    media_type = container.validator.infer_mime(path)
+    return StreamingResponse(
+        stream_file(path), media_type=media_type, headers=_download_headers(path, request_id)
+    )

app/core/request_limits.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+
+class RequestBodyLimitMiddleware:
+    """Enforce a hard byte ceiling on HTTP request bodies, including chunked bodies."""
+
+    def __init__(self, app: ASGIApp, max_bytes: int) -> None:
+        self.app = app
+        self.max_bytes = max_bytes
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or scope["method"] in {"GET", "HEAD", "OPTIONS"}:
+            await self.app(scope, receive, send)
+            return
+
+        headers = {key.lower(): value for key, value in scope.get("headers", [])}
+        declared = headers.get(b"content-length")
+        if declared:
+            try:
+                if int(declared) > self.max_bytes:
+                    await self._too_large(scope, receive, send)
+                    return
+            except ValueError:
+                # Invalid Content-Length is left to the ASGI server/parser; the
+                # streamed byte counter below remains authoritative.
+                pass
+
+        received = 0
+        exceeded = False
+        response_started = False
+
+        async def limited_receive() -> Message:
+            nonlocal received, exceeded
+            message = await receive()
+            if message["type"] == "http.request":
+                received += len(message.get("body", b""))
+                if received > self.max_bytes:
+                    exceeded = True
+                    # Do not pass an over-limit chunk into a multipart parser or
+                    # request.body(); it could otherwise spool/read the full body.
+                    return {"type": "http.disconnect"}
+            return message
+
+        async def guarded_send(message: Message) -> None:
+            nonlocal response_started
+            if message["type"] == "http.response.start":
+                if exceeded and not response_started:
+                    response_started = True
+                    await send({
+                        "type": "http.response.start",
+                        "status": 413,
+                        "headers": [
+                            (b"content-type", b"application/json"),
+                            (b"cache-control", b"no-store"),
+                        ],
+                    })
+                    return
+                response_started = True
+            if exceeded:
+                if message["type"] == "http.response.body" and not response_started:
+                    return
+                if message["type"] == "http.response.body":
+                    await send({"type": "http.response.body", "body": b'{"detail":"Request body too large"}', "more_body": False})
+                return
+            await send(message)
+
+        try:
+            await self.app(scope, limited_receive, guarded_send)
+        except Exception:
+            if exceeded and not response_started:
+                await self._too_large(scope, receive, send)
+                return
+            raise
+
+    async def _too_large(self, scope: Scope, receive: Receive, send: Send) -> None:
+        body = b'{"detail":"Request body too large"}'
+        await send({
+            "type": "http.response.start",
+            "status": 413,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(body)).encode("ascii")),
+                (b"cache-control", b"no-store"),
+            ],
+        })
+        await send({"type": "http.response.body", "body": body, "more_body": False})

app/operations/mix_audio.py

@@ -138,3 +138,57 @@ async def add_audio(
             "duration_seconds": duration,
         },
     )
+
+
+async def duck_background_music(
+    ffmpeg: FFmpegService,
+    inputs: Sequence[InputMedia],
+    params: dict[str, Any],
+    output_dir: Path,
+) -> OperationResult:
+    """Mix background music under the video's narration using side-chain compression."""
+    require_inputs(inputs, 2)
+    video, music = inputs[0], inputs[1]
+    duration = _video_duration(inputs)
+    if not _has_audio(video):
+        raise InputError("Background-music ducking requires narration audio in the source video")
+    music_volume = bounded_number(params, "music_volume", 0.22, 0, 2)
+    voice_volume = bounded_number(params, "voice_volume", 1, 0, 4)
+    threshold = bounded_number(params, "threshold", 0.03, 0.001, 1)
+    ratio = bounded_number(params, "ratio", 8, 1, 20)
+    attack = bounded_number(params, "attack", 20, 1, 2000)
+    release = bounded_number(params, "release", 300, 10, 5000)
+    bitrate = _audio_bitrate(params)
+    duration_value = f"{duration:.6f}"
+    filters = (
+        f"[0:a]apad=whole_dur={duration_value},atrim=duration={duration_value},"
+        f"volume={voice_volume:.6g}[voice];"
+        f"[1:a]apad=whole_dur={duration_value},atrim=duration={duration_value},"
+        f"volume={music_volume:.6g}[music];"
+        f"[music][voice]sidechaincompress=threshold={threshold:.6g}:"
+        f"ratio={ratio:.6g}:attack={attack:.6g}:release={release:.6g}[ducked];"
+        f"[voice][ducked]amix=inputs=2:duration=first:normalize=0[mixed]"
+    )
+    output = output_path(output_dir, "ducked-audio", "mp4")
+    args: list[str | Path] = []
+    for media in inputs:
+        args.extend(["-i", media.temp_path])
+    args.extend([
+        "-filter_complex", filters, "-map", "0:v:0", "-map", "[mixed]",
+        "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate,
+        "-movflags", "+faststart", output,
+    ])
+    return await execute(
+        ffmpeg, args, output, "video.duck_background_music",
+        {
+            "preserve_video": True,
+            "mix_mode": "sidechain_ducking",
+            "music_volume": music_volume,
+            "voice_volume": voice_volume,
+            "threshold": threshold,
+            "ratio": ratio,
+            "attack_ms": attack,
+            "release_ms": release,
+            "duration_seconds": duration,
+        },
+    )

app/services/cleanup.py

@@ -58,9 +58,7 @@ class CleanupService:
 
     async def publish(self, request_id: str, source: Path, filename: str) -> Path:
         self._validate_request_id(request_id)
-        safe_name = Path(filename).name
-        if not safe_name or safe_name in {".", ".."}:
-            raise ProcessingError("The generated output filename is invalid")
+        safe_name = self._validate_filename(filename)
         destination_dir = self.settings.output_dir / request_id
         destination_dir.mkdir(parents=True, exist_ok=True)
         destination = destination_dir / safe_name
@@ -71,18 +69,9 @@ class CleanupService:
         return destination
 
     async def publish_new(self, request_id: str, source: Path, filename: str) -> Path | None:
-        """Publish a generated output without replacing an existing file.
-
-        This is used by durable generation-job reconciliation, where a retry
-        must never overwrite a canonical output created by an earlier worker
-        attempt.  Existing media operations continue to use ``publish`` and
-        retain their established replacement semantics.
-        """
-
+        """Publish a generated output without replacing an existing file."""
         self._validate_request_id(request_id)
-        safe_name = Path(filename).name
-        if not safe_name or safe_name in {".", ".."}:
-            raise ProcessingError("The generated output filename is invalid")
+        safe_name = self._validate_filename(filename)
         destination_dir = self.settings.output_dir / request_id
         destination_dir.mkdir(parents=True, exist_ok=True)
         destination = destination_dir / safe_name
@@ -92,22 +81,17 @@ class CleanupService:
     @staticmethod
     def _publish_new_sync(source: Path, destination: Path) -> bool:
         """Atomically claim a destination, with a cross-device fallback."""
-
         try:
             os.link(source, destination)
         except FileExistsError:
             return False
         except OSError:
-            # ``temp_dir`` and ``output_dir`` can be different mounts.  An
-            # exclusive create still prevents overwrite in that arrangement.
             try:
                 with source.open("rb") as input_stream, destination.open("xb") as output_stream:
                     shutil.copyfileobj(input_stream, output_stream, length=1024 * 1024)
             except FileExistsError:
                 return False
             except OSError:
-                # Never leave a partial file reachable from the output
-                # directory when cross-device publication fails.
                 try:
                     destination.unlink(missing_ok=True)
                 except OSError:
@@ -121,11 +105,20 @@ class CleanupService:
 
     def resolve_download(self, request_id: str, filename: str) -> Path:
         self._validate_request_id(request_id)
-        if filename != Path(filename).name:
+        safe_name = self._validate_filename(filename)
+        base = self.settings.output_dir.resolve()
+        request_root = base / request_id
+        # Do not follow a request-directory symlink out of the configured
+        # output root, even if the resulting file happens to exist.
+        if request_root.is_symlink() or not request_root.is_dir():
             raise NotFoundError("Output file not found")
-        root = (self.settings.output_dir / request_id).resolve()
-        candidate = (root / filename).resolve()
-        if candidate.parent != root or not candidate.is_file():
+        candidate_unresolved = request_root / safe_name
+        # A published artifact must be a regular file created in this exact
+        # request directory, not a symlink to another artifact or host file.
+        if candidate_unresolved.is_symlink():
+            raise NotFoundError("Output file not found")
+        candidate = candidate_unresolved.resolve()
+        if candidate.parent != request_root or candidate.name != safe_name or not candidate.is_file():
             raise NotFoundError("Output file not found")
         return candidate
 
@@ -133,8 +126,8 @@ class CleanupService:
         cutoff = time.time() - self.settings.cleanup_minutes * 60
         async with self._lock:
             active = self._active.copy()
-        removed = 0
         protected = protected_request_ids or set()
+        removed = 0
         for base in (self.settings.temp_dir, self.settings.output_dir):
             if not base.exists():
                 continue
@@ -179,3 +172,18 @@ class CleanupService:
             UUID(request_id)
         except (ValueError, AttributeError) as exc:
             raise NotFoundError("Output file not found") from exc
+
+    @staticmethod
+    def _validate_filename(filename: str) -> str:
+        # Keep URL path parameters and Content-Disposition headers unambiguous.
+        if (
+            not filename
+            or filename in {".", ".."}
+            or Path(filename).name != filename
+            or "/" in filename
+            or "\\" in filename
+            or any(ord(char) < 32 or ord(char) == 127 for char in filename)
+            or '"' in filename
+        ):
+            raise NotFoundError("Output file not found")
+        return filename

app/services/downloader.py

@@ -16,27 +16,66 @@ from app.core.exceptions import DownloadError, InputError
 from app.services.validator import MediaValidator
 
 
+class _PinnedNetworkBackend:
+    """httpcore network backend that dials only DNS-validated IPs.
+
+    TLS negotiation still receives the original URL hostname from httpcore,
+    preserving SNI and certificate hostname verification.
+    """
+
+    def __init__(self, downloader: "Downloader", fallback: object) -> None:
+        self.downloader = downloader
+        self.fallback = fallback
+
+    async def connect_tcp(self, host: str, port: int, timeout: float | None = None, local_address: str | None = None, socket_options=None):
+        pinned = self.downloader._pinned.get((host.lower().rstrip("."), port))
+        target = pinned[0] if pinned else host
+        return await self.fallback.connect_tcp(
+            host=target,
+            port=port,
+            timeout=timeout,
+            local_address=local_address,
+            socket_options=socket_options,
+        )
+
+    async def connect_unix_socket(self, path: str, timeout: float | None = None, socket_options=None):
+        return await self.fallback.connect_unix_socket(path, timeout=timeout, socket_options=socket_options)
+
+    async def sleep(self, seconds: float) -> None:
+        await self.fallback.sleep(seconds)
+
+
 class Downloader:
-    """Size-limited streaming HTTP(S) downloader with SSRF protection."""
+    """Size-limited streaming HTTP(S) downloader with connection-pinned SSRF protection."""
 
     def __init__(self, settings: Settings, validator: MediaValidator) -> None:
         self.settings = settings
         self.validator = validator
+        self._pinned: dict[tuple[str, int], tuple[str, ...]] = {}
 
-    async def download(
-        self, url: str, destination_dir: Path, filename: str | None = None
-    ) -> tuple[Path, str]:
+    async def download(self, url: str, destination_dir: Path, filename: str | None = None) -> tuple[Path, str]:
         current_url = url
         timeout = httpx.Timeout(self.settings.download_timeout_seconds, connect=30.0)
         headers = {"User-Agent": "MediaAPI/1.0"}
-        async with httpx.AsyncClient(timeout=timeout, headers=headers) as client:
+        transport = httpx.AsyncHTTPTransport(retries=0)
+        # HTTPX 0.28 uses httpcore's network backend for socket creation. The
+        # wrapper pins the TCP destination while httpcore retains the URL host
+        # for TLS SNI, certificate checks, and the HTTP Host header.
+        try:
+            from httpcore._backends.auto import AutoBackend
+            transport._pool._network_backend = _PinnedNetworkBackend(self, AutoBackend())
+        except (AttributeError, ImportError) as exc:
+            raise DownloadError("Secure connection-pinned downloads are unavailable in this runtime") from exc
+
+        async with httpx.AsyncClient(
+            timeout=timeout, headers=headers, follow_redirects=False,
+            trust_env=False, transport=transport,
+        ) as client:
             for _ in range(6):
                 await self.validate_url(current_url)
                 destination: Path | None = None
                 try:
-                    async with client.stream(
-                        "GET", current_url, follow_redirects=False
-                    ) as response:
+                    async with client.stream("GET", current_url, follow_redirects=False) as response:
                         if response.status_code in {301, 302, 303, 307, 308}:
                             location = response.headers.get("location")
                             if not location:
@@ -45,21 +84,15 @@ class Downloader:
                             continue
                         response.raise_for_status()
                         declared = self._content_length(response.headers.get("content-length"))
-                        if declared and declared > self.settings.max_upload_size:
+                        if declared is not None and declared > self.settings.max_upload_size:
                             raise InputError("Remote media exceeds MAX_UPLOAD_SIZE")
-                        name = self.validator.safe_filename(
-                            filename or self._response_filename(response, current_url),
-                            "download.bin",
-                        )
-                        unique_name = f"{uuid4().hex}_{name}"
-                        destination = destination_dir / unique_name
+                        name = self.validator.safe_filename(filename or self._response_filename(response, current_url), "download.bin")
+                        destination = destination_dir / f"{uuid4().hex}_{name}"
                         size = 0
                         async with aiofiles.open(destination, "wb") as output:
                             async for chunk in response.aiter_bytes(1024 * 1024):
                                 size += len(chunk)
                                 if size > self.settings.max_upload_size:
-                                    await output.close()
-                                    destination.unlink(missing_ok=True)
                                     raise InputError("Remote media exceeds MAX_UPLOAD_SIZE")
                                 await output.write(chunk)
                         mime_type = response.headers.get("content-type", "").split(";", 1)[0]
@@ -69,10 +102,7 @@ class Downloader:
                 except httpx.HTTPStatusError as exc:
                     if destination is not None:
                         destination.unlink(missing_ok=True)
-                    raise DownloadError(
-                        "Remote server rejected the download",
-                        details={"status_code": exc.response.status_code},
-                    ) from exc
+                    raise DownloadError("Remote server rejected the download", details={"status_code": exc.response.status_code}) from exc
                 except httpx.HTTPError as exc:
                     if destination is not None:
                         destination.unlink(missing_ok=True)
@@ -88,28 +118,46 @@ class Downloader:
             raise DownloadError("Too many redirects while downloading media")
 
     async def validate_url(self, value: str) -> None:
-        parsed = urlparse(value)
-        if parsed.scheme not in {"http", "https"} or not parsed.hostname:
-            raise InputError("Only HTTP and HTTPS media URLs are supported")
-        if parsed.username or parsed.password:
-            raise InputError("URLs containing credentials are not allowed")
+        try:
+            parsed = urlparse(value)
+            if (
+                parsed.scheme.lower() not in {"http", "https"} or not parsed.hostname
+                or parsed.username is not None or parsed.password is not None
+                or any(char.isspace() for char in parsed.hostname)
+            ):
+                raise InputError("Only credential-free HTTP and HTTPS media URLs are supported")
+            port = parsed.port
+        except ValueError as exc:
+            raise InputError("Media URL contains an invalid host or port") from exc
+
+        hostname = parsed.hostname.encode("idna").decode("ascii").lower().rstrip(".")
+        target_port = port or (443 if parsed.scheme.lower() == "https" else 80)
         if self.settings.allow_private_urls:
-            return
+            # Explicit opt-in permits private hosts; still pin the current DNS
+            # result to prevent a second, inconsistent lookup by the HTTP client.
+            pass
         try:
-            records = await asyncio.to_thread(
-                socket.getaddrinfo, parsed.hostname, parsed.port or 443, type=socket.SOCK_STREAM
-            )
-        except socket.gaierror as exc:
+            records = await asyncio.to_thread(socket.getaddrinfo, hostname, target_port, type=socket.SOCK_STREAM)
+        except (socket.gaierror, OSError) as exc:
             raise DownloadError("The remote hostname could not be resolved") from exc
+        if not records:
+            raise DownloadError("The remote hostname has no usable address")
+        addresses: list[str] = []
         for record in records:
-            address = ipaddress.ip_address(record[4][0])
-            if not address.is_global:
+            try:
+                address = ipaddress.ip_address(record[4][0].split("%", 1)[0])
+            except (ValueError, IndexError, TypeError) as exc:
+                raise DownloadError("The remote hostname resolved to an invalid address") from exc
+            if not self.settings.allow_private_urls and not address.is_global:
                 raise InputError("Private, loopback, and link-local URLs are not allowed")
+            if str(address) not in addresses:
+                addresses.append(str(address))
+        self._pinned[(hostname, target_port)] = tuple(addresses)
 
     @staticmethod
     def _response_filename(response: httpx.Response, url: str) -> str:
         disposition = response.headers.get("content-disposition", "")
-        match = re.search(r"filename\*?=(?:UTF-8''|\")?([^\";]+)", disposition, re.I)
+        match = re.search(r"filename\\*?=(?:UTF-8''|\\")?([^\\\";]+)", disposition, re.I)
         if match:
             return unquote(match.group(1).strip())
         path_name = Path(unquote(urlparse(url).path)).name
@@ -117,7 +165,10 @@ class Downloader:
 
     @staticmethod
     def _content_length(value: str | None) -> int | None:
+        if value is None:
+            return None
         try:
-            return int(value) if value else None
-        except ValueError:
+            parsed = int(value)
+        except (TypeError, ValueError):
             return None
+        return parsed if parsed >= 0 else None

app/services/media_service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import math
 import os
 import time
 from collections.abc import Awaitable, Callable, Sequence
@@ -8,6 +9,7 @@ from pathlib import Path
 from typing import Any
 
 from app.core.config import Settings
+from app.core.exceptions import ProcessingError
 from app.core.logger import get_logger
 from app.core.response import SuccessResponse
 from app.models.media import InputMedia, OperationResult, ResolvedRequest
@@ -244,6 +246,8 @@ class MediaProcessor:
         output_size = 0
         canonical_asset_id = None
         if result.path is not None:
+            output_report = await self.validate_output_result(result)
+            result.metadata = {**result.metadata, "output_validation": output_report}
             published = await self.cleanup.publish(
                 resolved.request_id, result.path, result.filename or result.path.name
             )
@@ -291,6 +295,75 @@ class MediaProcessor:
             metadata=metadata,
         )
 
+    async def validate_output_result(self, result: OperationResult) -> dict[str, Any]:
+        """Validate every published media artifact, regardless of which API produced it."""
+        path = result.path
+        if path is None:
+            return {"valid": True, "file_artifact": False}
+        if not path.is_file():
+            raise ProcessingError("Output artifact is missing")
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            raise ProcessingError("Unable to inspect output artifact") from exc
+        if size <= 0:
+            raise ProcessingError("Output artifact is empty")
+
+        mime_type = result.mime_type or self.validator.infer_mime(path)
+        report: dict[str, Any] = {
+            "valid": True,
+            "file_artifact": True,
+            "size_bytes": size,
+            "mime_type": mime_type,
+            "probed": False,
+            "container": None,
+            "duration_seconds": None,
+            "video_stream_count": None,
+            "audio_stream_count": None,
+            "resolution": None,
+        }
+        if not mime_type.startswith(("audio/", "video/", "image/")):
+            return report
+
+        try:
+            probe = await self.ffprobe.probe(path)
+        except Exception as exc:
+            if isinstance(exc, ProcessingError):
+                raise
+            raise ProcessingError("Output media failed integrity validation") from exc
+
+        video_streams = probe.get("video_streams") or []
+        audio_streams = probe.get("audio_streams") or []
+        if mime_type.startswith("video/") and not video_streams:
+            raise ProcessingError("Output is declared as video but contains no video stream")
+        if mime_type.startswith("audio/") and not audio_streams:
+            raise ProcessingError("Output is declared as audio but contains no audio stream")
+        if mime_type.startswith("image/") and not (video_streams or audio_streams):
+            raise ProcessingError("Output is declared as an image but contains no decodable stream")
+        try:
+            self.validator.validate_probe(probe)
+        except Exception as exc:
+            raise ProcessingError("Output media failed integrity validation") from exc
+
+        duration = probe.get("duration")
+        if mime_type.startswith(("audio/", "video/")):
+            try:
+                valid_duration = duration is not None and math.isfinite(float(duration)) and float(duration) > 0
+            except (TypeError, ValueError):
+                valid_duration = False
+            if not valid_duration:
+                raise ProcessingError("Output media has an invalid duration")
+
+        report.update({
+            "probed": True,
+            "container": probe.get("container"),
+            "duration_seconds": duration,
+            "video_stream_count": len(video_streams),
+            "audio_stream_count": len(audio_streams),
+            "resolution": probe.get("resolution"),
+        })
+        return report
+
     @staticmethod
     def _optional_int(
         value: Any, name: str, minimum: int, maximum: int

app/services/media_url_signer.py

@@ -24,7 +24,11 @@ class MediaURLSigner:
         key = self._key()
         if key is None:
             return None
-        expires = int(time.time()) + (ttl or self.settings.media_signed_url_ttl_seconds)
+        requested_ttl = self.settings.media_signed_url_ttl_seconds if ttl is None else ttl
+        # A caller may request a shorter link, but cannot mint a link longer
+        # than the configured maximum lifetime.
+        lifetime = max(1, min(int(requested_ttl), self.settings.media_signed_url_ttl_seconds))
+        expires = int(time.time()) + lifetime
         message = f"{request_id}\n{filename}\n{expires}".encode("utf-8")
         digest = hmac.new(key, message, hashlib.sha256).digest()
         token = base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
@@ -33,8 +37,15 @@ class MediaURLSigner:
 
     def verify(self, request_id: str, filename: str, expires: int, signature: str) -> bool:
         key = self._key()
-        if key is None or expires < int(time.time()):
+        now = int(time.time())
+        if (
+            key is None
+            or expires <= now
+            or expires > now + self.settings.media_signed_url_ttl_seconds
+        ):
             return False
         message = f"{request_id}\n{filename}\n{expires}".encode("utf-8")
-        expected = base64.urlsafe_b64encode(hmac.new(key, message, hashlib.sha256).digest()).decode("ascii").rstrip("=")
+        expected = base64.urlsafe_b64encode(
+            hmac.new(key, message, hashlib.sha256).digest()
+        ).decode("ascii").rstrip("=")
         return hmac.compare_digest(expected, signature)

app/services/validator.py

@@ -9,44 +9,11 @@ from app.core.config import Settings
 from app.core.exceptions import InputError
 
 MEDIA_EXTENSIONS = {
-    ".3gp",
-    ".aac",
-    ".aiff",
-    ".apng",
-    ".avi",
-    ".bin",
-    ".bmp",
-    ".flac",
-    ".gif",
-    ".heic",
-    ".jpeg",
-    ".jpg",
-    ".m4a",
-    ".m4v",
-    ".mkv",
-    ".m3u",
-    ".m3u8",
-    ".mov",
-    ".mp3",
-    ".mp4",
-    ".mpeg",
-    ".mpg",
-    ".oga",
-    ".ogg",
-    ".opus",
-    ".png",
-    ".svg",
-    ".tif",
-    ".tiff",
-    ".ts",
-    ".vtt",
-    ".wav",
-    ".webm",
-    ".webp",
-    ".wmv",
-    ".srt",
-    ".ass",
-    ".ssa",
+    ".3gp", ".aac", ".aiff", ".apng", ".avi", ".bin", ".bmp", ".flac",
+    ".gif", ".heic", ".jpeg", ".jpg", ".m4a", ".m4v", ".mkv", ".m3u",
+    ".m3u8", ".mov", ".mp3", ".mp4", ".mpeg", ".mpg", ".oga", ".ogg",
+    ".opus", ".png", ".svg", ".tif", ".tiff", ".ts", ".vtt", ".wav",
+    ".webm", ".webp", ".wmv", ".srt", ".ass", ".ssa",
 }
 
 
@@ -55,8 +22,16 @@ class MediaValidator:
         self.settings = settings
 
     def safe_filename(self, filename: str | None, fallback: str = "input.bin") -> str:
-        name = Path(filename or fallback).name.replace("\x00", "")
-        if not name or name in {".", ".."}:
+        # Treat both POSIX and Windows separators as path delimiters regardless
+        # of the server OS; never allow a client path to become a stored name.
+        raw = str(filename or fallback).replace("\\", "/")
+        name = raw.rsplit("/", 1)[-1].replace("\x00", "")
+        if (
+            not name
+            or name in {".", ".."}
+            or any(ord(char) < 32 or ord(char) == 127 for char in name)
+            or '"' in name
+        ):
             raise InputError("Invalid filename")
         return name[:240]
 
@@ -72,22 +47,15 @@ class MediaValidator:
         if suffix and suffix not in MEDIA_EXTENSIONS:
             raise InputError("Unsupported media file extension", details={"extension": suffix})
         normalized_mime = mime_type.split(";", 1)[0].lower()
-        allowed = normalized_mime.startswith(
-            ("audio/", "video/", "image/", "text/")
-        ) or normalized_mime in {
-            "application/octet-stream",
-            "application/x-subrip",
-            "application/vnd.apple.mpegurl",
-            "application/x-mpegurl",
+        allowed = normalized_mime.startswith(("audio/", "video/", "image/", "text/")) or normalized_mime in {
+            "application/octet-stream", "application/x-subrip",
+            "application/vnd.apple.mpegurl", "application/x-mpegurl",
         }
         if normalized_mime and not allowed:
             raise InputError("Unsupported media MIME type", details={"mime_type": mime_type})
 
     def validate_probe(self, metadata: dict[str, Any]) -> None:
-        streams = [
-            *(metadata.get("video_streams") or []),
-            *(metadata.get("audio_streams") or []),
-        ]
+        streams = [*(metadata.get("video_streams") or []), *(metadata.get("audio_streams") or [])]
         if not streams:
             raise InputError("The input has no decodable video or audio stream")
         for stream in streams:

app/templates/categories/motivation/templates.yaml

@@ -1,4 +1,42 @@
 templates:
+  - id: motivational_word_captions
+    name: Motivational Video — Word-by-Word Captions
+    category: motivation
+    description: Burn compact, individually timed narration words onto a vertical motivational video using Whisper word timestamps.
+    author: Enterprise Media API
+    version: 1
+    tags: [motivation, captions, word-by-word, vertical, narration]
+    estimated_runtime: medium
+    supported_inputs: [video, url]
+    supported_outputs: [mp4]
+    parameters:
+      model: {type: string, default: tiny, enum: [tiny, base, small]}
+      crf: {type: integer, default: 23, minimum: 0, maximum: 51}
+      font_size: {type: integer, default: 32, minimum: 16, maximum: 40}
+      caption_margin: {type: integer, default: 260, minimum: 40, maximum: 400}
+    pipeline:
+      - operation: resize
+        width: 1080
+        height: 1920
+        fit: cover
+        save_as: vertical_video
+      - operation: transcribe
+        inputs: [original]
+        model: "{{ model }}"
+        output_format: srt
+        word_timestamps: true
+        caption_mode: word
+        save_as: captions
+      - operation: burn_subtitles
+        inputs: [artifact:vertical_video, artifact:captions]
+        style: "FontName=Arial,FontSize={{ font_size }},Bold=1,PrimaryColour=&H0000FFFF,Outline=2,Shadow=0,Alignment=2,MarginV={{ caption_margin }}"
+      - {operation: normalize_video}
+      - {operation: compress, crf: "{{ crf }}", preset: veryfast, format: mp4}
+    output: {format: mp4}
+    examples:
+      - input: {url: "https://example.com/motivation.mp4"}
+        parameters: {model: tiny, crf: 23, font_size: 32, caption_margin: 260}
+
   - id: motivational_video
     name: Motivational Video
     category: motivation

app/templates/categories/podcast/templates.yaml

@@ -97,3 +97,31 @@ templates:
           - {url: "https://example.com/waveform.png"}
           - {url: "https://example.com/podcast.mp3"}
         parameters: {duration: 60}
+
+  - id: voiceover_music_ducking
+    name: Voiceover + Background Music Ducking
+    category: podcast
+    description: Mix background music beneath narration with automatic side-chain ducking and preserve the source video stream.
+    author: Enterprise Media API
+    version: 1
+    tags: [audio, ducking, voiceover, background-music, podcast, motivation]
+    estimated_runtime: medium
+    supported_inputs: [video, audio]
+    supported_outputs: [mp4]
+    parameters:
+      music_volume: {type: number, default: 0.22, minimum: 0, maximum: 2}
+      voice_volume: {type: number, default: 1, minimum: 0, maximum: 4}
+      threshold: {type: number, default: 0.03, minimum: 0.001, maximum: 1}
+      ratio: {type: number, default: 8, minimum: 1, maximum: 20}
+      attack: {type: number, default: 20, minimum: 1, maximum: 2000}
+      release: {type: number, default: 300, minimum: 10, maximum: 5000}
+      audio_bitrate: {type: string, default: "192k"}
+    pipeline:
+      - operation: duck_audio
+        inputs: [original, original:1]
+    output: {format: mp4}
+    examples:
+      - inputs:
+          - {url: "https://example.com/narrated-video.mp4"}
+          - {url: "https://example.com/background-music.mp3"}
+        parameters: {music_volume: 0.22, ratio: 8, attack: 20, release: 300}

app/templates/executor.py

@@ -37,6 +37,7 @@ from app.operations.extract_audio import (
     set_volume,
 )
 from app.operations.merge import merge_audio, merge_video
+from app.operations.mix_audio import duck_background_music
 from app.operations.resize import pad_video, resize_image, resize_video, scale_video
 from app.operations.rotate import (
     change_bitrate,
@@ -137,6 +138,7 @@ OPERATION_BINDINGS: Mapping[str, OperationBinding] = MappingProxyType(
         "normalize_audio": _ffmpeg(normalize_audio),
         "trim_audio": _ffmpeg(trim_audio),
         "merge_audio": _ffmpeg(merge_audio, input_mode="all"),
+        "duck_audio": _ffmpeg(duck_background_music, input_mode="all"),
         "concat_audio": _ffmpeg(concat_audio, input_mode="all"),
         "fade_audio": _ffmpeg(fade_audio),
         "volume": _ffmpeg(set_volume),
@@ -270,11 +272,12 @@ class TemplateExecutor:
             if not operations:
                 raise TemplateExecutionError("All template pipeline operations were disabled")
             self._validate_output(prepared, current)
+            output_validation = self._output_validation(current)
             result = OperationResult(
                 path=current.temp_path,
                 filename=prepared.output.filename or current.filename,
                 mime_type=current.mime_type,
-                metadata=current.metadata,
+                metadata={**current.metadata, "output_validation": output_validation},
             )
             response = await self.processor.finish_result(
                 resolved,
@@ -409,6 +412,14 @@ class TemplateExecutor:
 
     @staticmethod
     def _validate_output(prepared: PreparedTemplate, media: InputMedia) -> None:
+        if not media.temp_path.is_file():
+            raise TemplateExecutionError("Template output artifact is missing")
+        try:
+            size = media.temp_path.stat().st_size
+        except OSError as exc:
+            raise TemplateExecutionError("Unable to inspect template output artifact") from exc
+        if size <= 0:
+            raise TemplateExecutionError("Template output artifact is empty")
         if prepared.output.filename:
             filename = prepared.output.filename
             if Path(filename).name != filename or len(filename) > 255:
@@ -424,6 +435,40 @@ class TemplateExecutor:
                 details={"expected": expected, "actual": actual},
             )
 
+    @staticmethod
+    def _output_validation(media: InputMedia) -> dict[str, object]:
+        """Summarize checks performed on the final artifact for automation clients."""
+        metadata = media.metadata
+        size = media.temp_path.stat().st_size
+        video_streams = metadata.get("video_streams")
+        audio_streams = metadata.get("audio_streams")
+        if media.mime_type.startswith("video/") and video_streams is not None and not video_streams:
+            raise TemplateExecutionError(
+                "Template output is declared as video but contains no video stream"
+            )
+        if media.mime_type.startswith("audio/") and audio_streams is not None and not audio_streams:
+            raise TemplateExecutionError(
+                "Template output is declared as audio but contains no audio stream"
+            )
+        duration = metadata.get("duration")
+        if media.mime_type.startswith(("video/", "audio/")) and duration is not None:
+            try:
+                valid_duration = float(duration) > 0
+            except (TypeError, ValueError):
+                valid_duration = False
+            if not valid_duration:
+                raise TemplateExecutionError("Template output has an invalid media duration")
+        return {
+            "valid": True,
+            "size_bytes": size,
+            "mime_type": media.mime_type,
+            "container": metadata.get("container"),
+            "duration_seconds": duration,
+            "video_stream_count": len(video_streams) if isinstance(video_streams, list) else None,
+            "audio_stream_count": len(audio_streams) if isinstance(audio_streams, list) else None,
+            "resolution": metadata.get("resolution"),
+        }
+
     @staticmethod
     def _log_data(
         prepared: PreparedTemplate | None,

docs/api-wide-output-validation.md

@@ -0,0 +1,28 @@
+# API-wide media output validation
+
+Every file-producing operation that reaches `MediaProcessor.finish_result` now validates its final artifact before publication. This covers the shared execution path used by the standalone video, audio, image, conversion, and template APIs.
+
+## Validation sequence
+
+1. Verify that the output path exists and is a regular file.
+2. Reject zero-byte artifacts.
+3. For audio, video, and image MIME types, run FFprobe on the actual output file.
+4. Require a video stream for video outputs, an audio stream for audio outputs, and at least one decodable stream for image outputs.
+5. Apply the shared media-probe constraints and require a finite, positive duration for audio/video outputs.
+6. Publish only after validation succeeds.
+
+A failed check raises a processing error; the file is not published as a successful response.
+
+## Response metadata
+
+Successful file responses include `metadata.output_validation`:
+
+- `valid`, `file_artifact`, `size_bytes`, and `mime_type`
+- `probed` indicates whether FFprobe ran
+- `container`, `duration_seconds`, `video_stream_count`, `audio_stream_count`, and `resolution` are populated when probing is applicable and successful
+
+Text-like outputs such as SRT/VTT and JSON artifacts are checked for file existence and non-zero size, but are not sent through FFprobe. Responses without a file artifact are not subject to file-output validation.
+
+## Operational note
+
+FFprobe validation adds work after each render. The output must be fully readable by FFprobe before the API publishes it. Automated tests and a live render should be run before merging this change request.

docs/artifact-download-hardening.md

@@ -0,0 +1,17 @@
+# Artifact download hardening
+
+MediaRouter download paths are treated as untrusted locators, not permissions.
+
+The download boundary now:
+- validates request IDs as UUIDs and filenames as single safe path components;
+- rejects slash, backslash, control characters, quotes, traversal names, and empty filenames;
+- rejects symlinked request directories and symlinked artifact files before resolving a published path;
+- preserves workspace ownership and content-digest verification for authenticated direct downloads;
+- verifies signed URLs with HMAC, rejects expired links, and caps requested link lifetime at `MEDIA_SIGNED_URL_TTL_SECONDS`;
+- sends `Cache-Control: private, no-store` and `X-Content-Type-Options: nosniff` on direct and signed download responses.
+
+Signed URLs remain bearer capabilities: anyone who receives a valid URL can use it until it expires. Do not put signed URLs in public logs, analytics, or long-lived messages.
+
+## Verification status
+
+Regression tests were added for traversal and symlink rejection, expired signatures, and TTL limits. They have not been executed in the remote environment; previous hosted test execution was blocked by a payment-required response. Treat this as source-level hardening pending CI and deployed integration tests.

docs/input-ingestion-security.md

@@ -0,0 +1,16 @@
+# Input-ingestion security hardening
+
+The input pipeline now applies these protections at the resolver boundary:
+
+- URL fetching accepts only HTTP(S), rejects URL credentials and malformed ports, resolves using the scheme's correct default port, and rejects hostnames with any non-global DNS answer when private URLs are disabled.
+- Redirects are handled manually, with each destination revalidated before the next request.
+- HTTPX environment proxy settings are not inherited for remote media fetches, avoiding an ambient proxy changing the destination semantics.
+- Remote downloads remain streamed to disk with a hard byte limit, including responses that omit or misstate Content-Length. Partial files are removed on download/validation failures.
+- Client filenames are normalized across POSIX and Windows separators and reject control characters and quote characters that can corrupt response headers.
+
+## Deployment notes and remaining limits
+
+- `ALLOW_PRIVATE_URLS=true` intentionally disables the private-address block; only enable it in a trusted, isolated environment.
+- DNS validation and the HTTP client's subsequent connection resolution are separate operations. For hostile URL-fetching environments, production-grade SSRF protection should additionally pin the connection to a validated IP while preserving TLS hostname verification, or enforce egress restrictions at the network layer.
+- Multipart parsing can spool uploads before application-level per-file limits are applied. Enforce request-body limits at the reverse proxy/ASGI boundary as well as in the resolver.
+- Source-level regression tests were added but have not been run in the hosted environment. Deployment and live SSRF tests remain unverified.

docs/template-output-validation.md

@@ -0,0 +1,38 @@
+# Template final-output validation
+
+Template runs validate the final artifact before publishing it to the media download layer.
+
+## Checks
+
+- The final artifact exists and has a non-zero file size.
+- The artifact's extension matches the template's declared output format (except `source`, which preserves the input format).
+- Probeable media is passed through the existing FFprobe validation path. The probe rejects outputs without decodable audio/video streams.
+- When stream metadata is available, the final check confirms that audio and video MIME types have their corresponding stream and that reported audio/video duration is positive.
+
+A failed check raises a template execution error, so the output is not published as a successful result.
+
+## Response metadata
+
+Successful template responses include an `output_validation` object in `metadata`, for example:
+
+```json
+{
+  "output_validation": {
+    "valid": true,
+    "size_bytes": 4821093,
+    "mime_type": "video/mp4",
+    "container": "mov,mp4,m4a,3gp,3g2,mj2",
+    "duration_seconds": 31.25,
+    "video_stream_count": 1,
+    "audio_stream_count": 1,
+    "resolution": {
+      "width": 1080,
+      "height": 1920
+    }
+  }
+}
+```
+
+Stream counts, container, duration, and resolution can be `null` when the output type is not probeable or a metadata field is unavailable. The file size and MIME type are always reported for a valid file artifact.
+
+This validation is applied to template pipeline outputs; it does not imply that every standalone media endpoint has the same response metadata.

docs/voiceover-music-ducking.md

@@ -0,0 +1,53 @@
+# Voiceover + background music ducking
+
+The `voiceover_music_ducking` template mixes a video containing narration with a separate background-music file. FFmpeg side-chain compression lowers the music while narration is active, then mixes the narration and ducked music into the output. The source video stream is copied without re-encoding.
+
+## Endpoint
+
+`POST https://basyx-mediarouter.hf.space/v1/templates/run`
+
+## Request example
+
+```json
+{
+  "template": "voiceover_music_ducking",
+  "inputs": [
+    {
+      "url": "https://example.com/narrated-video.mp4"
+    },
+    {
+      "url": "https://example.com/background-music.mp3"
+    }
+  ],
+  "parameters": {
+    "music_volume": 0.22,
+    "voice_volume": 1,
+    "threshold": 0.03,
+    "ratio": 8,
+    "attack": 20,
+    "release": 300,
+    "audio_bitrate": "192k"
+  }
+}
+```
+
+Use the standard MediaRouter input contract for multiple media inputs; if your client uses a nested `input` object, supply the equivalent two-item input collection supported by the shared resolver.
+
+## Parameters
+
+| Parameter | Default | Range | Purpose |
+|---|---:|---:|---|
+| `music_volume` | 0.22 | 0–2 | Linear gain applied to the music before ducking |
+| `voice_volume` | 1 | 0–4 | Linear gain applied to narration |
+| `threshold` | 0.03 | 0.001–1 | Side-chain threshold; lower values trigger ducking more readily |
+| `ratio` | 8 | 1–20 | Compression ratio for the music |
+| `attack` | 20 ms | 1–2000 ms | How quickly music is reduced after narration starts |
+| `release` | 300 ms | 10–5000 ms | How quickly music returns after narration pauses |
+| `audio_bitrate` | `192k` | Supported AAC bitrates | Output audio bitrate |
+
+The source video must contain an audio stream with the narration, and its duration must be available from probing. This template does not generate narration or music. Listen to the rendered output and adjust music gain and compression settings for the particular mix.
+
+## Template discovery
+
+- `GET /v1/templates/voiceover_music_ducking`
+- `GET /v1/templates?category=podcast`

docs/word-by-word-captions.md

@@ -0,0 +1,48 @@
+# Word-by-word motivational captions
+
+MediaRouter provides the `motivational_word_captions` template for producing a vertical MP4 with one timed caption cue per recognized word.
+
+## Endpoint
+
+`POST https://basyx-mediarouter.hf.space/v1/templates/run`
+
+Use the template ID `motivational_word_captions`. The template resizes the source to 1080×1920, transcribes the original media with Whisper word timestamps, burns the resulting SRT captions onto the resized video, normalizes the output, and encodes an MP4.
+
+## Request example
+
+Provide a publicly reachable video URL in the standard template input contract:
+
+```json
+{
+  "template": "motivational_word_captions",
+  "input": {
+    "url": "https://example.com/your-video.mp4"
+  },
+  "parameters": {
+    "model": "tiny",
+    "crf": 23,
+    "font_size": 32,
+    "caption_margin": 260
+  }
+}
+```
+
+You can also submit media through the other input transports supported by MediaRouter's shared input resolver.
+
+## Parameters
+
+| Parameter | Default | Allowed range / values | Purpose |
+|---|---:|---|---|
+| `model` | `tiny` | `tiny`, `base`, `small` | Whisper model size; larger models generally use more compute |
+| `crf` | `23` | 0–51 | H.264 quality/size trade-off; lower values preserve more quality and increase file size |
+| `font_size` | `32` | 16–40 | Caption font size for the 1080×1920 output |
+| `caption_margin` | `260` | 40–400 | Vertical margin from the bottom edge; increase it to move captions higher |
+
+Captions are individually timed from Whisper's word timestamps. Timing is model-estimated, not guaranteed to match every pronunciation perfectly; review the final render before publishing, especially for names, accents, music-heavy audio, or overlapping speech.
+
+## Inspect the template
+
+- `GET /v1/templates/motivational_word_captions`
+- `GET /v1/templates?category=motivation`
+
+This template processes an already assembled video. It does not generate scenes, narration, or background music.

tests/test_artifact_download_security.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from pathlib import Path
+from uuid import uuid4
+
+import pytest
+
+from app.core.exceptions import NotFoundError
+from app.services.cleanup import CleanupService
+
+
+def test_resolve_download_returns_only_file_in_request_directory(settings) -> None:
+    cleanup = CleanupService(settings)
+    request_id = str(uuid4())
+    request_dir = settings.output_dir / request_id
+    request_dir.mkdir(parents=True)
+    artifact = request_dir / "clip.mp4"
+    artifact.write_bytes(b"media")
+
+    assert cleanup.resolve_download(request_id, "clip.mp4") == artifact.resolve()
+
+
+@pytest.mark.parametrize("filename", ["../secret.txt", "sub/file.mp4", "sub\\file.mp4", 'bad"name.mp4', "bad\nname.mp4", ""])
+def test_resolve_download_rejects_unsafe_filenames(settings, filename: str) -> None:
+    cleanup = CleanupService(settings)
+    with pytest.raises(NotFoundError):
+        cleanup.resolve_download(str(uuid4()), filename)
+
+
+def test_resolve_download_rejects_symlinked_artifact(settings, tmp_path: Path) -> None:
+    cleanup = CleanupService(settings)
+    request_id = str(uuid4())
+    request_dir = settings.output_dir / request_id
+    request_dir.mkdir(parents=True)
+    outside = tmp_path / "outside.mp4"
+    outside.write_bytes(b"not published")
+    link = request_dir / "clip.mp4"
+    try:
+        link.symlink_to(outside)
+    except (OSError, NotImplementedError):
+        pytest.skip("Symlink creation is unavailable on this platform")
+
+    with pytest.raises(NotFoundError):
+        cleanup.resolve_download(request_id, "clip.mp4")
+
+
+def test_resolve_download_rejects_symlinked_request_directory(settings, tmp_path: Path) -> None:
+    cleanup = CleanupService(settings)
+    request_id = str(uuid4())
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    (outside / "clip.mp4").write_bytes(b"not published")
+    settings.output_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        (settings.output_dir / request_id).symlink_to(outside, target_is_directory=True)
+    except (OSError, NotImplementedError):
+        pytest.skip("Symlink creation is unavailable on this platform")
+
+    with pytest.raises(NotFoundError):
+        cleanup.resolve_download(request_id, "clip.mp4")

tests/test_downloader.py

@@ -1,8 +1,13 @@
+from __future__ import annotations
+
+import socket
 from unittest.mock import AsyncMock
 
+import pytest
 import respx
 from httpx import Response
 
+from app.core.exceptions import InputError
 from app.services.downloader import Downloader
 from app.services.validator import MediaValidator
 
@@ -18,3 +23,52 @@ async def test_url_download_streams_to_disk(settings, tmp_path) -> None:
     path, mime_type = await downloader.download(url, tmp_path)
     assert path.read_bytes() == b"ID3data"
     assert mime_type == "audio/mpeg"
+
+
+async def test_validate_url_rejects_non_global_dns_answer(settings, monkeypatch) -> None:
+    settings.allow_private_urls = False
+    downloader = Downloader(settings, MediaValidator(settings))
+
+    def private_answer(*args, **kwargs):
+        return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", ("127.0.0.1", 443))]
+
+    monkeypatch.setattr(socket, "getaddrinfo", private_answer)
+    with pytest.raises(InputError, match="Private, loopback"):
+        await downloader.validate_url("https://example.test/media.mp4")
+
+
+async def test_validate_url_rejects_mixed_public_and_private_dns(settings, monkeypatch) -> None:
+    settings.allow_private_urls = False
+    downloader = Downloader(settings, MediaValidator(settings))
+
+    def mixed_answers(*args, **kwargs):
+        return [
+            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("93.184.216.34", 443)),
+            (socket.AF_INET, socket.SOCK_STREAM, 6, "", ("10.0.0.4", 443)),
+        ]
+
+    monkeypatch.setattr(socket, "getaddrinfo", mixed_answers)
+    with pytest.raises(InputError, match="Private, loopback"):
+        await downloader.validate_url("https://example.test/media.mp4")
+
+
+@pytest.mark.parametrize("url", [
+    "file:///etc/passwd",
+    "https://user:password@example.test/media.mp4",
+    "https://example.test:invalid/media.mp4",
+    "https://example.test:99999/media.mp4",
+])
+async def test_validate_url_rejects_invalid_or_credentialed_urls(settings, url: str) -> None:
+    settings.allow_private_urls = False
+    downloader = Downloader(settings, MediaValidator(settings))
+    with pytest.raises(InputError):
+        await downloader.validate_url(url)
+
+
+def test_safe_filename_normalizes_windows_paths_and_rejects_header_injection(settings) -> None:
+    validator = MediaValidator(settings)
+    assert validator.safe_filename(r"C:\\temp\\clip.mp4") == "clip.mp4"
+    with pytest.raises(InputError):
+        validator.safe_filename("clip.mp4\r\nX-Evil: yes")
+    with pytest.raises(InputError):
+        validator.safe_filename('clip".mp4')

tests/test_media_url_signer.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import time
+from urllib.parse import parse_qs, urlparse
+
 from app.services.media_url_signer import MediaURLSigner
 
 
@@ -9,18 +12,36 @@ def test_signed_media_url_round_trip(settings) -> None:
     signer = MediaURLSigner(settings)
     url = signer.sign("123e4567-e89b-12d3-a456-426614174000", "clip.mp4", ttl=3600)
     assert url is not None
-    from urllib.parse import parse_qs, urlparse
     parsed = urlparse(url)
     params = parse_qs(parsed.query)
-    assert signer.verify(
-        "123e4567-e89b-12d3-a456-426614174000",
-        "clip.mp4",
-        int(params["expires"][0]),
-        params["signature"][0],
-    )
-    assert not signer.verify(
-        "123e4567-e89b-12d3-a456-426614174000",
-        "other.mp4",
-        int(params["expires"][0]),
-        params["signature"][0],
-    )
+    expires = int(params["expires"][0])
+    signature = params["signature"][0]
+    assert signer.verify("123e4567-e89b-12d3-a456-426614174000", "clip.mp4", expires, signature)
+    assert not signer.verify("123e4567-e89b-12d3-a456-426614174000", "other.mp4", expires, signature)
+
+
+def test_signed_media_url_rejects_expired_and_overlong_expiry(settings) -> None:
+    settings.media_signing_secret = "a" * 32
+    signer = MediaURLSigner(settings)
+    assert not signer.verify("request", "clip.mp4", int(time.time()) - 1, "x" * 43)
+
+    expiry = int(time.time()) + settings.media_signed_url_ttl_seconds + 120
+    import base64
+    import hashlib
+    import hmac
+
+    message = f"request\nclip.mp4\n{expiry}".encode()
+    signature = base64.urlsafe_b64encode(
+        hmac.new(b"a" * 32, message, hashlib.sha256).digest()
+    ).decode().rstrip("=")
+    assert not signer.verify("request", "clip.mp4", expiry, signature)
+
+
+def test_signer_caps_requested_ttl_to_configured_maximum(settings) -> None:
+    settings.media_signing_secret = "a" * 32
+    settings.base_url = "https://media.example"
+    signer = MediaURLSigner(settings)
+    url = signer.sign("request", "clip.mp4", ttl=settings.media_signed_url_ttl_seconds * 10)
+    assert url is not None
+    expiry = int(parse_qs(urlparse(url).query)["expires"][0])
+    assert expiry <= int(time.time()) + settings.media_signed_url_ttl_seconds

tests/test_mix_audio.py

@@ -95,3 +95,36 @@ async def test_add_audio_rejects_invalid_bitrate(tmp_path: Path) -> None:
     sfx = _media(tmp_path / "one.wav", "one.wav", "audio/wav")
     with pytest.raises(InputError, match="supported AAC bitrate"):
         await add_audio(FakeFFmpeg(), [video, sfx], {"audio_bitrate": "999k"}, tmp_path / "out")
+
+
+@pytest.mark.asyncio
+async def test_duck_background_music_uses_voice_sidechain_and_preserves_video(tmp_path: Path) -> None:
+    from app.operations.mix_audio import duck_background_music
+
+    video = _media(
+        tmp_path / "voice.mp4", "voice.mp4", "video/mp4", duration=18.0,
+        metadata={"audio_streams": [{"codec": "aac"}]},
+    )
+    music = _media(tmp_path / "music.mp3", "music.mp3", "audio/mpeg")
+    ffmpeg = FakeFFmpeg()
+    result = await duck_background_music(
+        ffmpeg, [video, music], {"music_volume": 0.2, "ratio": 8, "attack": 20, "release": 300},
+        tmp_path / "out",
+    )
+    command = [str(value) for value in ffmpeg.args]
+    filt = command[command.index("-filter_complex") + 1]
+    assert "[music][voice]sidechaincompress=threshold=0.03:ratio=8:attack=20:release=300[ducked]" in filt
+    assert "[voice][ducked]amix=inputs=2:duration=first:normalize=0[mixed]" in filt
+    assert command[command.index("-c:v") + 1] == "copy"
+    assert result.metadata["mix_mode"] == "sidechain_ducking"
+
+
+@pytest.mark.asyncio
+async def test_duck_background_music_rejects_silent_video(tmp_path: Path) -> None:
+    from app.operations.mix_audio import duck_background_music
+
+    video = _media(tmp_path / "silent.mp4", "silent.mp4", "video/mp4", duration=8.0,
+                   metadata={"audio_streams": []})
+    music = _media(tmp_path / "music.mp3", "music.mp3", "audio/mpeg")
+    with pytest.raises(InputError, match="requires narration audio"):
+        await duck_background_music(FakeFFmpeg(), [video, music], {}, tmp_path / "out")

tests/test_output_validation.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from app.container import build_container
+from app.core.exceptions import ProcessingError
+from app.models.media import OperationResult
+
+
+@pytest.mark.asyncio
+async def test_output_validation_probes_audio_artifact(settings, tmp_path: Path, monkeypatch) -> None:
+    container = build_container(settings)
+    output = tmp_path / "final.mp3"
+    output.write_bytes(b"audio-placeholder")
+
+    async def fake_probe(path: Path):
+        assert path == output
+        return {
+            "duration": 12.5,
+            "container": "mp3",
+            "video_streams": [],
+            "audio_streams": [{"codec": "mp3"}],
+            "resolution": None,
+        }
+
+    monkeypatch.setattr(container.processor.ffprobe, "probe", fake_probe)
+    report = await container.processor.validate_output_result(
+        OperationResult(path=output, filename=output.name, mime_type="audio/mpeg")
+    )
+
+    assert report["valid"] is True
+    assert report["probed"] is True
+    assert report["size_bytes"] == output.stat().st_size
+    assert report["audio_stream_count"] == 1
+    assert report["duration_seconds"] == 12.5
+
+
+@pytest.mark.asyncio
+async def test_output_validation_rejects_audio_without_audio_stream(settings, tmp_path: Path, monkeypatch) -> None:
+    container = build_container(settings)
+    output = tmp_path / "broken.mp3"
+    output.write_bytes(b"not-real-audio")
+
+    async def fake_probe(path: Path):
+        return {
+            "duration": 1.0,
+            "container": "mp3",
+            "video_streams": [],
+            "audio_streams": [],
+            "resolution": None,
+        }
+
+    monkeypatch.setattr(container.processor.ffprobe, "probe", fake_probe)
+    with pytest.raises(ProcessingError, match="no audio stream"):
+        await container.processor.validate_output_result(
+            OperationResult(path=output, filename=output.name, mime_type="audio/mpeg")
+        )
+
+
+@pytest.mark.asyncio
+async def test_output_validation_rejects_empty_artifact(settings, tmp_path: Path) -> None:
+    container = build_container(settings)
+    output = tmp_path / "empty.mp4"
+    output.write_bytes(b"")
+
+    with pytest.raises(ProcessingError, match="empty"):
+        await container.processor.validate_output_result(
+            OperationResult(path=output, filename=output.name, mime_type="video/mp4")
+        )

tests/test_templates.py

@@ -7,14 +7,25 @@ import pytest
 from fastapi.testclient import TestClient
 
 from app.container import build_container
-from app.core.exceptions import TemplateValidationError
+from app.core.exceptions import TemplateExecutionError, TemplateValidationError
 from app.models.media import InputMedia, MediaSource, ResolvedRequest
-from app.templates.executor import OPERATION_BINDINGS
+from app.templates.executor import OPERATION_BINDINGS, TemplateExecutor
 from app.templates.loader import TemplateLoader
 from app.templates.registry import TemplateRegistry
 from app.templates.validator import TemplateValidator
 from main import create_app
 
+
+async def fake_audio_output_probe(path: Path):
+    return {
+        "duration": 1.0,
+        "container": "mp3",
+        "video_streams": [],
+        "audio_streams": [{"codec": "mp3"}],
+        "resolution": None,
+    }
+
+
 EXPECTED_CATEGORIES = {
     "branding",
     "conversion",
@@ -32,7 +43,7 @@ EXPECTED_CATEGORIES = {
 def test_builtin_templates_are_loaded_dynamically(settings) -> None:
     registry = build_container(settings).template_registry
 
-    assert registry.count == 71
+    assert registry.count == 73
     assert set(registry.categories()) == EXPECTED_CATEGORIES
     assert registry.get("instagram_reel").version == 1
     assert registry.get("instagram_reel@latest").version == 1
@@ -52,6 +63,22 @@ def test_parameter_substitution_preserves_declared_types(settings) -> None:
     assert isinstance(compress_step.parameters["crf"], int)
 
 
+
+def test_motivational_word_caption_template_is_validated(settings) -> None:
+    registry = build_container(settings).template_registry
+
+    prepared = registry.prepare("motivational_word_captions", {})
+    operations = [step.operation for step in prepared.pipeline]
+
+    assert operations == ["resize", "transcribe", "burn_subtitles", "normalize_video", "compress"]
+    assert prepared.pipeline[1].parameters["word_timestamps"] is True
+    assert prepared.pipeline[1].parameters["caption_mode"] == "word"
+    assert prepared.pipeline[1].parameters["output_format"] == "srt"
+    assert prepared.pipeline[2].inputs == ["artifact:vertical_video", "artifact:captions"]
+    assert prepared.pipeline[2].parameters["style"].find("PrimaryColour=") >= 0
+    assert prepared.output.format == "mp4"
+
+
 def test_template_registry_keeps_old_versions(tmp_path: Path) -> None:
     root = tmp_path / "templates"
     root.mkdir()
@@ -192,6 +219,7 @@ async def test_template_executor_calls_existing_operation(settings, tmp_path, mo
         output.write_bytes(b"ID3-template-output")
 
     monkeypatch.setattr(container.processor, "probe_inputs", fake_probe)
+    monkeypatch.setattr(container.processor.ffprobe, "probe", fake_audio_output_probe)
     monkeypatch.setattr(container.ffmpeg, "run", fake_ffmpeg)
     resolved = ResolvedRequest(
         request_id="5fdbe750-4cb7-4f87-aa5c-3df50c3a6629",
@@ -238,6 +266,7 @@ def test_template_rest_endpoints_and_nested_input(settings, monkeypatch) -> None
         output.write_bytes(b"ID3-rest-template")
 
     monkeypatch.setattr(container.processor, "probe_inputs", fake_probe)
+    monkeypatch.setattr(container.processor.ffprobe, "probe", fake_audio_output_probe)
     monkeypatch.setattr(container.ffmpeg, "run", fake_ffmpeg)
 
     with TestClient(application) as client:
@@ -258,8 +287,62 @@ def test_template_rest_endpoints_and_nested_input(settings, monkeypatch) -> None
         )
 
     assert listing.status_code == 200
-    assert listing.json()["metadata"]["count"] == 71
+    assert listing.json()["metadata"]["count"] == 73
     assert set(categories.json()["metadata"]["categories"]) == EXPECTED_CATEGORIES
     assert details.json()["metadata"]["template"]["version"] == 1
     assert execution.status_code == 200
     assert execution.json()["metadata"]["template"]["id"] == "mp3"
+
+
+
+def test_voiceover_music_ducking_template_uses_two_original_inputs(settings) -> None:
+    registry = build_container(settings).template_registry
+    prepared = registry.prepare("voiceover_music_ducking", {})
+    assert [step.operation for step in prepared.pipeline] == ["duck_audio"]
+    assert prepared.pipeline[0].inputs == ["original", "original:1"]
+    assert prepared.pipeline[0].parameters["music_volume"] == 0.22
+    assert prepared.output.format == "mp4"
+
+
+def test_final_output_validation_reports_media_metadata(settings, tmp_path: Path) -> None:
+    output = tmp_path / "final.mp3"
+    output.write_bytes(b"non-empty-output")
+    media = InputMedia(
+        source=MediaSource.LOCAL_PATH,
+        filename=output.name,
+        mime_type="audio/mpeg",
+        temp_path=output,
+        size=output.stat().st_size,
+        duration=12.5,
+        metadata={
+            "duration": 12.5,
+            "container": "mp3",
+            "audio_streams": [{"codec": "mp3"}],
+            "video_streams": [],
+            "resolution": None,
+        },
+    )
+
+    report = TemplateExecutor._output_validation(media)
+
+    assert report["valid"] is True
+    assert report["size_bytes"] == output.stat().st_size
+    assert report["duration_seconds"] == 12.5
+    assert report["audio_stream_count"] == 1
+    assert report["video_stream_count"] == 0
+
+
+def test_final_output_validation_rejects_empty_artifact(settings, tmp_path: Path) -> None:
+    output = tmp_path / "empty.mp3"
+    output.write_bytes(b"")
+    media = InputMedia(
+        source=MediaSource.LOCAL_PATH,
+        filename=output.name,
+        mime_type="audio/mpeg",
+        temp_path=output,
+        size=0,
+    )
+    prepared = build_container(settings).template_registry.prepare("mp3@1", {})
+
+    with pytest.raises(TemplateExecutionError, match="empty"):
+        TemplateExecutor._validate_output(prepared, media)