better-ffmpeg-progress 5.4.2__tar.gz → 6.0.1__tar.gz

{better_ffmpeg_progress-5.4.2/better_ffmpeg_progress.egg-info → better_ffmpeg_progress-6.0.1}/PKG-INFO

@@ -1,21 +1,23 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: better-ffmpeg-progress
-Version: 5.4.2
+Version: 6.0.1
 Summary: Run FFmpeg & see percentage progress + ETA.
-Home-page: https://github.com/CrypticSignal/better-ffmpeg-progress
-Author: GitHub.com/CrypticSignal
-Author-email: theaudiophile@outlook.com
+Author-email: "GitHub.com/CrypticSignal" <theaudiophile@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/CrypticSignal/better-ffmpeg-progress
+Project-URL: Changelog, https://github.com/CrypticSignal/better-ffmpeg-progress/blob/main/CHANGELOG.md
 Keywords: ffmpeg,progress
 Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psutil
-Requires-Dist: requests
 Requires-Dist: rich
 Requires-Dist: tqdm
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
 
 <div align="center">
 
@@ -65,9 +67,8 @@ command = [
 ]
 
 try:
+    # Pass use_tqdm=True to use tqdm instead of Rich.
     process = FfmpegProcess(command)
-    # Uncomment this line to use tqdm instead of Rich.
-    # process.use_tqdm = True
 
     process.run()
 except FfmpegProcessError as e:
@@ -137,14 +138,50 @@ An instance of `FfmpegProcess` accepts the following optional arguments:
 * `ffmpeg_log_file` — Filepath or file-like object to which FFmpeg stderr will be written. Default: `<input filename>_ffmpeg_log.txt`.
 * `print_detected_duration` — Print the detected duration. Default: `False`.
 * `duration_override` — Specify input file duration in seconds to use for progress calculation, instead of trying to detect this automatically with FFprobe. Default: `None`.
+* `use_tqdm` — Use tqdm instead of Rich for the progress bar. Default: `False`.
+* `overwrite` — What to do if the output file already exists: `True` overwrites it, `False` raises `FfmpegCommandError`, and `None` asks whether to overwrite it. Ignored if the command contains `-y` or `-n`. Default: `None`.
 
 The `run` method accepts the following optional argument:
 * `print_command` — Print the FFmpeg command being executed. Default: `False`.
 
 ## Using tqdm
-By default, the [Rich](https://github.com/Textualize/rich) library is used to display a progress bar. [tqdm](https://github.com/tqdm/tqdm) can be used instead by setting `process.use_tqdm = True`:
+By default, the [Rich](https://github.com/Textualize/rich) library is used to display a progress bar. [tqdm](https://github.com/tqdm/tqdm) can be used instead by passing `use_tqdm=True`:
 ```python
-process = FfmpegProcess(command)
-process.use_tqdm = True
+process = FfmpegProcess(command, use_tqdm=True)
 process.run()
 ```
+## Limitations
+- Progress is calculated from the duration of the first input (the first `-i`).
+- The last argument of the command is treated as the output file, e.g. when checking whether it already exists. With multiple outputs, only the last one is checked.
+
+## Development
+Install the package in editable mode with the test dependencies, then run the tests (FFmpeg and FFprobe must be installed):
+```bash
+pip install -e ".[test]"
+```
+```bash
+pytest
+```
+`test.py` is a standalone example that encodes a test pattern and shows the progress bar.
+
+## Publishing
+Update `__version__` in `better_ffmpeg_progress/__init__.py` and add an entry to `CHANGELOG.md`.
+
+One-time setup:
+```bash
+python -m pip install --upgrade build twine pkginfo
+```
+
+Then, for each release:
+```bash
+rm -rf dist
+```
+```bash
+python -m build
+```
+```bash
+python -m twine check dist/*
+```
+```bash
+python -m twine upload dist/*
+```

better_ffmpeg_progress-5.4.2/PKG-INFO → better_ffmpeg_progress-6.0.1/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.1
-Name: better-ffmpeg-progress
-Version: 5.4.2
-Summary: Run FFmpeg & see percentage progress + ETA.
-Home-page: https://github.com/CrypticSignal/better-ffmpeg-progress
-Author: GitHub.com/CrypticSignal
-Author-email: theaudiophile@outlook.com
-Keywords: ffmpeg,progress
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: psutil
-Requires-Dist: requests
-Requires-Dist: rich
-Requires-Dist: tqdm
-
 <div align="center">
 
 # Better FFmpeg Progress
@@ -65,9 +46,8 @@ command = [
 ]
 
 try:
+    # Pass use_tqdm=True to use tqdm instead of Rich.
     process = FfmpegProcess(command)
-    # Uncomment this line to use tqdm instead of Rich.
-    # process.use_tqdm = True
 
     process.run()
 except FfmpegProcessError as e:
@@ -137,14 +117,50 @@ An instance of `FfmpegProcess` accepts the following optional arguments:
 * `ffmpeg_log_file` — Filepath or file-like object to which FFmpeg stderr will be written. Default: `<input filename>_ffmpeg_log.txt`.
 * `print_detected_duration` — Print the detected duration. Default: `False`.
 * `duration_override` — Specify input file duration in seconds to use for progress calculation, instead of trying to detect this automatically with FFprobe. Default: `None`.
+* `use_tqdm` — Use tqdm instead of Rich for the progress bar. Default: `False`.
+* `overwrite` — What to do if the output file already exists: `True` overwrites it, `False` raises `FfmpegCommandError`, and `None` asks whether to overwrite it. Ignored if the command contains `-y` or `-n`. Default: `None`.
 
 The `run` method accepts the following optional argument:
 * `print_command` — Print the FFmpeg command being executed. Default: `False`.
 
 ## Using tqdm
-By default, the [Rich](https://github.com/Textualize/rich) library is used to display a progress bar. [tqdm](https://github.com/tqdm/tqdm) can be used instead by setting `process.use_tqdm = True`:
+By default, the [Rich](https://github.com/Textualize/rich) library is used to display a progress bar. [tqdm](https://github.com/tqdm/tqdm) can be used instead by passing `use_tqdm=True`:
 ```python
-process = FfmpegProcess(command)
-process.use_tqdm = True
+process = FfmpegProcess(command, use_tqdm=True)
 process.run()
 ```
+## Limitations
+- Progress is calculated from the duration of the first input (the first `-i`).
+- The last argument of the command is treated as the output file, e.g. when checking whether it already exists. With multiple outputs, only the last one is checked.
+
+## Development
+Install the package in editable mode with the test dependencies, then run the tests (FFmpeg and FFprobe must be installed):
+```bash
+pip install -e ".[test]"
+```
+```bash
+pytest
+```
+`test.py` is a standalone example that encodes a test pattern and shows the progress bar.
+
+## Publishing
+Update `__version__` in `better_ffmpeg_progress/__init__.py` and add an entry to `CHANGELOG.md`.
+
+One-time setup:
+```bash
+python -m pip install --upgrade build twine pkginfo
+```
+
+Then, for each release:
+```bash
+rm -rf dist
+```
+```bash
+python -m build
+```
+```bash
+python -m twine check dist/*
+```
+```bash
+python -m twine upload dist/*
+```

{better_ffmpeg_progress-5.4.2 → better_ffmpeg_progress-6.0.1}/better_ffmpeg_progress/__init__.py

@@ -1,3 +1,5 @@
+__version__ = "6.0.1"
+
 from .better_ffmpeg_progress import FfmpegProcess
 from .enums import FfmpegLogLevel
 from .exceptions import (
@@ -8,6 +10,7 @@ from .exceptions import (
 )
 
 __all__ = [
+    "__version__",
     "FfmpegProcess",
     "FfmpegLogLevel",
     "FfmpegProcessError",

better_ffmpeg_progress-6.0.1/better_ffmpeg_progress/better_ffmpeg_progress.py

@@ -0,0 +1,277 @@
+import contextlib
+import math
+import os
+import re
+import shlex
+import subprocess
+from pathlib import Path
+from typing import IO, Any, List, Optional, Union
+
+from .enums import FfmpegLogLevel
+from .exceptions import (
+    FfmpegCommandError,
+    FfmpegProcessError,
+    FfmpegProcessInterruptedError,
+    FfmpegProcessUserCancelledError,
+)
+from .progress_bars import show_rich_progress, show_tqdm_progress
+from .terminate_process import terminate_ffmpeg_process
+from .utils import (
+    build_failure_message,
+    get_expected_output_duration,
+    get_media_duration,
+    is_lavfi_input,
+    is_local_file_input,
+    is_stdin_input,
+    truncate_filename,
+    validate_ffmpeg_command,
+)
+
+_MAX_FILENAME_LENGTH = 60
+
+
+def _safe_filename(name: str) -> str:
+    """Replaces characters that are not valid in filenames on every OS."""
+    return re.sub(r"[^\w.,-]", "_", name)
+
+
+def _parse_log_level(ffmpeg_log_level: Optional[Union[FfmpegLogLevel, str]]) -> FfmpegLogLevel:
+    if ffmpeg_log_level is None:
+        return FfmpegLogLevel.VERBOSE
+    if isinstance(ffmpeg_log_level, FfmpegLogLevel):
+        return ffmpeg_log_level
+    if not isinstance(ffmpeg_log_level, str):
+        raise TypeError(
+            "ffmpeg_log_level must be an FfmpegLogLevel, a string or None, not "
+            f"{type(ffmpeg_log_level).__name__}"
+        )
+    try:
+        return FfmpegLogLevel(ffmpeg_log_level.lower())
+    except ValueError:
+        valid_levels = [level.value for level in FfmpegLogLevel]
+        raise FfmpegCommandError(
+            f"Invalid ffmpeg_log_level string: '{ffmpeg_log_level}'. "
+            f"Must be one of {valid_levels} (case-insensitive)."
+        ) from None
+
+
+def _parse_duration_override(duration_override: Any) -> float:
+    if isinstance(duration_override, bool):
+        raise TypeError("duration_override must be a number of seconds, not bool")
+    try:
+        duration = float(duration_override)
+    except (TypeError, ValueError) as e:
+        raise TypeError("duration_override must be a number of seconds or None") from e
+    if not math.isfinite(duration) or duration <= 0:
+        raise ValueError("duration_override must be a finite number greater than 0")
+    return duration
+
+
+def _default_log_file(command: List[str], input_flag_pos: int) -> Path:
+    """Returns the default log file path, which is named after the input."""
+    input_file = command[input_flag_pos + 1]
+
+    if is_lavfi_input(command, input_flag_pos):
+        # A filtergraph such as "testsrc2=size=1920x1080" can contain characters that are not
+        # valid in filenames (e.g. ":" on Windows), so name the log after the source instead.
+        source_name = _safe_filename(input_file.split("=", 1)[0])
+        return Path(f"lavfi_{source_name}_ffmpeg_log.txt")
+    if input_file == "-":
+        return Path("stdin_ffmpeg_log.txt")
+    if is_local_file_input(command, input_flag_pos):
+        return Path(f"{Path(input_file).name}_ffmpeg_log.txt")
+    # URLs and other protocols (e.g. "pipe:0") can contain characters that are not valid in
+    # filenames, such as ":" or "?".
+    name = Path(input_file).name or input_file
+    return Path(f"{_safe_filename(name)}_ffmpeg_log.txt")
+
+
+class FfmpegProcess:
+    def __init__(
+        self,
+        command: List[str],
+        ffmpeg_log_level: Optional[Union[FfmpegLogLevel, str]] = None,
+        ffmpeg_log_file: Optional[Union[str, os.PathLike, IO[Any]]] = None,
+        print_detected_duration: bool = False,
+        duration_override: Optional[float] = None,
+        overwrite: Optional[bool] = None,
+        use_tqdm: bool = False,
+    ):
+        """
+        Create an FFmpeg process with progress reporting.
+
+        Args:
+            command:
+                FFmpeg command as a list of arguments.
+            ffmpeg_log_level:
+                FFmpeg log level enum or case-insensitive string.
+            ffmpeg_log_file:
+                File path or file object (with a file descriptor, e.g. one returned by open())
+                to which FFmpeg's stderr is written.
+            print_detected_duration:
+                Print the duration used for progress calculation.
+            duration_override:
+                Specify input file duration in seconds to use for progress calculation, instead
+                of trying to detect this automatically with FFprobe. This is useful for partial,
+                damaged, streamed, or synthetic inputs whose duration cannot be detected
+                correctly.
+            overwrite:
+                What to do if the output file already exists. True overwrites it, False raises
+                FfmpegCommandError, and None (the default) asks the user. Ignored if the command
+                contains -y or -n.
+            use_tqdm:
+                Use tqdm instead of Rich for the progress bar.
+        """
+        validate_ffmpeg_command(command)
+        log_level = _parse_log_level(ffmpeg_log_level)
+        if overwrite is not None and not isinstance(overwrite, bool):
+            raise TypeError("overwrite must be True, False or None")
+
+        input_flag_pos = command.index("-i")
+        input_file = command[input_flag_pos + 1]
+        self._input_filepath = Path(input_file)
+        # Assumes the last argument is the output.
+        self._output_filepath = Path(command[-1])
+
+        if ffmpeg_log_file is None:
+            self._ffmpeg_log_file = _default_log_file(command, input_flag_pos)
+        elif isinstance(ffmpeg_log_file, (str, os.PathLike)):
+            self._ffmpeg_log_file = Path(ffmpeg_log_file)
+        else:
+            self._ffmpeg_log_file = ffmpeg_log_file
+
+        if duration_override is not None:
+            input_duration_secs = _parse_duration_override(duration_override)
+        elif is_stdin_input(input_file):
+            # Running FFprobe on standard input would consume data that is meant for FFmpeg.
+            input_duration_secs = None
+        else:
+            input_duration_secs = get_media_duration(input_file)
+
+        # Account for trimming (-ss, -sseof, -t, -to) so the progress bar reflects the
+        # duration of the output rather than the whole input.
+        self._duration_secs = (
+            get_expected_output_duration(command, input_duration_secs)
+            if input_duration_secs is not None
+            else None
+        )
+
+        if duration_override is not None or print_detected_duration:
+            if input_duration_secs is None:
+                print("Could not detect duration. Progress bar may not show time remaining.")
+            else:
+                label = (
+                    "Using duration override"
+                    if duration_override is not None
+                    else "Detected duration"
+                )
+                print(f"{label}: {input_duration_secs:.2f} seconds")
+                if self._duration_secs != input_duration_secs:
+                    print(
+                        "Expected output duration after trimming: "
+                        f"{self._duration_secs:.2f} seconds"
+                    )
+
+        self._ffmpeg_command = [
+            command[0],
+            "-hide_banner",
+            "-loglevel",
+            log_level.value,
+            "-progress",
+            "pipe:1",
+            "-nostats",
+            *command[1:],
+        ]
+
+        user_args = command[1:]
+        if "-y" not in user_args and self._output_filepath.exists():
+            if "-n" in user_args or overwrite is False:
+                raise FfmpegCommandError(
+                    f"Output file {self._output_filepath} already exists and overwriting is "
+                    "disabled."
+                )
+            if overwrite is None:
+                if is_stdin_input(input_file):
+                    # Prompting would read from standard input, which carries FFmpeg's input.
+                    raise FfmpegCommandError(
+                        f"Output file {self._output_filepath} already exists. Pass "
+                        "overwrite=True or add -y to the command to overwrite it."
+                    )
+                self._ask_to_overwrite()
+            self._ffmpeg_command.insert(1, "-y")
+
+        self._process: Optional[subprocess.Popen] = None
+        self.use_tqdm: bool = use_tqdm
+
+    def _ask_to_overwrite(self) -> None:
+        """Raises an FfmpegProcessError unless the user agrees to overwrite the output file."""
+        try:
+            answer = input(
+                f"Output file {self._output_filepath} already exists. Overwrite? [y/N]: "
+            )
+        except KeyboardInterrupt as e:
+            raise FfmpegProcessInterruptedError(
+                "[KeyboardInterrupt] FFmpeg process cancelled during overwrite prompt."
+            ) from e
+        except EOFError as e:
+            raise FfmpegProcessInterruptedError(
+                "Input error (EOF) during overwrite prompt. FFmpeg process cancelled."
+            ) from e
+
+        if answer.strip().lower() != "y":
+            raise FfmpegProcessUserCancelledError(
+                "FFmpeg process cancelled. Output file exists and overwrite declined."
+            )
+
+    def run(self, print_command: bool = False) -> None:
+        if print_command:
+            print(f"Executing: {shlex.join(self._ffmpeg_command)}")
+
+        # Run FFmpeg in its own process group, so that pressing Ctrl+C does not send the signal
+        # to FFmpeg directly, and terminating the group does not terminate this Python process.
+        if os.name == "nt":
+            new_process_group = {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+        else:
+            new_process_group = {"start_new_session": True}
+
+        if isinstance(self._ffmpeg_log_file, Path):
+            log_file = open(self._ffmpeg_log_file, "w", encoding="utf-8")
+        else:
+            log_file = contextlib.nullcontext(self._ffmpeg_log_file)
+
+        try:
+            # FFmpeg keeps its own handle to the log file, so it can be closed here.
+            with log_file as stderr:
+                self._process = subprocess.Popen(
+                    self._ffmpeg_command,
+                    stdout=subprocess.PIPE,
+                    stderr=stderr,
+                    **new_process_group,
+                )
+        except Exception as e:
+            raise FfmpegProcessError(f"Error starting FFmpeg process: {e}") from e
+
+        filename = truncate_filename(self._input_filepath.name, _MAX_FILENAME_LENGTH)
+        try:
+            with self._process.stdout:
+                if not self._duration_secs:
+                    print(f"Processing '{filename}'...")
+                    # FFmpeg's progress output must be read even though it is not displayed:
+                    # once the pipe's buffer is full, FFmpeg blocks and never exits.
+                    for _ in self._process.stdout:
+                        pass
+                elif self.use_tqdm:
+                    show_tqdm_progress(self._process, filename, self._duration_secs)
+                else:
+                    show_rich_progress(self._process, filename, self._duration_secs)
+                returncode = self._process.wait()
+        except KeyboardInterrupt as e:
+            terminate_ffmpeg_process(self._process)
+            raise FfmpegProcessInterruptedError(
+                "[KeyboardInterrupt] FFmpeg process cancelled."
+            ) from e
+
+        if returncode != 0:
+            raise FfmpegProcessError(build_failure_message(self._ffmpeg_log_file))
+        if not self._duration_secs:
+            print(f"✓ Processed '{filename}'")

better_ffmpeg_progress-6.0.1/better_ffmpeg_progress/progress_bars.py

@@ -0,0 +1,98 @@
+import os
+import subprocess
+from typing import Optional
+
+from rich.progress import (
+    BarColumn,
+    Progress,
+    TaskProgressColumn,
+    TextColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+from tqdm import tqdm
+
+from .utils import estimate_final_size_mb, read_progress
+
+
+def _format_size(current_size_mb: float, estimated_size_mb: Optional[float]) -> str:
+    """
+    Returns e.g. "(3.25 MB / ~14.33 MB)", "(3.25 MB)" while there is no estimate yet, or ""
+    if FFmpeg has not reported a size (e.g. at the start, or when the output is "-f null").
+    """
+    # Also hide sizes that would display as "0.00 MB", such as a container header of a few bytes.
+    if round(current_size_mb, 2) <= 0:
+        return ""
+    if estimated_size_mb is None:
+        return f"({current_size_mb:.2f} MB)"
+    return f"({current_size_mb:.2f} MB / ~{estimated_size_mb:.2f} MB)"
+
+
+def _with_size(text: str, current_size_mb: float, estimated_size_mb: Optional[float]) -> str:
+    size = _format_size(current_size_mb, estimated_size_mb)
+    return f"{text} {size}" if size else text
+
+
+def show_rich_progress(process: subprocess.Popen, filename: str, duration_secs: float) -> None:
+    """Shows a Rich progress bar until FFmpeg exits."""
+    description = f"Processing '{filename}'"
+    progress_bar = Progress(
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TimeElapsedColumn(),
+        TimeRemainingColumn(compact=True),
+        refresh_per_second=2,
+    )
+
+    with progress_bar:
+        task_id = progress_bar.add_task(description, total=duration_secs)
+        size_mb = 0.0
+
+        for secs, size_mb in read_progress(process.stdout, duration_secs):
+            estimated_size_mb = estimate_final_size_mb(size_mb, secs, duration_secs)
+            progress_bar.update(
+                task_id,
+                completed=secs,
+                description=_with_size(description, size_mb, estimated_size_mb),
+            )
+
+        if process.wait() == 0:
+            # Remove the time columns, which are no longer useful.
+            progress_bar.columns = progress_bar.columns[:3]
+            progress_bar.update(
+                task_id,
+                completed=duration_secs,
+                description=_with_size(f"✓ Processed '{filename}'", size_mb, None),
+            )
+
+
+def show_tqdm_progress(process: subprocess.Popen, filename: str, duration_secs: float) -> None:
+    """Shows a tqdm progress bar until FFmpeg exits."""
+    try:
+        terminal_width = os.get_terminal_size().columns
+    except OSError:
+        terminal_width = 80
+
+    progress_bar = tqdm(
+        mininterval=0.5,
+        total=duration_secs,
+        desc=f"Processing '{filename}'",
+        ncols=80,
+        dynamic_ncols=terminal_width < 80,
+        bar_format="{desc} {bar} {percentage:.1f}% [{elapsed}<{remaining}, {rate_fmt}{postfix}]",
+    )
+    size_mb = 0.0
+
+    with progress_bar:
+        for secs, size_mb in read_progress(process.stdout, duration_secs):
+            progress_bar.n = secs
+            # set_postfix_str refreshes the bar.
+            progress_bar.set_postfix_str(
+                _format_size(size_mb, estimate_final_size_mb(size_mb, secs, duration_secs))
+            )
+
+        if process.wait() == 0:
+            progress_bar.n = duration_secs
+            progress_bar.set_description(f"✓ Processed '{filename}'")
+            progress_bar.set_postfix_str(_format_size(size_mb, None))

better_ffmpeg_progress-6.0.1/better_ffmpeg_progress/terminate_process.py

@@ -0,0 +1,44 @@
+import os
+import signal
+import subprocess
+
+from .exceptions import FfmpegProcessError
+
+_TIMEOUT_SECS = 2
+
+
+def _signal_process_group(process: subprocess.Popen, sig: int) -> None:
+    # FFmpeg is started in its own process group (see FfmpegProcess.run), whose ID is FFmpeg's PID.
+    # Signalling the group also stops any processes that FFmpeg started.
+    try:
+        os.killpg(process.pid, sig)
+    except ProcessLookupError:
+        pass  # The process has already exited.
+
+
+def terminate_ffmpeg_process(process: subprocess.Popen) -> None:
+    """
+    Stops the FFmpeg process. Raises FfmpegProcessError if it is still running afterwards.
+    """
+    if process.poll() is not None:
+        return
+
+    print("[KeyboardInterrupt] Terminating the FFmpeg process...")
+
+    if os.name == "nt":
+        # On Windows, terminate() stops the process immediately.
+        process.terminate()
+    else:
+        # Ask FFmpeg to exit, and force it to if it has not done so in time.
+        _signal_process_group(process, signal.SIGTERM)
+        try:
+            process.wait(timeout=_TIMEOUT_SECS)
+        except subprocess.TimeoutExpired:
+            _signal_process_group(process, signal.SIGKILL)
+
+    try:
+        process.wait(timeout=_TIMEOUT_SECS)
+    except subprocess.TimeoutExpired:
+        raise FfmpegProcessError(
+            f"FFmpeg process (PID: {process.pid}) could not be terminated."
+        ) from None