This class represents a single frame of video (i.e. image & audio data) More...

#include <Frame.h>

Public Member Functions
void	AddAudio (bool replaceSamples, int destChannel, int destStartSample, const float *source, int numSamples, float gainToApplyToSource)
	Add audio samples to a specific channel. More...

void	AddAudioSilence (int numSamples)
	Add audio silence. More...

void	AddColor (const QColor &new_color)
	Add (or replace) pixel data (filled with new_color) More...

void	AddColor (int new_width, int new_height, std::string new_color)
	Add (or replace) pixel data to the frame (based on a solid color) More...

void	AddImage (int new_width, int new_height, int bytes_per_pixel, QImage::Format type, const unsigned char *pixels_)
	Add (or replace) pixel data to the frame. More...

void	AddImage (std::shared_ptr< QImage > new_image)
	Add (or replace) pixel data to the frame. More...

void	AddImage (std::shared_ptr< QImage > new_image, bool only_odd_lines)
	Add (or replace) pixel data to the frame (for only the odd or even lines) More...

void	ApplyGainRamp (int destChannel, int destStartSample, int numSamples, float initial_gain, float final_gain)
	Apply gain ramp (i.e. fading volume) More...

openshot::ChannelLayout	ChannelsLayout ()

void	ChannelsLayout (openshot::ChannelLayout new_channel_layout)

bool	CheckPixel (int row, int col, int red, int green, int blue, int alpha, int threshold)
	Check a specific pixel color value (returns True/False) More...

void	ClearWaveform ()
	Clear the waveform image (and deallocate its memory) More...

void	DeepCopy (const Frame &other)
	Copy data and pointers from another Frame instance. More...

void	Display ()
	Display the frame image to the screen (primarily used for debugging reasons) More...

void	DisplayWaveform ()
	Display the wave form. More...

	Frame ()
	Constructor - blank frame. More...

	Frame (const Frame &other)
	Copy constructor. More...

	Frame (int64_t number, int samples, int channels)
	Constructor - audio only. More...

	Frame (int64_t number, int width, int height, std::string color)
	Constructor - image only. More...

	Frame (int64_t number, int width, int height, std::string color, int samples, int channels)
	Constructor - image & audio. More...

int	GetAudioChannelsCount ()
	Get number of audio channels. More...

float	GetAudioSample (int channel, int sample, int magnitude_range)
	Get magnitude of range of samples (if channel is -1, return average of all channels for that sample) More...

juce::AudioBuffer< float > *	GetAudioSampleBuffer ()

float *	GetAudioSamples (int channel)
	Get an array of sample data (and optional reverse the sample values) More...

int	GetAudioSamplesCount ()
	Get number of audio samples. More...

int64_t	GetBytes ()
	Get the size in bytes of this frame (rough estimate) More...

int	GetHeight ()
	Get height of image. More...

std::shared_ptr< QImage >	GetImage ()
	Get pointer to Qt QImage image object. More...

cv::Mat	GetImageCV ()
	Get pointer to OpenCV Mat image object. More...

float *	GetInterleavedAudioSamples (int *sample_count)
	Get an array of sample data (all channels interleaved together), using any sample rate. More...

openshot::Fraction	GetPixelRatio ()
	Set Pixel Aspect Ratio. More...

const unsigned char *	GetPixels ()
	Get pixel data (as packets) More...

const unsigned char *	GetPixels (int row)
	Get pixel data (for only a single scan-line) More...

int	GetSamplesPerFrame (openshot::Fraction fps, int sample_rate, int channels)
	Calculate the # of samples per video frame (for the current frame number) More...

std::shared_ptr< QImage >	GetWaveform (int width, int height, int Red, int Green, int Blue, int Alpha)
	Get an audio waveform image. More...

const unsigned char *	GetWaveformPixels (int width, int height, int Red, int Green, int Blue, int Alpha)
	Get an audio waveform image pixels. More...

int	GetWidth ()
	Get height of image. More...

std::shared_ptr< QImage >	Mat2Qimage (cv::Mat img)
	Convert OpenCV Mat to QImage. More...

Frame &	operator= (const Frame &other)
	Assignment operator. More...

void	Play ()
	Play audio samples for this frame. More...

cv::Mat	Qimage2mat (std::shared_ptr< QImage > &qimage)
	Convert Qimage to Mat. More...

void	ResizeAudio (int channels, int length, int sample_rate, openshot::ChannelLayout channel_layout)
	Resize audio container to hold more (or less) samples and channels. More...

int	SampleRate ()
	Get the original sample rate of this frame's audio data. More...

void	SampleRate (int orig_sample_rate)
	Set the original sample rate of this frame's audio data. More...

void	Save (std::string path, float scale, std::string format="PNG", int quality=100)
	Save the frame image to the specified path. The image format can be BMP, JPG, JPEG, PNG, PPM, XBM, XPM. More...

void	SetAudioDirection (bool is_increasing)
	Set the direction of the audio buffer of this frame. More...

void	SetFrameNumber (int64_t number)
	Set frame number. More...

void	SetImageCV (cv::Mat _image)
	Set pointer to OpenCV image object. More...

void	SetPixelRatio (int num, int den)
	Set Pixel Aspect Ratio. More...

void	Thumbnail (std::string path, int new_width, int new_height, std::string mask_path, std::string overlay_path, std::string background_color, bool ignore_aspect, std::string format="png", int quality=100, float rotate=0.0, ScaleType scale_mode=SCALE_FIT)

virtual	~Frame ()
	Destructor. More...

Static Public Member Functions
static int	GetSamplesPerFrame (int64_t frame_number, openshot::Fraction fps, int sample_rate, int channels)
	Calculate the # of samples per video frame (for a specific frame number and frame rate) More...

Public Attributes
std::shared_ptr< juce::AudioBuffer< float > >	audio

double	capture_timestamp
	Optional source capture timestamp in seconds for live capture frames. More...

bool	has_audio_data
	This frame has been loaded with audio data. More...

bool	has_image_data
	This frame has been loaded with pixel data. More...

int64_t	number
	This is the frame number (starting at 1) More...

Detailed Description

This class represents a single frame of video (i.e. image & audio data)

FileReaders (such as FFmpegReader) use instances of this class to store the individual frames of video, which include both the image data (i.e. pixels) and audio samples. An openshot::Frame also has many debug methods, such as the ability to display the image (using X11), play the audio samples (using JUCE), or display the audio waveform as an image.

FileWriters (such as FFmpegWriter) use instances of this class to create new video files, image files, or video streams. So, think of these openshot::Frame instances as the smallest unit of work in a video editor.

There are many ways to create an instance of an openshot::Frame:

// Most basic: a blank frame (all default values)
Frame();
 
// Image only settings
Frame(1, // Frame number
    720, // Width of image
    480, // Height of image
    "#000000" // HTML color code of background color
    );
 
// Audio only
Frame(number, // Frame number
    44100, // Sample rate of audio stream
    2 // Number of audio channels
    );
 
// Image and Audio settings (user defines all key settings)
Frame(number, // Frame number
    720, // Width of image
    480, // Height of image
    "#000000" // HTML color code of background color
    44100, // Sample rate of audio stream
    2 // Number of audio channels
    );
 
// Some methods require a shared pointer to an openshot::Frame object.
auto f = std::make_shared<openshot::Frame>(1, 720, 480, "#000000", 44100, 2);

Definition at line 89 of file Frame.h.

Constructor & Destructor Documentation

◆ Frame() [1/5]

Frame::Frame ( )

Constructor - blank frame.

Definition at line 59 of file Frame.cpp.

◆ Frame() [2/5]

Frame::Frame	(	int64_t	number,
		int	width,
		int	height,
		std::string	color
	)

Constructor - image only.

Definition at line 62 of file Frame.cpp.

◆ Frame() [3/5]

Frame::Frame	(	int64_t	number,
		int	samples,
		int	channels
	)

Constructor - audio only.

Definition at line 66 of file Frame.cpp.

◆ Frame() [4/5]

Frame::Frame	(	int64_t	number,
		int	width,
		int	height,
		std::string	color,
		int	samples,
		int	channels
	)

Constructor - image & audio.

Definition at line 45 of file Frame.cpp.

◆ Frame() [5/5]

Frame::Frame ( const Frame & other )

Copy constructor.

Definition at line 71 of file Frame.cpp.

◆ ~Frame()

Frame::~Frame ( )

virtual

Destructor.

Definition at line 112 of file Frame.cpp.

Member Function Documentation

◆ AddAudio()

void Frame::AddAudio	(	bool	replaceSamples,
		int	destChannel,
		int	destStartSample,
		const float *	source,
		int	numSamples,
		float	gainToApplyToSource = `1.0f`
	)

Add audio samples to a specific channel.

Definition at line 832 of file Frame.cpp.

◆ AddAudioSilence()

void Frame::AddAudioSilence ( int numSamples )

Add audio silence.

Definition at line 1003 of file Frame.cpp.

◆ AddColor() [1/2]

void Frame::AddColor ( const QColor & new_color )

Add (or replace) pixel data (filled with new_color)

Definition at line 702 of file Frame.cpp.

◆ AddColor() [2/2]

void Frame::AddColor	(	int	new_width,
		int	new_height,
		std::string	new_color
	)

Add (or replace) pixel data to the frame (based on a solid color)

Definition at line 691 of file Frame.cpp.

Referenced by GetImage(), GetImageCV(), and GetPixels().

◆ AddImage() [1/3]

void Frame::AddImage	(	int	new_width,
		int	new_height,
		int	bytes_per_pixel,
		QImage::Format	type,
		const unsigned char *	pixels_
	)

Add (or replace) pixel data to the frame.

Definition at line 714 of file Frame.cpp.

Referenced by AddImage().

◆ AddImage() [2/3]

void Frame::AddImage ( std::shared_ptr< QImage > new_image )

Add (or replace) pixel data to the frame.

Definition at line 736 of file Frame.cpp.

◆ AddImage() [3/3]

void Frame::AddImage	(	std::shared_ptr< QImage >	new_image,
		bool	only_odd_lines
	)

Add (or replace) pixel data to the frame (for only the odd or even lines)

Definition at line 757 of file Frame.cpp.

◆ ApplyGainRamp()

void Frame::ApplyGainRamp	(	int	destChannel,
		int	destStartSample,
		int	numSamples,
		float	initial_gain = `0.0f`,
		float	final_gain = `1.0f`
	)

Apply gain ramp (i.e. fading volume)

Definition at line 863 of file Frame.cpp.

◆ ChannelsLayout() [1/2]

ChannelLayout Frame::ChannelsLayout ( )

Channel Layout of audio samples. A frame needs to keep track of this, since Writers do not always know the original channel layout of a frame's audio samples (i.e. mono, stereo, 5 point surround, etc...)

Definition at line 510 of file Frame.cpp.

◆ ChannelsLayout() [2/2]

void openshot::Frame::ChannelsLayout ( openshot::ChannelLayout new_channel_layout )

inline

Definition at line 173 of file Frame.h.

◆ CheckPixel()

bool Frame::CheckPixel	(	int	row,
		int	col,
		int	red,
		int	green,
		int	blue,
		int	alpha,
		int	threshold
	)

Check a specific pixel color value (returns True/False)

Definition at line 423 of file Frame.cpp.

◆ ClearWaveform()

void Frame::ClearWaveform ( )

Clear the waveform image (and deallocate its memory)

Definition at line 253 of file Frame.cpp.

Referenced by DisplayWaveform(), and GetWaveform().

◆ DeepCopy()

void Frame::DeepCopy ( const Frame & other )

Copy data and pointers from another Frame instance.

Definition at line 87 of file Frame.cpp.

Referenced by Frame(), and operator=().

◆ Display()

void Frame::Display ( )

Display the frame image to the screen (primarily used for debugging reasons)

Definition at line 122 of file Frame.cpp.

◆ DisplayWaveform()

void Frame::DisplayWaveform ( )

Display the wave form.

Definition at line 270 of file Frame.cpp.

◆ GetAudioChannelsCount()

int Frame::GetAudioChannelsCount ( )

Get number of audio channels.

Definition at line 360 of file Frame.cpp.

◆ GetAudioSample()

float Frame::GetAudioSample	(	int	channel,
		int	sample,
		int	magnitude_range
	)

Get magnitude of range of samples (if channel is -1, return average of all channels for that sample)

Definition at line 303 of file Frame.cpp.

◆ GetAudioSampleBuffer()

juce::AudioBuffer< float > * Frame::GetAudioSampleBuffer ( )

Definition at line 376 of file Frame.cpp.

◆ GetAudioSamples()

float * Frame::GetAudioSamples ( int channel )

Get an array of sample data (and optional reverse the sample values)

Definition at line 316 of file Frame.cpp.

◆ GetAudioSamplesCount()

int Frame::GetAudioSamplesCount ( )

Get number of audio samples.

Definition at line 370 of file Frame.cpp.

Referenced by GetInterleavedAudioSamples(), GetWaveform(), and Play().

◆ GetBytes()

int64_t Frame::GetBytes ( )

Get the size in bytes of this frame (rough estimate)

Definition at line 382 of file Frame.cpp.

◆ GetHeight()

int Frame::GetHeight ( )

Get height of image.

Definition at line 492 of file Frame.cpp.

◆ GetImage()

std::shared_ptr< QImage > Frame::GetImage ( )

Get pointer to Qt QImage image object.

Definition at line 872 of file Frame.cpp.

Referenced by Display(), Save(), and Thumbnail().

◆ GetImageCV()

cv::Mat Frame::GetImageCV ( )

Get pointer to OpenCV Mat image object.

Definition at line 896 of file Frame.cpp.

◆ GetInterleavedAudioSamples()

float * Frame::GetInterleavedAudioSamples ( int * sample_count )

Get an array of sample data (all channels interleaved together), using any sample rate.

Definition at line 326 of file Frame.cpp.

◆ GetPixelRatio()

openshot::Fraction openshot::Frame::GetPixelRatio ( )

inline

Set Pixel Aspect Ratio.

Definition at line 211 of file Frame.h.

◆ GetPixels() [1/2]

const unsigned char * Frame::GetPixels ( )

Get pixel data (as packets)

Definition at line 399 of file Frame.cpp.

Referenced by CheckPixel().

◆ GetPixels() [2/2]

const unsigned char * Frame::GetPixels ( int row )

Get pixel data (for only a single scan-line)

Definition at line 411 of file Frame.cpp.

◆ GetSamplesPerFrame() [1/2]

int Frame::GetSamplesPerFrame	(	int64_t	frame_number,
		openshot::Fraction	fps,
		int	sample_rate,
		int	channels
	)

static

Calculate the # of samples per video frame (for a specific frame number and frame rate)

Definition at line 458 of file Frame.cpp.

◆ GetSamplesPerFrame() [2/2]

int Frame::GetSamplesPerFrame	(	openshot::Fraction	fps,
		int	sample_rate,
		int	channels
	)

Calculate the # of samples per video frame (for the current frame number)

Definition at line 486 of file Frame.cpp.

Referenced by openshot::SampleRange::Extend(), openshot::QtHtmlReader::GetFrame(), openshot::QtTextReader::GetFrame(), openshot::QtImageReader::GetFrame(), openshot::FrameMapper::GetFrame(), openshot::Timeline::GetFrame(), and openshot::SampleRange::Shrink().

◆ GetWaveform()

std::shared_ptr< QImage > Frame::GetWaveform	(	int	width,
		int	height,
		int	Red,
		int	Green,
		int	Blue,
		int	Alpha
	)

Get an audio waveform image.

Definition at line 161 of file Frame.cpp.

Referenced by DisplayWaveform(), and GetWaveformPixels().

◆ GetWaveformPixels()

const unsigned char * Frame::GetWaveformPixels	(	int	width,
		int	height,
		int	Red,
		int	Green,
		int	Blue,
		int	Alpha
	)

Get an audio waveform image pixels.

Definition at line 260 of file Frame.cpp.

◆ GetWidth()

int Frame::GetWidth ( )

Get height of image.

Definition at line 498 of file Frame.cpp.

◆ Mat2Qimage()

std::shared_ptr< QImage > Frame::Mat2Qimage ( cv::Mat img )

Convert OpenCV Mat to QImage.

Definition at line 910 of file Frame.cpp.

Referenced by SetImageCV().

◆ operator=()

Frame & Frame::operator= ( const Frame & other )

Assignment operator.

Definition at line 78 of file Frame.cpp.

◆ Play()

void Frame::Play ( )

Play audio samples for this frame.

Definition at line 932 of file Frame.cpp.

◆ Qimage2mat()

cv::Mat Frame::Qimage2mat ( std::shared_ptr< QImage > & qimage )

Convert Qimage to Mat.

Definition at line 885 of file Frame.cpp.

Referenced by GetImageCV().

◆ ResizeAudio()

void Frame::ResizeAudio	(	int	channels,
		int	length,
		int	sample_rate,
		openshot::ChannelLayout	channel_layout
	)

Resize audio container to hold more (or less) samples and channels.

Definition at line 806 of file Frame.cpp.

◆ SampleRate() [1/2]

int Frame::SampleRate ( )

Get the original sample rate of this frame's audio data.

Definition at line 504 of file Frame.cpp.

◆ SampleRate() [2/2]

void openshot::Frame::SampleRate ( int orig_sample_rate )

inline

Set the original sample rate of this frame's audio data.

Definition at line 247 of file Frame.h.

◆ Save()

void Frame::Save	(	std::string	path,
		float	scale,
		std::string	format = `"PNG"`,
		int	quality = `100`
	)

Save the frame image to the specified path. The image format can be BMP, JPG, JPEG, PNG, PPM, XBM, XPM.

Definition at line 517 of file Frame.cpp.

◆ SetAudioDirection()

void Frame::SetAudioDirection ( bool is_increasing )

Set the direction of the audio buffer of this frame.

Definition at line 820 of file Frame.cpp.

◆ SetFrameNumber()

void Frame::SetFrameNumber ( int64_t number )

Set frame number.

Definition at line 452 of file Frame.cpp.

◆ SetImageCV()

void Frame::SetImageCV ( cv::Mat _image )

Set pointer to OpenCV image object.

Definition at line 924 of file Frame.cpp.

◆ SetPixelRatio()

void Frame::SetPixelRatio	(	int	num,
		int	den
	)

Set Pixel Aspect Ratio.

Definition at line 445 of file Frame.cpp.

◆ Thumbnail()

void Frame::Thumbnail	(	std::string	path,
		int	new_width,
		int	new_height,
		std::string	mask_path,
		std::string	overlay_path,
		std::string	background_color,
		bool	ignore_aspect,
		std::string	format = `"png"`,
		int	quality = `100`,
		float	rotate = `0.0`,
		ScaleType	scale_mode = `SCALE_FIT`
	)

Thumbnail the frame image with tons of options to the specified path. The image format is determined from the extension (i.e. image.PNG, image.JPEG). This method allows for masks, overlays, background color, and much more accurate resizing (including padding and centering). A trailing optional scale mode can force FIT / CROP / STRETCH behavior while preserving legacy behavior for existing callers.

Definition at line 545 of file Frame.cpp.

Member Data Documentation

◆ audio

std::shared_ptr<juce::AudioBuffer<float> > openshot::Frame::audio

Definition at line 116 of file Frame.h.

Referenced by AddAudio(), AddAudioSilence(), ApplyGainRamp(), DeepCopy(), Frame(), GetAudioChannelsCount(), GetAudioSample(), GetAudioSampleBuffer(), GetAudioSamples(), GetBytes(), GetInterleavedAudioSamples(), GetWaveform(), Play(), ResizeAudio(), SetAudioDirection(), and ~Frame().

◆ capture_timestamp

double openshot::Frame::capture_timestamp

Optional source capture timestamp in seconds for live capture frames.

Definition at line 118 of file Frame.h.

Referenced by DeepCopy().

◆ has_audio_data

bool openshot::Frame::has_audio_data

This frame has been loaded with audio data.

Definition at line 119 of file Frame.h.

Referenced by AddAudio(), AddAudioSilence(), and DeepCopy().

◆ has_image_data

bool openshot::Frame::has_image_data

This frame has been loaded with pixel data.

Definition at line 120 of file Frame.h.

Referenced by AddColor(), AddImage(), and DeepCopy().

◆ number

int64_t openshot::Frame::number

This is the frame number (starting at 1)

Definition at line 117 of file Frame.h.

Referenced by DeepCopy(), GetSamplesPerFrame(), and SetFrameNumber().

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

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Frame() [1/5]

◆ Frame() [2/5]

◆ Frame() [3/5]

◆ Frame() [4/5]

◆ Frame() [5/5]

◆ ~Frame()

Member Function Documentation

◆ AddAudio()

◆ AddAudioSilence()

◆ AddColor() [1/2]

◆ AddColor() [2/2]

◆ AddImage() [1/3]

◆ AddImage() [2/3]

◆ AddImage() [3/3]

◆ ApplyGainRamp()

◆ ChannelsLayout() [1/2]

◆ ChannelsLayout() [2/2]

◆ CheckPixel()

◆ ClearWaveform()

◆ DeepCopy()

◆ Display()

◆ DisplayWaveform()

◆ GetAudioChannelsCount()

◆ GetAudioSample()

◆ GetAudioSampleBuffer()

◆ GetAudioSamples()

◆ GetAudioSamplesCount()

◆ GetBytes()

◆ GetHeight()

◆ GetImage()

◆ GetImageCV()

◆ GetInterleavedAudioSamples()

◆ GetPixelRatio()

◆ GetPixels() [1/2]

◆ GetPixels() [2/2]

◆ GetSamplesPerFrame() [1/2]

◆ GetSamplesPerFrame() [2/2]

◆ GetWaveform()

◆ GetWaveformPixels()

◆ GetWidth()

◆ Mat2Qimage()

◆ operator=()

◆ Play()

◆ Qimage2mat()

◆ ResizeAudio()

◆ SampleRate() [1/2]

◆ SampleRate() [2/2]

◆ Save()

◆ SetAudioDirection()

◆ SetFrameNumber()

◆ SetImageCV()

◆ SetPixelRatio()

◆ Thumbnail()

Member Data Documentation

◆ audio

◆ capture_timestamp

◆ has_audio_data

◆ has_image_data

◆ number