#!/usr/bin/env python3
"""Join clips with transitions, normalising resolution, frame rate and audio
layout so mismatched sources (phone + camera + screen recording) cut together.

Transitions (xfade): fade, dissolve, wipeleft, wiperight, wipeup, wipedown,
slideleft, slideright, circleopen, fadeblack, fadewhite, smoothleft, none.

Audio-only inputs (WAV, FLAC, MP3, M4A, ...) are joined as audio: every clip is
resampled to one rate and channel layout (the first clip's rate, the widest
layout; --sample-rate / --channels override), crossfaded with acrossfade or
butted with concat, and written in the codec the output extension names. The
output of an audio join must be an audio extension; mixing audio and video
inputs is refused.

Examples:
  python3 join.py a.mp4 b.mp4 c.mp4 -o final.mp4                      # 0.5 s crossfade, size/fps from the first clip
  python3 join.py *.mp4 --transition fadeblack --duration 1 -o reel.mp4
  python3 join.py a.mov b.mp4 --transition none --width 1920 --height 1080 --fps 30
  python3 join.py intro.wav talk.m4a outro.wav -o episode.flac            # audio join, 0.5 s crossfade
  python3 join.py part1.wav part2.wav --transition none -o full.wav       # butt join, sample rate of part1
  python3 join.py --list parts.txt --transition none -o voice.wav          # the segments a TTS step wrote, in order
  python3 join.py --list parts.txt --on-missing skip -o voice.wav          # join what is there, report the rest

Every input is checked before anything is joined: a missing, empty or unreadable segment is
refused with every problem named at once (kind input), never discovered one run at a time.
--on-missing skip joins the usable segments instead and lists the others under `skipped`.
Under --dry-run a segment that does not exist yet is an earlier step's output: it is planned
on and named under `pending` (never `skipped`), whichever --on-missing was given, and its
extension stands in for what it will hold (an audio extension: no picture).

Every input with an audio stream is also measured (one volumedetect pass): a segment whose peak
is at or below --silence-threshold (default -50 dBFS) is silent -- the trace of a TTS call that
wrote a valid but empty wav. --on-silent warn (default) joins it and names it under `silent`;
fail refuses it with the other input problems; skip drops it into `skipped`. A clip with no
audio stream is never silent.
"""
import argparse
import json
import math
import os
import tempfile
import sys
from fractions import Fraction
from typing import Any, Dict, List, Optional, Tuple

from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
from _common.runner import read_text_or_die
from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, refuse_output_is_input, place_output, refuse, sibling_temp, as_limited, draws_chroma, drawn_chain, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
from _common.emit import note, warn
from _common.decision import av_clip_length, av_trim, stream_starts
from _common.probe import display_size, square_pixels, square_pixels_note
from _common.timeline import exact_rate
from _common.emit import input_length

TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
               "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
LAYOUTS = {1: "mono", 2: "stereo", 6: "5.1", 8: "7.1"}
# inputs --on-missing skip dropped, reported in the success document (empty when nothing was)
STATE_SKIPPED: List[Dict[str, Any]] = []
# --dry-run: inputs that do not exist yet, planned on as an earlier step's output
STATE_PENDING: List[Dict[str, Any]] = []
STATE_NOTES: List[str] = []
# the joined picture's length against the clips' sum less the transitions: 1.5 frames, at least 0.05 s
DURATION_TOLERANCE_FRAMES = 1.5
DURATION_TOLERANCE_MIN = 0.05
# --on-silent warn: inputs whose audio peak is at or below --silence-threshold, joined anyway
STATE_SILENT: List[Dict[str, Any]] = []
# warnings, never refusals: a clip shorter than MIN_SEGMENT_FRAMES frames (audio-only: shorter than
# MIN_AUDIO_SEGMENT seconds) and a path listed more than once (repeating a clip can be intentional)
STATE_SHORT: List[Dict[str, Any]] = []
STATE_DUPES: List[Dict[str, Any]] = []
# original 0-based list position of each input still in args.inputs (after any skip)
STATE_KEPT: List[int] = []
MIN_SEGMENT_FRAMES = 2
MIN_AUDIO_SEGMENT = 0.05


def reported() -> Dict[str, Any]:
    """The input bookkeeping both success documents carry: `skipped` is what the join left out,
    `pending` what a dry run planned on without it existing; `notes` says the same in words."""
    extra: Dict[str, Any] = {"skipped": list(STATE_SKIPPED), "pending": list(STATE_PENDING), "silent": list(STATE_SILENT),
                             "short_segments": list(STATE_SHORT), "duplicates": list(STATE_DUPES)}
    if STATE_NOTES:
        extra["notes"] = list(STATE_NOTES)
    return extra


def unpending_length(durs: List[float], d: float) -> Optional[float]:
    """The joined length the clip durations add up to, or None while an input is pending: its
    dry-run stub says 0 s, which would count the clip as nothing and still subtract a transition
    for it (a negative length when nothing exists yet)."""
    if STATE_PENDING:
        return None
    return round(sum(durs) - d * (len(durs) - 1), 3)


def overlap_report(durs: List[float], expected: Optional[float]) -> Dict[str, Any]:
    """The clips' own total next to the joined length (2.20). The joined length is derived from
    the transition the join itself applied, so a check against it alone cannot show that a fade
    took time out of the material; the sum of the inputs is the yardstick the user holds."""
    if expected is None or STATE_PENDING:
        return {}
    total = round(sum(durs), 3)
    out: Dict[str, Any] = {"inputs_duration": total, "transition_shortening": round(total - expected, 3)}
    if out["transition_shortening"] > 0.0005:
        STATE_NOTES.append(f"the transitions overlap the clips: {fmt_secs(total)} of clips play as {fmt_secs(expected)} "
                           f"({out['transition_shortening']:.3f} s shorter)")
    return out


def clip_length(meta: Dict[str, Any], fps: float) -> float:
    """The one length a clip holds in a join, for its picture and its sound alike: the
    video stream's, or up to where the sound ends when it runs more than a frame past the picture
    (narration is never cut; an AAC tail adds no frame), counted from the first frame. The container
    duration (audio priming, a longer track) is only the fallback when a stream length is unknown
    (a pending input). Shared with reverse.py as av_clip_length."""
    return av_clip_length(meta, fps)


# the video join's sound rate (every clip is resampled to it before the trims)
JOIN_AUDIO_RATE = 48000


def output_rate(fps: float, first: Dict[str, Any], asked: bool) -> Fraction:
    """The join's frame rate as an exact fraction: the first clip's own r_frame_rate/avg_frame_rate
    when `fps` is that clip's (30000/1001, not 29.97), else the NTSC fraction or the plain one
    `fps` names (timeline.exact_rate). Every clip length, offset and sound length is counted in
    frames of this rate, so the graph's fps filter runs at the same fraction."""
    if not asked:
        for key in ("r_frame_rate", "avg_frame_rate"):
            try:
                q = Fraction(str(first.get(key) or ""))
            except (ValueError, ZeroDivisionError):
                continue
            # the declared rate also wins when the average was taken over a length that leaves out
            # the last frame's duration (#475: 5 frames in 0.1333 s read 37.5 fps, and the whole
            # join ran at 75/2)
            if 0 < q <= 240 and (abs(float(q) - fps) < 1e-3 or short_last_frame(first, q)):
                return q
    return exact_rate(fps)


def short_last_frame(video: Optional[Dict[str, Any]], q: Fraction) -> bool:
    """Whether a picture's duration is its frame count less one frame at rate `q`: a container
    that stores no duration for the last frame (MOV written with -fps_mode passthrough, seen on
    FFmpeg 7.1) reads 5 frames as 0.1333 s at 30 fps (#475)."""
    v = video or {}
    nb, dur = v.get("nb_frames"), v.get("duration")
    if not nb or nb < 2 or not dur or q <= 0:
        return False
    step = float(1 / q)
    return abs(dur - (nb - 1) * step) < 0.25 * step and abs(dur - nb * step) > 0.25 * step


def with_whole_picture(meta: Dict[str, Any], q: Fraction) -> Dict[str, Any]:
    """`meta` with its picture counted as every frame it holds when its duration leaves out the
    last one (short_last_frame), so the clip-length rule does not read the sound as running a
    frame past the picture and hold the clip longer (#475). Other clips are returned as they are."""
    v = meta.get("video") or {}
    # each clip at its OWN declared rate: at the join's rate a complete 30 fps clip of 5 frames
    # (5/30 s) also equals 4 frames at --fps 24 and would be stretched to 5/24 s
    try:
        own = Fraction(str(v.get("r_frame_rate") or ""))
    except (ValueError, ZeroDivisionError):
        own = q
    if not 0 < own <= 240:
        own = q
    if not short_last_frame(v, own):
        return meta
    return dict(meta, video=dict(v, duration=float(v["nb_frames"] / own)))


def clip_frames(meta: Dict[str, Any], length: float, q: Fraction) -> int:
    """How many frames of rate `q` a clip of `length` seconds (clip_length) holds in the join: its
    picture's frames, or, when the clip lasts as long as its sound, enough frames to cover that
    sound (narration is never cut; a hundredth of a frame is rounding, not sound). A pending
    dry-run stub's 0 s stays 0; a measured clip holds at least one frame (#455: a length in
    milliseconds rounded up started every next clip late, and the errors added up)."""
    exact = length * q.numerator / q.denominator
    vlen = (meta.get("video") or {}).get("duration") or 0.0
    frames = math.ceil(exact - 0.01) if vlen and length > vlen else round(exact)
    return frames if meta.get("dry_run") else max(1, frames)


def frame_time(frames: int, q: Fraction) -> str:
    """The time of frame `frames` at rate `q` in seconds, rounded down to the microsecond: never
    after that frame's own timestamp, so a filter that starts on the first frame at or after it
    (xfade's offset) starts on that frame and not the next (#468: 2.566667 written 2.567 started
    the transition a frame late). Trailing zeros are dropped (0.5, not 0.500000)."""
    us = (frames * q.denominator * 1_000_000) // q.numerator
    text = f"{us // 1_000_000}.{us % 1_000_000:06d}".rstrip("0").rstrip(".")
    return text or "0"


def find_duplicates(paths: List[str]) -> List[Dict[str, Any]]:
    """Every path (compared by its resolved absolute form) listed more than once, with the 0-based
    list positions it appears at. A warning, not a refusal: repeating a clip can be intentional."""
    seen: Dict[str, List[int]] = {}
    for i, p in enumerate(paths):
        seen.setdefault(os.path.realpath(p), []).append(i)
    return [{"path": paths[ix[0]], "indices": ix} for ix in seen.values() if len(ix) > 1]


def note_short_segments(paths: List[str], metas: List[dict], minimum: float, unit: str) -> None:
    """Record every measured input shorter than `minimum` seconds (a pending dry-run stub is not
    measured): such a clip joins as a flash nobody sees -- usually a failed earlier step."""
    for p, m, k in zip(paths, metas, STATE_KEPT or range(len(paths))):
        dur = m.get("duration") or 0.0
        if m.get("dry_run") or dur >= minimum:
            continue
        STATE_SHORT.append({"index": k, "path": p, "duration": round(dur, 4)})
    if STATE_SHORT:
        listing = ", ".join(f"#{s['index'] + 1} {s['path']} ({s['duration']:g}s)" for s in STATE_SHORT)
        warn(f"{len(STATE_SHORT)} input(s) shorter than {unit}: {listing}", "short_inputs", count=len(STATE_SHORT))
        STATE_NOTES.append(f"{len(STATE_SHORT)} input(s) are shorter than {unit} and were joined anyway: {listing}")


def expected_text(expected: Optional[float]) -> str:
    """unpending_length() as the stderr summary line puts it."""
    return f"expected ~{expected:.3f}s" if expected is not None else "expected length unknown until the pending inputs exist"


def join_audio(args: argparse.Namespace, metas: List[dict]) -> int:
    """Concatenate audio-only inputs: one sample rate, one channel layout, acrossfade or concat."""
    n = len(args.inputs)
    durs = [m.get("duration") or 0.0 for m in metas]
    d = args.duration if args.transition != "none" else 0.0
    place_silent(durs, d)
    note_short_segments(args.inputs, metas, MIN_AUDIO_SEGMENT, f"{MIN_AUDIO_SEGMENT:g}s")
    for p, dur in zip(args.inputs, durs):
        if d and dur <= d * 2 and not STATE.dry_run:
            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s crossfade; shorten --duration")
    # a pending input's probe is the dry-run stub (rate and layout unmeasured): plan from the
    # clips that exist, and fall back to 48 kHz stereo only when none does
    known = [m for m in metas if not m.get("dry_run")] or metas
    rates = [m["audio"].get("sample_rate") or 48000 for m in known]
    chans = [m["audio"].get("channels") or 2 for m in known]
    rate = args.sample_rate or rates[0]
    channels = args.channels or max(chans)
    layout = LAYOUTS.get(channels)
    if layout is None:
        die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
    if len(set(rates)) > 1:
        info(f"sample rates differ ({', '.join(str(r) for r in rates)} Hz); resampling every clip to {rate} Hz")
    if len(set(chans)) > 1:
        info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
    output = args.output or default_output(args.inputs[0], "joined")
    refuse_list_as_output(args, output)
    if not is_audio_output(output):
        die(f"audio-only inputs cannot fill a video container: give -o an audio extension (.wav, .flac, .mp3, .m4a, .ogg, .opus), not {output}")

    cmd = ffmpeg_base()
    for p in args.inputs:
        cmd += ["-i", p]
    parts = [f"[{i}:a:0]aformat=sample_rates={rate}:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]" for i in range(n)]
    if args.transition == "none":
        parts.append("".join(f"[a{i}]" for i in range(n)) + f"concat=n={n}:v=0:a=1[aout]")
    else:
        prev = "a0"
        for i in range(1, n):
            out = f"ax{i}" if i < n - 1 else "aout"
            parts.append(f"[{prev}][a{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{out}]")
            prev = out
    cmd += ["-filter_complex", ";".join(parts), "-map", "[aout]", "-vn"] + audio_codec_for(output) + [output]
    run(cmd)
    expected = unpending_length(durs, d)
    r = probe(output, role="output")
    a = r.get("audio") or {}
    if not STATE.dry_run:
        if r.get("video"):
            die(f"{output} unexpectedly contains a video stream")
        if a.get("sample_rate") != rate or a.get("channels") != channels:
            die(f"{output} is {a.get('sample_rate')} Hz {a.get('channels')} ch, expected {rate} Hz {channels} ch")
    info(f"wrote {output} ({fmt_secs(r['duration'])}, {expected_text(expected)}, audio {a.get('codec')} {channels}ch {rate}Hz, {n} clips, "
         + ("crossfade" if d else "butt join") + ")")
    overlap = overlap_report(durs, expected)
    emit(output, mode="audio", **overlap, **reported(), clips=n, transition=args.transition if d else "none", expected_duration=expected,
         sample_rate=rate, channels=channels, video=False, expect_streams={"audio": 1})
    return 0


# ffmpeg concat-demuxer directives other than `file`: they change what a `file` line plays
CONCAT_DIRECTIVES = frozenset({"inpoint", "outpoint", "duration", "stream", "exact_stream_id", "file_packet_metadata",
                               "file_packet_meta", "option", "stream_meta", "stream_codec", "stream_extradata", "chapter"})


def refuse_list_as_output(args: argparse.Namespace, output: str) -> None:
    """The --list file is read here and is never an -i of the join, so run()'s guard did not see
    an output named like it (#522's sweep): refused once the output is known, before any write."""
    if args.list:
        refuse_output_is_input(output, args.list, why="the clip list would be replaced by the join")


def read_list(path: str) -> List[str]:
    """--list FILE: one segment per line, in order, relative to the list file's own folder.
    Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
    (`file 'part 01.wav'`, the `ffconcat version` header) is accepted, so a list written for
    `ffmpeg -f concat` works as is unless it trims: `inpoint`, `outpoint`, `duration` and the other
    directives are refused by name, since nothing here applies them."""
    # the shared reader: a BOM, CRLF and a file that is not UTF-8 are read or refused as every
    # other text input is, and a line ends at "\n" only
    text = read_text_or_die(path, "--list")
    base = os.path.dirname(os.path.abspath(path))
    entries: List[str] = []
    for line in text.split("\n"):
        line = line.strip()
        if not line or line.startswith("#"):
            continue
        if line.startswith("file "):
            line = line[5:].strip()
            if len(line) >= 2 and line[0] == line[-1] and line[0] in "'\"":
                line = line[1:-1].replace("'\\''", "'")
        elif line.split()[0] == "ffconcat" and line.split()[1:2] == ["version"]:
            continue  # the concat demuxer's header line names no file
        elif line.split()[0] in CONCAT_DIRECTIVES and not os.path.exists(os.path.join(base, line)):
            # only `file` lines are read: a directive was taken for a path, reported as a missing
            # (or, under --dry-run, pending) input, and with --on-missing skip its trim was lost.
            # `stream` takes no argument (FFmpeg 6.1's concat demuxer); a line naming a file that is
            # there is a path, whatever its first word
            die(f"--list {path}: `{line}` is an ffmpeg concat directive, which join.py does not apply: the list is "
                "read for its `file` lines only", kind="input",
                hint="trim a clip with cut.py first and list the cut file (inpoint/outpoint/duration), "
                     "or remove the line")
        entries.append(line if os.path.isabs(line) else os.path.join(base, line))
    if not entries:
        # the failure this exists for: an upstream step produced nothing, and the join must
        # say so plainly rather than hand ffmpeg an empty concat and die somewhere later
        die(f"--list {path} names no segments (empty, or only blank lines and comments)",
            hint="check the step that writes the list: it produced no files")
    return entries


def preflight(paths: List[str], audible: Optional[List[int]] = None) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
    """Every problem with every input, found before anything runs: missing, empty (0 bytes,
    the usual trace of a TTS or download step that failed after creating its file), or not
    readable as media. One ffprobe per file; nothing is decoded. Under --dry-run a file that
    does not exist yet is not a problem but pending (the second list, with a note): in a
    planned pipeline it is an earlier step's output, and the plan keeps it. The index of every
    readable input with an audio stream is appended to `audible` (for find_silent())."""
    ffprobe = require_tool("ffprobe")
    problems: List[Dict[str, Any]] = []
    pending: List[Dict[str, Any]] = []
    for i, p in enumerate(paths):
        if dry_run_input_pending(p):
            pending.append({"index": i, "path": p})
            continue
        if not os.path.exists(p):
            problems.append({"index": i, "path": p, "reason": "missing"})
            continue
        if os.path.isdir(p):
            problems.append({"index": i, "path": p, "reason": "a directory, not a file"})
            continue
        if os.path.getsize(p) == 0:
            problems.append({"index": i, "path": p, "reason": "empty (0 bytes)"})
            continue
        proc = run([ffprobe, "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", p],
                   quiet=True, check=False)
        kinds = {line.strip() for line in (proc.stdout or "").splitlines() if line.strip()}
        if proc.returncode != 0 or not kinds & {"audio", "video"}:
            first = ((proc.stderr or "").strip().splitlines() or ["no audio or video stream"])[-1]
            problems.append({"index": i, "path": p, "reason": f"unreadable: {first}"})
        elif "audio" in kinds and audible is not None:
            audible.append(i)
    return problems, pending


def find_silent(paths: List[str], audible: List[int], threshold: float) -> List[Dict[str, Any]]:
    """The audible inputs whose whole-file peak (volumedetect max_volume) is at or below
    `threshold` dBFS: one decode of the audio per input. Not under --dry-run: join is a writing
    tool, and a dry run of it (or of render.py, which joins through it) runs no ffmpeg -- the plan
    notes that silence is measured on the real run. An input whose level cannot be measured is
    left to the join itself."""
    silent: List[Dict[str, Any]] = []
    if STATE.dry_run:
        if audible:
            STATE_NOTES.append("silence is not measured under --dry-run; a real run measures every input with audio "
                               "for --on-silent")
        return silent
    for i in audible:
        lv = measured_level_dbfs(paths[i], seconds=86400)
        if lv is not None and lv["peak_dbfs"] <= threshold:
            silent.append({"index": i, "path": paths[i], "peak_db": lv["peak_dbfs"]})
    return silent


def place_silent(lens: List[float], d: float) -> None:
    """Where each joined silent input sits in the output: `at`/`end` in output seconds. Input k
    (in kept order) starts after the kept inputs before it, each overlapped by the transition d."""
    for sil in STATE_SILENT:
        if sil["index"] not in STATE_KEPT:
            continue
        k = STATE_KEPT.index(sil["index"])
        if k >= len(lens):
            continue
        at = sum(lens[:k]) - k * d
        sil["at"], sil["end"] = round(at, 3), round(at + lens[k], 3)


def parse_allow_silent(value: Optional[str], n: int) -> List[int]:
    """--allow-silent 3,7 -> 0-based indices; each must name an input (1..n)."""
    if not value:
        return []
    out = []
    for tok in value.split(","):
        tok = tok.strip()
        if not tok.isdigit() or not 1 <= int(tok) <= n:
            die(f"--allow-silent takes input numbers 1..{n} separated by commas, got {tok!r}")
        out.append(int(tok) - 1)
    return out


# join.py --copy (2.24). The concat demuxer starts each clip where the previous one's container
# ends, so a stream that ends early leaves a gap at the join: a held frame for the picture, a hole
# for the sound. A clip whose picture and sound end further apart than this is refused.
COPY_AV_GAP = 0.05
COPY_PREROLL_PACKETS = 300   # packets read per clip to find an edit list's hidden pre-roll


def _copy_doc(path: str) -> "Optional[Dict[str, Any]]":
    """ffprobe's first video and first audio stream of `path`, with extradata hashes, as the doc
    stream_signature() reads; None when it cannot be read."""
    proc = run([require_tool("ffprobe"), "-v", "error", "-show_data_hash", "sha256", "-show_streams", "-show_format",
                "-of", "json", path], quiet=True, check=False)
    try:
        doc = json.loads(proc.stdout or "") if proc.returncode == 0 else None
    except ValueError:
        return None
    if not isinstance(doc, dict):
        return None
    # attached pictures (cover art) are not the picture being joined, as V:0 skips them
    every = doc.get("streams") or []
    streams = [st for st in every if not (st.get("disposition") or {}).get("attached_pic")]
    keep = [next((st for st in streams if st.get("codec_type") == kind), None) for kind in ("video", "audio")]
    doc["streams"] = [st for st in keep if st]
    # the concat demuxer maps every clip's packets by stream index, laid out as the first clip's
    doc["layout"] = {"streams": len(every), "indices": [st.get("index") for st in doc["streams"]]}
    return doc


def _video_packets(path: str, limit: "Optional[int]" = None) -> "List[str]":
    """The flags of the first video stream's packets (all of them, or the first `limit`); cover art
    is not that stream."""
    cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", "V:0", "-show_entries", "packet=flags", "-of", "csv=p=0"]
    if limit:
        cmd += ["-read_intervals", f"%+#{limit}"]
    proc = run(cmd + [path], quiet=True, check=False)
    return (proc.stdout or "").split() if proc.returncode == 0 else []


SPAN_HEAD_PACKETS = 64     # enough to see the earliest presentation time past B-frame reordering
SPAN_TAIL_SECONDS = 10.0   # read from this far before the end, so a seek that lands early still reaches it


def _stream_span(path: str, kind: str, duration: float = 0.0, start: float = 0.0) -> "Optional[Tuple[float, float]]":
    """First packet's time and last packet's time plus its duration for the first `kind` stream
    (V or a): measured, because Matroska/WebM state no stream length and MPEG-TS only an estimate.
    None when the packets cannot be read or one has no time: a partial span would invent a gap."""
    # JSON, not csv: older ffprobe builds (5.1) print side-data rows between the packet rows in csv.
    # A long clip is read at its head and its tail only: every packet of a two-hour file is
    # hundreds of thousands of entries for two numbers
    cmd = [require_tool("ffprobe"), "-v", "error", "-select_streams", f"{kind}:0", "-show_entries",
           "packet=pts_time,dts_time,duration_time", "-of", "json"]
    if duration > 3 * SPAN_TAIL_SECONDS:
        # read_intervals takes timestamps, so the tail starts from the file's own start time
        # (an MPEG-TS clock can start hours in; an edit list can start it below zero)
        cmd += ["-read_intervals", f"%+#{SPAN_HEAD_PACKETS},{start + duration - SPAN_TAIL_SECONDS:.3f}%"]
    proc = run(cmd + [path], quiet=True, check=False)
    try:
        packets = json.loads(proc.stdout or "{}").get("packets") or [] if proc.returncode == 0 else []
    except ValueError:
        return None
    times = []
    for pkt in packets:
        try:
            # a packet ffprobe gives no pts (some muxers leave it on B-frames) still has its dts
            t = float(pkt.get("pts_time", pkt.get("dts_time")))
        except (TypeError, ValueError):
            return None
        try:
            d = float(pkt.get("duration_time") or 0.0)
        except (TypeError, ValueError):
            d = 0.0
        times.append((t, t + d))
    if not times:
        return None
    return min(t for t, _ in times), max(e for _, e in times)


def join_copy(args, metas: List[Dict[str, Any]]) -> int:
    """--copy: the concat demuxer with -c copy, after checking that the clips can be joined that
    way, and measured afterwards (video packet count and length against the clips')."""
    if args.transition != "none":
        die("--copy joins without a transition: pass --transition none (a transition re-encodes the frames it blends)")
    if args.width or args.height or args.fps:
        die("--copy keeps every clip's own frame and rate: --width, --height and --fps need a re-encode, so drop --copy")
    if args.sample_rate or args.channels:
        die("--copy keeps every clip's own sound: --sample-rate and --channels need a re-encode, so drop --copy")
    encoder = [f for f, on in (("--codec", STATE.codec), ("--hw", STATE.hw and STATE.hw_source == "flag"),
                               ("--quality", getattr(args, "quality_given", False)))
               if on]
    if encoder:
        die(f"--copy keeps every clip's own encoding: {', '.join(encoder)} choose(s) an encode, so drop --copy")
    output = args.output or default_output(args.inputs[0], "joined", os.path.splitext(args.inputs[0])[1].lstrip(".") or "mp4")
    guard_sidecar(output, *args.inputs)
    refuse_list_as_output(args, output)
    ext = os.path.splitext(output)[1].lower()
    n = len(args.inputs)
    pending = any(m.get("dry_run") for m in metas)
    if pending:
        STATE_NOTES.append("--copy: an input does not exist yet, so whether the clips match is checked when a real run has them")
    else:
        docs = [_copy_doc(p) for p in args.inputs]
        unreadable = [p for p, d in zip(args.inputs, docs) if d is None]
        if unreadable:
            die(f"--copy: could not read the streams of {', '.join(unreadable)}")
        moved = [{"index": i, "path": p, "differs": {"stream_layout": [docs[0]["layout"], d["layout"]]}}
                 for i, (p, d) in enumerate(zip(args.inputs, docs)) if i and d["layout"] != docs[0]["layout"]]
        if moved:
            refuse("input", "join_copy_mismatch",
                   f"--copy: {', '.join(m['path'] for m in moved)} lay(s) out their streams differently from "
                   f"{args.inputs[0]} (count or order, cover art included); the concat demuxer maps streams by position",
                   hint="drop --copy to re-encode them to one layout", clips=moved)
        sigs = [stream_signature(d) for d in docs]
        mismatched = [{"index": i, "path": p, "differs": {k: [a.get(k), b.get(k)] for a, b in zip(sigs[0], sig)
                                                           for k in a if k != "extradata_hash" and a.get(k) != b.get(k)}
                       if len(sig) == len(sigs[0]) else {"streams": [len(sigs[0]), len(sig)]}}
                      for i, (p, sig) in enumerate(zip(args.inputs, sigs)) if i and not signatures_match([sigs[0], sig], ext)]
        if mismatched:
            listing = "; ".join(f"#{m['index'] + 1} {m['path']}: " + (", ".join(f"{k} {v[1]} (not {v[0]})" for k, v in m["differs"].items())
                                                                        or "codec configuration (extradata) differs")
                                for m in mismatched)
            refuse("input", "join_copy_mismatch", f"--copy: {len(mismatched)} clip(s) do not match the first one: {listing}",
                   hint="drop --copy to re-encode them to one format", clips=mismatched)
        hidden = [p for p in args.inputs if "D" in "".join(_video_packets(p, COPY_PREROLL_PACKETS))]
        if hidden:
            refuse("input", "join_copy_mismatch",
                   f"--copy: {', '.join(hidden)} hide(s) frames before their start (an edit list), which a copy join would show",
                   hint="drop --copy, or re-cut those clips with cut.py --accurate", clips=[{"path": p, "differs": {"edit_list": True}} for p in hidden])
        gaps = []
        for p, m in zip(args.inputs, metas):
            # each stream's span from its packets: Matroska/WebM state no stream length and an
            # MPEG-TS stream length is an estimate, so a stated duration missed or invented gaps
            if not (m.get("video") and m.get("audio")):
                continue
            length, origin = float(m.get("duration") or 0.0), float(m.get("start_time") or 0.0)
            v_span, a_span = _stream_span(p, "V", length, origin), _stream_span(p, "a", length, origin)
            if v_span is None or a_span is None:
                refuse("input", "join_copy_mismatch",
                       f"--copy: could not measure where picture and sound start and end in {p} (a packet without a "
                       "time), so a gap at the join could not be ruled out", hint="drop --copy to re-encode the join",
                       clips=[{"path": p, "differs": {"av_span": "unmeasured"}}])
            (vb, ve), (ab, ae) = v_span, a_span
            if abs(vb - ab) > COPY_AV_GAP or abs(ve - ae) > COPY_AV_GAP:
                gaps.append({"path": p, "video": [round(vb, 3), None if ve is None else round(ve, 3)],
                             "audio": [round(ab, 3), None if ae is None else round(ae, 3)]})
        if gaps:
            def span(x):
                return f"{x[0]:.3f}-" + ("?" if x[1] is None else f"{x[1]:.3f}") + "s"
            listing = "; ".join(f"{g['path']} (video {span(g['video'])}, audio {span(g['audio'])})" for g in gaps)
            refuse("input", "join_copy_mismatch",
                   f"--copy: picture and sound start or end more than {COPY_AV_GAP * 1000:.0f} ms apart in {listing}; a copy join "
                   "would leave that gap at the next clip", hint="drop --copy, which trims both streams to one length",
                   clips=[{"path": g["path"], "differs": {"video_span": g["video"], "audio_span": g["audio"]}} for g in gaps])
    fps = (metas[0].get("video") or {}).get("fps") or 30.0
    note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
    place_silent([m.get("duration") or 0.0 for m in metas], 0.0)
    with tempfile.TemporaryDirectory(prefix="ffskill_join_") as tmp:
        listfile = os.path.join(tmp, "list.txt")
        with open(listfile, "w", encoding="utf-8") as fh:
            for p in args.inputs:
                fh.write(concat_list_line(os.path.abspath(p)) + "\n")
        joined = sibling_temp(output, "join") if not STATE.dry_run else output
        cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-map", "0:V:0", "-map", "0:a:0?", "-c", "copy"]
        if ext in (".mp4", ".mov", ".m4v"):
            cmd += ["-movflags", "+faststart"]
        try:
            run(cmd + [joined])
            verification: List[Dict[str, Any]] = []
            if not STATE.dry_run:
                want = sum(len(_video_packets(p)) for p in args.inputs)
                got = len(_video_packets(joined))
                # nothing counted on either side is a failed read, not a match
                verification.append({"step": "join", "property": "video_packets", "ok": got == want and want > 0,
                                     "measured": got, "expected": want, "provenance": "input_premeasurement"})
                r = probe(joined, role="output")
                measured = (r.get("video") or {}).get("duration") or r.get("duration")
                expected = round(sum(m.get("duration") or 0.0 for m in metas), 3)
                tol = round(n * COPY_AV_GAP + 1.0 / fps, 3)
                verification.append({"step": "join", "property": "video_duration",
                                     "ok": measured is not None and abs(measured - expected) <= tol,
                                     "measured": None if measured is None else round(measured, 3), "expected": expected,
                                     "tolerance": tol, "provenance": "input_premeasurement"})
                bad = [v for v in verification if not v["ok"]]
                if bad:
                    die("--copy: the joined file does not hold the clips it was given: "
                        + "; ".join(f"{v['property']} {v['measured']} (expected {v['expected']})" for v in bad),
                        kind="verification", hint="drop --copy to re-encode the join", verification=verification)
                place_output(joined, output, move=True)
        finally:
            if joined != output and os.path.exists(joined):
                os.remove(joined)
    r = probe(output, role="output")
    info(f"wrote {output} ({fmt_secs(r.get('duration'))}, {n} clips, stream copy)")
    emit(output, mode="copy", **reported(), clips=n, transition="none", reencoded=False,
         verification=verification, expect_streams={"video": 1, "audio": 1 if all(m.get("audio") for m in metas) else 0},
         stream_reference=metas,
         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
    return 0


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("inputs", nargs="*", help="two or more clips in order (or --list FILE)")
    ap.add_argument("--list", metavar="FILE", help="read the clips from FILE, one per line in order (paths relative to FILE; "
                                                   "ffmpeg concat lines `file 'x.wav'` also accepted, other concat directives refused); an empty list is refused")
    ap.add_argument("--on-missing", choices=["fail", "skip"], default="fail",
                    help="a missing, empty or unreadable input: fail (default; every problem named at once) or skip "
                         "(join the rest; each skipped input is reported under `skipped`)")
    ap.add_argument("--on-silent", choices=["warn", "fail", "skip"], default="warn",
                    help="an input whose audio peak is at or below --silence-threshold: warn (default; join it, "
                         "name it under `silent`), fail (refuse with the other input problems) or skip (leave it out, "
                         "under `skipped`); a clip with no audio stream is never silent")
    ap.add_argument("--allow-silent", metavar="N[,N...]",
                    help="input numbers (1-based) whose silence is intended, e.g. a planned pause: always joined, "
                         "listed under `silent` with intended: true, no warning, whatever --on-silent says")
    ap.add_argument("--silence-threshold", type=float, default=SILENT_PEAK_DBFS, metavar="DB",
                    help="peak level in dBFS at or below which an input counts as silent (default -50)")
    ap.add_argument("-o", "--output", help="output file (default: <first>_joined.mp4)")
    ap.add_argument("--transition", choices=TRANSITIONS, default="fade", help="transition between clips (default fade)")
    ap.add_argument("--duration", type=float, default=0.5, help="transition length in seconds (default 0.5)")
    ap.add_argument("--width", type=int, help="output width (default: first clip)")
    ap.add_argument("--height", type=int, help="output height (default: first clip)")
    ap.add_argument("--fps", type=float, help="output frame rate (default: first clip)")
    ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how clips of another aspect reach the frame (default pad)")
    ap.add_argument("--copy", action="store_true",
                    help="join by stream copy, no re-encode (needs --transition none): every clip must carry the same "
                         "video and audio parameters (codec, size, rate, pixel format, sample rate, channels); a clip "
                         "that does not is refused, by name, with what differs")
    ap.add_argument("--pad-color", default="black")
    ap.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
    ap.add_argument("--preset", default="medium", choices=X264_PRESETS)
    aud = ap.add_argument_group("audio-only inputs")
    aud.add_argument("--sample-rate", type=int, help="output sample rate in Hz (default: first clip's)")
    aud.add_argument("--channels", type=int, choices=[1, 2, 6, 8], help="output channel count (default: the widest clip)")
    add_common(ap)
    args = ap.parse_args()
    # given at all, not only different from the default: --quality 18 asks for an encode as much as 23 does
    args.quality_given = any(a == "--quality" or a.startswith("--quality=") for a in sys.argv[1:])
    apply_common(args)
    if args.fps is not None and args.fps <= 0:
        die(f"--fps must be positive, got {args.fps:g}")
    # nan and inf are refused by the parser (finite_float); a negative length was taken as the
    # one-frame minimum and the join succeeded with a transition nobody asked for
    if args.duration < 0:
        die(f"--duration must be 0 or more seconds, got {args.duration:g}")

    if args.list:
        if args.inputs:
            die("give the clips either as arguments or with --list, not both")
        args.inputs = read_list(args.list)
    if not args.inputs:
        die("give at least two clips (or --list FILE)")
    if args.silence_threshold >= 0:
        die(f"--silence-threshold is a peak level in dBFS and must be negative, got {args.silence_threshold:g}")
    skipped: List[Dict[str, Any]] = []
    orig_inputs = list(args.inputs)
    audible: List[int] = []
    problems, pending = preflight(args.inputs, audible)
    allowed = parse_allow_silent(args.allow_silent, len(args.inputs))
    found = find_silent(args.inputs, audible, args.silence_threshold)
    intended = [dict(s, intended=True) for s in found if s["index"] in allowed]
    silent = [s for s in found if s["index"] not in allowed]
    silent_problems = [{"index": s["index"], "path": s["path"], "reason": f"silent (peak {s['peak_db']:.1f} dBFS)"}
                       for s in silent]
    refused = sorted((problems if args.on_missing == "fail" else [])
                     + (silent_problems if args.on_silent == "fail" else []), key=lambda p: p["index"])
    if refused:
        listing = "; ".join(f"#{p['index'] + 1} {p['path']}: {p['reason']}" for p in refused)
        ways = []
        if args.on_missing == "fail" and problems:
            ways.append("--on-missing skip")
        if args.on_silent == "fail" and silent:
            ways.append("--on-silent skip (or warn)")
        die(f"{len(refused)} of {len(args.inputs)} inputs cannot be joined: {listing}",
            hint="fix or regenerate them, or pass " + " and ".join(ways) + " to join the rest", problems=refused)
    dropped = sorted((problems if args.on_missing == "skip" else [])
                     + (silent_problems if args.on_silent == "skip" else []), key=lambda p: p["index"])
    if dropped:
        bad = {p["index"] for p in dropped}
        skipped = dropped
        args.inputs = [p for i, p in enumerate(args.inputs) if i not in bad]
        for p in dropped:
            info(f"skipping #{p['index'] + 1} {p['path']}: {p['reason']}")
    STATE_SILENT[:] = sorted(intended + (silent if args.on_silent == "warn" else []), key=lambda s: s["index"])
    if silent and args.on_silent == "warn":
        listing = ", ".join(f"#{s['index'] + 1} {s['path']} (peak {s['peak_db']:.1f} dBFS)" for s in silent)
        warn(f"{len(silent)} input(s) silent at or below {args.silence_threshold:g} dBFS, joined anyway: {listing}",
             "silent_inputs", count=len(silent))
        STATE_NOTES.append(f"{len(silent)} input(s) have no audible sound (peak at or below {args.silence_threshold:g} dBFS) "
                           f"and were joined anyway: {listing}; pass --on-silent fail or skip to refuse or drop them")
    STATE_SKIPPED[:] = skipped
    STATE_KEPT[:] = [i for i in range(len(args.inputs) + len(skipped)) if i not in {p["index"] for p in skipped}]
    dupes = [dd for dd in find_duplicates(orig_inputs)
             if len([i for i in dd["indices"] if i in STATE_KEPT]) > 1]
    for dd in dupes:
        dd["indices"] = [i for i in dd["indices"] if i in STATE_KEPT]
    STATE_DUPES[:] = dupes
    if dupes:
        listing = "; ".join(f"{dd['path']} at #" + ", #".join(str(i + 1) for i in dd["indices"]) for dd in dupes)
        warn(f"input(s) listed more than once: {listing}", "duplicate_inputs", count=len(dupes))
        STATE_NOTES.append(f"{len(dupes)} input(s) are listed more than once and joined each time: {listing}; "
                           "fine if the repeat is intended")
    STATE_PENDING[:] = pending
    if pending:
        # a dry run cannot know whether the file will be there: it plans on it, and says what a
        # real run does if it still is not (the same --on-missing rule as any missing input --
        # including the refusal when skipping would leave fewer than two inputs)
        left = len(args.inputs) - len(pending)
        if args.on_missing == "fail":
            then = "refuses the join if one is still missing"
        elif left >= 2:
            then = "skips one that is still missing"
        else:
            then = (f"skips one that is still missing and refuses the join if that leaves fewer than two inputs "
                    f"(only {left} exist{'s' if left == 1 else ''} now)")
        STATE_NOTES.append(f"{len(pending)} of {len(args.inputs) + len(skipped)} inputs do not exist yet and were planned on "
                           "as an earlier step's output: " + ", ".join(f"#{p['index'] + 1} {p['path']}" for p in pending)
                           + f"; a real run {then}")
    if len(args.inputs) < 2:
        die("give at least two clips" if not skipped else
            f"only {len(args.inputs)} usable input(s) left after skipping {len(skipped)}; nothing to join",
            skipped=skipped)
    validate_color(args.pad_color, "--pad-color")
    metas = [probe(p) for p in args.inputs]
    for p, m in zip(args.inputs, metas):
        input_length(m, p)  # every clip is placed by its length: one that states none is refused, not 0 s (#491)
    # A pending input's probe is the dry-run stub, whose (0x0) video stream says nothing about the
    # file an earlier step will write. Its extension stands in: a step names its output for what
    # it holds, so an audio extension (.wav, .m4a, .aiff, ... -- every audio file this skill
    # reads, not only the ones it writes) is taken for a file without a picture and any other for
    # one with a picture. Measured and pending inputs then meet the same rules a real run
    # applies: all without a picture is an audio join, a mix is refused.
    pictured = [(os.path.splitext(p)[1].lower() not in AUDIO_MEDIA_EXT) if m.get("dry_run") else bool(m.get("video"))
                for p, m in zip(args.inputs, metas)]
    if all(m.get("dry_run") for m in metas):
        STATE_NOTES.append(f"no input exists yet: {'a video' if any(pictured) else 'an audio'} join was planned from the file extensions")
    if not any(pictured):
        for p, m in zip(args.inputs, metas):
            if not m.get("audio"):
                die(f"{p} has neither a video nor an audio stream")
        if args.copy:
            die("--copy joins video clips; an audio-only join resamples every clip to one format, which a copy cannot do")
        return join_audio(args, metas)
    for p, m, pic in zip(args.inputs, metas, pictured):
        if not pic:
            # name an input measured to have a picture first; a pending one only as expected to
            measured = [q for q, mm in zip(args.inputs, metas) if mm.get("video") and not mm.get("dry_run")]
            planned = [q for q, mm, pc in zip(args.inputs, metas, pictured) if pc and mm.get("dry_run")]
            other = (f"{measured[0]} has one" if measured else
                     f"{planned[0]}, which does not exist yet, is expected to have one (its extension is not an audio one)" if planned else "")
            die((f"{p} does not exist yet, and its audio extension says it will have no video stream" if m.get("dry_run")
                 else f"{p} has no video stream")
                + (f" while {other}; join audio with audio or give every clip a picture" if other else ""))
    if args.copy:
        return join_copy(args, metas)
    first = metas[0]["video"]
    # the first clip's displayed frame: rotation applied, non-square pixels squared (#411)
    fw, fh = display_size(first)
    if args.width and args.height:
        w, h = args.width, args.height
    elif args.width:
        w = args.width
        h = int(round(args.width * fh / fw)) if fw else args.width
    elif args.height:
        h = args.height
        w = int(round(args.height * fw / fh)) if fh else args.height
    else:
        w, h = fw, fh
    fps = args.fps or first.get("fps") or 30.0
    fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
    # the exact rate every length below is counted in (30000/1001, not 29.97)
    rate_q = output_rate(fps, first, bool(args.fps))
    fps = float(rate_q)
    w, h = w - (w % 2), h - (h % 2)
    note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
    durs = [m.get("duration") or 0.0 for m in metas]
    d = args.duration if args.transition != "none" else 0.0
    # every clip gets one length for both streams, so whatever places the next clip -- xfade's
    # offsets, or the concat filter, which starts it after the LONGER stream of this one -- places
    # its picture and its sound together. The plain cut used to take the raw streams, and a sound
    # past the picture (a music bed padded to the container, even a 20 ms AAC tail) left a hole in
    # the video there.
    # Each length is a whole number of frames of the output rate, and each sound length the
    # samples those frames last (#455): a length in milliseconds rounded 5 frames at 30 fps
    # (0.166667 s) up to 0.167 s, the concat filter started the next clip after it, and 60 such
    # clips left one-frame holes from about 8 s on. Sample counts come from the running frame
    # total, so the sound never drifts from the picture by more than one sample.
    lmetas = [with_whole_picture(m, rate_q) for m in metas]
    frames = [clip_frames(m, clip_length(m, fps), rate_q) for m in lmetas]
    # the transition is a whole number of frames too, so xfade's offsets (and acrossfade's
    # overlap) land on frames of the output rate (#468). A transition is at least one frame:
    # --duration 0 used to build acrossfade=ns=0, which FFmpeg refuses
    tframes = max(1, round(d * fps)) if args.transition != "none" else 0
    d = tframes / fps
    lens = [f / fps for f in frames]
    place_silent(lens, d)
    for p, nf in zip(args.inputs, frames):
        if d and nf <= tframes * 2 and not STATE.dry_run:
            die(f"{p} is only {nf / fps:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
    # every sample boundary is a frame position of the OUTPUT rounded once: clip i spans output
    # frames [start_i, start_i + frames_i) and overlaps the clip before it over [start_i,
    # start_i + tframes), so its samples and each overlap's are differences of rounded
    # cumulative positions and their sum telescopes to the output's own length. Rounding each
    # overlap on its own (14414.4 samples -> 14414 at 30000/1001 and 9 frames) left the sound
    # 0.4 samples longer per transition.
    def at(frame: int) -> int:
        return round(frame * JOIN_AUDIO_RATE / rate_q)
    starts, start = [], 0
    for i, nf in enumerate(frames):
        starts.append(start)
        start += nf - tframes
    samples = [at(s0 + nf) - at(s0) for s0, nf in zip(starts, frames)]
    overlaps = [at(s0 + tframes) - at(s0) for s0 in starts]

    cmd = ffmpeg_base()
    extra_inputs: List[str] = []
    parts: List[str] = []
    n = len(args.inputs)
    for i, (p, m) in enumerate(zip(args.inputs, metas)):
        cmd += ["-i", p]
    # silent audio for clips without an audio track. `idx` is this ffmpeg input's position, i.e. n +
    # how many synthetic inputs were already added -- not len(extra_inputs), which counts the six
    # argv tokens ("-f", "lavfi", "-t", duration, "-i", "anullsrc=...") each synthetic input adds, not
    # the input itself. With one no-audio clip both counts coincide (n + 0); from the second no-audio
    # clip onward they diverge, and the previous `n + len(extra_inputs)` named a nonexistent, far-out-of-
    # range ffmpeg input index -- found via a real multi-camera join where every clip lacked audio.
    audio_src: List[str] = []
    added = 0
    for i, m in enumerate(metas):
        if m.get("audio"):
            audio_src.append(f"{i}:a:0")
        else:
            idx = n + added
            extra_inputs += ["-f", "lavfi", "-t", f"{durs[i]:.3f}", "-i", "anullsrc=r=48000:cl=stereo"]
            audio_src.append(f"{idx}:a:0")
            added += 1
    cmd += extra_inputs

    # Any HDR input makes the join HDR (10-bit, HEVC via video_args on that clip's tags): an SDR
    # first clip used to drag an HDR second clip down to 8-bit without a tone map.
    hdr_meta = next((m for m in metas if (m.get("video") or {}).get("bt2020_or_hdr")), None)
    pixfmt = "yuv420p10le" if hdr_meta else "yuv420p"
    line = hdr_meta or metas[0]
    # a BT.601 or RGB clip is converted to the BT.709 the join is tagged with, each clip by its own
    # tags; beside a converted clip (or under a --pad-color with chroma) an untagged one gets its
    # BT.709 label, tags only, so 7.1+'s concat/xfade and pad have nothing to convert or misread
    convert = [matrix_chain(m, line) for m in metas]
    chroma_pad = args.fit != "crop" and draws_chroma([args.pad_color], line)
    if any(convert) or chroma_pad:
        convert = [c or label_chain(m, line) for c, m in zip(convert, metas)]
    # concat/xfade mix samples: a full-range clip (VP9/AV1 full range, 10-bit pc) beside a limited
    # one is taken to limited range first, or it was shown with the other's range (#410)
    convert = [c + range_chain(m, line) for c, m in zip(convert, metas)]

    for p, m in zip(args.inputs, metas):
        if square_pixels(m.get("video")):
            note(square_pixels_note(m["video"], p))

    def geo(i: int) -> str:
        # every clip is squared at its display aspect before it is fitted (#411)
        sq = (square_pixels(metas[i].get("video")) + ",") if square_pixels(metas[i].get("video")) else ""
        if args.fit == "crop":
            return f"{sq}scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
        pad = f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color="
        return (f"{sq}scale={w}:{h}:force_original_aspect_ratio=decrease,"
                + drawn_chain(pad + args.pad_color, as_limited(metas[i]), [args.pad_color], pad + "black", line_meta=line,
                              tag=f"pad{i}", labelled=True))
    # the audio-only join keeps the widest layout; the video join used to force stereo and
    # silently dropped the centre/LFE of 5.1 material. A pending input's stub has no measured
    # layout: plan from the inputs that exist, as join_audio() does.
    chans = [(m.get("audio") or {}).get("channels") or 2 for m in ([m for m in metas if not m.get("dry_run")] or metas)]
    channels = args.channels or max(chans)
    layout = LAYOUTS.get(channels)
    if layout is None:
        die(f"{channels}-channel output has no standard layout here (1, 2, 6 or 8); pass --channels")
    if len(set(chans)) > 1:
        info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
    for i in range(n):
        # the fps filter's time base is one frame (1/rate), so every timestamp downstream is a
        # frame number and an offset in seconds is rounded to a whole frame, never a microsecond
        # off it on any FFmpeg (AVTB left xfade to compare microseconds)
        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={rate_q.numerator}/{rate_q.denominator},format={pixfmt}[v{i}]")
        # the sound is shifted by the picture's start, not to its own (#409): #338 started each
        # clip's picture at 0, and a per-stream PTS-STARTPTS then moved a sound that starts 0.3 s
        # after its picture 0.3 s early. Sound before the first frame is dropped and a late sound
        # is padded, as cut.py's re-cut does; a generated silent track starts at 0 already.
        shift = (av_trim(stream_starts(metas[i])[0], None)[1] + ",") if metas[i].get("audio") else ""
        parts.append(f"[{audio_src[i]}]{shift}aformat=sample_rates=48000:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]")

    # pad the shorter stream to the clip's length: the audio with silence, the picture by holding
    # its last frame, then cut both there -- each clip boundary is then the same for both chains
    # -- by frame and by sample, never by rounded seconds (#455)
    for i in range(n):
        vlen = (lmetas[i].get("video") or {}).get("duration") or lens[i]
        have = round(vlen * fps)
        # one frame more than the gap is held, and the trim cuts at the clip's last frame
        hold = f"tpad=stop_mode=clone:stop={frames[i] - have + 1}," if frames[i] > have else ""
        parts.append(f"[v{i}]{hold}trim=end_frame={frames[i]}[vp{i}]")
        parts.append(f"[a{i}]apad=whole_len={samples[i]},atrim=end_sample={samples[i]}[ap{i}]")
    if args.transition == "none":
        chain = "".join(f"[vp{i}][ap{i}]" for i in range(n))
        parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
    else:
        vprev, aprev = "vp0", "ap0"
        start = 0
        for i in range(1, n):
            # clip i starts on frame `start` of the output; xfade starts on the first frame at or
            # after its offset, so the offset is that frame's time rounded down (#468)
            start += frames[i - 1] - tframes
            vout = f"vx{i}" if i < n - 1 else "vout"
            aout = f"ax{i}" if i < n - 1 else "aout"
            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={frame_time(tframes, rate_q)}"
                         f":offset={frame_time(start, rate_q)}[{vout}]")
            parts.append(f"[{aprev}][ap{i}]acrossfade=ns={overlaps[i]}:c1=tri:c2=tri[{aout}]")
            vprev, aprev = vout, aout

    # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
    # plausible), and the planned command is built on it: say which numbers are placeholders.
    if metas[0].get("dry_run") and not (args.width and args.height and args.fps):
        STATE_NOTES.append(f"the first input is pending, so the planned frame and rate ({w}x{h} @ {fps:g}fps) are "
                           "placeholders: a real run takes them from that file")
    if d and any(m.get("dry_run") for m in metas[:-1]):
        STATE_NOTES.append("the planned xfade offsets count each pending input as 0 s long: a real run offsets "
                           "by its measured length")
    elif not d and any(m.get("dry_run") for m in metas):
        # the plain cut trims/holds every clip to clip_length too (2.4.1), so a pending clip's
        # planned trim=end_frame=0 is the stub's placeholder, not the cut
        STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
                           "or holds it to its measured length")
    output = args.output or default_output(args.inputs[0], "joined", "mp4")
    refuse_list_as_output(args, output)
    cmd += ["-filter_complex", ";".join(parts), "-map", "[vout]", "-map", "[aout]"]
    # the fps filter already made the picture constant-rate, and the per-clip trims (then xfade or
    # concat) place every frame: FFmpeg 5.1's default cfr output mode still duplicated the last one
    # to meet the AAC tail (a 51-frame dissolve came out 52), which newer builds no longer do -- pass
    # the frames through as built, for a plain cut as much as for a transition
    cmd += ["-fps_mode", "passthrough"]
    cmd += video_args(hdr_meta or metas[0], args.crf, args.preset, convert_matrix=False) + aac_args() + [output]
    run(cmd)
    expected = unpending_length(lens, d)
    r = probe(output, role="output")
    # the picture is what the offsets place: measure the video stream, not the container (whose
    # length also counts the AAC tail), against the length the clips add up to
    measured = (r.get("video") or {}).get("duration") or r.get("duration")
    verification = []
    if expected is not None and measured is not None and not STATE.dry_run:
        tol = max(DURATION_TOLERANCE_FRAMES / fps, DURATION_TOLERANCE_MIN)
        verification.append({"step": "duration", "property": "video_duration", "ok": abs(measured - expected) <= tol,
                             "measured": round(measured, 3), "expected": expected,
                             "delta": round(measured - expected, 3), "tolerance": round(tol, 3),
                             "provenance": "input_premeasurement", "inputs_total": round(sum(lens), 3)})
    # a clip with no audio stream is joined over generated silence: the join is right to do that, but
    # the report must say which clips' sound is not theirs (the paper's join finding: absence was
    # filled and nothing in the result showed it)
    substituted = [p for p, m in zip(args.inputs, metas) if not m.get("audio")]
    if substituted:
        STATE_NOTES.append(f"{len(substituted)} clip(s) had no audio stream; their span of the join is generated "
                           "silence: " + ", ".join(os.path.basename(p) for p in substituted))
    info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
    overlap = overlap_report(lens, expected)
    emit(output, mode="video", **overlap, **reported(), clips=n, transition=args.transition, expected_duration=expected,
         frame_rate=f"{rate_q.numerator}/{rate_q.denominator}", clip_frames=frames, transition_frames=tframes,
         verification=verification, expect_streams={"video": 1, "audio": 1}, stream_reference=metas,
         audio_substituted=substituted,
         dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))
    return 0


if __name__ == "__main__":
    sys.exit(main())
