diff --git a/.env.example b/.env.example
index e15e2cb..b64f7e9 100644
--- a/.env.example
+++ b/.env.example
@@ -23,7 +23,7 @@ NOTES_BASE_URL=https://notes.geckopico.com
 #
 # In development: GAM_BASE_URL=http://localhost:8001 and NOTES_BASE_URL=http://localhost:8000.
 # The dev user (DEV_AUTH_USER) sends no token, so GAM must run with a dev user too.
-GAM_BASE_URL=https://gam.geckopico.com
+GAM_BASE_URL=https://assets.geckopico.com
 
 # Per-request timeout for GAM, in seconds.
 GAM_TIMEOUT_SECONDS=30
@@ -31,6 +31,21 @@ GAM_TIMEOUT_SECONDS=30
 # The largest file "Copy into GAM" will move out of a note pushed from Notes, in MB.
 NOTE_MEDIA_MAX_MB=4096
 
+# ─── Rendering ───────────────────────────────────────────────────────────────
+#
+# Narration is read through Gecko Notes (NOTES_BASE_URL) as the signed-in user, so
+# voices and speech keys stay in Notes' settings. That needs a Notes with
+# gecko-notes#211; an older one makes a render stop and say so.
+
+# Renders running at once. Encoding is CPU-bound and shares the box with Notes and GAM.
+RENDER_CONCURRENCY=1
+RENDER_MAX_SEGMENTS=200
+RENDER_MAX_NARRATION_CHARS=60000
+# GAM files fetched for rendering are cached under data/cache/media, pruned to this.
+RENDER_CACHE_MAX_GB=20
+# How long the link to a finished render stays valid, in seconds.
+MEDIA_URL_TTL_SECONDS=3600
+
 # ─── Administrators ──────────────────────────────────────────────────────────
 
 # Gecko Notes user ids or usernames, comma-separated, matched exactly. Nothing in GVC
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 42db076..bafd92f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,8 +42,16 @@ jobs:
           cache: pip
           cache-dependency-path: backend/requirements-dev.txt
 
-      # No ffmpeg step yet: nothing renders until M2, and no test shells out to it.
-      # Add GAM's "Ensure ffmpeg is available" step back with the renderer.
+      # The render tests encode real video. Conditional because the runner image may
+      # already ship it and `apt-get update` is not free.
+      - name: Ensure ffmpeg is available
+        run: |
+          if command -v ffmpeg >/dev/null && command -v ffprobe >/dev/null; then
+            echo "ffmpeg already present: $(ffmpeg -version | head -1)"
+          else
+            sudo apt-get update
+            sudo apt-get install -y --no-install-recommends ffmpeg
+          fi
 
       - name: Install dependencies
         run: pip install -r requirements-dev.txt
diff --git a/.gitignore b/.gitignore
index 685ac61..5938f75 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,7 +10,7 @@ venv/
 .env.*
 !.env.example
 
-data/db/
+data/
 backend/data/
 backend/*.db*
 # Alembic's autogenerate scratch database (GAM committed one by accident once).
diff --git a/README.md b/README.md
index f32df39..9cf6a2d 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,13 @@ There are three ways to start one:
 
 ## Status
 
-**M0 (Genesis).** Sign in through Gecko Notes, create projects, build their structure
-by hand or as JSON, validate them against the schema, keep a version history and import
-a spec pushed from Notes. Nothing renders yet. That's M2.
+**M2 (the renderer).** Build a video by hand, or push one in from Notes. Find footage in
+GAM by what is said in it. Then preview and render it:
+- per-scene transitions and Ken Burns moves between two frames of a picture;
+- any number of soundtrack tracks, crossfading between scenes;
+- trimmed clips, and narration read through Gecko Notes.
+
+Timed overlays, saving renders to GAM and credits are next (M2b).
 
 ## Read first
 
diff --git a/backend/alembic/versions/20261016_0500_add_render_job_table.py b/backend/alembic/versions/20261016_0500_add_render_job_table.py
new file mode 100644
index 0000000..6cba24c
--- /dev/null
+++ b/backend/alembic/versions/20261016_0500_add_render_job_table.py
@@ -0,0 +1,56 @@
+"""Add the render_job table: one render of one version of a project.
+
+Revision ID: 1c0c7b02acd3
+Revises: 389de295043a
+Create Date: 2026-10-16 05:00:03.642906+00:00
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel
+
+
+revision: str = '1c0c7b02acd3'
+down_revision: Union[str, None] = '389de295043a'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table('render_job',
+    sa.Column('id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('project_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('user_id', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('version_seq', sa.Integer(), nullable=False),
+    sa.Column('preview', sa.Boolean(), nullable=False),
+    sa.Column('status', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('stage', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('progress', sa.Integer(), nullable=False),
+    sa.Column('detail', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('error_message', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('warnings', sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+    sa.Column('video_path', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('subtitle_path', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('poster_path', sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+    sa.Column('duration', sa.Float(), nullable=True),
+    sa.Column('size_bytes', sa.Integer(), nullable=True),
+    sa.Column('narration_chars', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(), nullable=False),
+    sa.ForeignKeyConstraint(['project_id'], ['project.id'], ),
+    sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('render_job', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_render_job_project_id'), ['project_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_render_job_user_id'), ['user_id'], unique=False)
+
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('render_job', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_render_job_user_id'))
+        batch_op.drop_index(batch_op.f('ix_render_job_project_id'))
+
+    op.drop_table('render_job')
diff --git a/backend/app/assets/fonts/Inter-Regular.ttf b/backend/app/assets/fonts/Inter-Regular.ttf
new file mode 100644
index 0000000..b7aaca8
Binary files /dev/null and b/backend/app/assets/fonts/Inter-Regular.ttf differ
diff --git a/backend/app/assets/fonts/Inter-SemiBold.ttf b/backend/app/assets/fonts/Inter-SemiBold.ttf
new file mode 100644
index 0000000..47f8ab1
Binary files /dev/null and b/backend/app/assets/fonts/Inter-SemiBold.ttf differ
diff --git a/backend/app/assets/fonts/OFL.txt b/backend/app/assets/fonts/OFL.txt
new file mode 100644
index 0000000..9b2ca37
--- /dev/null
+++ b/backend/app/assets/fonts/OFL.txt
@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/backend/app/auth.py b/backend/app/auth.py
index a2f498f..bd74a1c 100644
--- a/backend/app/auth.py
+++ b/backend/app/auth.py
@@ -25,7 +25,9 @@
 
 import base64
 import hashlib
+import hmac
 import logging
+import time
 from typing import Annotated, Optional
 from urllib.parse import urlsplit
 
@@ -317,3 +319,30 @@ def decrypt_api_key(value: str) -> str:
     except InvalidToken:
         logger.warning("Stored key could not be decrypted; treating as unset")
         return ""
+
+
+# ─── signed media URLs ───────────────────────────────────────────────────────
+#
+# Copied from GAM. A finished render is served at a signed URL rather than behind the
+# Authorization header, because a <video> element cannot send one. A signature works where an Authorization header cannot: a <video> or <img> element
+# cannot send one, but it can carry query parameters.
+
+
+def sign_media_key(key: str, *, ttl_seconds: Optional[int] = None) -> tuple[int, str]:
+    """Return `(expiry, signature)` for a storage key."""
+    ttl = settings.media_url_ttl_seconds if ttl_seconds is None else ttl_seconds
+    expires_at = int(time.time()) + ttl
+    return expires_at, _media_signature(key, expires_at)
+
+
+def _media_signature(key: str, expires_at: int) -> str:
+    message = f"{key}|{expires_at}".encode()
+    digest = hmac.new(settings.jwt_secret_key.encode(), message, hashlib.sha256).digest()
+    return base64.urlsafe_b64encode(digest).decode().rstrip("=")
+
+
+def verify_media_signature(key: str, expires_at: int, signature: str) -> bool:
+    """Constant-time check of a media URL's signature and expiry."""
+    if expires_at < int(time.time()):
+        return False
+    return hmac.compare_digest(_media_signature(key, expires_at), signature)
diff --git a/backend/app/config.py b/backend/app/config.py
index ec3b6aa..4bf4398 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -55,9 +55,15 @@ class Settings(BaseSettings):
     # all there is to locate.
     database_url: str = ""
 
+    # Where renders, the media cache and render work live. `data/db` stays the
+    # database's own directory inside it.
+    data_dir: str = ""
+    # How long a signed URL to a finished render stays valid.
+    media_url_ttl_seconds: int = 3600
+
     # ─── siblings ────────────────────────────────────────────────────────────
     # The media library: footage, pictures and music are searched for and kept there.
-    gam_base_url: str = "https://gam.geckopico.com"
+    gam_base_url: str = "https://assets.geckopico.com"
     # Per request to GAM. Generous, because a search that runs its semantic half calls
     # an embedding provider before it answers.
     gam_timeout_seconds: float = 30
@@ -69,6 +75,20 @@ class Settings(BaseSettings):
     # ─── http ────────────────────────────────────────────────────────────────
     cors_origin: str = ""
 
+    # ─── rendering (M2) ───────────────────────────────────────────────────────
+    # One at a time by default: encoding is CPU-bound, and on the suite's server it
+    # shares the machine with Notes and GAM.
+    render_concurrency: int = 1
+    render_max_segments: int = 200
+    # Narration is billed per character, through the user's own speech provider.
+    render_max_narration_chars: int = 60_000
+    # Size the render cache (GAM files fetched for rendering) is pruned back to.
+    render_cache_max_gb: float = 20
+    # The largest single file a render will fetch from GAM.
+    render_max_file_mb: int = 8192
+    job_heartbeat_seconds: int = 30
+    job_stale_minutes: int = 40
+
     # ─── administration ──────────────────────────────────────────────────────
     # Comma-separated user ids or usernames, matched exactly. The Notes token carries no
     # admin claim, so this is the only way anybody becomes one. Nothing in M0 is
@@ -99,6 +119,10 @@ def resolved_database_url(self) -> str:
             return self.database_url
         return f"sqlite:///{REPO_ROOT / 'data' / 'db' / 'gvc.db'}"
 
+    @property
+    def resolved_data_dir(self) -> Path:
+        return Path(self.data_dir) if self.data_dir else REPO_ROOT / "data"
+
     @property
     def cors_origins(self) -> List[str]:
         return [o.strip() for o in self.cors_origin.split(",") if o.strip()]
diff --git a/backend/app/gam/client.py b/backend/app/gam/client.py
index f15635b..fdf370f 100644
--- a/backend/app/gam/client.py
+++ b/backend/app/gam/client.py
@@ -51,6 +51,7 @@ def to_asset(raw: Dict[str, Any]) -> GamAssetRead:
         file_url=_absolute(raw.get("file_url")),
         thumb_url=_absolute(raw.get("thumb_url")),
         credit=raw.get("credit") or "",
+        size_bytes=raw.get("size_bytes") or 0,
         parent_asset_id=raw.get("parent_asset_id"),
         in_point=raw.get("in_point"),
         out_point=raw.get("out_point"),
@@ -136,6 +137,23 @@ def get_asset(self, asset_id: str) -> Optional[GamAssetRead]:
             raise GamError(code, message)
         return to_asset(response.json()["data"])
 
+    def download(self, file_url: str, sink, *, max_bytes: int) -> int:
+        """Stream one of GAM's signed media URLs into `sink`. Returns the bytes written."""
+        written = 0
+        try:
+            with self._http.stream("GET", file_url, timeout=600) as response:
+                if response.status_code != 200:
+                    raise GamError("gam_media_unavailable",
+                                   f"The asset library would not hand over a file ({response.status_code})")
+                for chunk in response.iter_bytes(1024 * 1024):
+                    written += len(chunk)
+                    if written > max_bytes:
+                        raise GamError("gam_media_too_large", "A file in this video is too large to render")
+                    sink.write(chunk)
+        except httpx.HTTPError as exc:
+            raise GamError("gam_unavailable", "Could not fetch a file from the asset library") from exc
+        return written
+
     def upload(self, filename: str, stream: IO[bytes], content_type: Optional[str]) -> GamAssetRead:
         """Store one file in the user's library and return it."""
         response = self._request(
diff --git a/backend/app/jobs/__init__.py b/backend/app/jobs/__init__.py
new file mode 100644
index 0000000..1942c90
--- /dev/null
+++ b/backend/app/jobs/__init__.py
@@ -0,0 +1 @@
+"""Background jobs: the queue and worker threads, and the kinds that run on them."""
diff --git a/backend/app/jobs/runner.py b/backend/app/jobs/runner.py
new file mode 100644
index 0000000..1832e17
--- /dev/null
+++ b/backend/app/jobs/runner.py
@@ -0,0 +1,329 @@
+"""The queue and worker threads a background job kind runs on.
+
+Copied from GAM, which ported it from gecko-notes' `app/jobs/runner.py`. Its reasoning
+holds unchanged and is worth restating, because it is why this is threads-and-a-queue rather than
+FastAPI's BackgroundTasks: transcoding and transcription saturate the CPU or block on a
+slow upstream while sharing a container with the API, so unbounded parallelism would
+starve request handling; a job needs to be cancellable mid-flight; and a job that was
+running when the process restarted has to be picked up rather than left stuck at
+"processing" forever.
+
+A kind supplies its table and a `run(job_id)` function. The queue, the worker threads,
+cooperative cancellation, heartbeats and restart recovery are all here.
+
+Single process only, deliberately. `_queue` and `_cancelled` are per-process state, so
+the concurrency cap and cancellation only hold within one interpreter — which matches
+how this is deployed (one uvicorn process over SQLite). Running replicas would mean
+moving the queue into the database or a broker, and this file is where that change
+would go.
+
+Changed from the original: the engine is injected rather than imported, so a test
+constructs a queue against its own database instead of monkeypatching a module global.
+And (GVC) a queue may say that interrupted work cannot be resumed: a render runs as the
+user who asked for it, with a token held only in memory, so after a restart there is
+nobody to run it as. `requeue_on_restart=False` ends those jobs with a message instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import queue
+import threading
+import time
+from datetime import timedelta
+from typing import Any, Callable, Iterable, List, Optional, Set, Type
+
+from sqlalchemy.engine import Engine
+from sqlmodel import Session, select
+
+from app.clock import utcnow
+from app.config import settings
+from app.database import engine as default_engine
+
+logger = logging.getLogger(__name__)
+
+# A job is "active" while it is waiting for, or sitting on, a worker thread. Everything
+# derived from "is this still going" keys off this tuple.
+ACTIVE_STATUSES = ("queued", "processing")
+
+TERMINAL_STATUSES = ("done", "error", "cancelled")
+
+# How often the sweeper looks for jobs whose heartbeat stopped.
+STALE_SWEEP_SECONDS = 60
+
+
+def stale_after() -> timedelta:
+    """How long a job may go silent before it is treated as dead.
+
+    Read at call time rather than captured at import, so a test can shorten it. With a
+    heartbeat every 30s this is a backstop rather than the mechanism, and it is set
+    well beyond any real run: ending live work is far worse than leaving a dead row
+    looking active for a while longer.
+    """
+    return timedelta(minutes=settings.job_stale_minutes)
+
+
+def is_stale(job: Any) -> bool:
+    """True when an active job has stopped reporting."""
+    if getattr(job, "status", None) not in ACTIVE_STATUSES:
+        return False
+    updated = getattr(job, "updated_at", None)
+    if not updated:
+        return False
+    return utcnow() - updated > stale_after()
+
+
+def set_fields(session: Session, job: Any, **fields: Any) -> None:
+    """Write fields to a job row and commit, touching `updated_at`.
+
+    `updated_at` advancing on every write is what makes it a heartbeat: a row that
+    stops moving is a worker that stopped working.
+    """
+    for key, value in fields.items():
+        setattr(job, key, value)
+    job.updated_at = utcnow()
+    session.add(job)
+    session.commit()
+
+
+def readable_error(exc: Exception) -> str:
+    """An exception as something worth showing a user.
+
+    Callers raise HTTPException, whose str() is the raw `400: {'code': ...}` repr. The
+    message inside it is the part someone can act on — "Deepgram API key is not
+    configured" rather than a traceback.
+    """
+    detail = getattr(exc, "detail", None)
+    if isinstance(detail, dict) and detail.get("message"):
+        return str(detail["message"])
+    if isinstance(detail, str) and detail:
+        return detail
+    return str(exc) or exc.__class__.__name__
+
+
+class JobCancelled(Exception):
+    """Raised at a checkpoint to unwind a job somebody stopped."""
+
+
+class JobQueue:
+    """One queue, its worker threads, and the cancellation set for a job table.
+
+    `kinds` / `exclude_kinds` let two queues share one table (M8): generation has its
+    own workers so a four-minute video cannot hold every transcription behind it, but
+    its rows live in `EnrichmentJob` like everything else. The filter is applied
+    wherever a queue goes looking for rows on its own — restart recovery and the stale
+    sweep — because without it each queue would requeue the other's work on start and
+    run it on the wrong workers. Unfiltered (both None) is every row, as before.
+    """
+
+    def __init__(
+        self,
+        model: Type[Any],
+        run: Callable[[str], None],
+        *,
+        name: str,
+        concurrency: int = 1,
+        engine: Optional[Engine] = None,
+        kinds: Optional[Iterable[str]] = None,
+        exclude_kinds: Optional[Iterable[str]] = None,
+        requeue_on_restart: bool = True,
+    ) -> None:
+        self.model = model
+        self.run = run
+        self.name = name
+        self.concurrency = max(1, concurrency)
+        self.engine = engine or default_engine
+        self.kinds = frozenset(kinds) if kinds is not None else None
+        self.exclude_kinds = frozenset(exclude_kinds) if exclude_kinds else None
+        self.requeue_on_restart = requeue_on_restart
+        self._queue: "queue.Queue[str]" = queue.Queue()
+        self._cancelled: Set[str] = set()
+        self._lock = threading.Lock()
+        self._started = False
+
+    def session(self) -> Session:
+        return Session(self.engine)
+
+    def _active_rows(self, session: Session) -> List[Any]:
+        """Every active row this queue owns."""
+        query = select(self.model).where(self.model.status.in_(ACTIVE_STATUSES))
+        if self.kinds is not None:
+            query = query.where(self.model.kind.in_(self.kinds))
+        if self.exclude_kinds is not None:
+            query = query.where(self.model.kind.not_in(self.exclude_kinds))
+        return list(session.exec(query).all())
+
+    # ─── control ─────────────────────────────────────────────────────────────
+
+    def enqueue(self, job_id: str) -> None:
+        self._queue.put(job_id)
+
+    def cancel(self, job_id: str) -> None:
+        """Ask a job to stop.
+
+        A queued job never starts; a running one unwinds at its next checkpoint,
+        wherever the kind chose to put those.
+        """
+        with self._lock:
+            self._cancelled.add(job_id)
+
+    def is_cancelled(self, job_id: str) -> bool:
+        with self._lock:
+            return job_id in self._cancelled
+
+    # ─── lifecycle ───────────────────────────────────────────────────────────
+
+    def start(self) -> None:
+        """Start the workers and requeue anything a restart interrupted.
+
+        Idempotent: the app lifespan is not the only caller, and a test may start a
+        queue directly.
+        """
+        if self._started:
+            return
+        self._started = True
+
+        for index in range(self.concurrency):
+            threading.Thread(
+                target=self._loop, daemon=True, name=f"{self.name}-{index}"
+            ).start()
+        threading.Thread(
+            target=self._sweeper, daemon=True, name=f"{self.name}-sweep"
+        ).start()
+        self.recover_pending()
+
+    def sweep_stale(self) -> int:
+        """End jobs whose heartbeat stopped, and tell their worker to unwind.
+
+        Cancelling as well as marking matters: a thread that later returns from a
+        wedged call must not go on writing for a job already reported as failed, and
+        the cancelled set is what its next checkpoint reads.
+        """
+        swept = 0
+        try:
+            with self.session() as session:
+                for row in self._active_rows(session):
+                    if not is_stale(row):
+                        continue
+                    self.cancel(row.id)
+                    fields: dict = {
+                        "status": "error",
+                        "error_message": "Stopped responding and was ended automatically",
+                    }
+                    if hasattr(row, "stage"):
+                        fields["stage"] = ""
+                    set_fields(session, row, **fields)
+                    swept += 1
+                if swept:
+                    logger.warning("Ended %d stalled %s job(s)", swept, self.name)
+        except Exception:
+            logger.exception("Could not sweep stalled %s jobs", self.name)
+        return swept
+
+    def _sweeper(self) -> None:
+        while True:
+            time.sleep(STALE_SWEEP_SECONDS)
+            self.sweep_stale()
+
+    def heartbeat(self, job_id: str, stop: threading.Event) -> None:
+        """Say "still alive" until `stop` is set.
+
+        Only `updated_at` is touched, never stage or progress: this is liveness, not a
+        progress report, and it must not overwrite what the job last said about itself.
+        It returns early once the row is no longer active, so a finished or cancelled
+        job is not kept looking live.
+        """
+        interval = max(1, settings.job_heartbeat_seconds)
+        while not stop.wait(interval):
+            try:
+                with self.session() as session:
+                    row = session.get(self.model, job_id)
+                    if not row or row.status not in ACTIVE_STATUSES:
+                        return
+                    row.updated_at = utcnow()
+                    session.add(row)
+                    session.commit()
+            except Exception:
+                # A missed beat is survivable; a heartbeat that kills the worker is not.
+                logger.exception("Heartbeat failed for %s job %s", self.name, job_id)
+
+    def _loop(self) -> None:
+        while True:
+            job_id = self._queue.get()
+            # Beats for as long as the job runs, so genuinely slow work is not mistaken
+            # for a dead worker. Without it the sweeper ends a long transcription
+            # mid-flight — and it does not merely release it, it marks it failed.
+            stop = threading.Event()
+            threading.Thread(
+                target=self.heartbeat,
+                args=(job_id, stop),
+                daemon=True,
+                name=f"{self.name}-beat",
+            ).start()
+            try:
+                self.run(job_id)
+            except Exception:
+                logger.exception("Unhandled error in the %s worker", self.name)
+            finally:
+                stop.set()
+                with self._lock:
+                    self._cancelled.discard(job_id)
+                self._queue.task_done()
+
+    def recover_pending(self) -> None:
+        """Re-enqueue work that outlived the process doing it.
+
+        A job left at "processing" by a restart has no worker any more, so it goes back
+        on the queue and starts over. Finished and cancelled rows are untouched, so a
+        restart never resurrects a run somebody stopped.
+        """
+        try:
+            with self.session() as session:
+                rows = self._active_rows(session)
+                for row in rows:
+                    if not self.requeue_on_restart:
+                        set_fields(session, row, status="error", stage="",
+                                   error_message="Interrupted by a restart of the server. "
+                                                 "Start it again.")
+                        continue
+                    fields: dict = {"status": "queued"}
+                    if hasattr(row, "stage"):
+                        fields["stage"] = ""
+                    if hasattr(row, "progress"):
+                        fields["progress"] = 0
+                    if hasattr(row, "detail"):
+                        fields["detail"] = "Requeued after a restart"
+                    set_fields(session, row, **fields)
+                    self._queue.put(row.id)
+                if rows:
+                    logger.info("Requeued %d unfinished %s job(s)", len(rows), self.name)
+        except Exception:
+            logger.exception("Could not recover pending %s jobs", self.name)
+
+    # ─── progress ────────────────────────────────────────────────────────────
+
+    def reporter(self, job_id: str) -> Callable[[str, int, str], None]:
+        """The `(stage, percent, detail)` callback a long job reports through.
+
+        It doubles as the cancellation checkpoint: it raises JobCancelled if the job
+        has been stopped, so a job unwinds wherever it happens to be reporting rather
+        than needing its own polling. Percent clamps to 99 so only completion writes
+        100, and each tick opens its own session because this runs on a worker thread,
+        not a request.
+        """
+
+        def report(stage: str, percent: int, detail: str = "") -> None:
+            if self.is_cancelled(job_id):
+                raise JobCancelled(job_id)
+            with self.session() as session:
+                row = session.get(self.model, job_id)
+                if row:
+                    set_fields(
+                        session,
+                        row,
+                        stage=stage,
+                        progress=max(0, min(99, percent)),
+                        detail=detail,
+                    )
+
+        return report
diff --git a/backend/app/main.py b/backend/app/main.py
index 23cb5c5..6d957b4 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -22,6 +22,7 @@
 from app.gam.client import GamError
 from app.routers import gam as gam_router
 from app.routers import projects as projects_router
+from app.routers import renders as renders_router
 from app.routers import spec as spec_router
 from app.schemas import ClientConfig, DataResponse, HealthResponse
 
@@ -37,14 +38,19 @@ def ffmpeg_available() -> bool:
 
 @asynccontextmanager
 async def lifespan(_app: FastAPI):
-    # Nothing renders until M2, so a missing ffmpeg is noted rather than warned about.
     if not ffmpeg_available():
-        logger.info("ffmpeg/ffprobe not found on PATH; rendering (M2) will need them.")
+        logger.warning("ffmpeg/ffprobe not found on PATH: renders will fail.")
     # One line here beats the same fact arriving as a traceback on whichever request
     # first touches a table that does not exist yet.
     from app.schema_check import log_if_behind
 
     log_if_behind(engine)
+
+    # Picks up nothing a restart interrupted (a render runs as its requester, whose
+    # token is gone), and starts the render workers.
+    from app.render import worker
+
+    worker.start()
     yield
 
 
@@ -138,3 +144,6 @@ def me(user: CurrentUser, session: Session = Depends(get_session)) -> DataRespon
 app.include_router(projects_router.router, prefix="/api/projects", tags=["projects"])
 app.include_router(spec_router.router, prefix="/api/spec", tags=["spec"])
 app.include_router(gam_router.router, prefix="/api/gam", tags=["gam"])
+app.include_router(renders_router.router, prefix="/api", tags=["renders"])
+# Not under /api: these URLs go straight into <video src>, authorised by signature.
+app.include_router(renders_router.media_router, prefix="/media/renders", tags=["media"])
diff --git a/backend/app/media/__init__.py b/backend/app/media/__init__.py
new file mode 100644
index 0000000..3d6216e
--- /dev/null
+++ b/backend/app/media/__init__.py
@@ -0,0 +1 @@
+"""Serving bytes to the browser."""
diff --git a/backend/app/media/ranged.py b/backend/app/media/ranged.py
new file mode 100644
index 0000000..453a249
--- /dev/null
+++ b/backend/app/media/ranged.py
@@ -0,0 +1,133 @@
+"""HTTP Range responses.
+
+Starlette's FileResponse has no Range support, so a `<video src>` pointed at it can
+only download the whole file — the browser cannot seek, and a scrub bar does nothing.
+For a library built around jumping to a timestamp inside a ninety-minute interview,
+that is the difference between working and not.
+
+Adapted from gecko-notes' `media_files.py`, which solves the same problem for its
+static mount. Rewritten against the storage layer rather than a filesystem path, so it
+keeps working when the bytes are not local.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import BinaryIO, Iterator, Optional, Tuple
+
+from fastapi import HTTPException, status
+from fastapi.responses import StreamingResponse
+
+# 64 KiB: large enough that streaming a film is not a syscall storm, small enough that
+# a cancelled request stops promptly.
+CHUNK_SIZE = 64 * 1024
+
+_RANGE_PATTERN = re.compile(r"^bytes=(\d*)-(\d*)$")
+
+
+def parse_range(header: Optional[str], size: int) -> Optional[Tuple[int, int]]:
+    """Interpret a Range header as an inclusive `(start, end)`.
+
+    Returns None when there is no range to honour — no header, a unit other than
+    bytes, or a malformed value — in which case the caller sends the whole body. Raises
+    416 only for a syntactically valid range that cannot be satisfied, which is what
+    the specification asks for.
+
+    Only single ranges are supported. Multi-range requests are rare, require a
+    multipart/byteranges body, and no browser needs them for media playback.
+    """
+    if not header:
+        return None
+
+    match = _RANGE_PATTERN.match(header.strip())
+    if not match:
+        return None
+
+    first, last = match.group(1), match.group(2)
+
+    if not first and not last:
+        return None
+
+    if not first:
+        # "bytes=-500" — the final 500 bytes. Players use this to read a trailing
+        # index (an MP4 moov atom at the end of the file, for instance).
+        suffix = int(last)
+        if suffix <= 0:
+            raise _unsatisfiable(size)
+        start = max(0, size - suffix)
+        return start, size - 1
+
+    start = int(first)
+    end = int(last) if last else size - 1
+
+    if start >= size or start > end:
+        raise _unsatisfiable(size)
+
+    # A range running past the end is clamped, not rejected: a player asking for more
+    # than exists should get what exists.
+    return start, min(end, size - 1)
+
+
+def _unsatisfiable(size: int) -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE,
+        detail={"code": "range_not_satisfiable", "message": "Requested range is outside the file"},
+        headers={"Content-Range": f"bytes */{size}"},
+    )
+
+
+def iter_slice(handle: BinaryIO, start: int, end: int) -> Iterator[bytes]:
+    """Yield `[start, end]` inclusive, then close the handle."""
+    try:
+        handle.seek(start)
+        remaining = end - start + 1
+        while remaining > 0:
+            chunk = handle.read(min(CHUNK_SIZE, remaining))
+            if not chunk:
+                break
+            remaining -= len(chunk)
+            yield chunk
+    finally:
+        handle.close()
+
+
+def ranged_response(
+    handle: BinaryIO,
+    *,
+    size: int,
+    media_type: str,
+    range_header: Optional[str],
+    filename: Optional[str] = None,
+    cache_seconds: int = 0,
+) -> StreamingResponse:
+    """A 200 or a 206, depending on what was asked for."""
+    headers = {
+        # Advertised on every response, including the 200. A player checks this before
+        # it will offer seeking at all.
+        "accept-ranges": "bytes",
+        "content-length": str(size),
+    }
+    if cache_seconds:
+        headers["cache-control"] = f"private, max-age={cache_seconds}"
+    if filename:
+        # Quoted and sanitised by the caller; only ever used for a download name.
+        headers["content-disposition"] = f'inline; filename="{filename}"'
+
+    requested = parse_range(range_header, size)
+    if requested is None:
+        return StreamingResponse(
+            iter_slice(handle, 0, size - 1),
+            status_code=status.HTTP_200_OK,
+            media_type=media_type,
+            headers=headers,
+        )
+
+    start, end = requested
+    headers["content-length"] = str(end - start + 1)
+    headers["content-range"] = f"bytes {start}-{end}/{size}"
+    return StreamingResponse(
+        iter_slice(handle, start, end),
+        status_code=status.HTTP_206_PARTIAL_CONTENT,
+        media_type=media_type,
+        headers=headers,
+    )
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 02ede35..7438325 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -6,6 +6,7 @@
 """
 
 from app.models.project import Project, ProjectVersion
+from app.models.render import RenderJob
 from app.models.user import User
 
-__all__ = ["Project", "ProjectVersion", "User"]
+__all__ = ["Project", "ProjectVersion", "RenderJob", "User"]
diff --git a/backend/app/models/render.py b/backend/app/models/render.py
new file mode 100644
index 0000000..4338411
--- /dev/null
+++ b/backend/app/models/render.py
@@ -0,0 +1,35 @@
+"""A render of one version of a project."""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlmodel import Field, SQLModel
+
+from app.clock import utcnow
+
+
+class RenderJob(SQLModel, table=True):
+    __tablename__ = "render_job"
+
+    id: str = Field(primary_key=True)
+    project_id: str = Field(foreign_key="project.id", index=True)
+    user_id: str = Field(foreign_key="user.id", index=True)
+    # The version rendered: later edits never change a render already asked for.
+    version_seq: int
+    preview: bool = True
+    # queued | processing | done | error | cancelled (jobs/runner.py)
+    status: str = "queued"
+    stage: str = ""
+    progress: int = 0
+    detail: str = ""
+    error_message: Optional[str] = None
+    warnings: str = "[]"            # JSON list of sentences
+    # Paths relative to the renders directory; set when done.
+    video_path: Optional[str] = None
+    subtitle_path: Optional[str] = None
+    poster_path: Optional[str] = None
+    duration: Optional[float] = None
+    size_bytes: Optional[int] = None
+    narration_chars: int = 0
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
diff --git a/backend/app/render/compile.py b/backend/app/render/compile.py
new file mode 100644
index 0000000..a0e546d
--- /dev/null
+++ b/backend/app/render/compile.py
@@ -0,0 +1,431 @@
+"""VideoSpec -> units -> a laid-out timeline. Pure: no ffmpeg, no network, no disk.
+
+This is the compile step of the Notes spec doc §5.8, done natively rather than by
+mapping the spec back onto Notes' flat shot list (plan of attack, D1). Notes' mapping
+is why it refuses per-scene transitions, per-scene motion and more than one track:
+its target could not say them. Here each of those is a field on a unit or a join.
+
+Three stages, each testable alone:
+
+1. `plan_units`: segments become units. A scene is cut at each beat that carries a
+   quote or code overlay (each such beat is a unit of its own, drawn as a screen
+   with its panel, as Notes always has); a card or a clip is one unit. Defaults
+   cascade project -> segment here, once.
+2. `unit_duration`: once narration has been synthesised and measured (the renderer
+   does that), how long each unit runs.
+3. `layout`: units end to end, with each join's transition, and the overlap a blend
+   takes. Then `resolve_anchor` turns the spec's structural anchors ("the start of
+   the market scene, 3 s early") into seconds on that timeline.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence, Tuple, Union
+
+from app.render.ffmpeg import KENBURNS_CYCLE, MIN_TRANSITION_SECONDS, XFADE_MAX_SHOTS
+from app.render.options import XFADE_NAMES, is_crossfade
+from app.spec.model import (
+    AnchorRef, AudioTrack, Beat, Card, CodeOverlay, Motion, QuoteOverlay, Segment,
+    Transition, VideoSpec,
+)
+
+UnitKind = str  # "still" | "card" | "video_muted" | "video_sound"
+
+
+@dataclass
+class Media:
+    """An asset made local by `media.py`: what the compiler needs to know of it."""
+
+    path: str
+    kind: str                      # "image" | "video" | "audio" | "slate"
+    duration: Optional[float] = None
+    has_audio: bool = False
+    width: Optional[int] = None
+    height: Optional[int] = None
+    # A GAM clip is its parent's bytes between two points; `offset` is where it
+    # starts in the file, `length` how long it is.
+    offset: float = 0.0
+    length: Optional[float] = None
+
+
+@dataclass
+class Panel:
+    kind: str                      # "quote" | "code"
+    text: str
+    attribution: str = ""
+
+
+@dataclass
+class Unit:
+    segment_id: str
+    segment_index: int
+    first_in_segment: bool
+    kind: UnitKind
+    media: Optional[Media]         # None: a drawn background (a card, or no picture)
+    beats: List[Beat] = field(default_factory=list)
+    card: Optional[Card] = None
+    # Seconds into the file and how long, for a video; None plays it whole.
+    trim: Optional[Tuple[float, float]] = None
+    loop: bool = True
+    panel: Optional[Panel] = None
+    motion: Optional[Motion] = None   # resolved, `alternate` already cycled
+    fit: str = "blur"
+    transition_in: Transition = field(default_factory=Transition)
+    min_seconds: float = 2.5
+    fixed_seconds: Optional[float] = None
+    voice: Optional[str] = None
+    speed: float = 1.0
+    chrome: bool = True
+    chapter: Optional[str] = None
+
+
+def _transition_in(spec: VideoSpec, segment: Segment) -> Transition:
+    """A segment's incoming join: its own fields over the project's, field by field."""
+    base = spec.style.transition
+    own = segment.transition_in
+    if own is None:
+        return base
+    return Transition(style=own.style or base.style,
+                      duration=own.duration if own.duration is not None else base.duration)
+
+
+def _motion(spec: VideoSpec, segment: Segment, position: int) -> Optional[Motion]:
+    motion = segment.visual.motion if segment.visual and segment.visual.motion else spec.style.motion
+    if motion.effect == "none":
+        return None
+    if motion.effect == "alternate":
+        return Motion(effect=KENBURNS_CYCLE[position % len(KENBURNS_CYCLE)], amount=motion.amount)
+    return motion
+
+
+def _panel_for(overlay: Union[QuoteOverlay, CodeOverlay]) -> Panel:
+    if isinstance(overlay, QuoteOverlay):
+        return Panel("quote", overlay.text, overlay.attribution or "")
+    return Panel("code", overlay.text)
+
+
+def _panel_beats(segment: Segment, warnings: List[str]) -> Tuple[Dict[str, Panel], Optional[Panel]]:
+    """Quote and code overlays: those anchored to a beat, and one for the whole scene."""
+    by_beat: Dict[str, Panel] = {}
+    whole: Optional[Panel] = None
+    for overlay in segment.overlays:
+        if not isinstance(overlay, (QuoteOverlay, CodeOverlay)):
+            # Timed text, lower thirds and images are M2b: a second technique
+            # (overlay with enable=) on top of this one. Said, never silently lost.
+            warnings.append(f"Scene {segment.label or segment.id}: {overlay.type} overlays "
+                            "are not rendered yet")
+            continue
+        anchor = overlay.show.from_ if overlay.show else None
+        if isinstance(anchor, AnchorRef) and anchor.beat and anchor.segment in (None, segment.id):
+            by_beat[anchor.beat] = _panel_for(overlay)
+        else:
+            whole = _panel_for(overlay)
+    return by_beat, whole
+
+
+def plan_units(spec: VideoSpec, media: Dict[str, Media], warnings: List[str]) -> List[Unit]:
+    """Every segment as the units it renders as, defaults resolved."""
+    units: List[Unit] = []
+    for seg_index, segment in enumerate(spec.segments):
+        visual = segment.visual
+        found = media.get(visual.asset) if visual else None
+        voice = segment.narration.voice if segment.narration else None
+        common = dict(
+            segment_id=segment.id,
+            segment_index=seg_index,
+            fit=(visual.fit if visual and visual.fit else spec.style.fit),
+            transition_in=_transition_in(spec, segment),
+            min_seconds=(segment.duration.min if segment.duration and segment.duration.min
+                         else spec.style.min_segment_seconds),
+            fixed_seconds=segment.duration.fixed if segment.duration else None,
+            voice=(voice.voice if voice and voice.voice else spec.voice.voice),
+            speed=(voice.speed if voice and voice.speed else spec.voice.speed),
+            chrome=(segment.chrome if segment.chrome is not None
+                    else segment.role not in ("intro", "outro")),
+        )
+
+        trim: Optional[Tuple[float, float]] = None
+        if found and found.kind == "video":
+            start = found.offset + (visual.trim.in_ if visual and visual.trim else 0.0)
+            if visual and visual.trim and visual.trim.out is not None:
+                length = visual.trim.out - visual.trim.in_
+            elif found.length is not None:
+                length = found.length - (visual.trim.in_ if visual and visual.trim else 0.0)
+            else:
+                length = None
+            if start > 0 or length is not None:
+                trim = (start, max(0.1, length) if length is not None else None)
+
+        if segment.kind == "card":
+            units.append(Unit(**common, first_in_segment=True, kind="card", media=None,
+                              beats=list(segment.beats), card=segment.card,
+                              chapter=segment.chapter,
+                              motion=(Motion(effect="zoom_in", amount=spec.style.motion.amount)
+                                      if spec.style.cards.motion else None)))
+            continue
+
+        if segment.kind == "clip":
+            if not found or found.kind != "video":
+                warnings.append(f"Clip {segment.label or segment.id} has no video to play; left out")
+                continue
+            units.append(Unit(**common, first_in_segment=True, kind="video_sound", media=found,
+                              trim=trim, loop=False, chapter=segment.chapter))
+            continue
+
+        if found and found.kind == "video":
+            kind = "video_muted"
+        else:
+            kind = "still"
+            if found and found.kind == "audio":
+                warnings.append(f"Scene {segment.label or segment.id}: a sound file can't be its "
+                                "picture; using the background")
+                found = None
+
+        by_beat, whole = _panel_beats(segment, warnings)
+        groups: List[Tuple[List[Beat], Optional[Panel]]] = []
+        current: List[Beat] = []
+        for beat in segment.beats:
+            if beat.id in by_beat:
+                if current:
+                    groups.append((current, whole))
+                    current = []
+                groups.append(([beat], by_beat[beat.id]))
+            else:
+                current.append(beat)
+        if current or not groups:
+            groups.append((current, whole))
+
+        for position, (beats, panel) in enumerate(groups):
+            units.append(Unit(
+                **common, first_in_segment=position == 0, kind=kind, media=found, beats=beats,
+                trim=trim, loop=visual.loop if visual else True, panel=panel,
+                motion=_motion(spec, segment, len(units)) if kind == "still" else None,
+                chapter=segment.chapter if position == 0 else None,
+            ))
+    return units
+
+
+def unit_duration(unit: Unit, narration_seconds: float, cards_seconds: float) -> float:
+    """How long a unit runs, once its narration has been measured."""
+    if unit.kind == "video_sound":
+        if unit.trim and unit.trim[1] is not None:
+            return unit.trim[1]
+        return max(0.1, (unit.media.duration or 0.0) - (unit.trim[0] if unit.trim else 0.0)) \
+            if unit.media else unit.min_seconds
+    if unit.fixed_seconds:
+        return unit.fixed_seconds
+    floor = max(unit.min_seconds, cards_seconds) if unit.kind == "card" else unit.min_seconds
+    return max(floor, narration_seconds)
+
+
+# ── layout ──────────────────────────────────────────────────────────────────
+
+@dataclass
+class Join:
+    """How unit i joins unit i-1."""
+
+    style: str            # the spec's transition style
+    duration: float       # as asked
+    overlap: float = 0.0  # seconds the two share on screen: a blend's, else 0
+
+    @property
+    def is_blend(self) -> bool:
+        return self.overlap > 0
+
+    @property
+    def is_cut(self) -> bool:
+        return self.style == "none"
+
+
+@dataclass
+class Timeline:
+    starts: List[float]
+    durations: List[float]
+    joins: List[Optional[Join]]      # joins[0] is None: nothing comes before
+    total: float
+
+    def end(self, index: int) -> float:
+        return self.starts[index] + self.durations[index]
+
+
+def layout(units: Sequence[Unit], durations: Sequence[float], warnings: List[str]) -> Timeline:
+    """Units end to end. Each join takes the transition of the unit coming in.
+
+    A unit after the first in its segment (a scene cut at a quote) joins with the
+    project's transition, as every quote has in Notes. A blend overlaps its two units
+    by its duration, held to half the shorter one so neither is ever entirely under a
+    blend; too short to see, and it becomes a cut.
+    """
+    joins: List[Optional[Join]] = [None]
+    for index in range(1, len(units)):
+        unit = units[index]
+        transition = unit.transition_in
+        join = Join(style=transition.style, duration=transition.duration)
+        if is_crossfade(transition.style):
+            overlap = min(transition.duration, 0.5 * min(durations[index - 1], durations[index]))
+            if overlap >= MIN_TRANSITION_SECONDS:
+                join.overlap = overlap
+            else:
+                join.style = "none"
+        joins.append(join)
+
+    if sum(1 for j in joins if j and j.is_blend) and len(units) > XFADE_MAX_SHOTS:
+        # One filtergraph holding every shot stops being reasonable past here;
+        # Notes draws the same line. A blend degrades to a fade through black.
+        warnings.append(f"Blends were drawn as fades: a video of more than {XFADE_MAX_SHOTS} "
+                        "shots is too large to blend")
+        for join in joins:
+            if join and join.is_blend:
+                join.style, join.overlap = "fade", 0.0
+
+    starts: List[float] = []
+    cursor = 0.0
+    for index, duration in enumerate(durations):
+        join = joins[index]
+        if join is not None and join.is_blend:
+            cursor -= join.overlap
+        starts.append(cursor)
+        cursor += duration
+    return Timeline(starts=starts, durations=list(durations), joins=joins, total=max(0.0, cursor))
+
+
+def xfade_name(style: str) -> str:
+    return XFADE_NAMES.get(style, "dissolve")
+
+
+# ── anchors ─────────────────────────────────────────────────────────────────
+
+Spans = Dict[str, Tuple[float, float]]
+
+
+@dataclass
+class Placement:
+    """Where things landed on the timeline, for anchors to point into."""
+
+    segments: Spans                                   # segment id -> (start, end)
+    beats: Dict[Tuple[str, str], Tuple[float, float]]  # (segment id, beat id) -> span
+    total: float
+
+
+def placement(units: Sequence[Unit], timeline: Timeline,
+              beat_offsets: Sequence[Dict[str, Tuple[float, float]]]) -> Placement:
+    """Segment and beat spans in seconds. `beat_offsets[i]` is unit i's beats, as
+    offsets into that unit (from its measured narration)."""
+    segments: Spans = {}
+    beats: Dict[Tuple[str, str], Tuple[float, float]] = {}
+    for index, unit in enumerate(units):
+        start, end = timeline.starts[index], timeline.end(index)
+        if unit.segment_id in segments:
+            segments[unit.segment_id] = (segments[unit.segment_id][0], end)
+        else:
+            segments[unit.segment_id] = (start, end)
+        for beat_id, (a, b) in beat_offsets[index].items():
+            beats[(unit.segment_id, beat_id)] = (start + a, start + b)
+    return Placement(segments=segments, beats=beats, total=timeline.total)
+
+
+class Orphaned(Exception):
+    """An anchor naming a segment or beat that is not in the video (any more)."""
+
+
+def resolve_anchor(anchor, where: Placement, *, segment: Optional[str] = None) -> float:
+    if anchor == "video_start":
+        return 0.0
+    if anchor == "video_end":
+        return where.total
+    seg = anchor.segment or segment
+    if seg is None:
+        raise Orphaned("an anchor names no segment")
+    if anchor.beat:
+        span = where.beats.get((seg, anchor.beat))
+        if span is None:
+            raise Orphaned(f"beat {anchor.beat!r} of segment {seg!r}")
+    else:
+        span = where.segments.get(seg)
+        if span is None:
+            raise Orphaned(f"segment {seg!r}")
+    edge = span[0] if anchor.edge == "start" else span[1]
+    return max(0.0, min(where.total, edge + anchor.offset))
+
+
+@dataclass
+class TrackPlacement:
+    track: AudioTrack
+    media: Media
+    start: float
+    length: float
+    loop: bool
+    duck: bool
+    trim_in: float
+
+
+def place_tracks(spec: VideoSpec, media: Dict[str, Media], where: Placement,
+                 warnings: List[str]) -> List[TrackPlacement]:
+    """Each audio track as a window on the timeline. One that cannot be placed is
+    dropped with a warning, never failing the render (§5.7)."""
+    placed: List[TrackPlacement] = []
+    for track in spec.audio_tracks:
+        found = media.get(track.asset)
+        if found is None or found.kind not in ("audio", "video"):
+            warnings.append(f"Audio track {track.id}: no sound to play; left out")
+            continue
+        try:
+            start = resolve_anchor(track.start, where)
+            end = resolve_anchor(track.end, where) if track.end is not None else None
+        except Orphaned as exc:
+            warnings.append(f"Audio track {track.id} is anchored to {exc}, which is not in "
+                            "the video; left out")
+            continue
+        trim_in = found.offset + (track.trim.in_ if track.trim else 0.0)
+        natural = None
+        if found.length is not None or found.duration:
+            full = found.length if found.length is not None else found.duration - found.offset
+            natural = max(0.0, full - (track.trim.in_ if track.trim else 0.0))
+            if track.trim and track.trim.out is not None:
+                natural = min(natural, track.trim.out - track.trim.in_)
+        loop = track.loop if track.loop is not None else track.kind == "music"
+        if end is None:
+            # "Play once to its natural end" (Notes spec doc §5.4).
+            end = start + (natural or 0.0)
+            loop = False
+        end = min(end, where.total)
+        if end - start < 0.1:
+            warnings.append(f"Audio track {track.id} ends before it starts; left out")
+            continue
+        length = end - start
+        if natural is not None and not loop:
+            length = min(length, natural)
+        placed.append(TrackPlacement(
+            track=track, media=found, start=start, length=length, loop=loop,
+            duck=(track.duck_under_narration if track.duck_under_narration is not None
+                  else track.kind == "music"),
+            trim_in=trim_in,
+        ))
+    return placed
+
+
+def chapters(units: Sequence[Unit], timeline: Timeline) -> List[Tuple[float, float, str]]:
+    """Chapter marks: each runs from its unit's start to the next mark."""
+    marks: List[Tuple[float, str]] = [
+        (timeline.starts[i], unit.chapter.strip())
+        for i, unit in enumerate(units) if unit.chapter and unit.chapter.strip()
+    ]
+    out = []
+    for position, (start, title) in enumerate(marks):
+        end = marks[position + 1][0] if position + 1 < len(marks) else timeline.total
+        out.append((start, end, title))
+    return out
+
+
+def beat_pause_ms(spec: VideoSpec, beats: Sequence[Beat], position: int) -> int:
+    """The silence held after a beat: its own, or the default for where it sits."""
+    beat = beats[position]
+    if beat.pause_after_ms is not None:
+        return beat.pause_after_ms
+    pauses = spec.voice.pauses
+    if position == len(beats) - 1:
+        return pauses.segment_end_ms
+    if beat.kind == "heading" or beats[position + 1].kind == "heading":
+        return pauses.heading_ms
+    return pauses.paragraph_ms
diff --git a/backend/app/render/compose.py b/backend/app/render/compose.py
new file mode 100644
index 0000000..f1681d4
--- /dev/null
+++ b/backend/app/render/compose.py
@@ -0,0 +1,553 @@
+"""Pillow composition: cards, overlays and fallback backgrounds.
+
+Every piece of static text in a rendered video is drawn here into a PNG and then
+composited by ffmpeg with a plain `overlay`, rather than being passed to
+ffmpeg's `drawtext`. That is a deliberate choice: `drawtext` needs its text
+escaped for colons, quotes, apostrophes and percent signs — note titles contain
+all of those — and it has no real line-breaking. Pillow gives proper measurement
+and wrapping, and removes the escaping surface entirely.
+"""
+
+import logging
+import math
+import os
+from typing import List, Optional, Sequence, Tuple
+
+from PIL import Image, ImageDraw, ImageFilter, ImageFont, ImageOps, UnidentifiedImageError
+
+from app.render.options import CardTextSpec, CodeSpec, OverlayTextSpec, Position, QuoteSpec, WatermarkSpec
+
+logger = logging.getLogger(__name__)
+
+FONT_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "assets", "fonts")
+REGULAR = os.path.join(FONT_DIR, "Inter-Regular.ttf")
+SEMIBOLD = os.path.join(FONT_DIR, "Inter-SemiBold.ttf")
+
+# Only used if the vendored files are somehow missing; keeps a render working
+# (with the wrong typeface) rather than failing it.
+_FALLBACKS = (
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+)
+
+# No monospace face is vendored alongside Inter, so code leans on whichever of
+# these the host has — the same Debian font packages _FALLBACKS already
+# assumes are present — before finally giving up proportional spacing
+# entirely and falling back to a normal one.
+MONO_REGULAR = "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"
+_MONO_FALLBACKS = ("/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf", *_FALLBACKS)
+
+
+def load_font(path: str, size: int, fallbacks: Sequence[str] = _FALLBACKS) -> ImageFont.FreeTypeFont:
+    for candidate in (path, *fallbacks):
+        try:
+            return ImageFont.truetype(candidate, size)
+        except OSError:
+            continue
+    logger.warning("No usable TrueType font found; falling back to the bitmap default")
+    return ImageFont.load_default()
+
+
+def parse_colour(value: str, default: Tuple[int, int, int] = (255, 255, 255)) -> Tuple[int, int, int]:
+    c = (value or "").strip().lstrip("#")
+    if len(c) == 3:
+        c = "".join(ch * 2 for ch in c)
+    if len(c) >= 6:
+        try:
+            return (int(c[0:2], 16), int(c[2:4], 16), int(c[4:6], 16))
+        except ValueError:
+            pass
+    return default
+
+
+def gradient_background(width: int, height: int, colours: Sequence[str], angle: int = 135) -> Image.Image:
+    """Two-stop linear gradient at an arbitrary angle.
+
+    Built by stretching a 1x256 ramp over the frame's diagonal, rotating it, and
+    cropping back — which keeps the gradient smooth at any angle without needing
+    a per-pixel loop (or numpy, which isn't a dependency here).
+    """
+    start = parse_colour(colours[0] if colours else "#1e293b", (30, 41, 59))
+    end = parse_colour(colours[1] if len(colours) > 1 else colours[0], (15, 23, 42))
+
+    ramp = Image.new("RGB", (1, 256))
+    px = ramp.load()
+    for i in range(256):
+        t = i / 255
+        px[0, i] = tuple(round(start[c] + (end[c] - start[c]) * t) for c in range(3))
+
+    diagonal = int(math.ceil(math.hypot(width, height))) + 2
+    stretched = ramp.resize((diagonal, diagonal), Image.BILINEAR).rotate(angle, resample=Image.BILINEAR)
+    left = (diagonal - width) // 2
+    top = (diagonal - height) // 2
+    return stretched.crop((left, top, left + width, top + height))
+
+
+def solid_background(width: int, height: int, colour: str) -> Image.Image:
+    return Image.new("RGB", (width, height), parse_colour(colour, (15, 23, 42)))
+
+
+def cover_image(path: str, width: int, height: int) -> Optional[Image.Image]:
+    """Load an image and scale-and-crop it to exactly fill the frame."""
+    try:
+        with Image.open(path) as img:
+            img = ImageOps.exif_transpose(img).convert("RGB")
+            return ImageOps.fit(img, (width, height), Image.LANCZOS, centering=(0.5, 0.5))
+    except (UnidentifiedImageError, OSError, ValueError) as exc:
+        logger.warning("Could not use %s as a background: %s", path, exc)
+        return None
+
+
+def wrap_text(draw: ImageDraw.ImageDraw, text: str, font: ImageFont.FreeTypeFont, max_width: int) -> List[str]:
+    """Greedy word wrap, breaking an over-long single word by character."""
+    lines: List[str] = []
+    for paragraph in (text or "").splitlines() or [""]:
+        words = paragraph.split()
+        if not words:
+            lines.append("")
+            continue
+        current = words[0]
+        for word in words[1:]:
+            trial = f"{current} {word}"
+            if draw.textlength(trial, font=font) <= max_width:
+                current = trial
+            else:
+                lines.append(current)
+                current = word
+        lines.append(current)
+
+    out: List[str] = []
+    for line in lines:
+        while draw.textlength(line, font=font) > max_width and len(line) > 1:
+            cut = len(line)
+            while cut > 1 and draw.textlength(line[:cut], font=font) > max_width:
+                cut -= 1
+            out.append(line[:cut])
+            line = line[cut:]
+        out.append(line)
+    return out
+
+
+def fit_font(
+    draw: ImageDraw.ImageDraw, text: str, font_path: str,
+    start_size: int, max_width: int, min_size: int = 8,
+) -> ImageFont.FreeTypeFont:
+    """Largest size at or below `start_size` where the longest word still fits.
+
+    Wrapping alone can't help a single unbreakable token — a domain name, a long
+    hashtag — which would otherwise be chopped mid-word; shrinking it does.
+    """
+    words = (text or "").split() or [""]
+    size = max(min_size, start_size)
+    while size > min_size:
+        font = load_font(font_path, size)
+        if all(draw.textlength(word, font=font) <= max_width for word in words):
+            return font
+        size -= 1
+    return load_font(font_path, min_size)
+
+
+def truncate_to_width(
+    draw: ImageDraw.ImageDraw, text: str, font: ImageFont.FreeTypeFont, max_width: int,
+) -> str:
+    """Shorten `text` with an ellipsis until it fits `max_width`."""
+    if max_width <= 0 or not text:
+        return ""
+    if draw.textlength(text, font=font) <= max_width:
+        return text
+    ellipsis = "\u2026"
+    trimmed = text
+    while trimmed and draw.textlength(trimmed + ellipsis, font=font) > max_width:
+        trimmed = trimmed[:-1]
+    return (trimmed.rstrip() + ellipsis) if trimmed else ""
+
+
+def _edge_of(position: str) -> str:
+    """Which horizontal band a position sits in — top, centre or bottom.
+
+    Two overlays only compete for width when they're in the same band; one at
+    the bottom and one at the top are free to use the full frame each.
+    """
+    if position.startswith("top"):
+        return "top"
+    if position.startswith("bottom"):
+        return "bottom"
+    return "center"
+
+
+def _side_of(position: str) -> str:
+    if position.endswith("left"):
+        return "left"
+    if position.endswith("right"):
+        return "right"
+    return "center"
+
+
+def _anchor_xy(position: str, width: int, height: int, box_w: int, box_h: int, margin: int) -> Tuple[int, int]:
+    if position == "top-left":
+        return (margin, margin)
+    if position == "top-right":
+        return (width - box_w - margin, margin)
+    if position == "center":
+        return ((width - box_w) // 2, (height - box_h) // 2)
+    if position == "bottom-left":
+        return (margin, height - box_h - margin)
+    return (width - box_w - margin, height - box_h - margin)
+
+
+def card_image(
+    width: int, height: int, *,
+    title: str, subtitle: str = "",
+    background: Optional[Image.Image] = None,
+    sizes: Optional[CardTextSpec] = None,
+) -> Image.Image:
+    """A title or chapter screen: large centred text over a dimmed background.
+
+    `sizes` gives the title and subtitle as percentages of the frame height, so
+    one setting holds at every resolution and aspect ratio.
+    """
+    spec = sizes or CardTextSpec()
+    base = (background.copy() if background is not None
+            else gradient_background(width, height, ["#1e293b", "#0f172a"], 135)).convert("RGB")
+
+    # Blur and darken whatever is behind so the text always has contrast.
+    base = base.filter(ImageFilter.GaussianBlur(radius=max(6, width // 90)))
+    base = Image.blend(base, Image.new("RGB", (width, height), (0, 0, 0)), 0.45)
+
+    layer = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    title_font = load_font(SEMIBOLD, max(10, int(height * spec.title_pct / 100)))
+    sub_font = load_font(REGULAR, max(8, int(height * spec.subtitle_pct / 100)))
+    max_width = int(width * 0.82)
+
+    title_lines = wrap_text(draw, title or "", title_font, max_width)[:4]
+    sub_lines = wrap_text(draw, subtitle or "", sub_font, max_width)[:2] if subtitle else []
+
+    line_h = int(title_font.size * 1.22)
+    sub_h = int(sub_font.size * 1.35)
+    # Spacing follows the type rather than the frame, so the block stays in
+    # proportion when the sizes are turned down. The multipliers reproduce the
+    # default layout exactly.
+    gap = int(sub_font.size * 1.05) if sub_lines else 0
+    block_h = len(title_lines) * line_h + gap + len(sub_lines) * sub_h
+    y = (height - block_h) // 2
+
+    for line in title_lines:
+        w = draw.textlength(line, font=title_font)
+        draw.text(((width - w) / 2, y), line, font=title_font, fill=(255, 255, 255, 255))
+        y += line_h
+    y += gap
+    for line in sub_lines:
+        w = draw.textlength(line, font=sub_font)
+        draw.text(((width - w) / 2, y), line, font=sub_font, fill=(226, 232, 240, 230))
+        y += sub_h
+
+    # A short rule under the block, purely so a bare title doesn't float.
+    rule_w = int(width * 0.12)
+    rule_y = y + int(title_font.size * 0.75)
+    draw.rounded_rectangle(
+        [(width - rule_w) // 2, rule_y, (width + rule_w) // 2, rule_y + max(2, height // 400)],
+        radius=max(1, height // 600), fill=(129, 140, 248, 210),
+    )
+
+    return Image.alpha_composite(base.convert("RGBA"), layer).convert("RGB")
+
+
+def quote_panel(
+    width: int, height: int, *,
+    text: str, attribution: str = "", spec: Optional[QuoteSpec] = None,
+) -> Optional[Image.Image]:
+    """A pull-quote panel drawn over whatever the section is already showing.
+
+    Returns a full-frame RGBA layer so the caller can composite it into the same
+    single `overlay` input the watermark already uses, rather than adding another
+    filter to every shot. Returns None when there is nothing to draw.
+
+    The panel hugs its text rather than spanning the frame: a quotation set
+    against the left edge of a photo reads as a quotation, where a full-width
+    band reads as a subtitle.
+    """
+    body = (text or "").strip()
+    if not body:
+        return None
+    style = spec or QuoteSpec()
+
+    # Curly quotes unless the author already supplied their own — the panel has
+    # to read as speech at a glance, before anyone has begun the sentence.
+    if body[0] not in "\u201c\"\u00ab":
+        body = f"\u201c{body}\u201d"
+
+    layer = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    margin = int(min(width, height) * 0.07)
+    pad = max(8, int(height * 0.028))
+    bar_w = max(3, int(height * 0.007))
+    gap = int(pad * 0.9)
+    # What the text may occupy once the panel's own furniture is accounted for.
+    budget = max(1, width - margin * 2 - pad * 2 - bar_w - gap)
+
+    font = fit_font(draw, body, SEMIBOLD, max(8, int(height * style.size_pct / 100)), budget)
+    lines = wrap_text(draw, body, font, budget)[:8]
+    line_h = int(font.size * 1.32)
+
+    credit = (attribution or "").strip()
+    credit_font = load_font(REGULAR, max(8, int(font.size * 0.5)))
+    credit_lines: List[str] = []
+    if credit:
+        if not credit.startswith(("\u2014", "\u2013", "-")):
+            credit = f"\u2014 {credit}"
+        credit_lines = wrap_text(draw, credit, credit_font, budget)[:2]
+    credit_h = int(credit_font.size * 1.4)
+    credit_gap = int(font.size * 0.55) if credit_lines else 0
+
+    text_w = int(max((draw.textlength(l, font=font) for l in lines), default=0))
+    if credit_lines:
+        text_w = max(text_w, int(max(draw.textlength(l, font=credit_font) for l in credit_lines)))
+    panel_w = min(width - margin * 2, pad * 2 + bar_w + gap + text_w)
+    panel_h = pad * 2 + line_h * len(lines) + credit_gap + credit_h * len(credit_lines)
+
+    if style.position == "top":
+        panel_y = margin
+    elif style.position == "bottom":
+        panel_y = max(0, height - panel_h - margin)
+    else:
+        panel_y = max(0, (height - panel_h) // 2)
+    panel_x = margin
+
+    scrim = max(0.0, min(1.0, style.scrim))
+    if scrim > 0.01:
+        draw.rounded_rectangle(
+            [panel_x, panel_y, panel_x + panel_w, panel_y + panel_h],
+            radius=max(4, int(height * 0.018)), fill=(0, 0, 0, int(255 * scrim)),
+        )
+    draw.rounded_rectangle(
+        [panel_x + pad, panel_y + pad, panel_x + pad + bar_w, panel_y + panel_h - pad],
+        radius=max(1, bar_w // 2), fill=(*parse_colour(style.accent, (129, 140, 248)), 255),
+    )
+
+    colour = parse_colour(style.color, (255, 255, 255))
+    x = panel_x + pad + bar_w + gap
+    y = panel_y + pad
+    for line in lines:
+        draw.text((x, y), line, font=font, fill=(*colour, 255))
+        y += line_h
+    y += credit_gap
+    for line in credit_lines:
+        draw.text((x, y), line, font=credit_font, fill=(226, 232, 240, 225))
+        y += credit_h
+
+    return layer
+
+
+def code_panel(
+    width: int, height: int, *, text: str, spec: Optional[CodeSpec] = None,
+) -> Optional[Image.Image]:
+    """A code panel drawn over whatever the shot is already showing — the same
+    idea as `quote_panel`, but for a code block.
+
+    Lines are never reflowed the way quote_panel wraps prose: word-wrapping a
+    line of code would scramble its indentation and structure. An over-wide
+    line is truncated with an ellipsis instead, and the block is capped to as
+    many lines as comfortably fit at the configured size rather than shrinking
+    the type to squeeze more in — a code block that doesn't fit is meant to be
+    trimmed by whoever wrote it, not silently minified.
+
+    Returns a full-frame RGBA layer, same as quote_panel, so the caller can
+    composite it into the single `overlay` input a shot already uses. Returns
+    None when there is nothing to draw.
+    """
+    body = (text or "").rstrip("\n")
+    if not body.strip():
+        return None
+    style = spec or CodeSpec()
+
+    layer = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    margin = int(min(width, height) * 0.07)
+    pad = max(10, int(height * 0.03))
+    font = load_font(MONO_REGULAR, max(8, int(height * style.size_pct / 100)), fallbacks=_MONO_FALLBACKS)
+    line_h = int(font.size * 1.5)
+    budget = max(1, width - margin * 2 - pad * 2)
+
+    lines = body.splitlines() or [""]
+    max_lines = max(1, (height - margin * 2 - pad * 2) // line_h)
+    shown = lines[:max_lines]
+    if len(lines) > max_lines and shown:
+        shown[-1] = truncate_to_width(draw, shown[-1] + " …", font, budget) or "…"
+    shown = [truncate_to_width(draw, line, font, budget) for line in shown]
+
+    text_w = int(max((draw.textlength(line, font=font) for line in shown), default=0))
+    panel_w = min(width - margin * 2, pad * 2 + text_w)
+    panel_h = pad * 2 + line_h * len(shown)
+
+    if style.position == "top":
+        panel_y = margin
+    elif style.position == "bottom":
+        panel_y = max(0, height - panel_h - margin)
+    else:
+        panel_y = max(0, (height - panel_h) // 2)
+    panel_x = margin
+
+    scrim = max(0.0, min(1.0, style.scrim))
+    if scrim > 0.01:
+        draw.rounded_rectangle(
+            [panel_x, panel_y, panel_x + panel_w, panel_y + panel_h],
+            radius=max(4, int(height * 0.018)), fill=(15, 23, 42, int(255 * scrim)),
+        )
+
+    colour = parse_colour(style.color, (226, 232, 240))
+    x = panel_x + pad
+    y = panel_y + pad
+    for line in shown:
+        draw.text((x, y), line or " ", font=font, fill=(*colour, 255))
+        y += line_h
+
+    return layer
+
+
+# In "title + chapter" mode the chapter line reads as a subheading, so it is
+# drawn a bit smaller than the title rather than at the same weight.
+CHAPTER_OVERLAY_SIZE_RATIO = 0.72
+
+
+def _overlay_text_blocks(
+    draw: ImageDraw.ImageDraw, overlay_text: OverlayTextSpec, chapter_line: Optional[str],
+    height: int, max_width: int,
+) -> List[Tuple[str, ImageFont.FreeTypeFont]]:
+    """Wrap the overlay's title (and optional chapter) line into (text, font) pairs.
+
+    Each block is fitted and wrapped independently, so the chapter line — when
+    present — gets its own, smaller font rather than sharing the title's.
+    """
+    blocks: List[Tuple[str, ImageFont.FreeTypeFont]] = []
+    title = (overlay_text.text or "").strip()
+    if title:
+        font = fit_font(draw, title, SEMIBOLD, max(8, int(height * overlay_text.size_pct / 100)), max_width)
+        blocks.extend((line, font) for line in wrap_text(draw, title, font, max_width)[:4])
+    chapter = (chapter_line or "").strip()
+    if chapter:
+        chapter_pct = overlay_text.size_pct * CHAPTER_OVERLAY_SIZE_RATIO
+        font = fit_font(draw, chapter, SEMIBOLD, max(8, int(height * chapter_pct / 100)), max_width)
+        blocks.extend((line, font) for line in wrap_text(draw, chapter, font, max_width)[:2])
+    return blocks
+
+
+def overlay_layer(
+    width: int, height: int, *,
+    watermark: WatermarkSpec, watermark_icon: Optional[str],
+    overlay_text: OverlayTextSpec, chapter_line: Optional[str] = None,
+) -> Optional[Image.Image]:
+    """One full-frame RGBA layer carrying the watermark and the fixed text.
+
+    Composing both into a single PNG means ffmpeg applies one `overlay` per shot
+    instead of a chain of scale/overlay/drawtext filters. `chapter_line`, when
+    given, is drawn under `overlay_text.text` at a smaller size — the video's
+    current chapter, in "title + chapter" mode.
+    """
+    wants_watermark = watermark.enabled and (watermark_icon or watermark.text.strip())
+    wants_text = overlay_text.enabled and (overlay_text.text.strip() or (chapter_line or "").strip())
+    if not wants_watermark and not wants_text:
+        return None
+
+    layer = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+
+    # An overlay only has to share the frame's width when something else sits in
+    # the same band. Alone on the bottom edge it gets the whole bottom edge, and
+    # only wraps when the text genuinely doesn't fit across it.
+    shares_edge = (
+        wants_watermark and wants_text
+        and _edge_of(overlay_text.position) == _edge_of(watermark.position)
+    )
+    # ...and if they're also on the same side, splitting the width wouldn't
+    # separate them at all, so the watermark is stacked clear of the text instead.
+    stacked = shares_edge and _side_of(overlay_text.position) == _side_of(watermark.position)
+
+    def _budget(margin: int, taken: int = 0) -> int:
+        usable = width - margin * 2 - taken
+        if shares_edge and not stacked:
+            usable = (usable - margin) // 2
+        return max(1, usable)
+
+    # Where the fixed text ended up, so a stacked watermark can avoid it.
+    text_rect: Optional[Tuple[int, int, int, int]] = None
+
+    if wants_text:
+        margin = int(min(width, height) * max(0, min(25, overlay_text.margin_pct)) / 100)
+        colour = parse_colour(overlay_text.color, (255, 255, 255))
+        text_budget = _budget(margin)
+        blocks = _overlay_text_blocks(draw, overlay_text, chapter_line, height, text_budget)
+        box_w = int(max((draw.textlength(l, font=f) for l, f in blocks), default=0))
+        box_h = sum(int(f.size * 1.3) for _, f in blocks)
+        x, y = _anchor_xy(overlay_text.position, width, height, box_w, box_h, margin)
+        text_rect = (x, y, box_w, box_h)
+        for line, font in blocks:
+            line_h = int(font.size * 1.3)
+            lw = draw.textlength(line, font=font)
+            # Right-aligned corners look wrong if the wrapped lines are ragged left.
+            lx = x + (box_w - lw) if overlay_text.position.endswith("right") else x
+            lx = x + (box_w - lw) / 2 if overlay_text.position == "center" else lx
+            if overlay_text.shadow:
+                off = max(1, font.size // 18)
+                draw.text((lx + off, y + off), line, font=font, fill=(0, 0, 0, 150))
+            draw.text((lx, y), line, font=font, fill=(*colour, 255))
+            y += line_h
+
+    if wants_watermark:
+        margin = int(min(width, height) * max(0, min(25, watermark.margin_pct)) / 100)
+        icon: Optional[Image.Image] = None
+        icon_h = max(2, int(height * watermark.scale_pct / 100))
+        if watermark_icon:
+            try:
+                with Image.open(watermark_icon) as raw:
+                    raw = ImageOps.exif_transpose(raw).convert("RGBA")
+                    ratio = raw.width / raw.height if raw.height else 1
+                    icon = raw.resize((max(1, int(icon_h * ratio)), icon_h), Image.LANCZOS)
+            except (UnidentifiedImageError, OSError, ValueError) as exc:
+                logger.warning("Could not load watermark icon %s: %s", watermark_icon, exc)
+
+        caption = watermark.text.strip()
+        # Sized off the frame rather than off the icon, so the two can be
+        # balanced independently — a large mark beside small type, or the reverse.
+        font = load_font(REGULAR, max(8, int(height * watermark.caption_pct / 100)))
+        # A caption defaulting to the note title can easily be wider than a 9:16
+        # frame, so it is trimmed to whatever width this edge actually offers.
+        icon_w = icon.width if icon is not None else 0
+        gap = int(icon_h * 0.35) if (icon is not None and caption) else 0
+        caption = truncate_to_width(draw, caption, font, _budget(margin, icon_w + gap))
+        cap_w = int(draw.textlength(caption, font=font)) if caption else 0
+        if not caption:
+            gap = 0
+        box_w = icon_w + gap + cap_w
+        box_h = max(icon_h if icon is not None else 0, font.size)
+        x, y = _anchor_xy(watermark.position, width, height, box_w, box_h, margin)
+
+        if stacked and text_rect is not None:
+            # Same edge and same side as the fixed text: sit clear of it rather
+            # than on top of it. Bottom stacks upward, everything else downward.
+            tx, ty, _tw, th = text_rect
+            spacing = max(4, int(height * 0.012))
+            y = ty - box_h - spacing if _edge_of(watermark.position) == "bottom" else ty + th + spacing
+            y = max(0, min(height - box_h, y))
+
+        mark = Image.new("RGBA", (max(1, box_w), max(1, box_h)), (0, 0, 0, 0))
+        mdraw = ImageDraw.Draw(mark)
+        cursor = 0
+        if icon is not None:
+            mark.paste(icon, (0, (box_h - icon.height) // 2), icon)
+            cursor = icon.width + gap
+        if caption:
+            ty = (box_h - font.size) // 2
+            off = max(1, font.size // 16)
+            mdraw.text((cursor + off, ty + off), caption, font=font, fill=(0, 0, 0, 140))
+            mdraw.text((cursor, ty), caption, font=font, fill=(255, 255, 255, 255))
+
+        alpha = max(0.05, min(1.0, watermark.opacity))
+        if alpha < 0.999:
+            mark.putalpha(mark.getchannel("A").point(lambda v: int(v * alpha)))
+        layer.alpha_composite(mark, (max(0, x), max(0, y)))
+
+    return layer
diff --git a/backend/app/render/estimate.py b/backend/app/render/estimate.py
new file mode 100644
index 0000000..7cfc3c9
--- /dev/null
+++ b/backend/app/render/estimate.py
@@ -0,0 +1,72 @@
+"""What a render would cost and whether it can run, worked out without running it.
+
+No network and no ffmpeg: the editor asks on every change to say "about 3 minutes,
+1,840 characters of narration" and which placeholders would stop a full render. The
+length is a reading-rate guess (Notes' figure: about fifteen characters a second); the
+render measures the real thing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from app.render.compile import beat_pause_ms
+from app.render.media import used_keys
+from app.spec.model import GeneratedAsset, NotesAsset, SearchAsset, VideoSpec
+
+CHARS_PER_SECOND = 15.0
+
+
+@dataclass
+class Estimate:
+    seconds: float
+    narration_chars: int
+    # Unknown clip lengths make `seconds` a floor rather than a guess.
+    seconds_is_floor: bool = False
+    # What stops a full render, and what stops even a preview.
+    blocks_render: List[str] = field(default_factory=list)
+    blocks_preview: List[str] = field(default_factory=list)
+
+
+def estimate(spec: VideoSpec) -> Estimate:
+    used = used_keys(spec)
+    out = Estimate(seconds=0.0, narration_chars=0)
+    for key in sorted(used):
+        ref = spec.assets[key]
+        if isinstance(ref, NotesAsset):
+            message = f"“{ref.label or ref.url}” is still in the note: copy the note's files into GAM."
+            out.blocks_render.append(message)
+            out.blocks_preview.append(message)
+        elif isinstance(ref, SearchAsset) and ref.result is None:
+            out.blocks_render.append(f"Footage still to find: “{ref.query}”.")
+        elif isinstance(ref, GeneratedAsset) and ref.result is None:
+            out.blocks_render.append(f"Still to generate: “{ref.prompt}”.")
+    if not spec.segments:
+        out.blocks_render.append("There is nothing in this video yet.")
+        out.blocks_preview.append("There is nothing in this video yet.")
+
+    for segment in spec.segments:
+        speed = (segment.narration.voice.speed if segment.narration and segment.narration.voice
+                 and segment.narration.voice.speed else spec.voice.speed)
+        beats = segment.beats
+        chars = sum(len(b.text) for b in beats if b.speak)
+        out.narration_chars += chars
+        spoken = chars / CHARS_PER_SECOND / max(0.5, speed)
+        spoken += sum(beat_pause_ms(spec, beats, i) for i in range(len(beats))) / 1000.0
+        if segment.duration and segment.duration.fixed:
+            out.seconds += segment.duration.fixed
+        elif segment.kind == "card":
+            out.seconds += max(spec.style.cards.seconds, spoken)
+        elif segment.kind == "clip":
+            trim = segment.visual.trim if segment.visual else None
+            if trim and trim.out is not None:
+                out.seconds += trim.out - trim.in_
+            else:
+                out.seconds_is_floor = True
+        else:
+            floor = (segment.duration.min if segment.duration and segment.duration.min
+                     else spec.style.min_segment_seconds)
+            out.seconds += max(floor, spoken)
+    out.seconds = round(out.seconds, 1)
+    return out
diff --git a/backend/app/render/ffmpeg.py b/backend/app/render/ffmpeg.py
new file mode 100644
index 0000000..8367ddd
--- /dev/null
+++ b/backend/app/render/ffmpeg.py
@@ -0,0 +1,1122 @@
+"""ffmpeg/ffprobe argv builders and process helpers.
+
+Every builder is a pure function returning a `list[str]`, so the filtergraphs can
+be asserted in unit tests without running ffmpeg — the same approach the repo
+already takes for the URL importer's parsers.
+
+The one invariant the whole pipeline rests on: every shot is encoded with
+byte-identical codec parameters (see `encode_args`), which is what lets the final
+stitch be a `concat -c copy` remux instead of a second full encode. A stray SAR
+or pixel format is the usual way that silently breaks, so every video chain ends
+with `setsar=1,format=yuv420p`.
+"""
+
+import logging
+import math
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from app.render.options import (
+    DIP_TRANSITIONS, KENBURNS_MIN_LEG_SECONDS, XFADE_NAMES, MusicSpec, TransitionSpec,
+    RenderOptions, encoder_tier, frame_size, is_crossfade, kenburns_geometry,
+    transition_colour,
+)
+
+logger = logging.getLogger(__name__)
+
+# Long enough for a 4K encode of a multi-minute clip, short enough that a wedged
+# process can't hold the render queue forever. Mirrors transcription.py's style.
+# A flat per-shot cap is wrong, because a shot is not a fixed amount of work: a
+# three-second card and an eight-minute still both used to get 900 seconds, and
+# the second one cannot possibly finish in it. These bound a shot by how long it
+# actually is, with the old value as the floor so short shots are unaffected.
+SHOT_TIMEOUT_SECONDS = 900
+SHOT_TIMEOUT_FACTOR = 6
+SHOT_TIMEOUT_CEILING = 2 * 60 * 60
+PROBE_TIMEOUT_SECONDS = 30
+
+# An xfade stitch puts every shot in one filtergraph as its own input. That is
+# fine for the ten to thirty shots a normal article produces and absurd at the
+# 200 VIDEO_MAX_SHOTS ceiling, so past this many the render degrades to a plain
+# concat rather than building a graph that would thrash the box.
+XFADE_MAX_SHOTS = 60
+
+# An overlap shorter than this isn't a transition, it's a glitch.
+MIN_TRANSITION_SECONDS = 0.05
+
+# Deterministic rotation for the "alternate" Ken Burns effect. Keyed off the shot
+# index rather than a random draw so re-rendering a note is reproducible.
+KENBURNS_CYCLE = ("zoom_in", "pan_right", "zoom_out", "pan_left")
+
+
+class FFmpegError(RuntimeError):
+    pass
+
+
+def ffmpeg_available() -> bool:
+    return bool(shutil.which("ffmpeg")) and bool(shutil.which("ffprobe"))
+
+
+_filter_cache: Optional[frozenset] = None
+
+
+def available_filters() -> frozenset:
+    """Filters this ffmpeg build actually has, probed once and cached.
+
+    Debian's build carries everything we use, but a slimmer base image might not,
+    and discovering that four minutes into a render is a bad way to find out.
+    Callers degrade (waveform off, burn-in falls back to a sidecar) instead.
+    """
+    global _filter_cache
+    if _filter_cache is not None:
+        return _filter_cache
+    names = set()
+    try:
+        out = subprocess.run(["ffmpeg", "-hide_banner", "-filters"],
+                             capture_output=True, timeout=PROBE_TIMEOUT_SECONDS)
+        for line in out.stdout.decode(errors="replace").splitlines():
+            parts = line.split()
+            # Rows look like: " T.. showwaves  A->V  Convert input audio to ..."
+            if len(parts) >= 3 and not line.startswith("Filters:"):
+                names.add(parts[1])
+    except Exception as exc:
+        logger.warning("Could not probe ffmpeg filters: %s", exc)
+    _filter_cache = frozenset(names)
+    return _filter_cache
+
+
+def shot_timeout(duration: float) -> int:
+    """How long one shot may take to encode, given how long the shot is.
+
+    Encoding runs slower than real time once a filter chain and a slow x264
+    preset are involved, so the budget is a multiple of the shot's length rather
+    than a constant — with the old flat value as a floor, so nothing short gets
+    less than it had.
+    """
+    scaled = max(0.0, duration) * SHOT_TIMEOUT_FACTOR
+    return int(min(SHOT_TIMEOUT_CEILING, max(SHOT_TIMEOUT_SECONDS, scaled)))
+
+
+def run(argv: Sequence[str], *, cwd: Optional[str] = None, timeout: int = SHOT_TIMEOUT_SECONDS) -> None:
+    """Run ffmpeg, raising FFmpegError with something readable on failure.
+
+    A timeout is converted here rather than left to propagate. `TimeoutExpired`
+    stringifies as the entire argv followed by the reason, which runs past a
+    thousand characters — so by the time the worker truncates it for the UI the
+    reason has been cut off the end and all the user sees is a severed command
+    line. The original is chained, so the full argv still reaches the log, which
+    is where it is actually useful.
+    """
+    try:
+        result = subprocess.run(list(argv), capture_output=True, timeout=timeout, cwd=cwd)
+    except subprocess.TimeoutExpired as exc:
+        raise FFmpegError(
+            f"ffmpeg gave up on a segment after {timeout}s. It is probably a very "
+            f"long section on one image — try a lower resolution or a faster "
+            f"encoding preset."
+        ) from exc
+    if result.returncode != 0:
+        stderr = result.stderr.decode(errors="replace")
+        tail = stderr[-800:].strip()
+        code = result.returncode
+        # `-loglevel error` means a process killed from outside says nothing at
+        # all, so the exit status is the only clue that it was the OOM killer.
+        if code < 0:
+            reason = f"killed by signal {-code}"
+            if code == -9:
+                reason += " (most likely out of memory)"
+        else:
+            reason = f"exit code {code}"
+        logger.error("ffmpeg %s\nargv: %s\nstderr: %s", reason, " ".join(argv), stderr or "<empty>")
+        raise FFmpegError(f"ffmpeg failed ({reason}): {tail}".rstrip(": "))
+
+
+def probe_duration(path: str) -> float:
+    """Container duration in seconds, or 0.0 if it can't be read."""
+    try:
+        out = subprocess.run(
+            ["ffprobe", "-v", "error", "-show_entries", "format=duration",
+             "-of", "csv=p=0", path],
+            capture_output=True, timeout=PROBE_TIMEOUT_SECONDS,
+        )
+        return float((out.stdout.decode(errors="replace").strip() or "0") or 0)
+    except (ValueError, OSError, subprocess.SubprocessError):
+        return 0.0
+
+
+def probe_has_audio(path: str) -> bool:
+    """True when the file carries at least one audio stream.
+
+    This is the test that decides whether a clip plays with its own sound (and
+    pauses the narration) or is looped silently as a background.
+    """
+    try:
+        out = subprocess.run(
+            ["ffprobe", "-v", "error", "-select_streams", "a",
+             "-show_entries", "stream=codec_type", "-of", "csv=p=0", path],
+            capture_output=True, timeout=PROBE_TIMEOUT_SECONDS,
+        )
+        return "audio" in out.stdout.decode(errors="replace")
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+def encode_args(options: RenderOptions, preview: bool) -> List[str]:
+    """Codec flags shared by every shot. Identical output = concat can `-c copy`."""
+    preset, crf = encoder_tier(options.quality, preview)
+    fps = options.fps
+    return [
+        "-c:v", "libx264", "-preset", preset, "-crf", str(crf),
+        "-pix_fmt", "yuv420p", "-profile:v", "high", "-level", "4.1",
+        "-r", str(fps), "-g", str(fps * 2), "-keyint_min", str(fps),
+        "-video_track_timescale", "90000",
+        "-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2",
+        "-max_muxing_queue_size", "1024",
+    ]
+
+
+def _hex_to_ffmpeg(colour: str) -> str:
+    """'#00FF41' -> '0x00FF41'. Falls back to white on anything unparseable."""
+    c = (colour or "").strip().lstrip("#")
+    if len(c) == 8:  # RGBA from a colour picker — drop the alpha, we set it separately
+        c = c[:6]
+    if len(c) == 3:
+        c = "".join(ch * 2 for ch in c)
+    if len(c) != 6 or any(ch not in "0123456789abcdefABCDEF" for ch in c):
+        return "0xffffff"
+    return f"0x{c.lower()}"
+
+
+def fit_chain(src: str, out: str, width: int, height: int, fit: str) -> str:
+    """Scale arbitrary media into the output frame.
+
+    blur — a scaled-up, blurred copy fills the frame with the real media
+           contained and centred on top. Never crops, and reads as deliberate at
+           every aspect ratio, which matters most for 9:16 where article images
+           are almost always the wrong shape.
+    pad  — letterbox against black.
+    crop — fill the frame and lose the edges.
+    """
+    if fit == "crop":
+        return (f"[{src}]scale={width}:{height}:force_original_aspect_ratio=increase,"
+                f"crop={width}:{height},setsar=1[{out}]")
+    if fit == "pad":
+        return (f"[{src}]scale={width}:{height}:force_original_aspect_ratio=decrease,"
+                f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1[{out}]")
+    sigma = max(8, width // 40)
+    return (
+        f"[{src}]split[{out}_a][{out}_b];"
+        f"[{out}_a]scale={width}:{height}:force_original_aspect_ratio=increase,"
+        f"crop={width}:{height},gblur=sigma={sigma},eq=brightness=-0.08[{out}_bg];"
+        f"[{out}_b]scale={width}:{height}:force_original_aspect_ratio=decrease[{out}_fg];"
+        f"[{out}_bg][{out}_fg]overlay=(W-w)/2:(H-h)/2:shortest=1,setsar=1[{out}]"
+    )
+
+
+def waveform_chain(
+    audio_src: str, video_src: str, out: str,
+    width: int, height: int, fps: int, spec,
+) -> str:
+    """Animated showwaves band composited over the background.
+
+    Two details matter: `rate` must equal the output frame rate or the wave
+    drifts against the picture, and the alpha is set once — the reference
+    formula's repeated colorchannelmixer passes collapse to a single value.
+    """
+    band = max(24, int(height * max(5, min(60, spec.height_pct)) / 100))
+    band -= band % 2
+    if spec.position == "top":
+        y = 0
+    elif spec.position == "center":
+        y = (height - band) // 2
+    else:
+        y = height - band
+    alpha = max(0.05, min(1.0, spec.opacity))
+    colour = _hex_to_ffmpeg(spec.color)
+
+    parts = [
+        f"[{audio_src}]aformat=channel_layouts=mono,"
+        f"showwaves=s={width}x{band}:mode={spec.mode}:draw=full:scale=sqrt:"
+        f"rate={fps}:colors={colour},format=rgba,"
+        f"colorchannelmixer=aa={alpha}[{out}_w]"
+    ]
+    base = video_src
+    scrim = max(0.0, min(1.0, spec.scrim))
+    if scrim > 0.01:
+        parts.append(
+            f"[{base}]drawbox=x=0:y={y}:w={width}:h={band}:"
+            f"color=black@{scrim}:t=fill[{out}_s]"
+        )
+        base = f"{out}_s"
+    parts.append(f"[{base}][{out}_w]overlay=0:{y}[{out}]")
+    return ";".join(parts)
+
+
+def _even(value: float) -> int:
+    """Round down to an even integer — libx264 with yuv420p requires it."""
+    n = max(2, int(value))
+    return n - n % 2
+
+
+def kenburns_effect_for(kind: str, index: int, options: RenderOptions) -> Optional[str]:
+    """Which drift, if any, this shot gets.
+
+    A video background already moves, so only stills and (opt-in) cards drift. A
+    card has its text drawn into the picture, so it is only ever allowed to zoom
+    from the centre — a pan would walk the type out of frame.
+
+    Every qualifying shot gets its drift regardless of how long it runs — a shot
+    long enough that one sweep across it would be too slow to see gets the drift
+    cycled by `kenburns_sweep` instead of dropped.
+    """
+    effect = options.ken_burns.effect
+    if effect == "none":
+        return None
+    if kind == "card":
+        if not options.ken_burns.include_cards:
+            return None
+    elif kind != "still":
+        return None
+
+    if effect == "alternate":
+        effect = KENBURNS_CYCLE[index % len(KENBURNS_CYCLE)]
+    if kind == "card" and effect.startswith("pan"):
+        return "zoom_in"
+    return effect
+
+
+def kenburns_sweep(travel: int, frames: int, fps: int) -> Tuple[str, str]:
+    """(rising, falling) crop-origin expressions, in whole read pixels.
+
+    `travel` is the headroom zoompan will clamp the origin against, counted in
+    the very pixels it truncates to, and `frames` is the length of the shot.
+    Both expressions run between 0 and `travel`, one upwards and one down, and
+    every effect is built out of that pair.
+
+    The invariant this exists to hold: **the truncated origin has to land on a
+    different pixel from one frame to the next.** A pan holds its zoom, so the
+    crop is the same size on every frame — an origin that rounds to the value it
+    had last frame makes zoompan emit a picture identical to the one before it,
+    and at less than a pixel a frame that happens on half of them. Those
+    duplicates are the stutter. They are also not evenly spread: which frames
+    repeat is decided by the fractional part of the rate, so the freezes cluster
+    and thin out on a slow beat against the frame rate — a 16-24 second section
+    at the default 12% drift beat about every two seconds, which is what "it
+    pauses every so often" was.
+
+    So the rate is never allowed below a pixel a frame:
+
+    fast enough   one sweep across the whole travel, `travel*on/frames`, which
+                  advances one pixel or two on every frame and repeats none;
+    too slow      the sweep rubber-bands, A to B to A, across `travel` frames —
+                  exactly a pixel a frame, the slowest this can go, and the only
+                  perfectly even rate available;
+    slower still  when even that leg would be over in a few seconds — only a
+                  very small `amount` has that little travel — reversing that
+                  often would read as a wobble, so the sweep holds each pixel
+                  for a fixed number of frames instead. It still steps, but on a
+                  cadence that never beats, and it crosses nearly all of the
+                  travel without reversing at all.
+
+    No expression here contains a comma or a colon, which is what keeps the
+    filtergraph free of any escaping: `on mod period` is written out as `on -
+    period*floor(on/period)` and the triangle's peak with `abs`, because
+    ffmpeg's own `mod()` and `min()` take comma-separated arguments.
+    """
+    travel, frames = max(1, travel), max(1, frames)
+    if frames <= travel:
+        return f"{travel}*on/{frames}", f"{travel}*(1-on/{frames})"
+
+    if travel >= KENBURNS_MIN_LEG_SECONDS * max(1, fps):
+        # A triangle of period 2*travel, counted in pixels because each frame is
+        # worth exactly one: 0 at on=0, `travel` at on=travel, back to 0 at
+        # on=2*travel, repeating.
+        period = 2 * travel
+        phase = f"(on-{period}*floor(on/{period}))"
+        return f"({travel}-abs({phase}-{travel}))", f"abs({phase}-{travel})"
+
+    hold = -(-frames // travel)          # ceil: frames spent on each pixel
+    used = min(travel, frames // hold)
+    lead = (travel - used) // 2          # centre the short sweep in its headroom
+    tick = f"floor(on/{hold})"
+    return (f"{lead}+{tick}" if lead else tick), f"{lead + used}-{tick}"
+
+
+def kenburns_chain(
+    src: str, out: str, *,
+    width: int, height: int, fps: int, duration: float,
+    effect: str, amount: float,
+) -> str:
+    """A `zoompan` drift over a still, rendered above `width`x`height` and scaled back.
+
+    `width`/`height` are the output frame; the caller must have fitted the source
+    at `kenburns_geometry`'s read size, which is what makes this smooth. zoompan
+    truncates its crop origin to whole pixels of the frame it is given, so
+    reading a much larger picture, and writing one larger than the frame before
+    scaling down, are what turn a whole-pixel step into a third of one.
+
+    Everything below is therefore worked out in those same whole read pixels
+    rather than in fractions of the frame: the crop zoompan will take, the
+    headroom left over, and the sweep across it. `kenburns_sweep` holds the rule
+    that keeps it gliding — never less than one of those pixels per frame.
+
+    A zoom drives the crop's *width* along that sweep rather than the zoom
+    factor, and `z` is written as the ratio that produces it. Ramping `z`
+    linearly instead would accelerate the picture across the shot (the crop is
+    `iw/z`, not `z`), and would leave the width free to round to the same value
+    twice running, which on a zoom is the same duplicate frame a pan gets. The
+    half pixel in the divisor puts `iw/z` at the middle of the intended width
+    rather than on its boundary, so the truncation can't be tipped either way by
+    the last bit of the division.
+
+    `zoompan` restarts its ramp every `d` output frames while `-loop 1` feeds
+    frames forever, so `d` is set a couple of frames beyond the shot and the
+    caller's `-t` cuts before the ramp can begin again.
+    """
+    read_width, read_height, write_width, write_height = kenburns_geometry(width, height)
+    frames = max(1, int(math.ceil(max(0.1, duration) * max(1, fps))))
+    # What is read is the only headroom the zoom has; travelling past it would
+    # start magnifying pixels, which is the softness this arrangement avoids.
+    span = max(0.01, min(amount, read_width / max(1, width) - 1.0))
+    # Rounded to the text ffmpeg will parse and read back, so the crop worked
+    # out here is the crop ffmpeg computes, to the pixel.
+    zoom_text = f"{1.0 + span:.4f}"
+    zoom = float(zoom_text)
+
+    # Exactly what zoompan will do: crop int(iw/zoom) x int(ih/zoom), and clamp
+    # the origin to whatever is left of the frame.
+    crop_width = max(1, int(read_width / zoom))
+    crop_height = max(1, int(read_height / zoom))
+    vertical = effect in ("pan_up", "pan_down")
+    travel = max(1, (read_height - crop_height) if vertical
+                 else (read_width - crop_width))
+    rise, fall = kenburns_sweep(travel, frames, fps)
+
+    if effect == "zoom_out":
+        # Opens out from the tightest crop and lands on the picture 1:1.
+        z = f"{read_width}/({crop_width}+0.5+{rise})"
+    elif effect.startswith("pan"):
+        z = zoom_text
+    else:  # zoom_in and anything unrecognised
+        z = f"{read_width}/({read_width}+0.5-{rise})"
+
+    # A pan sweeps one axis end to end and pins the other dead centre — as a
+    # number, not an expression, so nothing on it can move at all. A zoom has no
+    # axis to sweep and stays centred on both, which it can only do against the
+    # crop it is about to take.
+    if effect == "pan_left":
+        x, y = fall, str((read_height - crop_height) // 2)
+    elif effect == "pan_right":
+        x, y = rise, str((read_height - crop_height) // 2)
+    elif effect == "pan_up":
+        x, y = str((read_width - crop_width) // 2), fall
+    elif effect == "pan_down":
+        x, y = str((read_width - crop_width) // 2), rise
+    else:
+        x, y = "iw/2-(iw/zoom/2)", "ih/2-(ih/zoom/2)"
+
+    chain = (f"[{src}]zoompan=z={z}:x={x}:y={y}:"
+             f"d={frames + 2}:s={write_width}x{write_height}:fps={fps}")
+    if (write_width, write_height) != (width, height):
+        # Scaling back down halves whatever step survived and averages it away.
+        chain += f",scale={width}:{height}"
+    return f"{chain}[{out}]"
+
+
+def dip_seconds(style: str, requested: float, shot_duration: float) -> float:
+    """How long a dip-through-colour transition may last on a shot this short.
+
+    A shot has to hold a fade out as well as a fade in, so a third of its length
+    is the ceiling; below that the two would overlap and the picture would never
+    be fully visible.
+    """
+    if style not in DIP_TRANSITIONS:
+        return 0.0
+    seconds = min(max(0.0, requested), max(0.0, shot_duration) / 3.0)
+    return seconds if seconds >= MIN_TRANSITION_SECONDS else 0.0
+
+
+def crossfade_overlap(
+    style: str, durations: Sequence[float], requested: float,
+    *, filters: Optional[frozenset] = None,
+) -> Optional[float]:
+    """The overlap an xfade stitch should use, or None to fall back to concat.
+
+    Every reason a crossfade can't run lives here so the renderer branches once
+    and the guards can be tested without ffmpeg: the style isn't a blend, there
+    is nothing to blend between, the graph would be unreasonably large, the host
+    ffmpeg lacks the filters, or the shots are too short to absorb an overlap.
+    """
+    if not is_crossfade(style) or len(durations) < 2:
+        return None
+    if len(durations) > XFADE_MAX_SHOTS:
+        return None
+    names = available_filters() if filters is None else filters
+    if "xfade" not in names or "concat" not in names:
+        return None
+    overlap = min(max(0.0, requested), 0.5 * min(durations))
+    return overlap if overlap >= MIN_TRANSITION_SECONDS else None
+
+
+def build_shot_command(
+    *,
+    kind: str,
+    background: Optional[str],
+    audio: Optional[str],
+    duration: float,
+    output: str,
+    options: RenderOptions,
+    preview: bool,
+    overlay_png: Optional[str] = None,
+    subtitle_file: Optional[str] = None,
+    background_has_audio: bool = False,
+    index: int = 0,
+    dip_in: bool = True,
+    dip_out: bool = True,
+    in_transition: Optional[TransitionSpec] = None,
+    out_transition: Optional[TransitionSpec] = None,
+    loop: bool = True,
+    path: Optional["KenBurnsPath"] = None,
+) -> List[str]:
+    """Full argv for rendering one shot to its own MP4.
+
+    Paths are expected to be relative to the working directory the caller runs
+    this in, which keeps the `subtitles=` filter free of any escaping.
+    `dip_in`/`dip_out` False leave a dip transition off that end of the shot,
+    where it joins a neighbour by a straight cut (see `Shot.cut_in`).
+
+    GVC additions, all defaulting to Notes' behaviour:
+    - `in_transition` / `out_transition`: the join at each end, which in GVC differ
+      per scene (a scene's `transition_in` is its incoming join and the previous
+      scene's outgoing one). Unset, both are `options.transition`.
+    - `loop` False on a muted video holds its last frame instead of repeating it.
+    - `path`: a Ken Burns move between two frames of the picture (S1), in place of
+      the preset drift.
+    """
+    width, height = frame_size(options.aspect, options.resolution, preview)
+    argv: List[str] = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"]
+
+    # ── inputs ────────────────────────────────────────────────────────────────
+    if kind in ("still", "card"):
+        argv += ["-loop", "1", "-framerate", str(options.fps), "-i", background or ""]
+    elif kind == "video_muted":
+        # Loop the clip for as long as the narration runs, and cut the moment it
+        # ends — the two halves of the spec's rule fall out of these flags.
+        if loop:
+            argv += ["-stream_loop", "-1"]
+        argv += ["-i", background or ""]
+    else:  # video_sound
+        argv += ["-i", background or ""]
+
+    video_in = "0:v"
+    audio_in: Optional[str] = None
+    next_index = 1
+
+    if kind == "video_sound":
+        if background_has_audio:
+            audio_in = "0:a"
+        else:
+            argv += ["-f", "lavfi", "-i", "anullsrc=channel_layout=stereo:sample_rate=48000"]
+            audio_in = f"{next_index}:a"
+            next_index += 1
+    else:
+        argv += ["-i", audio or ""]
+        audio_in = f"{next_index}:a"
+        next_index += 1
+
+    overlay_index: Optional[int] = None
+    if overlay_png:
+        argv += ["-i", overlay_png]
+        overlay_index = next_index
+        next_index += 1
+
+    # ── filtergraph ───────────────────────────────────────────────────────────
+    filters = available_filters()
+
+    # A drifting shot is fitted larger than the output frame so `zoompan` has
+    # real pixels to zoom into, and zoompan's own `s=` brings it back down.
+    # Fitting at the output size first would just magnify its softness.
+    drift = (kenburns_effect_for(kind, index, options)
+             if "zoompan" in filters and path is None else None)
+    if path is not None and kind == "still" and "zoompan" in filters:
+        read_width, read_height, _w, _h = kenburns_geometry(width, height)
+        # A path's frames are fractions of the *picture*, so the picture is placed
+        # whole on a canvas of the output's shape (never cropped, whatever `fit`
+        # says) and the frames are worked out on that canvas.
+        chains = [fit_chain(video_in, "fit", read_width, read_height,
+                            "pad" if options.fit == "pad" else "blur")]
+        chains.append(kenburns_path_chain(
+            "fit", "kb", width=width, height=height, fps=options.fps, duration=duration,
+            path=path,
+        ))
+        stage = "kb"
+    elif drift:
+        read_width, read_height, _w, _h = kenburns_geometry(width, height)
+        chains = [fit_chain(video_in, "fit", read_width, read_height, options.fit)]
+        chains.append(kenburns_chain(
+            "fit", "kb", width=width, height=height, fps=options.fps, duration=duration,
+            effect=drift, amount=options.ken_burns.amount,
+        ))
+        stage = "kb"
+    else:
+        chains = [fit_chain(video_in, "fit", width, height, options.fit)]
+        stage = "fit"
+
+    if kind == "video_muted" and not loop:
+        # Shorter than its scene and not to be repeated: hold the last frame.
+        chains.append(f"[{stage}]tpad=stop_mode=clone:stop_duration={duration:.3f}[hold]")
+        stage = "hold"
+
+    draw_wave = bool(options.waveform.enabled and audio_in and "showwaves" in filters)
+
+    # An input pad may only be consumed once in a filtergraph, and the waveform
+    # reads the same track that gets muxed, so it needs an explicit asplit.
+    audio_main = audio_in
+    if draw_wave:
+        chains.append(f"[{audio_in}]asplit=2[a_wave][a_main]")
+        audio_main = "a_main"
+        chains.append(waveform_chain("a_wave", stage, "wv", width, height, options.fps, options.waveform))
+        stage = "wv"
+
+    if overlay_index is not None:
+        chains.append(f"[{stage}][{overlay_index}:v]overlay=0:0[ov]")
+        stage = "ov"
+
+    if subtitle_file and "subtitles" in filters:
+        chains.append(f"[{stage}]subtitles={subtitle_file}[sub]")
+        stage = "sub"
+
+    # A dip through black or white is drawn inside the shot, so its duration is
+    # unchanged and the stitch stays a `concat -c copy` remux. A blending
+    # transition cannot be expressed here at all — see build_xfade_command.
+    entering = in_transition or options.transition
+    leaving = out_transition or options.transition
+    dip_start = dip_seconds(entering.style, entering.duration, duration) if dip_in else 0.0
+    dip = dip_seconds(leaving.style, leaving.duration, duration) if dip_out else 0.0
+    fades = []
+    if dip_start > 0:
+        fades.append(f"fade=t=in:st=0:d={dip_start:.3f}:color={transition_colour(entering.style)}")
+    if dip > 0:
+        fades.append(f"fade=t=out:st={duration - dip:.3f}:d={dip:.3f}:color={transition_colour(leaving.style)}")
+    if fades:
+        chains.append(f"[{stage}]{','.join(fades)}[fd]")
+        stage = "fd"
+
+    chains.append(f"[{stage}]setsar=1,format=yuv420p[v]")
+
+    # Pad the audio so a shot always reaches its target length even when the
+    # narration is shorter (a media block with little text under it).
+    audio_chain = f"[{audio_main}]aresample=48000,aformat=channel_layouts=stereo,apad"
+    if dip > 0:
+        # Only the tail is faded, to match the picture dipping to colour there —
+        # and it lands in the trailing hold `shot_end_pause_ms` leaves after the
+        # last word, not on speech itself. The start has no equivalent lead-in
+        # silence: narration begins at st=0 of the shot, so a matching fade-in
+        # there was ramping up through the sentence's actual first word,
+        # sometimes past the point of being audible at all.
+        audio_chain += f",afade=t=out:st={duration - dip:.3f}:d={dip:.3f}"
+    chains.append(f"{audio_chain}[a]")
+
+    argv += ["-filter_complex", ";".join(chains), "-map", "[v]", "-map", "[a]"]
+    argv += ["-t", f"{max(0.1, duration):.3f}"]
+    argv += encode_args(options, preview)
+    argv += [output]
+    return argv
+
+
+def build_concat_command(list_file: str, output: str) -> List[str]:
+    """Stitch the shots. `-c copy` is valid only because every shot shares
+    encode_args() — this is a remux, not a re-encode."""
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-f", "concat", "-safe", "0", "-i", list_file,
+        "-c", "copy", "-movflags", "+faststart", output,
+    ]
+
+
+def build_xfade_command(
+    shot_files: Sequence[str], durations: Sequence[float], output: str,
+    *, options: RenderOptions, preview: bool, style: str, overlap: float,
+    cuts: Sequence[bool] = (),
+) -> List[str]:
+    """Stitch the shots with a blending transition instead of a plain concat.
+
+    Unlike `build_concat_command` this is a real encode, because a blend needs
+    adjacent shots to be on screen at the same time and no per-shot filter can
+    express that. It is still only one pass over the joined stream, and it reuses
+    `encode_args` so the result matches every other path's quality settings.
+
+    Each shot is its own input and the graph chains pairwise, carrying the
+    running total so every `offset` lands where the previous blend left off:
+    shot k starts `overlap` seconds before the accumulated stream ends.
+
+    The audio does not blend the way the picture does. An `acrossfade` here
+    would mix the outgoing shot's trailing hold — the very silence
+    `shot_end_pause_ms`/`heading_pause_ms` puts there — with the incoming
+    shot's opening words ramping up underneath it, which is exactly what
+    used to muffle the start of every segment after the first and swallow
+    the configured pause along with it. Instead the accumulated audio is
+    trimmed to end exactly where the picture starts blending, and the next
+    shot's track is appended untouched: a clean cut under a blended
+    picture, eating the same `overlap` seconds the video xfade does so the
+    two streams stay in sync without the words ever overlapping.
+
+    A shot whose `cuts` entry is True joins by a straight cut instead: it
+    carries on over the same picture, so it is appended whole, picture and
+    sound, with nothing eaten.
+    """
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"]
+    for name in shot_files:
+        argv += ["-i", name]
+
+    transition = XFADE_NAMES.get(style, "dissolve")
+    chains: List[str] = []
+    video, audio = "0:v", "0:a"
+    total = durations[0]
+    for index in range(1, len(shot_files)):
+        if index < len(cuts) and cuts[index]:
+            chains.append(f"[{video}][{index}:v]concat=n=2:v=1:a=0[vx{index}]")
+            chains.append(f"[{audio}][{index}:a]concat=n=2:v=0:a=1[ax{index}]")
+            video, audio = f"vx{index}", f"ax{index}"
+            total += durations[index]
+            continue
+        offset = max(0.0, total - overlap)
+        chains.append(
+            f"[{video}][{index}:v]xfade=transition={transition}:"
+            f"duration={overlap:.3f}:offset={offset:.3f}[vx{index}]"
+        )
+        chains.append(f"[{audio}]atrim=end={offset:.3f},asetpts=PTS-STARTPTS[at{index}]")
+        chains.append(f"[at{index}][{index}:a]concat=n=2:v=0:a=1[ax{index}]")
+        video, audio = f"vx{index}", f"ax{index}"
+        total += durations[index] - overlap
+
+    chains.append(f"[{video}]setsar=1,format=yuv420p[v]")
+    argv += ["-filter_complex", ";".join(chains), "-map", "[v]", "-map", f"[{audio}]"]
+    argv += encode_args(options, preview)
+    argv += ["-movflags", "+faststart", output]
+    return argv
+
+
+def crossfade_total(durations: Sequence[float], overlap: float,
+                    cuts: Sequence[bool] = ()) -> float:
+    """Length of an xfade stitch: every join eats `overlap` seconds, except
+    where a shot cuts straight in (see `build_xfade_command`)."""
+    if not durations:
+        return 0.0
+    blends = sum(1 for index in range(1, len(durations))
+                 if not (index < len(cuts) and cuts[index]))
+    return max(0.0, sum(durations) - overlap * blends)
+
+
+def build_music_command(
+    source: str, music: str, output: str,
+    *, duration: float, spec: MusicSpec, duck: bool,
+    start: float = 0.0, end: Optional[float] = None,
+) -> List[str]:
+    """Mix a background bed under the finished video, without touching the picture.
+
+    Music has to run continuously across shot boundaries, so it cannot be a
+    per-shot input — it goes on after the stitch. `-c:v copy` is the point: the
+    video stream is passed through untouched and only the audio is re-encoded,
+    so scoring a render costs seconds rather than a second full encode.
+
+    `-stream_loop -1` covers a bed shorter than the video and the output `-t`
+    truncates one that is longer. `normalize=0` stops `amix` halving the
+    narration to make room, which is the default and never what anyone wants.
+
+    `start`/`end` narrow the bed to a window of the video — the article between
+    an intro and an outro, which bring their own sound. The fades land at the
+    window's edges, and the bed is padded with silence past its end so the mix
+    and the ducking compressor run on to the end of the narration as before.
+    """
+    end = duration if end is None else max(0.0, min(end, duration))
+    start = max(0.0, min(start, end))
+    window = max(0.1, end - start)
+    fade_out_at = max(0.0, window - max(0.0, spec.fade_out))
+    bed = (f"[1:a]volume={max(0.0, min(1.0, spec.volume)):.3f},"
+           f"aresample=48000,aformat=channel_layouts=stereo")
+    if spec.fade_in > 0:
+        bed += f",afade=t=in:st=0:d={spec.fade_in:.3f}"
+    if spec.fade_out > 0:
+        bed += f",afade=t=out:st={fade_out_at:.3f}:d={spec.fade_out:.3f}"
+    if start > 0 or end < duration:
+        bed += f",atrim=end={window:.3f}"
+        if start > 0:
+            delay = int(round(start * 1000))
+            bed += f",adelay={delay}|{delay}"
+        bed += ",apad"
+    chains = [f"{bed}[m]"]
+
+    if duck:
+        # Compress the bed against the narration so it drops under speech and
+        # comes back up in the gaps. The main input comes first, the key second.
+        chains.append("[0:a]asplit=2[nar][key]")
+        chains.append("[m][key]sidechaincompress="
+                      "threshold=0.060:ratio=8:attack=15:release=350[bed]")
+        chains.append("[nar][bed]amix=inputs=2:normalize=0:duration=first[a]")
+    else:
+        chains.append("[0:a][m]amix=inputs=2:normalize=0:duration=first[a]")
+
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-i", source, "-stream_loop", "-1", "-i", music,
+        "-filter_complex", ";".join(chains),
+        "-map", "0:v", "-map", "[a]",
+        "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2",
+        "-t", f"{max(0.1, duration):.3f}", "-movflags", "+faststart", output,
+    ]
+
+
+def build_mux_command(
+    source: str, output: str,
+    *, chapters_file: Optional[str] = None, subtitle_file: Optional[str] = None,
+) -> List[str]:
+    """Attach chapter marks and/or a soft subtitle track, still without re-encoding."""
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", source]
+    index = 1
+    chapters_index = subtitle_index = None
+    if chapters_file:
+        argv += ["-i", chapters_file]
+        chapters_index = index
+        index += 1
+    if subtitle_file:
+        argv += ["-i", subtitle_file]
+        subtitle_index = index
+        index += 1
+
+    argv += ["-map", "0"]
+    if subtitle_index is not None:
+        argv += ["-map", str(subtitle_index)]
+    if chapters_index is not None:
+        argv += ["-map_metadata", str(chapters_index), "-map_chapters", str(chapters_index)]
+
+    argv += ["-c", "copy"]
+    if subtitle_index is not None:
+        argv += ["-c:s", "mov_text"]
+    argv += ["-movflags", "+faststart", output]
+    return argv
+
+
+def build_poster_command(source: str, output: str, at_seconds: float = 1.0) -> List[str]:
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-ss", f"{max(0.0, at_seconds):.3f}", "-i", source,
+        "-frames:v", "1", "-q:v", "3", output,
+    ]
+
+
+def build_narration_command(
+    list_file: str, output: str, *, speed: float = 1.0, min_seconds: float = 0.0,
+) -> List[str]:
+    """Join the TTS chunks into one WAV.
+
+    Decoding to PCM rather than concatenating MP3s avoids the frame-padding gaps
+    that make joined MP3 audio click and make durations drift — and the durations
+    are what every shot length and subtitle cue is derived from.
+    """
+    filters: List[str] = []
+    # atempo only accepts 0.5-2.0, so an extreme rate is applied in stages.
+    remaining = max(0.25, min(4.0, speed))
+    while abs(remaining - 1.0) > 0.01:
+        step = max(0.5, min(2.0, remaining))
+        filters.append(f"atempo={step:.4f}")
+        remaining /= step
+        if len(filters) >= 4:
+            break
+    if min_seconds > 0:
+        filters.append(f"apad=whole_dur={min_seconds:.3f}")
+
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+            "-f", "concat", "-safe", "0", "-i", list_file]
+    if filters:
+        argv += ["-filter:a", ",".join(filters)]
+    argv += ["-c:a", "pcm_s16le", "-ar", "48000", "-ac", "2", output]
+    return argv
+
+
+def build_decode_command(source: str, output: str) -> List[str]:
+    """Normalise a TTS clip to 48 kHz stereo PCM.
+
+    The concat demuxer needs every input to share a codec and stream layout, so
+    provider output (MP3 at whatever rate the model emits) is decoded before it
+    is joined with the silence pads. It also makes the per-chunk durations that
+    the subtitle cues are built from exact rather than frame-quantised.
+    """
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", source,
+        "-c:a", "pcm_s16le", "-ar", "48000", "-ac", "2", output,
+    ]
+
+
+def build_silence_command(output: str, seconds: float) -> List[str]:
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-f", "lavfi", "-i", "anullsrc=channel_layout=stereo:sample_rate=48000",
+        "-t", f"{max(0.01, seconds):.3f}", "-c:a", "pcm_s16le", output,
+    ]
+
+
+def build_join_mp3_command(list_name: str, output: str) -> List[str]:
+    """Join a concat playlist of WAV parts back into one MP3.
+
+    `build_narration_command`'s counterpart for the read-aloud export path: no
+    speed change and no minimum length, just the re-encode. It does not stay
+    WAV because an exported or inserted clip is written into the user's media
+    directory and re-fetched on every playback, and 48 kHz stereo PCM is an
+    order of magnitude larger than a 128 kbps MP3 of the same narration.
+    """
+    return [
+        "ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+        "-f", "concat", "-safe", "0", "-i", list_name,
+        "-c:a", "libmp3lame", "-b:a", "128k", "-ar", "44100", output,
+    ]
+
+
+def write_concat_list(path: str, filenames: Sequence[str]) -> None:
+    """Concat-demuxer playlist. Single quotes in a name are escaped per its
+    (unusual) quoting rules; in practice every name here is a generated one."""
+    with open(path, "w", encoding="utf-8") as f:
+        for name in filenames:
+            safe = name.replace("'", "'\\''")
+            f.write(f"file '{safe}'\n")
+
+
+# ── GVC additions ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class KenBurnsPath:
+    """A camera move from one frame of a picture to another (spec S1).
+
+    Frames are fractions of the picture: `x`, `y` the top-left, `w` the width. Their
+    height follows from the output's aspect ratio, so a frame can never ask for a
+    stretched picture. `picture` is the source's pixel size, needed to place the
+    frames on the canvas the picture is fitted into.
+    """
+
+    start: Tuple[float, float, float]
+    end: Tuple[float, float, float]
+    picture: Tuple[int, int]
+    ease: str = "in_out"
+
+
+def path_crop_rects(
+    path: KenBurnsPath, canvas_width: int, canvas_height: int, out_aspect: float,
+) -> Tuple[Tuple[float, float, float], Tuple[float, float, float], bool]:
+    """Each frame as (x, y, width) in canvas pixels, and whether one had to move.
+
+    The picture sits centred on the canvas at the largest size that fits (as `pad`
+    and `blur` place it). A frame whose derived height would run past the picture's
+    edge, or past the canvas, is moved back inside rather than refused: the spec
+    cannot know the picture's shape, so this is the first place it can be checked.
+    """
+    pic_w, pic_h = max(1, path.picture[0]), max(1, path.picture[1])
+    scale = min(canvas_width / pic_w, canvas_height / pic_h)
+    shown_w, shown_h = pic_w * scale, pic_h * scale
+    left, top = (canvas_width - shown_w) / 2, (canvas_height - shown_h) / 2
+    moved = False
+    rects = []
+    for fx, fy, fw in (path.start, path.end):
+        crop_w = max(2.0, min(canvas_width, fw * shown_w))
+        crop_h = crop_w / out_aspect
+        if crop_h > canvas_height:
+            crop_h, crop_w, moved = canvas_height, canvas_height * out_aspect, True
+        x, y = left + fx * shown_w, top + fy * shown_h
+        cx, cy = min(max(0.0, x), canvas_width - crop_w), min(max(0.0, y), canvas_height - crop_h)
+        moved = moved or abs(cx - x) > 1 or abs(cy - y) > 1
+        rects.append((cx, cy, crop_w))
+    return rects[0], rects[1], moved
+
+
+def kenburns_path_chain(
+    src: str, out: str, *, width: int, height: int, fps: int, duration: float,
+    path: KenBurnsPath,
+) -> str:
+    """A `zoompan` move between two frames, over a picture fitted at the read size.
+
+    The caller fits the picture onto a canvas of the output's shape at
+    `kenburns_geometry`'s read size, as the preset drifts do, so a crop of the
+    output's aspect is what zoompan takes (`iw/zoom` by `ih/zoom`) and nothing is
+    stretched. Crop width and origin are interpolated linearly, or with a smoothstep
+    for `in_out` so the move starts and ends at rest.
+
+    Coarser than the presets' `kenburns_sweep`, which guarantees a whole read pixel
+    per frame: an arbitrary path cannot, so a very slow move may step. The read
+    oversampling keeps each step to a fraction of an output pixel, which is what
+    makes that acceptable for M2.
+    """
+    read_width, read_height, write_width, write_height = kenburns_geometry(width, height)
+    frames = max(1, int(math.ceil(max(0.1, duration) * max(1, fps))))
+    (x0, y0, w0), (x1, y1, w1), _moved = path_crop_rects(
+        path, read_width, read_height, width / max(1, height))
+    # zoompan's `on` runs 0..d-1 and d is frames+2 (see `kenburns_chain`), so the
+    # move completes on the last frame the caller's `-t` keeps.
+    span = frames + 1
+    t = f"(on/{span})"
+    progress = f"({t}*{t}*(3-2*{t}))" if path.ease != "linear" else t
+    crop = f"({w0:.3f}+{w1 - w0:.3f}*{progress})"
+    z = f"{read_width}/{crop}"
+    x = f"{x0:.3f}+{x1 - x0:.3f}*{progress}"
+    y = f"{y0:.3f}+{y1 - y0:.3f}*{progress}"
+    chain = (f"[{src}]zoompan=z={z}:x={x}:y={y}:"
+             f"d={frames + 2}:s={write_width}x{write_height}:fps={fps}")
+    if (write_width, write_height) != (width, height):
+        chain += f",scale={width}:{height}"
+    return f"{chain}[{out}]"
+
+
+def build_extract_command(
+    source: str, output: str, *, start: float, length: float, with_audio: bool,
+) -> List[str]:
+    """Cut `length` seconds out of a video from `start`, re-encoded.
+
+    A trimmed clip is cut out once, before its shot is built, so the shot command
+    stays as Notes wrote it: looping a trim then means looping this file, which
+    `-stream_loop` on the original could not do (it restarts at the file's start).
+    Seeking before `-i` with a re-encode is frame-accurate. Quality is set high
+    because the shot encodes it again.
+    """
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error",
+            "-ss", f"{max(0.0, start):.3f}", "-i", source,
+            "-t", f"{max(0.1, length):.3f}",
+            "-c:v", "libx264", "-preset", "veryfast", "-crf", "16", "-pix_fmt", "yuv420p"]
+    if with_audio:
+        argv += ["-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2"]
+    else:
+        argv += ["-an"]
+    argv += ["-avoid_negative_ts", "make_zero", output]
+    return argv
+
+
+def build_stitch_command(
+    shot_files: Sequence[str], durations: Sequence[float], output: str,
+    *, joins: Sequence[Optional[Tuple[str, float]]], options: RenderOptions, preview: bool,
+) -> List[str]:
+    """`build_xfade_command` with a transition of its own at every join.
+
+    `joins[i]` is how shot i joins shot i-1 (`joins[0]` is unused): None appends it
+    whole, which is a cut or a dip (a dip is drawn inside both shots); a pair is the
+    xfade name and the overlap. Audio is handled exactly as there: trimmed to where
+    the blend starts and the next shot appended, so words never overlap.
+    """
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"]
+    for name in shot_files:
+        argv += ["-i", name]
+
+    # Every input on one timebase first. `concat` re-times its output to
+    # AV_TIME_BASE (1/1000000) while the shots carry 1/90000, and `xfade` refuses two
+    # inputs that disagree — so a cut followed by a blend failed to build at all.
+    chains: List[str] = [f"[{i}:v]settb=AVTB[s{i}]" for i in range(len(shot_files))]
+    video, audio = "s0", "0:a"
+    total = durations[0]
+    for index in range(1, len(shot_files)):
+        join = joins[index] if index < len(joins) else None
+        if join is None:
+            chains.append(f"[{video}][s{index}]concat=n=2:v=1:a=0[vx{index}]")
+            chains.append(f"[{audio}][{index}:a]concat=n=2:v=0:a=1[ax{index}]")
+            total += durations[index]
+        else:
+            name, overlap = join
+            offset = max(0.0, total - overlap)
+            chains.append(
+                f"[{video}][s{index}]xfade=transition={name}:"
+                f"duration={overlap:.3f}:offset={offset:.3f}[vx{index}]"
+            )
+            chains.append(f"[{audio}]atrim=end={offset:.3f},asetpts=PTS-STARTPTS[at{index}]")
+            chains.append(f"[at{index}][{index}:a]concat=n=2:v=0:a=1[ax{index}]")
+            total += durations[index] - overlap
+        video, audio = f"vx{index}", f"ax{index}"
+
+    chains.append(f"[{video}]setsar=1,format=yuv420p[v]")
+    argv += ["-filter_complex", ";".join(chains), "-map", "[v]", "-map", f"[{audio}]"]
+    argv += encode_args(options, preview)
+    argv += ["-movflags", "+faststart", output]
+    return argv
+
+
+@dataclass(frozen=True)
+class MixTrack:
+    """One audio track placed on the finished video's timeline."""
+
+    path: str
+    start: float          # seconds into the video
+    length: float         # how long it plays
+    trim_in: float = 0.0  # seconds into the file it starts from
+    loop: bool = False    # repeat the file to fill `length`
+    volume: float = 0.18
+    fade_in: float = 0.0
+    fade_out: float = 0.0
+    duck: bool = True     # pushed down under the narration
+
+
+def build_mix_command(
+    source: str, tracks: Sequence[MixTrack], output: str,
+    *, duration: float, duck_available: bool = True,
+) -> List[str]:
+    """Mix any number of tracks under the finished video, the picture untouched.
+
+    `build_music_command` for N tracks, each anywhere on the timeline: a soundtrack
+    that changes partway through is two tracks, and a crossfade is two that overlap
+    with matching fades. Each is trimmed to its window, faded, set to its volume and
+    delayed to its start. The ducked ones (music, by default) are summed into one bed
+    and compressed against the narration, as Notes ducks its single bed; the rest
+    (sound effects, extra voice) are mixed in flat.
+
+    A looping track restarts from the top of its file, not from `trim_in`: that is
+    what `-stream_loop` does with an input seek, and a bed short enough to loop is
+    rarely trimmed as well.
+    """
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", source]
+    chains: List[str] = []
+    ducked: List[str] = []
+    flat: List[str] = []
+    for position, track in enumerate(tracks, start=1):
+        if track.trim_in > 0:
+            argv += ["-ss", f"{track.trim_in:.3f}"]
+        if track.loop:
+            argv += ["-stream_loop", "-1"]
+        argv += ["-i", track.path]
+        length = max(0.1, track.length)
+        chain = (f"[{position}:a]aresample=48000,aformat=channel_layouts=stereo,"
+                 f"atrim=end={length:.3f},asetpts=PTS-STARTPTS,"
+                 f"volume={max(0.0, min(1.0, track.volume)):.3f}")
+        if track.fade_in > 0:
+            chain += f",afade=t=in:st=0:d={min(track.fade_in, length):.3f}"
+        if track.fade_out > 0:
+            fade = min(track.fade_out, length)
+            chain += f",afade=t=out:st={length - fade:.3f}:d={fade:.3f}"
+        delay = int(round(max(0.0, track.start) * 1000))
+        if delay:
+            chain += f",adelay={delay}|{delay}"
+        chain += f",apad[t{position}]"
+        chains.append(chain)
+        (ducked if track.duck and duck_available else flat).append(f"t{position}")
+
+    mix_inputs = ["nar"]
+    if ducked:
+        if len(ducked) == 1:
+            bed = ducked[0]
+        else:
+            chains.append("".join(f"[{t}]" for t in ducked)
+                          + f"amix=inputs={len(ducked)}:normalize=0[bedmix]")
+            bed = "bedmix"
+        chains.append("[0:a]asplit=2[nar][key]")
+        chains.append(f"[{bed}][key]sidechaincompress="
+                      "threshold=0.060:ratio=8:attack=15:release=350[bed]")
+        mix_inputs.append("bed")
+    else:
+        chains.append("[0:a]anull[nar]")
+    mix_inputs += flat
+    chains.append("".join(f"[{t}]" for t in mix_inputs)
+                  + f"amix=inputs={len(mix_inputs)}:normalize=0:duration=first[a]")
+
+    argv += [
+        "-filter_complex", ";".join(chains),
+        "-map", "0:v", "-map", "[a]",
+        "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-ar", "48000", "-ac", "2",
+        "-t", f"{max(0.1, duration):.3f}", "-movflags", "+faststart", output,
+    ]
+    return argv
diff --git a/backend/app/render/media.py b/backend/app/render/media.py
new file mode 100644
index 0000000..41e9637
--- /dev/null
+++ b/backend/app/render/media.py
@@ -0,0 +1,175 @@
+"""The files a render needs, made local.
+
+GVC owns no media: everything a video shows or plays lives in GAM. A render streams
+each file it needs into a cache once, keyed on GAM's id and checked against GAM's
+size, so rendering the same project again (a preview, then the full render) fetches
+nothing twice. Signed URLs are asked for at render time, because they expire.
+
+What cannot be fetched is said per asset, all at once, before anything is encoded:
+- a placeholder still to find or generate is drawn as a slate in a preview, and
+  refuses a full render;
+- a file still inside the note a project was pushed from refuses both, with the fix.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from PIL import Image
+
+from app.config import settings
+from app.gam.client import GamClient
+from app.render import compose
+from app.render import ffmpeg as F
+from app.render.compile import Media
+from app.spec.model import GamAsset, GeneratedAsset, NotesAsset, SearchAsset, VideoSpec
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Resolution:
+    media: Dict[str, Media] = field(default_factory=dict)
+    # Reasons the render cannot go ahead, one per asset.
+    problems: List[str] = field(default_factory=list)
+
+
+def used_keys(spec: VideoSpec) -> Set[str]:
+    """Every asset key the render will read."""
+    keys = {s.visual.asset for s in spec.segments if s.visual is not None}
+    keys |= {t.asset for t in spec.audio_tracks}
+    if spec.style.background.type == "image" and spec.style.background.asset:
+        keys.add(spec.style.background.asset)
+    if spec.chrome.watermark and spec.chrome.watermark.asset:
+        keys.add(spec.chrome.watermark.asset)
+    return keys
+
+
+def _probe(path: str, kind: str) -> Media:
+    if kind == "image":
+        try:
+            with Image.open(path) as image:
+                width, height = image.size
+        except OSError:
+            width = height = None
+        return Media(path=path, kind="image", width=width, height=height)
+    return Media(path=path, kind=kind, duration=F.probe_duration(path) or None,
+                 has_audio=F.probe_has_audio(path) if kind == "video" else True)
+
+
+def _slate(work_dir: str, key: str, title: str, subtitle: str, width: int, height: int) -> Media:
+    """A placeholder drawn as a card, so a preview shows where it will go."""
+    path = os.path.join(work_dir, f"slate_{key}.png")
+    compose.card_image(width, height, title=title, subtitle=subtitle).convert("RGB").save(path, "PNG")
+    return Media(path=path, kind="slate", width=width, height=height)
+
+
+class MediaCache:
+    """GAM files on local disk, pruned oldest-used first past the size cap."""
+
+    def __init__(self, root: Path):
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def fetch(self, gam: GamClient, file_id: str, file_url: str, size: int) -> str:
+        path = self.root / file_id
+        meta = self.root / f"{file_id}.json"
+        if path.exists() and meta.exists():
+            try:
+                if json.loads(meta.read_text()).get("size") == size and size:
+                    os.utime(path)  # recently used: last to be pruned
+                    return str(path)
+            except ValueError:
+                pass
+        # Streamed to a temporary name and renamed, so a render interrupted
+        # mid-download never leaves a truncated file that looks complete.
+        handle, tmp = tempfile.mkstemp(dir=self.root, prefix=".part-")
+        try:
+            with os.fdopen(handle, "wb") as sink:
+                written = gam.download(file_url, sink,
+                                       max_bytes=settings.render_max_file_mb * 1024 * 1024)
+            os.replace(tmp, path)
+        except BaseException:
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+            raise
+        meta.write_text(json.dumps({"size": size or written}))
+        return str(path)
+
+    def prune(self, max_bytes: int) -> None:
+        files = [p for p in self.root.iterdir() if p.is_file() and not p.name.endswith(".json")
+                 and not p.name.startswith(".part-")]
+        files.sort(key=lambda p: p.stat().st_mtime)
+        total = sum(p.stat().st_size for p in files)
+        for path in files:
+            if total <= max_bytes:
+                break
+            total -= path.stat().st_size
+            for doomed in (path, path.with_name(path.name + ".json")):
+                try:
+                    doomed.unlink()
+                except OSError:
+                    pass
+
+
+def resolve(
+    spec: VideoSpec, gam: GamClient, *, cache: MediaCache, work_dir: str, preview: bool,
+    frame: tuple,
+) -> Resolution:
+    out = Resolution()
+    width, height = frame
+    for key in sorted(used_keys(spec)):
+        ref = spec.assets[key]
+        if isinstance(ref, NotesAsset):
+            out.problems.append(f"“{ref.label or ref.url}” is still inside the note this came "
+                                "from. Copy the note's files into GAM first.")
+            continue
+        if isinstance(ref, SearchAsset) and ref.result is None:
+            if preview:
+                out.media[key] = _slate(work_dir, key, "To find", ref.query, width, height)
+            else:
+                out.problems.append(f"Footage still to find: “{ref.query}”.")
+            continue
+        if isinstance(ref, GeneratedAsset) and ref.result is None:
+            if preview:
+                out.media[key] = _slate(work_dir, key, "To generate", ref.prompt, width, height)
+            else:
+                out.problems.append(f"Still to generate: “{ref.prompt}”.")
+            continue
+
+        gam_id = ref.result.id if isinstance(ref, (SearchAsset, GeneratedAsset)) else ref.id
+        label = ref.label or gam_id
+        # GamError (the library unreachable) propagates: that is one problem for the
+        # whole render, not one per asset.
+        asset = gam.get_asset(gam_id)
+        if asset is None:
+            out.problems.append(f"“{label}” is no longer in the asset library.")
+            continue
+        if asset.missing or not asset.file_url:
+            out.problems.append(f"“{asset.name}” has no file in the asset library.")
+            continue
+        # A GAM clip plays its parent's bytes, so the parent's file is what is cached.
+        file_id = asset.parent_asset_id if asset.parent_asset_id and asset.in_point is not None \
+            else asset.id
+        path = cache.fetch(gam, file_id, asset.file_url, asset.size_bytes)
+        kind = asset.asset_type if asset.asset_type in ("image", "video", "audio") else "video"
+        media = _probe(path, kind)
+        if file_id != asset.id:
+            media.offset = asset.in_point or 0.0
+            if asset.out_point is not None:
+                media.length = max(0.1, asset.out_point - (asset.in_point or 0.0))
+        out.media[key] = media
+
+    try:
+        cache.prune(int(settings.render_cache_max_gb * 1024 ** 3))
+    except OSError:
+        logger.exception("Could not prune the render media cache")
+    return out
diff --git a/backend/app/render/narration.py b/backend/app/render/narration.py
new file mode 100644
index 0000000..4d8e572
--- /dev/null
+++ b/backend/app/render/narration.py
@@ -0,0 +1,473 @@
+"""Narration: text -> chunked TTS -> one WAV per shot, plus subtitle cues.
+
+The TTS endpoints cap a request at 2000 characters, so a section of an article
+has to be split, synthesised piece by piece and rejoined. Splitting on sentence
+boundaries (rather than at a fixed offset) is what keeps the prosody natural,
+and knowing each piece's duration is what makes accurate subtitles free.
+
+Joining is done by decoding to PCM rather than concatenating the MP3s: joined
+MP3 frames click at the seams and their padding makes the measured duration
+drift, and every shot length and subtitle cue is derived from that measurement.
+"""
+
+import asyncio
+import logging
+import os
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional, Sequence, Tuple
+
+from app.render import ffmpeg as F
+from app.render import pause_markup
+from app.render.options import RenderOptions
+from app.render.pause_markup import Chunk
+
+logger = logging.getLogger(__name__)
+
+# Comfortably under the backend's 2000-char TTS cap, and the same budget the
+# read-aloud player uses client-side, so the two share disk-cache entries.
+MAX_CHUNK_CHARS = 1500
+
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?…])\s+|\n+")
+_WHITESPACE = re.compile(r"[ \t]+")
+
+# Matches emoji (pictographs, flag letters, misc symbol blocks with emoji
+# presentation) plus the zero-width joiner / variation-selector / keycap marks
+# used to build compound emoji, so they can be dropped before synthesis —
+# otherwise the TTS engine reads them out by description (e.g. "🚗" becomes
+# the spoken word "car"). `re` has no \p{Extended_Pictographic}, so the
+# ranges are spelled out by hand; mirrors EMOJI_REGEX in the frontend's
+# useTextToSpeech hook so a note read aloud there and rendered into a video
+# here drop the same characters (and keep sharing chunk_text's cache keys).
+_EMOJI = re.compile(
+    "["
+    "\U0001F1E6-\U0001F1FF"  # regional indicators (flag letters)
+    "\U0001F300-\U0001F5FF"  # misc symbols & pictographs (incl. skin-tone modifiers)
+    "\U0001F600-\U0001F64F"  # emoticons
+    "\U0001F680-\U0001F6FF"  # transport & map symbols
+    "\U0001F700-\U0001F77F"  # alchemical symbols
+    "\U0001F780-\U0001F7FF"  # geometric shapes extended
+    "\U0001F800-\U0001F8FF"  # supplemental arrows-C
+    "\U0001F900-\U0001F9FF"  # supplemental symbols & pictographs
+    "\U0001FA00-\U0001FA6F"  # chess symbols
+    "\U0001FA70-\U0001FAFF"  # symbols & pictographs extended-A
+    "\u2600-\u26FF"  # misc symbols (e.g. sun, heart)
+    "\u2700-\u27BF"  # dingbats (e.g. scissors, airplane)
+    "\u2300-\u23FF"  # misc technical (e.g. watch, alarm clock)
+    "\u2B00-\u2BFF"  # misc symbols & arrows (e.g. star, block)
+    "\u200D\uFE0F\u20E3"  # ZWJ, variation selector, keycap combiner
+    "]"
+)
+
+
+def strip_emoji(text: str) -> str:
+    return _EMOJI.sub("", text)
+
+
+def chunk_text(text: str, max_chars: int = MAX_CHUNK_CHARS) -> List[str]:
+    """Greedily pack sentences into chunks of at most `max_chars`.
+
+    A single over-long sentence is only broken when it exceeds the cap on its
+    own, and then on a word boundary — never mid-word, and never mid-sentence
+    when the sentence would have fit. Mirrors packChunks() in the frontend's
+    useTextToSpeech hook so both sides produce the same cache keys.
+    """
+    clean = _WHITESPACE.sub(" ", strip_emoji(text or "").strip())
+    if not clean:
+        return []
+    if len(clean) <= max_chars:
+        return [clean]
+
+    chunks: List[str] = []
+    current = ""
+    for piece in _SENTENCE_SPLIT.split(clean):
+        piece = piece.strip()
+        if not piece:
+            continue
+        if len(piece) > max_chars:
+            if current:
+                chunks.append(current.strip())
+                current = ""
+            rest = piece
+            while len(rest) > max_chars:
+                cut = rest.rfind(" ", 0, max_chars)
+                if cut <= 0:
+                    cut = max_chars
+                chunks.append(rest[:cut].strip())
+                rest = rest[cut:].lstrip()
+            current = rest
+            continue
+        trial = f"{current} {piece}".strip()
+        if len(trial) <= max_chars:
+            current = trial
+        else:
+            chunks.append(current.strip())
+            current = piece
+    if current.strip():
+        chunks.append(current.strip())
+    return [c for c in chunks if c]
+
+
+# A blank line marks a break the voice cannot make on its own — see
+# segmenter._set_apart. A single newline is an ordinary block join and is left
+# to the sentence packer, so marking is opt-in rather than accidental.
+_HARD_BREAK = re.compile(r"\n[ \t]*\n+")
+
+
+def chunk_narration(
+    text: str, *, paragraph_pause_ms: int, heading_pause_ms: int,
+    max_chars: int = MAX_CHUNK_CHARS,
+) -> List[Chunk]:
+    """Split a shot's narration into TTS requests and the pauses between them.
+
+    Silence can only be laid between separately synthesised pieces, so a pause
+    inside a section means splitting the request there. A whole section is
+    normally one chunk, which is exactly why a heading in the middle of it gets
+    nothing more than a full stop today.
+
+    Sections split on a blank line and are chunked as before within themselves;
+    the gap after a section is the longer heading pause. With that pause turned
+    off the marks are ignored entirely, so nothing is split that would otherwise
+    have travelled as one request.
+
+    A heading-adjacent chunk therefore stops matching the one the read-aloud
+    player would have produced for the same passage, so the two no longer share
+    that disk-cache entry. Only passages next to a heading are affected, and the
+    chunks a render makes are still cached and reused by later renders.
+    """
+    body = text or ""
+    if heading_pause_ms <= 0:
+        packed = chunk_text(body, max_chars)
+        return [Chunk(c, 0 if index == len(packed) - 1 else paragraph_pause_ms)
+                for index, c in enumerate(packed)]
+
+    sections = [s for s in _HARD_BREAK.split(body) if s.strip()]
+    chunks: List[Chunk] = []
+    for index, section in enumerate(sections):
+        packed = chunk_text(section, max_chars)
+        for position, piece in enumerate(packed):
+            last_in_section = position == len(packed) - 1
+            ends_the_text = last_in_section and index == len(sections) - 1
+            if ends_the_text:
+                pause = 0
+            elif last_in_section:
+                pause = heading_pause_ms
+            else:
+                pause = paragraph_pause_ms
+            chunks.append(Chunk(piece, pause))
+    return chunks
+
+
+def build_narration_chunks(text: str, *, options: RenderOptions) -> List[Chunk]:
+    """The default split for a shot's narration: heading pauses plus whatever
+    pause markup the writer typed into the prose themselves.
+
+    Two independent sources of pauses, combined:
+
+    - `options.heading_pause_ms`, wherever a heading wrapped its section in a
+      blank line (see `segmenter._set_apart`) — the coarse, article-structure
+      pause `chunk_narration` also makes, driven by the render options rather
+      than anything the writer typed.
+    - `[pause:...]` markers and an ellipsis ("..." or "…"), via
+      `pause_markup.parse_pause_markup` — fine-grained pauses the writer
+      places explicitly in the text.
+
+    A bare sentence-ending "." is deliberately not a trigger here, unlike the
+    read-aloud player: forcing every sentence into its own TTS request with a
+    hard silence after it would cost an ordinary paragraph its natural
+    one-breath prosody, which nobody asked for when they typed a normal
+    sentence. Only the punctuation someone put there on purpose — an
+    ellipsis, an explicit marker, a blank line — becomes a pause.
+
+    Any resulting piece still longer than one TTS request is packed down
+    further exactly like `chunk_narration` does, holding
+    `options.paragraph_pause_ms` between the pieces that split created.
+    """
+    pause_ms: Dict[str, int] = {"…": pause_markup.DEFAULT_PAUSE_MS["…"]}
+    if options.heading_pause_ms > 0:
+        pause_ms["\n\n"] = options.heading_pause_ms
+
+    # Emoji come out before the split, not during it. `chunk_text` below strips
+    # them too, but it only runs for a chunk too long for one request — which
+    # nearly none are — so relying on it left every ordinary chunk with its
+    # emoji intact and the voice reading "🚗" aloud as "car". Stripping first
+    # also matches the order `packSpeechChunks` uses client-side.
+    # Runs of spaces and tabs collapse with them, closing the gap a removed
+    # emoji leaves behind. Newlines are deliberately untouched: a blank line is
+    # what the paragraph trigger is made of.
+    cleaned = _WHITESPACE.sub(" ", strip_emoji(text or ""))
+    marked = pause_markup.parse_pause_markup(cleaned, pause_ms=pause_ms)
+
+    chunks: List[Chunk] = []
+    for chunk in marked:
+        if len(chunk.text) <= MAX_CHUNK_CHARS:
+            chunks.append(chunk)
+            continue
+        pieces = chunk_text(chunk.text, MAX_CHUNK_CHARS)
+        for position, piece in enumerate(pieces):
+            last = position == len(pieces) - 1
+            chunks.append(Chunk(piece, chunk.pause_after_ms if last else options.paragraph_pause_ms))
+    return chunks
+
+
+def stitch_chunks_to_mp3(pieces: Sequence[Tuple[bytes, int]]) -> bytes:
+    """Join already-synthesised chunks into one MP3, holding each one's pause.
+
+    The whole-file counterpart to `synthesize_shot`'s concat step, for the
+    read-aloud export/insert path. It takes the same route for the same reason:
+    decode every piece to a common PCM layout first, because joined MP3 frames
+    click at the seams and the concat demuxer silently drops inputs that don't
+    match the first one — which is exactly how pauses get quietly eaten.
+
+    `pieces` is `(audio_bytes, pause_after_ms)` in playback order. The last
+    piece's pause is ignored: there is nothing after it to separate it from.
+    """
+    if not pieces:
+        return b""
+
+    work_dir = tempfile.mkdtemp(prefix="tts_join_")
+    try:
+        entries: List[str] = []
+        for index, (audio, pause_after_ms) in enumerate(pieces):
+            raw_name = f"part_{index:04d}.raw"
+            with open(os.path.join(work_dir, raw_name), "wb") as f:
+                f.write(audio)
+            part_name = f"part_{index:04d}.wav"
+            F.run(F.build_decode_command(raw_name, part_name), cwd=work_dir, timeout=120)
+            entries.append(part_name)
+            if index < len(pieces) - 1:
+                pad = build_silence(work_dir, pause_after_ms)
+                if pad:
+                    entries.append(pad)
+
+        list_name = "join.txt"
+        F.write_concat_list(os.path.join(work_dir, list_name), entries)
+        out_name = "joined.mp3"
+        F.run(F.build_join_mp3_command(list_name, out_name), cwd=work_dir, timeout=600)
+        with open(os.path.join(work_dir, out_name), "rb") as f:
+            return f.read()
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+
+# Two lines of roughly 42 characters is the long-standing broadcast convention
+# and about as much as anyone can read before the next cue arrives.
+SUBTITLE_MAX_CHARS = 84
+
+
+def split_for_subtitles(text: str, max_chars: int = SUBTITLE_MAX_CHARS) -> List[str]:
+    """Break narration into subtitle-sized lines, preferring sentence ends."""
+    clean = _WHITESPACE.sub(" ", (text or "").strip())
+    if not clean:
+        return []
+
+    lines: List[str] = []
+    current = ""
+    for sentence in _SENTENCE_SPLIT.split(clean):
+        sentence = sentence.strip()
+        if not sentence:
+            continue
+        if len(sentence) > max_chars:
+            if current:
+                lines.append(current)
+                current = ""
+            words = sentence.split()
+            for word in words:
+                trial = f"{current} {word}".strip()
+                if len(trial) <= max_chars:
+                    current = trial
+                else:
+                    if current:
+                        lines.append(current)
+                    current = word
+            continue
+        trial = f"{current} {sentence}".strip()
+        if len(trial) <= max_chars:
+            current = trial
+        else:
+            if current:
+                lines.append(current)
+            current = sentence
+    if current:
+        lines.append(current)
+    return lines
+
+
+@dataclass
+class Cue:
+    """One subtitle cue, in seconds relative to the start of the video."""
+
+    start: float
+    end: float
+    text: str
+
+
+@dataclass
+class NarrationResult:
+    path: Optional[str]        # WAV for this shot, relative to the work dir
+    duration: float
+    cues: List[Cue] = field(default_factory=list)   # shot-local timings
+    chars: int = 0
+
+
+def _srt_timestamp(seconds: float) -> str:
+    total_ms = max(0, int(round(seconds * 1000)))
+    h, rem = divmod(total_ms, 3_600_000)
+    m, rem = divmod(rem, 60_000)
+    s, ms = divmod(rem, 1000)
+    return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
+
+
+def write_srt(path: str, cues: Sequence[Cue]) -> bool:
+    """Write cues as SubRip. Returns False when there was nothing to write."""
+    usable = [c for c in cues if c.text.strip() and c.end > c.start]
+    if not usable:
+        return False
+    with open(path, "w", encoding="utf-8") as f:
+        for index, cue in enumerate(usable, start=1):
+            f.write(f"{index}\n{_srt_timestamp(cue.start)} --> {_srt_timestamp(cue.end)}\n")
+            f.write(f"{cue.text.strip()}\n\n")
+    return True
+
+
+def shift_cues(cues: Sequence[Cue], offset: float) -> List[Cue]:
+    return [Cue(c.start + offset, c.end + offset, c.text) for c in cues]
+
+
+def build_silence(work_dir: str, milliseconds: int) -> Optional[str]:
+    """Render (once per job) the pad inserted between narration chunks."""
+    if milliseconds <= 0:
+        return None
+    name = f"silence_{milliseconds}.wav"
+    path = os.path.join(work_dir, name)
+    if not os.path.isfile(path):
+        F.run(F.build_silence_command(name, milliseconds / 1000.0), cwd=work_dir, timeout=60)
+    return name
+
+
+def synthesize_shot(
+    text: str,
+    *,
+    index: int,
+    work_dir: str,
+    options: RenderOptions,
+    tts: Callable[[str], bytes],
+    chunks: Optional[List[Chunk]] = None,
+) -> NarrationResult:
+    """Synthesise one shot's narration and return its WAV, length and cues.
+
+    `tts` is injected (rather than imported) so this stays testable without a
+    network call, and so the caller owns provider selection and usage recording.
+
+    `chunks` lets a caller supply its own text/pause split instead of the
+    default — heading pauses plus the pause markup in the prose itself, see
+    `build_narration_chunks`.
+    """
+    chunks = chunks if chunks is not None else build_narration_chunks(text, options=options)
+    if not chunks:
+        # A shot with no text still needs an audio track — the concat demuxer
+        # requires every part to have the same stream layout — so it gets
+        # silence at the shot's minimum length.
+        name = f"narration_{index:04d}.wav"
+        F.run(F.build_silence_command(name, options.min_shot_seconds), cwd=work_dir, timeout=60)
+        return NarrationResult(path=name, duration=options.min_shot_seconds, cues=[], chars=0)
+
+    parts: List[str] = []
+    scratch: List[str] = []
+    for position, chunk in enumerate(chunks):
+        audio = tts(chunk.text)
+        raw_name = f"chunk_{index:04d}_{position:03d}.raw"
+        with open(os.path.join(work_dir, raw_name), "wb") as f:
+            f.write(audio)
+        scratch.append(raw_name)
+        # Decode to a common format before joining. Providers return MP3 at
+        # whatever rate they like, and the concat demuxer silently drops inputs
+        # that don't match the first one — which quietly ate the pauses.
+        part_name = f"chunk_{index:04d}_{position:03d}.wav"
+        try:
+            F.run(F.build_decode_command(raw_name, part_name), cwd=work_dir, timeout=120)
+        except F.FFmpegError as exc:
+            # ffmpeg cannot say what it choked on: given bytes it can't identify
+            # it falls back to the demuxer matching the ".raw" name and reports
+            # "Invalid pixel format", which sends anyone reading the job error
+            # looking for a video problem in an audio path. Name the real cause
+            # — the provider handed back something that isn't audio — and the
+            # text it did it for. `has_speech` should mean this never fires.
+            raise F.FFmpegError(
+                f"Narration chunk {position} of shot {index} came back as "
+                f"{len(audio)} bytes that ffmpeg could not decode as audio. "
+                f"Chunk text: {chunk.text[:120]!r}"
+            ) from exc
+        parts.append(part_name)
+        scratch.append(part_name)
+
+    # Measure each chunk before joining: after the join the boundaries are gone,
+    # and these are what the subtitle cues are built from.
+    raw_durations = [F.probe_duration(os.path.join(work_dir, p)) for p in parts]
+
+    entries: List[str] = []
+    for position, part in enumerate(parts):
+        entries.append(part)
+        if position >= len(parts) - 1:
+            continue
+        # Each gap is the one its own chunk asked for, so a heading break is
+        # audibly longer than the join between two halves of a paragraph.
+        pad = build_silence(work_dir, chunks[position].pause_after_ms)
+        if pad:
+            entries.append(pad)
+
+    # Held after the shot's very last word, before the cut to whatever comes
+    # next. Without this the shot's audio — and so the shot itself, since its
+    # length is measured from this file — ends the instant speech does, often
+    # mid-decay on a voice's own trailing intonation; the cut then lands right
+    # on top of it and reads as the sentence getting clipped rather than
+    # finishing. paragraph_pause_ms and heading_pause_ms only ever sit
+    # *between* two chunks above, which is why this needs its own entry here.
+    end_pad = build_silence(work_dir, options.shot_end_pause_ms)
+    if end_pad:
+        entries.append(end_pad)
+
+    list_name = f"narration_{index:04d}.txt"
+    F.write_concat_list(os.path.join(work_dir, list_name), entries)
+
+    out_name = f"narration_{index:04d}.wav"
+    F.run(
+        F.build_narration_command(
+            list_name, out_name, speed=options.speed, min_seconds=options.min_shot_seconds,
+        ),
+        cwd=work_dir, timeout=600,
+    )
+    duration = F.probe_duration(os.path.join(work_dir, out_name)) or sum(raw_durations)
+
+    # Lay the cues out on the same timeline the join produced: chunk lengths and
+    # pauses scaled by the speed change, so they stay aligned end to end. A TTS
+    # chunk is far too long to show as one subtitle, so each is split into
+    # readable lines and given a proportional slice of its measured duration.
+    speed = max(0.25, options.speed)
+    cues: List[Cue] = []
+    cursor = 0.0
+    for position, chunk in enumerate(chunks):
+        length = raw_durations[position] / speed if raw_durations[position] else 0.0
+        if length <= 0:
+            # Fall back to a reading-rate estimate rather than emitting a zero
+            # cue, which would be dropped and lose the line entirely.
+            length = max(0.6, len(chunk.text) / 15.0 / speed)
+        lines = split_for_subtitles(chunk.text)
+        total = sum(len(l) for l in lines) or 1
+        for line in lines:
+            span = length * len(line) / total
+            cues.append(Cue(cursor, cursor + span, line))
+            cursor += span
+        if position < len(chunks) - 1:
+            cursor += chunk.pause_after_ms / 1000.0 / speed
+
+    for name in scratch:
+        try:
+            os.remove(os.path.join(work_dir, name))
+        except OSError:
+            pass
+
+    return NarrationResult(path=out_name, duration=duration, cues=cues,
+                           chars=sum(len(c.text) for c in chunks))
diff --git a/backend/app/render/options.py b/backend/app/render/options.py
new file mode 100644
index 0000000..c13cf6d
--- /dev/null
+++ b/backend/app/render/options.py
@@ -0,0 +1,487 @@
+"""Render options and the frame-size / encoder tables.
+
+Everything the user picks in the "Generate video" dialog lands here as a
+`RenderOptions`, which is stored verbatim on the job row as JSON. Keeping it one
+serialisable model (rather than columns) means a future presets feature can save
+and replay a configuration without a schema change.
+"""
+
+from typing import Dict, List, Literal, Optional, Tuple
+
+from pydantic import BaseModel, Field, field_validator
+
+Aspect = Literal["16:9", "9:16", "1:1"]
+Resolution = Literal["720p", "1080p", "4k"]
+Quality = Literal["preview", "standard", "high"]
+Fit = Literal["blur", "pad", "crop"]
+Position = Literal["top-left", "top-right", "center", "bottom-left", "bottom-right"]
+WavePosition = Literal["top", "center", "bottom"]
+WaveMode = Literal["line", "p2p", "cline", "point"]
+SubtitleMode = Literal["off", "sidecar", "soft", "burn"]
+# "title" shows the note's title; "title_chapter" adds the current chapter
+# underneath it, in a smaller size, and follows it as the video moves between
+# chapters; "fixed" is free text the user types in.
+OverlayTextMode = Literal["fixed", "title", "title_chapter"]
+
+# A transition either dips through a colour — which each shot can draw inside its
+# own filtergraph — or blends into its neighbour, which needs the two shots to
+# overlap on the timeline. Only the second kind costs anything; see is_crossfade.
+Transition = Literal[
+    "none", "fade", "fadewhite",
+    "dissolve", "slideleft", "slideright", "wipeleft", "wiperight",
+    "circleopen", "smoothleft",
+]
+KenBurnsEffect = Literal[
+    "none", "zoom_in", "zoom_out",
+    "pan_left", "pan_right", "pan_up", "pan_down", "alternate",
+]
+QuotePosition = Literal["top", "center", "bottom"]
+
+# Drawn per shot with `fade`/`afade`, so shot durations are unchanged and the
+# stitch stays a `concat -c copy` remux.
+DIP_TRANSITIONS = frozenset({"fade", "fadewhite"})
+
+# ffmpeg's xfade name for each blending style. Anything absent from here that
+# isn't a dip is treated as "none".
+XFADE_NAMES: Dict[str, str] = {
+    "dissolve": "dissolve",
+    "slideleft": "slideleft",
+    "slideright": "slideright",
+    "wipeleft": "wipeleft",
+    "wiperight": "wiperight",
+    "circleopen": "circleopen",
+    "smoothleft": "smoothleft",
+}
+
+
+def is_crossfade(style: str) -> bool:
+    """True when this style needs the xfade stitch instead of `concat -c copy`.
+
+    The whole pipeline rests on every shot being encoded identically so the join
+    is a remux. A blend needs adjacent shots to overlap, which no per-shot filter
+    can express, so it costs one re-encode of the joined stream. Keeping the test
+    here means the renderer branches in exactly one place.
+    """
+    return style in XFADE_NAMES
+
+
+def transition_colour(style: str) -> str:
+    """The colour a dip transition passes through."""
+    return "white" if style == "fadewhite" else "black"
+
+
+# Ken Burns smoothness.
+#
+# `zoompan` truncates its crop origin to whole pixels of whatever frame it is
+# handed, so the drift can only ever move in whole pixels of that frame. Two
+# sizes decide how coarse that is:
+#
+#   read   the picture is scaled well above the output frame before zoompan
+#          sees it, so one truncated pixel of movement lands as a third of an
+#          output pixel rather than a whole one;
+#   write  zoompan renders above the output size and is scaled back down, which
+#          halves whatever step is left and averages it away.
+#
+# The read size is also the drift's entire travel budget, and that is the part
+# that actually decides whether a sweep looks smooth: it can cross `read minus
+# crop` pixels and no more, so a shot longer than that many frames cannot
+# advance every frame. `kenburns_sweep` is where that is enforced — the sizes
+# here only set how many pixels it has to spend.
+#
+# Both are bounded by a pixel budget rather than a width, so a 9:16 frame gets
+# the same treatment as a 16:9 one instead of an enormous portrait buffer.
+# 24 megapixels is a deliberate ceiling rather than the largest that would fit:
+# the fit stage runs a split/scale/crop/blur chain at this size, so the buffers
+# and the blur both grow with it, and past here the smoothness gained is smaller
+# than the memory spent.
+KENBURNS_READ_PIXELS = 24_000_000
+KENBURNS_READ_MAX_SCALE = 8.0
+KENBURNS_WRITE_PIXELS = 3840 * 2160
+KENBURNS_WRITE_MAX_SCALE = 2.0
+
+# Shortest a rubber-band leg may run before the drift reads as a wobble rather
+# than a sweep. A leg lasts one frame per pixel of travel, so at the default 12%
+# a 1080p sweep runs about thirteen seconds and nothing near this floor; only a
+# very small `amount` — a 2% drift has about seventy pixels to spend — falls
+# under it, and those shots hold each pixel for a few frames instead of
+# reversing every couple of seconds. See `kenburns_sweep`.
+#
+# Four seconds rather than something longer because a reversal is much cheaper
+# to watch than a stepped cadence: past a few seconds a turn reads as a slow
+# drift changing its mind, while a hold reads as the picture ticking. Raising
+# this trades the first for the second.
+KENBURNS_MIN_LEG_SECONDS = 4.0
+
+
+def _budgeted_scale(width: int, height: int, budget: int, ceiling: float) -> float:
+    """Largest scale at or below `ceiling` that keeps width*height under budget."""
+    pixels = max(1, width * height)
+    return max(1.0, min(ceiling, (budget / pixels) ** 0.5))
+
+
+def kenburns_geometry(width: int, height: int) -> Tuple[int, int, int, int]:
+    """(read_w, read_h, write_w, write_h) for a drifting shot at this frame size.
+
+    The fit stage renders at the read size, zoompan crops from it and emits the
+    write size, and the caller scales that back to the frame. All four are even,
+    which every filter in the chain is happier with.
+    """
+    def _even(value: float) -> int:
+        n = max(2, int(value))
+        return n - n % 2
+
+    read = _budgeted_scale(width, height, KENBURNS_READ_PIXELS, KENBURNS_READ_MAX_SCALE)
+    write = _budgeted_scale(width, height, KENBURNS_WRITE_PIXELS, KENBURNS_WRITE_MAX_SCALE)
+    # Reading below what is written would mean zoompan upscaling to fill its own
+    # output, which is the softness this whole arrangement exists to avoid.
+    read = max(read, write)
+    return (_even(width * read), _even(height * read),
+            _even(width * write), _even(height * write))
+
+# Frame size per aspect x resolution. "preview" is not a resolution the user picks —
+# it comes from the job's quality flag and deliberately renders small and fast so a
+# full-quality pass afterwards reuses the cached narration for free.
+FRAME_SIZES: Dict[str, Dict[str, Tuple[int, int]]] = {
+    "16:9": {"preview": (854, 480), "720p": (1280, 720), "1080p": (1920, 1080), "4k": (3840, 2160)},
+    "9:16": {"preview": (480, 854), "720p": (720, 1280), "1080p": (1080, 1920), "4k": (2160, 3840)},
+    "1:1": {"preview": (480, 480), "720p": (720, 720), "1080p": (1080, 1080), "4k": (2160, 2160)},
+}
+
+# x264 preset/CRF per quality tier. Preview trades a lot of file size for speed.
+ENCODER_TIERS: Dict[str, Tuple[str, int]] = {
+    "preview": ("ultrafast", 30),
+    "standard": ("medium", 21),
+    "high": ("slow", 18),
+}
+
+
+def frame_size(aspect: str, resolution: str, preview: bool = False) -> Tuple[int, int]:
+    """Even-numbered (width, height) for an aspect/resolution pair.
+
+    libx264 with yuv420p requires even dimensions; every entry in FRAME_SIZES is
+    already even, but the rounding here keeps that true if the table grows.
+    """
+    sizes = FRAME_SIZES.get(aspect) or FRAME_SIZES["16:9"]
+    key = "preview" if preview else resolution
+    width, height = sizes.get(key) or sizes["1080p"]
+    return (width - width % 2, height - height % 2)
+
+
+def encoder_tier(quality: str, preview: bool = False) -> Tuple[str, int]:
+    """(x264 preset, CRF). A preview job always renders at the preview tier."""
+    return ENCODER_TIERS["preview"] if preview else (ENCODER_TIERS.get(quality) or ENCODER_TIERS["standard"])
+
+
+class BackgroundSpec(BaseModel):
+    """Fallback background for shots with no image or video of their own."""
+
+    type: Literal["gradient", "solid", "image"] = "gradient"
+    # Two-stop linear gradient; only `colors[0]` is used for a solid.
+    colors: List[str] = Field(default_factory=lambda: ["#1e293b", "#0f172a"])
+    angle: int = 135
+    # A /media/... URL, used when type == "image".
+    url: Optional[str] = None
+
+    @field_validator("colors")
+    @classmethod
+    def _at_least_one_colour(cls, v: List[str]) -> List[str]:
+        return v or ["#1e293b", "#0f172a"]
+
+
+class WaveformSpec(BaseModel):
+    """Animated audio waveform drawn over the background."""
+
+    enabled: bool = False
+    mode: WaveMode = "line"
+    color: str = "#00ff41"
+    opacity: float = 0.7
+    position: WavePosition = "bottom"
+    # Band height as a percentage of the frame height.
+    height_pct: int = 22
+    # Darkened box behind the wave so it stays legible over a bright photo.
+    scrim: float = 0.45
+
+
+# Every text size in a render is expressed as a percentage of the frame height,
+# so a setting chosen once looks the same at 720p, 1080p and 4K, and in every
+# aspect ratio. They are floats rather than ints because a whole percent is a
+# coarse step at these sizes — the difference between 6% and 7% of a 1080p frame
+# is 11 pixels of title.
+def _clamp_pct(low: float, high: float):
+    def _validate(value: float) -> float:
+        return max(low, min(high, float(value)))
+    return _validate
+
+
+class WatermarkSpec(BaseModel):
+    """Corner watermark: an uploaded icon plus a caption line beside it."""
+
+    enabled: bool = False
+    url: Optional[str] = None          # /media/... icon
+    text: str = ""                     # free text; defaults to "by {note title}"
+    position: Position = "bottom-right"
+    opacity: float = 0.85
+    # Icon height as a percentage of the frame height.
+    scale_pct: float = 6.0
+    # Caption size, also as a percentage of the frame height — independent of the
+    # icon, so the two can be balanced against each other.
+    caption_pct: float = 2.3
+    margin_pct: int = 4
+
+    _scale = field_validator("scale_pct")(_clamp_pct(1.0, 30.0))
+    _caption = field_validator("caption_pct")(_clamp_pct(0.5, 15.0))
+
+
+class OverlayTextSpec(BaseModel):
+    """A text overlay held on screen for the whole video.
+
+    `mode` picks what's shown: the note's title, the title with the current
+    chapter added underneath, or `text` verbatim. `text` is only read in
+    "fixed" mode — the other two derive their words from the note itself.
+    """
+
+    enabled: bool = False
+    mode: OverlayTextMode = "fixed"
+    text: str = ""
+    position: Position = "bottom-left"
+    color: str = "#ffffff"
+    # Font size as a percentage of the frame height.
+    size_pct: float = 3.0
+    margin_pct: int = 5
+    shadow: bool = True
+
+    _size = field_validator("size_pct")(_clamp_pct(0.5, 20.0))
+
+
+class CardTextSpec(BaseModel):
+    """Type sizes for a full-screen card (the title screen or a chapter screen)."""
+
+    title_pct: float = 6.8
+    subtitle_pct: float = 2.9
+
+    _title = field_validator("title_pct")(_clamp_pct(1.0, 25.0))
+    _subtitle = field_validator("subtitle_pct")(_clamp_pct(0.5, 15.0))
+
+
+class TransitionSpec(BaseModel):
+    """How one shot gives way to the next."""
+
+    style: Transition = "none"
+    # Seconds. A dip spends this long fading out and the same fading back in; a
+    # crossfade overlaps its neighbours by it. Clamped again at render time
+    # against the shortest shot, which is the real ceiling.
+    duration: float = 0.6
+
+    @field_validator("duration")
+    @classmethod
+    def _sane_duration(cls, v: float) -> float:
+        return max(0.1, min(3.0, float(v)))
+
+
+class KenBurnsSpec(BaseModel):
+    """Slow drift over a still, so a photo-backed section isn't frozen."""
+
+    effect: KenBurnsEffect = "none"
+    # Fraction of the frame travelled: 0.12 is a 12% push. Clamped at render
+    # time to the headroom the prescale actually provides.
+    amount: float = 0.12
+    # Title and chapter screens have their text drawn into the picture, so they
+    # are left still by default; when included they only ever zoom from the
+    # centre, never pan, or the type would drift out of frame.
+    include_cards: bool = False
+
+    @field_validator("amount")
+    @classmethod
+    def _sane_amount(cls, v: float) -> float:
+        return max(0.02, min(0.5, float(v)))
+
+
+class MusicSpec(BaseModel):
+    """A background bed mixed under the narration."""
+
+    enabled: bool = False
+    url: Optional[str] = None          # /media/... audio file
+    # Bed level relative to the narration.
+    volume: float = 0.18
+    # Duck the bed under speech with a sidechain compressor. Falls back to a
+    # flat mix when the host ffmpeg has no sidechaincompress.
+    duck: bool = True
+    fade_in: float = 1.5
+    fade_out: float = 3.0
+
+    @field_validator("volume")
+    @classmethod
+    def _sane_volume(cls, v: float) -> float:
+        return max(0.0, min(1.0, float(v)))
+
+    @field_validator("fade_in", "fade_out")
+    @classmethod
+    def _sane_fade(cls, v: float) -> float:
+        return max(0.0, min(15.0, float(v)))
+
+
+class QuoteSpec(BaseModel):
+    """Pull-quote panel drawn over the section a blockquote interrupts."""
+
+    enabled: bool = False
+    position: QuotePosition = "center"
+    # Quotation size as a percentage of the frame height, like every other size
+    # in a render, so one setting holds at 720p, 1080p and 4K.
+    size_pct: float = 4.2
+    color: str = "#ffffff"
+    accent: str = "#818cf8"
+    # Darkened panel behind the words so they stay legible over a bright photo.
+    scrim: float = 0.55
+
+    _size = field_validator("size_pct")(_clamp_pct(1.0, 15.0))
+
+    @field_validator("scrim")
+    @classmethod
+    def _sane_scrim(cls, v: float) -> float:
+        return max(0.0, min(1.0, float(v)))
+
+
+class CodeSpec(BaseModel):
+    """Code panel drawn over the section a code block interrupts.
+
+    Unlike QuoteSpec there is no `enabled` toggle: a code block always gets
+    its panel, on screen until the next shot replaces it — this only styles
+    it. Whether it's also *read aloud* is `RenderOptions.narrate_code`, a
+    separate concern the way a blockquote's own narration is always on but a
+    code block's is opt-in.
+    """
+
+    position: QuotePosition = "center"
+    size_pct: float = 3.4
+    color: str = "#e2e8f0"
+    # Darkened panel behind the text so it stays legible over a bright photo.
+    scrim: float = 0.72
+
+    _size = field_validator("size_pct")(_clamp_pct(1.0, 12.0))
+
+    @field_validator("scrim")
+    @classmethod
+    def _sane_scrim(cls, v: float) -> float:
+        return max(0.0, min(1.0, float(v)))
+
+
+class BumperSpec(BaseModel):
+    """A pre-made clip played before (intro) or after (outro) the article.
+
+    It plays whole, with its own sound, fitted to the frame like any other clip
+    in a note — but it is the user's own branding, so nothing of the render's is
+    drawn over it: no watermark, no text overlay, no waveform, and the music bed
+    stops short of it. Transitions still apply, so it joins the video the same
+    way every other segment does.
+    """
+
+    enabled: bool = False
+    url: Optional[str] = None          # /media/... video
+    # The uploaded file's own name. The file is stored under a UUID, so this is
+    # the only readable label the dialog has for it.
+    name: str = ""
+
+
+class RenderOptions(BaseModel):
+    """The complete render configuration. Persisted as JSON on the job row."""
+
+    aspect: Aspect = "16:9"
+    resolution: Resolution = "1080p"
+    quality: Quality = "standard"
+    fps: int = 30
+    fit: Fit = "blur"
+
+    fallback: BackgroundSpec = Field(default_factory=BackgroundSpec)
+    waveform: WaveformSpec = Field(default_factory=WaveformSpec)
+    watermark: WatermarkSpec = Field(default_factory=WatermarkSpec)
+    overlay_text: OverlayTextSpec = Field(default_factory=OverlayTextSpec)
+    # Sized separately: the opening title is usually the largest thing in the
+    # video, while chapter dividers read better a little smaller.
+    title_card_text: CardTextSpec = Field(default_factory=CardTextSpec)
+    chapter_card_text: CardTextSpec = Field(default_factory=CardTextSpec)
+
+    # Motion and audio. `transition` is the one option that can change how the
+    # video is stitched — see is_crossfade.
+    transition: TransitionSpec = Field(default_factory=TransitionSpec)
+    ken_burns: KenBurnsSpec = Field(default_factory=KenBurnsSpec)
+    music: MusicSpec = Field(default_factory=MusicSpec)
+    quotes: QuoteSpec = Field(default_factory=QuoteSpec)
+    code: CodeSpec = Field(default_factory=CodeSpec)
+
+    # Clips bracketing the whole video: the intro plays before the title
+    # screen, the outro after the last section. See BumperSpec.
+    intro: BumperSpec = Field(default_factory=BumperSpec)
+    outro: BumperSpec = Field(default_factory=BumperSpec)
+
+    # Append the finished video to the note as a playable block. Done by the
+    # worker rather than the browser so a render survives the tab being closed.
+    insert_into_note: bool = True
+
+    title_card: bool = True
+    chapter_screens: bool = False
+    # Speak each heading aloud. Off, headings are still shown (chapter screens,
+    # the on-video chapter name) and marked, just not narrated.
+    read_chapters: bool = True
+    embed_chapters: bool = True
+    thumbnail: bool = True
+    subtitles: SubtitleMode = "sidecar"
+
+    # Narration
+    voice: Optional[str] = None        # None = the account's configured voice
+    speed: float = 1.0
+    paragraph_pause_ms: int = 350
+    # Held at a heading, going in and coming out. A full stop is all a voice has
+    # to separate "...ends here." from "A New Chapter.", so the two run together
+    # in one breath — which is the main thing that makes a long read sound
+    # machine-made. Set to 0 to run headings on as ordinary prose.
+    heading_pause_ms: int = 800
+    # Held after the *last* word of every shot — a plain section, a title
+    # screen, a chapter card — before the cut to whatever comes next. Without
+    # this a shot's audio stops the instant speech does, often mid-decay on a
+    # voice's own trailing intonation, and the cut lands right on top of it: it
+    # reads as the sentence getting clipped rather than finishing. This is the
+    # gap paragraph_pause_ms and heading_pause_ms don't cover — both only ever
+    # sit *between* two chunks inside one shot, never after the shot's last one.
+    shot_end_pause_ms: int = 600
+    # A code block always gets its own on-screen panel (see CodeSpec); this
+    # only controls whether its text is *read aloud* too. Off, the panel is
+    # still shown, silently, for at least min_shot_seconds.
+    narrate_code: bool = False
+
+    # Shortest a shot may be, so a media block with little or no text under it
+    # doesn't flash past. Also the duration of a silent title/chapter card.
+    min_shot_seconds: float = 2.5
+    card_seconds: float = 3.5
+
+    # blockId -> /media URL for `diagram` blocks the client rasterised for us.
+    diagram_images: Dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("fps")
+    @classmethod
+    def _sane_fps(cls, v: int) -> int:
+        return max(12, min(60, v))
+
+    @field_validator("speed")
+    @classmethod
+    def _sane_speed(cls, v: float) -> float:
+        return max(0.5, min(2.0, v))
+
+    @field_validator("paragraph_pause_ms")
+    @classmethod
+    def _sane_pause(cls, v: int) -> int:
+        return max(0, min(3000, v))
+
+    @field_validator("heading_pause_ms")
+    @classmethod
+    def _sane_heading_pause(cls, v: int) -> int:
+        return max(0, min(5000, v))
+
+    @field_validator("shot_end_pause_ms")
+    @classmethod
+    def _sane_shot_end_pause(cls, v: int) -> int:
+        return max(0, min(3000, v))
+
+    @field_validator("min_shot_seconds", "card_seconds")
+    @classmethod
+    def _sane_seconds(cls, v: float) -> float:
+        return max(0.5, min(30.0, v))
diff --git a/backend/app/render/pause_markup.py b/backend/app/render/pause_markup.py
new file mode 100644
index 0000000..604951d
--- /dev/null
+++ b/backend/app/render/pause_markup.py
@@ -0,0 +1,331 @@
+"""Configurable pause insertion for spoken-word narration.
+
+Deepgram (Flux, used by `_deepgram_tts` in `app/routers/settings.py`, and
+Aura-2, the other TTS family this app can call) has no SSML support at all —
+`<break>`/`<prosody>` tags would just be read aloud or rejected, not honoured.
+So pauses here are made real the same way `chunk_narration` already does it:
+by splitting narration into separate TTS requests (`Chunk`) and letting the
+caller stitch real silence between them (`build_silence` + the concat step in
+`synthesize_shot`), rather than by emitting markup.
+
+`parse_pause_markup` turns punctuation, blank lines, and explicit
+`[pause:...]` markers in the source prose into a `List[Chunk]`. The prose
+itself is left untouched other than removing the markers.
+
+The marker grammar is deliberately forgiving. Anything it fails to recognise
+is not silently ignored — it is *spoken*, because the literal text travels on
+to the TTS engine — so `[Pause: 2s]` missing by a capital letter and a space
+is far worse than a marker that never existed. Separator, spacing, case, unit
+and even the value itself are all optional; see `_MARKER`.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+@dataclass
+class Chunk:
+    """One TTS request, and the silence held after it."""
+
+    text: str
+    pause_after_ms: int = 0
+
+
+# Implicit pause after each trigger, in milliseconds. `\n\n` is the pause for
+# *one* blank line; each additional blank line multiplies it (see
+# `parse_pause_markup`), so paragraph breaks with more blank lines pause
+# longer. Single source of truth — no duration is hardcoded elsewhere.
+#
+# A trigger absent from the `pause_ms` a caller passes in is not merely a
+# zero-length pause — it isn't a boundary at all, so the text around it is
+# never split. That's what lets a caller opt a plain sentence-ending "."
+# out of becoming a TTS-request boundary (see `narration.build_narration_chunks`)
+# while still honouring "…"/"..." and "[pause:...]", rather than forcing
+# every sentence into its own request with a 0ms gap, which would cost
+# ordinary prose its natural one-breath prosody.
+#
+# These are *added* silence, on top of the gap a chunk boundary already
+# creates: every chunk is its own TTS request, so its audio arrives with the
+# engine's own trailing fall and leading lead-in, and the player needs a moment
+# to swap clips (the export stitches the same silence in with ffmpeg, so both
+# sides hear the same thing). Read the numbers as "how much longer than an
+# ordinary sentence break", not as the length of the gap a listener hears.
+#
+# Hence the ordinary "." is small. It is the one trigger nobody opts into —
+# every sentence in every note ends with one — so it has to sound like prose,
+# not like a beat. It sits below even `NAMED_PAUSE_MS["short"]`, so a writer
+# who actually types `[pause:short]` still gets something audibly longer than
+# the full stop they'd have got for free. The deliberate marks — an ellipsis, a
+# blank line — are where the long pauses belong.
+DEFAULT_PAUSE_MS: Dict[str, int] = {".": 250, "…": 1300, "\n\n": 1600}
+
+# Named levels for the `[pause:short|medium|long|xlong]` marker.
+NAMED_PAUSE_MS: Dict[str, int] = {"short": 350, "medium": 750, "long": 1200, "xlong": 2000}
+
+# What a marker means when it names no duration (`[pause]`) or names one that
+# isn't in `named_pause_ms` (`[pause:xxlong]`). An unrecognised level resolves
+# here rather than raising: a typo in a note must not take down a render
+# worker halfway through a job.
+DEFAULT_MARKER_MS = NAMED_PAUSE_MS["medium"]
+
+# Ceiling on one explicit marker. A bare number is milliseconds, so somebody
+# reaching for seconds and writing `[pause:120000]` would otherwise wedge two
+# minutes of silence into the middle of a render.
+MAX_PAUSE_MS = 10_000
+
+# Deepgram Flux's `speed` query param (see `DEEPGRAM_TTS_SPEED_MIN/MAX` in
+# `app/routers/settings.py`, range 0.85-1.15) is the real, working equivalent
+# of the SSML `<prosody rate='0.88'>` wrap this feature was originally
+# specified with. Not applied automatically here — this module has no network
+# dependency — a caller synthesising pause-markup narration should pass this
+# as `speed` to `_deepgram_tts`/`synthesize_tts_bytes`.
+DEFAULT_NARRATION_SPEED = 0.88
+
+# `[pause]`, `[pause:long]`, `[Pause: 2s]`, `[PAUSE 1500]`, `[pause=400ms]` —
+# the separator, the value and the unit are each optional, and the whole thing
+# is matched case-insensitively (see `_EVENT`). Only spaces and tabs are
+# allowed inside, never a newline: a marker must not be able to swallow the
+# blank line that a paragraph break is made of.
+_MARKER = (
+    r"(?P<marker>\[[ \t]*pause[ \t]*"
+    r"(?:(?:[:=][ \t]*|[ \t]+)(?P<mval>[A-Za-z]+|\d+(?:\.\d+)?)[ \t]*"
+    r"(?P<munit>ms|seconds|second|secs|sec|s)?[ \t]*)?"
+    r"\])"
+)
+_PARA_BREAK = r"\n[ \t]*\n+"
+# Quote and bracket characters that close a sentence *after* its full stop.
+# Both triggers below swallow them so `He said "go." Then left.` keeps the
+# closing quote on the chunk it belongs to instead of opening the next one.
+_CLOSERS = r"[\"'’”)\]]*"
+# Two or more periods, however they're spaced, are one ellipsis. Matching them
+# as a single event is what stops "Wait...." leaving a stray "." to open the
+# next chunk — which the TTS engine then reads aloud as its own utterance.
+_ELLIPSIS = rf"(?:\.(?:[ \t]*\.)+|…){_CLOSERS}"
+# A lone period. Never inside a number ("3.5", "$1,200.50"); `_ends_a_sentence`
+# rules out the rest.
+_SENTENCE_END = rf"(?<!\d)\.(?!\d){_CLOSERS}"
+
+_EVENT = re.compile(
+    f"(?:{_MARKER})|(?P<para>{_PARA_BREAK})"
+    f"|(?P<ell>{_ELLIPSIS})|(?P<dot>{_SENTENCE_END})",
+    re.IGNORECASE,
+)
+_LOOKAHEAD_MARKER = re.compile(rf"[ \t]*{_MARKER}", re.IGNORECASE)
+_MARKER_ONLY = re.compile(_MARKER, re.IGNORECASE)
+
+# A voice can say letters and digits; punctuation, symbols and emoji on their
+# own are not speech. `[^\W_]` excludes emoji naturally — they are
+# symbol-category, not word characters — while keeping accented, Greek and CJK
+# text speakable.
+_SPEAKABLE = re.compile(r"[^\W_]", re.UNICODE)
+
+
+def has_speech(text: str) -> bool:
+    """Is there anything here a TTS engine could actually pronounce?
+
+    A chunk of pure punctuation is not a smaller request, it is a broken one:
+    the provider has nothing to synthesise and answers with an empty or
+    non-audio body, which then reaches ffmpeg as an undecodable file and fails
+    the whole render with a message about pixel formats. So a beat written as
+    "...", a "---" separator, or a paragraph holding nothing but an emoji must
+    never become a request of its own.
+    """
+    return bool(_SPEAKABLE.search(text or ""))
+
+
+# Words that end in a period without ending a sentence. Lowercased for lookup.
+_ABBREVIATIONS = frozenset({
+    "dr", "mr", "mrs", "ms", "prof", "rev", "sr", "jr", "st", "mt", "ft",
+    "vs", "etc", "al", "cf", "approx", "est", "dept", "no", "fig", "vol",
+    "ch", "pp", "inc", "ltd", "co", "corp", "univ",
+    "jan", "feb", "mar", "apr", "jun", "jul", "aug", "sep", "sept", "oct",
+    "nov", "dec",
+    "mon", "tue", "tues", "wed", "thu", "thur", "thurs", "fri", "sat", "sun",
+})
+
+# Longest abbreviation above, plus room for the word to start mid-slice.
+_ABBREV_WINDOW = 32
+_WORD_BEFORE = re.compile(r"([A-Za-z]+)$")
+_AFTER_DOT = re.compile(r"\s|$")
+
+
+def _ends_a_sentence(body: str, start: int, end: int) -> bool:
+    """Is the "." at `body[start:end]` a sentence end, or part of a word?
+
+    A period only ends a sentence when what follows it (past any closing quote
+    or bracket, which `_SENTENCE_END` has already consumed) is whitespace or the
+    end of the text, and what precedes it is neither a single letter — an initial, or one leg of "e.g."/"U.S." — nor a
+    known abbreviation. Without this the read-aloud player pauses inside "3.5",
+    after "Dr", and three separate times inside "www.example.com".
+    """
+    if not _AFTER_DOT.match(body, end):
+        return False
+    word = _WORD_BEFORE.search(body[max(0, start - _ABBREV_WINDOW):start])
+    if word is None:
+        return True
+    token = word.group(1)
+    return len(token) > 1 and token.lower() not in _ABBREVIATIONS
+
+
+def _resolve_marker(
+    value: Optional[str], unit: Optional[str], named_pause_ms: Dict[str, int],
+) -> int:
+    """Resolve one `[pause:...]` marker to milliseconds.
+
+    A bare number is milliseconds — `[pause:1500]` is a second and a half — and
+    an `s`/`sec`/`second` suffix opts into seconds instead. A bare *decimal* is
+    read as seconds as well: `[pause:1.5]` can only have meant 1.5 seconds,
+    since a millisecond and a half is far below anything a listener could hear.
+
+    A marker with no value at all, or with a level this caller doesn't define,
+    falls back to `DEFAULT_MARKER_MS` rather than raising — see that constant.
+    """
+    if value is None:
+        return DEFAULT_MARKER_MS
+    if not value[0].isdigit():
+        return named_pause_ms.get(value.lower(), DEFAULT_MARKER_MS)
+
+    amount = float(value)
+    suffix = (unit or "").lower()
+    if suffix == "ms":
+        milliseconds = amount
+    elif suffix or "." in value:
+        milliseconds = amount * 1000
+    else:
+        milliseconds = amount
+    return max(0, min(MAX_PAUSE_MS, int(round(milliseconds))))
+
+
+def strip_pause_markup(text: str) -> str:
+    """Remove `[pause:...]` markers from text that is *drawn* rather than spoken.
+
+    `parse_pause_markup` already strips them out of narration, but a heading and
+    a quote are also rendered to the screen — see `segmenter`'s `card_title` and
+    `quote_text` — and those paths never went through the parser, so a marker
+    typed into a heading was drawn onto the video.
+    """
+    if not text:
+        return text
+    cleaned = _MARKER_ONLY.sub("", text)
+    # Close up the gap a mid-line marker leaves behind, without touching
+    # newlines: a card's line breaks are laid out on purpose.
+    cleaned = re.sub(r"[ \t]{2,}", " ", cleaned)
+    return "\n".join(line.strip() for line in cleaned.split("\n")).strip()
+
+
+def parse_pause_markup(
+    text: str,
+    *,
+    pause_ms: Dict[str, int] = DEFAULT_PAUSE_MS,
+    named_pause_ms: Dict[str, int] = NAMED_PAUSE_MS,
+) -> List[Chunk]:
+    """Split narration into `Chunk`s at sentence/paragraph/marker boundaries.
+
+    Implicit pauses come from `pause_ms` — `.`/`...`/`…` end a sentence,
+    `\\n\\n` (a blank line) ends a paragraph, with each additional blank line
+    multiplying that pause. Explicit `[pause:1500]` / `[pause:LEVEL]` markers
+    are always stripped from the output text; one directly following (only
+    whitespace between) an implicit trigger overrides that trigger's pause
+    instead of adding to it — e.g. a period immediately followed by
+    `[pause:xlong]` produces one 2000ms gap, not 900 + 2000. A marker
+    anywhere else just becomes its own chunk boundary.
+
+    A trigger missing from `pause_ms` entirely is not a boundary at all —
+    the text around it just runs on into whatever comes next, as if that
+    trigger didn't exist — rather than a boundary with a 0ms gap. That's the
+    difference between "pause here for no time" (still a new TTS request,
+    still a seam in the prosody) and "don't split here", and it's what lets
+    a caller opt the bare "." out without forcing every sentence into its
+    own request. An explicit `[pause:...]` marker immediately following a
+    disabled trigger still overrides it, same as with an enabled one.
+
+    A period that doesn't actually end a sentence — inside a decimal, an
+    initial, or an abbreviation — is never a boundary regardless of
+    `pause_ms`; see `_ends_a_sentence`.
+
+    Two boundaries with no words between them (e.g. a sentence-ending period
+    immediately followed by a blank line) don't produce an empty chunk — the
+    longer of the two pauses is kept on the previous chunk instead. The same
+    holds for anything between them that isn't speech: a "..." beat on its own
+    line, a "---" rule, a lone emoji. Those mark a pause without being one, so
+    the pause survives on the previous chunk and no chunk is emitted for them —
+    see `has_speech`, and never remove that guard: a wordless TTS request comes
+    back as a non-audio body and fails the render at the ffmpeg decode.
+
+    The final chunk always carries `pause_after_ms == 0`; the shot's trailing
+    pause is a separate, caller-level concern (e.g.
+    `RenderOptions.shot_end_pause_ms`).
+    """
+    body = text or ""
+    chunks: List[Chunk] = []
+    current: List[str] = []
+
+    def emit(ms: int) -> None:
+        nonlocal current
+        segment = "".join(current).strip()
+        current = []
+        if has_speech(segment):
+            chunks.append(Chunk(segment, ms))
+        elif chunks:
+            # Nothing sayable between this boundary and the last one — a beat
+            # written as "..." on its own line, a "---" rule, a lone emoji.
+            # It still marks a pause, so the pause is kept on the chunk before
+            # it; what must not happen is a TTS request with no words in it.
+            chunks[-1] = Chunk(chunks[-1].text, max(chunks[-1].pause_after_ms, ms))
+        # A pause before any spoken text has nothing to attach to — dropped.
+
+    pos = 0
+    for m in _EVENT.finditer(body):
+        if m.start() < pos:
+            continue  # already consumed as an override lookahead below
+        # A period mid-word isn't a boundary at all: leave it where it is and
+        # let the next event's `gap` carry it into the chunk being built.
+        if m.group("dot") is not None and not _ends_a_sentence(body, m.start(), m.end()):
+            continue
+
+        gap = body[pos:m.start()]
+
+        if m.group("marker") is not None:
+            current.append(gap)
+            pos = m.end()
+            emit(_resolve_marker(m.group("mval"), m.group("munit"), named_pause_ms))
+            continue
+
+        current.append(gap)
+        para = m.group("para")
+        is_para = para is not None
+        if is_para:
+            blank_lines = para.count("\n") - 1
+            base = pause_ms.get("\n\n")
+            ms = None if base is None else base * max(1, blank_lines)
+        else:
+            ellipsis = m.group("ell")
+            current.append(ellipsis if ellipsis is not None else m.group("dot"))
+            ms = pause_ms.get("…" if ellipsis is not None else ".")
+        pos = m.end()
+
+        override = _LOOKAHEAD_MARKER.match(body, pos)
+        if override:
+            ms = _resolve_marker(
+                override.group("mval"), override.group("munit"), named_pause_ms,
+            )
+            pos = override.end()
+
+        if ms is not None:
+            emit(ms)
+        elif is_para:
+            # A blank line that isn't a pause boundary is still whitespace
+            # between two words — drop it entirely (as opposed to a period,
+            # which keeps its own character either way) and "text.\n\nHeading"
+            # glues into "text.Heading" with no space at all.
+            current.append(" ")
+
+    current.append(body[pos:])
+    tail = "".join(current).strip()
+    if has_speech(tail):
+        chunks.append(Chunk(tail, 0))
+    elif chunks:
+        chunks[-1] = Chunk(chunks[-1].text, 0)
+
+    return chunks
diff --git a/backend/app/render/renderer.py b/backend/app/render/renderer.py
new file mode 100644
index 0000000..c7b06c5
--- /dev/null
+++ b/backend/app/render/renderer.py
@@ -0,0 +1,475 @@
+"""A VideoSpec in, an MP4 out.
+
+Notes' pipeline (`gecko-notes/backend/app/video/renderer.py`), re-driven by GVC's own
+compiled timeline instead of Notes' shot list:
+
+    fetch media -> plan units -> narrate each beat -> encode each unit
+        -> stitch (per-join transitions) -> mix the soundtrack -> chapters, subtitles
+
+Every unit is encoded to its own MP4 with identical codec settings, so a stitch with
+no blends is a `concat -c copy` remux, and a unit is the unit of progress and of the
+shot cache. Everything happens in a scratch directory removed on every exit; only the
+finished files are moved out.
+
+Narration is synthesised **per beat** rather than per unit, and the beats' WAVs then
+joined. That costs nothing extra in TTS (the same chunks are read either way) and is
+what tells us exactly when each beat starts, which anchors pointing at a beat (a sound
+effect on a line) need.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+from app.render import compose, shot_cache
+from app.render import ffmpeg as F
+from app.render.compile import (
+    Unit, beat_pause_ms, chapters, layout, place_tracks, placement, plan_units, unit_duration,
+    xfade_name,
+)
+from app.render.media import MediaCache, resolve
+from app.render.narration import Cue, build_silence, shift_cues, synthesize_shot, write_srt
+from app.render.options import (
+    BackgroundSpec, CardTextSpec, CodeSpec, KenBurnsSpec, OverlayTextSpec, QuoteSpec,
+    RenderOptions, TransitionSpec, WatermarkSpec, WaveformSpec, frame_size, kenburns_geometry,
+)
+from app.render.tts import NotesSpeech
+from app.gam.client import GamClient
+from app.spec.model import VideoSpec
+
+logger = logging.getLogger(__name__)
+
+Progress = Callable[[str, int, str], None]
+
+NARRATION_SHARE = 40
+RENDER_SHARE = 45
+
+
+class RenderRefused(Exception):
+    """The spec cannot be rendered as it stands; the message says what to fix."""
+
+
+@dataclass
+class RenderOutput:
+    video: str
+    subtitles: Optional[str]
+    poster: Optional[str]
+    duration: float
+    size_bytes: int
+    narration_chars: int
+    warnings: List[str] = field(default_factory=list)
+
+
+def base_options(spec: VideoSpec) -> RenderOptions:
+    """The spec's project-wide settings as the per-shot options the builders take.
+
+    `RenderOptions` is Notes' type and stays internal: a unit gets its own copy with
+    its fit, motion and joins, so nothing here is the source of truth for anything.
+    """
+    style, chrome, voice = spec.style, spec.chrome, spec.voice
+    watermark = chrome.watermark
+    overlay = chrome.overlay_text
+    wave = chrome.waveform
+    return RenderOptions(
+        aspect=spec.output.aspect, resolution=spec.output.resolution,
+        quality=spec.output.quality, fps=spec.output.fps, fit=style.fit,
+        fallback=BackgroundSpec(type=style.background.type if style.background.type != "image"
+                                else "gradient",
+                                colors=style.background.colors, angle=style.background.angle),
+        waveform=(WaveformSpec(enabled=True, mode=wave.mode, color=wave.color, opacity=wave.opacity,
+                               position=wave.position, height_pct=wave.height_pct, scrim=wave.scrim)
+                  if wave else WaveformSpec()),
+        watermark=(WatermarkSpec(enabled=True, text=watermark.text, position=watermark.position,
+                                 opacity=watermark.opacity, scale_pct=watermark.scale_pct,
+                                 caption_pct=watermark.caption_pct, margin_pct=watermark.margin_pct)
+                   if watermark else WatermarkSpec()),
+        overlay_text=(OverlayTextSpec(enabled=True, mode=overlay.mode,
+                                      text=overlay.text if overlay.mode == "fixed" else spec.title,
+                                      position=overlay.position, color=overlay.color,
+                                      size_pct=overlay.size_pct, margin_pct=overlay.margin_pct,
+                                      shadow=overlay.shadow)
+                      if overlay else OverlayTextSpec()),
+        title_card_text=CardTextSpec(**style.cards.title.model_dump()),
+        chapter_card_text=CardTextSpec(**style.cards.chapter.model_dump()),
+        transition=TransitionSpec(style=style.transition.style, duration=style.transition.duration),
+        ken_burns=KenBurnsSpec(effect="none", amount=style.motion.amount,
+                               include_cards=style.cards.motion),
+        quotes=QuoteSpec(enabled=True, **style.quote.model_dump()),
+        code=CodeSpec(**style.code.model_dump()),
+        subtitles=spec.output.subtitles, embed_chapters=spec.output.chapters,
+        thumbnail=spec.output.thumbnail, speed=voice.speed,
+        paragraph_pause_ms=voice.pauses.paragraph_ms, heading_pause_ms=voice.pauses.heading_ms,
+        shot_end_pause_ms=voice.pauses.segment_end_ms,
+        min_shot_seconds=style.min_segment_seconds, card_seconds=style.cards.seconds,
+    )
+
+
+def _chapters_file(path: str, marks) -> bool:
+    usable = [(s, e, t) for s, e, t in marks if t.strip() and e > s + 0.5]
+    if not usable:
+        return False
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(";FFMETADATA1\n")
+        for start, end, title in usable:
+            safe = (title.replace("\\", "\\\\").replace("=", "\\=")
+                         .replace(";", "\\;").replace("#", "\\#").replace("\n", " "))
+            f.write("[CHAPTER]\nTIMEBASE=1/1000\n")
+            f.write(f"START={int(start * 1000)}\nEND={int(end * 1000)}\ntitle={safe}\n")
+    return True
+
+
+@dataclass
+class _Narrated:
+    path: Optional[str]
+    duration: float
+    cues: List[Cue]
+    beats: Dict[str, Tuple[float, float]]
+
+
+def _narrate(spec: VideoSpec, unit: Unit, index: int, work_dir: str, options: RenderOptions,
+             speech: NotesSpeech) -> _Narrated:
+    """Read a unit's beats, one after another, and join them into one WAV."""
+    parts: List[str] = []
+    cues: List[Cue] = []
+    spans: Dict[str, Tuple[float, float]] = {}
+    cursor = 0.0
+    for position, beat in enumerate(unit.beats):
+        pause = beat_pause_ms(spec, unit.beats, position)
+        if beat.speak and beat.text.strip():
+            beat_options = options.model_copy(update={
+                "speed": unit.speed, "shot_end_pause_ms": pause,
+                # Beats are joined below; only the unit as a whole has a minimum.
+                "min_shot_seconds": 0.5,
+            })
+            result = synthesize_shot(beat.text, index=index * 1000 + position, work_dir=work_dir,
+                                     options=beat_options, tts=speech.caller(unit.voice))
+            if result.path:
+                parts.append(result.path)
+            cues.extend(shift_cues(result.cues, cursor))
+            length = result.duration
+        else:
+            # A silent beat holds the picture for its `hold`, then its pause.
+            length = (beat.hold or 0.0) + pause / 1000.0
+            pad = build_silence(work_dir, int(length * 1000)) if length > 0 else None
+            if pad:
+                parts.append(pad)
+            else:
+                length = 0.0
+        spans[beat.id] = (cursor, cursor + length)
+        cursor += length
+
+    if not parts:
+        return _Narrated(path=None, duration=0.0, cues=[], beats=spans)
+    list_name = f"unit_{index:04d}.txt"
+    out = f"unit_{index:04d}.wav"
+    F.write_concat_list(os.path.join(work_dir, list_name), parts)
+    F.run(F.build_narration_command(list_name, out), cwd=work_dir, timeout=600)
+    duration = F.probe_duration(os.path.join(work_dir, out)) or cursor
+    return _Narrated(path=out, duration=duration, cues=cues, beats=spans)
+
+
+def _background(unit: Unit, spec: VideoSpec, options: RenderOptions, work_dir: str, index: int,
+                width: int, height: int, background_image: Optional[str]) -> str:
+    """The still a card, or a scene without a picture, sits on."""
+    base = None
+    if background_image:
+        base = compose.cover_image(background_image, width, height)
+    if base is None:
+        fallback = options.fallback
+        base = (compose.solid_background(width, height, fallback.colors[0])
+                if fallback.type == "solid"
+                else compose.gradient_background(width, height, fallback.colors, fallback.angle))
+    if unit.kind == "card" and unit.card:
+        image = compose.card_image(
+            width, height, title=unit.card.title or spec.title or "Untitled",
+            subtitle=unit.card.subtitle or "", background=base,
+            sizes=(options.chapter_card_text if unit.card.variant == "chapter"
+                   else options.title_card_text),
+        )
+    else:
+        image = base
+    name = f"bg_{index:04d}.png"
+    image.convert("RGB").save(os.path.join(work_dir, name), "PNG")
+    return name
+
+
+def render(
+    *, spec: VideoSpec, preview: bool, work_dir: str, out_dir: str, data_dir: str, user_id: str,
+    gam: GamClient, speech: NotesSpeech, progress: Progress,
+    max_segments: int, max_narration_chars: int,
+) -> RenderOutput:
+    if not F.ffmpeg_available():
+        raise RuntimeError("ffmpeg and ffprobe must be installed on the server")
+    os.makedirs(work_dir, exist_ok=True)
+    os.makedirs(out_dir, exist_ok=True)
+    warnings: List[str] = []
+    width, height = frame_size(spec.output.aspect, spec.output.resolution, preview)
+
+    progress("Preparing", 1, "Fetching pictures, footage and music")
+    resolved = resolve(spec, gam, cache=MediaCache(Path(data_dir) / "cache" / "media"),
+                       work_dir=work_dir, preview=preview, frame=(width, height))
+    if resolved.problems:
+        raise RenderRefused(" ".join(resolved.problems))
+    media = resolved.media
+
+    units = plan_units(spec, media, warnings)
+    if not units:
+        raise RenderRefused("This video has nothing in it to render yet.")
+    if len(units) > max_segments:
+        raise RenderRefused(f"This video has {len(units)} shots, above the limit of {max_segments}.")
+    chars = sum(len(b.text) for u in units for b in u.beats if b.speak)
+    if chars > max_narration_chars:
+        raise RenderRefused(f"This video has {chars:,} characters of narration, above the limit "
+                            f"of {max_narration_chars:,}.")
+    if spec.voice.expressivity is not None:
+        warnings.append("Voice expressivity is not passed to the narrator yet.")
+
+    options = base_options(spec)
+    background_image = (media[spec.style.background.asset].path
+                        if spec.style.background.type == "image" and spec.style.background.asset
+                        in media else None)
+    watermark_icon = (media[spec.chrome.watermark.asset].path
+                      if spec.chrome.watermark and spec.chrome.watermark.asset in media else None)
+
+    # ── narrate ──────────────────────────────────────────────────────────────
+    narrated: List[_Narrated] = []
+    speaking = sum(1 for u in units if u.beats)
+    done = 0
+    for index, unit in enumerate(units):
+        if unit.beats:
+            done += 1
+            progress("Narrating", 2 + NARRATION_SHARE * done // max(1, speaking),
+                     f"shot {done} of {speaking}")
+        narrated.append(_narrate(spec, unit, index, work_dir, options, speech))
+
+    durations = [unit_duration(u, n.duration, spec.style.cards.seconds)
+                 for u, n in zip(units, narrated)]
+    timeline = layout(units, durations, warnings)
+
+    # ── encode each unit ─────────────────────────────────────────────────────
+    cache = shot_cache.ShotCache(data_dir, user_id)
+    try:
+        shot_cache.prune(data_dir)
+    except Exception:
+        logger.exception("Could not prune the shot cache")
+    base = 2 + NARRATION_SHARE
+    shot_files: List[str] = []
+    current_chapter: Optional[str] = None
+    for index, (unit, narration) in enumerate(zip(units, narrated)):
+        progress("Rendering", base + RENDER_SHARE * index // len(units),
+                 f"shot {index + 1} of {len(units)}")
+        duration = timeline.durations[index]
+        unit_options = options.model_copy(deep=True)
+        unit_options.fit = unit.fit
+        if not unit.chrome:
+            unit_options.waveform.enabled = False
+
+        path = None
+        if unit.motion is not None and unit.kind in ("still", "card"):
+            if unit.motion.effect == "path":
+                media_item = unit.media
+                if media_item and media_item.width and media_item.height:
+                    path = F.KenBurnsPath(
+                        start=(unit.motion.from_.x, unit.motion.from_.y, unit.motion.from_.w),
+                        end=(unit.motion.to.x, unit.motion.to.y, unit.motion.to.w),
+                        picture=(media_item.width, media_item.height),
+                        ease=unit.motion.ease or "in_out",
+                    )
+                    if F.path_crop_rects(path, *kenburns_geometry(width, height)[:2],
+                                         width / height)[2]:
+                        warnings.append(f"Shot {index + 1}: a Ken Burns frame ran off the "
+                                        "picture and was moved back inside it")
+            else:
+                unit_options.ken_burns.effect = unit.motion.effect
+                unit_options.ken_burns.amount = unit.motion.amount
+
+        has_audio = False
+        if unit.kind in ("card",) or (unit.kind == "still" and unit.media is None):
+            drift = F.kenburns_effect_for(unit.kind, index, unit_options)
+            draw_w, draw_h = (kenburns_geometry(width, height)[:2] if drift else (width, height))
+            background = _background(unit, spec, unit_options, work_dir, index, draw_w, draw_h,
+                                     background_image)
+        elif unit.kind == "still":
+            background = unit.media.path
+        else:
+            background = unit.media.path
+            has_audio = unit.media.has_audio
+            if unit.trim is not None:
+                start, length = unit.trim
+                if length is None:
+                    length = max(0.1, (unit.media.duration or 0.0) - start)
+                clip = f"clip_{index:04d}.mp4"
+                F.run(F.build_extract_command(background, clip, start=start, length=length,
+                                              with_audio=unit.kind == "video_sound"),
+                      cwd=work_dir, timeout=F.shot_timeout(length))
+                background = clip
+
+        # Watermark, overlay text and a quote or code panel, as one layer.
+        if unit.chapter:
+            current_chapter = unit.chapter
+        layer = None
+        if unit.chrome:
+            chapter_line = (current_chapter if options.overlay_text.mode == "title_chapter"
+                            and current_chapter and current_chapter != spec.title else None)
+            watermark = unit_options.watermark.model_copy()
+            if watermark.enabled and not watermark.text.strip() and spec.title:
+                watermark.text = f"by {spec.title}"
+            layer = compose.overlay_layer(width, height, watermark=watermark,
+                                          watermark_icon=watermark_icon,
+                                          overlay_text=unit_options.overlay_text,
+                                          chapter_line=chapter_line)
+        if unit.panel is not None:
+            panel = (compose.quote_panel(width, height, text=unit.panel.text,
+                                         attribution=unit.panel.attribution, spec=options.quotes)
+                     if unit.panel.kind == "quote"
+                     else compose.code_panel(width, height, text=unit.panel.text, spec=options.code))
+            if panel is not None:
+                if layer is not None:
+                    panel.alpha_composite(layer)
+                layer = panel
+        overlay_png = None
+        if layer is not None:
+            overlay_png = f"overlay_{index:04d}.png"
+            layer.save(os.path.join(work_dir, overlay_png), "PNG")
+
+        shot_srt = None
+        if spec.output.subtitles == "burn" and narration.cues:
+            name = f"shot_{index:04d}.srt"
+            if write_srt(os.path.join(work_dir, name), narration.cues):
+                shot_srt = name
+
+        join_in = timeline.joins[index]
+        join_out = timeline.joins[index + 1] if index + 1 < len(units) else None
+        in_transition = (TransitionSpec(style=join_in.style, duration=join_in.duration)
+                         if join_in else TransitionSpec(style="none"))
+        out_transition = (TransitionSpec(style=join_out.style, duration=join_out.duration)
+                          if join_out else TransitionSpec(style="none"))
+        output = f"shot_{index:04d}.mp4"
+
+        def argv(with_options: RenderOptions, with_path=path) -> List[str]:
+            return F.build_shot_command(
+                kind=unit.kind if unit.kind != "card" else "card", background=background,
+                audio=narration.path if unit.kind != "video_sound" else None,
+                duration=duration, output=output, options=with_options, preview=preview,
+                overlay_png=overlay_png, subtitle_file=shot_srt, background_has_audio=has_audio,
+                index=index, in_transition=in_transition, out_transition=out_transition,
+                loop=unit.loop, path=with_path,
+            )
+
+        if narration.path is None and unit.kind != "video_sound":
+            # Every shot needs an audio track for the stitch: silence, then.
+            silence = build_silence(work_dir, int(duration * 1000))
+            narration.path = silence
+
+        key = shot_cache.shot_key(argv(unit_options), [background, narration.path, overlay_png,
+                                                        shot_srt], work_dir)
+        fell_back = cache.restore(key, os.path.join(work_dir, output))
+        if fell_back is None:
+            try:
+                F.run(argv(unit_options), cwd=work_dir, timeout=F.shot_timeout(duration))
+                fell_back = False
+            except F.FFmpegError as exc:
+                logger.warning("Shot %d failed (%s); retrying it plainer", index + 1, exc)
+                plain = unit_options.model_copy(deep=True)
+                plain.ken_burns.effect = "none"
+                plain.waveform.enabled = False
+                F.run(argv(plain, None), cwd=work_dir, timeout=F.shot_timeout(duration))
+                fell_back = True
+            cache.store(key, os.path.join(work_dir, output), plain=fell_back)
+        if fell_back:
+            warnings.append(f"Shot {index + 1} was rendered without motion or a waveform.")
+        shot_files.append(output)
+
+    # ── stitch ───────────────────────────────────────────────────────────────
+    progress("Stitching", base + RENDER_SHARE, f"joining {len(shot_files)} shots")
+    blends = [(xfade_name(j.style), j.overlap) if j and j.is_blend else None
+              for j in timeline.joins]
+    stitched = "stitched.mp4"
+    if any(blends):
+        try:
+            F.run(F.build_stitch_command(shot_files, timeline.durations, stitched, joins=blends,
+                                         options=options, preview=preview),
+                  cwd=work_dir, timeout=F.shot_timeout(sum(timeline.durations)))
+        except F.FFmpegError as exc:
+            # The blends cost a re-encode; if that fails, the shots still join by cuts,
+            # and the timeline is re-laid without their overlaps to match.
+            logger.warning("Blended stitch failed (%s); joining with cuts", exc)
+            warnings.append("Blends were joined as cuts: blending the shots together failed.")
+            for join in timeline.joins:
+                if join and join.is_blend:
+                    join.overlap = 0.0
+            timeline = layout_without_overlaps(timeline)
+            blends = []
+    if not any(blends):
+        F.write_concat_list(os.path.join(work_dir, "shots.txt"), shot_files)
+        F.run(F.build_concat_command("shots.txt", stitched), cwd=work_dir, timeout=1800)
+    final = stitched
+
+    # ── the soundtrack ───────────────────────────────────────────────────────
+    where = placement(units, timeline, [n.beats for n in narrated])
+    tracks = place_tracks(spec, media, where, warnings)
+    if tracks:
+        progress("Mixing", 90, f"{len(tracks)} audio track{'s' if len(tracks) != 1 else ''}")
+        mix = [F.MixTrack(path=t.media.path, start=t.start, length=t.length, trim_in=t.trim_in,
+                          loop=t.loop, volume=t.track.volume, fade_in=t.track.fade_in,
+                          fade_out=t.track.fade_out, duck=t.duck) for t in tracks]
+        F.run(F.build_mix_command(final, mix, "scored.mp4", duration=timeline.total,
+                                  duck_available="sidechaincompress" in F.available_filters()),
+              cwd=work_dir, timeout=1800)
+        final = "scored.mp4"
+
+    # ── chapters and subtitles ───────────────────────────────────────────────
+    all_cues: List[Cue] = []
+    for index, narration in enumerate(narrated):
+        all_cues.extend(shift_cues(narration.cues, timeline.starts[index]))
+    srt_written = write_srt(os.path.join(work_dir, "subtitles.srt"), all_cues)
+    chapters_name = ("chapters.ffmeta"
+                     if spec.output.chapters and _chapters_file(
+                         os.path.join(work_dir, "chapters.ffmeta"), chapters(units, timeline))
+                     else None)
+    subtitle_name = "subtitles.srt" if srt_written and spec.output.subtitles == "soft" else None
+    if chapters_name or subtitle_name:
+        progress("Finishing", 94, "adding chapters and subtitles")
+        F.run(F.build_mux_command(final, "final.mp4", chapters_file=chapters_name,
+                                  subtitle_file=subtitle_name), cwd=work_dir, timeout=900)
+        final = "final.mp4"
+
+    progress("Finishing", 96, "saving")
+    video = os.path.join(out_dir, "video.mp4")
+    shutil.move(os.path.join(work_dir, final), video)
+    cache.discard_used()
+    subtitles = None
+    if srt_written and spec.output.subtitles != "off":
+        subtitles = os.path.join(out_dir, "subtitles.srt")
+        shutil.move(os.path.join(work_dir, "subtitles.srt"), subtitles)
+    poster = None
+    if spec.output.thumbnail:
+        poster = os.path.join(out_dir, "poster.jpg")
+        try:
+            F.run(F.build_poster_command(video, poster,
+                                         at_seconds=min(1.0, max(0.0, timeline.total / 2))),
+                  timeout=120)
+        except (F.FFmpegError, OSError) as exc:
+            logger.warning("Poster frame failed: %s", exc)
+            poster = None
+
+    return RenderOutput(
+        video=video, subtitles=subtitles, poster=poster,
+        duration=F.probe_duration(video) or timeline.total,
+        size_bytes=os.path.getsize(video), narration_chars=speech.characters, warnings=warnings,
+    )
+
+
+def layout_without_overlaps(timeline):
+    """The same units laid end to end, for when blends had to become cuts."""
+    starts, cursor = [], 0.0
+    for duration in timeline.durations:
+        starts.append(cursor)
+        cursor += duration
+    timeline.starts, timeline.total = starts, cursor
+    return timeline
diff --git a/backend/app/render/shot_cache.py b/backend/app/render/shot_cache.py
new file mode 100644
index 0000000..a6c8278
--- /dev/null
+++ b/backend/app/render/shot_cache.py
@@ -0,0 +1,164 @@
+"""Finished shot encodes, kept across a failed render so a retry doesn't redo them.
+
+A render works in a scratch directory that is removed on every exit path, and a
+retry is a brand-new job with a brand-new directory — so a render that died at
+the stitch, after every segment had been encoded, used to throw all of that
+work away and start over.
+
+Each shot is filed here under a fingerprint of everything that decides its
+pixels and samples: the exact ffmpeg command (which carries the filtergraph, the
+duration and the codec settings) and the content of every file it reads. It is
+deliberately *not* keyed on the job id or on the options as a whole. Retrying
+with a different transition, music bed or subtitle setting leaves most shots
+byte-for-byte identical, and those are exactly the retries that matter — the
+usual reason to retry is to change something that isn't in the shots at all.
+
+Entries are hard links to the scratch file, so keeping one costs no extra disk
+while the render runs. A successful render discards the entries it used, since
+they are inside the finished video now; whatever a failed or cancelled one left
+behind is pruned by age.
+"""
+
+import hashlib
+import logging
+import os
+import shutil
+import time
+from typing import List, Optional, Sequence
+
+logger = logging.getLogger(__name__)
+
+CACHE_ROOT_NAME = "_video_cache"
+
+# Long enough to notice a failure, change a setting and try again; short enough
+# that abandoned encodes don't sit on the disk.
+MAX_AGE_SECONDS = 48 * 60 * 60
+
+# Bump when a change to the pipeline means an old encode is no longer valid even
+# though the command and inputs look the same.
+CACHE_VERSION = "1"
+
+_PLAIN_SUFFIX = ".plain"
+
+
+def shot_key(argv: Sequence[str], inputs: Sequence[Optional[str]], work_dir: str) -> str:
+    """Fingerprint of one shot's encode.
+
+    `argv` is the command that would produce it, minus its trailing output name
+    (which only carries the shot's position, so a shot that merely moved would
+    otherwise miss). `inputs` are the files it reads: generated ones inside
+    `work_dir` are hashed by content, since they are rebuilt every run; the
+    user's own media, which can be hundreds of megabytes, by size and mtime.
+    """
+    digest = hashlib.sha256(CACHE_VERSION.encode())
+    for arg in argv[:-1]:
+        digest.update(arg.encode("utf-8", "replace"))
+        digest.update(b"\0")
+    for name in inputs:
+        if not name:
+            continue
+        digest.update(_signature(name, work_dir).encode())
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _signature(name: str, work_dir: str) -> str:
+    full = name if os.path.isabs(name) else os.path.join(work_dir, name)
+    try:
+        stat = os.stat(full)
+    except OSError:
+        return "missing"
+    root = os.path.abspath(work_dir) + os.sep
+    if not os.path.abspath(full).startswith(root):
+        return f"{stat.st_size}:{stat.st_mtime_ns}"
+    digest = hashlib.sha256()
+    with open(full, "rb") as f:
+        for block in iter(lambda: f.read(1 << 20), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _link_or_copy(src: str, dest: str) -> None:
+    """Hard link where the filesystem allows it, else copy. Lands atomically."""
+    tmp = f"{dest}.{os.getpid()}.tmp"
+    try:
+        try:
+            os.link(src, tmp)
+        except OSError:
+            shutil.copy2(src, tmp)
+        os.replace(tmp, dest)
+    finally:
+        try:
+            os.remove(tmp)
+        except OSError:
+            pass
+
+
+class ShotCache:
+    """One user's cache directory, plus a note of which entries this render touched."""
+
+    def __init__(self, media_dir: str, user_id: str) -> None:
+        self.dir = os.path.join(media_dir, CACHE_ROOT_NAME, user_id)
+        self._used: List[str] = []
+
+    def _path(self, key: str) -> str:
+        return os.path.join(self.dir, f"{key}.mp4")
+
+    def restore(self, key: str, dest: str) -> Optional[bool]:
+        """Put a cached encode at `dest`.
+
+        None on a miss. On a hit, whether that encode had to fall back to the
+        plainer settings, so the render can repeat the warning it earned then.
+        """
+        path = self._path(key)
+        if not os.path.isfile(path):
+            return None
+        try:
+            _link_or_copy(path, dest)
+            os.utime(path)  # a retry in progress keeps its entries alive
+        except OSError as exc:
+            logger.warning("Could not reuse cached shot %s: %s", key[:12], exc)
+            return None
+        self._used.append(key)
+        return os.path.isfile(path + _PLAIN_SUFFIX)
+
+    def store(self, key: str, src: str, *, plain: bool) -> None:
+        """File a finished encode. Best effort: a full disk must not fail a render."""
+        try:
+            os.makedirs(self.dir, exist_ok=True)
+            path = self._path(key)
+            _link_or_copy(src, path)
+            if plain:
+                open(path + _PLAIN_SUFFIX, "wb").close()
+            self._used.append(key)
+        except OSError as exc:
+            logger.warning("Could not cache shot %s: %s", key[:12], exc)
+
+    def discard_used(self) -> None:
+        """The render succeeded, so what it used is inside the finished video."""
+        for key in self._used:
+            for path in (self._path(key), self._path(key) + _PLAIN_SUFFIX):
+                try:
+                    os.remove(path)
+                except OSError:
+                    pass
+        self._used = []
+
+
+def prune(media_dir: str, max_age_seconds: int = MAX_AGE_SECONDS) -> None:
+    """Delete cache entries nobody has touched for `max_age_seconds`."""
+    root = os.path.join(media_dir, CACHE_ROOT_NAME)
+    cutoff = time.time() - max_age_seconds
+    for folder, _dirs, files in os.walk(root, topdown=False):
+        for name in files:
+            path = os.path.join(folder, name)
+            try:
+                if os.path.getmtime(path) < cutoff:
+                    os.remove(path)
+            except OSError:
+                pass
+        if folder != root:
+            try:
+                os.rmdir(folder)  # only succeeds once empty
+            except OSError:
+                pass
diff --git a/backend/app/render/tts.py b/backend/app/render/tts.py
new file mode 100644
index 0000000..8db3255
--- /dev/null
+++ b/backend/app/render/tts.py
@@ -0,0 +1,74 @@
+"""Narration, read through Gecko Notes' speech.
+
+Voices, provider keys and the TTS cache live in Notes, so GVC asks Notes to read each
+chunk as the signed-in user (open decision 3 in the plan of attack). Notes' cache is
+keyed on provider, voice and text, which is what makes a preview followed by a full
+render bill for the narration once.
+
+One video must not change voice partway through. The first chunk is sent with
+`provider: "auto"`; Notes answers with the engine and voice it resolved
+(`X-Speech-Provider` / `X-Speech-Voice`, gecko-notes#211), and every later chunk
+sends those back. A transient failure then fails the render, instead of one chunk
+quietly arriving in another engine's voice.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Optional
+
+import httpx
+
+from app import outbound
+from app.config import settings
+
+
+class SpeechError(Exception):
+    pass
+
+
+class NotesSpeech:
+    def __init__(self, token: Optional[str]):
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        self._http = outbound.client(settings.notes_base_url, timeout=120, headers=headers)
+        self.provider: Optional[str] = None
+        # The voice each requested one resolved to (None: the account's).
+        self._voices: Dict[Optional[str], Optional[str]] = {}
+        self.characters = 0
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _say(self, text: str, voice: Optional[str]) -> bytes:
+        pinned = self._voices.get(voice, voice)
+        body = {"text": text, "provider": self.provider or "auto", "voice": pinned}
+        try:
+            response = self._http.post("/api/settings/speech/tts", json=body)
+        except httpx.HTTPError as exc:
+            raise SpeechError("Could not reach Gecko Notes to read the narration") from exc
+        if response.status_code == 401:
+            raise SpeechError("Gecko Notes did not accept your session for reading the "
+                              "narration. Its JWT_SECRET_KEY may differ from GVC's.")
+        if response.status_code != 200:
+            try:
+                detail = response.json().get("detail")
+                message = detail.get("message") if isinstance(detail, dict) else str(detail)
+            except ValueError:
+                message = response.text[:200]
+            raise SpeechError(f"Gecko Notes could not read the narration: {message}")
+        provider = response.headers.get("x-speech-provider")
+        if not provider:
+            # A Notes from before #211 ignores the fields and reads in whatever
+            # `model` defaults to, with nothing to pin. Better to say so than to
+            # render a video that may change voice.
+            raise SpeechError("Gecko Notes needs updating to read narration for a video "
+                              "(gecko-notes#211).")
+        if self.provider is None:
+            self.provider = provider
+        if voice not in self._voices:
+            self._voices[voice] = response.headers.get("x-speech-voice") or None
+        self.characters += len(text)
+        return response.content
+
+    def caller(self, voice: Optional[str]) -> Callable[[str], bytes]:
+        """A `text -> audio bytes` callable for `narration.synthesize_shot`."""
+        return lambda text: self._say(text, voice)
diff --git a/backend/app/render/worker.py b/backend/app/render/worker.py
new file mode 100644
index 0000000..95e580c
--- /dev/null
+++ b/backend/app/render/worker.py
@@ -0,0 +1,128 @@
+"""Running renders in the background, as the user who asked for them.
+
+A render calls GAM (for media) and Notes (for narration) with the requester's own
+token, so it can never reach what they could not. The token is held here, in memory,
+for the job's life only. It is never written to the database: a 30-day credential at
+rest is a worse problem than a render that has to be started again after a restart,
+which is what `requeue_on_restart=False` makes happen.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import uuid
+from pathlib import Path
+from typing import Dict, Optional
+
+from sqlmodel import Session, select
+
+from app.config import settings
+from app.gam.client import GamClient, GamError
+from app.jobs.runner import JobCancelled, JobQueue, readable_error, set_fields
+from app.models.project import Project, ProjectVersion
+from app.models.render import RenderJob
+from app.render.renderer import RenderRefused, render
+from app.render.tts import NotesSpeech, SpeechError
+from app.spec.validation import parse_spec
+
+logger = logging.getLogger(__name__)
+
+_tokens: Dict[str, Optional[str]] = {}
+
+
+def renders_dir() -> Path:
+    return settings.resolved_data_dir / "renders"
+
+
+def _run(job_id: str) -> None:
+    with queue.session() as session:
+        job = session.get(RenderJob, job_id)
+        if job is None or job.status != "queued":
+            return
+        if job_id not in _tokens:
+            set_fields(session, job, status="error",
+                       error_message="Interrupted by a restart of the server. Start it again.")
+            return
+        version = session.exec(select(ProjectVersion).where(
+            ProjectVersion.project_id == job.project_id,
+            ProjectVersion.seq == job.version_seq)).first()
+        if version is None:
+            set_fields(session, job, status="error", error_message="That version no longer exists")
+            return
+        spec, issues = parse_spec(json.loads(version.spec))
+        if spec is None:
+            set_fields(session, job, status="error",
+                       error_message="This version of the project no longer validates")
+            return
+        set_fields(session, job, status="processing", stage="Starting", progress=0)
+        preview, user_id = job.preview, job.user_id
+
+    token = _tokens.get(job_id)
+    data_dir = settings.resolved_data_dir
+    work_dir = data_dir / "work" / job_id
+    out_dir = renders_dir() / job_id
+    gam, speech = GamClient(token), NotesSpeech(token)
+    try:
+        result = render(
+            spec=spec, preview=preview, work_dir=str(work_dir), out_dir=str(out_dir),
+            data_dir=str(data_dir), user_id=user_id, gam=gam, speech=speech,
+            progress=queue.reporter(job_id),
+            max_segments=settings.render_max_segments,
+            max_narration_chars=settings.render_max_narration_chars,
+        )
+    except JobCancelled:
+        _finish(job_id, status="cancelled", stage="")
+        shutil.rmtree(out_dir, ignore_errors=True)
+    except (RenderRefused, SpeechError) as exc:
+        _finish(job_id, status="error", stage="", error_message=str(exc))
+        shutil.rmtree(out_dir, ignore_errors=True)
+    except GamError as exc:
+        _finish(job_id, status="error", stage="", error_message=exc.message)
+        shutil.rmtree(out_dir, ignore_errors=True)
+    except Exception as exc:  # noqa: BLE001 - a failed render is a job error, not a crash
+        logger.exception("Render %s failed", job_id)
+        _finish(job_id, status="error", stage="", error_message=readable_error(exc))
+        shutil.rmtree(out_dir, ignore_errors=True)
+    else:
+        def rel(path: Optional[str]) -> Optional[str]:
+            return Path(path).name if path else None
+
+        _finish(job_id, status="done", stage="", progress=100, detail="",
+                video_path=rel(result.video), subtitle_path=rel(result.subtitles),
+                poster_path=rel(result.poster), duration=result.duration,
+                size_bytes=result.size_bytes, narration_chars=result.narration_chars,
+                warnings=json.dumps(result.warnings))
+    finally:
+        gam.close()
+        speech.close()
+        shutil.rmtree(work_dir, ignore_errors=True)
+        _tokens.pop(job_id, None)
+
+
+def _finish(job_id: str, **fields) -> None:
+    with queue.session() as session:
+        job = session.get(RenderJob, job_id)
+        if job is not None:
+            set_fields(session, job, **fields)
+
+
+queue = JobQueue(RenderJob, _run, name="render", concurrency=settings.render_concurrency,
+                 requeue_on_restart=False)
+
+
+def submit(session: Session, project: Project, *, user_id: str, token: Optional[str],
+           preview: bool) -> RenderJob:
+    job = RenderJob(id=str(uuid.uuid4()), project_id=project.id, user_id=user_id,
+                    version_seq=project.head_seq, preview=preview)
+    session.add(job)
+    session.commit()
+    session.refresh(job)
+    _tokens[job.id] = token
+    queue.enqueue(job.id)
+    return job
+
+
+def start() -> None:
+    queue.start()
diff --git a/backend/app/routers/renders.py b/backend/app/routers/renders.py
new file mode 100644
index 0000000..dfcbe48
--- /dev/null
+++ b/backend/app/routers/renders.py
@@ -0,0 +1,148 @@
+"""Rendering a project, following the render, and fetching what it made."""
+
+import json
+import mimetypes
+import shutil
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, Response, status
+from sqlmodel import Session, select
+
+from app.auth import CallerToken, CurrentUser, sign_media_key, verify_media_signature
+from app.database import get_session
+from app.jobs.runner import ACTIVE_STATUSES
+from app.media.ranged import ranged_response
+from app.models.render import RenderJob
+from app.render import worker
+from app.render.estimate import estimate
+from app.schemas import DataResponse, ListResponse
+from app.schemas_renders import EstimateRead, RenderCreate, RenderRead
+from app.services import projects as project_service
+
+router = APIRouter()
+media_router = APIRouter()
+
+_FILES = ("video.mp4", "subtitles.srt", "poster.jpg")
+
+
+def _signed(job: RenderJob, name: Optional[str]) -> Optional[str]:
+    if not name or job.status != "done":
+        return None
+    key = f"{job.id}/{name}"
+    expires_at, signature = sign_media_key(key)
+    return f"/media/renders/{key}?exp={expires_at}&sig={signature}"
+
+
+def _read(job: RenderJob) -> RenderRead:
+    return RenderRead(
+        id=job.id, project_id=job.project_id, version=job.version_seq, preview=job.preview,
+        status=job.status, stage=job.stage, progress=job.progress, detail=job.detail,
+        error=job.error_message, warnings=json.loads(job.warnings or "[]"),
+        duration=job.duration, size_bytes=job.size_bytes, narration_chars=job.narration_chars,
+        video_url=_signed(job, job.video_path), subtitles_url=_signed(job, job.subtitle_path),
+        poster_url=_signed(job, job.poster_path),
+        created_at=job.created_at, updated_at=job.updated_at,
+    )
+
+
+def _owned(session: Session, user, render_id: str) -> RenderJob:
+    job = session.get(RenderJob, render_id)
+    if job is None or job.user_id != user.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,
+                            detail={"code": "not_found", "message": "Render not found"})
+    return job
+
+
+@router.post("/projects/{project_id}/estimate", response_model=DataResponse[EstimateRead])
+def estimate_project(project_id: str, user: CurrentUser,
+                     session: Session = Depends(get_session)) -> DataResponse[EstimateRead]:
+    """How long the saved version would run, and what would stop it rendering."""
+    project = project_service.get_owned(session, user, project_id)
+    spec = project_service.require_spec(project_service.decode(project.spec))
+    result = estimate(spec)
+    return DataResponse(data=EstimateRead(**result.__dict__))
+
+
+@router.post("/projects/{project_id}/renders", response_model=DataResponse[RenderRead],
+             status_code=status.HTTP_202_ACCEPTED)
+def start_render(project_id: str, body: RenderCreate, user: CurrentUser, token: CallerToken,
+                 session: Session = Depends(get_session)) -> DataResponse[RenderRead]:
+    """Render the project as it is saved now. Later edits never change this render."""
+    project = project_service.get_owned(session, user, project_id)
+    spec = project_service.require_spec(project_service.decode(project.spec))
+    checked = estimate(spec)
+    blocks = checked.blocks_preview if body.preview else checked.blocks_render
+    if blocks:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "not_renderable", "message": " ".join(blocks)})
+    running = session.exec(select(RenderJob).where(
+        RenderJob.project_id == project.id, RenderJob.status.in_(ACTIVE_STATUSES))).first()
+    if running is not None:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "render_running",
+                                    "message": "This project is already rendering"})
+    job = worker.submit(session, project, user_id=user.id, token=token, preview=body.preview)
+    return DataResponse(data=_read(job))
+
+
+@router.get("/projects/{project_id}/renders", response_model=ListResponse[RenderRead])
+def list_renders(project_id: str, user: CurrentUser, limit: int = Query(default=20, ge=1, le=100),
+                 session: Session = Depends(get_session)) -> ListResponse[RenderRead]:
+    project = project_service.get_owned(session, user, project_id)
+    rows = session.exec(select(RenderJob).where(RenderJob.project_id == project.id)
+                        .order_by(RenderJob.created_at.desc()).limit(limit)).all()
+    return ListResponse(data=[_read(r) for r in rows], total=len(rows), limit=limit, offset=0)
+
+
+@router.get("/renders/{render_id}", response_model=DataResponse[RenderRead])
+def get_render(render_id: str, user: CurrentUser,
+               session: Session = Depends(get_session)) -> DataResponse[RenderRead]:
+    return DataResponse(data=_read(_owned(session, user, render_id)))
+
+
+@router.post("/renders/{render_id}/cancel", response_model=DataResponse[RenderRead])
+def cancel_render(render_id: str, user: CurrentUser,
+                  session: Session = Depends(get_session)) -> DataResponse[RenderRead]:
+    job = _owned(session, user, render_id)
+    if job.status in ACTIVE_STATUSES:
+        worker.queue.cancel(job.id)
+        if job.status == "queued":
+            # Never picked up, so nothing will unwind it: say so now.
+            job.status, job.stage = "cancelled", ""
+            session.add(job)
+            session.commit()
+            session.refresh(job)
+    return DataResponse(data=_read(job))
+
+
+@router.delete("/renders/{render_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_render(render_id: str, user: CurrentUser,
+                  session: Session = Depends(get_session)) -> Response:
+    job = _owned(session, user, render_id)
+    if job.status in ACTIVE_STATUSES:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT,
+                            detail={"code": "render_running", "message": "Cancel it first"})
+    shutil.rmtree(worker.renders_dir() / job.id, ignore_errors=True)
+    session.delete(job)
+    session.commit()
+    return Response(status_code=status.HTTP_204_NO_CONTENT)
+
+
+@media_router.get("/{render_id}/{name}")
+def serve_render_file(
+    render_id: str, name: str,
+    exp: int = Query(...), sig: str = Query(...),
+    range_header: Optional[str] = Header(default=None, alias="Range"),
+):
+    """A finished render's file, by signed URL; ranged, so a long video can scrub."""
+    if name not in _FILES or not verify_media_signature(f"{render_id}/{name}", exp, sig):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN,
+                            detail={"code": "invalid_signature",
+                                    "message": "This link is invalid or has expired"})
+    path = worker.renders_dir() / render_id / name
+    if not path.is_file():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,
+                            detail={"code": "not_found", "message": "No such file"})
+    return ranged_response(open(path, "rb"), size=path.stat().st_size,
+                           media_type=mimetypes.guess_type(name)[0] or "application/octet-stream",
+                           range_header=range_header, cache_seconds=3600)
diff --git a/backend/app/schemas_gam.py b/backend/app/schemas_gam.py
index f943c83..7509ad0 100644
--- a/backend/app/schemas_gam.py
+++ b/backend/app/schemas_gam.py
@@ -21,6 +21,8 @@ class GamAssetRead(BaseModel):
     file_url: Optional[str] = None
     thumb_url: Optional[str] = None
     credit: str = ""
+    # The file's size, which is what tells the render cache a copy is still current.
+    size_bytes: int = 0
     # A GAM clip has no file of its own: it is its parent's bytes between these points.
     parent_asset_id: Optional[str] = None
     in_point: Optional[float] = None
diff --git a/backend/app/schemas_renders.py b/backend/app/schemas_renders.py
new file mode 100644
index 0000000..26c2ecc
--- /dev/null
+++ b/backend/app/schemas_renders.py
@@ -0,0 +1,42 @@
+"""Request and response bodies for renders."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class RenderCreate(BaseModel):
+    # A preview renders at 480p and draws placeholders as slates; a full render
+    # refuses them.
+    preview: bool = True
+
+
+class RenderRead(BaseModel):
+    id: str
+    project_id: str
+    version: int
+    preview: bool
+    status: str
+    stage: str
+    progress: int
+    detail: str
+    error: Optional[str] = None
+    warnings: List[str] = []
+    duration: Optional[float] = None
+    size_bytes: Optional[int] = None
+    narration_chars: int = 0
+    # Signed and short-lived: a <video> element cannot send an Authorization header.
+    video_url: Optional[str] = None
+    subtitles_url: Optional[str] = None
+    poster_url: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class EstimateRead(BaseModel):
+    seconds: float
+    seconds_is_floor: bool
+    narration_chars: int
+    blocks_render: List[str]
+    blocks_preview: List[str]
diff --git a/backend/app/services/projects.py b/backend/app/services/projects.py
index 1d60d96..024df2f 100644
--- a/backend/app/services/projects.py
+++ b/backend/app/services/projects.py
@@ -171,6 +171,13 @@ def delete(session: Session, project: Project) -> None:
     # Versions first, flushed on their own. With no relationship declared between the
     # two tables, the unit of work is free to issue the project's DELETE first, which
     # the foreign key refuses.
+    from app.models.render import RenderJob
+    from app.render.worker import renders_dir
+    import shutil
+
+    for job in session.exec(select(RenderJob).where(RenderJob.project_id == project.id)).all():
+        shutil.rmtree(renders_dir() / job.id, ignore_errors=True)
+    session.exec(sa_delete(RenderJob).where(RenderJob.project_id == project.id))
     session.exec(sa_delete(ProjectVersion).where(ProjectVersion.project_id == project.id))
     session.delete(project)
     session.commit()
diff --git a/backend/requirements.txt b/backend/requirements.txt
index 177eaf2..72471dc 100644
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -7,3 +7,6 @@ httpx==0.27.0
 python-jose[cryptography]==3.5.0
 cryptography>=42.0.0
 python-dotenv>=1.0.0
+# Drawing cards, slates, panels and overlays for renders. The version GAM pins, which
+# ships a wheel for Python 3.13.
+Pillow==10.4.0
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 7ba002a..c65b49a 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -103,3 +103,61 @@ def siblings_fixture(monkeypatch):
     monkeypatch.setattr(settings, "gam_base_url", GAM)
     monkeypatch.setattr(settings, "notes_base_url", NOTES)
     return fake
+
+
+@pytest.fixture(autouse=True)
+def no_render_workers(monkeypatch, tmp_path):
+    """No worker threads in tests, and renders written under the test's own directory.
+
+    The app's lifespan starts the render queue, and TestClient runs the lifespan; a
+    test that wants a render to happen calls `worker._run` itself, which is also the
+    only way to assert on what it did.
+    """
+    from app.config import settings
+    from app.render import worker
+
+    monkeypatch.setattr(worker.queue, "start", lambda: None)
+    monkeypatch.setattr(worker.queue, "enqueue", lambda job_id: None)
+    monkeypatch.setattr(settings, "data_dir", str(tmp_path / "data"))
+
+
+# ── media a render can really encode ─────────────────────────────────────────
+
+import subprocess  # noqa: E402
+
+
+def _make(path, *args):
+    subprocess.run(["ffmpeg", "-y", "-hide_banner", "-loglevel", "error", *args, path], check=True)
+    with open(path, "rb") as f:
+        return f.read()
+
+
+@pytest.fixture(scope="module")
+def files(tmp_path_factory):
+    d = tmp_path_factory.mktemp("media")
+    return {
+        "picture": _make(str(d / "p.png"), "-f", "lavfi", "-i", "testsrc=size=1600x900", "-frames:v", "1"),
+        "reel": _make(str(d / "r.mp4"), "-f", "lavfi", "-i", "testsrc=size=640x360:rate=25",
+                      "-f", "lavfi", "-i", "sine=frequency=220", "-t", "20",
+                      "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac"),
+        "song_a": _make(str(d / "a.mp3"), "-f", "lavfi", "-i", "sine=frequency=330", "-t", "30"),
+        "song_b": _make(str(d / "b.mp3"), "-f", "lavfi", "-i", "sine=frequency=660", "-t", "30"),
+        "speech": _make(str(d / "s.wav"), "-f", "lavfi", "-i", "sine=frequency=500", "-t", "1.5"),
+    }
+
+
+@pytest.fixture
+def library(siblings, files):
+    from tests.fake_siblings import gam_asset
+
+    for key, kind, size in (("p", "image", None), ("r", "video", 20.0),
+                            ("a", "audio", 30.0), ("b", "audio", 30.0)):
+        asset = gam_asset(key, f"asset {key}", kind, file_url=f"/media/{key}.bin", size_bytes=1,
+                          duration_seconds=size)
+        siblings.assets[key] = asset
+    siblings.media_files = {"/media/p.bin": files["picture"], "/media/r.bin": files["reel"],
+                            "/media/a.bin": files["song_a"], "/media/b.bin": files["song_b"]}
+    siblings.speech = files["speech"]
+    return siblings
+
+
diff --git a/backend/tests/fake_siblings.py b/backend/tests/fake_siblings.py
index 7e28c19..320080f 100644
--- a/backend/tests/fake_siblings.py
+++ b/backend/tests/fake_siblings.py
@@ -38,6 +38,11 @@ class FakeSiblings:
     # Set to make GAM answer every request with this status.
     gam_status: Optional[int] = None
     gam_down: bool = False
+    # GAM media bytes by path ("/media/<key>"), and what Notes' speech says per chunk.
+    media_files: Dict[str, bytes] = field(default_factory=dict)
+    speech: Optional[bytes] = None
+    speech_provider: Optional[str] = "deepgram"
+    spoken: List[dict] = field(default_factory=list)
     # Filenames GAM should refuse on upload.
     refuse_uploads: List[str] = field(default_factory=list)
     uploads: List[dict] = field(default_factory=list)
@@ -47,6 +52,15 @@ def handler(self, request: httpx.Request) -> httpx.Response:
         url = str(request.url)
         if url.startswith(GAM):
             return self._gam(request)
+        if url.startswith(NOTES) and request.url.path == "/api/settings/speech/tts":
+            body = json.loads(request.content)
+            self.spoken.append(body)
+            headers = {"content-type": "audio/wav"}
+            if self.speech_provider:
+                headers["x-speech-provider"] = body["provider"] if body["provider"] != "auto" \
+                    else self.speech_provider
+                headers["x-speech-voice"] = body.get("voice") or "Rex"
+            return httpx.Response(200, content=self.speech or b"", headers=headers)
         if url.startswith(NOTES):
             path = request.url.path
             if path in self.notes_files:
@@ -61,6 +75,8 @@ def _gam(self, request: httpx.Request) -> httpx.Response:
         if self.gam_status:
             return httpx.Response(self.gam_status, json={"detail": {"code": "x", "message": "y"}})
         path = request.url.path
+        if path.startswith("/media/") and path in self.media_files:
+            return httpx.Response(200, content=self.media_files[path])
         if path == "/api/search":
             return httpx.Response(200, json={
                 "data": self.hits, "total": len(self.hits),
diff --git a/backend/tests/fixtures/pause_cases.json b/backend/tests/fixtures/pause_cases.json
new file mode 100644
index 0000000..57364ed
--- /dev/null
+++ b/backend/tests/fixtures/pause_cases.json
@@ -0,0 +1,745 @@
+{
+  "_comment": [
+    "Shared behaviour table for the two mirrored pause-markup implementations:",
+    "backend/app/video/pause_markup.py and frontend/src/utils/pauseMarkup.ts.",
+    "Both test suites read this file, so a change made to one implementation and",
+    "not the other fails on whichever side was left behind. Three divergences had",
+    "already accumulated before this existed (an unknown level raised on the",
+    "backend but returned 0 on the frontend; a partial pause_ms dict produced NaN",
+    "in TypeScript; the frontend had no test infrastructure at all).",
+    "",
+    "pauseMs: null means 'use the implementation's DEFAULT_PAUSE_MS'. The named",
+    "subsets below mirror what real callers pass: 'video' is the dict",
+    "narration.build_narration_chunks builds, where a bare '.' is deliberately",
+    "not a boundary.",
+    "",
+    "chunk: whole-text splitting, after emoji removal and whitespace collapse. The frontend's chunkText and the backend's _pack_export_chunks must agree exactly or the export re-synthesises audio the cache already holds.",
+    "",
+    "A segment with nothing a voice could pronounce is never emitted as a chunk: its pause is kept on the chunk before it. A wordless TTS request comes back as a non-audio body, which fails the video render at the ffmpeg decode."
+  ],
+  "pauseMsSets": {
+    "video": {
+      "…": 1300,
+      "\n\n": 1600
+    },
+    "ellipsisOnly": {
+      "…": 1300
+    }
+  },
+  "parse": [
+    {
+      "name": "sentences split on a real full stop",
+      "pauseMs": null,
+      "text": "One sentence. Two sentence.",
+      "expect": [
+        [
+          "One sentence.",
+          250
+        ],
+        [
+          "Two sentence.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no pause inside a decimal",
+      "pauseMs": null,
+      "text": "The rate is 3.5 percent today.",
+      "expect": [
+        [
+          "The rate is 3.5 percent today.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no pause after an abbreviation or an initial",
+      "pauseMs": null,
+      "text": "Dr. Smith arrived. e.g. this one.",
+      "expect": [
+        [
+          "Dr. Smith arrived.",
+          250
+        ],
+        [
+          "e.g. this one.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a URL is not three sentences",
+      "pauseMs": null,
+      "text": "See www.example.com now.",
+      "expect": [
+        [
+          "See www.example.com now.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no pause inside a currency amount",
+      "pauseMs": null,
+      "text": "It cost $1,200.50 in total.",
+      "expect": [
+        [
+          "It cost $1,200.50 in total.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no pause inside a version number",
+      "pauseMs": null,
+      "text": "Version 2.0.1 shipped.",
+      "expect": [
+        [
+          "Version 2.0.1 shipped.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no pause inside an acronym",
+      "pauseMs": null,
+      "text": "U.S. policy changed.",
+      "expect": [
+        [
+          "U.S. policy changed.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a closing quote stays with its own sentence",
+      "pauseMs": null,
+      "text": "He said \"go.\" Then left.",
+      "expect": [
+        [
+          "He said \"go.\"",
+          250
+        ],
+        [
+          "Then left.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a closing bracket stays with its own sentence",
+      "pauseMs": null,
+      "text": "(He left.) Next.",
+      "expect": [
+        [
+          "(He left.)",
+          250
+        ],
+        [
+          "Next.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a blank line outranks the period before it",
+      "pauseMs": null,
+      "text": "Para one.\n\nPara two.",
+      "expect": [
+        [
+          "Para one.",
+          1600
+        ],
+        [
+          "Para two.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "each extra blank line multiplies the pause",
+      "pauseMs": null,
+      "text": "A.\n\n\nB.",
+      "expect": [
+        [
+          "A.",
+          3200
+        ],
+        [
+          "B.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: bare integer is milliseconds",
+      "pauseMs": "video",
+      "text": "Hello [pause:15] world",
+      "expect": [
+        [
+          "Hello",
+          15
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: space after the colon",
+      "pauseMs": "video",
+      "text": "Hello [pause: 15] world",
+      "expect": [
+        [
+          "Hello",
+          15
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: space instead of a colon",
+      "pauseMs": "video",
+      "text": "Hello [pause 15] world",
+      "expect": [
+        [
+          "Hello",
+          15
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: no value at all",
+      "pauseMs": "video",
+      "text": "Hello [pause] world",
+      "expect": [
+        [
+          "Hello",
+          750
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: capitalised",
+      "pauseMs": "video",
+      "text": "Hello [Pause:15] world",
+      "expect": [
+        [
+          "Hello",
+          15
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: shouty, spaced, uppercase unit",
+      "pauseMs": "video",
+      "text": "Hello [PAUSE : 2S] world",
+      "expect": [
+        [
+          "Hello",
+          2000
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: equals separator and ms unit",
+      "pauseMs": "video",
+      "text": "Hello [pause=400ms] world",
+      "expect": [
+        [
+          "Hello",
+          400
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: bare decimal is seconds",
+      "pauseMs": "video",
+      "text": "Hello [pause:1.5] world",
+      "expect": [
+        [
+          "Hello",
+          1500
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: decimal seconds",
+      "pauseMs": "video",
+      "text": "Hello [pause:1.5s] world",
+      "expect": [
+        [
+          "Hello",
+          1500
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: whole seconds",
+      "pauseMs": "video",
+      "text": "Hello [pause:2s] world",
+      "expect": [
+        [
+          "Hello",
+          2000
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: spelled-out unit",
+      "pauseMs": "video",
+      "text": "Hello [pause:2 seconds] world",
+      "expect": [
+        [
+          "Hello",
+          2000
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: named level",
+      "pauseMs": "video",
+      "text": "Hello [pause:xlong] world",
+      "expect": [
+        [
+          "Hello",
+          2000
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: unknown level falls back, never raises",
+      "pauseMs": "video",
+      "text": "Hello [pause:xxlong] world",
+      "expect": [
+        [
+          "Hello",
+          750
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "marker: absurd value is clamped",
+      "pauseMs": "video",
+      "text": "Hello [pause:120000] world",
+      "expect": [
+        [
+          "Hello",
+          10000
+        ],
+        [
+          "world",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: three dots",
+      "pauseMs": "video",
+      "text": "Wait... go",
+      "expect": [
+        [
+          "Wait...",
+          1300
+        ],
+        [
+          "go",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: four dots leave no orphan period",
+      "pauseMs": "video",
+      "text": "Wait.... go",
+      "expect": [
+        [
+          "Wait....",
+          1300
+        ],
+        [
+          "go",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: spaced dots",
+      "pauseMs": "video",
+      "text": "Wait . . . go",
+      "expect": [
+        [
+          "Wait . . .",
+          1300
+        ],
+        [
+          "go",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: two dots",
+      "pauseMs": "video",
+      "text": "Wait .. go",
+      "expect": [
+        [
+          "Wait ..",
+          1300
+        ],
+        [
+          "go",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: the single character",
+      "pauseMs": "video",
+      "text": "Wait … go",
+      "expect": [
+        [
+          "Wait …",
+          1300
+        ],
+        [
+          "go",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "ellipsis: closing quote stays put",
+      "pauseMs": "video",
+      "text": "She replied \"wait...\" and paused.",
+      "expect": [
+        [
+          "She replied \"wait...\"",
+          1300
+        ],
+        [
+          "and paused.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "an adjacent marker overrides rather than stacks",
+      "pauseMs": null,
+      "text": "Done. [pause:xlong] Next.",
+      "expect": [
+        [
+          "Done.",
+          2000
+        ],
+        [
+          "Next.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "an adjacent marker overrides an ellipsis too",
+      "pauseMs": null,
+      "text": "Done… [pause:400ms] Next.",
+      "expect": [
+        [
+          "Done…",
+          400
+        ],
+        [
+          "Next.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a trigger absent from the dict is not a boundary",
+      "pauseMs": "ellipsisOnly",
+      "text": "a.\n\nb... c.",
+      "expect": [
+        [
+          "a. b...",
+          1300
+        ],
+        [
+          "c.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a bare period never splits in the video dict",
+      "pauseMs": "video",
+      "text": "Wait for it. Here.",
+      "expect": [
+        [
+          "Wait for it. Here.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "empty text yields no chunks",
+      "pauseMs": null,
+      "text": "",
+      "expect": []
+    },
+    {
+      "name": "an ellipsis beat on its own line is silence, not a chunk",
+      "text": "Before this.\n\n...\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a two-dot beat likewise",
+      "text": "Before this.\n\n..\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "spaced dots likewise",
+      "text": "Before this.\n\n. . .\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a quoted ellipsis likewise",
+      "text": "Before this.\n\n“...”\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a rule of dashes is not speech",
+      "text": "Before this.\n\n---\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a lone emoji is not speech",
+      "text": "Before this.\n\n🚗\n\nAfter this.",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "Before this.",
+          1600
+        ],
+        [
+          "After this.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a note with nothing sayable yields no chunks",
+      "text": "...\n\n---",
+      "pauseMs": "video",
+      "expect": []
+    },
+    {
+      "name": "a trailing beat keeps the last chunk at zero",
+      "text": "All done.\n\n...",
+      "pauseMs": "video",
+      "expect": [
+        [
+          "All done.",
+          0
+        ]
+      ]
+    }
+  ],
+  "strip": [
+    {
+      "text": "Chapter One [pause:2s]",
+      "expect": "Chapter One"
+    },
+    {
+      "text": "Intro [PAUSE] Part",
+      "expect": "Intro Part"
+    },
+    {
+      "text": "[pause:long]Heading",
+      "expect": "Heading"
+    },
+    {
+      "text": "No markers here",
+      "expect": "No markers here"
+    },
+    {
+      "text": "Keep the ellipsis…",
+      "expect": "Keep the ellipsis…"
+    }
+  ],
+  "chunk": [
+    {
+      "name": "markers stripped, pauses carried",
+      "text": "One. Two [pause:2s] three... four.",
+      "expect": [
+        [
+          "One.",
+          250
+        ],
+        [
+          "Two",
+          2000
+        ],
+        [
+          "three...",
+          1300
+        ],
+        [
+          "four.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a blank line is a paragraph pause",
+      "text": "One.\n\nTwo.",
+      "expect": [
+        [
+          "One.",
+          1600
+        ],
+        [
+          "Two.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "emoji are dropped before synthesis",
+      "text": "Drive the car 🚗 home.",
+      "expect": [
+        [
+          "Drive the car home.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "runs of spaces collapse",
+      "text": "Spaced   out    words.",
+      "expect": [
+        [
+          "Spaced out words.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "no split inside an abbreviation or decimal",
+      "text": "Dr. Smith said 3.5 percent.",
+      "expect": [
+        [
+          "Dr. Smith said 3.5 percent.",
+          0
+        ]
+      ]
+    },
+    {
+      "name": "a lone marker attaches to the words before it",
+      "text": "Hold on [pause:long]",
+      "expect": [
+        [
+          "Hold on",
+          0
+        ]
+      ]
+    }
+  ]
+}
diff --git a/backend/tests/test_pause_markup.py b/backend/tests/test_pause_markup.py
new file mode 100644
index 0000000..c49b173
--- /dev/null
+++ b/backend/tests/test_pause_markup.py
@@ -0,0 +1,214 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from app.render import pause_markup
+from app.render.pause_markup import (
+    DEFAULT_PAUSE_MS,
+    NAMED_PAUSE_MS,
+    parse_pause_markup,
+)
+
+SNIPPET = (
+    "You began watching the TV news.\n\n"
+    "1, 2, 3\n\n"
+    "Then you took a side. [pause:xlong] And that's when you found your heart."
+)
+
+
+def test_the_snippet_from_the_spec_has_no_markers_left():
+    chunks = parse_pause_markup(SNIPPET)
+    for chunk in chunks:
+        assert "[pause:" not in chunk.text
+
+
+def test_the_snippet_from_the_spec_produces_the_expected_chunks_and_pauses():
+    chunks = parse_pause_markup(SNIPPET)
+    assert [(c.text, c.pause_after_ms) for c in chunks] == [
+        ("You began watching the TV news.", DEFAULT_PAUSE_MS["\n\n"]),
+        ("1, 2, 3", DEFAULT_PAUSE_MS["\n\n"]),
+        ("Then you took a side.", NAMED_PAUSE_MS["xlong"]),
+        ("And that's when you found your heart.", 0),
+    ]
+
+
+def test_the_snippet_reconstructs_to_the_original_prose_minus_markers_and_blank_lines():
+    chunks = parse_pause_markup(SNIPPET)
+    assert " ".join(c.text for c in chunks) == (
+        "You began watching the TV news. 1, 2, 3 Then you took a side. "
+        "And that's when you found your heart."
+    )
+
+
+def test_explicit_marker_overrides_rather_than_stacks_with_the_implicit_pause():
+    # If it stacked, "side." would carry the full stop's pause *plus* 2000ms
+    # instead of the 2000ms the marker asked for.
+    chunks = parse_pause_markup(SNIPPET)
+    side_chunk = next(c for c in chunks if c.text == "Then you took a side.")
+    assert side_chunk.pause_after_ms == NAMED_PAUSE_MS["xlong"]
+
+
+def test_the_last_chunk_never_carries_a_trailing_pause():
+    chunks = parse_pause_markup(SNIPPET)
+    assert chunks[-1].pause_after_ms == 0
+
+
+def test_two_blank_lines_pause_twice_as_long_as_one():
+    one_blank = parse_pause_markup("First.\n\nSecond.")
+    two_blank = parse_pause_markup("First.\n\n\nSecond.")
+    assert one_blank[0].pause_after_ms == DEFAULT_PAUSE_MS["\n\n"]
+    assert two_blank[0].pause_after_ms == 2 * DEFAULT_PAUSE_MS["\n\n"]
+
+
+def test_a_bare_numeric_marker_splits_the_sentence_and_is_removed():
+    chunks = parse_pause_markup("Then you took a side [pause:1200] really took a side.")
+    assert [(c.text, c.pause_after_ms) for c in chunks] == [
+        ("Then you took a side", 1200),
+        ("really took a side.", 0),
+    ]
+
+
+def test_each_named_level_resolves_to_its_configured_ms_value():
+    for level, ms in NAMED_PAUSE_MS.items():
+        chunks = parse_pause_markup(f"Wait [pause:{level}] for it.")
+        assert chunks[0].pause_after_ms == ms
+
+
+def test_ellipsis_uses_its_own_longer_duration_not_the_period_duration():
+    dotdotdot = parse_pause_markup("Wait for it... here it comes.")
+    unicode_ellipsis = parse_pause_markup("Wait for it… here it comes.")
+    assert dotdotdot[0].pause_after_ms == DEFAULT_PAUSE_MS["…"]
+    assert unicode_ellipsis[0].pause_after_ms == DEFAULT_PAUSE_MS["…"]
+    assert DEFAULT_PAUSE_MS["…"] != DEFAULT_PAUSE_MS["."]
+
+
+def test_period_immediately_followed_by_a_blank_line_does_not_create_an_empty_chunk():
+    # No words between the period and the blank line, so there is nothing to
+    # split into a second chunk — the longer (paragraph) pause wins.
+    chunks = parse_pause_markup("End of section.\n\nNext section.")
+    assert [c.text for c in chunks] == ["End of section.", "Next section."]
+    assert chunks[0].pause_after_ms == DEFAULT_PAUSE_MS["\n\n"]
+
+
+def test_custom_pause_and_named_dicts_override_the_module_defaults():
+    chunks = parse_pause_markup(
+        "First. Second. [pause:custom] Third.",
+        pause_ms={".": 111, "…": 222, "\n\n": 333},
+        named_pause_ms={"custom": 4242},
+    )
+    assert chunks[0].pause_after_ms == 111
+    assert chunks[1].pause_after_ms == 4242
+
+
+def test_a_trailing_explicit_marker_still_yields_zero_pause_on_the_last_chunk():
+    # pause_after_ms is only ever read *between* chunks (see synthesize_shot);
+    # nothing follows the last chunk, so its value is always forced to 0 even
+    # when an explicit marker sits at the very end of the text.
+    chunks = parse_pause_markup("Final line. [pause:xlong]")
+    assert chunks[-1].pause_after_ms == 0
+
+
+def test_empty_text_produces_no_chunks():
+    assert parse_pause_markup("") == []
+    assert parse_pause_markup("   ") == []
+
+
+# ── omitting a trigger from pause_ms disables it, rather than zeroing it ────
+# This is what lets a caller (narration.build_narration_chunks) turn off the
+# bare "." without forcing every sentence into its own TTS request.
+
+def test_a_trigger_missing_from_pause_ms_is_not_a_boundary_at_all():
+    chunks = parse_pause_markup(
+        "First sentence. Second sentence.", pause_ms={"…": 1300, "\n\n": 1600},
+    )
+    assert len(chunks) == 1
+    assert chunks[0].text == "First sentence. Second sentence."
+
+
+def test_a_disabled_period_still_lets_ellipsis_and_markers_split():
+    chunks = parse_pause_markup(
+        "One. Two... Three [pause:medium] four.", pause_ms={"…": 1300, "\n\n": 1600},
+    )
+    assert [c.text for c in chunks] == ["One. Two...", "Three", "four."]
+    assert chunks[0].pause_after_ms == 1300
+    assert chunks[1].pause_after_ms == NAMED_PAUSE_MS["medium"]
+
+
+def test_a_disabled_blank_line_collapses_to_a_space_not_nothing():
+    """A period keeps its own character either way, but a blank line's
+    newlines are otherwise dropped outright — without a substitute space,
+    'text.\\n\\nHeading' would glue into 'text.Heading'."""
+    chunks = parse_pause_markup("Ends here.\n\nStarts here.", pause_ms={"…": 1300})
+    assert len(chunks) == 1
+    assert chunks[0].text == "Ends here. Starts here."
+
+
+def test_an_explicit_marker_overrides_even_a_disabled_trigger():
+    chunks = parse_pause_markup(
+        "Ends here. [pause:xlong] Starts here.", pause_ms={"…": 1300, "\n\n": 1600},
+    )
+    assert [c.text for c in chunks] == ["Ends here.", "Starts here."]
+    assert chunks[0].pause_after_ms == NAMED_PAUSE_MS["xlong"]
+
+
+# ── shared parity table ───────────────────────────────────────────────────────
+# The cases in tests/fixtures/pause_cases.json are asserted here and, verbatim,
+# by frontend/src/utils/pauseMarkup.test.ts. Both implementations have to agree
+# with the table, which is what keeps them mirrored — see the file's _comment.
+
+_FIXTURE = json.loads(
+    (Path(__file__).parent / "fixtures" / "pause_cases.json").read_text(encoding="utf-8")
+)
+
+
+def _pause_ms_for(case):
+    named = case["pauseMs"]
+    if named is None:
+        return pause_markup.DEFAULT_PAUSE_MS
+    return _FIXTURE["pauseMsSets"][named]
+
+
+@pytest.mark.parametrize("case", _FIXTURE["parse"], ids=lambda c: c["name"])
+def test_shared_parse_cases(case):
+    chunks = pause_markup.parse_pause_markup(case["text"], pause_ms=_pause_ms_for(case))
+    assert [[c.text, c.pause_after_ms] for c in chunks] == case["expect"]
+
+
+@pytest.mark.parametrize("case", _FIXTURE["strip"], ids=lambda c: c["text"][:30])
+def test_shared_strip_cases(case):
+    assert pause_markup.strip_pause_markup(case["text"]) == case["expect"]
+
+
+# ── nothing sayable is never its own chunk ────────────────────────────────────
+# A wordless TTS request comes back as an empty or error body, which reaches
+# ffmpeg as an undecodable file and fails a whole video render ("Invalid pixel
+# format", from the rawvideo demuxer it falls back to on the ".raw" name).
+
+@pytest.mark.parametrize("text,speakable", [
+    ("hello", True), ("7", True), ("café", True), ("日本語", True), ("Ω", True),
+    ("¿qué?", True),
+    ("...", False), ("..", False), (". . .", False), ("“...”", False),
+    ("---", False), ("—", False), ("_", False), ("   ", False), ("", False),
+    ("🚗", False), ("👨‍👩‍👧", False), ("🇬🇧", False),
+])
+def test_has_speech(text, speakable):
+    assert pause_markup.has_speech(text) is speakable
+
+
+def test_a_beat_becomes_silence_on_the_previous_chunk():
+    chunks = parse_pause_markup("Before this.\n\n...\n\nAfter this.")
+    assert [c.text for c in chunks] == ["Before this.", "After this."]
+    assert chunks[0].pause_after_ms > 0
+
+
+def test_the_longer_of_two_pauses_around_a_beat_wins():
+    """The beat's own pause competes with the paragraph breaks either side
+    rather than stacking with them, same as any other collapsed boundary."""
+    chunks = parse_pause_markup("A.\n\n...\n\nB.", pause_ms={".": 100, "…": 5000, "\n\n": 200})
+    assert [c.text for c in chunks] == ["A.", "B."]
+    assert chunks[0].pause_after_ms == 5000
+
+
+def test_no_chunk_survives_a_note_with_nothing_to_say():
+    assert parse_pause_markup("...\n\n---\n\n🚗") == []
diff --git a/backend/tests/test_render_compile.py b/backend/tests/test_render_compile.py
new file mode 100644
index 0000000..4b44ca1
--- /dev/null
+++ b/backend/tests/test_render_compile.py
@@ -0,0 +1,209 @@
+"""The compile step: units, durations, layout and anchors, with no ffmpeg at all."""
+
+import pytest
+
+from app.render.compile import (
+    Media, layout, place_tracks, placement, plan_units, resolve_anchor, unit_duration, Orphaned,
+    beat_pause_ms, chapters,
+)
+from app.spec.validation import parse_spec
+from tests.conftest import load_fixture
+
+IMAGE = Media(path="img.png", kind="image", width=1600, height=900)
+VIDEO = Media(path="reel.mp4", kind="video", duration=3600.0, has_audio=True)
+SONG = Media(path="song.mp3", kind="audio", duration=200.0)
+
+
+def spec_of(data):
+    spec, issues = parse_spec(data)
+    assert spec is not None, issues
+    return spec
+
+
+def salt_road():
+    spec = spec_of(load_fixture("salt_road_0_1.json"))
+    media = {key: IMAGE for key in spec.assets}
+    media.update({"a_caravan": VIDEO, "a_intro": VIDEO, "a_outro": VIDEO,
+                  "a_theme": SONG, "a_close": SONG, "a_bell": SONG})
+    return spec, media
+
+
+def test_a_scene_is_cut_at_its_quote_and_cards_and_clips_are_one_unit_each():
+    spec, media = salt_road()
+    warnings = []
+    units = plan_units(spec, media, warnings)
+    shape = [(u.segment_id, u.kind, [b.id for b in u.beats], u.panel.kind if u.panel else None)
+             for u in units]
+    assert shape == [
+        ("s_title", "card", [], None),
+        ("s_intro", "video_sound", [], None),
+        ("s_open", "still", ["b1", "b2", "b3"], None),
+        ("s_caravan", "video_muted", ["b1"], None),
+        ("s_caravan", "video_muted", ["b2"], "quote"),
+        ("s_caravan", "video_muted", ["b3"], None),
+        ("s_market", "still", ["b1", "b2"], None),
+        ("s_ruins", "still", ["b1", "b2"], None),
+        ("s_outro", "video_sound", [], None),
+    ]
+    # The lower third is M2b, and says so rather than vanishing.
+    assert any("lower_third" in w for w in warnings)
+
+
+def test_defaults_cascade_field_by_field():
+    spec, media = salt_road()
+    units = plan_units(spec, media, [])
+    caravan = [u for u in units if u.segment_id == "s_caravan"]
+    # Its own dissolve on the way in, at its own 1.0 s ...
+    assert (caravan[0].transition_in.style, caravan[0].transition_in.duration) == ("dissolve", 1.0)
+    # ... and the units it was cut into keep the segment's settings too.
+    assert caravan[0].first_in_segment and not caravan[1].first_in_segment
+    market = next(u for u in units if u.segment_id == "s_market")
+    assert (market.transition_in.style, market.transition_in.duration) == ("fade", 0.6)
+    assert market.motion.effect == "pan_right"
+    opening = next(u for u in units if u.segment_id == "s_open")
+    assert opening.motion.effect == "zoom_in" and opening.motion.amount == 0.08
+    # The trim is taken in the file's seconds; the clip and intros keep their sound.
+    assert caravan[0].trim == (734.0, 18.5)
+    ruins = next(u for u in units if u.segment_id == "s_ruins")
+    assert ruins.min_seconds == 8
+    intro = next(u for u in units if u.segment_id == "s_intro")
+    assert intro.chrome is False
+
+
+def test_only_the_style_can_be_overridden_and_the_duration_still_inherited():
+    spec = spec_of({
+        "style": {"transition": {"style": "fade", "duration": 1.4}},
+        "segments": [{"id": "a", "kind": "scene"},
+                     {"id": "b", "kind": "scene", "transition_in": {"style": "dissolve"}}],
+    })
+    units = plan_units(spec, {}, [])
+    assert (units[1].transition_in.style, units[1].transition_in.duration) == ("dissolve", 1.4)
+
+
+def test_a_gam_clip_is_its_parents_file_from_its_in_point():
+    clip = Media(path="parent.mp4", kind="video", duration=3600.0, offset=100.0, length=30.0)
+    spec = spec_of({"assets": {"c": {"from": "gam", "id": "x"}},
+                    "segments": [{"id": "s", "kind": "scene", "visual": {"asset": "c"}},
+                                 {"id": "t", "kind": "scene",
+                                  "visual": {"asset": "c", "trim": {"in": 5, "out": 9}}}]})
+    first, second = plan_units(spec, {"c": clip}, [])
+    assert first.trim == (100.0, 30.0)
+    assert second.trim == (105.0, 4.0)
+
+
+def test_alternate_cycles_through_the_presets():
+    spec = spec_of({"style": {"motion": {"effect": "alternate"}},
+                    "assets": {"i": {"from": "gam", "id": "x"}},
+                    "segments": [{"id": f"s{n}", "kind": "scene", "visual": {"asset": "i"}}
+                                 for n in range(4)]})
+    units = plan_units(spec, {"i": IMAGE}, [])
+    assert [u.motion.effect for u in units] == ["zoom_in", "pan_right", "zoom_out", "pan_left"]
+
+
+def test_durations_floor_and_fix():
+    spec, media = salt_road()
+    units = plan_units(spec, media, [])
+    card, intro = units[0], units[1]
+    assert unit_duration(card, narration_seconds=0, cards_seconds=3.5) == 3.5
+    assert unit_duration(intro, 0, 3.5) == 3600.0
+    caravan = units[3]
+    assert unit_duration(caravan, narration_seconds=1.0, cards_seconds=3.5) == 2.5
+    assert unit_duration(caravan, narration_seconds=7.2, cards_seconds=3.5) == 7.2
+    ruins = units[7]
+    assert unit_duration(ruins, narration_seconds=5.0, cards_seconds=3.5) == 8
+
+
+def _three(styles):
+    spec = spec_of({"segments": [
+        {"id": "a", "kind": "scene"},
+        {"id": "b", "kind": "scene", "transition_in": {"style": styles[0], "duration": 1.0}},
+        {"id": "c", "kind": "scene", "transition_in": {"style": styles[1], "duration": 1.0}},
+    ]})
+    return plan_units(spec, {}, [])
+
+
+def test_each_join_has_its_own_transition_and_only_blends_overlap():
+    units = _three(["dissolve", "fade"])
+    timeline = layout(units, [10.0, 10.0, 10.0], [])
+    assert timeline.joins[1].is_blend and timeline.joins[1].overlap == 1.0
+    assert not timeline.joins[2].is_blend and timeline.joins[2].style == "fade"
+    assert timeline.starts == [0.0, 9.0, 19.0]
+    assert timeline.total == 29.0
+
+
+def test_a_blend_never_covers_more_than_half_a_short_unit():
+    units = _three(["dissolve", "none"])
+    timeline = layout(units, [10.0, 1.0, 10.0], [])
+    assert timeline.joins[1].overlap == 0.5
+    assert timeline.joins[2].is_cut
+    assert timeline.total == 20.5
+
+
+def _placed():
+    spec, media = salt_road()
+    units = plan_units(spec, media, [])
+    durations = [3.5, 5.0, 12.0, 6.0, 4.0, 5.0, 9.0, 8.0, 6.0]
+    timeline = layout(units, durations, [])
+    offsets = [{} for _ in units]
+    offsets[6] = {"b1": (0.0, 4.0), "b2": (4.0, 9.0)}
+    return spec, media, units, timeline, placement(units, timeline, offsets)
+
+
+def test_the_worked_examples_crossfade_lands_on_the_cut_into_the_ruins():
+    spec, media, units, timeline, where = _placed()
+    warnings = []
+    tracks = {p.track.id: p for p in place_tracks(spec, media, where, warnings)}
+    ruins_start = where.segments["s_ruins"][0]
+    market_end = where.segments["s_market"][1]
+
+    theme, close, bell = tracks["m_theme"], tracks["m_close"], tracks["x_bell"]
+    assert theme.start == where.segments["s_open"][0]
+    assert theme.start + theme.length == pytest.approx(market_end)
+    # The closing theme starts three seconds before the ruins and fades in over them:
+    # the two beds overlap, which is the crossfade.
+    assert close.start == pytest.approx(ruins_start - 3.0)
+    assert close.start < theme.start + theme.length
+    assert close.trim_in == 12.0
+    assert theme.loop and theme.duck
+    # The bell lands 0.3 s before its line, and plays once, unducked.
+    assert bell.start == pytest.approx(where.beats[("s_market", "b1")][0] - 0.3)
+    assert not bell.loop and not bell.duck
+    # Once, to its natural end, or the video's if that comes first.
+    assert bell.length == pytest.approx(min(200.0, where.total - bell.start))
+    assert warnings == []
+
+
+def test_an_anchor_to_a_removed_segment_drops_its_track_with_a_warning():
+    spec, media, units, timeline, where = _placed()
+    spec.segments = [s for s in spec.segments if s.id != "s_market"]
+    del where.segments["s_market"]
+    warnings = []
+    placed = place_tracks(spec, media, where, warnings)
+    assert "m_theme" not in [p.track.id for p in placed]
+    assert any("m_theme" in w and "s_market" in w for w in warnings)
+
+
+def test_anchor_offsets_are_held_inside_the_video():
+    spec, media, units, timeline, where = _placed()
+    from app.spec.model import AnchorRef
+    assert resolve_anchor(AnchorRef(segment="s_title", edge="start", offset=-5), where) == 0.0
+    assert resolve_anchor("video_end", where) == where.total
+    with pytest.raises(Orphaned):
+        resolve_anchor(AnchorRef(segment="gone", edge="end"), where)
+
+
+def test_chapter_marks_follow_the_units():
+    spec, media, units, timeline, where = _placed()
+    marks = chapters(units, timeline)
+    assert [m[2] for m in marks] == ["The Salt Road", "Intro", "Where it started", "The caravans",
+                                     "The market", "What remains", "Outro"]
+    assert marks[-1][1] == timeline.total
+    assert all(a[1] == b[0] for a, b in zip(marks, marks[1:]))
+
+
+def test_pauses_after_beats():
+    spec, media = salt_road()
+    beats = spec.segments[2].beats
+    assert beat_pause_ms(spec, beats, 0) == 800   # a heading
+    assert beat_pause_ms(spec, beats, 1) == 350   # between paragraphs
+    assert beat_pause_ms(spec, beats, 2) == 600   # the end of the scene
diff --git a/backend/tests/test_render_compose.py b/backend/tests/test_render_compose.py
new file mode 100644
index 0000000..514fdd6
--- /dev/null
+++ b/backend/tests/test_render_compose.py
@@ -0,0 +1,359 @@
+"""Overlay layout tests.
+
+These assert against the rendered RGBA layer rather than internal numbers, so
+they describe what a viewer would actually see: how much of an edge an overlay
+is allowed to use, and whether two overlays collide.
+"""
+
+import pytest
+from PIL import Image
+
+from app.render.compose import (
+    _edge_of, _side_of, card_image, code_panel, overlay_layer, quote_panel,
+    wrap_text, load_font, SEMIBOLD,
+)
+from app.render.options import (
+    CardTextSpec, CodeSpec, OverlayTextSpec, QuoteSpec, RenderOptions, WatermarkSpec,
+)
+
+WIDTH, HEIGHT = 1280, 720
+
+# Long enough to need more than half the frame, short enough to fit across all
+# of it — so the "is this edge shared?" decision is what changes the layout.
+LONG_TEXT = "A fairly long line of fixed overlay text that really does want the room"
+
+
+def _text(position="bottom-left", enabled=True, text=LONG_TEXT):
+    return OverlayTextSpec(enabled=enabled, text=text, position=position)
+
+
+def _mark(position="bottom-right", enabled=True):
+    return WatermarkSpec(enabled=enabled, text="by Gecko Notes", position=position)
+
+
+def _layer(watermark, overlay_text):
+    return overlay_layer(WIDTH, HEIGHT, watermark=watermark,
+                         watermark_icon=None, overlay_text=overlay_text)
+
+
+def _box(layer: Image.Image, crop=None):
+    """Bounding box of everything actually drawn (alpha > 0)."""
+    region = layer.crop(crop) if crop else layer
+    return region.getchannel("A").getbbox()
+
+
+def _height_of(box):
+    return box[3] - box[1]
+
+
+LEFT_HALF = (0, 0, WIDTH // 2, HEIGHT)
+
+
+# ── the sharing rule ─────────────────────────────────────────────────────────
+
+def test_text_alone_on_an_edge_spans_the_whole_edge():
+    box = _box(_layer(_mark(enabled=False), _text()))
+    assert box[2] > WIDTH // 2, "an unshared edge should not be limited to half the frame"
+
+
+def test_sharing_an_edge_confines_each_overlay_to_its_own_half():
+    layer = _layer(_mark("bottom-right"), _text("bottom-left"))
+    left = _box(layer, LEFT_HALF)
+    right = _box(layer, (WIDTH // 2, 0, WIDTH, HEIGHT))
+    assert left is not None and right is not None
+    # Neither one crosses the midline into the other's space.
+    assert left[2] <= WIDTH // 2
+    assert right[0] >= 0
+
+
+def test_text_wraps_only_once_the_edge_is_actually_shared():
+    alone = _box(_layer(_mark(enabled=False), _text("bottom-left")))
+    shared = _box(_layer(_mark("bottom-right"), _text("bottom-left")), LEFT_HALF)
+    assert _height_of(shared) > _height_of(alone), (
+        "the same text should fit on fewer lines when it has the edge to itself"
+    )
+
+
+def test_overlays_on_different_edges_each_keep_the_full_width():
+    # Watermark up top, text along the bottom: they never compete, so the text
+    # should lay out exactly as it does when it is the only overlay.
+    alone = _box(_layer(_mark(enabled=False), _text("bottom-left")))
+    apart = _box(_layer(_mark("top-right"), _text("bottom-left")), (0, HEIGHT // 2, WIDTH, HEIGHT))
+    assert _height_of(apart) == _height_of(alone)
+    assert apart[2] > WIDTH // 2
+
+
+def test_centre_counts_as_its_own_band():
+    assert _edge_of("center") == "center"
+    # A centred watermark does not squeeze text pinned to the bottom.
+    alone = _box(_layer(_mark(enabled=False), _text("bottom-left")))
+    with_centre = _box(_layer(_mark("center"), _text("bottom-left")),
+                       (0, int(HEIGHT * 0.75), WIDTH, HEIGHT))
+    assert _height_of(with_centre) == _height_of(alone)
+
+
+# ── collisions ───────────────────────────────────────────────────────────────
+
+def test_two_overlays_in_the_same_corner_stack_instead_of_overlapping():
+    """Halving the width can't separate overlays that share an anchor."""
+    layer = _layer(_mark("bottom-left"), _text("bottom-left"))
+    box = _box(layer, LEFT_HALF)
+    text_only = _box(_layer(_mark(enabled=False), _text("bottom-left")))
+    # Taller than the text alone, because the watermark now sits clear above it.
+    assert _height_of(box) > _height_of(text_only)
+
+
+def test_a_stacked_watermark_stays_inside_the_frame():
+    for position in ("top-left", "bottom-left", "center"):
+        layer = _layer(_mark(position), _text(position))
+        box = _box(layer)
+        assert box is not None
+        assert box[1] >= 0 and box[3] <= HEIGHT
+
+
+def test_a_long_caption_is_trimmed_rather_than_running_off_the_edge():
+    mark = _mark("bottom-right")
+    mark.text = "by " + ("An Extremely Long Note Title " * 6)
+    box = _box(_layer(mark, _text(enabled=False)))
+    assert box[2] <= WIDTH
+
+
+# ── position mapping ─────────────────────────────────────────────────────────
+
+def test_edge_and_side_mapping():
+    assert [_edge_of(p) for p in ("top-left", "top-right")] == ["top", "top"]
+    assert [_edge_of(p) for p in ("bottom-left", "bottom-right")] == ["bottom", "bottom"]
+    assert _edge_of("center") == "center"
+    assert [_side_of(p) for p in ("top-left", "bottom-left")] == ["left", "left"]
+    assert [_side_of(p) for p in ("top-right", "bottom-right")] == ["right", "right"]
+    assert _side_of("center") == "center"
+
+
+# ── nothing to draw ──────────────────────────────────────────────────────────
+
+def test_no_layer_is_produced_when_there_is_nothing_to_show():
+    assert _layer(_mark(enabled=False), _text(enabled=False)) is None
+    assert _layer(_mark(enabled=False), _text(text="   ")) is None
+
+
+# ── configurable sizes ───────────────────────────────────────────────────────
+
+def _ink(card: Image.Image) -> int:
+    """Roughly how much type is on a card: bright pixels over its dim ground."""
+    grey = card.convert("L")
+    return sum(1 for p in grey.getdata() if p > 200)
+
+
+def test_card_type_scales_with_its_size_setting():
+    small = card_image(WIDTH, HEIGHT, title="A Reasonably Long Card Title",
+                       subtitle="by someone", sizes=CardTextSpec(title_pct=3.0, subtitle_pct=1.5))
+    large = card_image(WIDTH, HEIGHT, title="A Reasonably Long Card Title",
+                       subtitle="by someone", sizes=CardTextSpec(title_pct=10.0, subtitle_pct=4.0))
+    assert _ink(large) > _ink(small) * 2
+
+
+def test_a_card_with_no_sizes_given_uses_the_defaults():
+    assert _ink(card_image(WIDTH, HEIGHT, title="Title", subtitle="sub")) == _ink(
+        card_image(WIDTH, HEIGHT, title="Title", subtitle="sub", sizes=CardTextSpec())
+    )
+
+
+def test_title_and_chapter_screens_are_sized_independently():
+    options = RenderOptions()
+    assert options.title_card_text is not options.chapter_card_text
+    options.chapter_card_text.title_pct = 4.0
+    assert options.title_card_text.title_pct == 6.8
+
+
+def test_the_watermark_caption_is_sized_independently_of_the_icon():
+    def caption_box(caption_pct: float):
+        mark = WatermarkSpec(enabled=True, text="by Gecko Notes",
+                             position="bottom-right", caption_pct=caption_pct)
+        return _box(_layer(mark, _text(enabled=False)))
+
+    small, large = caption_box(1.5), caption_box(6.0)
+    assert _height_of(large) > _height_of(small)
+    assert large[2] - large[0] > small[2] - small[0]
+
+
+def test_size_defaults_match_the_shipped_look():
+    """These are the values the renders in the PR were checked against."""
+    options = RenderOptions()
+    assert (options.title_card_text.title_pct, options.title_card_text.subtitle_pct) == (6.8, 2.9)
+    assert (options.chapter_card_text.title_pct, options.chapter_card_text.subtitle_pct) == (6.8, 2.9)
+    assert (options.watermark.scale_pct, options.watermark.caption_pct) == (6.0, 2.3)
+    assert options.overlay_text.size_pct == 3.0
+
+
+def test_sizes_are_clamped_rather_than_rejected():
+    assert CardTextSpec(title_pct=999).title_pct == 25.0
+    assert CardTextSpec(title_pct=-1).title_pct == 1.0
+    assert CardTextSpec(subtitle_pct=0).subtitle_pct == 0.5
+    assert WatermarkSpec(scale_pct=999).scale_pct == 30.0
+    assert WatermarkSpec(caption_pct=0).caption_pct == 0.5
+    assert OverlayTextSpec(size_pct=999).size_pct == 20.0
+
+
+def test_whole_number_sizes_are_accepted():
+    """Stored options predating the switch to fractional percentages."""
+    assert CardTextSpec(title_pct=7).title_pct == 7.0
+    assert WatermarkSpec(scale_pct=6).scale_pct == 6.0
+
+
+def test_a_tiny_card_size_still_renders_legible_type():
+    card = card_image(WIDTH, HEIGHT, title="Tiny", subtitle="also tiny",
+                      sizes=CardTextSpec(title_pct=1.0, subtitle_pct=0.5))
+    assert _ink(card) > 0
+
+
+def test_wrap_text_never_exceeds_the_budget():
+    font = load_font(SEMIBOLD, 28)
+    draw = Image.new("RGBA", (10, 10)).convert("RGBA")
+    from PIL import ImageDraw
+    d = ImageDraw.Draw(draw)
+    for line in wrap_text(d, LONG_TEXT, font, 300):
+        assert d.textlength(line, font=font) <= 300
+
+
+# ── quote panels ─────────────────────────────────────────────────────────────
+
+QUOTE = "The best way out is always through, however long the way may look."
+
+
+def _panel(text=QUOTE, attribution="", **spec):
+    return quote_panel(WIDTH, HEIGHT, text=text, attribution=attribution,
+                       spec=QuoteSpec(**spec))
+
+
+def test_a_quote_panel_draws_something_and_an_empty_one_draws_nothing():
+    assert _box(_panel()) is not None
+    assert _panel(text="   ") is None
+    assert _panel(text="") is None
+
+
+def test_a_bigger_setting_makes_a_taller_panel():
+    """Sizes are percentages of the frame height, so this is the control the
+    user actually turns — it has to move the type, not just the box."""
+    small = _height_of(_box(_panel(size_pct=3.0)))
+    large = _height_of(_box(_panel(size_pct=8.0)))
+    assert large > small * 1.5
+
+
+def test_a_long_quotation_wraps_instead_of_running_off_the_frame():
+    long_quote = QUOTE * 3
+    box = _box(_panel(text=long_quote))
+    assert box[2] <= WIDTH
+    assert _height_of(box) > _height_of(_box(_panel()))
+
+
+def test_an_attribution_adds_a_line_without_changing_the_quotation():
+    """The credit is sized off the quotation, so it must not resize it."""
+    plain = _box(_panel())
+    credited = _box(_panel(attribution="Robert Frost"))
+    assert _height_of(credited) > _height_of(plain)
+
+
+@pytest.mark.parametrize("position", ["top", "center", "bottom"])
+def test_the_panel_lands_in_the_band_it_was_asked_for(position):
+    box = _box(_panel(position=position))
+    middle = (box[1] + box[3]) / 2
+    if position == "top":
+        assert middle < HEIGHT / 2
+    elif position == "bottom":
+        assert middle > HEIGHT / 2
+    else:
+        assert abs(middle - HEIGHT / 2) < HEIGHT * 0.1
+
+
+def test_the_panel_hugs_its_text_rather_than_spanning_the_frame():
+    """A full-width band reads as a subtitle; a quotation should read as a quotation."""
+    assert _box(_panel(text="Short one."))[2] < WIDTH * 0.75
+
+
+def test_an_out_of_range_size_clamps_rather_than_failing_the_render():
+    assert QuoteSpec(size_pct=999).size_pct == 15.0
+    assert QuoteSpec(size_pct=0).size_pct == 1.0
+    assert QuoteSpec(scrim=5).scrim == 1.0
+    assert _box(_panel(size_pct=999)) is not None
+
+
+def test_a_quote_panel_is_transparent_where_nothing_was_drawn():
+    """It is composited over the section's own picture, so it cannot be opaque."""
+    layer = _panel(position="bottom", scrim=1.0)
+    assert layer.getpixel((WIDTH // 2, 2))[3] == 0
+
+
+# ── code panels ──────────────────────────────────────────────────────────────
+
+CODE = "def greet(name):\n    print(f\"hello, {name}\")\n\ngreet(\"world\")"
+
+
+def _code(text=CODE, **spec):
+    return code_panel(WIDTH, HEIGHT, text=text, spec=CodeSpec(**spec))
+
+
+def test_a_code_panel_draws_something_and_an_empty_one_draws_nothing():
+    assert _box(_code()) is not None
+    assert _code(text="   ") is None
+    assert _code(text="") is None
+    assert _code(text="\n\n") is None
+
+
+def test_a_bigger_setting_makes_a_taller_code_panel():
+    small = _height_of(_box(_code(size_pct=2.0)))
+    large = _height_of(_box(_code(size_pct=6.0)))
+    assert large > small * 1.5
+
+
+def test_code_lines_are_never_reflowed():
+    """Word-wrapping a line of code would scramble its indentation and
+    structure, so an over-wide line is truncated with an ellipsis instead of
+    being wrapped onto a second line the way a quotation would be."""
+    wide_line = "x = " + " + ".join(f"variable_{i}" for i in range(40))
+    layer = _code(text=wide_line)
+    box = _box(layer)
+    assert box[2] - box[0] <= WIDTH - 1  # never wider than the frame
+    # A single logical line stays a single visual line: about one line's
+    # worth of height, not several.
+    single_line_h = _height_of(_box(_code(text="short_line = 1")))
+    assert _height_of(box) < single_line_h * 1.5
+
+
+def test_multi_line_code_keeps_its_own_line_breaks():
+    two_lines = _height_of(_box(_code(text="line_one()\nline_two()")))
+    one_line = _height_of(_box(_code(text="line_one()")))
+    assert two_lines > one_line * 1.3
+
+
+def test_a_code_block_too_tall_for_the_frame_is_capped_not_shrunk():
+    """A code block that doesn't fit is meant to be trimmed by whoever wrote
+    it — the panel caps the line count rather than shrinking the type."""
+    many_lines = "\n".join(f"line_{i} = {i}" for i in range(200))
+    layer = _code(text=many_lines, size_pct=6.0)
+    box = _box(layer)
+    assert box[3] - box[1] <= HEIGHT
+
+
+@pytest.mark.parametrize("position", ["top", "center", "bottom"])
+def test_the_code_panel_lands_in_the_band_it_was_asked_for(position):
+    box = _box(_code(position=position))
+    middle = (box[1] + box[3]) / 2
+    if position == "top":
+        assert middle < HEIGHT / 2
+    elif position == "bottom":
+        assert middle > HEIGHT / 2
+    else:
+        assert abs(middle - HEIGHT / 2) < HEIGHT * 0.1
+
+
+def test_an_out_of_range_code_size_clamps_rather_than_failing_the_render():
+    assert CodeSpec(size_pct=999).size_pct == 12.0
+    assert CodeSpec(size_pct=0).size_pct == 1.0
+    assert CodeSpec(scrim=5).scrim == 1.0
+    assert _box(_code(size_pct=999)) is not None
+
+
+def test_a_code_panel_is_transparent_where_nothing_was_drawn():
+    """It is composited over the section's own picture, so it cannot be opaque."""
+    layer = _code(position="bottom", scrim=1.0)
+    assert layer.getpixel((WIDTH // 2, 2))[3] == 0
diff --git a/backend/tests/test_render_ffmpeg.py b/backend/tests/test_render_ffmpeg.py
new file mode 100644
index 0000000..4db74c9
--- /dev/null
+++ b/backend/tests/test_render_ffmpeg.py
@@ -0,0 +1,1268 @@
+"""Copied from gecko-notes' tests/test_video_ffmpeg.py with the engine it covers.
+
+Tests of Notes' shot timeline and estimate are left behind: GVC lays out its own
+timeline (app/render/compile.py) and tests it there.
+"""
+
+import json
+import math
+import os
+import tempfile
+import types
+
+import pytest
+
+from app.render import ffmpeg as F
+from app.render.narration import (
+    Cue, _srt_timestamp, build_narration_chunks, chunk_narration, chunk_text,
+    shift_cues, split_for_subtitles, strip_emoji, write_srt,
+)
+from app.render.options import (
+    KENBURNS_MIN_LEG_SECONDS, MusicSpec, RenderOptions, encoder_tier, frame_size,
+    kenburns_geometry,
+)
+
+
+@pytest.fixture(autouse=True)
+def _all_filters_present(monkeypatch):
+    """Pretend the host ffmpeg has everything, so tests exercise the full graph."""
+    monkeypatch.setattr(F, "_filter_cache", frozenset({
+        "showwaves", "gblur", "subtitles", "drawbox", "overlay", "asplit", "apad",
+        "zoompan", "xfade", "concat", "sidechaincompress", "fade", "afade",
+    }))
+
+
+def _graph(argv):
+    return argv[argv.index("-filter_complex") + 1]
+
+
+# ── frame sizes and encoder tiers ────────────────────────────────────────────
+
+@pytest.mark.parametrize("aspect,resolution,expected", [
+    ("16:9", "720p", (1280, 720)),
+    ("16:9", "1080p", (1920, 1080)),
+    ("16:9", "4k", (3840, 2160)),
+    ("9:16", "1080p", (1080, 1920)),
+    ("1:1", "720p", (720, 720)),
+])
+def test_frame_size_table(aspect, resolution, expected):
+    assert frame_size(aspect, resolution) == expected
+
+
+def test_every_frame_size_is_even_as_yuv420p_requires():
+    for aspect in ("16:9", "9:16", "1:1"):
+        for resolution in ("720p", "1080p", "4k"):
+            for preview in (False, True):
+                w, h = frame_size(aspect, resolution, preview)
+                assert w % 2 == 0 and h % 2 == 0
+
+
+def test_unknown_aspect_and_resolution_fall_back():
+    assert frame_size("banana", "1080p") == (1920, 1080)
+    assert frame_size("16:9", "banana") == (1920, 1080)
+
+
+def test_preview_overrides_the_chosen_quality():
+    assert frame_size("16:9", "4k", preview=True) == (854, 480)
+    assert encoder_tier("high", preview=True) == ("ultrafast", 30)
+    assert encoder_tier("high") == ("slow", 18)
+
+
+# ── uniform encoding, which is what makes `concat -c copy` valid ─────────────
+
+def test_every_shot_kind_encodes_identically():
+    options = RenderOptions()
+    graphs = [
+        F.build_shot_command(kind="still", background="a.png", audio="n.wav", duration=3,
+                             output="0.mp4", options=options, preview=False),
+        F.build_shot_command(kind="video_muted", background="c.mp4", audio="n.wav", duration=3,
+                             output="1.mp4", options=options, preview=False),
+        F.build_shot_command(kind="video_sound", background="c.mp4", audio=None, duration=3,
+                             output="2.mp4", options=options, preview=False,
+                             background_has_audio=True),
+    ]
+    encode = F.encode_args(options, False)
+    for argv in graphs:
+        assert argv[-len(encode) - 1:-1] == encode
+
+
+def test_concat_copies_rather_than_re_encoding():
+    argv = F.build_concat_command("shots.txt", "out.mp4")
+    assert "-c" in argv and argv[argv.index("-c") + 1] == "copy"
+    assert "+faststart" in argv
+    assert "libx264" not in argv
+
+
+# ── per-shot commands ────────────────────────────────────────────────────────
+
+def test_muted_video_loops_and_is_cut_by_the_narration():
+    argv = F.build_shot_command(kind="video_muted", background="c.mp4", audio="n.wav",
+                                duration=7.25, output="s.mp4", options=RenderOptions(),
+                                preview=False)
+    # Loop while the narration runs...
+    assert argv[argv.index("-stream_loop") + 1] == "-1"
+    # ...and cut the instant it ends, never waiting for the clip.
+    assert argv[argv.index("-t") + 1] == "7.250"
+
+
+def test_still_shot_holds_one_frame_for_the_narration():
+    argv = F.build_shot_command(kind="still", background="bg.png", audio="n.wav", duration=4,
+                                output="s.mp4", options=RenderOptions(), preview=False)
+    assert "-loop" in argv and argv[argv.index("-loop") + 1] == "1"
+
+
+def test_sounded_clip_uses_its_own_audio():
+    argv = F.build_shot_command(kind="video_sound", background="c.mp4", audio=None, duration=2,
+                                output="s.mp4", options=RenderOptions(), preview=False,
+                                background_has_audio=True)
+    assert "anullsrc" not in " ".join(argv)
+    assert "[0:a]" in _graph(argv)
+
+
+def test_sounded_clip_without_an_audio_track_gets_silence():
+    """The concat demuxer needs every part to carry an audio stream."""
+    argv = F.build_shot_command(kind="video_sound", background="c.mp4", audio=None, duration=2,
+                                output="s.mp4", options=RenderOptions(), preview=False,
+                                background_has_audio=False)
+    assert "anullsrc=channel_layout=stereo:sample_rate=48000" in argv
+    assert "[1:a]" in _graph(argv)
+
+
+# ── filtergraph shape ────────────────────────────────────────────────────────
+
+@pytest.mark.parametrize("fit,marker", [
+    ("blur", "gblur"),
+    ("pad", "pad=1920:1080"),
+    ("crop", "crop=1920:1080"),
+])
+def test_fit_modes(fit, marker):
+    argv = F.build_shot_command(kind="still", background="bg.png", audio="n.wav", duration=3,
+                                output="s.mp4", options=RenderOptions(fit=fit), preview=False)
+    assert marker in _graph(argv)
+
+
+def test_blurred_fill_contains_the_image_over_a_filled_background():
+    graph = F.fit_chain("0:v", "fit", 1080, 1920, "blur")
+    assert "force_original_aspect_ratio=increase" in graph   # the blurred fill
+    assert "force_original_aspect_ratio=decrease" in graph   # the contained image
+    assert "gblur" in graph
+
+
+def test_every_video_chain_ends_normalised():
+    """A stray SAR or pixel format is what silently breaks a `-c copy` concat."""
+    for kind, audio, has_audio in (
+        ("still", "n.wav", False), ("video_muted", "n.wav", False), ("video_sound", None, True),
+    ):
+        graph = _graph(F.build_shot_command(
+            kind=kind, background="x", audio=audio, duration=3, output="o.mp4",
+            options=RenderOptions(), preview=False, background_has_audio=has_audio))
+        assert "setsar=1,format=yuv420p[v]" in graph
+
+
+def test_waveform_splits_the_audio_it_shares_with_the_muxed_track():
+    """An input pad can only be consumed once in a filtergraph."""
+    options = RenderOptions()
+    options.waveform.enabled = True
+    graph = _graph(F.build_shot_command(kind="still", background="bg.png", audio="n.wav",
+                                        duration=3, output="s.mp4", options=options, preview=False))
+    assert "[1:a]asplit=2[a_wave][a_main]" in graph
+    assert graph.count("[1:a]") == 1
+
+
+def test_waveform_rate_matches_the_output_frame_rate():
+    """A mismatch makes the wave drift against the picture."""
+    options = RenderOptions(fps=24)
+    options.waveform.enabled = True
+    graph = _graph(F.build_shot_command(kind="still", background="bg.png", audio="n.wav",
+                                        duration=3, output="s.mp4", options=options, preview=False))
+    assert "rate=24" in graph
+
+
+@pytest.mark.parametrize("position,expected_y", [
+    ("top", 0), ("center", (1080 - 236) // 2), ("bottom", 1080 - 236),
+])
+def test_waveform_position(position, expected_y):
+    options = RenderOptions()
+    options.waveform.enabled = True
+    options.waveform.position = position
+    graph = _graph(F.build_shot_command(kind="still", background="bg.png", audio="n.wav",
+                                        duration=3, output="s.mp4", options=options, preview=False))
+    assert f"overlay=0:{expected_y}" in graph
+
+
+def test_waveform_is_dropped_when_the_host_ffmpeg_lacks_it(monkeypatch):
+    monkeypatch.setattr(F, "_filter_cache", frozenset({"overlay"}))
+    options = RenderOptions()
+    options.waveform.enabled = True
+    graph = _graph(F.build_shot_command(kind="still", background="bg.png", audio="n.wav",
+                                        duration=3, output="s.mp4", options=options, preview=False))
+    assert "showwaves" not in graph
+    assert "setsar=1,format=yuv420p[v]" in graph  # still a valid graph
+
+
+def test_overlay_and_subtitles_are_layered_in_order():
+    graph = _graph(F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=3, output="s.mp4",
+        options=RenderOptions(), preview=False, overlay_png="ov.png", subtitle_file="s.srt"))
+    assert graph.index("[2:v]overlay=0:0[ov]") < graph.index("subtitles=s.srt")
+
+
+def test_colour_parsing_is_forgiving():
+    assert F._hex_to_ffmpeg("#00FF41") == "0x00ff41"
+    assert F._hex_to_ffmpeg("00ff41") == "0x00ff41"
+    assert F._hex_to_ffmpeg("#abc") == "0xaabbcc"
+    assert F._hex_to_ffmpeg("#00ff41ff") == "0x00ff41"
+    assert F._hex_to_ffmpeg("nonsense") == "0xffffff"
+    assert F._hex_to_ffmpeg("") == "0xffffff"
+
+
+# ── muxing ───────────────────────────────────────────────────────────────────
+
+def test_mux_attaches_chapters_and_soft_subtitles_without_re_encoding():
+    argv = F.build_mux_command("in.mp4", "out.mp4", chapters_file="c.ff", subtitle_file="s.srt")
+    assert argv[argv.index("-c") + 1] == "copy"
+    assert argv[argv.index("-c:s") + 1] == "mov_text"
+    assert "-map_chapters" in argv
+
+
+def test_mux_with_nothing_to_attach_still_copies():
+    argv = F.build_mux_command("in.mp4", "out.mp4")
+    assert "-c:s" not in argv and "-map_chapters" not in argv
+
+
+# ── narration joining ────────────────────────────────────────────────────────
+
+def test_narration_decodes_to_pcm_so_the_join_has_no_gaps():
+    argv = F.build_narration_command("list.txt", "n.wav")
+    assert argv[argv.index("-c:a") + 1] == "pcm_s16le"
+
+
+def test_speed_beyond_atempos_range_is_applied_in_stages():
+    """atempo only accepts 0.5-2.0."""
+    single = F.build_narration_command("l.txt", "n.wav", speed=1.5)
+    assert "atempo=1.5000" in single[single.index("-filter:a") + 1]
+
+    chained = F.build_narration_command("l.txt", "n.wav", speed=3.0)
+    assert chained[chained.index("-filter:a") + 1].count("atempo") == 2
+
+    assert "-filter:a" not in F.build_narration_command("l.txt", "n.wav", speed=1.0)
+
+
+def test_narration_is_padded_to_the_minimum_shot_length():
+    argv = F.build_narration_command("l.txt", "n.wav", min_seconds=2.5)
+    assert "apad=whole_dur=2.500" in argv[argv.index("-filter:a") + 1]
+
+
+def test_concat_list_quotes_each_entry():
+    import tempfile
+    path = tempfile.mktemp()
+    F.write_concat_list(path, ["shot_000.mp4", "it's.mp4"])
+    body = open(path).read()
+    assert body.splitlines()[0] == "file 'shot_000.mp4'"
+    assert "'\\''" in body.splitlines()[1]
+
+
+@pytest.mark.parametrize("code,stderr,expected", [
+    (-9, b"", "killed by signal 9 (most likely out of memory)"),
+    (1, b"Invalid argument", "exit code 1): Invalid argument"),
+])
+def test_run_failure_reports_how_the_process_died(monkeypatch, code, stderr, expected):
+    result = types.SimpleNamespace(returncode=code, stderr=stderr)
+    monkeypatch.setattr(F.subprocess, "run", lambda *a, **k: result)
+    with pytest.raises(F.FFmpegError) as err:
+        F.run(["ffmpeg", "-i", "x"])
+    assert expected in str(err.value)
+
+
+# ── chunking ─────────────────────────────────────────────────────────────────
+
+def test_short_text_is_one_chunk():
+    assert chunk_text("Hello there. How are you?") == ["Hello there. How are you?"]
+
+
+def test_empty_text_produces_nothing():
+    assert chunk_text("") == []
+    assert chunk_text("   \n  ") == []
+
+
+def test_chunks_stay_under_the_providers_character_cap():
+    text = " ".join(f"Sentence number {i} is right here." for i in range(400))
+    chunks = chunk_text(text)
+    assert len(chunks) > 1
+    assert all(len(c) <= 1500 for c in chunks)
+    # Nothing is dropped on the way through.
+    assert "".join(chunks).replace(" ", "") == text.replace(" ", "")
+
+
+def test_a_sentence_is_kept_whole_when_the_chunk_is_full():
+    """A sentence that fits the cap starts a new chunk rather than being cut."""
+    long_sentence = ("A " * 745).strip() + "."      # 1490 chars — fits on its own
+    text = f"{long_sentence} Short one."             # together they exceed 1500
+    chunks = chunk_text(text)
+    assert len(chunks) == 2
+    assert chunks[0] == long_sentence
+    assert chunks[1] == "Short one."
+
+
+def test_an_over_long_sentence_is_split_on_a_word_boundary():
+    chunks = chunk_text("word " * 800)
+    assert len(chunks) > 1
+    assert all(not c.startswith(" ") and "  " not in c for c in chunks)
+    assert all(len(c) <= 1500 for c in chunks)
+
+
+def test_an_unbroken_run_is_split_by_length_as_a_last_resort():
+    chunks = chunk_text("x" * 4000)
+    assert len(chunks) == 3
+    assert sum(len(c) for c in chunks) == 4000
+
+
+def test_strip_emoji_drops_pictographs_but_keeps_plain_text():
+    assert strip_emoji("I drove my car \U0001F697 to work.") == "I drove my car  to work."
+    assert strip_emoji("No emoji here, just #hashtag and 100% normal text.") == \
+        "No emoji here, just #hashtag and 100% normal text."
+    assert strip_emoji(":) plain smiley text stays") == ":) plain smiley text stays"
+
+
+def test_strip_emoji_drops_modifiers_and_compound_sequences():
+    # Skin-tone modifier, ZWJ family sequence, flag pair, keycap sequence.
+    assert strip_emoji("Great \U0001F44D\U0001F3FD job") == "Great  job"
+    assert strip_emoji("Family \U0001F468‍\U0001F469‍\U0001F467 photo") == "Family  photo"
+    assert strip_emoji("Flags \U0001F1FA\U0001F1F8 here") == "Flags  here"
+    assert strip_emoji("Step 1️⃣ done") == "Step 1 done"
+
+
+def test_chunk_text_strips_emoji_so_narration_never_speaks_them():
+    chunks = chunk_text("Great job! \U0001F44D Keep it up.")
+    assert chunks == ["Great job! Keep it up."]
+
+
+# ── subtitles ────────────────────────────────────────────────────────────────
+
+def test_subtitle_lines_stay_readable():
+    """A whole TTS chunk is far too much text to show at once."""
+    text = " ".join(f"This is sentence {i} of the narration." for i in range(30))
+    lines = split_for_subtitles(text)
+    assert lines
+    assert all(len(l) <= 84 for l in lines)
+    assert "".join(lines).replace(" ", "") == text.replace(" ", "")
+
+
+def test_a_single_long_word_is_still_broken_up():
+    lines = split_for_subtitles("supercalifragilistic " * 20)
+    assert all(len(l) <= 84 for l in lines)
+
+
+def test_srt_timestamps():
+    assert _srt_timestamp(0) == "00:00:00,000"
+    assert _srt_timestamp(3661.5) == "01:01:01,500"
+    assert _srt_timestamp(-5) == "00:00:00,000"
+
+
+def test_write_srt_numbers_cues_and_skips_empty_ones():
+    import tempfile
+    path = tempfile.mktemp()
+    assert write_srt(path, [Cue(0, 1, "first"), Cue(1, 2, "   "), Cue(2, 3, "second")])
+    body = open(path).read()
+    assert body.startswith("1\n00:00:00,000 --> 00:00:01,000\nfirst\n")
+    assert "2\n00:00:02,000 --> 00:00:03,000\nsecond\n" in body
+    assert body.count("-->") == 2
+
+
+def test_write_srt_reports_when_there_was_nothing_to_write():
+    import tempfile
+    assert write_srt(tempfile.mktemp(), []) is False
+    assert write_srt(tempfile.mktemp(), [Cue(1.0, 1.0, "zero length")]) is False
+
+
+# ── options validation ───────────────────────────────────────────────────────
+
+def test_out_of_range_options_are_clamped_rather_than_rejected():
+    assert RenderOptions(fps=999).fps == 60
+    assert RenderOptions(fps=1).fps == 12
+    assert RenderOptions(speed=9).speed == 2.0
+    assert RenderOptions(speed=0.01).speed == 0.5
+    assert RenderOptions(paragraph_pause_ms=-5).paragraph_pause_ms == 0
+    assert RenderOptions(min_shot_seconds=999).min_shot_seconds == 30.0
+    assert RenderOptions(shot_end_pause_ms=-5).shot_end_pause_ms == 0
+    assert RenderOptions(shot_end_pause_ms=99999).shot_end_pause_ms == 3000
+
+
+def test_shot_end_pause_defaults_on():
+    """Confirmed as a real bug and the reason this option exists: without a
+    trailing pause, a shot's audio stops the instant speech does, often
+    mid-decay on the voice's own trailing intonation, and the cut lands right
+    on top of it — it reads as the sentence getting clipped, not finishing."""
+    assert RenderOptions().shot_end_pause_ms > 0
+
+
+# ── transitions ──────────────────────────────────────────────────────────────
+
+def _shot(options, *, kind="still", duration=6.0, index=0):
+    return F.build_shot_command(
+        kind=kind, background="bg.png", audio="n.wav", duration=duration,
+        output="s.mp4", options=options, preview=False, index=index,
+    )
+
+
+@pytest.mark.parametrize("style,colour", [("fade", "black"), ("fadewhite", "white")])
+def test_a_dip_transition_fades_the_picture_and_only_the_sounds_tail(style, colour):
+    graph = _graph(_shot(RenderOptions(transition={"style": style, "duration": 0.6})))
+    assert f"fade=t=in:st=0:d=0.600:color={colour}" in graph
+    assert f"fade=t=out:st=5.400:d=0.600:color={colour}" in graph
+    # The tail is faded to match the picture dipping to colour there, landing in
+    # the trailing hold after the last word rather than on speech.
+    assert "afade=t=out:st=5.400:d=0.600" in graph
+    # But not the head: narration starts at st=0 with no lead-in silence, so a
+    # matching fade-in there would ramp up through the sentence's actual first
+    # word instead of the picture's cosmetic fade from black.
+    assert "afade=t=in" not in graph
+
+
+def test_a_dip_never_takes_more_than_a_third_of_a_short_shot():
+    """Two 0.6s dips on a 1.2s shot would never let the picture be fully seen."""
+    assert F.dip_seconds("fade", 0.6, 1.2) == pytest.approx(0.4)
+    assert F.dip_seconds("fade", 0.6, 30.0) == pytest.approx(0.6)
+
+
+def test_a_dip_too_short_to_see_is_dropped_entirely():
+    assert F.dip_seconds("fade", 0.6, 0.09) == 0.0
+    graph = _graph(_shot(RenderOptions(transition={"style": "fade"}), duration=0.09))
+    assert "fade=t=in" not in graph
+
+
+def test_a_crossfade_style_draws_no_per_shot_fade():
+    """A blend happens between shots, so drawing one inside a shot as well would
+    dip to black and then dissolve out of it."""
+    graph = _graph(_shot(RenderOptions(transition={"style": "dissolve"})))
+    assert "fade=t=in" not in graph and "afade=" not in graph
+
+
+def test_no_transition_leaves_the_graph_as_it_was():
+    graph = _graph(_shot(RenderOptions()))
+    assert "fade=" not in graph
+    assert graph.endswith("aresample=48000,aformat=channel_layouts=stereo,apad[a]")
+
+
+def test_a_dip_is_left_off_the_end_that_joins_by_a_straight_cut():
+    """Where a heading carries a section on over the same picture, dipping to
+    black and back would show nothing changing."""
+    options = RenderOptions(transition={"style": "fade", "duration": 0.6})
+    into = _graph(F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=6.0, output="s.mp4",
+        options=options, preview=False, dip_in=False))
+    assert "fade=t=in" not in into
+    assert "fade=t=out:st=5.400:d=0.600:color=black" in into
+    assert "afade=t=out:st=5.400:d=0.600" in into
+
+    out_of = _graph(F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=6.0, output="s.mp4",
+        options=options, preview=False, dip_out=False))
+    assert "fade=t=in:st=0:d=0.600:color=black[fd]" in out_of
+    assert "fade=t=out" not in out_of and "afade" not in out_of
+
+
+# ── the crossfade stitch ─────────────────────────────────────────────────────
+
+ALL = frozenset({"xfade", "concat"})
+
+
+def test_crossfade_offsets_accumulate_across_the_whole_video():
+    """Each join eats `overlap` seconds, so shot k starts that much earlier than
+    the running total — get this wrong and every chapter after the first drifts."""
+    argv = F.build_xfade_command(
+        ["a.mp4", "b.mp4", "c.mp4"], [5.0, 4.0, 6.0], "out.mp4",
+        options=RenderOptions(), preview=False, style="dissolve", overlap=0.6,
+    )
+    graph = _graph(argv)
+    assert "[0:v][1:v]xfade=transition=dissolve:duration=0.600:offset=4.400[vx1]" in graph
+    assert "[vx1][2:v]xfade=transition=dissolve:duration=0.600:offset=7.800[vx2]" in graph
+    # The audio cuts cleanly at the same offset the picture starts blending at,
+    # rather than crossfading — an acrossfade would mix the outgoing shot's
+    # trailing hold with the next shot's opening words fading in underneath it.
+    assert "acrossfade" not in graph
+    assert "[0:a]atrim=end=4.400,asetpts=PTS-STARTPTS[at1]" in graph
+    assert "[at1][1:a]concat=n=2:v=0:a=1[ax1]" in graph
+    assert "[ax1]atrim=end=7.800,asetpts=PTS-STARTPTS[at2]" in graph
+    assert "[at2][2:a]concat=n=2:v=0:a=1[ax2]" in graph
+    assert argv[argv.index("-map") + 1] == "[v]"
+    assert argv[argv.index("-movflags") + 1] == "+faststart" and argv[-1] == "out.mp4"
+
+
+def test_every_shot_is_its_own_input_to_the_crossfade():
+    argv = F.build_xfade_command(
+        ["a.mp4", "b.mp4", "c.mp4"], [5.0, 4.0, 6.0], "out.mp4",
+        options=RenderOptions(), preview=False, style="wipeleft", overlap=0.5,
+    )
+    assert [argv[i + 1] for i, a in enumerate(argv) if a == "-i"] == ["a.mp4", "b.mp4", "c.mp4"]
+    assert "transition=wipeleft" in _graph(argv)
+
+
+def test_a_crossfade_shortens_the_video_by_one_overlap_per_join():
+    assert F.crossfade_total([5.0, 4.0, 6.0], 0.6) == pytest.approx(13.8)
+    assert F.crossfade_total([5.0, 4.0, 6.0], 0.0) == pytest.approx(15.0)
+    assert F.crossfade_total([], 0.6) == 0.0
+
+
+def test_a_shot_that_cuts_in_is_appended_whole_with_no_blend():
+    argv = F.build_xfade_command(
+        ["a.mp4", "b.mp4", "c.mp4"], [5.0, 4.0, 6.0], "out.mp4",
+        options=RenderOptions(), preview=False, style="dissolve", overlap=0.6,
+        cuts=[False, True, False],
+    )
+    graph = _graph(argv)
+    assert "[0:v][1:v]concat=n=2:v=1:a=0[vx1]" in graph
+    assert "[0:a][1:a]concat=n=2:v=0:a=1[ax1]" in graph
+    # Nothing was eaten at the cut, so the blend into c starts at 9 - 0.6.
+    assert "[vx1][2:v]xfade=transition=dissolve:duration=0.600:offset=8.400[vx2]" in graph
+    assert "[ax1]atrim=end=8.400,asetpts=PTS-STARTPTS[at2]" in graph
+    assert F.crossfade_total([5.0, 4.0, 6.0], 0.6, [False, True, False]) == pytest.approx(14.4)
+
+
+def test_an_overlap_can_never_exceed_half_the_shortest_shot():
+    """Overlapping more than a short shot's own length would blend it away."""
+    assert F.crossfade_overlap("dissolve", [10.0, 1.0, 8.0], 0.6, filters=ALL) == pytest.approx(0.5)
+    assert F.crossfade_overlap("dissolve", [10.0, 8.0], 0.6, filters=ALL) == pytest.approx(0.6)
+
+
+def test_shots_too_short_to_overlap_fall_back_to_a_plain_concat():
+    assert F.crossfade_overlap("dissolve", [0.08, 5.0], 0.6, filters=ALL) is None
+
+
+def test_a_dip_or_no_transition_never_takes_the_crossfade_path():
+    assert F.crossfade_overlap("fade", [5.0, 5.0], 0.6, filters=ALL) is None
+    assert F.crossfade_overlap("none", [5.0, 5.0], 0.6, filters=ALL) is None
+
+
+def test_a_single_shot_has_nothing_to_crossfade_into():
+    assert F.crossfade_overlap("dissolve", [5.0], 0.6, filters=ALL) is None
+
+
+def test_too_many_shots_fall_back_rather_than_build_a_vast_filtergraph():
+    many = [5.0] * (F.XFADE_MAX_SHOTS + 1)
+    assert F.crossfade_overlap("dissolve", many, 0.6, filters=ALL) is None
+    assert F.crossfade_overlap("dissolve", [5.0] * F.XFADE_MAX_SHOTS, 0.6, filters=ALL) is not None
+
+
+def test_a_host_without_xfade_falls_back_instead_of_failing_the_render():
+    assert F.crossfade_overlap("dissolve", [5.0, 5.0], 0.6, filters=frozenset({"overlay"})) is None
+    assert F.crossfade_overlap("dissolve", [5.0, 5.0], 0.6, filters=frozenset({"xfade"})) is None
+
+
+# ── Ken Burns ────────────────────────────────────────────────────────────────
+
+def _kb(effect="zoom_in", **kwargs):
+    return RenderOptions(ken_burns={"effect": effect, **kwargs})
+
+
+def test_a_drifting_still_reads_far_above_the_frame_and_writes_above_it_too():
+    """zoompan truncates its crop origin to whole pixels of the frame it is
+    handed, so a slow drift steps unless it is given many more of them. Reading
+    big is most of the fix; writing big and scaling back down is the rest."""
+    read_w, read_h, write_w, write_h = kenburns_geometry(1920, 1080)
+    assert read_w >= 1920 * 3                  # a real supersample, not a token one
+    assert (write_w, write_h) == (3840, 2160)  # written at 2x, then scaled back
+
+    graph = _graph(_shot(_kb()))
+    assert f"scale={read_w}:{read_h}" in graph
+    assert f"s={write_w}x{write_h}" in graph
+    assert "scale=1920:1080" in graph
+
+
+FRAME_SIZES_TO_CHECK = ((854, 480), (1280, 720), (1920, 1080), (3840, 2160),
+                        (1080, 1920), (2160, 3840))
+
+EVERY_EFFECT = ("zoom_in", "zoom_out", "pan_left", "pan_right", "pan_up", "pan_down")
+
+
+def _zoompan_rects(width, height, *, seconds, effect, amount=0.12, fps=30):
+    """Replay a drift the way vf_zoompan does, one crop rectangle per frame.
+
+    zoompan evaluates z, x and y once per output frame and then works entirely
+    in whole pixels of the frame it was handed: `w = int(iw/zoom)`, likewise for
+    h, and the origin truncated and clamped into whatever is left. Two frames
+    with the same rectangle are two identical pictures, which is the whole
+    subject of the tests below — so the arithmetic is reproduced here rather
+    than taken on trust.
+    """
+    chain = F.kenburns_chain("in", "out", width=width, height=height, fps=fps,
+                             duration=seconds, effect=effect, amount=amount)
+    body = chain[chain.index("zoompan=") + len("zoompan="):].split(",")[0]
+    exprs = {name: compile(value, "<zoompan>", "eval")
+             for name, value in (part.split("=", 1) for part in body.split(":"))
+             if name in ("z", "x", "y")}
+    read_w, read_h, _w, _h = kenburns_geometry(width, height)
+    scope = {"__builtins__": {}, "floor": math.floor, "abs": abs,
+             "iw": read_w, "ih": read_h}
+
+    rects = []
+    for on in range(int(math.ceil(seconds * fps))):
+        at = {**scope, "on": on}
+        at["zoom"] = min(10.0, max(1.0, eval(exprs["z"], at)))
+        w, h = int(read_w / at["zoom"]), int(read_h / at["zoom"])
+        rects.append((
+            w, h,
+            min(max(0, int(eval(exprs["x"], at))), read_w - w),
+            min(max(0, int(eval(exprs["y"], at))), read_h - h),
+        ))
+    return rects
+
+
+@pytest.mark.parametrize("effect", EVERY_EFFECT)
+@pytest.mark.parametrize("seconds", (2.5, 4.0, 15.0, 24.0, 60.0, 502.678))
+def test_no_drift_ever_repeats_a_frame(effect, seconds):
+    """The failure this whole arrangement exists to prevent, stated exactly.
+
+    zoompan truncates the crop to whole pixels, so a drift that moves less than
+    one of them in a frame lands on the rectangle it already had — and a pan,
+    whose crop never changes size, then emits a byte-identical picture. The
+    drift stops dead, then jumps.
+
+    At 1080p and the default 12% this used to freeze one frame in eight of a
+    15-second section and every other frame of a 30-second one. Worse, which
+    frames froze was decided by the fractional part of the rate, so they
+    clustered and thinned on a slow beat against the frame rate — around two
+    seconds for a section of 16 to 24 seconds, which is what the drift
+    "pausing every so often" actually was.
+    """
+    rects = _zoompan_rects(1920, 1080, seconds=seconds, effect=effect)
+    frozen = [i for i in range(1, len(rects)) if rects[i] == rects[i - 1]]
+    assert not frozen, f"{len(frozen)} frozen frames, first at frame {frozen[0]}"
+
+
+@pytest.mark.parametrize("effect", EVERY_EFFECT)
+@pytest.mark.parametrize("size", FRAME_SIZES_TO_CHECK)
+def test_no_frame_size_repeats_a_frame_either(effect, size):
+    """Every aspect and resolution reads at the same pixel budget, so none of
+    them has more headroom to spend than any other."""
+    rects = _zoompan_rects(*size, seconds=20.0, effect=effect)
+    assert all(rects[i] != rects[i - 1] for i in range(1, len(rects)))
+
+
+def test_a_drift_slow_enough_to_cycle_moves_exactly_one_pixel_a_frame():
+    """Never repeating is half of it; the other half is moving by the *same*
+    amount each time. A fractional rate rounds to one pixel on some frames and
+    two on others, and the pattern of which is which beats slowly against the
+    frame rate — so even without a single frozen frame the drift would visibly
+    surge and ease. A pixel a frame is the one rate with no fractional part to
+    beat, which is why the sweep rubber-bands at it rather than going slower."""
+    rects = _zoompan_rects(1920, 1080, seconds=24.0, effect="pan_up")
+    steps = {abs(rects[i][3] - rects[i - 1][3]) for i in range(1, len(rects))}
+    assert steps == {1}
+
+
+def test_a_shot_short_enough_to_sweep_once_is_allowed_to_move_faster():
+    """Above a pixel a frame the rounding can only ever be one pixel or two,
+    never none, so the full sweep is spent rather than rationed."""
+    rects = _zoompan_rects(1920, 1080, seconds=4.0, effect="pan_up")
+    steps = {abs(rects[i][3] - rects[i - 1][3]) for i in range(1, len(rects))}
+    assert min(steps) >= 1 and max(steps) <= 4
+
+
+@pytest.mark.parametrize("effect", EVERY_EFFECT)
+def test_a_drift_still_spends_the_travel_it_was_asked_for(effect):
+    """Never stalling would be easy if the drift simply moved less, so this
+    pins the other end: each effect still crosses essentially all of the
+    headroom the chosen zoom leaves it."""
+    read_w, read_h, _w, _h = kenburns_geometry(1920, 1080)
+    rects = _zoompan_rects(1920, 1080, seconds=15.0, effect=effect)
+    if effect in ("pan_up", "pan_down"):
+        room, axis = read_h - int(read_h / 1.12), 3
+    elif effect.startswith("pan"):
+        room, axis = read_w - int(read_w / 1.12), 2
+    else:
+        room, axis = read_w - int(read_w / 1.12), 0
+    spent = max(r[axis] for r in rects) - min(r[axis] for r in rects)
+    assert spent >= room * 0.98, f"{spent} of {room}"
+
+
+def test_a_long_slow_drift_is_carried_by_the_downscale_not_by_reading_bigger():
+    """A 12% zoom over 30s is a genuinely sub-pixel motion — the same travel over
+    five times the frames — and no affordable read size fixes it. Writing above
+    the frame and scaling back down is what keeps it smooth, because the step
+    that survives lands at half size and gets averaged across the downscale."""
+    for width, height in FRAME_SIZES_TO_CHECK:
+        _r, _rh, write_w, write_h = kenburns_geometry(width, height)
+        if (write_w, write_h) == (width, height):
+            continue                             # 4K writes at frame size
+        assert write_w >= width * 2 or write_h >= height * 2, (width, height)
+
+
+def test_reading_is_never_smaller_than_writing():
+    """That would have zoompan upscaling just to fill its own output."""
+    for size in ((854, 480), (1280, 720), (1920, 1080), (3840, 2160), (2160, 3840)):
+        read_w, read_h, write_w, write_h = kenburns_geometry(*size)
+        assert read_w >= write_w and read_h >= write_h
+
+
+def test_a_portrait_frame_is_budgeted_by_pixels_not_by_width():
+    """Scaling a 9:16 frame by a width rule would build an enormous buffer."""
+    read_w, read_h, _w, _h = kenburns_geometry(1080, 1920)
+    assert read_w * read_h <= 24_000_000 * 1.02
+
+
+def test_ken_burns_travel_is_written_against_the_frame_count_not_a_step():
+    """An incremental `zoom+step` drifts with the frame rate; `on/N` does not.
+
+    A zoom drives the crop's *width* along that sweep — 6530 read pixels down
+    to 5830 — rather than ramping the zoom factor, so the picture crosses the
+    frame at one speed instead of accelerating, and the width is guaranteed to
+    round to a new value every frame. The half pixel keeps `iw/z` off the
+    boundary the truncation would otherwise sit on.
+    """
+    graph = _graph(_shot(_kb(), duration=6.0))          # 6s at 30fps = 180 frames
+    assert "z=6530/(6530+0.5-700*on/180)" in graph
+    # Two frames past the shot, so `-t` cuts before zoompan restarts its ramp.
+    assert "d=182" in graph
+
+
+def test_zoom_out_starts_wide_and_closes_in_on_one():
+    """The same sweep read the other way: it opens from the tightest crop and
+    lands on the picture at 1:1."""
+    graph = _graph(_shot(_kb("zoom_out"), duration=6.0))
+    assert "z=6530/(5830+0.5+700*on/180)" in graph
+
+
+@pytest.mark.parametrize("effect,swept,pinned", [
+    ("pan_right", "x=700*on/180", "y=197"),
+    ("pan_left", "x=700*(1-on/180)", "y=197"),
+    ("pan_down", "y=394*on/180", "x=350"),
+    ("pan_up", "y=394*(1-on/180)", "x=350"),
+])
+def test_a_pan_holds_the_zoom_and_sweeps_one_axis(effect, swept, pinned):
+    """The swept axis is written in the whole read pixels zoompan truncates to,
+    and the axis that isn't swept is a number rather than an expression — an
+    expression there could round its way onto a different pixel and drift the
+    picture sideways through a vertical pan."""
+    graph = _graph(_shot(_kb(effect), duration=6.0))
+    assert "z=1.1200:" in graph
+    assert swept in graph and pinned in graph
+
+
+def test_no_ken_burns_expression_needs_escaping():
+    """A comma or colon in an expression would be read as a filtergraph
+    separator, so every expression here is deliberately free of both."""
+    chain = F.kenburns_chain("in", "out", width=1920, height=1080, fps=30,
+                             duration=6.0, effect="pan_right", amount=0.2)
+    zoompan = chain[chain.index("zoompan=") + len("zoompan="):]
+    # Only the zoompan call itself — the trailing scale is a separate filter.
+    zoompan = zoompan.split(",")[0]
+    for option in zoompan.split(":"):
+        assert "," not in option
+
+
+def test_a_cycling_zoom_in_and_out_use_the_same_wave():
+    """A shot too long to cross its travel at a pixel a frame rubber-bands A to
+    B to A instead of crawling — the same triangle drives both directions, only
+    the sign each applies it with differs. It is counted in pixels rather than
+    as a fraction because each frame is worth exactly one of them."""
+    wave = "(700-abs((on-1400*floor(on/1400))-700))"
+    assert f"z=6530/(6530+0.5-{wave})" in _graph(_shot(_kb("zoom_in"), duration=200.0))
+    assert f"z=6530/(5830+0.5+{wave})" in _graph(_shot(_kb("zoom_out"), duration=200.0))
+
+
+def test_a_cycling_pan_still_only_sweeps_one_axis_and_holds_the_zoom():
+    right = _graph(_shot(_kb("pan_right"), duration=200.0))
+    left = _graph(_shot(_kb("pan_left"), duration=200.0))
+    assert "z=1.1200:" in right and "z=1.1200:" in left
+    assert "x=(700-abs((on-1400*floor(on/1400))-700))" in right
+    # The falling half is the same triangle mirrored, which is just the abs.
+    assert "x=abs((on-1400*floor(on/1400))-700)" in left
+
+
+def test_a_travel_too_small_to_rubber_band_holds_each_pixel_instead():
+    """A 2% drift has about seventy read pixels to spend, so a leg at a pixel a
+    frame would be over in two and a half seconds and the picture would visibly
+    wobble. Under KENBURNS_MIN_LEG_SECONDS the sweep holds each pixel for a
+    fixed number of frames and never reverses at all. It still steps — nothing
+    can move less than a pixel — but on a cadence that doesn't beat, and it
+    crosses 64 of the 68 pixels it centres itself in."""
+    graph = _graph(_shot(_kb("pan_up", amount=0.02), duration=15.0))
+    assert "y=68-floor(on/7)" in graph
+
+
+def test_the_hold_cadence_is_the_same_every_time_it_steps():
+    """The point of holding rather than rounding a fractional rate: the gaps
+    between moves are all equal, so there is no slow beat in them."""
+    rects = _zoompan_rects(1920, 1080, seconds=15.0, effect="pan_up", amount=0.02)
+    moves = [i for i in range(1, len(rects)) if rects[i] != rects[i - 1]]
+    assert len({b - a for a, b in zip(moves, moves[1:])}) == 1
+
+
+def test_no_ken_burns_expression_needs_escaping_when_cycling():
+    """Same invariant as above, for the cycling branch: the wave is built from
+    floor/abs and arithmetic only — never ffmpeg's comma-separated mod() — so
+    nothing here needs escaping either."""
+    chain = F.kenburns_chain("in", "out", width=1920, height=1080, fps=30,
+                             duration=600.0, effect="pan_right", amount=0.2)
+    zoompan = chain[chain.index("zoompan=") + len("zoompan="):].split(",")[0]
+    for option in zoompan.split(":"):
+        assert "," not in option
+
+
+def test_the_zoom_never_travels_further_than_what_was_read():
+    """Past that the zoom magnifies pixels rather than revealing them, so a
+    wildly over-asked amount closes on the output width and stops there."""
+    read_w, _h, _ww, _wh = kenburns_geometry(3840, 2160)
+    chain = F.kenburns_chain("in", "out", width=3840, height=2160, fps=30,
+                             duration=4.0, effect="zoom_in", amount=5.0)
+    assert f"z={read_w}/({read_w}+0.5-{read_w - 3840}*on/120)" in chain
+
+
+def test_a_video_background_is_never_given_ken_burns():
+    """The footage already moves; drifting it as well would fight the content."""
+    options = _kb()
+    assert F.kenburns_effect_for("video_muted", 0, options) is None
+    assert F.kenburns_effect_for("video_sound", 0, options) is None
+    assert "zoompan" not in _graph(_shot(options, kind="video_muted"))
+
+
+def test_cards_hold_still_unless_they_are_opted_in():
+    assert F.kenburns_effect_for("card", 0, _kb()) is None
+    assert F.kenburns_effect_for("card", 0, _kb(include_cards=True)) == "zoom_in"
+
+
+def test_an_included_card_zooms_from_the_centre_and_never_pans():
+    """A card's text is drawn into the picture, so a pan would walk it out of frame."""
+    options = _kb("pan_right", include_cards=True)
+    assert F.kenburns_effect_for("card", 0, options) == "zoom_in"
+    graph = _graph(_shot(options, kind="card"))
+    assert "x=iw/2-(iw/zoom/2)" in graph
+
+
+def test_alternate_rotates_deterministically_so_a_rerender_matches():
+    options = _kb("alternate")
+    picks = [F.kenburns_effect_for("still", i, options) for i in range(5)]
+    assert picks == ["zoom_in", "pan_right", "zoom_out", "pan_left", "zoom_in"]
+
+
+def test_a_host_without_zoompan_renders_the_shot_still(monkeypatch):
+    monkeypatch.setattr(F, "_filter_cache", frozenset({"overlay"}))
+    assert "zoompan" not in _graph(_shot(_kb()))
+
+
+def test_ken_burns_sits_under_the_overlay_so_the_watermark_stays_pinned():
+    argv = F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=6.0,
+        output="s.mp4", options=_kb(), preview=False, overlay_png="ov.png", index=0,
+    )
+    graph = _graph(argv)
+    assert graph.index("zoompan") < graph.index("overlay=0:0")
+
+
+# ── background music ─────────────────────────────────────────────────────────
+
+def _music(**kwargs):
+    return MusicSpec(enabled=True, url="/media/u/bed.mp3", **kwargs)
+
+
+def test_scoring_a_render_never_re_encodes_the_picture():
+    """The bed only touches the audio, so the video stream is passed through."""
+    argv = F.build_music_command("in.mp4", "bed.mp3", "out.mp4",
+                                 duration=40.0, spec=_music(), duck=False)
+    assert argv[argv.index("-c:v") + 1] == "copy"
+    assert argv[argv.index("-c:a") + 1] == "aac"
+    assert argv[argv.index("-map") + 1] == "0:v"
+
+
+def test_a_short_bed_loops_and_a_long_one_is_cut_to_the_video():
+    argv = F.build_music_command("in.mp4", "bed.mp3", "out.mp4",
+                                 duration=40.0, spec=_music(), duck=False)
+    assert argv[argv.index("-stream_loop") + 1] == "-1"
+    assert argv[argv.index("-stream_loop") + 2] == "-i"      # loops the bed, not the video
+    assert argv[argv.index("-t") + 1] == "40.000"
+    assert "duration=first" in _graph(argv)
+
+
+def test_the_mix_does_not_let_amix_halve_the_narration():
+    """amix normalises by input count by default, which buries the voice."""
+    assert "normalize=0" in _graph(
+        F.build_music_command("in.mp4", "b.mp3", "o.mp4",
+                              duration=40.0, spec=_music(), duck=False))
+
+
+def test_ducking_compresses_the_bed_against_the_narration():
+    graph = _graph(F.build_music_command("in.mp4", "b.mp3", "o.mp4",
+                                         duration=40.0, spec=_music(), duck=True))
+    # The narration has to be split: it is both the key and part of the mix.
+    assert "[0:a]asplit=2[nar][key]" in graph
+    assert "[m][key]sidechaincompress=" in graph
+    assert "[nar][bed]amix=inputs=2:normalize=0:duration=first[a]" in graph
+
+
+def test_without_ducking_the_bed_is_mixed_flat():
+    graph = _graph(F.build_music_command("in.mp4", "b.mp3", "o.mp4",
+                                         duration=40.0, spec=_music(), duck=False))
+    assert "sidechaincompress" not in graph
+    assert "[0:a][m]amix=inputs=2:normalize=0:duration=first[a]" in graph
+
+
+def test_the_bed_fades_in_at_the_start_and_out_at_the_end():
+    graph = _graph(F.build_music_command(
+        "in.mp4", "b.mp3", "o.mp4", duration=40.0,
+        spec=_music(fade_in=2.0, fade_out=3.0), duck=False))
+    assert "afade=t=in:st=0:d=2.000" in graph
+    assert "afade=t=out:st=37.000:d=3.000" in graph
+
+
+def test_a_video_shorter_than_the_fade_out_still_builds_a_valid_graph():
+    graph = _graph(F.build_music_command(
+        "in.mp4", "b.mp3", "o.mp4", duration=1.0,
+        spec=_music(fade_out=5.0), duck=False))
+    assert "afade=t=out:st=0.000:d=5.000" in graph
+
+
+# ── the finished video's timeline ────────────────────────────────────────────
+
+
+# ── pauses around headings ───────────────────────────────────────────────────
+
+def _narration(text, paragraph=350, heading=800):
+    return chunk_narration(text, paragraph_pause_ms=paragraph, heading_pause_ms=heading)
+
+
+def test_a_heading_is_held_on_both_sides():
+    """A full stop is all a voice has between a paragraph and the heading after
+    it, so the two run together in one breath unless real silence is inserted."""
+    chunks = _narration("Ends here.\n\nA New Chapter.\n\nBegins now.")
+    assert [c.text for c in chunks] == ["Ends here.", "A New Chapter.", "Begins now."]
+    assert [c.pause_after_ms for c in chunks] == [800, 800, 0]
+
+
+def test_prose_without_a_heading_still_travels_as_one_request():
+    """Splitting where no pause is wanted would buy nothing and cost a TTS call."""
+    chunks = _narration("Just prose. More of the same prose.")
+    assert len(chunks) == 1
+    assert chunks[0].pause_after_ms == 0
+
+
+def test_an_ordinary_block_join_is_not_a_break():
+    """Blocks are joined with a single newline; only a blank line marks a pause,
+    so marking has to be deliberate rather than accidental."""
+    chunks = _narration("One paragraph.\nAnother paragraph.")
+    assert len(chunks) == 1
+
+
+def test_turning_the_pause_off_restores_the_old_single_chunk():
+    chunks = _narration("Ends here.\n\nA New Chapter.\n\nBegins now.", heading=0)
+    assert len(chunks) == 1
+    assert chunks[0].pause_after_ms == 0
+
+
+def test_back_to_back_headings_are_held_once_not_twice():
+    chunks = _narration("Body.\n\nFirst Heading.\n\n\nSecond Heading.\n\nMore body.")
+    assert [c.text for c in chunks] == [
+        "Body.", "First Heading.", "Second Heading.", "More body.",
+    ]
+    assert [c.pause_after_ms for c in chunks] == [800, 800, 800, 0]
+
+
+def test_a_long_section_keeps_the_shorter_pause_between_its_own_chunks():
+    """Only the gap at a heading is the long one; splitting an oversized section
+    is a mechanical necessity, not a place anyone wants a beat."""
+    section = " ".join(f"Sentence number {i}." for i in range(400))
+    chunks = _narration(f"{section}\n\nA Heading.")
+    assert len(chunks) > 2
+    assert chunks[-2].pause_after_ms == 800     # the last chunk before the heading
+    assert chunks[0].pause_after_ms == 350      # inside the section
+    assert chunks[-1].pause_after_ms == 0
+
+
+def test_nothing_is_held_after_the_final_chunk():
+    """A trailing pause would just pad the end of the shot."""
+    for text in ("Alone.", "A.\n\nB.", "A.\n\nB.\n\nC."):
+        assert _narration(text)[-1].pause_after_ms == 0
+
+
+def test_blank_narration_produces_no_chunks():
+    assert _narration("") == []
+    assert _narration("\n\n   \n\n") == []
+
+
+# ── build_narration_chunks: heading pauses + pause markup, combined ─────────
+# This is what synthesize_shot actually calls by default. The markup handling (ellipsis, [pause:...], blank lines) was wired
+# in here after users found it had never been reachable at all: RenderOptions
+# only ever fed chunk_narration, which has no notion of pause markup.
+
+def _chunks(text, **kwargs):
+    opts = RenderOptions(**kwargs)
+    return build_narration_chunks(text, options=opts)
+
+
+def test_a_plain_sentence_period_never_forces_a_split():
+    """Unlike the read-aloud player, an ordinary paragraph keeps its natural
+    one-breath prosody — only punctuation someone typed on purpose pauses."""
+    chunks = _chunks("First sentence. Second sentence. Third sentence.")
+    assert len(chunks) == 1
+    assert chunks[0].text == "First sentence. Second sentence. Third sentence."
+
+
+@pytest.mark.parametrize("ellipsis", ["...", "…"])
+def test_an_ellipsis_pauses_regardless_of_spelling(ellipsis):
+    chunks = _chunks(f"Wait for it{ellipsis} here it comes.")
+    assert [c.text for c in chunks] == ["Wait for it" + ellipsis, "here it comes."]
+    assert chunks[0].pause_after_ms > 0
+    assert chunks[-1].pause_after_ms == 0
+
+
+def test_an_explicit_pause_marker_is_honoured_and_stripped():
+    chunks = _chunks("Then you took a side [pause:1200] really took a side.")
+    assert [c.text for c in chunks] == ["Then you took a side", "really took a side."]
+    assert chunks[0].pause_after_ms == 1200
+    assert "[pause" not in "".join(c.text for c in chunks)
+
+
+def test_a_heading_boundary_still_pauses_through_pause_markup():
+    """The blank line _set_apart wraps a heading in is exactly the "\\n\\n"
+    trigger pause_markup already understands — heading_pause_ms drives it."""
+    chunks = _chunks("Ends here.\n\nA New Chapter.\n\nBegins now.", heading_pause_ms=2000)
+    assert [c.text for c in chunks] == ["Ends here.", "A New Chapter.", "Begins now."]
+    assert [c.pause_after_ms for c in chunks] == [2000, 2000, 0]
+
+
+def test_heading_pause_off_disables_the_blank_line_without_gluing_words():
+    """A regression guard: dropping the "\\n\\n" trigger entirely used to also
+    drop its whitespace, gluing 'text.Heading' together with no space."""
+    chunks = _chunks("Ends here.\n\nA New Chapter.", heading_pause_ms=0)
+    assert len(chunks) == 1
+    assert chunks[0].text == "Ends here. A New Chapter."
+
+
+def test_a_long_stretch_with_no_markup_still_falls_back_to_length_splitting():
+    """paragraph_pause_ms's one remaining job: a section pause_markup left as
+    a single chunk that is still too long for one TTS request."""
+    section = " ".join(f"Sentence number {i}." for i in range(400))
+    chunks = _chunks(section, paragraph_pause_ms=3000, heading_pause_ms=0)
+    assert len(chunks) > 1
+    assert chunks[0].pause_after_ms == 3000
+    assert chunks[-1].pause_after_ms == 0
+
+
+def test_blank_narration_produces_no_chunks_via_markup_too():
+    assert _chunks("") == []
+    assert _chunks("   ") == []
+
+
+# ── the per-shot timeout scales with the shot, instead of being flat ────────
+
+def test_a_short_shot_gets_the_old_flat_floor():
+    assert F.shot_timeout(3.0) == F.SHOT_TIMEOUT_SECONDS
+    assert F.shot_timeout(0.0) == F.SHOT_TIMEOUT_SECONDS
+
+
+def test_a_long_shot_gets_a_budget_scaled_to_its_own_length():
+    """A flat cap is wrong because a shot is not a fixed amount of work — an
+    eight-minute still and a three-second card used to get the same 900s."""
+    assert F.shot_timeout(200.0) == 200.0 * F.SHOT_TIMEOUT_FACTOR
+
+
+def test_the_exact_shot_that_failed_in_production_now_gets_room_to_finish():
+    """Shot 34 from job 3d815257: a 502.678s still that hit the flat 900s cap
+    and was killed with 40% of its own length still left to encode."""
+    assert F.shot_timeout(502.678) > 900
+    assert F.shot_timeout(502.678) >= 502.678 * 2  # comfortable headroom, not just enough
+
+
+def test_the_timeout_still_has_a_ceiling():
+    assert F.shot_timeout(10_000.0) == F.SHOT_TIMEOUT_CEILING
+
+
+# ── a timeout becomes a readable error, not a severed argv ──────────────────
+
+def test_a_timeout_is_reported_as_a_short_readable_message(monkeypatch):
+    """subprocess.TimeoutExpired stringifies as the whole argv followed by the
+    reason — over a thousand characters for a real shot command — and the
+    worker truncates error_message to 500, which used to cut the reason off
+    the end entirely. The message here has to be short enough, on its own, to
+    survive that truncation with the reason still in it."""
+    def _fake_run(argv, **kwargs):
+        raise F.subprocess.TimeoutExpired(cmd=argv, timeout=kwargs.get("timeout", 900))
+    monkeypatch.setattr(F.subprocess, "run", _fake_run)
+
+    with pytest.raises(F.FFmpegError) as excinfo:
+        F.run(["ffmpeg"] + ["-argument"] * 200, timeout=900)
+
+    message = str(excinfo.value)
+    assert len(message) < 500
+    assert "900" in message
+
+
+def test_the_original_timeout_is_chained_so_the_full_argv_still_reaches_the_log(monkeypatch):
+    def _fake_run(argv, **kwargs):
+        raise F.subprocess.TimeoutExpired(cmd=argv, timeout=kwargs.get("timeout", 900))
+    monkeypatch.setattr(F.subprocess, "run", _fake_run)
+
+    with pytest.raises(F.FFmpegError) as excinfo:
+        F.run(["ffmpeg", "-i", "in.mp4", "out.mp4"], timeout=900)
+    assert isinstance(excinfo.value.__cause__, F.subprocess.TimeoutExpired)
+
+
+def test_a_non_zero_exit_is_still_reported_as_before(monkeypatch):
+    """The timeout handling must not swallow the ordinary failure path."""
+    class _Result:
+        returncode = 1
+        stderr = b"encoder error: unsupported pixel format"
+    monkeypatch.setattr(F.subprocess, "run", lambda *a, **k: _Result())
+    with pytest.raises(F.FFmpegError, match="unsupported pixel format"):
+        F.run(["ffmpeg"])
+
+
+# ── Ken Burns cycles instead of stalling on a shot too long for one sweep ───
+
+def test_a_normal_length_shot_fits_inside_one_leg():
+    """A 6s shot at 12% travel is nowhere near long enough to need cycling: a
+    leg runs one frame per pixel of travel, and 1080p has 394 of them."""
+    rise, _fall = F.kenburns_sweep(394, 6 * 30, 30)
+    assert rise == "394*on/180"
+
+
+def test_the_exact_shot_that_used_to_go_still_now_needs_many_legs():
+    """502.678s at 12% travel on a 1080p frame — the shot that used to render
+    eight minutes of a static image because one sweep across it would crawl
+    under a hundredth of a pixel a frame. It still can't sweep once across its
+    own length, so it sweeps a leg it can, many times."""
+    rise, _fall = F.kenburns_sweep(394, int(502.678 * 30), 30)
+    assert "floor(on/788)" in rise          # a triangle, not a single ramp
+
+
+def test_raising_travel_lengthens_the_leg():
+    """Travel is the discoverable lever: turning it up gives the sweep more
+    pixels, and a leg spends one of them a frame, so it runs longer before it
+    has to start cycling."""
+    read_w, read_h, _w, _h = kenburns_geometry(1920, 1080)
+    legs = [read_h - int(read_h / (1 + amount)) for amount in (0.12, 0.40)]
+    assert legs[1] > legs[0]
+    # And the longer one still sweeps a shot the shorter one would have cycled.
+    assert "floor" in F.kenburns_sweep(legs[0], legs[0] + 1, 30)[0]
+    assert "floor" not in F.kenburns_sweep(legs[1], legs[0] + 1, 30)[0]
+
+
+def test_a_degenerate_travel_or_length_still_builds_a_usable_sweep():
+    """A zero period would divide by zero building the wave, and a zero frame
+    count would divide by zero building the ramp, so both are floored at one."""
+    for rise, fall in (F.kenburns_sweep(0, 180, 30), F.kenburns_sweep(394, 0, 30)):
+        assert rise and fall
+        for expression in (rise, fall):
+            assert "/0" not in expression and "," not in expression
+
+
+def test_the_leg_floor_is_what_picks_the_hold_over_the_rubber_band():
+    """Either side of KENBURNS_MIN_LEG_SECONDS, at the same shot length: a
+    travel that can sustain a long enough leg rubber-bands, and one that can't
+    holds each pixel instead of reversing every second or two."""
+    floor_px = int(KENBURNS_MIN_LEG_SECONDS * 30)
+    assert "abs" in F.kenburns_sweep(floor_px, 3000, 30)[0]           # cycles
+    assert "floor(on/" in F.kenburns_sweep(floor_px - 1, 3000, 30)[0]  # holds
+
+
+def test_kenburns_effect_for_no_longer_depends_on_shot_length():
+    """Ken Burns used to be refused outright on a shot long enough that one
+    sweep across it would be too slow to see; kenburns_chain cycles it
+    instead now, so which effect a shot gets never depended on duration in
+    the first place — the parameter was dropped, not just made optional."""
+    options = RenderOptions(ken_burns={"effect": "zoom_in"})
+    assert F.kenburns_effect_for("still", 0, options) == "zoom_in"
+
+
+def test_a_long_shot_cycles_instead_of_stalling():
+    """502.678s at 12% travel on a 1920-wide (1080p) frame — the shot that
+    used to render eight minutes of a completely still image. It now gets a
+    rubber-band cycle: A to B, then B to A, repeating in legs short enough to
+    stay visible, instead of one sweep too slow to see or no motion at all."""
+    options = RenderOptions(ken_burns={"effect": "zoom_in"})
+    argv = F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=502.678,
+        output="s.mp4", options=options, preview=False, index=0,
+    )
+    graph = _graph(argv)
+    assert "z=6530/(6530+0.5-(700-abs((on-1400*floor(on/1400))-700)))" in graph
+    # It pays the same supersample cost as any other drifting shot now — Ken
+    # Burns is no longer refused, so the expense the old gate avoided is back
+    # by design.
+    read_w, read_h, _w, _h = kenburns_geometry(1920, 1080)
+    assert f"scale={read_w}:{read_h}" in graph
+
+
+def test_a_short_shot_still_gets_the_full_supersampled_drift():
+    options = RenderOptions(ken_burns={"effect": "zoom_in"})
+    argv = F.build_shot_command(
+        kind="still", background="bg.png", audio="n.wav", duration=6.0,
+        output="s.mp4", options=options, preview=False, index=0,
+    )
+    assert "zoompan" in _graph(argv)
+
+
+# ── the video path never asks the TTS engine to say nothing ───────────────────
+# Each of these patterns used to become its own TTS request. The provider
+# answered with an empty or error body, which synthesize_shot wrote to a .raw
+# file and handed to ffmpeg — which, unable to identify it, fell back to the
+# rawvideo demuxer and failed the render with "Invalid pixel format".
+
+@pytest.mark.parametrize("body,label", [
+    ("...", "ellipsis beat"),
+    ("..", "two dots"),
+    (". . .", "spaced dots"),
+    ("“...”", "quoted ellipsis"),
+    ("---", "rule of dashes"),
+    ("\U0001F697", "lone emoji"),
+])
+def test_a_wordless_paragraph_never_becomes_a_tts_request(body, label):
+    chunks = _chunks(f"Before this.\n\n{body}\n\nAfter this.", heading_pause_ms=1600)
+    assert [c.text for c in chunks] == ["Before this.", "After this."], label
+    # The beat is still a beat — it just lives as silence on the chunk before it.
+    assert chunks[0].pause_after_ms > 0
+
+
+def test_a_shot_of_pure_punctuation_produces_no_chunks_at_all():
+    """synthesize_shot already turns an empty chunk list into silence at the
+    shot's minimum length, which is the right outcome for a divider slide."""
+    assert _chunks("...\n\n---") == []
+
+
+def test_emoji_are_stripped_from_short_chunks_too():
+    """chunk_text strips emoji, but only runs for a chunk too long for one TTS
+    request — so relying on it left ordinary chunks with their emoji intact and
+    the voice reading them out by description."""
+    chunks = _chunks("Drive the car \U0001F697 home.")
+    joined = "".join(c.text for c in chunks)
+    assert "\U0001F697" not in joined
+    assert joined == "Drive the car home."
+
+
+def test_a_bed_without_a_window_is_not_trimmed_or_delayed():
+    graph = _graph(F.build_music_command("in.mp4", "b.mp3", "o.mp4",
+                                         duration=40.0, spec=_music(), duck=False))
+    assert "atrim" not in graph and "adelay" not in graph and "apad" not in graph
+
+
+def test_a_bed_windowed_between_an_intro_and_an_outro():
+    """It starts after the intro, stops before the outro, and fades at those edges."""
+    graph = _graph(F.build_music_command(
+        "in.mp4", "b.mp3", "o.mp4", duration=40.0,
+        spec=_music(fade_in=2.0, fade_out=3.0), duck=False, start=5.0, end=32.0))
+    assert "afade=t=in:st=0:d=2.000" in graph
+    # 27 seconds of bed, faded over its own last three.
+    assert "afade=t=out:st=24.000:d=3.000" in graph
+    assert "atrim=end=27.000,adelay=5000|5000,apad[m]" in graph
+    # The output still runs the whole video, intro and outro included.
+    argv = F.build_music_command("in.mp4", "b.mp3", "o.mp4", duration=40.0,
+                                 spec=_music(), duck=False, start=5.0, end=32.0)
+    assert argv[argv.index("-t") + 1] == "40.000"
+
+
+def test_a_bed_stopping_before_an_outro_needs_no_delay():
+    graph = _graph(F.build_music_command(
+        "in.mp4", "b.mp3", "o.mp4", duration=40.0,
+        spec=_music(fade_out=0.0), duck=True, end=30.0))
+    assert "atrim=end=30.000,apad[m]" in graph
+    assert "adelay" not in graph
+    # Padded rather than ended, so the ducking compressor keeps running.
+    assert "[m][key]sidechaincompress=" in graph
+
+
+def test_a_window_out_of_range_is_clamped_to_the_video():
+    graph = _graph(F.build_music_command(
+        "in.mp4", "b.mp3", "o.mp4", duration=10.0,
+        spec=_music(fade_out=0.0), duck=False, start=12.0, end=50.0))
+    # Nothing left to score: a sliver, never a negative trim.
+    assert "atrim=end=0.100" in graph
diff --git a/backend/tests/test_render_integration.py b/backend/tests/test_render_integration.py
new file mode 100644
index 0000000..80fc6a3
--- /dev/null
+++ b/backend/tests/test_render_integration.py
@@ -0,0 +1,140 @@
+"""A real render, through real ffmpeg, of a small video with everything M2 adds.
+
+GAM and Notes are faked (`fake_siblings.py`): GAM serves generated files, and Notes'
+speech answers every chunk with a tone of known length. Rendered at preview size.
+"""
+
+import json
+import os
+import subprocess
+
+import pytest
+
+from app.gam.client import GamClient
+from app.render import ffmpeg as F
+from app.render.renderer import RenderRefused, render
+from app.render.tts import NotesSpeech, SpeechError
+from app.spec.validation import parse_spec
+
+pytestmark = pytest.mark.skipif(not F.ffmpeg_available(), reason="needs ffmpeg")
+
+
+SPEC = {
+    "title": "Water Wars",
+    "output": {"chapters": True, "subtitles": "sidecar"},
+    "style": {"transition": {"style": "fade", "duration": 0.4}},
+    "assets": {
+        "a_pic": {"from": "gam", "id": "p", "type": "image"},
+        "a_reel": {"from": "gam", "id": "r", "type": "video"},
+        "a_song1": {"from": "gam", "id": "a", "type": "audio"},
+        "a_song2": {"from": "gam", "id": "b", "type": "audio"},
+    },
+    "segments": [
+        {"id": "s_title", "kind": "card", "role": "title", "chapter": "Start",
+         "card": {"variant": "title", "title": "Water Wars"}},
+        {"id": "s_valley", "kind": "scene", "chapter": "The valley",
+         "visual": {"asset": "a_pic", "motion": {
+             "effect": "path", "from": {"x": 0, "y": 0, "w": 1}, "to": {"x": 0.5, "y": 0.4, "w": 0.4}}},
+         "narration": {"beats": [{"id": "b1", "text": "The valley used to run clear."},
+                                 {"id": "b2", "text": "Now every drop is fought over."}]}},
+        {"id": "s_river", "kind": "scene", "chapter": "The river",
+         "transition_in": {"style": "dissolve", "duration": 1.0},
+         "visual": {"asset": "a_reel", "trim": {"in": 5, "out": 9}},
+         "narration": {"beats": [{"id": "b1", "text": "The river is lower every year."}]}},
+        {"id": "s_voice", "kind": "clip",
+         "visual": {"asset": "a_reel", "trim": {"in": 2, "out": 5}, "audio": "play"}},
+    ],
+    "audio_tracks": [
+        {"id": "m_one", "asset": "a_song1",
+         "start": {"segment": "s_valley", "edge": "start"},
+         "end": {"segment": "s_river", "edge": "start", "offset": 1.0}, "fade_out": 1.0},
+        {"id": "m_two", "asset": "a_song2",
+         "start": {"segment": "s_river", "edge": "start", "offset": -1.0},
+         "end": "video_end", "fade_in": 1.0},
+    ],
+}
+
+
+def _render(tmp_path, spec_data, preview=True):
+    spec, issues = parse_spec(spec_data)
+    assert spec is not None, issues
+    gam, speech = GamClient(None), NotesSpeech(None)
+    stages = []
+    try:
+        return render(
+            spec=spec, preview=preview, work_dir=str(tmp_path / "work"),
+            out_dir=str(tmp_path / "out"), data_dir=str(tmp_path / "data"), user_id="u",
+            gam=gam, speech=speech, progress=lambda s, p, d: stages.append((s, p)),
+            max_segments=200, max_narration_chars=10_000,
+        ), speech
+    finally:
+        gam.close()
+        speech.close()
+
+
+def _probe(path):
+    out = subprocess.run(["ffprobe", "-v", "error", "-show_streams", "-show_chapters",
+                          "-show_format", "-of", "json", path], capture_output=True, check=True)
+    return json.loads(out.stdout)
+
+
+def test_a_video_with_a_path_a_dissolve_a_clip_and_two_crossfading_tracks(tmp_path, library):
+    result, speech = _render(tmp_path, SPEC)
+
+    info = _probe(result.video)
+    # MP4 carries chapter marks as a `data` stream of their own.
+    kinds = sorted(s["codec_type"] for s in info["streams"] if s["codec_type"] != "data")
+    assert kinds == ["audio", "video"]
+    video = next(s for s in info["streams"] if s["codec_type"] == "video")
+    assert (video["width"], video["height"]) == (854, 480)
+    # Card (3.5) + valley (two 1.5 s beats + pauses) + river (2.5 floor or narration)
+    # + the 3 s clip, minus the 1 s dissolve: about 13-15 s. The exact figure is the
+    # compiler's; what matters here is that the stitched file agrees with it.
+    assert 11.0 < result.duration < 17.0
+    assert float(info["format"]["duration"]) == pytest.approx(result.duration, abs=0.25)
+    assert [c["tags"]["title"] for c in info["chapters"]] == ["Start", "The valley", "The river"]
+    assert result.subtitles and os.path.getsize(result.subtitles) > 0
+    assert result.poster and os.path.exists(result.poster)
+    assert result.warnings == []
+
+    # Every chunk but the first was read with the engine Notes pinned on the first.
+    assert speech.provider == "deepgram"
+    assert library.spoken[0]["provider"] == "auto"
+    assert all(s["provider"] == "deepgram" for s in library.spoken[1:])
+    assert len(library.spoken) == 3
+
+    # The media cache: a second render fetches nothing from GAM's media again.
+    fetched = [r for r in library.requests if r.url.path.startswith("/media/")]
+    assert len(fetched) == 4
+    library.requests.clear()
+    again, _ = _render(tmp_path, SPEC)
+    assert not [r for r in library.requests if r.url.path.startswith("/media/")]
+    assert again.duration == pytest.approx(result.duration, abs=0.05)
+
+
+def test_a_full_render_refuses_placeholders_and_note_files_and_says_which(tmp_path, library):
+    data = json.loads(json.dumps(SPEC))
+    data["assets"]["a_find"] = {"from": "search", "query": "a dry riverbed"}
+    data["assets"]["a_note"] = {"from": "notes", "url": "/media/u/x.png", "type": "image",
+                                "label": "the old map"}
+    data["segments"][1]["visual"] = {"asset": "a_find"}
+    data["segments"].append({"id": "s_map", "kind": "scene", "visual": {"asset": "a_note"}})
+    with pytest.raises(RenderRefused) as refused:
+        _render(tmp_path, data, preview=False)
+    message = str(refused.value)
+    assert "a dry riverbed" in message and "the old map" in message
+
+
+def test_a_preview_draws_a_placeholder_as_a_slate(tmp_path, library):
+    data = json.loads(json.dumps(SPEC))
+    data["assets"]["a_find"] = {"from": "search", "query": "a dry riverbed"}
+    data["segments"][1]["visual"] = {"asset": "a_find"}
+    result, _ = _render(tmp_path, data, preview=True)
+    assert os.path.exists(result.video)
+
+
+def test_a_notes_too_old_to_pin_the_voice_stops_the_render(tmp_path, library):
+    library.speech_provider = None
+    with pytest.raises(SpeechError) as stopped:
+        _render(tmp_path, SPEC)
+    assert "gecko-notes#211" in str(stopped.value)
diff --git a/backend/tests/test_render_shot_cache.py b/backend/tests/test_render_shot_cache.py
new file mode 100644
index 0000000..fce2457
--- /dev/null
+++ b/backend/tests/test_render_shot_cache.py
@@ -0,0 +1,130 @@
+"""The shot cache: what makes a retry reuse an encode, and what must not.
+
+No ffmpeg here — the cache only ever sees file names and bytes.
+"""
+
+import os
+import time
+
+from app.render import shot_cache as C
+
+
+def _work(tmp_path):
+    work = tmp_path / "work"
+    work.mkdir()
+    return str(work)
+
+
+def _key(work, argv=("ffmpeg", "-i", "a.wav", "shot_0001.mp4"), inputs=("a.wav",)):
+    return C.shot_key(list(argv), list(inputs), work)
+
+
+def test_same_command_and_inputs_share_a_key(tmp_path):
+    work = _work(tmp_path)
+    (tmp_path / "work" / "a.wav").write_bytes(b"narration")
+    assert _key(work) == _key(work)
+
+
+def test_output_name_does_not_matter_but_everything_else_does(tmp_path):
+    work = _work(tmp_path)
+    (tmp_path / "work" / "a.wav").write_bytes(b"narration")
+    base = _key(work)
+    # A shot that merely moved position keeps its encode...
+    assert _key(work, argv=("ffmpeg", "-i", "a.wav", "shot_0009.mp4")) == base
+    # ...but a different filtergraph, duration or codec setting does not.
+    assert _key(work, argv=("ffmpeg", "-t", "3", "-i", "a.wav", "shot_0001.mp4")) != base
+
+
+def test_generated_inputs_are_keyed_on_content(tmp_path):
+    work = _work(tmp_path)
+    audio = tmp_path / "work" / "a.wav"
+    audio.write_bytes(b"one")
+    first = _key(work)
+    audio.write_bytes(b"two")
+    assert _key(work) != first
+
+
+def test_user_media_is_keyed_on_size_and_mtime_not_content(tmp_path):
+    work = _work(tmp_path)
+    media = tmp_path / "photo.jpg"
+    media.write_bytes(b"x" * 10)
+    first = C.shot_key(["ffmpeg", "out.mp4"], [str(media)], work)
+    assert C.shot_key(["ffmpeg", "out.mp4"], [str(media)], work) == first
+    media.write_bytes(b"x" * 11)
+    assert C.shot_key(["ffmpeg", "out.mp4"], [str(media)], work) != first
+
+
+def test_missing_and_absent_inputs_are_tolerated(tmp_path):
+    work = _work(tmp_path)
+    assert _key(work, inputs=("nope.png", None, ""))
+
+
+def test_a_miss_then_a_hit(tmp_path):
+    cache = C.ShotCache(str(tmp_path), "u1")
+    work = tmp_path / "work"
+    work.mkdir()
+    (work / "shot_0000.mp4").write_bytes(b"encoded")
+
+    assert cache.restore("k", str(work / "again.mp4")) is None
+    cache.store("k", str(work / "shot_0000.mp4"), plain=False)
+
+    retry = C.ShotCache(str(tmp_path), "u1")
+    assert retry.restore("k", str(work / "again.mp4")) is False
+    assert (work / "again.mp4").read_bytes() == b"encoded"
+
+
+def test_the_plain_fallback_is_remembered(tmp_path):
+    cache = C.ShotCache(str(tmp_path), "u1")
+    src = tmp_path / "shot.mp4"
+    src.write_bytes(b"encoded")
+    cache.store("k", str(src), plain=True)
+    assert C.ShotCache(str(tmp_path), "u1").restore("k", str(tmp_path / "out.mp4")) is True
+
+
+def test_a_cached_shot_survives_the_scratch_directory_being_removed(tmp_path):
+    import shutil
+    cache = C.ShotCache(str(tmp_path), "u1")
+    work = tmp_path / "work"
+    work.mkdir()
+    (work / "shot.mp4").write_bytes(b"encoded")
+    cache.store("k", str(work / "shot.mp4"), plain=False)
+    shutil.rmtree(work)
+
+    work.mkdir()
+    assert C.ShotCache(str(tmp_path), "u1").restore("k", str(work / "shot.mp4")) is False
+    assert (work / "shot.mp4").read_bytes() == b"encoded"
+
+
+def test_users_do_not_share_entries(tmp_path):
+    src = tmp_path / "shot.mp4"
+    src.write_bytes(b"encoded")
+    C.ShotCache(str(tmp_path), "u1").store("k", str(src), plain=False)
+    assert C.ShotCache(str(tmp_path), "u2").restore("k", str(tmp_path / "out.mp4")) is None
+
+
+def test_a_successful_render_discards_what_it_used(tmp_path):
+    cache = C.ShotCache(str(tmp_path), "u1")
+    src = tmp_path / "shot.mp4"
+    src.write_bytes(b"encoded")
+    cache.store("k", str(src), plain=True)
+    cache.discard_used()
+    assert C.ShotCache(str(tmp_path), "u1").restore("k", str(tmp_path / "out.mp4")) is None
+    assert os.listdir(cache.dir) == []
+
+
+def test_prune_removes_only_stale_entries(tmp_path):
+    cache = C.ShotCache(str(tmp_path), "u1")
+    # Separate sources: a cache entry is a hard link, so two entries filed from
+    # one file would share an inode and therefore a modification time.
+    for name in ("old", "new"):
+        (tmp_path / f"{name}_src.mp4").write_bytes(b"encoded")
+        cache.store(name, str(tmp_path / f"{name}_src.mp4"), plain=False)
+    stale = time.time() - 10 * C.MAX_AGE_SECONDS
+    os.utime(os.path.join(cache.dir, "old.mp4"), (stale, stale))
+
+    C.prune(str(tmp_path))
+    assert os.listdir(cache.dir) == ["new.mp4"]
+
+
+def test_prune_with_no_cache_yet_is_a_no_op(tmp_path):
+    C.prune(str(tmp_path))
diff --git a/backend/tests/test_renders_api.py b/backend/tests/test_renders_api.py
new file mode 100644
index 0000000..4f57f20
--- /dev/null
+++ b/backend/tests/test_renders_api.py
@@ -0,0 +1,153 @@
+"""Rendering over HTTP: estimate, start, follow, fetch, cancel; and who may."""
+
+import json
+import time
+
+import pytest
+from jose import jwt
+
+from app.config import settings
+from app.render import ffmpeg as F
+from app.render import worker
+from tests.test_render_integration import SPEC
+
+needs_ffmpeg = pytest.mark.skipif(not F.ffmpeg_available(), reason="needs ffmpeg")
+
+
+@pytest.fixture
+def engine_for_worker(engine, monkeypatch):
+    """The worker opens its own sessions; point them at the test database."""
+    monkeypatch.setattr(worker.queue, "engine", engine)
+    return engine
+
+
+def _project(client, spec=SPEC):
+    res = client.post("/api/projects", json={"spec": spec})
+    assert res.status_code == 201, res.text
+    return res.json()["data"]
+
+
+def _start(client, project_id, preview=True, **kwargs):
+    return client.post(f"/api/projects/{project_id}/renders", json={"preview": preview}, **kwargs)
+
+
+def test_the_estimate_says_how_long_and_what_would_stop_a_render(auth_client):
+    data = json.loads(json.dumps(SPEC))
+    data["assets"]["a_find"] = {"from": "search", "query": "a dry riverbed"}
+    data["segments"][1]["visual"] = {"asset": "a_find"}
+    project = _project(auth_client, data)
+
+    body = auth_client.post(f"/api/projects/{project['id']}/estimate").json()["data"]
+
+    # card 3.5 + valley (~58 chars / 15 + pauses) + river (2.5 floor) + the 3 s clip
+    assert 10 < body["seconds"] < 16
+    assert body["narration_chars"] == len("The valley used to run clear.") + len(
+        "Now every drop is fought over.") + len("The river is lower every year.")
+    assert body["blocks_render"] == ["Footage still to find: “a dry riverbed”."]
+    assert body["blocks_preview"] == []
+
+
+def test_a_full_render_is_refused_until_the_placeholders_are_found(auth_client):
+    data = json.loads(json.dumps(SPEC))
+    data["assets"]["a_find"] = {"from": "search", "query": "a dry riverbed"}
+    data["segments"][1]["visual"] = {"asset": "a_find"}
+    project = _project(auth_client, data)
+
+    refused = _start(auth_client, project["id"], preview=False)
+    assert refused.status_code == 409
+    assert refused.json()["detail"]["code"] == "not_renderable"
+    assert "a dry riverbed" in refused.json()["detail"]["message"]
+    # A preview draws it as a slate instead.
+    assert _start(auth_client, project["id"], preview=True).status_code == 202
+
+
+def test_one_render_at_a_time_per_project(auth_client):
+    project = _project(auth_client)
+    first = _start(auth_client, project["id"])
+    assert first.status_code == 202
+    assert first.json()["data"]["status"] == "queued"
+    assert first.json()["data"]["version"] == 1
+    again = _start(auth_client, project["id"])
+    assert again.status_code == 409 and again.json()["detail"]["code"] == "render_running"
+
+
+@needs_ffmpeg
+def test_a_render_runs_as_its_requester_and_its_files_are_served_signed(
+        client, library, engine_for_worker):
+    token = jwt.encode({"sub": "notes-user-1", "username": "gecko", "exp": int(time.time()) + 3600},
+                       settings.jwt_secret_key, algorithm="HS256")
+    auth = {"Authorization": f"Bearer {token}"}
+    project = client.post("/api/projects", json={"spec": SPEC}, headers=auth).json()["data"]
+    job = _start(client, project["id"], headers=auth).json()["data"]
+
+    worker._run(job["id"])
+
+    done = client.get(f"/api/renders/{job['id']}", headers=auth).json()["data"]
+    assert done["status"] == "done", done
+    assert done["progress"] == 100
+    assert 11 < done["duration"] < 17
+    assert done["narration_chars"] > 0
+    # Media and narration were fetched as the user who asked, nobody else.
+    sibling_calls = [r for r in library.requests if not r.url.path.startswith("/media/")]
+    assert sibling_calls and all(r.headers.get("authorization") == f"Bearer {token}"
+                                 for r in sibling_calls)
+
+    video = client.get(done["video_url"])
+    assert video.status_code == 200 and video.headers["content-type"] == "video/mp4"
+    ranged = client.get(done["video_url"], headers={"Range": "bytes=0-99"})
+    assert ranged.status_code == 206 and len(ranged.content) == 100
+    assert client.get(done["poster_url"]).status_code == 200
+    tampered = done["video_url"].replace("video.mp4", "poster.jpg")
+    assert client.get(tampered).status_code == 403
+
+    listed = client.get(f"/api/projects/{project['id']}/renders", headers=auth).json()
+    assert [r["id"] for r in listed["data"]] == [job["id"]]
+
+    # Deleting the project takes its renders, files and all, with it.
+    assert client.delete(f"/api/projects/{project['id']}", headers=auth).status_code == 204
+    assert not (worker.renders_dir() / job["id"]).exists()
+
+
+@needs_ffmpeg
+def test_a_render_that_cannot_reach_notes_says_why(auth_client, library, engine_for_worker):
+    library.speech_provider = None
+    project = _project(auth_client)
+    job = _start(auth_client, project["id"]).json()["data"]
+    worker._run(job["id"])
+    failed = auth_client.get(f"/api/renders/{job['id']}").json()["data"]
+    assert failed["status"] == "error"
+    assert "gecko-notes#211" in failed["error"]
+    assert failed["video_url"] is None
+
+
+def test_a_render_queued_before_a_restart_is_ended_not_rerun(auth_client, engine_for_worker,
+                                                             monkeypatch):
+    project = _project(auth_client)
+    job = _start(auth_client, project["id"]).json()["data"]
+    worker._tokens.clear()  # what a restart does to the in-memory tokens
+    worker.queue.recover_pending()
+    ended = auth_client.get(f"/api/renders/{job['id']}").json()["data"]
+    assert ended["status"] == "error"
+    assert "restart" in ended["error"]
+
+
+def test_a_queued_render_can_be_cancelled(auth_client, engine_for_worker):
+    project = _project(auth_client)
+    job = _start(auth_client, project["id"]).json()["data"]
+    cancelled = auth_client.post(f"/api/renders/{job['id']}/cancel").json()["data"]
+    assert cancelled["status"] == "cancelled"
+    worker._run(job["id"])  # the worker, reaching it later, leaves it alone
+    assert auth_client.get(f"/api/renders/{job['id']}").json()["data"]["status"] == "cancelled"
+
+
+def test_another_users_render_does_not_exist_for_you(auth_client, switch_user):
+    project = _project(auth_client)
+    job = _start(auth_client, project["id"]).json()["data"]
+    switch_user("someone-else")
+    for method, url in (("get", f"/api/renders/{job['id']}"),
+                        ("post", f"/api/renders/{job['id']}/cancel"),
+                        ("delete", f"/api/renders/{job['id']}"),
+                        ("post", f"/api/projects/{project['id']}/renders"),
+                        ("get", f"/api/projects/{project['id']}/renders")):
+        kwargs = {"json": {"preview": True}} if url.endswith("/renders") and method == "post" else {}
+        assert getattr(auth_client, method)(url, **kwargs).status_code == 404, (method, url)
diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
index f757b84..e4de8a0 100644
--- a/docker-compose.prod.yml
+++ b/docker-compose.prod.yml
@@ -11,6 +11,17 @@
 #   COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml
 
 services:
+  # GVC's server calls GAM and Notes at their public names (GAM_BASE_URL,
+  # NOTES_BASE_URL). On the suite's server all three run on one machine, and from
+  # inside a container those names resolve to the machine's own public address,
+  # which the host does not route back in (hairpin NAT): every search failed with
+  # `gam_unavailable`. Pointing them at the Docker host reaches Caddy directly,
+  # with the same names and so the same TLS certificates.
+  gvc-backend:
+    extra_hosts:
+      - "assets.geckopico.com:host-gateway"
+      - "notes.geckopico.com:host-gateway"
+
   frontend:
     networks:
       - default
diff --git a/docker-compose.yml b/docker-compose.yml
index bd0d29b..b658177 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -5,7 +5,9 @@ services:
     build: ./backend
     restart: unless-stopped
     volumes:
-      - ./data/db:/app/data/db
+      # All of data/: the database, finished renders, and the cache of GAM files a
+      # render fetched, so a rebuild keeps all three.
+      - ./data:/app/data
     environment:
       - DATABASE_URL=sqlite:////app/data/db/gvc.db
       # Must match gecko-notes'. GVC verifies the sessions Notes issues; a different
@@ -13,9 +15,14 @@ services:
       - JWT_SECRET_KEY=${JWT_SECRET_KEY}
       - CORS_ORIGIN=${CORS_ORIGIN:-}
       - NOTES_BASE_URL=${NOTES_BASE_URL:-https://notes.geckopico.com}
-      - GAM_BASE_URL=${GAM_BASE_URL:-https://gam.geckopico.com}
+      - GAM_BASE_URL=${GAM_BASE_URL:-https://assets.geckopico.com}
       - GAM_TIMEOUT_SECONDS=${GAM_TIMEOUT_SECONDS:-30}
       - NOTE_MEDIA_MAX_MB=${NOTE_MEDIA_MAX_MB:-4096}
+      - RENDER_CONCURRENCY=${RENDER_CONCURRENCY:-1}
+      - RENDER_MAX_SEGMENTS=${RENDER_MAX_SEGMENTS:-200}
+      - RENDER_MAX_NARRATION_CHARS=${RENDER_MAX_NARRATION_CHARS:-60000}
+      - RENDER_CACHE_MAX_GB=${RENDER_CACHE_MAX_GB:-20}
+      - MEDIA_URL_TTL_SECONDS=${MEDIA_URL_TTL_SECONDS:-3600}
       - ADMIN_USERS=${ADMIN_USERS:-}
       - ENVIRONMENT=${ENVIRONMENT:-production}
     # Never published to the host: the frontend proxies it, and ProxyHeadersMiddleware
@@ -41,7 +48,7 @@ services:
       # The CSP's connect-src; must agree with the backend's value.
       - NOTES_BASE_URL=${NOTES_BASE_URL:-https://notes.geckopico.com}
       # The CSP's img-src and media-src, for GAM thumbnails and previews; same rule.
-      - GAM_BASE_URL=${GAM_BASE_URL:-https://gam.geckopico.com}
+      - GAM_BASE_URL=${GAM_BASE_URL:-https://assets.geckopico.com}
     depends_on:
       - gvc-backend
     networks:
diff --git a/docs/plan-of-attack.md b/docs/plan-of-attack.md
index 6eac23d..6b3f8bb 100644
--- a/docs/plan-of-attack.md
+++ b/docs/plan-of-attack.md
@@ -276,6 +276,7 @@ GAM-1 and GAM-2 come first. They're small, and M1 below depends on them.
 |---|---|---|
 | GN-V1 | "Make video" posts the spec from `POST /api/video/spec` to GVC's `POST /api/projects/import` and opens the returned project | The one-way push (D3) |
 | ~~GN-V2~~ | **Not needed.** Notes serves `/media/*` with no authentication at all (`gecko-notes/backend/app/main.py`), so GVC's server fetches a pushed note's files directly. Worth knowing for its own sake: anyone holding a note's media URL can fetch it, which is Notes' existing behaviour, not something GVC adds | |
+| GN-V4 | `POST /api/settings/speech/tts` takes `provider` and `voice` (null: the account's) and names the resolved pair in `X-Speech-Provider` / `X-Speech-Voice`. **[davior/gecko-notes#211](https://github.com/davior/gecko-notes/pull/211).** GVC refuses to narrate against a Notes without it, rather than risk a video that changes voice | M2: narration read through Notes, one voice per video |
 | GN-V3 | Once GVC renders (M2): Notes' own render pipeline is retired (the Notes spec doc §10, Phase 4) | One renderer, not two |
 
 ## Milestones
@@ -286,7 +287,7 @@ Each milestone ends with something you can use, not just with code merged.
 |---|---|---|---|
 | **M0** | **Genesis** | Skeleton from GAM: `config.py`, `clock.py`, Alembic, shadow-user auth on the Notes JWT, `/api/health`, Dockerfiles (backend with ffmpeg), compose, nginx, CI. `Project` (current spec as JSON) and `ProjectVersion` (snapshot, author, message). Spec Pydantic model copied from Notes with S1–S3 applied, `0.1 → 0.2` migration on load. Projects API: blank project (title card + one empty scene), paste a spec, `POST /api/projects/import` for a Notes push, versions and revert, validation with errors by path. React shell: project list, a plain scene list (add, reorder, delete, edit narration), a JSON tab with live validation, version history. | You can sign in with your Notes account, make a video's structure by hand, paste the Notes spec doc's §6 example and see it validate (or see exactly why not), and import a spec Notes produced |
 | **M1** | **GAM as the library** | GAM-1 applied (gam#36). GVC's server calls GAM as the signed-in user by forwarding their own Notes token, so GAM's ownership checks hold and no service account exists. Search GAM from a scene: results with transcript snippets and the moment's time; picking a hit places it as muted b-roll or as a clip with its own sound, trimmed to what was said (padded, and sized by a placeholder's `moment`). `search` placeholders resolved the same way. Thumbnails and names looked up per page load, since GAM's signed URLs expire, and loaded straight from GAM (CSP `img-src`/`media-src`). A pushed note's media copied into GAM (D3). The byte cache keyed on asset id and checksum moved to M2: nothing reads media bytes until the renderer does. | A scene's footage is found by what is said in it ("where people talk about *X*") and lands in the spec as a trimmed GAM clip |
-| **M2** | **Native renderer** | Engine copied from Notes (D1). The compile step from the Notes spec doc §5.8, plus S1 framing. Renders: per-join transitions with the project default, per-scene motion and framing, N audio tracks with fades, crossfades and ducking, trims, card/scene/clip. All media from GAM (M1), its bytes fetched through signed URLs into a local cache keyed on asset id and checksum. Placeholder slates. Preview (480p) and full render as jobs. Download, and file the render back to GAM (GAM-3). Credits from GAM attribution. TTS through Notes' `POST /api/settings/speech/tts`, so voices and keys stay in one place (open decision 3). | A spec with two music tracks crossfading at a scene cut, a dissolve into one scene, and a Ken Burns path over a chosen part of a picture renders correctly |
+| **M2** | **Native renderer** | **Built (M2a).** Engine copied from Notes (`app/render/`: ffmpeg, compose, narration, pause markup, shot cache, with Notes' 359 tests). `compile.py` is the §5.8 compile step, done natively: scenes cut at quote/code beats, defaults cascading field by field, per-join transitions (blends overlap, dips draw in-shot, cuts cut), anchors resolved to seconds. Ken Burns paths between two frames (S1), trimmed and held clips, N audio tracks with fades, crossfades and ducking. Media fetched from GAM into a cache keyed on GAM id and size; placeholders drawn as slates in a preview, refusing a full render. Narration read per beat through Notes (GN-V4), so beat anchors are exact. Render jobs on GAM's runner; the requester's token held in memory only, so a restart ends a render rather than storing a credential. Finished files at signed, ranged URLs. Editor: per-scene transition and Ken Burns (with a frame editor), a Soundtrack tab, a Render tab with estimate, progress and the result. Left for M2b: timed text/lower-third/image overlays, Save to GAM (GAM-3), credits. | A spec with two music tracks crossfading at a scene cut, a dissolve into one scene, and a Ken Burns path over a chosen part of a picture renders correctly |
 | **M3** | **Editor** | The M0 scene list grows into the storyboard: a card per segment (thumbnail, label, first line), lanes for audio tracks and overlays against the segments, a per-scene panel (visual, trim, transition, motion with a drag-a-box framing tool, voice), a project defaults panel. Sliders take their ranges from the schema (the Notes spec doc, open decision 12). Undo/redo over `ProjectVersion`. | You can build and fix a whole video by hand without opening the JSON tab |
 | **M4** | **AI drafting** | Providers copied from GAM's M6. "New video from a prompt": brief → spec (D2) with GAM search as a tool, and placeholders for gaps, with one repair round. Also from selected GAM assets. Cost estimate before running, usage recorded. | "Make a 3-minute video about *X* using clips where people talk about it" produces a spec that previews immediately |
 | **M5** | **AI editing** | The Notes spec doc §8.2 operations, addressed by id. Chat beside the storyboard. Suggestions staged and accepted one by one. Generate placeholders sent to GAM's M8. | "Change the music after the second chapter to something calmer, and dissolve into the last scene" becomes reviewed, applied edits |
diff --git a/frontend/Dockerfile b/frontend/Dockerfile
index 6bd912c..0e2df29 100644
--- a/frontend/Dockerfile
+++ b/frontend/Dockerfile
@@ -23,7 +23,7 @@ EXPOSE 80
 # not need its own image. Substituted at container start, not build time.
 ENV NOTES_BASE_URL=https://notes.geckopico.com
 # img-src and media-src: thumbnails and previews load from GAM directly.
-ENV GAM_BASE_URL=https://gam.geckopico.com
+ENV GAM_BASE_URL=https://assets.geckopico.com
 
 # Only these two are substituted; nginx's own $variables ($uri, $host, $remote_addr …)
 # must survive untouched, which is why envsubst is given an explicit list rather than
diff --git a/frontend/nginx.conf b/frontend/nginx.conf
index f33c1d3..43710fd 100644
--- a/frontend/nginx.conf
+++ b/frontend/nginx.conf
@@ -12,6 +12,20 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # A finished render, by signed URL (the signature is what authorises it), so it
+    # must reach the backend rather than be looked for on disk here. `^~` so the
+    # static-asset regex below cannot shadow a poster .jpg.
+    location ^~ /media/ {
+        proxy_pass http://backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        # Range requests are what let a long video scrub instead of downloading whole.
+        proxy_buffering off;
+        proxy_read_timeout 300s;
+        add_header X-Content-Type-Options "nosniff";
+    }
+
     location /api/ {
         proxy_pass http://backend/api/;
         proxy_set_header Host $host;
diff --git a/frontend/src/api/projects.ts b/frontend/src/api/projects.ts
index 61d39d6..ac6c69a 100644
--- a/frontend/src/api/projects.ts
+++ b/frontend/src/api/projects.ts
@@ -26,11 +26,50 @@ export interface Trim {
   out?: number
 }
 
+/** A crop of a picture, as fractions of it. Its height follows from the output's
+ *  aspect ratio, so there is no `h`. */
+export interface Frame {
+  x: number
+  y: number
+  w: number
+}
+
+export interface Motion {
+  effect: string
+  amount?: number
+  from?: Frame
+  to?: Frame
+  ease?: 'linear' | 'in_out'
+}
+
 export interface Visual {
   asset: string
   trim?: Trim
   audio?: 'mute' | 'play'
   loop?: boolean
+  fit?: string
+  motion?: Motion
+  [key: string]: unknown
+}
+
+export type Anchor =
+  | 'video_start'
+  | 'video_end'
+  | { segment?: string; beat?: string; edge: 'start' | 'end'; offset?: number }
+
+export interface AudioTrack {
+  id: string
+  kind?: 'music' | 'sfx' | 'voiceover'
+  asset: string
+  start: Anchor
+  /** Absent: play once to its natural end. */
+  end?: Anchor
+  trim?: Trim
+  loop?: boolean
+  volume?: number
+  duck_under_narration?: boolean
+  fade_in?: number
+  fade_out?: number
   [key: string]: unknown
 }
 
@@ -76,6 +115,13 @@ export interface VideoSpec {
   source?: { kind: 'note' | 'brief'; [key: string]: unknown }
   assets?: Record<string, AssetRef>
   segments: Segment[]
+  audio_tracks?: AudioTrack[]
+  output?: { aspect?: '16:9' | '9:16' | '1:1'; [key: string]: unknown }
+  style?: {
+    transition?: { style?: string; duration?: number }
+    motion?: Motion
+    [key: string]: unknown
+  }
   [key: string]: unknown
 }
 
diff --git a/frontend/src/api/renders.ts b/frontend/src/api/renders.ts
new file mode 100644
index 0000000..ac8b380
--- /dev/null
+++ b/frontend/src/api/renders.ts
@@ -0,0 +1,83 @@
+import client from '@/api/client'
+
+/** Rendering a project, following the render, and its finished files. */
+
+export type RenderStatus = 'queued' | 'processing' | 'done' | 'error' | 'cancelled'
+
+export interface Render {
+  id: string
+  project_id: string
+  /** The project version rendered; later edits never change it. */
+  version: number
+  preview: boolean
+  status: RenderStatus
+  stage: string
+  progress: number
+  detail: string
+  error: string | null
+  warnings: string[]
+  duration: number | null
+  size_bytes: number | null
+  narration_chars: number
+  /** Signed and short-lived: refetch the render for fresh ones. */
+  video_url: string | null
+  subtitles_url: string | null
+  poster_url: string | null
+  created_at: string
+  updated_at: string
+}
+
+export interface Estimate {
+  seconds: number
+  /** True when a clip's length is unknown, so `seconds` is a lower bound. */
+  seconds_is_floor: boolean
+  narration_chars: number
+  /** Reasons a full render would be refused, and a preview. */
+  blocks_render: string[]
+  blocks_preview: string[]
+}
+
+export const ACTIVE: RenderStatus[] = ['queued', 'processing']
+
+interface DataResponse<T> {
+  data: T
+}
+
+interface ListResponse<T> {
+  data: T[]
+  total: number
+}
+
+export const rendersApi = {
+  estimate(projectId: string): Promise<Estimate> {
+    return client
+      .post<DataResponse<Estimate>>(`/projects/${projectId}/estimate`)
+      .then((r) => r.data.data)
+  },
+
+  start(projectId: string, preview: boolean): Promise<Render> {
+    return client
+      .post<DataResponse<Render>>(`/projects/${projectId}/renders`, { preview })
+      .then((r) => r.data.data)
+  },
+
+  list(projectId: string): Promise<Render[]> {
+    return client
+      .get<ListResponse<Render>>(`/projects/${projectId}/renders`)
+      .then((r) => r.data.data)
+  },
+
+  get(id: string): Promise<Render> {
+    return client.get<DataResponse<Render>>(`/renders/${id}`).then((r) => r.data.data)
+  },
+
+  cancel(id: string): Promise<Render> {
+    return client
+      .post<DataResponse<Render>>(`/renders/${id}/cancel`)
+      .then((r) => r.data.data)
+  },
+
+  remove(id: string): Promise<void> {
+    return client.delete(`/renders/${id}`).then(() => undefined)
+  },
+}
diff --git a/frontend/src/components/FootageSearch.tsx b/frontend/src/components/FootageSearch.tsx
index ce2d881..6ff7f56 100644
--- a/frontend/src/components/FootageSearch.tsx
+++ b/frontend/src/components/FootageSearch.tsx
@@ -8,8 +8,9 @@ import { clock, momentTrim, type MomentSize, type PlaceMode } from '@/spec/foota
  * - `scene`: footage for one scene, as b-roll under its narration or as a clip with
  *   its own sound.
  * - `resolve`: whatever answers a `search` placeholder.
+ * - `track`: a sound to play under the video: music, an effect, a voice.
  */
-type Purpose = 'scene' | 'resolve'
+type Purpose = 'scene' | 'resolve' | 'track'
 
 interface Props {
   title: string
@@ -25,6 +26,7 @@ interface Props {
 const TYPES: { id: MediaKind | undefined; label: string }[] = [
   { id: 'video', label: 'Video' },
   { id: 'image', label: 'Pictures' },
+  { id: 'audio', label: 'Sound' },
   { id: undefined, label: 'Everything' },
 ]
 
@@ -205,6 +207,14 @@ export default function FootageSearch({
                       : selected.asset.file_url
                   }
                 />
+              ) : selected.asset.asset_type === 'audio' && selected.asset.file_url ? (
+                <audio
+                  key={selected.asset.id}
+                  controls
+                  preload="metadata"
+                  className="w-full"
+                  src={selected.asset.file_url}
+                />
               ) : selected.asset.file_url ? (
                 <img
                   src={selected.asset.file_url}
@@ -213,17 +223,29 @@ export default function FootageSearch({
                 />
               ) : null}
               <p className="text-sm text-gray-700 dark:text-gray-300">
-                {trim
-                  ? `Uses ${clock(trim.in)}–${clock(trim.out)} (${Math.round(trim.out - trim.in)} s)`
-                  : isVideo
-                    ? 'Uses the whole video'
-                    : 'A still picture'}
+                {purpose === 'track'
+                  ? selected.asset.duration_seconds
+                    ? `${clock(selected.asset.duration_seconds)} long`
+                    : 'A sound'
+                  : trim
+                    ? `Uses ${clock(trim.in)}–${clock(trim.out)} (${Math.round(trim.out - trim.in)} s)`
+                    : isVideo
+                      ? 'Uses the whole video'
+                      : 'A still picture'}
               </p>
               {selected.asset.credit && (
                 <p className="text-xs text-gray-500">{selected.asset.credit}</p>
               )}
               <div className="flex flex-wrap gap-2">
-                {purpose === 'resolve' ? (
+                {purpose === 'track' ? (
+                  <button
+                    type="button"
+                    className="btn btn-primary"
+                    onClick={() => onPick(selected, 'broll')}
+                  >
+                    Use this track
+                  </button>
+                ) : purpose === 'resolve' ? (
                   <button
                     type="button"
                     className="btn btn-primary"
diff --git a/frontend/src/components/FrameEditor.tsx b/frontend/src/components/FrameEditor.tsx
new file mode 100644
index 0000000..ff359a0
--- /dev/null
+++ b/frontend/src/components/FrameEditor.tsx
@@ -0,0 +1,158 @@
+import { useRef, useState, type PointerEvent } from 'react'
+import type { Frame } from '@/api/projects'
+import { clampFrame } from '@/spec/scene'
+
+interface Props {
+  imageUrl: string | null
+  /** The picture's width over its height. */
+  pictureAspect: number
+  /** The video's width over its height. */
+  outputAspect: number
+  from: Frame
+  to: Frame
+  onChange: (next: { from: Frame; to: Frame }) => void
+}
+
+type Which = 'from' | 'to'
+
+const COLOURS: Record<Which, string> = { from: '#22c55e', to: '#ef4444' }
+const NAMES: Record<Which, string> = { from: 'Start', to: 'End' }
+
+/**
+ * Where a Ken Burns move starts and ends, as two boxes over the picture.
+ *
+ * Drag a box to move it; drag its corner to make it bigger or smaller. Its shape is
+ * the video's, so a frame can never ask for a stretched picture (the spec stores only
+ * its width). The numbers underneath are the same frames, for exact positions.
+ */
+export default function FrameEditor({
+  imageUrl,
+  pictureAspect,
+  outputAspect,
+  from,
+  to,
+  onChange,
+}: Props) {
+  const area = useRef<HTMLDivElement>(null)
+  const [drag, setDrag] = useState<{
+    which: Which
+    mode: 'move' | 'size'
+    startX: number
+    startY: number
+    frame: Frame
+  } | null>(null)
+  // A frame's height as a fraction of the picture's, per unit of its width.
+  const heightPerWidth = pictureAspect / outputAspect
+  const frames = { from, to }
+
+  function set(which: Which, frame: Frame) {
+    const next = { ...frames, [which]: clampFrame(frame, heightPerWidth) }
+    onChange(next)
+  }
+
+  function begin(which: Which, mode: 'move' | 'size', event: PointerEvent) {
+    event.preventDefault()
+    event.stopPropagation()
+    ;(event.target as Element).setPointerCapture?.(event.pointerId)
+    setDrag({
+      which,
+      mode,
+      startX: event.clientX,
+      startY: event.clientY,
+      frame: frames[which],
+    })
+  }
+
+  function move(event: PointerEvent) {
+    if (!drag || !area.current) return
+    const box = area.current.getBoundingClientRect()
+    const dx = (event.clientX - drag.startX) / box.width
+    const dy = (event.clientY - drag.startY) / box.height
+    const f = drag.frame
+    set(
+      drag.which,
+      drag.mode === 'move' ? { ...f, x: f.x + dx, y: f.y + dy } : { ...f, w: f.w + dx }
+    )
+  }
+
+  return (
+    <div className="space-y-2" aria-label="Ken Burns frames">
+      <div
+        ref={area}
+        className="relative w-full select-none overflow-hidden rounded bg-gray-200 dark:bg-gray-700"
+        style={{ aspectRatio: String(pictureAspect) }}
+        onPointerMove={move}
+        onPointerUp={() => setDrag(null)}
+      >
+        {imageUrl && (
+          <img
+            src={imageUrl}
+            alt=""
+            className="absolute inset-0 h-full w-full"
+            draggable={false}
+          />
+        )}
+        {(['from', 'to'] as Which[]).map((which) => {
+          const f = frames[which]
+          return (
+            <div
+              key={which}
+              role="button"
+              aria-label={`${NAMES[which]} frame`}
+              className="absolute cursor-move border-2"
+              style={{
+                left: `${f.x * 100}%`,
+                top: `${f.y * 100}%`,
+                width: `${f.w * 100}%`,
+                height: `${Math.min(1, f.w * heightPerWidth) * 100}%`,
+                borderColor: COLOURS[which],
+                background: `${COLOURS[which]}22`,
+              }}
+              onPointerDown={(e) => begin(which, 'move', e)}
+            >
+              <span
+                className="absolute left-1 top-0.5 text-[10px] font-semibold"
+                style={{ color: COLOURS[which] }}
+              >
+                {NAMES[which]}
+              </span>
+              <span
+                aria-label={`Resize ${NAMES[which].toLowerCase()} frame`}
+                className="absolute -bottom-1 -right-1 h-3 w-3 cursor-nwse-resize rounded-sm"
+                style={{ background: COLOURS[which] }}
+                onPointerDown={(e) => begin(which, 'size', e)}
+              />
+            </div>
+          )
+        })}
+      </div>
+      <div className="grid grid-cols-2 gap-2 text-xs">
+        {(['from', 'to'] as Which[]).map((which) => (
+          <fieldset key={which} className="flex items-center gap-1">
+            <legend className="sr-only">{NAMES[which]} frame</legend>
+            <span className="w-8 font-medium" style={{ color: COLOURS[which] }}>
+              {NAMES[which]}
+            </span>
+            {(['x', 'y', 'w'] as const).map((field) => (
+              <label key={field} className="flex items-center gap-0.5">
+                {field}
+                <input
+                  type="number"
+                  step="0.05"
+                  min="0"
+                  max="1"
+                  aria-label={`${NAMES[which]} ${field}`}
+                  className="input w-16 px-1 py-0.5"
+                  value={frames[which][field]}
+                  onChange={(e) =>
+                    set(which, { ...frames[which], [field]: Number(e.target.value) })
+                  }
+                />
+              </label>
+            ))}
+          </fieldset>
+        ))}
+      </div>
+    </div>
+  )
+}
diff --git a/frontend/src/components/RenderPanel.test.tsx b/frontend/src/components/RenderPanel.test.tsx
new file mode 100644
index 0000000..7351352
--- /dev/null
+++ b/frontend/src/components/RenderPanel.test.tsx
@@ -0,0 +1,101 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { rendersApi, type Estimate, type Render } from '@/api/renders'
+import RenderPanel from '@/components/RenderPanel'
+import { useRenderStore } from '@/stores/renders'
+
+const estimate = (overrides: Partial<Estimate> = {}): Estimate => ({
+  seconds: 95,
+  seconds_is_floor: false,
+  narration_chars: 1840,
+  blocks_render: [],
+  blocks_preview: [],
+  ...overrides,
+})
+
+const done: Render = {
+  id: 'r1',
+  project_id: 'p',
+  version: 3,
+  preview: false,
+  status: 'done',
+  stage: '',
+  progress: 100,
+  detail: '',
+  error: null,
+  warnings: ['Blends were joined as cuts.'],
+  duration: 94.2,
+  size_bytes: 12 * 1024 * 1024,
+  narration_chars: 1840,
+  video_url: '/media/renders/r1/video.mp4?exp=1&sig=x',
+  subtitles_url: '/media/renders/r1/subtitles.srt?exp=1&sig=x',
+  poster_url: null,
+  created_at: '2026-10-16T00:00:00',
+  updated_at: '2026-10-16T00:00:00',
+}
+
+beforeEach(() => useRenderStore.getState().reset())
+afterEach(() => vi.restoreAllMocks())
+
+describe('RenderPanel', () => {
+  it('says how long, and plays and offers the latest render', async () => {
+    vi.spyOn(rendersApi, 'list').mockResolvedValue([done])
+    vi.spyOn(rendersApi, 'estimate').mockResolvedValue(estimate())
+    render(<RenderPanel projectId="p" dirty={false} version={3} />)
+
+    expect(
+      await screen.findByText(/About 1:35 long, with 1,840 characters/)
+    ).toBeInTheDocument()
+    expect(document.querySelector('video')?.getAttribute('src')).toBe(done.video_url)
+    expect(screen.getByText('Blends were joined as cuts.')).toBeInTheDocument()
+    expect(screen.getByRole('link', { name: 'Download video' })).toHaveAttribute(
+      'href',
+      done.video_url
+    )
+    expect(screen.getByText('12.0 MB')).toBeInTheDocument()
+  })
+
+  it('will not render unsaved edits, and says why a full render is blocked', async () => {
+    vi.spyOn(rendersApi, 'list').mockResolvedValue([])
+    vi.spyOn(rendersApi, 'estimate').mockResolvedValue(
+      estimate({ blocks_render: ['Footage still to find: “ruins”.'] })
+    )
+    const { rerender } = render(<RenderPanel projectId="p" dirty={true} version={3} />)
+    expect(await screen.findByText('Footage still to find: “ruins”.')).toBeInTheDocument()
+    expect(screen.getByText(/Save first/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Preview' })).toBeDisabled()
+
+    rerender(<RenderPanel projectId="p" dirty={false} version={3} />)
+    expect(screen.getByRole('button', { name: 'Preview' })).toBeEnabled()
+    expect(screen.getByRole('button', { name: 'Render' })).toBeDisabled()
+  })
+
+  it('starts a preview and shows its progress', async () => {
+    vi.spyOn(rendersApi, 'list').mockResolvedValue([])
+    vi.spyOn(rendersApi, 'estimate').mockResolvedValue(estimate())
+    const queued: Render = {
+      ...done,
+      id: 'r2',
+      status: 'processing',
+      stage: 'Narrating',
+      progress: 30,
+      detail: 'shot 2 of 6',
+      video_url: null,
+      preview: true,
+      warnings: [],
+    }
+    const startSpy = vi.spyOn(rendersApi, 'start').mockResolvedValue(queued)
+    render(<RenderPanel projectId="p" dirty={false} version={3} />)
+    await screen.findByText(/About/)
+
+    await userEvent.click(screen.getByRole('button', { name: 'Preview' }))
+
+    expect(startSpy).toHaveBeenCalledWith('p', true)
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '30')
+    expect(
+      screen.getByText(/Preview of version 3: Narrating \(shot 2 of 6\)/)
+    ).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Render' })).toBeDisabled()
+  })
+})
diff --git a/frontend/src/components/RenderPanel.tsx b/frontend/src/components/RenderPanel.tsx
new file mode 100644
index 0000000..208a2f3
--- /dev/null
+++ b/frontend/src/components/RenderPanel.tsx
@@ -0,0 +1,216 @@
+import { useEffect } from 'react'
+import { Clapperboard, Download, Eye, Square, Trash2 } from 'lucide-react'
+import { ACTIVE, type Render } from '@/api/renders'
+import { useRenderStore } from '@/stores/renders'
+import { clock } from '@/spec/footage'
+
+interface Props {
+  projectId: string
+  /** Unsaved edits: a render is of the saved version, so they would be left out. */
+  dirty: boolean
+  /** The saved version, so the estimate follows saves. */
+  version: number
+}
+
+function size(bytes: number | null): string {
+  if (!bytes) return ''
+  return bytes > 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : `${Math.round(bytes / 1024)} KB`
+}
+
+function Status({ render }: { render: Render }) {
+  if (render.status === 'done')
+    return <span className="text-green-700 dark:text-green-400">Done</span>
+  if (render.status === 'error')
+    return <span className="text-red-700 dark:text-red-400">Failed</span>
+  if (render.status === 'cancelled')
+    return <span className="text-gray-500">Cancelled</span>
+  return (
+    <span className="text-blue-700 dark:text-blue-400">{render.stage || 'Waiting'}</span>
+  )
+}
+
+/**
+ * Previewing and rendering the saved project, and the renders made so far.
+ *
+ * A preview is small and fast, and shows placeholders as slates; a full render needs
+ * every placeholder found. Both render the *saved* version, so unsaved edits block
+ * them rather than being silently left out.
+ */
+export default function RenderPanel({ projectId, dirty, version }: Props) {
+  const renders = useRenderStore((s) => s.renders)
+  const estimate = useRenderStore((s) => s.estimate)
+  const starting = useRenderStore((s) => s.starting)
+  const error = useRenderStore((s) => s.error)
+  const load = useRenderStore((s) => s.load)
+  const refreshEstimate = useRenderStore((s) => s.refreshEstimate)
+  const start = useRenderStore((s) => s.start)
+  const cancel = useRenderStore((s) => s.cancel)
+  const remove = useRenderStore((s) => s.remove)
+
+  useEffect(() => {
+    void load(projectId)
+  }, [projectId, load])
+
+  useEffect(() => {
+    void refreshEstimate()
+  }, [version, refreshEstimate])
+
+  const running = renders.find((r) => ACTIVE.includes(r.status))
+  const latest = renders.find((r) => r.status === 'done')
+  const previewBlocks = estimate?.blocks_preview ?? []
+  const renderBlocks = estimate?.blocks_render ?? []
+  const busy = starting || !!running
+
+  return (
+    <div className="space-y-4">
+      {estimate && (
+        <p className="text-sm text-gray-700 dark:text-gray-300">
+          About {estimate.seconds_is_floor ? 'at least ' : ''}
+          {clock(estimate.seconds)} long, with {estimate.narration_chars.toLocaleString()}{' '}
+          characters of narration.
+        </p>
+      )}
+      {dirty && (
+        <p className="text-sm text-amber-700 dark:text-amber-300">
+          Save first: a render is made from the saved version.
+        </p>
+      )}
+      {renderBlocks.length > 0 && (
+        <ul className="list-disc space-y-0.5 pl-5 text-sm text-amber-800 dark:text-amber-200">
+          {renderBlocks.map((b) => (
+            <li key={b}>{b}</li>
+          ))}
+        </ul>
+      )}
+
+      <div className="flex flex-wrap gap-2">
+        <button
+          type="button"
+          className="btn btn-secondary"
+          disabled={dirty || busy || previewBlocks.length > 0}
+          onClick={() => void start(true)}
+          title="Small and quick; placeholders show as slates"
+        >
+          <Eye className="mr-1 inline h-4 w-4" />
+          Preview
+        </button>
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={dirty || busy || renderBlocks.length > 0}
+          onClick={() => void start(false)}
+        >
+          <Clapperboard className="mr-1 inline h-4 w-4" />
+          Render
+        </button>
+      </div>
+
+      {error && (
+        <p role="alert" className="text-sm text-red-600 dark:text-red-400">
+          {error}
+        </p>
+      )}
+
+      {running && (
+        <div className="card space-y-2 p-3" aria-label="Rendering">
+          <div className="flex items-center gap-2 text-sm">
+            <span className="flex-1 text-gray-700 dark:text-gray-300">
+              {running.preview ? 'Preview' : 'Render'} of version {running.version}:{' '}
+              {running.stage || 'waiting to start'}
+              {running.detail && ` (${running.detail})`}
+            </span>
+            <button
+              type="button"
+              className="btn btn-ghost text-xs"
+              onClick={() => void cancel(running.id)}
+            >
+              <Square className="mr-1 inline h-3 w-3" />
+              Stop
+            </button>
+          </div>
+          <div className="h-2 overflow-hidden rounded bg-gray-200 dark:bg-gray-700">
+            <div
+              role="progressbar"
+              aria-valuenow={running.progress}
+              aria-valuemin={0}
+              aria-valuemax={100}
+              className="h-full bg-primary-600 transition-all"
+              style={{ width: `${running.progress}%` }}
+            />
+          </div>
+        </div>
+      )}
+
+      {latest?.video_url && (
+        <div className="space-y-2" aria-label="Latest render">
+          <video
+            key={latest.id}
+            controls
+            preload="metadata"
+            poster={latest.poster_url ?? undefined}
+            className="w-full rounded bg-black"
+            src={latest.video_url}
+          />
+          {latest.warnings.length > 0 && (
+            <ul className="list-disc space-y-0.5 pl-5 text-xs text-amber-700 dark:text-amber-300">
+              {latest.warnings.map((w) => (
+                <li key={w}>{w}</li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+
+      {renders.length > 0 && (
+        <ul className="space-y-1" aria-label="Renders">
+          {renders.map((render) => (
+            <li key={render.id} className="card flex items-center gap-3 p-2 text-xs">
+              <span className="w-24 font-medium text-gray-900 dark:text-gray-100">
+                {render.preview ? 'Preview' : 'Render'} v{render.version}
+              </span>
+              <span className="flex-1">
+                <Status render={render} />
+                {render.error && (
+                  <span className="text-red-700 dark:text-red-400">: {render.error}</span>
+                )}
+              </span>
+              {render.duration !== null && <span>{clock(render.duration)}</span>}
+              <span>{size(render.size_bytes)}</span>
+              {render.video_url && (
+                <a
+                  className="btn btn-ghost p-1"
+                  href={render.video_url}
+                  download
+                  aria-label="Download video"
+                >
+                  <Download className="h-4 w-4" />
+                </a>
+              )}
+              {render.subtitles_url && (
+                <a
+                  className="btn btn-ghost px-1 py-0.5"
+                  href={render.subtitles_url}
+                  download
+                >
+                  .srt
+                </a>
+              )}
+              {!ACTIVE.includes(render.status) && (
+                <button
+                  type="button"
+                  className="btn btn-ghost p-1"
+                  aria-label="Delete render"
+                  onClick={() => void remove(render.id)}
+                >
+                  <Trash2 className="h-4 w-4" />
+                </button>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/components/SceneList.tsx b/frontend/src/components/SceneList.tsx
index 770c15d..6c3a55c 100644
--- a/frontend/src/components/SceneList.tsx
+++ b/frontend/src/components/SceneList.tsx
@@ -1,6 +1,7 @@
 import { ArrowDown, ArrowUp, Plus, Trash2 } from 'lucide-react'
 import type { GamAsset } from '@/api/gam'
 import type { Segment, VideoSpec } from '@/api/projects'
+import SceneSettings from '@/components/SceneSettings'
 import VisualStrip from '@/components/VisualStrip'
 import { removeVisual } from '@/spec/footage'
 import {
@@ -117,6 +118,16 @@ export default function SceneList({
             />
           )}
 
+          {onFindFootage && (
+            <SceneSettings
+              spec={spec}
+              index={index}
+              segment={segment}
+              gamAssets={gamAssets}
+              onChange={onChange}
+            />
+          )}
+
           {segment.kind === 'scene' && (
             <textarea
               className="input min-h-[5rem] w-full"
diff --git a/frontend/src/components/SceneSettings.test.tsx b/frontend/src/components/SceneSettings.test.tsx
new file mode 100644
index 0000000..f12d2e5
--- /dev/null
+++ b/frontend/src/components/SceneSettings.test.tsx
@@ -0,0 +1,86 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+import { describe, expect, it } from 'vitest'
+import type { GamAsset } from '@/api/gam'
+import type { VideoSpec } from '@/api/projects'
+import SceneSettings from '@/components/SceneSettings'
+
+const map: GamAsset = {
+  id: 'p',
+  name: 'Map',
+  asset_type: 'image',
+  duration_seconds: null,
+  width: 1600,
+  height: 900,
+  file_url: 'https://gam.test/p.png',
+  thumb_url: null,
+  credit: '',
+  parent_asset_id: null,
+  in_point: null,
+  out_point: null,
+  missing: false,
+}
+
+const start: VideoSpec = {
+  title: 'T',
+  output: { aspect: '16:9' },
+  style: { transition: { style: 'fade', duration: 0.6 } },
+  assets: { a_map: { from: 'gam', id: 'p' } },
+  segments: [
+    { id: 's0', kind: 'card', card: { variant: 'title', title: 'T' } },
+    { id: 's1', kind: 'scene', visual: { asset: 'a_map' } },
+  ],
+}
+
+let latest = start
+function Harness() {
+  const [spec, setSpec] = useState(start)
+  latest = spec
+  return (
+    <SceneSettings
+      spec={spec}
+      index={1}
+      segment={spec.segments[1]}
+      gamAssets={{ p: map }}
+      onChange={setSpec}
+    />
+  )
+}
+
+describe('SceneSettings', () => {
+  it('sets a transition of its own, keeping the project duration until one is typed', () => {
+    render(<Harness />)
+    fireEvent.change(screen.getByLabelText('Transition into this scene'), {
+      target: { value: 'dissolve' },
+    })
+    expect(latest.segments[1].transition_in).toEqual({ style: 'dissolve' })
+    expect(screen.getByLabelText('Transition length in seconds')).toHaveAttribute(
+      'placeholder',
+      '0.6'
+    )
+    fireEvent.change(screen.getByLabelText('Transition length in seconds'), {
+      target: { value: '1.2' },
+    })
+    expect(latest.segments[1].transition_in).toEqual({ style: 'dissolve', duration: 1.2 })
+    fireEvent.change(screen.getByLabelText('Transition into this scene'), {
+      target: { value: '' },
+    })
+    expect(latest.segments[1].transition_in).toBeUndefined()
+  })
+
+  it('moves the camera between two frames set over the picture', () => {
+    render(<Harness />)
+    fireEvent.change(screen.getByLabelText('Ken Burns move'), {
+      target: { value: 'path' },
+    })
+    expect(latest.segments[1].visual?.motion?.effect).toBe('path')
+    expect(screen.getByRole('button', { name: 'Start frame' })).toBeInTheDocument()
+
+    fireEvent.change(screen.getByLabelText('End x'), { target: { value: '0.55' } })
+    fireEvent.change(screen.getByLabelText('End w'), { target: { value: '0.3' } })
+    expect(latest.segments[1].visual?.motion?.to).toEqual({ x: 0.55, y: 0.3, w: 0.3 })
+    // Too far right for its width: brought back inside the picture.
+    fireEvent.change(screen.getByLabelText('End x'), { target: { value: '0.9' } })
+    expect(latest.segments[1].visual?.motion?.to?.x).toBe(0.7)
+  })
+})
diff --git a/frontend/src/components/SceneSettings.tsx b/frontend/src/components/SceneSettings.tsx
new file mode 100644
index 0000000..ce1b112
--- /dev/null
+++ b/frontend/src/components/SceneSettings.tsx
@@ -0,0 +1,152 @@
+import type { GamAsset } from '@/api/gam'
+import type { Segment, VideoSpec } from '@/api/projects'
+import FrameEditor from '@/components/FrameEditor'
+import {
+  DEFAULT_PATH,
+  MOTIONS,
+  TRANSITIONS,
+  setMotion,
+  setTransition,
+} from '@/spec/scene'
+
+interface Props {
+  spec: VideoSpec
+  index: number
+  segment: Segment
+  gamAssets: Record<string, GamAsset | null>
+  onChange: (next: VideoSpec) => void
+}
+
+const ASPECTS: Record<string, number> = { '16:9': 16 / 9, '9:16': 9 / 16, '1:1': 1 }
+
+/** The GAM asset a scene shows, if the spec's ref resolves to one. */
+function pictureOf(spec: VideoSpec, segment: Segment, gamAssets: Props['gamAssets']) {
+  const key = segment.visual?.asset
+  const ref = key ? spec.assets?.[key] : undefined
+  const id =
+    ref?.from === 'gam' ? ref.id : ref?.from === 'search' ? ref.result?.id : undefined
+  return id ? (gamAssets[id] ?? null) : null
+}
+
+/**
+ * How a scene comes in and how its picture moves. "Project default" removes the
+ * scene's own setting, so changing the project's default later changes this scene too.
+ */
+export default function SceneSettings({
+  spec,
+  index,
+  segment,
+  gamAssets,
+  onChange,
+}: Props) {
+  const transition = segment.transition_in
+  const picture = pictureOf(spec, segment, gamAssets)
+  const isStill = picture?.asset_type === 'image'
+  const motion = segment.visual?.motion
+  const outputAspect = ASPECTS[spec.output?.aspect ?? '16:9'] ?? 16 / 9
+  const pictureAspect =
+    picture?.width && picture?.height ? picture.width / picture.height : outputAspect
+
+  return (
+    <div className="space-y-2 text-xs text-gray-600 dark:text-gray-300">
+      <div className="flex flex-wrap items-center gap-2">
+        {index > 0 && (
+          <label className="flex items-center gap-1">
+            In with
+            <select
+              className="input w-auto py-0.5"
+              aria-label="Transition into this scene"
+              value={transition?.style ?? ''}
+              onChange={(e) =>
+                onChange(
+                  setTransition(
+                    spec,
+                    index,
+                    e.target.value
+                      ? {
+                          style: e.target.value,
+                          ...(transition?.duration !== undefined
+                            ? { duration: transition.duration }
+                            : {}),
+                        }
+                      : undefined
+                  )
+                )
+              }
+            >
+              <option value="">Project default</option>
+              {TRANSITIONS.map((t) => (
+                <option key={t.value} value={t.value}>
+                  {t.label}
+                </option>
+              ))}
+            </select>
+            {transition?.style && transition.style !== 'none' && (
+              <input
+                type="number"
+                min="0.1"
+                max="3"
+                step="0.1"
+                aria-label="Transition length in seconds"
+                className="input w-16 py-0.5"
+                placeholder={String(spec.style?.transition?.duration ?? 0.6)}
+                value={transition.duration ?? ''}
+                onChange={(e) =>
+                  onChange(
+                    setTransition(spec, index, {
+                      style: transition.style,
+                      ...(e.target.value ? { duration: Number(e.target.value) } : {}),
+                    })
+                  )
+                }
+              />
+            )}
+          </label>
+        )}
+        {isStill && (
+          <label className="flex items-center gap-1">
+            Camera
+            <select
+              className="input w-auto py-0.5"
+              aria-label="Ken Burns move"
+              value={motion?.effect ?? ''}
+              onChange={(e) => {
+                const effect = e.target.value
+                onChange(
+                  setMotion(
+                    spec,
+                    index,
+                    !effect
+                      ? undefined
+                      : effect === 'path'
+                        ? { effect: 'path', ...DEFAULT_PATH }
+                        : { effect }
+                  )
+                )
+              }}
+            >
+              <option value="">Project default</option>
+              {MOTIONS.map((m) => (
+                <option key={m.value} value={m.value}>
+                  {m.label}
+                </option>
+              ))}
+            </select>
+          </label>
+        )}
+      </div>
+      {isStill && motion?.effect === 'path' && motion.from && motion.to && (
+        <FrameEditor
+          imageUrl={picture?.file_url ?? picture?.thumb_url ?? null}
+          pictureAspect={pictureAspect}
+          outputAspect={outputAspect}
+          from={motion.from}
+          to={motion.to}
+          onChange={(frames) =>
+            onChange(setMotion(spec, index, { ...motion, ...frames }))
+          }
+        />
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/components/SoundtrackPanel.test.tsx b/frontend/src/components/SoundtrackPanel.test.tsx
new file mode 100644
index 0000000..10c79aa
--- /dev/null
+++ b/frontend/src/components/SoundtrackPanel.test.tsx
@@ -0,0 +1,69 @@
+import { fireEvent, render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useState } from 'react'
+import { describe, expect, it } from 'vitest'
+import type { VideoSpec } from '@/api/projects'
+import SoundtrackPanel from '@/components/SoundtrackPanel'
+
+const start: VideoSpec = {
+  title: 'T',
+  assets: {
+    a_theme: { from: 'gam', id: 'g1', label: 'Theme' },
+    a_close: { from: 'gam', id: 'g2', label: 'Close' },
+  },
+  segments: [
+    { id: 's1', kind: 'scene', label: 'Valley' },
+    { id: 's2', kind: 'scene', label: 'River' },
+  ],
+  audio_tracks: [
+    {
+      id: 'm_1',
+      asset: 'a_theme',
+      start: { segment: 's1', edge: 'start' },
+      end: { segment: 's2', edge: 'end' },
+    },
+    { id: 'm_2', asset: 'a_close', start: { segment: 's2', edge: 'start' } },
+  ],
+}
+
+let latest = start
+function Harness() {
+  const [spec, setSpec] = useState(start)
+  latest = spec
+  return <SoundtrackPanel spec={spec} gamAssets={{}} onChange={setSpec} />
+}
+
+describe('SoundtrackPanel', () => {
+  it('places a track between scenes and crossfades into the next', async () => {
+    render(<Harness />)
+    const theme = screen.getByRole('region', { name: 'Theme' })
+    fireEvent.change(within(theme).getByLabelText('Until'), {
+      target: { value: 'start:s2' },
+    })
+    expect(latest.audio_tracks![0].end).toEqual({ segment: 's2', edge: 'start' })
+
+    const close = screen.getByRole('region', { name: 'Close' })
+    await userEvent.click(
+      within(close).getByRole('button', { name: /Crossfade from the track above/ })
+    )
+    expect(latest.audio_tracks![1].start).toEqual({
+      segment: 's2',
+      edge: 'start',
+      offset: -3,
+    })
+    expect(latest.audio_tracks![0].fade_out).toBe(3)
+
+    fireEvent.change(within(close).getByLabelText('Volume'), { target: { value: '0.5' } })
+    expect(latest.audio_tracks![1].volume).toBe(0.5)
+    expect(within(close).getByText('50%')).toBeInTheDocument()
+
+    // Music is ducked and looped unless told otherwise; an effect is neither.
+    expect(within(close).getByLabelText('Quieter under narration')).toBeChecked()
+    fireEvent.change(within(close).getByLabelText('Kind of track'), {
+      target: { value: 'sfx' },
+    })
+    expect(
+      within(screen.getByRole('region', { name: 'Close' })).getByLabelText('Loop to fill')
+    ).not.toBeChecked()
+  })
+})
diff --git a/frontend/src/components/SoundtrackPanel.tsx b/frontend/src/components/SoundtrackPanel.tsx
new file mode 100644
index 0000000..9b254f1
--- /dev/null
+++ b/frontend/src/components/SoundtrackPanel.tsx
@@ -0,0 +1,254 @@
+import { useState } from 'react'
+import { Music, Plus, Trash2 } from 'lucide-react'
+import type { GamAsset } from '@/api/gam'
+import type { Anchor, AudioTrack, VideoSpec } from '@/api/projects'
+import FootageSearch from '@/components/FootageSearch'
+import { addTrack, crossfadeInto, removeTrack, updateTrack } from '@/spec/soundtrack'
+
+interface Props {
+  spec: VideoSpec
+  gamAssets: Record<string, GamAsset | null>
+  onChange: (next: VideoSpec) => void
+}
+
+/** An anchor as one select value: `start:s_market`, `end:s_market`, or the two ends. */
+function anchorValue(anchor: Anchor | undefined): string {
+  if (anchor === undefined) return ''
+  if (typeof anchor === 'string') return anchor
+  return `${anchor.edge}:${anchor.segment ?? ''}`
+}
+
+function anchorFrom(value: string, offset?: number): Anchor | undefined {
+  if (value === '') return undefined
+  if (value === 'video_start' || value === 'video_end') return value
+  const [edge, segment] = value.split(':')
+  return {
+    segment,
+    edge: edge as 'start' | 'end',
+    ...(offset ? { offset } : {}),
+  }
+}
+
+function offsetOf(anchor: Anchor | undefined): number {
+  return anchor && typeof anchor !== 'string' ? (anchor.offset ?? 0) : 0
+}
+
+/**
+ * The video's audio: any number of tracks, each running between two scenes.
+ *
+ * Changing the soundtrack partway through is a second track starting where the first
+ * ends; "crossfade from the track above" overlaps them with matching fades. Tracks
+ * are anchored to scenes, so moving or rewriting a scene keeps them where they belong.
+ */
+export default function SoundtrackPanel({ spec, gamAssets, onChange }: Props) {
+  const [adding, setAdding] = useState(false)
+  const tracks = spec.audio_tracks ?? []
+  const segments = spec.segments
+  const labels = (id: string) => {
+    const index = segments.findIndex((s) => s.id === id)
+    return segments[index]?.label || `Scene ${index + 1}`
+  }
+  const nameOf = (track: AudioTrack) => {
+    const ref = spec.assets?.[track.asset]
+    const id = ref?.from === 'gam' ? ref.id : undefined
+    return (id && gamAssets[id]?.name) || ref?.label || track.asset
+  }
+  const set = (index: number, patch: Partial<AudioTrack>) =>
+    onChange(updateTrack(spec, index, patch))
+
+  const anchorSelect = (
+    label: string,
+    value: Anchor | undefined,
+    onPick: (next: Anchor | undefined) => void,
+    allowNone: boolean
+  ) => (
+    <label className="flex items-center gap-1">
+      {label}
+      <select
+        className="input w-auto py-0.5"
+        aria-label={label}
+        value={anchorValue(value)}
+        onChange={(e) => onPick(anchorFrom(e.target.value, offsetOf(value)))}
+      >
+        {allowNone && <option value="">its own end</option>}
+        <option value="video_start">start of the video</option>
+        {segments.map((s) => (
+          <option key={`s-${s.id}`} value={`start:${s.id}`}>
+            start of {labels(s.id)}
+          </option>
+        ))}
+        {segments.map((s) => (
+          <option key={`e-${s.id}`} value={`end:${s.id}`}>
+            end of {labels(s.id)}
+          </option>
+        ))}
+        <option value="video_end">end of the video</option>
+      </select>
+      {value !== undefined && typeof value !== 'string' && (
+        <input
+          type="number"
+          step="0.5"
+          aria-label={`${label} offset in seconds`}
+          title="Seconds before (negative) or after the scene's edge"
+          className="input w-16 py-0.5"
+          value={value.offset ?? 0}
+          onChange={(e) =>
+            onPick({ ...value, offset: Number(e.target.value) || undefined })
+          }
+        />
+      )}
+    </label>
+  )
+
+  return (
+    <div className="space-y-3">
+      {tracks.length === 0 && (
+        <p className="text-sm text-gray-500 dark:text-gray-400">
+          No music or sound yet. Add a track from the asset library and choose the scenes
+          it plays between.
+        </p>
+      )}
+      {tracks.map((track, index) => {
+        const music = (track.kind ?? 'music') === 'music'
+        return (
+          <section
+            key={track.id}
+            aria-label={nameOf(track)}
+            className="card space-y-2 p-3 text-xs text-gray-700 dark:text-gray-300"
+          >
+            <div className="flex items-center gap-2">
+              <Music className="h-4 w-4 text-gray-400" />
+              <span className="min-w-0 flex-1 truncate text-sm font-medium text-gray-900 dark:text-gray-100">
+                {nameOf(track)}
+              </span>
+              <select
+                className="input w-auto shrink-0 py-0.5"
+                aria-label="Kind of track"
+                value={track.kind ?? 'music'}
+                onChange={(e) =>
+                  set(index, { kind: e.target.value as AudioTrack['kind'] })
+                }
+              >
+                <option value="music">Music</option>
+                <option value="sfx">Sound effect</option>
+                <option value="voiceover">Voice</option>
+              </select>
+              <button
+                type="button"
+                className="btn btn-ghost p-1"
+                aria-label="Remove track"
+                onClick={() => onChange(removeTrack(spec, index))}
+              >
+                <Trash2 className="h-4 w-4" />
+              </button>
+            </div>
+            <div className="flex flex-wrap items-center gap-3">
+              {anchorSelect(
+                'From',
+                track.start,
+                (a) => a && set(index, { start: a }),
+                false
+              )}
+              {anchorSelect('Until', track.end, (a) => set(index, { end: a }), true)}
+            </div>
+            <div className="flex flex-wrap items-center gap-3">
+              <label className="flex items-center gap-1">
+                Volume
+                <input
+                  type="range"
+                  min="0"
+                  max="1"
+                  step="0.01"
+                  aria-label="Volume"
+                  value={track.volume ?? 0.18}
+                  onChange={(e) => set(index, { volume: Number(e.target.value) })}
+                />
+                <span className="w-8">{Math.round((track.volume ?? 0.18) * 100)}%</span>
+              </label>
+              <label className="flex items-center gap-1">
+                Fade in
+                <input
+                  type="number"
+                  min="0"
+                  max="15"
+                  step="0.5"
+                  aria-label="Fade in seconds"
+                  className="input w-14 py-0.5"
+                  value={track.fade_in ?? 0}
+                  onChange={(e) => set(index, { fade_in: Number(e.target.value) })}
+                />
+              </label>
+              <label className="flex items-center gap-1">
+                Fade out
+                <input
+                  type="number"
+                  min="0"
+                  max="15"
+                  step="0.5"
+                  aria-label="Fade out seconds"
+                  className="input w-14 py-0.5"
+                  value={track.fade_out ?? 0}
+                  onChange={(e) => set(index, { fade_out: Number(e.target.value) })}
+                />
+              </label>
+              <label className="flex items-center gap-1">
+                <input
+                  type="checkbox"
+                  checked={track.duck_under_narration ?? music}
+                  onChange={(e) => set(index, { duck_under_narration: e.target.checked })}
+                />
+                Quieter under narration
+              </label>
+              <label className="flex items-center gap-1">
+                <input
+                  type="checkbox"
+                  checked={track.loop ?? music}
+                  onChange={(e) => set(index, { loop: e.target.checked })}
+                />
+                Loop to fill
+              </label>
+            </div>
+            {index > 0 && typeof track.start !== 'string' && (
+              <button
+                type="button"
+                className="btn btn-ghost text-xs"
+                onClick={() => onChange(crossfadeInto(spec, index, 3))}
+              >
+                Crossfade from the track above (3 s)
+              </button>
+            )}
+          </section>
+        )
+      })}
+      <button
+        type="button"
+        className="btn btn-secondary w-full"
+        disabled={segments.length === 0}
+        onClick={() => setAdding(true)}
+      >
+        <Plus className="mr-1 inline h-4 w-4" />
+        Add music or sound
+      </button>
+      {adding && (
+        <FootageSearch
+          title="Music or sound"
+          purpose="track"
+          initialType="audio"
+          onClose={() => setAdding(false)}
+          onPick={(hit) => {
+            onChange(
+              addTrack(
+                spec,
+                hit.asset,
+                'music',
+                segments[0].id,
+                segments[segments.length - 1].id
+              )
+            )
+            setAdding(false)
+          }}
+        />
+      )}
+    </div>
+  )
+}
diff --git a/frontend/src/spec/scene.ts b/frontend/src/spec/scene.ts
new file mode 100644
index 0000000..a893922
--- /dev/null
+++ b/frontend/src/spec/scene.ts
@@ -0,0 +1,81 @@
+import type { Frame, Motion, VideoSpec } from '@/api/projects'
+import { updateSegment } from '@/spec/edits'
+
+/**
+ * A scene's transition and Ken Burns move, set from the scene card.
+ *
+ * `undefined` means "the project's default", which removes the field rather than
+ * writing the default in: the spec's rule is that a scene overrides only what it says.
+ */
+
+export const TRANSITIONS = [
+  { value: 'none', label: 'Cut' },
+  { value: 'fade', label: 'Fade through black' },
+  { value: 'fadewhite', label: 'Fade through white' },
+  { value: 'dissolve', label: 'Dissolve' },
+  { value: 'slideleft', label: 'Slide left' },
+  { value: 'slideright', label: 'Slide right' },
+  { value: 'wipeleft', label: 'Wipe left' },
+  { value: 'wiperight', label: 'Wipe right' },
+  { value: 'circleopen', label: 'Circle open' },
+  { value: 'smoothleft', label: 'Smooth left' },
+] as const
+
+export const MOTIONS = [
+  { value: 'none', label: 'Still' },
+  { value: 'zoom_in', label: 'Zoom in' },
+  { value: 'zoom_out', label: 'Zoom out' },
+  { value: 'pan_left', label: 'Pan left' },
+  { value: 'pan_right', label: 'Pan right' },
+  { value: 'pan_up', label: 'Pan up' },
+  { value: 'pan_down', label: 'Pan down' },
+  { value: 'path', label: 'Move between two frames' },
+] as const
+
+export function setTransition(
+  spec: VideoSpec,
+  index: number,
+  transition: { style?: string; duration?: number } | undefined
+): VideoSpec {
+  return updateSegment(spec, index, (segment) => {
+    const next = { ...segment }
+    if (transition === undefined) delete next.transition_in
+    else next.transition_in = transition
+    return next
+  })
+}
+
+/** The whole picture to its middle third: a sensible first path to adjust. */
+export const DEFAULT_PATH: { from: Frame; to: Frame } = {
+  from: { x: 0, y: 0, w: 1 },
+  to: { x: 0.3, y: 0.3, w: 0.4 },
+}
+
+export function setMotion(
+  spec: VideoSpec,
+  index: number,
+  motion: Motion | undefined
+): VideoSpec {
+  return updateSegment(spec, index, (segment) => {
+    if (!segment.visual) return segment
+    const visual = { ...segment.visual }
+    if (motion === undefined) delete visual.motion
+    else visual.motion = motion
+    return { ...segment, visual }
+  })
+}
+
+/**
+ * Keep a frame inside the picture: its width within (0, 1], its left and top edges
+ * such that the frame (whose height comes from the output's shape) still fits.
+ */
+export function clampFrame(frame: Frame, frameHeightPerWidth: number): Frame {
+  const w = Math.min(1, Math.max(0.05, frame.w))
+  const h = Math.min(1, w * frameHeightPerWidth)
+  const round = (n: number) => Math.round(n * 1000) / 1000
+  return {
+    w: round(w),
+    x: round(Math.min(Math.max(0, frame.x), 1 - w)),
+    y: round(Math.min(Math.max(0, frame.y), Math.max(0, 1 - h))),
+  }
+}
diff --git a/frontend/src/spec/soundtrack.test.ts b/frontend/src/spec/soundtrack.test.ts
new file mode 100644
index 0000000..5026ca6
--- /dev/null
+++ b/frontend/src/spec/soundtrack.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+import type { GamAsset } from '@/api/gam'
+import type { VideoSpec } from '@/api/projects'
+import { clampFrame, setMotion, setTransition } from '@/spec/scene'
+import {
+  addTrack,
+  crossfadeInto,
+  describeAnchor,
+  removeTrack,
+  updateTrack,
+} from '@/spec/soundtrack'
+
+const song = (id: string, name: string): GamAsset => ({
+  id,
+  name,
+  asset_type: 'audio',
+  duration_seconds: 180,
+  width: null,
+  height: null,
+  file_url: null,
+  thumb_url: null,
+  credit: '',
+  parent_asset_id: null,
+  in_point: null,
+  out_point: null,
+  missing: false,
+})
+
+function spec(): VideoSpec {
+  return {
+    title: 'T',
+    assets: { a_map: { from: 'gam', id: 'p' } },
+    segments: [
+      { id: 's1', kind: 'scene', visual: { asset: 'a_map' } },
+      { id: 's2', kind: 'scene' },
+      { id: 's3', kind: 'scene' },
+    ],
+  }
+}
+
+describe('soundtrack', () => {
+  it('adds a music track between two scenes, with a readable key and gentle defaults', () => {
+    const next = addTrack(spec(), song('g1', 'Desert Theme.mp3'), 'music', 's1', 's2')
+    expect(next.assets?.a_desert_theme).toEqual({
+      from: 'gam',
+      id: 'g1',
+      type: 'audio',
+      label: 'Desert Theme.mp3',
+    })
+    expect(next.audio_tracks).toEqual([
+      {
+        id: 'm_1',
+        kind: 'music',
+        asset: 'a_desert_theme',
+        start: { segment: 's1', edge: 'start' },
+        end: { segment: 's2', edge: 'end' },
+        volume: 0.18,
+        fade_in: 1.5,
+        fade_out: 3,
+      },
+    ])
+  })
+
+  it('changes the soundtrack partway: a second track, crossfaded from the first', () => {
+    let next = addTrack(spec(), song('g1', 'Theme'), 'music', 's1', 's3')
+    next = addTrack(next, song('g2', 'Close'), 'music', 's3')
+    next = crossfadeInto(next, 1, 3)
+    const [first, second] = next.audio_tracks!
+    // The first now stops where the third scene starts, fading over the last 3 s ...
+    expect(first.end).toEqual({ segment: 's3', edge: 'start' })
+    expect(first.fade_out).toBe(3)
+    // ... and the second starts 3 s before it, fading in over those same 3 s.
+    expect(second.start).toEqual({ segment: 's3', edge: 'start', offset: -3 })
+    expect(second.fade_in).toBe(3)
+    // No end: it plays to its own end.
+    expect(second.end).toBeUndefined()
+  })
+
+  it('edits and removes a track, an undefined field meaning "not set"', () => {
+    let next = addTrack(spec(), song('g1', 'Theme'), 'music', 's1', 's2')
+    next = updateTrack(next, 0, { volume: 0.4, end: undefined })
+    expect(next.audio_tracks![0].volume).toBe(0.4)
+    expect('end' in next.audio_tracks![0]).toBe(false)
+    expect(removeTrack(next, 0).audio_tracks).toEqual([])
+  })
+
+  it('describes an anchor in words', () => {
+    const labels = { s3: 'The market' }
+    expect(describeAnchor({ segment: 's3', edge: 'start', offset: -3 }, labels)).toBe(
+      'start of The market −3 s'
+    )
+    expect(describeAnchor(undefined, labels)).toBe('its own end')
+    expect(describeAnchor('video_end', labels)).toBe('the end of the video')
+  })
+})
+
+describe('scene settings', () => {
+  it('overrides the transition into a scene, and "project default" removes it', () => {
+    const dissolved = setTransition(spec(), 1, { style: 'dissolve' })
+    expect(dissolved.segments[1].transition_in).toEqual({ style: 'dissolve' })
+    expect('transition_in' in setTransition(dissolved, 1, undefined).segments[1]).toBe(
+      false
+    )
+  })
+
+  it('sets a Ken Burns path on a scene with a picture, and only there', () => {
+    const path = {
+      effect: 'path',
+      from: { x: 0, y: 0, w: 1 },
+      to: { x: 0.5, y: 0.4, w: 0.4 },
+    }
+    expect(setMotion(spec(), 0, path).segments[0].visual?.motion).toEqual(path)
+    expect(setMotion(spec(), 1, path).segments[1].visual).toBeUndefined()
+  })
+
+  it('keeps a frame inside the picture', () => {
+    // A 16:9 frame on a 16:9 picture is as tall as it is a fraction of the width.
+    expect(clampFrame({ x: 0.8, y: 0.9, w: 0.5 }, 1)).toEqual({ x: 0.5, y: 0.5, w: 0.5 })
+    expect(clampFrame({ x: -1, y: 0, w: 3 }, 1)).toEqual({ x: 0, y: 0, w: 1 })
+  })
+})
diff --git a/frontend/src/spec/soundtrack.ts b/frontend/src/spec/soundtrack.ts
new file mode 100644
index 0000000..79f7b1d
--- /dev/null
+++ b/frontend/src/spec/soundtrack.ts
@@ -0,0 +1,118 @@
+import type { GamAsset } from '@/api/gam'
+import type { Anchor, AudioTrack, VideoSpec } from '@/api/projects'
+import { assetKeyFor } from '@/spec/footage'
+
+/**
+ * Audio tracks: music, sound effects, extra voice, each placed against the scenes.
+ *
+ * A soundtrack that changes through the video is several tracks, and a crossfade is
+ * two that overlap with matching fades. Tracks anchor to scenes, never to seconds, so
+ * inserting or rewording a scene never leaves a track ending in the wrong place.
+ */
+
+function nextTrackId(spec: VideoSpec, prefix: string): string {
+  const taken = new Set((spec.audio_tracks ?? []).map((t) => t.id))
+  let n = (spec.audio_tracks ?? []).length + 1
+  while (taken.has(`${prefix}_${n}`)) n += 1
+  return `${prefix}_${n}`
+}
+
+export function addTrack(
+  spec: VideoSpec,
+  asset: GamAsset,
+  kind: 'music' | 'sfx' | 'voiceover',
+  from: string,
+  to?: string
+): VideoSpec {
+  const key = assetKeyFor(spec, asset)
+  const assets = spec.assets?.[key]
+    ? spec.assets
+    : {
+        ...(spec.assets ?? {}),
+        [key]: {
+          from: 'gam' as const,
+          id: asset.id,
+          type: asset.asset_type,
+          label: asset.name,
+        },
+      }
+  const track: AudioTrack = {
+    id: nextTrackId(spec, kind === 'music' ? 'm' : kind === 'sfx' ? 'x' : 'v'),
+    kind,
+    asset: key,
+    start: { segment: from, edge: 'start' },
+    ...(to ? { end: { segment: to, edge: 'end' } as Anchor } : {}),
+    volume: kind === 'music' ? 0.18 : 0.6,
+    fade_in: kind === 'music' ? 1.5 : 0,
+    fade_out: kind === 'music' ? 3 : 0,
+  }
+  return { ...spec, assets, audio_tracks: [...(spec.audio_tracks ?? []), track] }
+}
+
+export function updateTrack(
+  spec: VideoSpec,
+  index: number,
+  patch: Partial<AudioTrack>
+): VideoSpec {
+  return {
+    ...spec,
+    audio_tracks: (spec.audio_tracks ?? []).map((t, i) => {
+      if (i !== index) return t
+      const next = { ...t, ...patch }
+      for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined) delete next[k as keyof AudioTrack]
+      }
+      return next
+    }),
+  }
+}
+
+export function removeTrack(spec: VideoSpec, index: number): VideoSpec {
+  return {
+    ...spec,
+    audio_tracks: (spec.audio_tracks ?? []).filter((_, i) => i !== index),
+  }
+}
+
+/**
+ * Crossfade from the track before this one into this one, over `seconds`.
+ *
+ * This track starts `seconds` before its scene does and fades in over them; the one
+ * before ends exactly where this one's scene starts and fades out over the same
+ * span, so the two overlap by exactly the crossfade, wherever that scene moves to.
+ */
+export function crossfadeInto(
+  spec: VideoSpec,
+  index: number,
+  seconds: number
+): VideoSpec {
+  const tracks = spec.audio_tracks ?? []
+  const track = tracks[index]
+  const previous = tracks[index - 1]
+  if (!track || !previous || typeof track.start === 'string') return spec
+  const scene = track.start.segment
+  let next = updateTrack(spec, index, {
+    start: { segment: scene, edge: 'start', offset: -seconds },
+    fade_in: seconds,
+  })
+  next = updateTrack(next, index - 1, {
+    end: { segment: scene, edge: 'start' },
+    fade_out: seconds,
+  })
+  return next
+}
+
+/** "Scene 3 start" for an anchor, given the scenes' labels. */
+export function describeAnchor(
+  anchor: Anchor | undefined,
+  labels: Record<string, string>
+): string {
+  if (anchor === undefined) return 'its own end'
+  if (anchor === 'video_start') return 'the start of the video'
+  if (anchor === 'video_end') return 'the end of the video'
+  const name = anchor.segment ? (labels[anchor.segment] ?? anchor.segment) : 'this scene'
+  const offset = anchor.offset
+    ? ` ${anchor.offset > 0 ? '+' : '−'}${Math.abs(anchor.offset)} s`
+    : ''
+  return `${anchor.edge === 'start' ? 'start' : 'end'} of ${name}${offset}`
+}
diff --git a/frontend/src/stores/auth.ts b/frontend/src/stores/auth.ts
index 6890e19..b28ad6d 100644
--- a/frontend/src/stores/auth.ts
+++ b/frontend/src/stores/auth.ts
@@ -2,6 +2,7 @@ import { create } from 'zustand'
 import { authApi, redirectToLogin, type User } from '@/api/auth'
 import { apiErrorCode, apiErrorMessage, clearToken } from '@/api/client'
 import { useProjectStore } from '@/stores/projects'
+import { useRenderStore } from '@/stores/renders'
 
 /**
  * Who is signed in.
@@ -67,6 +68,8 @@ export const useAuthStore = create<AuthState>((set, get) => ({
     // Fan out to every store holding user data, so signing out cannot leave one
     // person's projects on screen for the next.
     useProjectStore.getState().reset()
+    // Also stops the poll, which would otherwise keep asking as the old user.
+    useRenderStore.getState().reset()
     void redirectToLogin()
   },
 
diff --git a/frontend/src/stores/renders.ts b/frontend/src/stores/renders.ts
new file mode 100644
index 0000000..82e81f6
--- /dev/null
+++ b/frontend/src/stores/renders.ts
@@ -0,0 +1,139 @@
+import { create } from 'zustand'
+import { apiErrorMessage } from '@/api/client'
+import { ACTIVE, rendersApi, type Estimate, type Render } from '@/api/renders'
+
+/**
+ * The renders of the project open in the editor, and the one in progress.
+ *
+ * A running render is polled every couple of seconds until it finishes. The poll is
+ * one timer, re-armed only after the previous answer arrives, and every answer is
+ * checked against a token so a project closed mid-render cannot have its render's
+ * progress land on the next one.
+ */
+
+const POLL_MS = 2000
+
+interface RenderState {
+  projectId: string | null
+  renders: Render[]
+  estimate: Estimate | null
+  starting: boolean
+  error: string | null
+
+  load: (projectId: string) => Promise<void>
+  refreshEstimate: () => Promise<void>
+  start: (preview: boolean) => Promise<void>
+  cancel: (id: string) => Promise<void>
+  remove: (id: string) => Promise<void>
+  reset: () => void
+}
+
+let token = 0
+let timer: ReturnType<typeof setTimeout> | null = null
+
+function stopPolling() {
+  if (timer) clearTimeout(timer)
+  timer = null
+}
+
+export const useRenderStore = create<RenderState>((set, get) => {
+  const replace = (render: Render) =>
+    set({ renders: get().renders.map((r) => (r.id === render.id ? render : r)) })
+
+  function poll(mine: number) {
+    stopPolling()
+    const active = get().renders.find((r) => ACTIVE.includes(r.status))
+    if (!active) return
+    timer = setTimeout(async () => {
+      try {
+        const fresh = await rendersApi.get(active.id)
+        if (mine !== token) return
+        replace(fresh)
+      } catch (error) {
+        if (mine !== token) return
+        set({ error: apiErrorMessage(error) })
+      }
+      poll(mine)
+    }, POLL_MS)
+  }
+
+  return {
+    projectId: null,
+    renders: [],
+    estimate: null,
+    starting: false,
+    error: null,
+
+    async load(projectId) {
+      const mine = ++token
+      stopPolling()
+      set({ projectId, renders: [], estimate: null, error: null })
+      try {
+        const [renders, estimate] = await Promise.all([
+          rendersApi.list(projectId),
+          rendersApi.estimate(projectId),
+        ])
+        if (mine !== token) return
+        set({ renders, estimate })
+        poll(mine)
+      } catch (error) {
+        if (mine !== token) return
+        set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async refreshEstimate() {
+      const projectId = get().projectId
+      if (!projectId) return
+      const mine = token
+      try {
+        const estimate = await rendersApi.estimate(projectId)
+        if (mine === token) set({ estimate })
+      } catch {
+        /* the next load says what is wrong */
+      }
+    },
+
+    async start(preview) {
+      const projectId = get().projectId
+      if (!projectId) return
+      const mine = token
+      set({ starting: true, error: null })
+      try {
+        const render = await rendersApi.start(projectId, preview)
+        if (mine !== token) return
+        set({ renders: [render, ...get().renders], starting: false })
+        poll(mine)
+      } catch (error) {
+        if (mine !== token) return
+        set({ starting: false, error: apiErrorMessage(error) })
+      }
+    },
+
+    async cancel(id) {
+      const mine = token
+      try {
+        const render = await rendersApi.cancel(id)
+        if (mine === token) replace(render)
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    async remove(id) {
+      const mine = token
+      try {
+        await rendersApi.remove(id)
+        if (mine === token) set({ renders: get().renders.filter((r) => r.id !== id) })
+      } catch (error) {
+        if (mine === token) set({ error: apiErrorMessage(error) })
+      }
+    },
+
+    reset() {
+      token += 1
+      stopPolling()
+      set({ projectId: null, renders: [], estimate: null, starting: false, error: null })
+    },
+  }
+})
diff --git a/frontend/src/views/ProjectView.tsx b/frontend/src/views/ProjectView.tsx
index 14526e7..0800cd9 100644
--- a/frontend/src/views/ProjectView.tsx
+++ b/frontend/src/views/ProjectView.tsx
@@ -4,19 +4,23 @@ import { Link, useParams } from 'react-router-dom'
 import type { NoteMediaCopy } from '@/api/projects'
 import FootageSearch from '@/components/FootageSearch'
 import HistoryPanel from '@/components/HistoryPanel'
+import RenderPanel from '@/components/RenderPanel'
+import SoundtrackPanel from '@/components/SoundtrackPanel'
 import IssueList from '@/components/IssueList'
 import JsonPanel from '@/components/JsonPanel'
 import SceneList from '@/components/SceneList'
 import { gamIdsIn, placeHit, resolveSearch, unresolvedSearches } from '@/spec/footage'
 import { useProjectStore } from '@/stores/projects'
 
-type Tab = 'scenes' | 'json' | 'history'
+type Tab = 'scenes' | 'soundtrack' | 'render' | 'json' | 'history'
 
 /** What the footage search is open for: one scene, or a placeholder to resolve. */
 type Finding = { kind: 'scene'; index: number } | { kind: 'resolve'; key: string }
 
 const TABS: { id: Tab; label: string }[] = [
   { id: 'scenes', label: 'Scenes' },
+  { id: 'soundtrack', label: 'Soundtrack' },
+  { id: 'render', label: 'Render' },
   { id: 'json', label: 'JSON' },
   { id: 'history', label: 'History' },
 ]
@@ -254,6 +258,12 @@ export default function ProjectView() {
       {tab === 'json' && (
         <JsonPanel key={JSON.stringify(draft)} spec={draft} onApply={edit} />
       )}
+      {tab === 'soundtrack' && (
+        <SoundtrackPanel spec={draft} gamAssets={gamAssets} onChange={edit} />
+      )}
+      {tab === 'render' && (
+        <RenderPanel projectId={project.id} dirty={dirty} version={project.version} />
+      )}
       {tab === 'history' && <HistoryPanel />}
     </div>
   )
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index b3b746e..d2f3f54 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -26,6 +26,7 @@ export default defineConfig({
       // a sibling's port does not fail cleanly: that backend shares JWT_SECRET_KEY, so
       // it verifies the token and answers with another app's data.
       '/api': { target: 'http://localhost:8002', changeOrigin: true, ws: true },
+      '/media': { target: 'http://localhost:8002', changeOrigin: true },
     },
   },
   test: {