OpenShot Library | libopenshot  0.2.5
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
openshot::Frame Class Reference

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 (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 AddMagickImage (std::shared_ptr< Magick::Image > new_image)
 Add (or replace) pixel data to the frame from an ImageMagick Image. 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 (int64_t number, int width, int height, std::string color)
 Constructor - image only. More...
 
 Frame (int64_t number, int samples, int channels)
 Constructor - audio only. More...
 
 Frame (int64_t number, int width, int height, std::string color, int samples, int channels)
 Constructor - image & audio. More...
 
 Frame (const Frame &other)
 Copy constructor. 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::AudioSampleBuffer * GetAudioSampleBuffer ()
 
float * GetAudioSamples (int channel)
 Get an array of sample data. 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...
 
float * GetInterleavedAudioSamples (int new_sample_rate, openshot::AudioResampler *resampler, int *sample_count)
 Get an array of sample data (all channels interleaved together), using any sample rate. More...
 
std::shared_ptr< Magick::Image > GetMagickImage ()
 Get pointer to ImageMagick image object. 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...
 
float * GetPlanarAudioSamples (int new_sample_rate, openshot::AudioResampler *resampler, int *sample_count)
 
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...
 
Frameoperator= (const Frame &other)
 Assignment operator. More...
 
void Play ()
 Play audio samples for this frame. 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 SetFrameNumber (int64_t number)
 Set frame number. 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)
 
virtual ~Frame ()
 Destructor. More...
 

Static Public Member Functions

static void cleanUpBuffer (void *info)
 Clean up buffer after QImage is deleted. More...
 
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

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)
// 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 98 of file Frame.h.

Constructor & Destructor Documentation

◆ Frame() [1/5]

Frame::Frame ( )

Constructor - blank frame.

Definition at line 69 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 72 of file Frame.cpp.

◆ Frame() [3/5]

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

Constructor - audio only.

Definition at line 76 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 55 of file Frame.cpp.

◆ Frame() [5/5]

Frame::Frame ( const Frame other)

Copy constructor.

Definition at line 81 of file Frame.cpp.

◆ ~Frame()

Frame::~Frame ( )
virtual

Destructor.

Definition at line 120 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 889 of file Frame.cpp.

◆ AddAudioSilence()

void Frame::AddAudioSilence ( int  numSamples)

Add audio silence.

Definition at line 1075 of file Frame.cpp.

◆ AddColor()

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 747 of file Frame.cpp.

Referenced by GetImage(), GetMagickImage(), 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 768 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 796 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 820 of file Frame.cpp.

◆ AddMagickImage()

void Frame::AddMagickImage ( std::shared_ptr< Magick::Image >  new_image)

Add (or replace) pixel data to the frame from an ImageMagick Image.

Use realloc for fast memory allocation. TODO: consider locking the buffer for mt safety

Definition at line 965 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 919 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 570 of file Frame.cpp.

◆ ChannelsLayout() [2/2]

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

Definition at line 178 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 487 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ cleanUpBuffer()

void Frame::cleanUpBuffer ( void *  info)
static

Clean up buffer after QImage is deleted.

Definition at line 1064 of file Frame.cpp.

Referenced by AddImage(), AddMagickImage(), and ChannelsLayout().

◆ ClearWaveform()

void Frame::ClearWaveform ( )

Clear the waveform image (and deallocate its memory)

Definition at line 265 of file Frame.cpp.

Referenced by ChannelsLayout(), DisplayWaveform(), and GetWaveform().

◆ DeepCopy()

void Frame::DeepCopy ( const Frame other)

Copy data and pointers from another Frame instance.

Definition at line 97 of file Frame.cpp.

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

◆ Display()

void Frame::Display ( )

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

Definition at line 127 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ DisplayWaveform()

void Frame::DisplayWaveform ( )

Display the wave form.

Definition at line 282 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetAudioChannelsCount()

int Frame::GetAudioChannelsCount ( )

Get number of audio channels.

Definition at line 426 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ 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 315 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetAudioSampleBuffer()

juce::AudioSampleBuffer * Frame::GetAudioSampleBuffer ( )

Definition at line 442 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetAudioSamples()

float * Frame::GetAudioSamples ( int  channel)

Get an array of sample data.

Definition at line 328 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetAudioSamplesCount()

int Frame::GetAudioSamplesCount ( )

Get number of audio samples.

Definition at line 436 of file Frame.cpp.

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

◆ GetBytes()

int64_t Frame::GetBytes ( )

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

Definition at line 448 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetHeight()

int Frame::GetHeight ( )

Get height of image.

Definition at line 552 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ GetImage()

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

Get pointer to Qt QImage image object.

Definition at line 928 of file Frame.cpp.

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

◆ GetInterleavedAudioSamples()

float * Frame::GetInterleavedAudioSamples ( int  new_sample_rate,
openshot::AudioResampler resampler,
int *  sample_count 
)

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

Definition at line 381 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetMagickImage()

std::shared_ptr< Magick::Image > Frame::GetMagickImage ( )

Get pointer to ImageMagick image object.

Definition at line 940 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetPixelRatio()

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

Set Pixel Aspect Ratio.

Definition at line 227 of file Frame.h.

◆ GetPixels() [1/2]

const unsigned char * Frame::GetPixels ( )

Get pixel data (as packets)

Definition at line 463 of file Frame.cpp.

Referenced by CheckPixel(), and GetPixelRatio().

◆ GetPixels() [2/2]

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

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

Definition at line 475 of file Frame.cpp.

◆ GetPlanarAudioSamples()

float * Frame::GetPlanarAudioSamples ( int  new_sample_rate,
openshot::AudioResampler resampler,
int *  sample_count 
)

Definition at line 335 of file Frame.cpp.

Referenced by ChannelsLayout().

◆ GetSamplesPerFrame() [1/2]

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

◆ GetSamplesPerFrame() [2/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 522 of file Frame.cpp.

◆ 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 169 of file Frame.cpp.

Referenced by DisplayWaveform(), GetPixelRatio(), 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 272 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ GetWidth()

int Frame::GetWidth ( )

Get height of image.

Definition at line 558 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ operator=()

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

Assignment operator.

Definition at line 88 of file Frame.cpp.

◆ Play()

void Frame::Play ( )

Play audio samples for this frame.

Definition at line 993 of file Frame.cpp.

Referenced by SampleRate().

◆ 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 875 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ SampleRate() [1/2]

int Frame::SampleRate ( )

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

Definition at line 564 of file Frame.cpp.

Referenced by GetPixelRatio().

◆ 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 263 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 577 of file Frame.cpp.

Referenced by SampleRate().

◆ SetFrameNumber()

void Frame::SetFrameNumber ( int64_t  number)

Set frame number.

Definition at line 516 of file Frame.cpp.

Referenced by SampleRate().

◆ SetPixelRatio()

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

Set Pixel Aspect Ratio.

Definition at line 509 of file Frame.cpp.

Referenced by SampleRate().

◆ 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 
)

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)

Definition at line 612 of file Frame.cpp.

Referenced by SampleRate().

Member Data Documentation

◆ has_audio_data

bool openshot::Frame::has_audio_data

This frame has been loaded with audio data.

Definition at line 122 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 123 of file Frame.h.

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

◆ number

int64_t openshot::Frame::number

This is the frame number (starting at 1)

Definition at line 121 of file Frame.h.

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


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