videoconv 2.1__py3-none-any.whl

MyVideoConverter.py

@@ -0,0 +1,893 @@
+"""
+MyVideoConverter
+
+Batch video converter and compressor built on top of ffmpeg.  Supports
+sequential and parallel (multiprocessing) execution, optional rich progress
+bars, file-size and custom-predicate filtering, anime-tuned encoding, and
+automatic timestamp preservation.
+
+Public entry points:
+    main()        — convert every matching file in a folder.
+    main_files()  — convert an explicit list of files.
+"""
+
+import multiprocessing
+import re as regex
+import shlex
+import subprocess
+import time
+from collections.abc import Callable
+from concurrent.futures import ProcessPoolExecutor
+from datetime import datetime, timedelta
+from multiprocessing import Pool
+from typing import Optional
+
+import filedate
+from ext_pathlib import Path
+from ffmpeg_progress_yield import FfmpegProgress
+from ffprobe import ffprobe_info, get_info
+from plyer import notification
+from rich import progress
+from rich.console import Console
+from rich.rule import Rule
+from rich.theme import Theme
+
+console = Console()
+
+VIDEO_EXTENSIONS: tuple[str, ...] = (".mp4", ".webm", ".gif", ".mov", ".m4v", ".mkv")
+
+
+def is_even(num: int) -> bool:
+    """Return True if *num* is evenly divisible by 2."""
+    return num % 2 == 0
+
+
+def pretty_print_timedelta(timedelta_obj: timedelta) -> str:
+    """
+    Convert a timedelta into a human-readable string such as "1 hour, 3 minutes, 5 seconds".
+
+    Only non-zero components are included.  Seconds are always shown when all
+    other components are zero (e.g. a 0-second delta renders as "0 seconds").
+
+    Args:
+        timedelta_obj: The duration to format.
+
+    Returns:
+        A comma-separated string of hours, minutes, and/or seconds.
+    """
+
+    # Get the total number of hours, minutes, and seconds
+    hours = int(timedelta_obj.total_seconds() // 3600)
+    minutes = int((timedelta_obj.total_seconds() % 3600) // 60)
+    seconds = int(timedelta_obj.total_seconds() % 60)
+
+    values = []
+
+    if hours:
+        trailing = "s" if hours > 1 else ""
+        values.append(f"{hours} hour{trailing}")
+
+    if minutes:
+        trailing = "s" if minutes > 1 else ""
+        values.append(f"{minutes} minute{trailing}")
+
+    if seconds or len(values) == 0:
+        trailing = "s" if seconds > 1 or len(values) == 0 else ""
+        values.append(f"{seconds} second{trailing}")
+
+    return ", ".join(values)
+
+
+def mkv_to_mp4(mkv_file: Path) -> Path | bool:
+    """
+    Remux an MKV file to MP4 using ffmpeg stream-copy (no re-encoding).
+
+    On success the source MKV is deleted and the new MP4 path is returned.
+    On failure an error message is printed and False is returned.
+
+    Args:
+        mkv_file: Path to the source MKV file.
+
+    Returns:
+        The Path of the newly created MP4 file, or False if ffmpeg failed.
+    """
+    mp4 = Path(mkv_file.parent.resolve(), f"{mkv_file.stem}.mp4")
+    cmd = f'ffmpeg -y -i "{mkv_file.resolve()}" -c copy "{mp4.resolve()}"'
+    sp = subprocess.run(
+        cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False
+    )
+    if sp.returncode == 0:
+        mkv_file.unlink()
+        return mp4
+
+    console.print("[red]ffmpeg error occured converting MKV to MP4.[/]")
+    print(sp.stderr.decode("utf-8"))
+    return False
+
+
+def video_conversion(
+    file: Path,
+    crf: int = 23,
+    resize: bool = False,
+    date_fix: bool = False,
+    anime: bool = False,
+    progress_dict: Optional[dict] = None,
+    task_id: Optional[int] = 0,
+) -> None:
+    """
+    Encode a single video file to H.264/MP4 via ffmpeg, then call mkv_to_mp4
+    to remux the intermediate MKV to the final MP4 container.
+
+    The output file is written next to the source as ``<stem>_conv.mp4``.
+    Audio and subtitle streams are copied without re-encoding.  A scale filter
+    is inserted when the source has odd dimensions or is a GIF/WebM, and
+    optionally when the longest edge exceeds 1280 px.
+
+    When *progress_dict* and *task_id* are both provided the function streams
+    per-frame progress into the shared dict (used by the rich parallel pool).
+    Otherwise ffmpeg runs silently via subprocess and results are printed on
+    completion.
+
+    Args:
+        file: Path to the input video file.
+        crf: H.264 Constant Rate Factor — lower = higher quality, larger file.
+            Defaults to 23.
+        resize: If True and the longest edge exceeds 1280 px, downscale to 1280
+            on that axis while preserving aspect ratio.  Defaults to False.
+        date_fix: If True, stamp the output file with the original source
+            file's created/modified/accessed times.  Defaults to False.
+        anime: If True, apply ``-tune animation`` and ``-level:v 4`` for
+            better compression on animated content.  Defaults to False.
+        progress_dict: Shared manager dict used to report progress back to the
+            rich progress bar in the parallel pool.  Defaults to None.
+        task_id: Key under which this task writes into *progress_dict*.
+            Defaults to 0.
+    """
+    file_out: Path = Path(file.parent.resolve(), f"{file.stem}_conv.mkv")
+    if file_out.exists():
+        console.print("[yellow]Converted file already exists. Stopping.[/]")
+        return
+    info: ffprobe_info = get_info(file)
+
+    video_setting_line: str = (
+        f"-map 0:v -c:v libx264 -pix_fmt yuv420p -crf {crf} -preset slow"
+    )
+
+    if anime:
+        video_setting_line += " -level:v 4 -tune animation"
+    else:
+        video_setting_line += " -level:v 3.1"
+
+    cmd_list: list[str] = [
+        "ffmpeg -hide_banner -i",
+        f'"{file.resolve()}"',
+        video_setting_line,
+        "-map 0:a? -c:a copy",
+        f'"{file_out}"',
+    ]
+
+    # Resize logic
+    w: int = info.width
+    h: int = info.height
+    if max(w, h) > 1280:
+        if resize:
+            cmd_list.insert(
+                4, "-vf \"scale='if(gt(iw,ih),1280,-2)':'if(gt(iw,ih),-2,1280)'\""
+            )
+    elif not all([is_even(w), is_even(h)]) or file.suffix in [".gif", ".webm"]:
+        cmd_list.insert(4, '-vf "scale=ceil(iw/2)*2:ceil(ih/2)*2"')
+
+    # Subtitle logic
+    if info.has_subtitle:
+        subtitle_maps: list[str] = []
+        for index, subtitle in enumerate(info.subtitle_streams):
+            subtitle_maps.append(f"-map 0:s:{index}")
+        subtitle_map_str: str = " ".join(subtitle_maps) + " -c:s copy"
+        cmd_list.insert(4, subtitle_map_str)
+
+    cmd: str = " ".join(cmd_list)
+
+    start: float = time.perf_counter()
+    is_error: bool = False
+    if progress_dict is not None and task_id is not None:
+        ff: FfmpegProgress = FfmpegProgress(shlex.split(cmd))
+        done_percentage: float = 0.0
+        video_time: int = int(info.dur.total_seconds())
+        video_time_done: int = 0
+        for doneperc in ff.run_command_with_progress():
+            done_percentage = doneperc
+            video_time_done = int(doneperc / 100 * video_time)
+            progress_dict[task_id] = {
+                "progress": doneperc,
+                "total": 100,
+                "current": video_time_done,
+                "total_time": video_time,
+            }
+        is_error = done_percentage != 100
+        rich_used: bool = True
+    else:
+        sp: subprocess.CompletedProcess = subprocess.run(
+            cmd, shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=False
+        )
+        is_error = sp.returncode != 0
+        rich_used = False
+    elapsed: timedelta = timedelta(seconds=time.perf_counter() - start)
+
+    if is_error:
+        console.print("[red]ffmpeg error occured.[/]")
+        if not rich_used:
+            print(sp.stderr.decode("utf-8"))
+    else:
+        mp4_file: Path = mkv_to_mp4(file_out)
+        if not mp4_file:
+            console.log(
+                "[yellow]Video converted to MKV, but MP4 conversion was unsuccessful.[/]"
+            )
+            return
+
+        in_size: int | float = file.mb()
+        out_size: int | float = mp4_file.mb()
+        in_bytes: int = file.b()
+        out_bytes: int = mp4_file.b()
+
+        if not rich_used:
+            console.print("[green]Success![/]")
+        stat_str = (
+            f"Converted '{file.stem}' length {info.dur} in {elapsed}. New file is"
+            f" {out_bytes/in_bytes:.2%} of the original size. ({in_size:.1f}MB -> {out_size:.1f}MB)"
+        )
+        if not rich_used:
+            console.print(stat_str)
+        if date_fix:
+            ctime, mtime, atime = file.getctime(), file.getmtime(), file.getatime()
+            filedate.File(mp4_file).set(created=ctime, modified=mtime, accessed=atime)
+
+
+def _run_conversions(
+    files_dict: list[dict], threads: int = 4, use_rich: bool = True
+) -> None:
+    """
+    Run all pending conversions, choosing the execution strategy based on
+    *threads* and *use_rich*.
+
+    - threads is None / 0 / 1  → simple sequential loop, no multiprocessing.
+    - threads >= 2, use_rich=False → multiprocessing.Pool with a plain spinner.
+    - threads >= 2, use_rich=True  → ProcessPoolExecutor with a rich multi-bar
+      progress display driven by a shared manager dict.
+
+    Args:
+        files_dict: List of kwarg dicts, each ready to be unpacked into
+            ``video_conversion(**file_dict)``.
+        threads: Number of worker processes for parallel execution.  Values of
+            None, 0, or 1 disable multiprocessing entirely.  Defaults to 4.
+        use_rich: Whether to show the rich per-file progress bars when running
+            in parallel.  Defaults to True.
+    """
+    if not threads or threads == 1:
+        for file_dict in files_dict:
+            video_conversion(**file_dict)
+        return
+
+    if not use_rich:
+        with Pool(threads) as p:
+            with console.status(
+                "[green]Process Pool running[/]", spinner="simpleDotsScrolling"
+            ):
+                p.map(lambda kw: video_conversion(**kw), files_dict)
+        return
+
+    # Rich progress pool
+    theme = Theme(
+        {
+            "progress.elapsed": "white",
+            "progress.download": "white",
+            "progress.remaining": "white",
+            "progress.percentage": "white",
+        }
+    )
+
+    with progress.Progress(
+        progress.SpinnerColumn(),
+        "[progress.description]{task.description}",
+        progress.BarColumn(
+            style="gray50",
+            complete_style="dodger_blue2",
+            finished_style="green3",
+        ),
+        "[progress.percentage]{task.percentage:>3.0f}%",
+        progress.TextColumn("•"),
+        progress.TimeRemainingColumn(),
+        progress.TextColumn("•"),
+        progress.TimeElapsedColumn(),
+        refresh_per_second=10,
+        console=Console(theme=theme),
+    ) as progress_bar:
+        futures = []
+        with multiprocessing.Manager() as manager:
+            _progress = manager.dict()
+            overall_progress_task = progress_bar.add_task(
+                f"[green]{'Conversion Progress':<40}"
+            )
+            total_queue_time: int = int(
+                sum(
+                    get_info(file_dict["file"]).dur.total_seconds()
+                    for file_dict in files_dict
+                )
+            )
+
+            with ProcessPoolExecutor(max_workers=threads) as executor:
+                for file_dict in files_dict:
+                    task_id = progress_bar.add_task(
+                        f"{file_dict['file'].stem[:40]:<40}", visible=False
+                    )
+                    file_dict["progress_dict"] = _progress
+                    file_dict["task_id"] = task_id
+                    futures.append(executor.submit(video_conversion, **file_dict))
+
+                while sum(future.done() for future in futures) < len(futures):
+                    overall_video_time_done: int = sum(
+                        tup[1].get("current", 0) for tup in _progress.items()
+                    )
+                    progress_bar.update(
+                        overall_progress_task,
+                        completed=overall_video_time_done,
+                        total=total_queue_time,
+                    )
+                    for task_id, update_data in _progress.items():
+                        latest = update_data["progress"]
+                        total = update_data["total"]
+                        progress_bar.update(
+                            task_id,
+                            completed=latest,
+                            total=total,
+                            visible=latest < total,
+                        )
+
+            progress_bar.update(
+                overall_progress_task, completed=len(futures), total=len(futures)
+            )
+
+            for future in futures:
+                future.result()
+
+
+def _build_files_dict(
+    files: list[Path],
+    crf: int,
+    resize: bool,
+    date_fix: bool,
+    anime: bool,
+    size_filt: str | None = None,
+    func_filt: Callable | None = None,
+) -> list[dict]:
+    """
+    Filter *files* and build the list of kwarg dicts consumed by
+    ``video_conversion`` / ``_run_conversions``.
+
+    A file is skipped if any of the following are true:
+      - Its converted output (``<stem>_conv.mp4``) already exists.
+      - Its byte size is below the *size_filt* threshold.
+      - *func_filt* returns False for it.
+
+    Args:
+        files: Candidate input files to evaluate.
+        crf: H.264 Constant Rate Factor passed through to ``video_conversion``.
+        resize: Resize flag passed through to ``video_conversion``.
+        date_fix: Timestamp-preservation flag passed through to
+            ``video_conversion``.
+        anime: Anime-encoding flag passed through to ``video_conversion``.
+        size_filt: Human-readable minimum file size (e.g. ``"500k"``, ``"2M"``).
+            Files smaller than this are skipped.  Defaults to None (no filter).
+        func_filt: Optional predicate — a file is included only when this
+            callable returns True for it.  Defaults to None (no filter).
+
+    Returns:
+        A list of dicts, each ready to be unpacked as
+        ``video_conversion(**file_dict)``.
+    """
+    min_size: int | float = parse_bytes(size_filt) if size_filt else 0
+    files_dict = []
+    for f in files:
+        if min_size and f.stat().st_size < min_size:
+            continue
+        if func_filt and not func_filt(f):
+            continue
+        _out = Path(f.parent, f"{f.stem}_conv.mp4")
+        if not _out.exists():
+            files_dict.append(
+                {
+                    "file": f,
+                    "crf": crf,
+                    "resize": resize,
+                    "date_fix": date_fix,
+                    "anime": anime,
+                }
+            )
+    return files_dict
+
+
+def _notify() -> None:
+    """
+    Send a desktop notification announcing that the conversion batch is done.
+
+    Errors from the notification system (including KeyboardInterrupt) are
+    silently swallowed so that a missing notification daemon never crashes the
+    script.
+    """
+    try:
+        notification.notify(
+            title="VideoConverter", message="Script is done!", timeout=5
+        )
+    except KeyboardInterrupt:
+        pass
+    except Exception:
+        console.print("[red]Error showing notification[/]")
+
+
+def parse_bytes(
+    value: str, default: int | float = 0, suffixes: str = "bkmgtp"
+) -> int | float:
+    """
+    Parse a human-readable byte size string (e.g. ``"500k"``, ``"2.5M"``,
+    ``"1G"``) and return the equivalent number of bytes as an int.
+
+    The suffix character (case-insensitive) maps to a power of 1024:
+    b=1, k=1024, m=1024², g=1024³, t=1024⁴, p=1024⁵.  If no recognised
+    suffix is present the value is treated as plain bytes.
+
+    Args:
+        value: The size string to parse (e.g. ``"500k"``, ``"2.5M"``).
+        default: Value returned when *value* cannot be parsed.  Defaults to 0.
+        suffixes: Ordered string of recognised suffix characters.
+            Defaults to ``"bkmgtp"``.
+
+    Returns:
+        The parsed byte count rounded to the nearest integer, or *default* on
+        any parse error.
+    """
+
+    try:
+        last = value[-1].lower()
+    except (TypeError, LookupError):
+        return default
+
+    if last in suffixes:
+        mul = 1024 ** suffixes.index(last)
+        value = value[:-1]
+    else:
+        mul = 1
+
+    try:
+        return round(float(value) * mul)
+    except ValueError:
+        return default
+
+
+def folder_iter(
+    folder: str = ".",
+    exts: tuple[str] | list[str] = ("*.webm", "*.gif"),
+    crf: int = 23,
+    resize: bool = False,
+    date_fix: bool = False,
+    anime: bool = False,
+    threads: int = 4,
+    use_rich: bool = True,
+    notify: bool = True,
+    size_filt: str | None = None,
+    func_filt: Callable | None = None,
+) -> None:
+    """
+    Scan a folder for video files and convert all that have not already been
+    processed.
+
+    Matching files are collected, filtered through ``_build_files_dict``, then
+    dispatched via ``_run_conversions``.  Already-converted files
+    (``<stem>_conv.mp4``) are automatically skipped.
+
+    Args:
+        folder: Directory to scan.  Defaults to the current working directory.
+        exts: Glob patterns for the file extensions to include
+            (e.g. ``["*.mp4", "*.webm"]``).  Defaults to ``("*.webm", "*.gif")``.
+        crf: H.264 Constant Rate Factor — lower = higher quality, larger file.
+            Defaults to 23.
+        resize: Downscale videos whose longest edge exceeds 1280 px.
+            Defaults to False.
+        date_fix: Copy the source file's timestamps to the output file.
+            Defaults to False.
+        anime: Apply anime-optimised encoding settings (``-tune animation``).
+            Defaults to False.
+        threads: Worker processes for parallel conversion.  None / 0 / 1 runs
+            sequentially.  Defaults to 4.
+        use_rich: Show per-file rich progress bars when running in parallel.
+            Defaults to True.
+        notify: Send a desktop notification when the batch finishes.
+            Defaults to True.
+        size_filt: Skip files smaller than this size (e.g. ``"500k"``).
+            Defaults to None.
+        func_filt: Skip files for which this predicate returns False.
+            Defaults to None.
+    """
+
+    files: list[Path] = sorted(
+        (
+            f
+            for f in Path(folder).scan(exts)
+            if not regex.search("_conv$", f.stem, regex.I)
+        ),
+        key=lambda x: x.name.casefold(),
+    )
+    files_dict = _build_files_dict(
+        files, crf, resize, date_fix, anime, size_filt, func_filt
+    )
+    _run_conversions(files_dict, threads=threads, use_rich=use_rich)
+    if notify:
+        _notify()
+
+
+def file_converter(
+    files: str | Path | list[str] | list[Path],
+    crf: int = 23,
+    resize: bool = False,
+    date_fix: bool = False,
+    anime: bool = False,
+    threads: int = 4,
+    use_rich: bool = True,
+    notify: bool = True,
+    size_filt: str | None = None,
+    func_filt: Callable | None = None,
+) -> None:
+    """
+    Convert an explicit file or list of files, skipping any whose output
+    already exists.
+
+    Accepts a single path (str or Path) or a collection of paths, normalises
+    them to a list of Path objects, then delegates filtering to
+    ``_build_files_dict`` and execution to ``_run_conversions``.
+
+    Args:
+        files: A single file path or a list of file paths to convert.
+        crf: H.264 Constant Rate Factor — lower = higher quality, larger file.
+            Defaults to 23.
+        resize: Downscale videos whose longest edge exceeds 1280 px.
+            Defaults to False.
+        date_fix: Copy the source file's timestamps to the output file.
+            Defaults to False.
+        anime: Apply anime-optimised encoding settings (``-tune animation``).
+            Defaults to False.
+        threads: Worker processes for parallel conversion.  None / 0 / 1 runs
+            sequentially.  Defaults to 4.
+        use_rich: Show per-file rich progress bars when running in parallel.
+            Defaults to True.
+        notify: Send a desktop notification when the batch finishes.
+            Defaults to True.
+        size_filt: Skip files smaller than this size (e.g. ``"500k"``).
+            Defaults to None.
+        func_filt: Skip files for which this predicate returns False.
+            Defaults to None.
+    """
+
+    if isinstance(files, (str, Path)):
+        _files: list[Path] = [Path(files)]
+    else:
+        _files = [Path(f) for f in files]
+
+    files_dict = _build_files_dict(
+        _files, crf, resize, date_fix, anime, size_filt, func_filt
+    )
+    _run_conversions(files_dict, threads=threads, use_rich=use_rich)
+    if notify:
+        _notify()
+
+
+def _find_conv_files(folder: str | Path) -> list[tuple["Path", "Path"]]:
+    """
+    Scan *folder* and return ``(converted, original)`` Path pairs for every
+    file whose stem ends with ``_conv`` and whose pre-conversion source still
+    exists in the same directory.
+
+    Used by ``conversion_size_check`` and ``conversion_delete`` to locate
+    original files without duplicating the scan logic.
+
+    Args:
+        folder: Directory to scan.
+
+    Returns:
+        A list of ``(conv_file, original_file)`` tuples.  Files whose original
+        cannot be found are omitted.
+    """
+    pairs = []
+    for file in Path(folder).scan("*"):
+        if not (
+            regex.search("_conv$", file.stem, regex.I)
+            and file.is_file()
+            and file.suffix != ".py"
+        ):
+            continue
+        non_conv_name = regex.sub("_conv$", "", file.stem, regex.I)
+        try:
+            original = next(
+                Path(file.parent, f"{non_conv_name}{ext}")
+                for ext in VIDEO_EXTENSIONS
+                if Path(file.parent, f"{non_conv_name}{ext}").exists()
+            )
+            pairs.append((file, original))
+        except StopIteration:
+            continue
+    return pairs
+
+
+def conversion_size_check(folder: str | Path = ".") -> None:
+    """
+    Print a summary of the total size reduction achieved by the conversion batch.
+
+    Scans *folder* for ``_conv`` files via ``_find_conv_files``, sums the byte
+    sizes of both the originals and the converted outputs, and prints a single
+    rich-formatted line showing file count, before/after sizes in MB, and the
+    percentage reduction.  Does nothing if no converted files are found.
+
+    Args:
+        folder: Directory to inspect.  Defaults to the current working directory.
+    """
+    pairs = _find_conv_files(folder)
+    total_before_size = sum(orig.b() for _, orig in pairs)
+    total_after_size = sum(conv.b() for conv, _ in pairs)
+    try:
+        console.print(
+            Rule(style="bright_white"),
+            (
+                f"[bold cyan]{len(pairs)}[/] files converted, [bold cyan]{total_before_size/1024**2:.1f}"
+                f"[/]MB -> [bold cyan]{total_after_size/1024**2:.1f}[/]MB, new files are [bold cyan]"
+                f"{(total_after_size/total_before_size)*100:.1f}[/]% the size of the old files."
+            ),
+            highlight=False,
+        )
+    except ZeroDivisionError:
+        pass
+
+
+def conversion_delete(folder: str | Path = ".") -> None:
+    """
+    Delete the original (pre-conversion) source files in *folder*.
+
+    Uses ``_find_conv_files`` to locate every ``_conv`` file that still has a
+    matching original alongside it, then deletes only the originals.  The
+    converted outputs are left untouched.
+
+    Args:
+        folder: Directory to clean up.  Defaults to the current working directory.
+    """
+    for _, original in _find_conv_files(folder):
+        original.unlink()
+
+
+def _main_finish(
+    start: "datetime",
+    folders: list["Path"],
+    prompt_delete: bool,
+    force_delete: bool,
+    wait_on_finish: bool,
+) -> None:
+    """
+    Print timing stats, handle optional cleanup, and optionally wait for input.
+
+    Shared by ``main`` and ``main_files`` to avoid duplicating their identical
+    closing logic.  Prints the start/finish timestamps and human-readable
+    elapsed time, then conditionally deletes original files (with or without a
+    confirmation prompt), then optionally blocks until the user presses Enter.
+
+    Args:
+        start: Timestamp recorded immediately before the conversion began.
+        folders: Directories whose originals may be deleted.
+        prompt_delete: If True, ask the user whether to delete originals before
+            doing so.  Takes precedence over *force_delete*.
+        force_delete: If True (and *prompt_delete* is False), delete originals
+            without asking.
+        wait_on_finish: If True, block until the user presses Enter — useful
+            when running from a double-clicked script that would otherwise close
+            its window immediately.
+    """
+    end = datetime.now()
+    fmt = "%m/%d %I:%M:%S %p"
+    console.print(
+        (
+            f"Started  : [bold green]{start.strftime(fmt)}[/]"
+            f"\nFinished : [bold green]{end.strftime(fmt)}[/]"
+        ),
+        highlight=False,
+    )
+    console.print(
+        f"Elapsed  : [bold cyan]{pretty_print_timedelta(end - start)}[/]",
+        highlight=False,
+    )
+
+    if prompt_delete:
+        clean = console.input(
+            "Type [green3]'y'[/] to delete pre-conversion files,"
+            "type [red3]'n'[/] or nothing to preserve it: "
+        )
+        if regex.search(r"^\s*y\s*$", clean, regex.I):
+            for folder in folders:
+                conversion_delete(folder=folder)
+    elif force_delete:
+        for folder in folders:
+            conversion_delete(folder=folder)
+
+    if wait_on_finish:
+        wait_for_input()
+
+
+def wait_for_input() -> None:
+    """
+    Print a prompt and block until the user presses Enter.
+
+    Useful when the script is launched by double-clicking so that the terminal
+    window stays open long enough to read the output.
+    """
+
+    console.print(r"Press [bright_white]\[enter][/] when you're done.", highlight=False)
+    input()
+
+
+def main(
+    folder: str = ".",
+    exts: tuple[str] | list[str] = (
+        "*.webm",
+        "*.gif",
+        "*.mp4",
+        "*.mov",
+        "*.m4v",
+        "*.mkv",
+    ),
+    crf: int = 28,
+    resize: bool = False,
+    date_fix: bool = True,
+    anime: bool = False,
+    threads: int = 4,
+    use_rich: bool = True,
+    size_filt: str | None = None,
+    func_filt: Callable | None = None,
+    prompt_delete: bool = False,
+    force_delete: bool = False,
+    notify_on_finish: bool = True,
+    wait_on_finish: bool = True,
+) -> None:
+    """
+    Convert all matching video files in *folder* and print a final summary.
+
+    This is the primary entry point for folder-based batch conversion.  It
+    runs ``folder_iter`` to perform the conversions, then calls
+    ``conversion_size_check`` to report size savings, and finally
+    ``_main_finish`` to print timing, handle optional cleanup, and optionally
+    wait for user input before returning.
+
+    Args:
+        folder: Directory containing the videos to convert.  Defaults to the
+            current working directory.
+        exts: Glob patterns for file extensions to include.  Defaults to the
+            most common video formats.
+        crf: H.264 Constant Rate Factor.  Lower = higher quality / larger file.
+            Defaults to 28.
+        resize: Downscale videos whose longest edge exceeds 1280 px.
+            Defaults to False.
+        date_fix: Preserve the source file's timestamps on the output.
+            Defaults to True.
+        anime: Apply anime-optimised encoding settings.  Defaults to False.
+        threads: Worker processes for parallel conversion.  None / 0 / 1 runs
+            sequentially.  Defaults to 4.
+        use_rich: Show per-file rich progress bars when running in parallel.
+            Defaults to True.
+        size_filt: Skip files smaller than this size (e.g. ``"500k"``).
+            Defaults to None.
+        func_filt: Skip files for which this predicate returns False.
+            Defaults to None.
+        prompt_delete: Ask the user whether to delete originals after conversion.
+            Defaults to False.
+        force_delete: Delete originals after conversion without prompting.
+            Defaults to False.
+        notify_on_finish: Send a desktop notification when the batch finishes.
+            Defaults to True.
+        wait_on_finish: Block until the user presses Enter before returning.
+            Defaults to True.
+    """
+    start = datetime.now()
+    folder_iter(
+        folder=folder,
+        exts=exts,
+        crf=crf,
+        resize=resize,
+        date_fix=date_fix,
+        anime=anime,
+        threads=threads,
+        use_rich=use_rich,
+        notify=notify_on_finish,
+        size_filt=size_filt,
+        func_filt=func_filt,
+    )
+    conversion_size_check(folder=folder)
+    _main_finish(
+        start=start,
+        folders=[Path(folder)],
+        prompt_delete=prompt_delete,
+        force_delete=force_delete,
+        wait_on_finish=wait_on_finish,
+    )
+
+
+def main_files(
+    files: str | Path | list[str] | list[Path],
+    crf: int = 28,
+    resize: bool = False,
+    date_fix: bool = True,
+    anime: bool = False,
+    threads: int = 4,
+    use_rich: bool = True,
+    size_filt: str | None = None,
+    func_filt: Callable | None = None,
+    prompt_delete: bool = False,
+    force_delete: bool = False,
+    notify_on_finish: bool = True,
+    wait_on_finish: bool = True,
+) -> None:
+    """
+    Convert an explicit list of video files and print a final summary.
+
+    This is the primary entry point for file-based batch conversion.  It runs
+    ``file_converter`` to perform the conversions, then calls
+    ``conversion_size_check`` for each unique parent directory, and finally
+    ``_main_finish`` to print timing, handle optional cleanup, and optionally
+    wait for user input before returning.
+
+    Args:
+        files: A single file path or a list of file paths to convert.
+        crf: H.264 Constant Rate Factor.  Lower = higher quality / larger file.
+            Defaults to 28.
+        resize: Downscale videos whose longest edge exceeds 1280 px.
+            Defaults to False.
+        date_fix: Preserve the source file's timestamps on the output.
+            Defaults to True.
+        anime: Apply anime-optimised encoding settings.  Defaults to False.
+        threads: Worker processes for parallel conversion.  None / 0 / 1 runs
+            sequentially.  Defaults to 4.
+        use_rich: Show per-file rich progress bars when running in parallel.
+            Defaults to True.
+        size_filt: Skip files smaller than this size (e.g. ``"500k"``).
+            Defaults to None.
+        func_filt: Skip files for which this predicate returns False.
+            Defaults to None.
+        prompt_delete: Ask the user whether to delete originals after conversion.
+            Defaults to False.
+        force_delete: Delete originals after conversion without prompting.
+            Defaults to False.
+        notify_on_finish: Send a desktop notification when the batch finishes.
+            Defaults to True.
+        wait_on_finish: Block until the user presses Enter before returning.
+            Defaults to True.
+    """
+
+    start = datetime.now()
+    file_converter(
+        files=files,
+        crf=crf,
+        resize=resize,
+        date_fix=date_fix,
+        anime=anime,
+        threads=threads,
+        use_rich=use_rich,
+        notify=notify_on_finish,
+        size_filt=size_filt,
+        func_filt=func_filt,
+    )
+    folders: list[Path] = list({Path(f).parent for f in files})
+    for folder in folders:
+        conversion_size_check(folder=folder)
+    _main_finish(
+        start=start,
+        folders=folders,
+        prompt_delete=prompt_delete,
+        force_delete=force_delete,
+        wait_on_finish=wait_on_finish,
+    )
+
+
+if __name__ == "__main__":
+    pass