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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-ffmpeg-progress
-Version: 6.0.0
+Version: 7.0.0
 Summary: Run FFmpeg & see percentage progress + ETA.
 Author-email: "GitHub.com/CrypticSignal" <theaudiophile@outlook.com>
 License-Expression: MIT
@@ -8,16 +8,28 @@ 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: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video :: Conversion
 Classifier: Operating System :: OS Independent
 Classifier: Typing :: Typed
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psutil
 Requires-Dist: rich
-Requires-Dist: tqdm
+Provides-Extra: tqdm
+Requires-Dist: tqdm; extra == "tqdm"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
+Requires-Dist: tqdm; extra == "test"
+Provides-Extra: dev
+Requires-Dist: better-ffmpeg-progress[test]; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: types-tqdm; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
@@ -141,28 +153,78 @@ An instance of `FfmpegProcess` accepts the following optional arguments:
 * `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`.
+* `quiet` — Do not show a progress bar or status messages. Default: `False`.
+* `progress_callback` — A function to call each time FFmpeg reports its progress. See [Progress callback](#progress-callback). Default: `None`.
+* `delete_log_on_success` — Delete the FFmpeg log file if FFmpeg succeeds. Default: `False`.
+
+Creating an `FfmpegProcess` only validates the command. FFprobe is run, and you are asked whether to overwrite an existing output file, when `run()` is called.
 
 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 passing `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`. tqdm is an optional dependency, installed with:
+```bash
+pip install "better-ffmpeg-progress[tqdm]" --upgrade
+```
 ```python
 process = FfmpegProcess(command, use_tqdm=True)
 process.run()
 ```
+
+## Progress callback
+To show progress in your own UI (e.g. a GUI or a web app), pass a function as `progress_callback`. It is called with the number of seconds processed, the expected output duration in seconds (`None` if it is unknown) and the current output size in MB. Combine it with `quiet=True` to hide the progress bar:
+```python
+def on_progress(secs: float, duration: float | None, size_mb: float) -> None:
+    if duration:
+        print(f"{secs / duration:.0%}")
+
+FfmpegProcess(command, quiet=True, progress_callback=on_progress).run()
+```
+If the callback raises an exception, FFmpeg is stopped and the exception is propagated by `run()`.
+
+## Errors
+All exceptions raised by the package are subclasses of `FfmpegProcessError`, which has these attributes:
+* `returncode` — FFmpeg's exit code, or `None` if FFmpeg was not started or had not exited.
+* `log_file` — The path or file object that FFmpeg's log was written to.
+
+Pressing Ctrl+C raises `FfmpegProcessInterruptedError`. FFmpeg is first asked to stop the way pressing `q` does, so it can finish writing the output file, e.g. an MP4 file stays playable. If it does not stop within 5 seconds, it is terminated.
+
+## Logging
+Warnings, such as when the input duration cannot be detected, are logged with the `logging` module using the `better_ffmpeg_progress` logger. Without any logging configuration, Python prints them to standard error. To hide them:
+```python
+import logging
+
+logging.getLogger("better_ffmpeg_progress").setLevel(logging.ERROR)
+```
+
+## Writing to standard output
+On Linux and macOS, the output can be written to standard output, e.g. `-f mpegts -`, to pipe it to another program. The progress bar is then shown on standard error. This is not supported on Windows, where FFmpeg's progress is read from its standard output.
+
+## Duration detection
+FFprobe is looked for next to the FFmpeg executable first (e.g. `/opt/ffmpeg/bin/ffprobe` for `/opt/ffmpeg/bin/ffmpeg`), then in `PATH`. If it does not finish within 30 seconds, e.g. for an unresponsive URL, the duration is treated as unknown.
 ## 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):
+Install the package in editable mode with the development dependencies, then run the tests (FFmpeg and FFprobe must be installed):
 ```bash
-pip install -e ".[test]"
+pip install -e ".[dev]"
 ```
 ```bash
 pytest
 ```
+Lint, format and type-check the code like CI does:
+```bash
+ruff check .
+```
+```bash
+ruff format --check better_ffmpeg_progress tests test.py
+```
+```bash
+mypy
+```
 `test.py` is a standalone example that encodes a test pattern and shows the progress bar.
 
 ## Publishing
@@ -170,7 +232,7 @@ Update `__version__` in `better_ffmpeg_progress/__init__.py` and add an entry to
 
 One-time setup:
 ```bash
-pip install --upgrade build twine pkginfo
+python -m pip install --upgrade build twine pkginfo
 ```
 
 Then, for each release:
@@ -181,8 +243,8 @@ rm -rf dist
 python -m build
 ```
 ```bash
-twine check dist/*
+python -m twine check dist/*
 ```
 ```bash
-twine upload dist/*
+python -m twine upload dist/*
 ```

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

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: better-ffmpeg-progress
-Version: 6.0.0
-Summary: Run FFmpeg & see percentage progress + ETA.
-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: Operating System :: OS Independent
-Classifier: Typing :: Typed
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: psutil
-Requires-Dist: rich
-Requires-Dist: tqdm
-Provides-Extra: test
-Requires-Dist: pytest; extra == "test"
-Dynamic: license-file
-
 <div align="center">
 
 # Better FFmpeg Progress
@@ -141,28 +119,78 @@ An instance of `FfmpegProcess` accepts the following optional arguments:
 * `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`.
+* `quiet` — Do not show a progress bar or status messages. Default: `False`.
+* `progress_callback` — A function to call each time FFmpeg reports its progress. See [Progress callback](#progress-callback). Default: `None`.
+* `delete_log_on_success` — Delete the FFmpeg log file if FFmpeg succeeds. Default: `False`.
+
+Creating an `FfmpegProcess` only validates the command. FFprobe is run, and you are asked whether to overwrite an existing output file, when `run()` is called.
 
 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 passing `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`. tqdm is an optional dependency, installed with:
+```bash
+pip install "better-ffmpeg-progress[tqdm]" --upgrade
+```
 ```python
 process = FfmpegProcess(command, use_tqdm=True)
 process.run()
 ```
+
+## Progress callback
+To show progress in your own UI (e.g. a GUI or a web app), pass a function as `progress_callback`. It is called with the number of seconds processed, the expected output duration in seconds (`None` if it is unknown) and the current output size in MB. Combine it with `quiet=True` to hide the progress bar:
+```python
+def on_progress(secs: float, duration: float | None, size_mb: float) -> None:
+    if duration:
+        print(f"{secs / duration:.0%}")
+
+FfmpegProcess(command, quiet=True, progress_callback=on_progress).run()
+```
+If the callback raises an exception, FFmpeg is stopped and the exception is propagated by `run()`.
+
+## Errors
+All exceptions raised by the package are subclasses of `FfmpegProcessError`, which has these attributes:
+* `returncode` — FFmpeg's exit code, or `None` if FFmpeg was not started or had not exited.
+* `log_file` — The path or file object that FFmpeg's log was written to.
+
+Pressing Ctrl+C raises `FfmpegProcessInterruptedError`. FFmpeg is first asked to stop the way pressing `q` does, so it can finish writing the output file, e.g. an MP4 file stays playable. If it does not stop within 5 seconds, it is terminated.
+
+## Logging
+Warnings, such as when the input duration cannot be detected, are logged with the `logging` module using the `better_ffmpeg_progress` logger. Without any logging configuration, Python prints them to standard error. To hide them:
+```python
+import logging
+
+logging.getLogger("better_ffmpeg_progress").setLevel(logging.ERROR)
+```
+
+## Writing to standard output
+On Linux and macOS, the output can be written to standard output, e.g. `-f mpegts -`, to pipe it to another program. The progress bar is then shown on standard error. This is not supported on Windows, where FFmpeg's progress is read from its standard output.
+
+## Duration detection
+FFprobe is looked for next to the FFmpeg executable first (e.g. `/opt/ffmpeg/bin/ffprobe` for `/opt/ffmpeg/bin/ffmpeg`), then in `PATH`. If it does not finish within 30 seconds, e.g. for an unresponsive URL, the duration is treated as unknown.
 ## 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):
+Install the package in editable mode with the development dependencies, then run the tests (FFmpeg and FFprobe must be installed):
 ```bash
-pip install -e ".[test]"
+pip install -e ".[dev]"
 ```
 ```bash
 pytest
 ```
+Lint, format and type-check the code like CI does:
+```bash
+ruff check .
+```
+```bash
+ruff format --check better_ffmpeg_progress tests test.py
+```
+```bash
+mypy
+```
 `test.py` is a standalone example that encodes a test pattern and shows the progress bar.
 
 ## Publishing
@@ -170,7 +198,7 @@ Update `__version__` in `better_ffmpeg_progress/__init__.py` and add an entry to
 
 One-time setup:
 ```bash
-pip install --upgrade build twine pkginfo
+python -m pip install --upgrade build twine pkginfo
 ```
 
 Then, for each release:
@@ -181,8 +209,8 @@ rm -rf dist
 python -m build
 ```
 ```bash
-twine check dist/*
+python -m twine check dist/*
 ```
 ```bash
-twine upload dist/*
+python -m twine upload dist/*
 ```

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

@@ -1,12 +1,12 @@
-__version__ = "6.0.0"
+__version__ = "7.0.0"
 
 from .better_ffmpeg_progress import FfmpegProcess
 from .enums import FfmpegLogLevel
 from .exceptions import (
-    FfmpegProcessError,
     FfmpegCommandError,
-    FfmpegProcessUserCancelledError,
+    FfmpegProcessError,
     FfmpegProcessInterruptedError,
+    FfmpegProcessUserCancelledError,
 )
 
 __all__ = [