Metadata-Version: 2.4
Name: cs-ffmpegutils
Version: 20260531
Summary: Convenience facilities for using FFmpeg (ffmpeg.org), with invocation via `ffmpeg-python`.
Keywords: python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.dockerutils>=20260531
Requires-Dist: cs.fstags>=20260531
Requires-Dist: cs.lex>=20260526
Requires-Dist: cs.logutils>=20250323
Requires-Dist: cs.mappings>=20260531
Requires-Dist: cs.pfx>=20250914
Requires-Dist: cs.psutils>=20260531
Requires-Dist: cs.tagset>=20260531
Requires-Dist: ffmpeg-python
Requires-Dist: typeguard
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/ffmpegutils.py

Convenience facilities for using FFmpeg (ffmpeg.org),
with invocation via `ffmpeg-python`.

*Latest release 20260531*:
FFMPEG_DOCKER_IMAGE_DEFAULT=docker.io/linuxserver/ffmpeg, adjust for cs.dockerutils changes.

Short summary:
* `ConversionSource`: ConversionSource(src, srcfmt, start_s, end_s).
* `convert`: Transcode video to `dstpath` in FFMPEG compatible `dstfmt`.
* `ffmpeg_docker`: Invoke `ffmpeg` using docker.
* `FFmpegSource`: A representation of an `ffmpeg` input source.
* `ffprobe`: Run `ffprobe -print_format json` on `input_file`, return format, stream, program and chapter information as an `AttrableMapping` (a `dict` subclass).
* `main_ffmpeg_docker`: The `ffm[peg-docker` command line implementation.
* `MetaData`: Object containing fields which may be supplied to ffmpeg's -metadata option.

Module contents:
- <a name="ConversionSource"></a>`class ConversionSource(builtins.tuple)`: ConversionSource(src, srcfmt, start_s, end_s)

*`ConversionSource.__replace__(self, /, **kwds)`*:
Return a new ConversionSource object replacing specified fields with new values

*`ConversionSource.end_s`*:
Alias for field number 3

*`ConversionSource.src`*:
Alias for field number 0

*`ConversionSource.srcfmt`*:
Alias for field number 1

*`ConversionSource.start_s`*:
Alias for field number 2
- <a name="convert"></a>`convert(*srcs, dstpath: str, doit=True, dstfmt=None, ffmpeg_exe=None, fstags: Optional[cs.fstags.FSTags] = <function <lambda> at 0x10e323a60>, conversions=None, metadata: Optional[dict] = None, timespans=(), overwrite=False, acodec=None, vcodec=None, extra_opts=None) -> List[str]`: Transcode video to `dstpath` in FFMPEG compatible `dstfmt`.

  Parameters:
  * `srcs`: the positional parameters specify source files
  * `doit`: optional flag (default `True`); do not procude the output if false
  * `dstfmt`: optional destination format
  * `ffmpeg_exe`: optional `ffmepg` executable
  * `conversions`: optional format conversions
  * `metadata`: an optional mapping of metadata values
  * `timespans`: optional timespans to select form the sources
  * `overwrite`: optional flag (default `False`); if true allow overwriting an existing destination file
  * `acodec`: optional target audio codec
  * `vcodec`: optional target video codec
  * `extra_opts`: an optional mapping of additional ffmpeg output options
- <a name="ffmpeg_docker"></a>`ffmpeg_docker(*ffmpeg_args: Iterable[str], docker_run_opts: Union[List[str], Mapping, NoneType] = None, doit: Optional[bool] = None, quiet: Optional[bool] = None, ffmpeg_exe: Optional[str] = None, image: Optional[str] = None, output_hostdir: Optional[str] = None) -> Optional[subprocess.CompletedProcess]`: Invoke `ffmpeg` using docker.
- <a name="FFmpegSource"></a>`class FFmpegSource`: A representation of an `ffmpeg` input source.

*`FFmpegSource.add_as_input(self, ff)`*:
Add as an input to `ff`.
Return `None` if `self.source` is a pathname,
otherwise return the file descriptor of the data source.

Note: because we rely on `ff.input('pipe:')` for nonpathnames,
you can only use a nonpathname `FFmpegSource` for one of the inputs.
This is not checked.

*`FFmpegSource.promote(source)`*:
Promote `source` to an `FFmpegSource`.
- <a name="ffprobe"></a>`ffprobe(input_file, *, doit=True, ffprobe_exe='ffprobe', quiet=False)`: Run `ffprobe -print_format json` on `input_file`,
  return format, stream, program and chapter information
  as an `AttrableMapping` (a `dict` subclass).
- <a name="main_ffmpeg_docker"></a>`main_ffmpeg_docker(argv=None)`: The `ffm[peg-docker` command line implementation.
- <a name="MetaData"></a>`class MetaData(cs.tagset.TagSet)`: Object containing fields which may be supplied to ffmpeg's -metadata option.

*`MetaData.__init__(self, format, **kw)`*:
pylint: disable=redefined-builtin

*`MetaData.options(self)`*:
Compute the FFmpeg -metadata option strings and return as a list.

# Release Log



*Release 20260531*:
FFMPEG_DOCKER_IMAGE_DEFAULT=docker.io/linuxserver/ffmpeg, adjust for cs.dockerutils changes.

*Release 20241122*:
Honour the $FFMPEG_DOCKER_IMAGE environment variable.

*Release 20240519*:
ffmpeg_docker: set DockerRun.output_hostdir from the output file dirname.

*Release 20240316.1*:
DISTINFO fix.

*Release 20240316*:
Fixed release upload artifacts.

*Release 20240201*:
* New $FFMPEG_EXE envvar.
* convert: use $FFMPEG_EXE, return the ffmpeg argv.
* convert: include the media type in DEFAULT_CONVERSIONS, refactor the choice of codec conversion.
* convert: supply dummy results if doit is false - could do with some finesse.
* ffmpeg_docker: use DockerRun.{add_input,add_output}.
* New main_ffmpeg_docker to support the ffmpeg-docker command, add ffmpeg-docker to DISTINFO scripts.

*Release 20231202*:
Initial PyPI release.
