Writer

ffpyplayer.writer

FFmpeg based media writer

A FFmpeg based python media writer. See MediaWriter for details. Currently writes only video.

class ffpyplayer.writer.MediaWriter

Bases: object

An FFmpeg based media writer class. Currently only supports video.

With this class one can write images frames stored in many different pixel formats into a multi-stream video file using write_frame(). All FFmpeg codecs and pixel formats are supported.

Parameters:

filename: str

The filename of the media file to create. Will be encoded using utf8 berfore passing to FFmpeg.

streams: list of dicts

A list of streams to create in the file. streams is a list of dicts, where each dict configures the corresponding stream. The keywords listed below are available. One can also specify default values for the keywords for all streams using kwargs. Keywords also found in streams will overwrite those in kwargs:

pix_fmt_in: str

The pixel format of the Image to be passed to write_frame() for this stream. Can be one of ffpyplayer.tools.pix_fmts.

width_in: int

The width of the ffpyplayer.pic.Image that will be passed to write_frame() for this stream.

height_in: int

The height of the ffpyplayer.pic.Image that will be passed to write_frame() for this stream.

pix_fmt_out: str

The pixel format in which frames will be written to the file for this stream. Can be one of ffpyplayer.tools.pix_fmts. Defaults to pix_fmt_in if not provided. Not every pixel format is supported for each encoding codec, see get_supported_pixfmts() for which pixel formats are supported for codec.

width_out: int

The width at which frames will be written to the file for this stream. Defaults to width_in if not provided.

height_out: int

The height at which frames will be written to the file for this stream. Defaults to height_in if not provided.

codec: str

The codec used to write the frames to the file. Can be one of the encoding codecs in ffpyplayer.tools.codecs_enc.

If not provided, it defaults to the default best codec for the format provided in fmt or guessed from the filename. See ffpyplayer.tools.get_format_codecs()

frame_rate: 2-tuple of ints

A 2-tuple of ints representing the frame rate to be used when writing the file. The first element is the numerator, while the second is the denuminator of a ratio describing the rate. E.g. (2997, 100) describes 29.97 fps.

The timestamps of the frames written using write_frame() do not necessarily need to be multiples of the frame rate because they might be forced to matching timestamps if required. Not every frame rate is supported for each encoding codec, see ffpyplayer.tools.get_supported_framerates() for which frame rates are supported for codec.

fmt: str

The format to use for the output. Can be one of ffpyplayer.tools.formats_out. Defaults to empty string. If not provided, filename will be used determine the format, otherwise this arg will be used.

lib_opts: dict or list of dicts

A dictionary of options that will be passed to the ffmpeg libraries, codecs, sws, and formats when opening them. This accepts most of the options that can be passed to ffmpeg libraries. See below for examples. Both the keywords and values must be strings. It can be passed a dict in which case it’ll be applied to all the streams or a list containing a dict for each stream.

metadata: dict or list of dicts

Metadata that will be written to the streams, if supported by the stream. See below for examples. Both the keywords and values must be strings. It can be passed a dict in which case it’ll be applied to all the streams or a list containing a dict for each stream. If (these) metadata is not supported, it will silently fail to write them.

overwrite: bool

Whether we should overwrite an existing file. If False, an error will be raised if the file already exists. If True, the file will be overwritten if it exists.

**kwargs:

Accepts default values for all streams which will be used if these keywords are not provided for any stream.

See Writing video to file and Compressing video to h264 for examples.

close(self)

Closes the writer and writes any frames cached and not yet written.

Until called, or until the instance is deleted (and this is implicitly called) the file is not fully written.

Warning

After calling this method, calling any other class method on this instance may result in a crash or program corruption.

get_configuration(self)

Returns the configuration parameters used to initialize all the streams for this instance.

This is not the same as the dicts passed when creating the file because this uses the actual parameters used.

Returns:

list: List of dicts for each stream.

For example:

from ffpyplayer.writer import MediaWriter

w, h = 640, 480
out_opts = {'pix_fmt_in':'rgb24', 'width_in':w, 'height_in':h, 'codec':'rawvideo',
            'frame_rate':(5, 1)}
writer = MediaWriter('output.avi', [out_opts] * 2, width_out=w/2, height_out=h/2)

print writer.get_configuration()
[{'height_in': 480, 'codec': 'rawvideo', 'width_in': 640, 'frame_rate': (5, 1),
'pix_fmt_in': 'rgb24', 'width_out': 320, 'height_out': 240, 'pix_fmt_out': 'rgb24'},
{'height_in': 480, 'codec': 'rawvideo', 'width_in': 640, 'frame_rate': (5, 1),
'pix_fmt_in': 'rgb24', 'width_out': 320, 'height_out': 240, 'pix_fmt_out': 'rgb24'}]

write_frame(self, Image img, double pts, int stream=0)

Writes a ffpyplayer.pic.Image frame to the specified stream.

If the input data is different than the frame written to disk in either size or pixel format as specified when creating the stream, the frame is converted before writing. But the input image must match the size and format as that specified when creating this stream.

Parameters:

img: ffpyplayer.pic.Image

The ffpyplayer.pic.Image instance containing the frame to be written to disk.

pts: float

The timestamp of this frame in video time. E.g. 0.5 means the frame should be displayed by a player at 0.5 seconds after the video started playing. In a sense, the frame rate defines which timestamps are valid timestamps. However, this is not always the case, so if timestamps are invalid for a particular format, they are forced to valid values, if possible.

stream: int

The stream number to which to write this frame. Defaults to 0.

Returns:

(int): The approximate number of bytes written to disk so far for this file.

Note

This is not the same as the number of bytes passed to this function so far, because the encoders cache data before writing to disk. So although some frames may have been passed, the return value may not represent this.

An extreme example is where the same frame is passed many times to h264; the encoder will only write this frame once when the Writer object is closed and encoders are flushed, so this function will only return 0.

See Examples for its usage.