fffw.encoding package¶

Submodules¶

fffw.encoding.codecs module¶

class fffw.encoding.codecs.AudioCodec(codec: str | None = None, bitrate: int = 0)¶

Bases: Codec

Base class for describing audio codecs.

See fffw.encoding.outputs.Codec for params definition.

>>> from dataclasses import dataclass
>>> from fffw.wrapper import param
>>> @dataclass
... class FdkAAC(AudioCodec):
...     codec = 'libfdk_aac'
...     rate: int = param(default=48000, name='r')
...
>>> codec = FdkAAC(bitrate=192000, rate=44100)
>>> copy = AudioCodec('copy')

kind: StreamType = 'a'¶

class fffw.encoding.codecs.Copy(codec: str = None, bitrate: int = 0, kind: fffw.graph.meta.StreamType = <factory>)¶

Bases: Codec

connect_edge(edge: Edge) → Edge¶

Cuts out a graph path that leads from input stream to copy codec.

copy codec cannot be used with filtered frames because they are not even decoded
when using vectorized processing to construct processing graph, intermediate vectors don’t know whether their output will be connected to a copy codec or to another filter
so input streams for complex vectors are connected to split filters
to copy codec properly, after all there split filters must be disconnected from input stream
if there is any another filter except split, it’s an error

Returns:: edge pointing to an input stream

codec: str = 'copy'¶

kind: StreamType¶

class fffw.encoding.codecs.VideoCodec(codec: str | None = None, bitrate: int = 0)¶

Bases: Codec

Base class for describing video codecs.

See fffw.encoding.outputs.Codec for params definition.

>>> from dataclasses import dataclass
>>> from fffw.wrapper import param
>>> @dataclass
... class X264(VideoCodec):
...     codec = 'libx264'
...     gop: int = param(name='g')
...
>>> codec = X264(bitrate=4000000, gop=25)
>>> copy = VideoCodec('copy')

kind: StreamType = 'v'¶

fffw.encoding.complex module¶

class fffw.encoding.complex.FilterComplex(input_list: InputList, output_list: OutputList)¶

Bases: object

ffmpeg filter graph wrapper.

get_free_source(kind: StreamType) → Source¶

Parameters:: kind – stream type
Returns:: first stream of this kind not connected to filter graph

render(partial: bool = False) → str¶: Returns filter_graph description in corresponding ffmpeg param syntax.

fffw.encoding.ffmpeg module¶

Bases: BaseWrapper

ffmpeg command line basic wrapper.

>>> from fffw.encoding.codecs import VideoCodec, AudioCodec
>>> from fffw.encoding.filters import Scale
>>> from fffw.encoding.outputs import output_file
>>> ff = FFMPEG('/tmp/input.mp4', overwrite=True)
>>> c = VideoCodec('libx264', bitrate=4_000_000)
>>> ff.video | Scale(1280, 720) > c
VideoCodec(codec='libx264', bitrate=4000000)
>>> ff.overwrite = True
>>> ff > output_file('/tmp/output.mp4', c,
...                  AudioCodec('libfdk_aac', bitrate=192_000))
>>> ff.get_cmd()
'ffmpeg -y -i /tmp/input.mp4 -filter_complex "[0:v]scale=w=1280:h=720[vout0]" -map "[vout0]" -c:v libx264 -b:v 4000000 -map 0:a -c:a libfdk_aac -b:a 192000 /tmp/output.mp4'
>>>

add_input(input_file: Input) → Input¶

Adds new source to ffmpeg.

>>> ff = FFMPEG()
>>> ff.add_input(Input(input_file="/tmp/input.mp4"))
>>>

add_output(output: Output) → Output¶

Adds output file to ffmpeg and connect it’s codecs to free sources.

>>> ff = FFMPEG()
>>> ff.add_output(Output(output_file='/tmp/output.mp4'))
>>>

check_buffering() → None¶

Checks that ffmpeg command will not cause frame buffering and out of memory errors.

Each input file must be read simultaneously be all codecs in outputs, or some streams will be buffered until requested by output codecs.

get_args() → List[bytes]¶

Returns:: command line arguments for ffmpeg.

This includes: - ffmpeg executable name - ffmpeg parameters - input list args - filter_graph definition - output list args

handle_stderr(line: str) → str¶

Handle ffmpeg output.

Capture only lines containing one of stderr_markers.

Parameters:: line – ffmpeg output line
Returns:: line to be appended to whole ffmpeg output.

property audio: Stream¶

first audio stream not yet connected to filter graph or codec.

>>> from fffw.encoding.codecs import AudioCodec
>>> ff = FFMPEG('/tmp/input.mp4')
>>> ac = AudioCodec('aac')
>>> ff.audio > ac
AudioCodec(codec='aac', bitrate=0)
>>>

Type:: returns

command: str = 'ffmpeg'¶

property filter_device: Device¶: Returns filter hardware device metadata.

filter_hardware: str = None¶: Sets a device for filter graph by it’s name set with init_hardware.

init_hardware: str = None¶: Initializes hardware acceleration device.

input: str | Input = None¶

property inputs: Tuple[Input, ...]¶

a copy of ffmpeg input list.

Type:: return

loglevel: str = None¶

i.e. level+info.

Type:: Loglevel

output: str | Output = None¶

property outputs: Tuple[Output, ...]¶

a copy of ffmpeg output list.

Type:: return

overwrite: bool = None¶: Overwrite output files without manual confirmation.

stderr_markers = ['[error]', '[fatal]']¶

property video: Stream¶

first video stream not yet connected to filter graph or codec.

>>> from fffw.encoding.filters import Scale
>>> ff = FFMPEG('/tmp/input.mp4')
>>> ff.video | Scale(1280, 720)
Scale(width=1280, height=720)
>>>

Type:: returns

fffw.encoding.filters module¶

class fffw.encoding.filters.AudioFilter¶

Bases: Filter

Base class for audio filters.

>>> @dataclass
... class Volume(AudioFilter):
...     filter = 'volume'
...     volume: float = param(default=1.0)
...
>>>

hardware: str | None¶

kind: StreamType = 'a'¶

class fffw.encoding.filters.AutoFilter(kind: StreamType)¶

Bases: Filter

Base class for stream kind autodetect.

kind: StreamType¶: Stream kind used to generate filter name. Required. Not used as filter parameter.

class fffw.encoding.filters.Concat(kind: StreamType, input_count: int = 2)¶

Bases: Filter

Concatenates multiple input stream to a single one.

Parameters:

kind – stream kind (for proper concatenated streams definitions).
input_count – number of input streams.

transform(*metadata: Meta) → Meta¶

Compute metadata for concatenated streams.

Parameters:: metadata – concatenated streams metadata
Returns:: Metadata for resulting stream with duration set to a sum of stream durations. Scenes and streams are also concatenated.

property args: str¶: Formats filter args as k=v pairs separated by colon.

filter: str = 'concat'¶

input_count: int = 2¶

kind: StreamType¶

class fffw.encoding.filters.Format(format: str | None = None)¶

Bases: VideoFilter

Converts pixel format of video stream

filter: str = 'format'¶

format: str = None¶

class fffw.encoding.filters.Overlay(x: int, y: int)¶

Bases: VideoFilter

Combines two video streams one on top of another.

Parameters:

x – horizontal position of top image in bottom one.
y – vertical position of top image in bottom one.

filter: str = 'overlay'¶

input_count: int = 2¶

x: int¶

y: int¶

class fffw.encoding.filters.Scale(width: int | None = None, height: int | None = None)¶

Bases: VideoFilter

Video scaling filter.

Parameters:

width – resulting video width
height – resulting video height

transform(*metadata: Meta) → Meta¶: Apply filter changes to stream metadata.

filter: str = 'scale'¶

hardware: str | None = None¶

height: int = None¶

width: int = None¶

class fffw.encoding.filters.SetPTS(kind: StreamType, expr: str = 'PTS-STARTPTS')¶

Bases: AutoFilter

Change the PTS (presentation timestamp) of the input frames.

$ ffmpeg -y -i source.mp4 -vf trim=start=3:end=4,setpts=PTS-STARTPTS -an test.mp4

Supported cases for metadata handling:

“PTS-STARTPTS” - resets stream start to zero.

transform(*metadata: Meta) → Meta¶: Apply filter changes to stream metadata.

RESET_PTS = 'PTS-STARTPTS'¶

property args: str¶: Formats filter args as k=v pairs separated by colon.

expr: str = 'PTS-STARTPTS'¶

filter: str = 'setpts'¶

class fffw.encoding.filters.Split(kind: StreamType, output_count: int = 2)¶

Bases: AutoFilter

Audio or video split filter.

Splits audio or video stream to multiple output streams (2 by default). Unlike ffmpeg split filter this one does not allow passing multiple inputs.

Parameters:

kind – stream type.
output_count – number of output streams.

disconnect(edge: Edge) → Edge | None¶

Removes unused edge from outputs and returns input edge instead.

This is used for “copy” codec, because it must be able to remove a graph path from input stream to an output codec, as copy is not allowed for filtered streams.

property args: str¶

split/asplit filter parameters

Type:: returns

property enabled: bool¶

filter: str = 'split'¶

output_count: int = 2¶

class fffw.encoding.filters.Trim(kind: StreamType, start: int | float | str | TS, end: int | float | str | TS)¶

Bases: AutoFilter

Cuts the input so that the output contains one continuous subpart of the input.

Parameters:

kind – stream kind (for proper concatenated streams definitions).
start – start time of trimmed output
end – end time of trimmed output

transform(*metadata: Meta) → Meta¶

Computes metadata for trimmed stream.

Parameters:: metadata – single incoming stream metadata.
Returns:: metadata with initial start (this is fixed with SetPTS) and duration set to trim end. Scenes list is intersected with trim interval, scene borders are aligned to trim borders.

end: int | float | str | TS¶

filter: str = 'trim'¶

start: int | float | str | TS¶

class fffw.encoding.filters.Upload(device: Device | None = None)¶

Bases: VideoFilter

Uploads a stream to a hardware device

transform(*metadata: Meta) → VideoMeta¶: Marks a stream as uploaded to a device.

device: Device = None¶

extra_hw_frames: int = 64¶

filter: str = 'hwupload'¶

class fffw.encoding.filters.VideoFilter¶

Bases: Filter

Base class for video filters.

>>> @dataclass
... class Deinterlace(VideoFilter):
...     filter = 'yadif'
...     mode: int = param(default=0)
...
>>>

hardware: str | None¶

kind: StreamType = 'v'¶

fffw.encoding.filters.ensure_audio(meta: Meta, *_: Meta) → AudioMeta¶

Checks that first passed stream is a audio stream

Returns:: first passed stream

fffw.encoding.filters.ensure_video(meta: Meta, *_: Meta) → VideoMeta¶

Checks that first passed stream is a video stream

Returns:: first passed stream

fffw.encoding.inputs module¶

Bases: BaseWrapper

Input command line params generator for FFMPEG.

Parameters:

fast_seek – seek input file over key frames
input_file – input file name
slow_seek – perform whole file decoding and output frames only from offset to end of file.
duration – stop decoding frames after an interval

connect_streams() → None¶: Sets a unique source identifier for each stream metadata in input.

get_stream(kind: StreamType) → Stream¶

Parameters:: kind – desired stream kind
Returns:: first available stream of desired kind
Raises:: KeyError – if no streams of this kind found.

property audio: Stream¶

device: str = None¶

duration: TS | float | int = None¶

fast_seek: TS | float | int = None¶

hardware: str = None¶

index¶: Internal ffmpeg source file index.

input_file: str = None¶

output_format: str = None¶

slow_seek: TS | float | int = None¶

streams: Tuple[Stream, ...]¶: List of audio and video streams for input file.

property video: Stream¶

class fffw.encoding.inputs.InputList(sources: Iterable[Input] = ())¶

Bases: list

List of inputs in FFMPEG.

append(source: Input) → None¶

Adds new source file to input list.

Parameters:: source – input file

extend(sources: Iterable[Input]) → None¶

Adds multiple source files to input list.

Parameters:: sources – list of input files

get_args() → List[bytes]¶

property streams: List[Stream]¶

class fffw.encoding.inputs.Stream(kind: StreamType, meta: Meta | None = None)¶

Bases: Source

Video or audio stream in input file.

connect_input(source: str) → None¶

Marks current stream metadata that it belongs to some input file.

Parameters:: source – source filename

split(count: int = 1) → List[Filter]¶

Splits input stream to reuse it as input node for multiple output nodes.

>>> from fffw.graph import meta
>>> stream = Stream(meta.VIDEO)
>>> s1, s2 = stream.split(2)
>>> s1 | filters.Scale(1280, 720)
>>> s2 | filters.Scale(640, 360)

index¶: Index of current stream in source file.

property name: str¶

source¶: Source file that contains current stream.

fffw.encoding.inputs.input_file(filename: str, *streams: Stream, **kwargs: Any) → Input¶

fffw.encoding.outputs module¶

class fffw.encoding.outputs.Codec(codec: str | None = None, bitrate: int = 0)¶

Bases: StreamValidationMixin, Dest, BaseWrapper

Base class for output codecs.

Parameters:

codec – ffmpeg codec name.
bitrate – output bitrate in bps.

as_pairs() → List[Tuple[str | None, str | None]]¶: Add stream index suffix to all named params

check_buffering() → List[str] | None¶

Check that scenes read from input stream are ordered with ascending timestamps.

Returns:: A list of streams needed for this codec or None if metadata for codec can’t be computed.

clone(count: int = 1) → List[Codec]¶

Creates multiple copies of self to reuse it as output node for multiple sources.

Any connected input node is being split and connected to a corresponding copy of current filter.

get_args() → List[bytes]¶: Insert map argument before all rest codec params.

bitrate: int = 0¶

codec: str = None¶

property connected: bool¶

True if codec is already connected to a node or a source.

Type:: return

index¶: Index of current codec in ffmpeg output streams.

property map: str | None¶

-map argument value depending of a node or a source connected to codec.

Type:: returns

class fffw.encoding.outputs.Output(codecs: ~typing.List[~fffw.encoding.outputs.Codec] = <factory>, no_video: bool | None = None, no_audio: bool | None = None, format: str | None = None, output_file: str | None = None)¶

Bases: BaseWrapper

Base class for ffmpeg output.

Parameters:

codecs – list of codecs used in output.
format – output file format.
output_file – output file name.

get_args() → List[bytes]¶

Returns:: codec args and output file parameters for ffmpeg

get_free_codec(kind: StreamType, create: bool = True) → Codec¶

Finds first codec not connected to filter graph or to an input, or creates a new unnamed codec stub if no free codecs left.

Parameters:

kind – desired codec stream type
create – create new codec stub

Returns:

first free codec or a new codec stub.

property audio: Codec¶

first audio codec not connected to source.

If no free codecs left, new one codec stub is appended to output.

Type:: returns

codecs: List[Codec]¶

format: str = None¶

no_audio: bool | None = None¶

no_video: bool | None = None¶

output_file: str = None¶

property video: Codec¶

first video codec not connected to source.

If no free codecs left, new one codec stub is appended to output.

Type:: returns

class fffw.encoding.outputs.OutputList(outputs: Iterable[Output] = ())¶

Bases: list

Supports unique output streams names generation.

append(output: Output) → None¶

Adds new output file to output list.

Parameters:: output – output file

extend(outputs: Iterable[Output]) → None¶

Adds multiple output files to output list.

Parameters:: outputs – list of output files

get_args() → List[bytes]¶: Combine all output params together

property codecs: List[Codec]¶

fffw.encoding.outputs.output_file(filename: str, *codecs: Codec, **kwargs: Any) → Output¶: A shortcut to create proper output file. :param filename: output file name. :param codecs: codec list for this output. :param kwargs: output parameters. :return: configured ffmpeg output.

fffw.encoding.sources module¶

fffw.encoding.vector module¶

class fffw.encoding.vector.FFMPEGFactory¶

Bases: object

MyPy-respected FFMPEG factory definition.

class fffw.encoding.vector.SIMD(source: Input, *results: Output, **kwargs: Any)¶

Bases: object

Single Instruction Multiple Data helper for video file processing.

Handles Vector initialization from source streams and output codecs connections.

add_input(source: Input) → Input¶: Adds additional input file to ffmpeg :param source: additional input file :returns: connected input

get_codecs(kind: StreamType) → Vector¶

Parameters:: kind – desired vector kind
Returns:: a vector of all codecs of desired kind for each output.

get_stream(kind: StreamType) → Stream¶

Parameters:: kind – desired stream kind
Returns:: first stream of desired kind from input file
Raises:: KeyError – if no streams of this kind found.

static validate_input_file(input_file: Input) → None¶: Checks that input file contains streams information with stream metadata.

static validate_output_file(output: Output) → None¶: Checks that output file contains codec information.

property audio: Vector¶

a vector with single audio input stream

Type:: returns

property ffmpeg: FFMPEG¶

Initializes ffmpeg wrapper with input/output files and command line arguments.

Note that ffmpeg instance can’t be instantiated twice, because existing output files could be connected to input streams only once.

Returns:: cached FFMPEG instance.

ffmpeg_wrapper = <fffw.encoding.vector.FFMPEGFactory object>¶

property video: Vector¶

a vector with single video input stream

Type:: returns

class fffw.encoding.vector.Vector(source: Stream | Filter | Iterable[Filter] | Iterable[Codec])¶

Bases: tuple

Represents immutable stream vector that helps to apply same or similar filters to a set of stream simultaneously.

Connects current vector to destination filter vector.

Parameters:

dst – destination vector, single filter or filter class used to initialize same filter with different parameters.
mask – list of flags that allows to skip applying destination filters to some sources.
params – filter class constructor arguments used to initialize a destination filter vector from filter class.

Returns:

new vector which is a result of applying destination filters to an input streams vector.

property kind: StreamType¶

a kind of streams in vector.

Type:: returns

property meta: Meta¶

metadata for a stream in vector.

Type:: returns

fffw.encoding.vector.group(first: Iterable[Any], second: Iterable[Any]) → Dict[int, Set[int]]¶

Group second iterable by first.

Parameters:

first – First iterable. ID of each object in iterable will be used as a key.
second – Second iterable. ID of each object in iterable will be added to a set, which is a value for corresponding key in first iterable.

Returns:

A dict that maps single object from first iterable to a set of objects from second iterable by object ids.

fffw.encoding.vector.init_filter_vector(filter_class: Type[Filter], params: List[Dict[str, Any]] | List[List[Any]] | List[Any]) → Vector¶

Initializes filter vector from filter class and list of parameters.

Parameters:

filter_class – type to initialize
params – list of filter class positional or keyword arguments

Returns:

filter vector with elements count equal to length of params list, each vector is instance of filter_class.

Links sources to destinations.

For each source/destination pair we find corresponding source split result and destination clone. Split is connected to clone, clone is added to resulting vector and cached to prevent connecting same split to same clone twice.

If destination is None, which means that it is disabled by mask, split is added to resulting vector instead of clone.

Parameters:

sources – list of initial incoming nodes.
src_splits – contains actual split node for each source/destination pair.
destinations – list of outgoing nodes (or None if disabled by mask).
dst_clones – contains actual dst clone for each source/destination pair.

Returns:

final vector with results of src/dst connection.

Transform different args to same form: vector of filters/codecs and boolean mask with corresponding length.

Parameters:

dst – destination vector, single filter or filter class used to initialize same filter with different parameters.
mask – list of flags that allows to skip applying destination filters to some sources.
params – filter class constructor arguments used to initialize a destination filter vector from filter class.

Returns:

new vector which is a result of applying destination filters to an input streams vector.

fffw.encoding.vector.prepare_dst_clones(destinations: Dict[int, Filter | Codec], groups: Dict[int, Set[int]]) → Dict[Tuple[int, int], Filter | Codec]¶

Prepares copies of filter for each unique group.

Destination (which is a group key) is copied N times with same parameters, where N is a number of unique inputs related to this destination.

If destination is a filter with multiple inputs, each input is split multiple times, disconnected from initial filter and split results are connected to filter copies.

Parameters:

destinations – contains outputs by object id.
groups – sources grouped by destination id.

Returns:

destination filter copy for each src/dst pair.

fffw.encoding.vector.prepare_src_splits(sources: Dict[int, Stream | Filter], groups: Dict[int, Set[int]]) → Dict[Tuple[int, int], Filter]¶

Initialize split filter for each unique group.

Source (which is a group key) is split to N nodes, where N is a number of corresponding outputs related to this source.

Parameters:

sources – contains sources by object id.
groups – destinations grouped by source id.

Returns:

split for each src/dst pair.

fffw.encoding.vector.Group¶

Grouping result.

alias of Dict[int, Set[int]]

fffw.encoding.vector.PairKey¶

Dict key containing ids of two related objects.

alias of Tuple[int, int]

fffw.encoding package¶

Submodules¶

fffw.encoding.codecs module¶

fffw.encoding.complex module¶

fffw.encoding.ffmpeg module¶

fffw.encoding.filters module¶

fffw.encoding.inputs module¶

fffw.encoding.outputs module¶

fffw.encoding.sources module¶

fffw.encoding.vector module¶

Module contents¶

fffw

Navigation

Related Topics