This class implements a simple video encoder for Android using Ocean::Frame objects as input. More...

#include <VideoEncoder.h>

Data Structures
class	Sample
	Definition of an encoded sample. More...

Public Types
enum	MediaCodecBufferFlags : uint32_t { BUFFER_FLAG_NONE = 0u , BUFFER_FLAG_KEY_FRAME = 1u , BUFFER_FLAG_CODEC_CONFIG = 2u , BUFFER_FLAG_END_OF_STREAM = 4u , BUFFER_FLAG_PARTIAL_FRAME = 8u }
	Definition of individual MediaCodec buffer flag constants. More...

using	Samples = std::vector< Media::Android::VideoEncoder::Sample >
	Definition of a vector holding sample objects.

Public Member Functions
	VideoEncoder ()
	Default constructor creating an un-initialized encoder.

	VideoEncoder (VideoEncoder &&videoEncoder) noexcept
	Move constructor.

	~VideoEncoder ()
	Destructs the video encoder and releases all associated resources.

bool	initialize (const unsigned int width, const unsigned int height, const std::string &mime="video/avc", const double frameRate=30.0, const unsigned int bitrate=bitrateMbps2_, const int iFrameInterval=1, const FrameType::PixelFormat preferredPixelFormat=FrameType::FORMAT_Y_UV12_LIMITED_RANGE)
	Initializes the video encoder with the specified configuration.

bool	start ()
	Starts the video encoder.

bool	stop ()
	Stops the video encoder.

bool	pushFrame (const Frame &frame, const uint64_t presentationTime)
	Adds a new frame which needs to be encoded to the video encoder.

Sample	popSample ()
	Returns the next encoded sample if available.

bool	isInitialized () const
	Returns whether this encoder is initialized.

bool	isStarted () const
	Returns whether this encoder is currently running.

void	release ()
	Explicitly releases this video encoder.

VideoEncoder &	operator= (VideoEncoder &&videoEncoder) noexcept
	Move operator.

Static Public Attributes
static constexpr int	bitrateMbps1_ = 1000 * 1000
	Definition of a 1 Mbps bit rate.

static constexpr int	bitrateMbps2_ = bitrateMbps1_ * 2
	Definition of a 2 Mbps bit rate.

static constexpr int	bitrateMbps5_ = bitrateMbps1_ * 5
	Definition of a 5 Mbps bit rate.

static constexpr int	bitrateMbps10_ = bitrateMbps1_ * 10
	Definition of a 10 Mbps bit rate.

Protected Member Functions
	VideoEncoder (const VideoEncoder &)=delete
	Disabled copy constructor.

VideoEncoder &	operator= (const VideoEncoder &)=delete
	Disabled copy operator.

Static Protected Member Functions
static Frame	frameFromBuffer (const unsigned int width, const unsigned int height, uint8_t *const buffer, size_t size, const int32_t androidFormat, const int32_t androidColorRange)
	Creates a Frame object from a raw buffer provided by the Android MediaCodec.

Protected Attributes
NativeMediaLibrary::ScopedSubscription	nativeMediaLibrarySubscription_
	The subscription for the native media library.

NativeMediaLibrary::ScopedAMediaCodec	encoder_
	The Android media encoder used to encode the video.

bool	isStarted_ = false
	True, if the encoder is currently started.

Lock	lock_
	The encoder's lock.

Static Protected Attributes
static constexpr unsigned int	maximalWidth_ = 1920u * 8u
	Definition of the maximal image width.

static constexpr unsigned int	maximalHeight_ = 1080u * 8u
	Definition of the maximal image height.

static constexpr int	maximalBitrate_ = bitrateMbps10_ * 10
	Definition of the maximal bit rate.

Detailed Description

This class implements a simple video encoder for Android using Ocean::Frame objects as input.

Usage:

// a function which is e.g., running in a separate thread
void threadRun()
{
    VideoEncoder videoEncoder;
*
    if (!videoEncoder.initialize(1920u, 1080u))
    {
        // handle error
    }
 
    if (!videoEncoder.start())
    {
        // handle error
    }
 
    unsigned int frameIndex = 0u;
    double frameRate = 30.0;
 
    while (true)
    {
        Frame frame;
 
        // external function: function needs to provide frames from an external source - e.g., from a camera, a video stream, etc.
        if (doesNewFrameExist(frame))
        {
            // presentation time in microseconds
            uint64_t presentationTime = uint64_t(1.0e6 * double(frameIndex) / frameRate);
 
            // we forward the frame to the encoder, eventually it will be encoded and will be available through popSample()
            if (!videoEncoder.pushFrame(frame, presentationTime))
            {
                // handle error
            }
 
            ++frameIndex;
        }
 
        // we simply check whether another sample has been encoded
        VideoEncoder::Sample encodedSample = videoEncoder.popSample();
 
        if (encodedSample.isValid())
        {
            // external function: receiving encoded samples and processes them
            sendSampleToReceiver(std::move(encodedSample));
        }
    }
}

Member Typedef Documentation

◆ Samples

using Ocean::Media::Android::VideoEncoder::Samples = std::vector<Media::Android::VideoEncoder::Sample>

Definition of a vector holding sample objects.

Member Enumeration Documentation

◆ MediaCodecBufferFlags

enum Ocean::Media::Android::VideoEncoder::MediaCodecBufferFlags : uint32_t

Definition of individual MediaCodec buffer flag constants.

From Android MediaCodec.BufferInfo: https://developer.android.com/reference/android/media/MediaCodec.BufferInfo

Enumerator
BUFFER_FLAG_NONE	The buffer has no special property.
BUFFER_FLAG_KEY_FRAME	Indicates that the (encoded) buffer marked as such contains the data for a key frame.
BUFFER_FLAG_CODEC_CONFIG	Indicates that the buffer marked as such contains codec initialization / codec specific data instead of media data.
BUFFER_FLAG_END_OF_STREAM	Indicates that the buffer is the last buffer in the stream.
BUFFER_FLAG_PARTIAL_FRAME	Indicates that the buffer only contains part of a frame.

Constructor & Destructor Documentation

◆ VideoEncoder() [1/3]

Ocean::Media::Android::VideoEncoder::VideoEncoder ( )

Default constructor creating an un-initialized encoder.

◆ VideoEncoder() [2/3]

Ocean::Media::Android::VideoEncoder::VideoEncoder ( VideoEncoder && videoEncoder )

inlinenoexcept

Move constructor.

Parameters

videoEncoder The encoder to be moved

◆ ~VideoEncoder()

Ocean::Media::Android::VideoEncoder::~VideoEncoder ( )

Destructs the video encoder and releases all associated resources.

◆ VideoEncoder() [3/3]

Ocean::Media::Android::VideoEncoder::VideoEncoder ( const VideoEncoder & )

protecteddelete

Disabled copy constructor.

Member Function Documentation

◆ frameFromBuffer()

static Frame Ocean::Media::Android::VideoEncoder::frameFromBuffer	(	const unsigned int	width,
		const unsigned int	height,
		uint8_t *const	buffer,
		size_t	size,
		const int32_t	androidFormat,
		const int32_t	androidColorRange
	)

staticprotected

Creates a Frame object from a raw buffer provided by the Android MediaCodec.

This function wraps the raw buffer memory into a Frame object with the appropriate pixel format and plane layout. The function supports YUV420 formats in both semi-planar (Y_UV12) and planar (Y_U_V12) layouts.

Parameters

width	The width of the frame in pixels, must be even, with range [2, infinity)
height	The height of the frame in pixels, must be even, with range [2, infinity)
buffer	The raw buffer containing the frame data, must be valid
size	The size of the buffer in bytes, with range [1, infinity)
androidFormat	The Android MediaCodec color format constant
androidColorRange	The Android MediaFormat color range constant

Returns: The resulting Frame object wrapping the buffer, invalid if the parameters are invalid or the format is not supported

◆ initialize()

bool Ocean::Media::Android::VideoEncoder::initialize	(	const unsigned int	width,
		const unsigned int	height,
		const std::string &	mime = `"video/avc"`,
		const double	frameRate = `30.0`,
		const unsigned int	bitrate = `bitrateMbps2_`,
		const int	iFrameInterval = `1`,
		const FrameType::PixelFormat	preferredPixelFormat = `FrameType::FORMAT_Y_UV12_LIMITED_RANGE`
	)

Initializes the video encoder with the specified configuration.

Parameters

width	The width of the video to be encoded, in pixel, with range [1, infinity)
height	The height of the video to be encoded, in pixel, with range [1, infinity)
mime	The MIME type (Multipurpose Internet Mail Extensions) of the video to be encoded, e.g., "video/avc", "video/hevc", ...
frameRate	The target frame rate in frames per second, with range (0, infinity), e.g., 30.0
bitrate	The target bitrate in bits per second, with range [1, infinity), e.g., 5000000 for 5 Mbps
iFrameInterval	The interval between I-frames (key frames) in seconds: negative value = no key frames after first frame, 0 = all frames are key frames, positive value = key frames every N seconds
preferredPixelFormat	The preferred pixel format the encoded uses internally

Returns: True, if succeeded

See also: isInitialized().

◆ isInitialized()

bool Ocean::Media::Android::VideoEncoder::isInitialized ( ) const

inline

Returns whether this encoder is initialized.

Returns: True, if so

See also: initialize().

◆ isStarted()

bool Ocean::Media::Android::VideoEncoder::isStarted ( ) const

inline

Returns whether this encoder is currently running.

Returns: True, if so

See also: start().

◆ operator=() [1/2]

VideoEncoder & Ocean::Media::Android::VideoEncoder::operator= ( const VideoEncoder & )

protecteddelete

Disabled copy operator.

Returns: Reference to this object

◆ operator=() [2/2]

VideoEncoder & Ocean::Media::Android::VideoEncoder::operator= ( VideoEncoder && videoEncoder )

inlinenoexcept

Move operator.

Parameters

videoEncoder The video encoder to be moved

Returns: Reference to this object

◆ popSample()

Sample Ocean::Media::Android::VideoEncoder::popSample ( )

Returns the next encoded sample if available.

Returns: The resulting encoded sample, invalid if currently no encoded sample is available

See also: pushFrame().

◆ pushFrame()

bool Ocean::Media::Android::VideoEncoder::pushFrame	(	const Frame &	frame,
		const uint64_t	presentationTime
	)

Adds a new frame which needs to be encoded to the video encoder.

The encoder needs to be initialized and started.
The presentation time is mainly intended to allow associating the provided frame with the resulting encoded sample when calling popSample().
However, it's recommended to define a reasonable presentation time for each frame (e.g., let the first frame start at 0 and increment the time by 1^6/fps for each following frame).

Parameters

frame	The frame to be encoded, must be valid
presentationTime	The presentation time of the frame, in microseconds, with range [0, infinity)

Returns: True, if succeeded

See also: start(), isInitialized(), isStarted().

◆ release()

void Ocean::Media::Android::VideoEncoder::release ( )

Explicitly releases this video encoder.

If the encoder is still running, the encoder will be stopped as well.

◆ start()

bool Ocean::Media::Android::VideoEncoder::start ( )

Starts the video encoder.

Returns: True, if succeeded

See also: isStarted().

◆ stop()

bool Ocean::Media::Android::VideoEncoder::stop ( )

Stops the video encoder.

Returns: True, if succeeded

Field Documentation

◆ bitrateMbps10_

constexpr int Ocean::Media::Android::VideoEncoder::bitrateMbps10_ = bitrateMbps1_ * 10

staticconstexpr

Definition of a 10 Mbps bit rate.

◆ bitrateMbps1_

constexpr int Ocean::Media::Android::VideoEncoder::bitrateMbps1_ = 1000 * 1000

staticconstexpr

Definition of a 1 Mbps bit rate.

◆ bitrateMbps2_

constexpr int Ocean::Media::Android::VideoEncoder::bitrateMbps2_ = bitrateMbps1_ * 2

staticconstexpr

Definition of a 2 Mbps bit rate.

◆ bitrateMbps5_

constexpr int Ocean::Media::Android::VideoEncoder::bitrateMbps5_ = bitrateMbps1_ * 5

staticconstexpr

Definition of a 5 Mbps bit rate.

◆ encoder_

NativeMediaLibrary::ScopedAMediaCodec Ocean::Media::Android::VideoEncoder::encoder_

protected

The Android media encoder used to encode the video.

◆ isStarted_

bool Ocean::Media::Android::VideoEncoder::isStarted_ = false

protected

True, if the encoder is currently started.

◆ lock_

Lock Ocean::Media::Android::VideoEncoder::lock_

mutableprotected

The encoder's lock.

◆ maximalBitrate_

constexpr int Ocean::Media::Android::VideoEncoder::maximalBitrate_ = bitrateMbps10_ * 10

staticconstexprprotected

Definition of the maximal bit rate.

◆ maximalHeight_

constexpr unsigned int Ocean::Media::Android::VideoEncoder::maximalHeight_ = 1080u * 8u

staticconstexprprotected

Definition of the maximal image height.

◆ maximalWidth_

constexpr unsigned int Ocean::Media::Android::VideoEncoder::maximalWidth_ = 1920u * 8u

staticconstexprprotected

Definition of the maximal image width.

◆ nativeMediaLibrarySubscription_

NativeMediaLibrary::ScopedSubscription Ocean::Media::Android::VideoEncoder::nativeMediaLibrarySubscription_

protected

The subscription for the native media library.

The documentation for this class was generated from the following file:

VideoEncoder.h

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Samples

Member Enumeration Documentation

◆ MediaCodecBufferFlags

Constructor & Destructor Documentation

◆ VideoEncoder() [1/3]

◆ VideoEncoder() [2/3]

◆ ~VideoEncoder()

◆ VideoEncoder() [3/3]

Member Function Documentation

◆ frameFromBuffer()

◆ initialize()

◆ isInitialized()

◆ isStarted()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ popSample()

◆ pushFrame()

◆ release()

◆ start()

◆ stop()

Field Documentation

◆ bitrateMbps10_

◆ bitrateMbps1_

◆ bitrateMbps2_

◆ bitrateMbps5_

◆ encoder_

◆ isStarted_

◆ lock_

◆ maximalBitrate_

◆ maximalHeight_

◆ maximalWidth_

◆ nativeMediaLibrarySubscription_