This module is a thin ctypes-based wrapper around the functions provided by the ffmpeg libraries. The libraries themselves are not part of cgkit, they must be installed separately as shared libraries.
The module was built against ffmpeg version 0.7.6 (avformat 52.110.0, avcodec 52.122.0, avutil 50.43.0, swscale 0.14.1). If the ffmpeg libraries on your system are different, you may not be able to use this wrapper module because of changes in the ffmpeg API.
Return the libavformat library version.
Returns a tuple (major,minor,micro) containing the three parts of the version number.
Initialize libavformat and register all the (de)muxers and protocols.
This must be called at the beginning before any file is opened.
Return the first/next registered input format.
If fmt is None, the first registered input format is returned as a AVInputFormat object. If that object is passed back in as input, the next registered format is returned and so on. If there are no more formats available, None is returned.
Return the first/next registered output format.
If fmt is None, the first registered output format is returned as a AVOutputFormat object. If that object is passed back in as input, the next registered format is returned and so on. If there are no more formats available, None is returned.
Open a media file as input.
fileName is a string containing the file to open. format is an optional AVInputFormat object that can be specified to force a particular file format (AVInputFormat is not yet exposed). buf_size is an optional buffer size (or 0/None if the default size is ok) params is an optional AVFormatParameters object if extra parameters have to be passed.
The return value is a AVFormatContext object that contains information about the format and that serves as a handle to the open file. In case of an error, an AVFormatError exception is thrown.
Close a media file (but not its codecs).
formatCtx is the format context as returned by av_open_input_file() If it is None, the function returns immediately.
Read packets of a media file to get stream information.
This is useful for file formats with no headers such as MPEG. This function also computes the real frame rate in case of mpeg2 repeat frame mode. The logical file position is not changed by this function; examined packets may be buffered for later processing.
formatCtx is the media file handle as returned by av_open_input_file(). The return value is the integer that was returned by the underlying C function (it is always >=0). In the case of an error, an AVFormatError exception is thrown.
Return the next frame of a stream.
formatCtx is the media file handle as returned by av_open_input_file(). pkt is a AVPacket object that will be filled with the packet data.
The returned packet is valid until the next av_read_frame() or until av_close_input_file() and must be freed with av_free_packet(). For video, the packet contains exactly one frame. For audio, it contains an integer number of frames if each frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames have a variable size (e.g. MPEG audio), then it contains one frame.
pkt.pts, pkt.dts and pkt.duration are always set to correct values in AVStream.timebase units (and guessed if the format cannot provided them). pkt.pts can be AV_NOPTS_VALUE if the video format has B frames, so it is better to rely on pkt.dts if you do not decompress the payload.
Returns False when EOF was reached.
Seek to the key frame at timestamp.
‘timestamp’ in ‘stream_index’.
stream_index If stream_index is (-1), a default stream is selected, and timestamp is automatically converted from AV_TIME_BASE units to the stream specific time_base. timestamp timestamp in AVStream.time_base units or if there is no stream specified then in AV_TIME_BASE units flags flags which select direction and seeking mode (AVSEEK_FLAG_*)
Allocates and initializes an AVFormatContext object.
Returns an initialized AVFormatContext object that can be used to write a new file.
The allocated structure must be freed with avutil.av_free() (everything that has been explicitly allocated must also be freed explicitly).
Search for an output format.
Returns the output format in the list of registered output formats which best matches the provided parameters, or returns NULL if there is no match.
shortName (if not None) checks if shortName matches with the names of the registered formats. fileName (if not None) checks if file name terminates with the extensions of the registered formats. mimeType (if not None) checks if mime type matches with the MIME type of the registered formats.
Returns an AVOutputFormat object or None. The returned object is owned by ffmpeg and must not be freed.
Guesses the codec ID based upon muxer and filename.
outputFormat is an AVOutputFormat object. codecType determines what kind of codec is required, it can be either CODEC_TYPE_VIDEO or CODEC_TYPE_AUDIO. Returns a codec id (int) or None if no codec could be found.
Adds a new stream to a media file.
Allocates a new stream and adds it to formatCtx. formatCtx is an AVFormatContext object which will receive the new stream. id is an integer containing a file-format-dependent stream id. Returns an AVStream object (which will also be available in formatCtx.streams).
If the stream couldn’t be allocated, an AVFormatError exception is thrown.
Return the libavcodec library version.
Returns a tuple (major,minor,micro) containing the three parts of the version number.
Finds a decoder with a matching codec ID.
id is an integer containing the codec id. Returns a AVCodec object or None if no decoder was found.
Finds a registered decoder with the specified name.
Returns a AVCodec object or None if no decoder was found.
Finds a registered encoder with a matching codec ID.
id is an integer containing the codec id. Returns an AVCodec object or None if no encoder was found.
Finds a registered encoder with the specified name.
Returns an AVCodec object or None if no encoder was found.
Initializes the AVCodecContext to use the given AVCodec.
avctx is a AVCodecContext object and codec a AVCodec object. Raises an exception when an error occurs.
Prior to using this function the context has to be allocated.
The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(), avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for retrieving a codec.
Warning: This function is not thread safe!
Close the codec.
Allocates an AVFrame and sets its fields to default values.
The resulting struct can be deallocated by simply calling avutil.av_free(). Returns an AVFrame object.
Decodes a video frame from pkt into picture.
Some decoders may support multiple frames in a single AVPacket, such decoders would then just decode the first frame.
Some codecs have a delay between input and output, these need to be fed with avpkt.data=NULL, avpkt.size=0 at the end to return the remaining frames.
codecCtx is an AVCodecCtx object, picture is an AVFrame object which will receive the decoded video frame. pkt is a AVPacket object containing the encoded data.
Returns a tuple (got_picture, bytes) where got_picture is a boolean that indicates whether a frame was decoded (True) or not and bytes is the number of bytes used or 0 if no frame could be decompressed.
Decode an audio frame.
Some decoders may support multiple frames in a single AVPacket, such decoders would then just decode the first frame. In this case, avcodec_decode_audio3 has to be called again with an AVPacket that contains the remaining data in order to decode the second frame etc.
codecCtx is an AVCodecCtx object, sampleBuf is a ctypes short array that will receive the decoded audio data. pkt is a AVPacket object containing the encoded data.
Returns the frameSize (size in bytes of the decoded frame) and the number of bytes that have been used from the input buffer in pkt. If there are no more frames, both values are 0.
Encodes a video frame from picture into buf.
codecCtx is a AVCodecContext object, buf is a pointer to the output buffer, bufsize is the size in bytes of the buffer and picture is a AVFrame object containing the picture to encode.
The input picture should be stored using a specific format, namely avctx.pix_fmt. Returns 0 or the number of bytes used from the output buffer.
Flush buffers.
Should be called when seeking or when switching to a different stream.
Allocate memory for a picture.
Call avpicture_free() to free it.
picture the AVPicture obejct to be filled in pix_fmt the format of the picture width the width of the picture height the height of the picture
Free a picture previously allocated by avpicture_alloc().
Initialize optional fields of a packet with default values.
pkt is a AVPacket object. Don’t call this function on a packet that already contains data as this would lead to a memory leak.
Free a packet.
pkt is a AVPacket object. Frees the data associated with the packet (if there is any data set).
Calculate image size.
Calculate the size in bytes that a picture of the given width and height would occupy if stored in the given picture format.
pix_fmt the given picture format width the width of the image height the height of the image
Returns the size in bytes.
Fill in the AVPicture fields.
The fields of the given AVPicture are filled in by using the ‘ptr’ address which points to the image data buffer. Depending on the specified picture format, one or multiple image data pointers and line sizes will be set. If a planar format is specified, several pointers will be set pointing to the different picture planes and the line sizes of the different planes will be stored in the lines_sizes array.
picture AVPicture whose fields are to be filled in ptr Buffer which will contain or contains the actual image data pix_fmt The format in which the picture data is stored. width the width of the image in pixels height the height of the image in pixels
Returns the size of the image data in bytes
Codec types:
There are the following functions in the module:
Return the libswscale library version.
Returns a tuple (major,minor,micro) containing the three parts of the version number.
Allocate a SwsContext object.
Must be deallocated using sws_freeContext(). Returns a SwsContext object.
Free a SwsContext object.
Scale/convert an image.
Scales the image slice in srcSlice and puts the resulting scaled slice in the image in dst. A slice is a sequence of consecutive rows in an image.
Slices have to be provided in sequential order, either in top-bottom or bottom-top order. If slices are provided in non-sequential order the behavior of the function is undefined.
swsCtx is the scaling context as returned by sws_getContext(). src is the array containing the pointers to the planes of the source slice. srcStride is the array containing the strides for each plane of the source image srcSliceY is the position in the source image of the slice to process, that is the number (counted starting from zero) in the image of the first row of the slice. srcSliceH is the height of the source slice, that is the number of rows in the slice. dst is the array containing the pointers to the planes of the destination image. dstStride is the array containing the strides for each plane of the destination image Returns the height of the output slice.
There are the following functions in the module:
Return the libavutil library version.
Returns a tuple (major,minor,micro) containing the three parts of the version number.
Free memory which has been allocated with av_malloc(z)() or av_realloc().
obj may be a AVFrame object that was allocated using avcodec_alloc_frame() (note: obj must be the object itself, not a pointer to it).
Convert a floating point number into a rational.
d is the floating point number and max the maximum allowed numerator and denominator Returns a AVRational object representing d.
Return a description of an AVERROR code.
Returns None if no description could be found.
Return the name of the sample format or None if an unknown value is passed.
sampleFmt is an AV_SAMPLE_FMT_* value.
Return the sample format corresponding to the given name.
Returns AV_SAMPLE_FMT_NONE if the name is not recognized.
Return the number of bytes per sample.
sampleFmt is an AV_SAMPLE_FMT_* value. Returns 0 if sampleFmt refers to an unknown sample format.
Return the pixel format corresponding to the given name.
Returns PIX_FMT_NONE if the name is not recognized.
Return the name of the pixel format or None if an unknown value is passed.
pixFmt is a PIX_FMT_* value.
The module defines the following pixel format constants:
This is a pointer to an AVInputFormat object. Only one of iformat and oformat can contain a valid object, the other one is NULL.
This is a pointer to an AVOutputFormat object. Only one of iformat and oformat can contain a valid object, the other one is NULL.
The number of streams in the file.
The name of the file.
...
Decoding: Position of the first frame of the component, in AV_TIME_BASE fractional seconds. NEVER set this value directly, it is deduced from the AVStream values.
Decoding: duration of the stream, in AV_TIME_BASE fractional seconds. NEVER set this value directly, it is deduced from the AVStream values.
Decoding: Total file size, 0 if unknown.
Decoding: Total stream bitrate in bit/s, 0 if not available. Never set it directly if the file_size and the duration are known as FFmpeg can compute it automatically.
The stream index inside the file.
Format-specific stream id.
A AVCodecContext object.
This is a AVRational object containing the fundamental unit of time (in seconds) in terms of which frame timestamps are represented. For fixed-fps content, time base should be 1/framerate and timestamp increments should be 1.
Decoding: pts of the first frame of the stream in time_base units. Only set this if you are absolutely 100% sure that the value you set it to really is the pts of the first frame. This may be undefined (AV_NOPTS_VALUE).
Note: The ASF header does NOT contain a correct start_time the ASF demuxer must NOT set this.
Decoding: duration of the stream, in stream time base. If a source file does not specify a duration, but does specify a bitrate, this value will be estimated from bitrate and file size.
ISO 639-2/B 3-letter language code (empty string if undefined).
The number of frames in this stream if known or 0.
An AVRational containing the sample aspect ratio (0 if unknown). This is the width of a pixel divided by the height of the pixel.
An integer containing the presentation timestamp (in stream.time_base units). This is the time at which the decompressed packet has to be presented to the user. The value can be AV_NOPTS_VALUE if it is not stored in the file.
Decompression timestamp (in stream.time_base units). This is the time at which the packet is decompressed. Can be AV_NOPTS_VALUE if it is not stored in the file.
This is a pointer containing the address of the packet data.
The size of the packet data in bytes.
The index of the stream this packet belongs to.
The duration of this packet in stream.time_base units or 0 if unknown. Equals next_pts - this_pts in presentation order.
The byte position within the stream or -1 if unknown.
The average bitrate.
Number of bits the bitstream is allowed to diverge from the reference. The reference can be CBR (for CBR pass1) or VBR (for pass2)
Fourcc (LSB first, so “ABCD” -> (‘D’<<24) + (‘C’<<16) + (‘B’<<8) + ‘A’)).
This is a AVRational containing the fundamental unit of time (in seconds) in terms of which frame timestamps are represented. For fixed-fps content, timebase should be 1/framerate and timestamp increments should be identically 1.
Picture width (video only).
Picture height (video only).
An AVRational containing the sample aspect ratio (0 if unknown). This is the width of a pixel divided by the height of the pixel. Numerator and denominator must be relatively prime and smaller than 256 for some video standards.
The number of pictures in a group of pictures, or 0 for intra_only.
Pixel format, see PIX_FMT_xxx.
A list of 4 pointers.
A list of 4 integers.
Indicates whether this frame is a key frame (1) or not (0). This is always set by libavcodec (encoding and decoding).
Presentation time stamp in time_base units. If AV_NOPTS_VALUE then frame_rate = 1/time_base will be assumed.