Reference¶
pyffstream.ffmpeg¶
Helper functions for interacting with ffmpeg.
Functions include mimicking number/duration processing, probing files with ffprobe, and a utility class to deal with filters.
- pyffstream.ffmpeg.ff_bin¶
A tuple that is the recommended way to specify the path to ffmpeg utilities. Can be overridden.
- Type:
- class pyffstream.ffmpeg.FFBanner(ffversion, ffconfig, versions)¶
-
- versions: dict[str, pyffstream.ffmpeg.FFVersion]¶
Alias for field number 2
- class pyffstream.ffmpeg.FFBin(ffmpeg='ffmpeg', ffprobe='ffprobe', env=None)¶
An instance of a path to an ffmpeg binary.
Provides various helper properties to get information about the capabilities of the ffmpeg binary. Note that just because something was compiled into the binary it doesn’t mean it’s usable at runtime. This is the case for hardware support (e.g. nvidia) in particular.
- property ffversion: str¶
String representing ffmpeg release version.
Note this might not always be sensible to use for simple comparison, for example in the case of versions compiled from git.
- Return type:
- make_playlist(pathlist, directory, idxs=(0, 0), deep_probe=False, name='streamplaylist.txt')¶
Construct ffconcat playlist from path list.
Paths created are absolute, and the files are probed in parallel if needed to determine the duration.
- Parameters:
- Return type:
- Returns:
Path to created ffconcat playlist.
- probe_json(entries, fileargs, streamtype=None, deep_probe=False, extraargs=None)¶
Probes a media file with ffprobe and returns results.
Generic function for probing a media file for information using ffmpeg’s ffprobe utility and returning its JSON.
- Parameters:
entries (str) – Argument passed to the
-show_entries
flag in ffprobe.fileargs (str | Iterable[str] | None) – String of the file you want to analyze. If additional args are needed to specify the input, accepts a list of args to pass on.
streamtype (str | None) – Optional; Argument to pass on to the
-select_streams
flag in ffprobe. Argument not passed if None.deep_probe (bool) – Optional; Pass extra arguments to ffprobe in order to probe the file more deeply. This is useful for containers that can’t be lightly inspected.
extraargs (str | Iterable[str] | None) – Optional; A list of additional arguments to past to ffprobe during runtime. Can be used for example to request
-sexagesimal
formatting of duration fields.
- Returns:
The query failed or returned “unknown” or “N/A”.
deserialized JSON: For raw probetype, the JSON returned after deserialization.
- Return type:
None
- probe_val(entry, fileargs, streamtype=None, probetype=ProbeType.STREAM, deep_probe=False, extraargs=None)¶
Wrapper for probe_vals to probe a single val.
- probe_vals(entries, fileargs, streamtype=None, probetype=ProbeType.STREAM, deep_probe=False, extraargs=None)¶
Probes a media file with ffprobe and returns results.
Generic function for probing a media file for information using ffmpeg’s ffprobe utility. Returns individual values.
- Parameters:
entries (Iterable[str]) – List of arguments passed to the
-show_entries
flag in ffprobe. If a non-raw streamtype is specified, then the argument may be the type field you want to query, for example the duration.fileargs (str | Iterable[str] | None) – String of the file you want to analyze. If additional args are needed to specify the input, accepts a list of args to pass on.
streamtype (str | None) – Optional; Argument to pass on to the
-select_streams
flag in ffprobe. Argument not passed if None.probetype (ProbeType) – Optional; One of STREAM, TAGS, DISPOSITION, FORMAT; query file for metadata of selected probetype and streamtype and return the requested entries of the first matching stream.
deep_probe (bool) – Optional; Pass extra arguments to ffprobe in order to probe the file more deeply. This is useful for containers that can’t be lightly inspected.
extraargs (str | Iterable[str] | None) – Optional; A list of additional arguments to past to ffprobe during runtime. Can be used for example to request
-sexagesimal
formatting of duration fields.
- Returns:
None: The query failed or returned “unknown” or “N/A”.
str: The value of the requested query.
- Return type:
list of values in order of entries iterable containing
- Raises:
ValueError – Invalid probetype was passed.
- property protocols: FFProtocols¶
A FFProtocols of compiled in input/output protocols.
- class pyffstream.ffmpeg.FFEncoders(vencoders, aencoders, sencoders)¶
- class pyffstream.ffmpeg.FFProbeJSON¶
- class pyffstream.ffmpeg.FFProtocols(inputs, outputs)¶
- class pyffstream.ffmpeg.FFVersion(*args)¶
Holds a ffmpeg component version.
- class pyffstream.ffmpeg.Filter(filt, *filtopts, src=None, dst=None)¶
A single ffmpeg filter.
Collects helper methods for constructing and rendering out ffmpeg filter strings for use with the CLI.
- Parameters:
- classmethod complex_join(filterlist, startkey='v', endkey='b', basekey='c')¶
Combine filters in a way compatible with -filter_complex.
- classmethod full_escape(val)¶
Do full escaping needed for complex filter graph in ffmpeg.
https://ffmpeg.org/ffmpeg-filters.html#Notes-on-filtergraph-escaping
- class pyffstream.ffmpeg.ProbeType(value)¶
An enumeration.
- class pyffstream.ffmpeg.Progress¶
Assists in monitoring the progress output of an ffmpeg encode.
- pyffstream.ffmpeg.duration(timestamp)¶
Processes ffmpeg duration string into time in seconds.
- pyffstream.ffmpeg.format_q_tuple(init_tuple, is_stream)¶
Format the entries arg for raw JSON queries to the probefile.
This corresponds to the
-show_entries
flag in ffprobe and can be used generically to format arguments to it.- Parameters:
init_tuple (InitTuple | None) – If querying a stream, a 3-tuple of the stream values, stream tags, and stream dispositions to query ffprobe for. If querying a format, a list of the format values to query. Can be None.
is_stream (bool) – A boolean indicating whether or not init_tuple is a 3-tuple for a stream or a list for a format.
- Return type:
- Returns:
A formatted query for -show_entries in ffprobe. An empty string if init_tuple is None.
- pyffstream.ffmpeg.num(val)¶
Process input into float in a way that mimics ffmpeg.
Method follows ffmpeg’s numerical options. All whitespace is stripped, then valid input is a number followed optionally with an SI prefix that may be appended with an i modifier that indicates the SI prefix is in powers of 1024 instead of 1000. Finally, the number may end in a B indicating it is to be multiplied by 8. The optional ffmpeg utility
ffeval
may be used to validate the output of this function.
pyffstream.encode¶
Classes and functions for ffmpeg encoding.
- class pyffstream.encode.EncType(value)¶
An enumeration.
- class pyffstream.encode.FileOpts(main, subtitle, fpath, sfpath, allpaths)¶
-
- main: MutableSequence[str]¶
Alias for field number 0
- subtitle: MutableSequence[str]¶
Alias for field number 1
- class pyffstream.encode.FilterList¶
Thread-safe class for storing and getting ffmpeg filters.
- get(k, default=None)¶
An implementation of the get method as in dicts.
- Parameters:
k (str) –
default (ffmpeg.Filter | str | None) –
- Return type:
str | None
- class pyffstream.encode.StaticEncodeVars(tempdir, verbosity=0, api_url='', api_key='', samplerate='48000', endpoint='127.0.0.1:9998', target_w='1920', target_h='1080', framerate='24/1', framerate_multiplier=Fraction(1, 1), scale_w='1920', scale_h='1080', bound_w='1920', bound_h='1080', kf_target_sec=5.0, clip_length=None, vencoder=VEncoder(name='libx264', codec='h264', flag_function=<function get_libx264_flags>, presets=['placebo', 'veryslow', 'slower', 'slow', 'medium', 'fast', 'faster', 'veryfast', 'superfast', 'ultrafast'], default_preset='medium', tenbit=False, type=<EncType.SOFTWARE: 1>, multipass=True), aencoder='aac', encode_preset=None, encode_tune=None, realtime=False, vstandard='h264', astandard='aac', include_audio=True, protocol='srt', vbitrate='6M', max_vbitrate='0', rc_mode='cbr', abitrate='256k', chlayout='stereo', start_delay='30', end_pad=True, end_delay='600', timestamp=None, suboffset=None, cleanborders=None, crop_ts='600', crop_len='60', target_i='-19', target_lra='11.0', target_tp='-1.0', pix_fmt='yuv420p', subfile_provided=False, text_subs=True, subfilter_list=<factory>, kf_int='0', min_kf_int='0', bufsize='0', kf_sec='0', latency_target='0', afilters='', filter_complex='', input_flags=<factory>, encode_flags=<factory>, filter_flags=<factory>, output_flags=<factory>, shader_list=<factory>, ff_flags=<factory>, srt_passphrase='', srt_latency=5.0, ff_verbosity_flags=<factory>, ff_deepprobe_flags=<factory>, placebo_opts=<factory>, sw_filters=<factory>, vencoder_params=<factory>, copy_audio=False, copy_video=False, use_timeline=False, hwaccel=True, subs=False, deep_probe=False, vindex=0, aindex=0, sindex=None, outfile=None, npass=None, passfile=None, wait=False, overwrite=False, fifo=False, soxr=False, zscale=False, slowseek=False, live=False, obs=False, vulkan=False, vgop=False, trust_vulkan=False, vulkan_device=-1, decimate_target='24/1', is_playlist=False, eightbit=False, cropsecond=False, subcropfirst=False, picsubscale='bicubic', delay_start=False, deinterlace=False, crop=False, upscale=False, anormalize=False, normfile=None, dynamicnorm=False, fix_start_time=True, pyffserver=False, ffprogress=<factory>)¶
Class holding general encoding parameters.
Needs to be passed to an encode session to initialize it.
- Parameters:
tempdir (pathlib.Path) –
verbosity (int) –
api_url (str) –
api_key (str) –
samplerate (str) –
endpoint (str) –
target_w (str) –
target_h (str) –
framerate (str) –
framerate_multiplier (fractions.Fraction) –
scale_w (str) –
scale_h (str) –
bound_w (str) –
bound_h (str) –
kf_target_sec (float) –
clip_length (str | None) –
vencoder (VEncoder) –
aencoder (str) –
encode_preset (str | None) –
encode_tune (str | None) –
realtime (bool) –
vstandard (str) –
astandard (str) –
include_audio (bool) –
protocol (str) –
vbitrate (str) –
max_vbitrate (str) –
rc_mode (str) –
abitrate (str) –
chlayout (str) –
start_delay (str) –
end_pad (bool) –
end_delay (str) –
timestamp (str | None) –
suboffset (str | None) –
crop_ts (str) –
crop_len (str) –
target_i (str) –
target_lra (str) –
target_tp (str) –
pix_fmt (str) –
subfile_provided (bool) –
text_subs (bool) –
subfilter_list (Sequence[ffmpeg.Filter]) –
kf_int (str) –
min_kf_int (str) –
bufsize (str) –
kf_sec (str) –
latency_target (str) –
afilters (str) –
filter_complex (str) –
input_flags (MutableSequence[str]) –
encode_flags (MutableSequence[str]) –
filter_flags (MutableSequence[str]) –
output_flags (MutableSequence[str]) –
shader_list (MutableSequence[str]) –
ff_flags (MutableSequence[str]) –
srt_passphrase (str) –
srt_latency (float) –
ff_verbosity_flags (Sequence[str]) –
ff_deepprobe_flags (Sequence[str]) –
placebo_opts (Sequence[str]) –
sw_filters (Sequence[str]) –
vencoder_params (Sequence[str]) –
copy_audio (bool) –
copy_video (bool) –
use_timeline (bool) –
hwaccel (bool) –
subs (bool) –
deep_probe (bool) –
vindex (int) –
aindex (int) –
sindex (int | None) –
outfile (pathlib.Path | None) –
npass (int | None) –
passfile (pathlib.Path | None) –
wait (bool) –
overwrite (bool) –
fifo (bool) –
soxr (bool) –
zscale (bool) –
slowseek (bool) –
live (bool) –
obs (bool) –
vulkan (bool) –
vgop (bool) –
trust_vulkan (bool) –
vulkan_device (int) –
decimate_target (str) –
is_playlist (bool) –
eightbit (bool) –
cropsecond (bool) –
subcropfirst (bool) –
picsubscale (str) –
delay_start (bool) –
deinterlace (bool) –
crop (bool) –
upscale (bool) –
anormalize (bool) –
normfile (pathlib.Path | None) –
dynamicnorm (bool) –
fix_start_time (bool) –
pyffserver (bool) –
ffprogress (ffmpeg.Progress[str]) –
- class pyffstream.encode.StatusCode(value)¶
An enumeration.
- class pyffstream.encode.StyleFile(names, lines, insert_index)¶
-
- lines: MutableSequence[str]¶
Alias for field number 1
- names: MutableSequence[str]¶
Alias for field number 0
- class pyffstream.encode.VEncoder(name, codec, flag_function, presets=<factory>, default_preset=None, tenbit=False, type=EncType.SOFTWARE, multipass=False)¶
pyffstream.cli¶
CLI frontend for encoding and streaming.
- class pyffstream.cli.ConfName(file_name, arg_name)¶
- class pyffstream.cli.DefaultConfig(pyffserver=False, protocol='srt', vbitrate='6M', max_vbitrate='0', abitrate='256k', aencoder='aac', vencoder='libx264', endpoint='127.0.0.1:9998', api_url='', api_key='', soxr=False, preset=<factory>, zscale=False, vulkan=False, trust_vulkan=False, vgop=False, vulkan_device=-1, hwaccel=True, height=1080, shader_list=<factory>, kf_target_sec=5.0, srt_latency=5.0, ffmpeg_bin='ffmpeg', ffprobe_bin='ffprobe', env=<factory>)¶
Holds config file values.
Used to determine the default CLI parameters after processing config from files.
- Parameters:
pyffserver (bool) –
protocol (str) –
vbitrate (str) –
max_vbitrate (str) –
abitrate (str) –
aencoder (str) –
vencoder (str) –
endpoint (str) –
api_url (str) –
api_key (str) –
soxr (bool) –
zscale (bool) –
vulkan (bool) –
trust_vulkan (bool) –
vgop (bool) –
vulkan_device (int) –
hwaccel (bool) –
height (int) –
kf_target_sec (float) –
srt_latency (float) –
ffmpeg_bin (str) –
ffprobe_bin (str) –
- pyffstream.cli.download_win_ffmpeg(dltype='git')¶
Download and install ffmpeg for windows in user_data_path.
The current ffmpeg in the location is replaced if already there. User data path is determined from platformdirs.
- pyffstream.cli.get_parserconfig(reproducible=True)¶
Return parser and config used.
- Parameters:
reproducible (
bool
) –- Return type:
- pyffstream.cli.get_stream_list(streamtype, q_tuple, myfileargs, deep_probe=False)¶
Make and return tuples of (key,val) pairs for each stream.
- pyffstream.cli.main()¶
Process config and CLI arguments then send off for processing.
- Return type:
- pyffstream.cli.parse_files(args, parser)¶
Process input arguments and send them off processing.
- Parameters:
args (
Namespace
) –parser (
ArgumentParser
) –
- Return type:
- pyffstream.cli.print_info(fopts, *, verbosity=0, deep_probe=False)¶
Prints to console formatted information about the input file.
Output is nicely formatted for console usage using rich tables.
- pyffstream.cli.process_file(fpath, args, stream_flist)¶
Format input arguments needed for a file and send to output.
- pyffstream.cli.set_console_logger(verbosity, logfile)¶
Set loglevel.
- Parameters:
verbosity (int) –
logfile (pathlib.Path | None) –
- Return type:
None
- pyffstream.cli.setup_pyffserver_stream(fv)¶
Communicate with a pyffserver API to set up encode session.
- Parameters:
fv (
EncodeSession
) –- Return type:
- pyffstream.cli.start_stream(fv)¶
Start and track the actual encode.
- Parameters:
fv (
EncodeSession
) –- Return type:
- pyffstream.cli.status_wait(fv, futures)¶
Wait on remaining background processes while showing status.
- pyffstream.cli.stream_file(fopts, args)¶
Manage calculating of all stream parameters.