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, string 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...
ChannelLayout | ChannelsLayout ()
void | ChannelsLayout (ChannelLayout new_channel_layout)
void | ClearWaveform ()
| Clear the waveform image (and deallocate it's 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 (300x200 blank image, 48kHz audio silence) More...
| Frame (int64_t number, int width, int height, string color)
| Constructor - image only (48kHz audio silence) More...
| Frame (int64_t number, int samples, int channels)
| Constructor - audio only (300x200 blank image) More...
| Frame (int64_t number, int width, int height, 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, AudioResampler *resampler, int *sample_count)
| Get an array of sample data (all channels interleaved together), using any sample rate. More...
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, AudioResampler *resampler, int *sample_count)
int | GetSamplesPerFrame (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...
void | Play ()
| Play audio samples for this frame. More...
void | ResizeAudio (int channels, int length, int sample_rate, 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 (string path, float scale, 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 (string path, int new_width, int new_height, string mask_path, string overlay_path, string background_color, bool ignore_aspect, string format="png", int quality=100)
| ~Frame ()
| Assignment operator. 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, 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 (300x200 blank image, 48kHz audio silence)
Frame();
// Image only settings (48kHz audio silence)
Frame(1, // Frame number
720, // Width of image
480, // Height of image
"#000000" // HTML color code of background color
);
// Audio only (300x200 blank image)
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.
std::shared_ptr<Frame> f(new Frame(1, 720, 480, "#000000", 44100, 2));

Definition at line 115 of file Frame.h.

## Constructor & Destructor Documentation

## Frame() [1/5]

Frame::Frame | ( |  | ) |

Constructor - blank frame (300x200 blank image, 48kHz audio silence)

Definition at line 34 of file Frame.cpp.

## Frame() [2/5]

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

Constructor - image only (48kHz audio silence)

Definition at line 45 of file Frame.cpp.

## Frame() [3/5]

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

Constructor - audio only (300x200 blank image)

Definition at line 57 of file Frame.cpp.

## Frame() [4/5]

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

Constructor - image & audio.

Definition at line 69 of file Frame.cpp.

## Frame() [5/5]

Frame::Frame | ( | const Frame & | other | ) |

Copy constructor.

Definition at line 82 of file Frame.cpp.

## ~Frame()

Frame::~Frame | ( |  | ) |

Assignment operator.

Destructor

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

## AddAudioSilence()

void Frame::AddAudioSilence | ( | int | numSamples | ) |

Add audio silence.

Definition at line 987 of file Frame.cpp.

## AddColor()

void Frame::AddColor | ( | int | new_width,
|  | int | new_height,
|  | string | color
| ) |  |

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

Definition at line 681 of file Frame.cpp.

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

## AddImage() [2/3]

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

Add (or replace) pixel data to the frame.

Definition at line 726 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 750 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 831 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 529 of file Frame.cpp.

## ChannelsLayout() [2/2]

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

inline

Definition at line 192 of file Frame.h.

## cleanUpBuffer()

void Frame::cleanUpBuffer | ( | void * | info | ) |

static

Clean up buffer after QImage is deleted.

Definition at line 976 of file Frame.cpp.

## ClearWaveform()

void Frame::ClearWaveform | ( |  | ) |

Clear the waveform image (and deallocate it's memory)

Definition at line 250 of file Frame.cpp.

## DeepCopy()

void Frame::DeepCopy | ( | const Frame & | other | ) |

Copy data and pointers from another Frame instance.

Definition at line 89 of file Frame.cpp.

## Display()

void Frame::Display | ( |  | ) |

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

Definition at line 114 of file Frame.cpp.

## DisplayWaveform()

void Frame::DisplayWaveform | ( |  | ) |

Display the wave form.

Definition at line 267 of file Frame.cpp.

## GetAudioChannelsCount()

int Frame::GetAudioChannelsCount | ( |  | ) |

Get number of audio channels.

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

## GetAudioSampleBuffer()

juce::AudioSampleBuffer * Frame::GetAudioSampleBuffer | ( |  | ) |

Definition at line 430 of file Frame.cpp.

## GetAudioSamples()

float * Frame::GetAudioSamples | ( | int | channel | ) |

Get an array of sample data.

Definition at line 313 of file Frame.cpp.

## GetAudioSamplesCount()

int Frame::GetAudioSamplesCount | ( |  | ) |

Get number of audio samples.

Definition at line 421 of file Frame.cpp.

## GetBytes()

int64_t Frame::GetBytes | ( |  | ) |

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

Definition at line 436 of file Frame.cpp.

## GetHeight()

int Frame::GetHeight | ( |  | ) |

Get height of image.

Definition at line 511 of file Frame.cpp.

## GetImage()

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

Get pointer to Qt QImage image object.

Definition at line 840 of file Frame.cpp.

## GetInterleavedAudioSamples()

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

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

Definition at line 366 of file Frame.cpp.

## GetPixelRatio()

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

inline

Set Pixel Aspect Ratio.

Definition at line 241 of file Frame.h.

## GetPixels() [1/2]

const unsigned char * Frame::GetPixels | ( |  | ) |

Get pixel data (as packets)

Definition at line 451 of file Frame.cpp.

## GetPixels() [2/2]

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

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

Definition at line 463 of file Frame.cpp.

## GetPlanarAudioSamples()

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

Definition at line 320 of file Frame.cpp.

## GetSamplesPerFrame() [1/2]

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

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

Definition at line 505 of file Frame.cpp.

## GetSamplesPerFrame() [2/2]

int Frame::GetSamplesPerFrame | ( | int64_t | frame_number,
|  | 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 483 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 155 of file Frame.cpp.

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

## GetWidth()

int Frame::GetWidth | ( |  | ) |

Get height of image.

Definition at line 517 of file Frame.cpp.

## Play()

void Frame::Play | ( |  | ) |

Play audio samples for this frame.

Definition at line 910 of file Frame.cpp.

## ResizeAudio()

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

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

Definition at line 797 of file Frame.cpp.

## SampleRate() [1/2]

int Frame::SampleRate | ( |  | ) |

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

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

## Save()

void Frame::Save | ( | string | path,
|  | float | scale,
|  | 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 536 of file Frame.cpp.

## SetFrameNumber()

void Frame::SetFrameNumber | ( | int64_t | number | ) |

Set frame number.

Definition at line 477 of file Frame.cpp.

## SetPixelRatio()

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

Set Pixel Aspect Ratio.

Definition at line 470 of file Frame.cpp.

## Thumbnail()

void Frame::Thumbnail | ( | string | path,
|  | int | new_width,
|  | int | new_height,
|  | string | mask_path,
|  | string | overlay_path,
|  | string | background_color,
|  | bool | ignore_aspect,
|  | string | format = `"png"`,
|  | int | quality = `100`
| ) |  |

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

## Member Data Documentation

## has_audio_data

bool openshot::Frame::has_audio_data

This frame has been loaded with audio data.

Definition at line 137 of file Frame.h.

## has_image_data

bool openshot::Frame::has_image_data

This frame has been loaded with pixel data.

Definition at line 138 of file Frame.h.

## number

int64_t openshot::Frame::number

This is the frame number (starting at 1)

Definition at line 136 of file Frame.h.

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

- Frame.h
- Frame.cpp