This class implements a simple video decoder for Android using encoded media samples from memory as input. More...

#include <VideoDecoder.h>

Public Member Functions
	VideoDecoder ()
	Default constructor creating an un-initialized decoder.

	VideoDecoder (VideoDecoder &&videoDecoder) noexcept
	Move constructor.

	~VideoDecoder ()
	Destructs the video decoder and releases all associated resources.

bool	initialize (const std::string &mime, const unsigned int width, const unsigned int height)

bool	start ()
	Starts the video decoder.

bool	stop ()
	Stops the video decoder.

bool	pushSample (const void *data, const size_t size, const uint64_t presentationTime)
	Adds a new media sample which needs to be decoded to the video decoder.

Frame	popFrame (int64_t *presentationTime=nullptr)
	Optional the frame's presentation time will be returned, this is the presentation time which was used when the corresponding sample was provided in decodedSample().

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

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

void	release ()
	Explicitly releases this video encoder.

VideoDecoder &	operator= (VideoDecoder &&videoDecoder) noexcept
	Move operator.

Static Public Member Functions
static Frame	extractVideoFrameFromCodecOutputBuffer (AMediaCodec const mediaCodec, int64_t presentationTime=nullptr)
	Extracts the video frame from an output buffer of a video codec.

static bool	convertAvccToAnnexB (const void *avccData, const size_t avccSize, std::vector< uint8_t > &annexBData, const bool isCodecConfig=false, const std::string &mime="video/avc")
	Converts AVCC/HVCC formatted H.264/H.265 data to Annex B format.

static bool	isAvcc (const void *data, const size_t size, const bool isCodecConfig=false)
	Determines whether the given data is in AVCC format (length prefixed) or Annex B format (start code prefixed).

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

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

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

NativeMediaLibrary::ScopedAMediaCodec	decoder_
	The Android media decoder used to decode the video.

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

Lock	lock_
	The decoder's lock.

Detailed Description

This class implements a simple video decoder for Android using encoded media samples from memory as input.

Usage:

// a function which is e.g., running in a separate thread
void threadRun()
{
    VideoDecoder videoDecoder;
 
    // initializing the decoder with the input format of the media samples
    if (!videoDecoder.initialize("video/avc", 1920u, 1080u))
    {
        // handle error
    }
 
    if (!videoDecoder.start())
    {
        // handle error
    }
 
    unsigned int frameIndex = 0u;
    double frameRate = 30.0;
 
    while (true)
    {
        void* sampleData = nullptr;
        size_t sampleSize = 0;
 
        // external function: function needs to provide the new media samples from an external source - e.g., from an external webcam, a video stream, etc.
        if (doesNewInputSampleExist(sampleData, &sampleSize))
        {
            // presentation time in microseconds
            uint64_t presentationTime = uint64_t(1.0e6 * double(frameIndex) / frameRate);
 
            // we forward the media sample to the decoder, eventually it will be decoded and will be available through decodedFrame()
            if (!videoDecoder.pushSample(sampleData, sampleSize, presentationTime))
            {
                // handle error
            }
 
            ++frameIndex;
        }
 
        // we simply check whether another frame has been decoded (there may be a delay between
        Frame newFrame = videoDecoder.popFrame();
 
        if (newFrame.isValid())
        {
            // external function: receiving new frames and processes the frames
            sendFrameToReceiver(std::move(newFrame));
        }
    }
}

Constructor & Destructor Documentation

◆ VideoDecoder() [1/3]

Ocean::Media::Android::VideoDecoder::VideoDecoder ( )

Default constructor creating an un-initialized decoder.

◆ VideoDecoder() [2/3]

Ocean::Media::Android::VideoDecoder::VideoDecoder ( VideoDecoder && videoDecoder )

inlinenoexcept

Move constructor.

Parameters

videoDecoder The decoder to be moved

◆ ~VideoDecoder()

Ocean::Media::Android::VideoDecoder::~VideoDecoder ( )

Destructs the video decoder and releases all associated resources.

◆ VideoDecoder() [3/3]

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

protecteddelete

Disabled copy constructor.

Member Function Documentation

◆ convertAvccToAnnexB()

static bool Ocean::Media::Android::VideoDecoder::convertAvccToAnnexB	(	const void *	avccData,
		const size_t	avccSize,
		std::vector< uint8_t > &	annexBData,
		const bool	isCodecConfig = `false`,
		const std::string &	mime = `"video/avc"`
	)

static

Converts AVCC/HVCC formatted H.264/H.265 data to Annex B format.

For encoded samples (isCodecConfig = false): Replaces 4-byte big-endian length prefixes with start code prefixes (00 00 00 01). For codec config (isCodecConfig = true): Parses the AVCC/HVCC configuration record and extracts SPS/PPS (and VPS for HEVC) NAL units with start codes.

Parameters

avccData	The AVCC/HVCC formatted data, must be valid
avccSize	The size of the AVCC/HVCC data in bytes, with range [4, infinity)
annexBData	The resulting Annex B formatted data with start code prefixes
isCodecConfig	True if the input is an AVCC/HVCC codec configuration record; False if it contains length-prefixed NAL units
mime	The MIME type, used only when isCodecConfig is true to determine H.264 vs HEVC format, either "video/avc" or "video/hevc"

Returns: True if conversion succeeded; False if the input data is invalid or conversion failed

◆ extractVideoFrameFromCodecOutputBuffer()

static Frame Ocean::Media::Android::VideoDecoder::extractVideoFrameFromCodecOutputBuffer	(	AMediaCodec *const	mediaCodec,
		int64_t *	presentationTime = `nullptr`
	)

static

Extracts the video frame from an output buffer of a video codec.

Parameters

mediaCodec	The media codec to which the output buffer belongs, must be valid
presentationTime	Optional resulting presentation time in micro seconds, with range (-infinity, infinity)

Returns: The resulting extracted frame, invalid if the frame could not be extracted

◆ initialize()

bool Ocean::Media::Android::VideoDecoder::initialize	(	const std::string &	mime,
		const unsigned int	width,
		const unsigned int	height
	)

Parameters

mime	The MIME type (Multipurpose Internet Mail Extensions) of the video to be decoded, e.g., "video/avc", "video/hevc", ...
width	The width of the video to be decoded, in pixel, with range [1, infinity)
height	The height of the video to be decoded, in pixel, with range [1, infinity)

Returns: True, if succeeded

See also: isInitialized().

◆ isAvcc()

static bool Ocean::Media::Android::VideoDecoder::isAvcc	(	const void *	data,
		const size_t	size,
		const bool	isCodecConfig = `false`
	)

static

Determines whether the given data is in AVCC format (length prefixed) or Annex B format (start code prefixed).

AVCC format uses 4-byte big-endian length prefixes before each NAL unit. Annex B format uses start codes (0x00 0x00 0x00 0x01 or 0x00 0x00 0x01) to delimit NAL units.

Note: For codec configuration data, use isCodecConfig=true as AVCC config starts with version byte 0x01. For regular NAL unit samples, use isCodecConfig=false which applies more sophisticated detection to distinguish AVCC length prefixes from Annex B start codes (especially for NAL sizes 256-511 bytes where the length prefix 0x00 0x00 0x01 XX looks like an Annex B 3-byte start code).

Parameters

data	The data to check, must be valid
size	The size of the data in bytes, with range [4, infinity)
isCodecConfig	True if the data is codec configuration (SPS/PPS), false for regular NAL samples

Returns: True if the data is in AVCC format; false if it's in Annex B format

◆ isInitialized()

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

inline

Returns whether this decode is initialized.

Returns: True, if so

See also: initialize().

◆ isStarted()

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

inline

Returns whether this decoder is currently running.

Returns: True, if so

See also: start().

◆ operator=() [1/2]

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

protecteddelete

Disabled copy operator.

Returns: Reference to this object

◆ operator=() [2/2]

VideoDecoder & Ocean::Media::Android::VideoDecoder::operator= ( VideoDecoder && videoDecoder )

inlinenoexcept

Move operator.

Parameters

videoDecoder The video decoder to be moved

Returns: Reference to this object

◆ popFrame()

Frame Ocean::Media::Android::VideoDecoder::popFrame ( int64_t * presentationTime = nullptr )

Optional the frame's presentation time will be returned, this is the presentation time which was used when the corresponding sample was provided in decodedSample().

Parameters

presentationTime Optional resulting presentation time in micro seconds, with range (-infinity, infinity)

Returns: The resulting frame, invalid if currently no decoded frame is available

See also: pushSample().

◆ pushSample()

bool Ocean::Media::Android::VideoDecoder::pushSample	(	const void *	data,
		const size_t	size,
		const uint64_t	presentationTime
	)

Adds a new media sample which needs to be decoded to the video decoder.

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

Parameters

data	The data of the encoded media sample, must be valid
size	The size of the encoded media sample, in bytes, with range [1, infinity)
presentationTime	The presentation time of the sample, in microseconds, with range [0, infinity)

Returns: True, if succeeded

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

◆ release()

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

Explicitly releases this video encoder.

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

◆ start()

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

Starts the video decoder.

Returns: True, if succeeded

See also: isStarted().

◆ stop()

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

Stops the video decoder.

Returns: True, if succeeded

Field Documentation

◆ decoder_

NativeMediaLibrary::ScopedAMediaCodec Ocean::Media::Android::VideoDecoder::decoder_

protected

The Android media decoder used to decode the video.

◆ isStarted_

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

protected

True, if the decoder is currently started.

◆ lock_

Lock Ocean::Media::Android::VideoDecoder::lock_

mutableprotected

The decoder's lock.

◆ nativeMediaLibrarySubscription_

NativeMediaLibrary::ScopedSubscription Ocean::Media::Android::VideoDecoder::nativeMediaLibrarySubscription_

protected

The subscription for the native media library.

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

android/VideoDecoder.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VideoDecoder() [1/3]

◆ VideoDecoder() [2/3]

◆ ~VideoDecoder()

◆ VideoDecoder() [3/3]

Member Function Documentation

◆ convertAvccToAnnexB()

◆ extractVideoFrameFromCodecOutputBuffer()

◆ initialize()

◆ isAvcc()

◆ isInitialized()

◆ isStarted()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ popFrame()

◆ pushSample()

◆ release()

◆ start()

◆ stop()

Field Documentation

◆ decoder_

◆ isStarted_

◆ lock_

◆ nativeMediaLibrarySubscription_