better-ffmpeg-progress 5.4.1__tar.gz → 6.0.0__tar.gz

{better_ffmpeg_progress-5.4.1/better_ffmpeg_progress.egg-info → better_ffmpeg_progress-6.0.0}/PKG-INFO

@@ -1,21 +1,24 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: better-ffmpeg-progress
-Version: 5.4.1
+Version: 6.0.0
 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 +68,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 +139,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
+pip install --upgrade build twine pkginfo
+```
+
+Then, for each release:
+```bash
+rm -rf dist
+```
+```bash
+python -m build
+```
+```bash
+twine check dist/*
+```
+```bash
+twine upload dist/*
+```

better_ffmpeg_progress-5.4.1/PKG-INFO → better_ffmpeg_progress-6.0.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.1
-Name: better-ffmpeg-progress
-Version: 5.4.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
-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
+pip install --upgrade build twine pkginfo
+```
+
+Then, for each release:
+```bash
+rm -rf dist
+```
+```bash
+python -m build
+```
+```bash
+twine check dist/*
+```
+```bash
+twine upload dist/*
+```

{better_ffmpeg_progress-5.4.1 → better_ffmpeg_progress-6.0.0}/better_ffmpeg_progress/__init__.py

@@ -1,3 +1,5 @@
+__version__ = "6.0.0"
+
 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-5.4.1 → better_ffmpeg_progress-6.0.0}/better_ffmpeg_progress/better_ffmpeg_progress.py

@@ -4,8 +4,7 @@ import re
 import shlex
 from pathlib import Path
 import subprocess
-from sys import exit
-from typing import List, Optional, Union
+from typing import IO, Any, List, Optional, Union
 
 from .enums import FfmpegLogLevel
 from .exceptions import (
@@ -19,11 +18,19 @@ from .utils import (
     get_media_duration,
     get_expected_output_duration,
     is_lavfi_input,
+    is_local_file_input,
+    is_stdin_input,
 )
 from .terminate_process import terminate_ffmpeg_process
 from .progress_bars import use_rich, use_tqdm
 
 _FFMPEG_OVERWRITE_FLAG = "-y"
+_FFMPEG_NO_OVERWRITE_FLAG = "-n"
+
+
+def _safe_filename(name: str) -> str:
+    """Replaces characters that are not valid in filenames on every OS."""
+    return re.sub(r"[^\w.,-]", "_", name)
 
 
 class FfmpegProcess:
@@ -59,9 +66,11 @@ class FfmpegProcess:
         self,
         command: List[str],
         ffmpeg_log_level: Optional[Union[FfmpegLogLevel, str]] = None,
-        ffmpeg_log_file: Optional[Union[str, os.PathLike]] = 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.
@@ -72,12 +81,19 @@ class FfmpegProcess:
             ffmpeg_log_level:
                 FFmpeg log level enum or case-insensitive string.
             ffmpeg_log_file:
-                File path or file-like object used for FFmpeg stderr.
+                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)
 
@@ -118,10 +134,17 @@ class FfmpegProcess:
                 # 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 = re.sub(r"[^\w.,-]", "_", input_file_path_str.split("=", 1)[0])
+                source_name = _safe_filename(input_file_path_str.split("=", 1)[0])
                 self._ffmpeg_log_file = Path(f"lavfi_{source_name}_ffmpeg_log.txt")
-            else:
+            elif input_file_path_str == "-":
+                self._ffmpeg_log_file = Path("stdin_ffmpeg_log.txt")
+            elif is_local_file_input(command, input_file_index):
                 self._ffmpeg_log_file = Path(f"{self._input_filepath.name}_ffmpeg_log.txt")
+            else:
+                # URLs and other protocols (e.g. "pipe:0") can contain characters that are not
+                # valid in filenames, such as ":" or "?".
+                name = self._input_filepath.name or input_file_path_str
+                self._ffmpeg_log_file = Path(f"{_safe_filename(name)}_ffmpeg_log.txt")
         elif isinstance(ffmpeg_log_file, (str, os.PathLike)):
             self._ffmpeg_log_file = Path(ffmpeg_log_file)
         else:
@@ -142,6 +165,9 @@ class FfmpegProcess:
                 raise ValueError("duration_override must be a finite number greater than 0")
 
             self._duration_secs = duration_value
+        elif is_stdin_input(input_file_path_str):
+            # Running FFprobe on standard input would consume data that is meant for FFmpeg.
+            self._duration_secs = None
         else:
             self._duration_secs = get_media_duration(input_file_path_str)
 
@@ -178,13 +204,29 @@ class FfmpegProcess:
         ]
         self._ffmpeg_command.extend(command[1:])
 
-        is_overwrite_in_user_command = any(arg == _FFMPEG_OVERWRITE_FLAG for arg in command[1:])
+        if overwrite is not None and not isinstance(overwrite, bool):
+            raise TypeError("overwrite must be True, False or None")
 
-        if self._output_filepath.exists() and not is_overwrite_in_user_command:
-            self._handle_overwrite_prompt()
+        user_args = command[1:]
+        if _FFMPEG_OVERWRITE_FLAG not in user_args and self._output_filepath.exists():
+            if _FFMPEG_NO_OVERWRITE_FLAG in user_args or overwrite is False:
+                raise FfmpegCommandError(
+                    f"Output file {self._output_filepath} already exists and overwriting is "
+                    "disabled."
+                )
+            elif overwrite:
+                self._ffmpeg_command.insert(1, _FFMPEG_OVERWRITE_FLAG)
+            elif is_stdin_input(input_file_path_str):
+                # 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."
+                )
+            else:
+                self._handle_overwrite_prompt()
 
         self._process: Optional[subprocess.Popen] = None
-        self.use_tqdm: bool = False
+        self.use_tqdm: bool = use_tqdm
 
     def run(
         self,
@@ -193,12 +235,15 @@ class FfmpegProcess:
         if print_command:
             print(f"Executing: {shlex.join(self._ffmpeg_command)}")
 
-        try:
-            creationflags = 0
-            # Windows
-            if os.name == "nt":
-                creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+        # Run FFmpeg in its own process group, so that terminating the group on
+        # KeyboardInterrupt does not also terminate this Python process.
+        popen_kwargs = {}
+        if os.name == "nt":
+            popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            popen_kwargs["start_new_session"] = True
 
+        try:
             if isinstance(self._ffmpeg_log_file, Path):
                 with open(
                     self._ffmpeg_log_file,
@@ -209,14 +254,14 @@ class FfmpegProcess:
                         self._ffmpeg_command,
                         stdout=subprocess.PIPE,
                         stderr=f,
-                        creationflags=creationflags,
+                        **popen_kwargs,
                     )
             else:
                 self._process = subprocess.Popen(
                     self._ffmpeg_command,
                     stdout=subprocess.PIPE,
                     stderr=self._ffmpeg_log_file,
-                    creationflags=creationflags,
+                    **popen_kwargs,
                 )
         except Exception as e:
             raise FfmpegProcessError(f"Error starting FFmpeg process: {e}") from e
@@ -226,14 +271,11 @@ class FfmpegProcess:
                 use_tqdm(self, self._process)
             else:
                 use_rich(self, self._process)
-        except KeyboardInterrupt:
-            self._terminate()
+        except KeyboardInterrupt as e:
+            terminate_ffmpeg_process(self._process)
+            raise FfmpegProcessInterruptedError(
+                "[KeyboardInterrupt] FFmpeg process cancelled."
+            ) from e
         finally:
             if self._process and self._process.stdout:
                 self._process.stdout.close()
-
-    def _terminate(self):
-        if self._process:
-            terminate_ffmpeg_process(self._process)
-        else:
-            exit()

{better_ffmpeg_progress-5.4.1 → better_ffmpeg_progress-6.0.0}/better_ffmpeg_progress/progress_bars.py

@@ -13,6 +13,7 @@ from rich.progress import (
 from tqdm import tqdm
 
 from .utils import (
+    build_failure_message,
     estimate_final_size_mb,
     parse_ffmpeg_progress_line,
     parse_ffmpeg_total_size_line,
@@ -27,8 +28,31 @@ _MAX_FILENAME_LENGTH = 60
 
 
 def _format_size(current_size_mb: float, estimated_size_mb: Optional[float]) -> str:
-    estimate = f"~{estimated_size_mb:.2f} MB" if estimated_size_mb is not None else "~? MB"
-    return f"({current_size_mb:.2f} MB / {estimate})"
+    """
+    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 _drain(process: subprocess.Popen) -> None:
+    """
+    Reads FFmpeg's progress output until it ends. FFmpeg writes it to a pipe, so it must be read
+    even when it is not displayed: once the pipe's buffer is full, FFmpeg blocks and never exits.
+    """
+    if process.stdout is not None:
+        for _ in process.stdout:
+            pass
 
 
 def use_rich(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen) -> None:
@@ -75,11 +99,13 @@ def use_rich(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen
                     update_progress(
                         task_id,
                         completed=progress_val_secs,
-                        description=f"Processing {input_filename} "
-                        f"{_format_size(current_size_mb, estimated_size_mb)}",
+                        description=_with_size(
+                            f"Processing {input_filename}", current_size_mb, estimated_size_mb
+                        ),
                     )
         else:
             print(f"Processing '{input_filename}'...")
+            _drain(process)
 
         process.wait()
 
@@ -93,13 +119,15 @@ def use_rich(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen
                 )
                 update_progress(
                     task_id,
-                    description=f"✓ Processed '{input_filename}' ({current_size_mb:.2f} MB)",
+                    description=_with_size(
+                        f"✓ Processed '{input_filename}'", current_size_mb, None
+                    ),
                 )
         else:
             if task_id is not None:
                 progress_bar.update(task_id)
 
-            raise FfmpegProcessError(f"FFmpeg process failed. Check '{log_file}' for details.")
+            raise FfmpegProcessError(build_failure_message(log_file))
 
 
 def use_tqdm(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen) -> None:
@@ -145,6 +173,7 @@ def use_tqdm(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen
                 progress_bar.set_postfix_str(_format_size(current_size_mb, estimated_size_mb))
     else:
         print(f"Processing '{input_filename}'...")
+        _drain(process)
 
     process.wait()
 
@@ -152,7 +181,7 @@ def use_tqdm(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen
         if progress_bar:
             progress_bar.n = duration_secs
             progress_bar.set_description(f"✓ Processed '{input_filename}'")
-            progress_bar.set_postfix_str(f"{current_size_mb:.2f} MB")
+            progress_bar.set_postfix_str(_format_size(current_size_mb, None))
             progress_bar.close()
         else:
             print(f"✓ Processed '{input_filename}'")
@@ -160,4 +189,4 @@ def use_tqdm(ffmpeg_process_instance: "FfmpegProcess", process: subprocess.Popen
         if progress_bar:
             progress_bar.close()
 
-        raise FfmpegProcessError(f"FFmpeg process failed. Check '{log_file}' for details.")
+        raise FfmpegProcessError(build_failure_message(log_file))