class mrpt::hwdrivers::CFFMPEG_InputStream

Overview

Decodes video files and RTSP/HTTP streams frame by frame using FFmpeg.

Opens local video files (AVI, MPEG, …) and IP camera streams (rtsp://, http://) via openURL(). Frames are retrieved one by one with grabFrame().

Typical use inside CCameraSensor via grabber_type=ffmpeg. Can also be used directly for reading pre-recorded video files.

Requires FFmpeg libraries (libavcodec, libavformat, libswscale). On Linux, install the ffmpeg development packages. On Windows, a precompiled set must be provided alongside MRPT.

#include <mrpt/hwdrivers/CFFMPEG_InputStream.h>

class CFFMPEG_InputStream
{
public:
    // structs

    struct Impl;

    // construction

    CFFMPEG_InputStream();

    // methods

    bool openURL(
        const std::string& url,
        bool grab_as_grayscale = false,
        bool verbose = false,
        const std::map<std::string, std::string>& options = { {"rtsp_transport", "tcp"} }
        );

    bool isOpen() const;
    void close();
    double getVideoFPS() const;
    bool retrieveFrame(mrpt::img::CImage& out_img);
    bool retrieveFrame(mrpt::img::CImage& out_img, int64_t& outPTS);
    std::optional<mrpt::img::CImage> grabFrame();
};

Construction

CFFMPEG_InputStream()

Default constructor.

No video source is open at startup.

Methods

bool openURL(
    const std::string& url,
    bool grab_as_grayscale = false,
    bool verbose = false,
    const std::map<std::string, std::string>& options = { {"rtsp_transport", "tcp"} }
    )

Opens a video file or a network video stream.

Supports local video files (e.g. “myVideo.avi”) and IP camera URLs (e.g. “rtsp://a.b.c.d/live.sdp”). Credentials can be embedded as “rtsp://USER:PASSWORD@IP/PATH”.

Parameters:

url	Path to a local file or a network stream URL.
grab_as_grayscale	If true, frames are converted to grayscale.
verbose	If true, stream metadata is printed to cout.
options	Extra FFmpeg protocol options (key-value pairs).

Returns:

true on success; false on any error (details printed to cerr).

See also:

close, grabFrame

bool isOpen() const

Returns true if the video source is currently open.

void close()

Closes the video stream.

Called automatically on destruction.

See also:

openURL

double getVideoFPS() const

Returns the nominal frame rate of the open video source.

Returns:

Frames per second, or -1 if the stream is not open.

bool retrieveFrame(mrpt::img::CImage& out_img)

Decodes and returns the next video frame.

For network streams this call may block until enough data is available. Deprecated Use grabFrame() instead.

Parameters:

out_img

The decoded image (8-bit RGB or grayscale).

Returns:

false on any error or end of stream, true on success.

See also:

openURL, close, isOpen

bool retrieveFrame(mrpt::img::CImage& out_img, int64_t& outPTS)

Decodes the next frame and also returns its presentation timestamp.

Parameters:

out_img	Decoded image.
outPTS	AVFrame::pts value (ffmpeg presentation timestamp).

Returns:

false on any error or end of stream, true on success.

std::optional<mrpt::img::CImage> grabFrame()

Decodes and returns the next video frame by value.

Returns:

std::nullopt on any error or end of stream, or the image on success.

See also:

openURL, close, isOpen