OpenShot Library | libopenshot  0.2.5
Clip.h
Go to the documentation of this file.
1 /**
2  * @file
3  * @brief Header file for Clip class
4  * @author Jonathan Thomas <jonathan@openshot.org>
5  *
6  * @ref License
7  */
8 
9 /* LICENSE
10  *
11  * Copyright (c) 2008-2019 OpenShot Studios, LLC
12  * <http://www.openshotstudios.com/>. This file is part of
13  * OpenShot Library (libopenshot), an open-source project dedicated to
14  * delivering high quality video editing and animation solutions to the
15  * world. For more information visit <http://www.openshot.org/>.
16  *
17  * OpenShot Library (libopenshot) is free software: you can redistribute it
18  * and/or modify it under the terms of the GNU Lesser General Public License
19  * as published by the Free Software Foundation, either version 3 of the
20  * License, or (at your option) any later version.
21  *
22  * OpenShot Library (libopenshot) is distributed in the hope that it will be
23  * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25  * GNU Lesser General Public License for more details.
26  *
27  * You should have received a copy of the GNU Lesser General Public License
28  * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
29  */
30 
31 #ifndef OPENSHOT_CLIP_H
32 #define OPENSHOT_CLIP_H
33 
34 #include <memory>
35 #include <string>
36 #include <QtGui/QImage>
37 #include "AudioResampler.h"
38 #include "ClipBase.h"
39 #include "Color.h"
40 #include "Enums.h"
41 #include "EffectBase.h"
42 #include "Effects.h"
43 #include "EffectInfo.h"
44 #include "Fraction.h"
45 #include "KeyFrame.h"
46 #include "ReaderBase.h"
47 #include "JuceHeader.h"
48 
49 namespace openshot {
50 
51  /// Comparison method for sorting effect pointers (by Position, Layer, and Order). Effects are sorted
52  /// from lowest layer to top layer (since that is sequence clips are combined), and then by
53  /// position, and then by effect order.
56  if( lhs->Layer() < rhs->Layer() ) return true;
57  if( lhs->Layer() == rhs->Layer() && lhs->Position() < rhs->Position() ) return true;
58  if( lhs->Layer() == rhs->Layer() && lhs->Position() == rhs->Position() && lhs->Order() > rhs->Order() ) return true;
59  return false;
60  }};
61 
62  /**
63  * @brief This class represents a clip (used to arrange readers on the timeline)
64  *
65  * Each image, video, or audio file is represented on a layer as a clip. A clip has many
66  * properties that affect how it behaves on the timeline, such as its size, position,
67  * transparency, rotation, speed, volume, etc...
68  *
69  * @code
70  * // Create some clips
71  * Clip c1(new ImageReader("MyAwesomeLogo.jpeg"));
72  * Clip c2(new FFmpegReader("BackgroundVideo.webm"));
73  *
74  * // CLIP 1 (logo) - Set some clip properties (with openshot::Keyframes)
75  * c1.Position(0.0); // Set the position or location (in seconds) on the timeline
76  * c1.gravity = GRAVITY_LEFT; // Set the alignment / gravity of the clip (position on the screen)
77  * c1.scale = SCALE_CROP; // Set the scale mode (how the image is resized to fill the screen)
78  * c1.Layer(1); // Set the layer of the timeline (higher layers cover up images of lower layers)
79  * c1.Start(0.0); // Set the starting position of the video (trim the left side of the video)
80  * c1.End(16.0); // Set the ending position of the video (trim the right side of the video)
81  * c1.alpha.AddPoint(1, 0.0); // Set the alpha to transparent on frame #1
82  * c1.alpha.AddPoint(500, 0.0); // Keep the alpha transparent until frame #500
83  * c1.alpha.AddPoint(565, 1.0); // Animate the alpha from transparent to visible (between frame #501 and #565)
84  *
85  * // CLIP 2 (background video) - Set some clip properties (with openshot::Keyframes)
86  * c2.Position(0.0); // Set the position or location (in seconds) on the timeline
87  * c2.Start(10.0); // Set the starting position of the video (trim the left side of the video)
88  * c2.Layer(0); // Set the layer of the timeline (higher layers cover up images of lower layers)
89  * c2.alpha.AddPoint(1, 1.0); // Set the alpha to visible on frame #1
90  * c2.alpha.AddPoint(150, 0.0); // Animate the alpha to transparent (between frame 2 and frame #150)
91  * c2.alpha.AddPoint(360, 0.0, LINEAR); // Keep the alpha transparent until frame #360
92  * c2.alpha.AddPoint(384, 1.0); // Animate the alpha to visible (between frame #360 and frame #384)
93  * @endcode
94  */
95  class Clip : public openshot::ClipBase {
96  protected:
97  /// Section lock for multiple threads
98  juce::CriticalSection getFrameCriticalSection;
99 
100  private:
101  bool waveform; ///< Should a waveform be used instead of the clip's image
102  std::list<openshot::EffectBase*> effects; ///<List of clips on this timeline
103 
104  // Audio resampler (if time mapping)
105  openshot::AudioResampler *resampler;
106  juce::AudioSampleBuffer *audio_cache;
107 
108  // File Reader object
109  openshot::ReaderBase* reader;
110 
111  /// If we allocated a reader, we store it here to free it later
112  /// (reader member variable itself may have been replaced)
113  openshot::ReaderBase* allocated_reader;
114 
115  /// Adjust frame number minimum value
116  int64_t adjust_frame_number_minimum(int64_t frame_number);
117 
118  /// Apply effects to the source frame (if any)
119  std::shared_ptr<openshot::Frame> apply_effects(std::shared_ptr<openshot::Frame> frame);
120 
121  /// Get file extension
122  std::string get_file_extension(std::string path);
123 
124  /// Get a frame object or create a blank one
125  std::shared_ptr<openshot::Frame> GetOrCreateFrame(int64_t number);
126 
127  /// Adjust the audio and image of a time mapped frame
128  void get_time_mapped_frame(std::shared_ptr<openshot::Frame> frame, int64_t frame_number);
129 
130  /// Init default settings for a clip
131  void init_settings();
132 
133  /// Update default rotation from reader
134  void init_reader_rotation();
135 
136  /// Sort effects by order
137  void sort_effects();
138 
139  /// Reverse an audio buffer
140  void reverse_buffer(juce::AudioSampleBuffer* buffer);
141 
142  public:
143  openshot::GravityType gravity; ///< The gravity of a clip determines where it snaps to its parent
144  openshot::ScaleType scale; ///< The scale determines how a clip should be resized to fit its parent
145  openshot::AnchorType anchor; ///< The anchor determines what parent a clip should snap to
146  openshot::FrameDisplayType display; ///< The format to display the frame number (if any)
147  openshot::VolumeMixType mixing; ///< What strategy should be followed when mixing audio with other clips
148 
149  /// Default Constructor
150  Clip();
151 
152  /// @brief Constructor with filepath (reader is automatically created... by guessing file extensions)
153  /// @param path The path of a reader (video file, image file, etc...). The correct reader will be used automatically.
154  Clip(std::string path);
155 
156  /// @brief Constructor with reader
157  /// @param new_reader The reader to be used by this clip
158  Clip(openshot::ReaderBase* new_reader);
159 
160  /// Destructor
161  virtual ~Clip();
162 
163  /// @brief Add an effect to the clip
164  /// @param effect Add an effect to the clip. An effect can modify the audio or video of an openshot::Frame.
165  void AddEffect(openshot::EffectBase* effect);
166 
167  /// Close the internal reader
168  void Close();
169 
170  /// Return the list of effects on the timeline
171  std::list<openshot::EffectBase*> Effects() { return effects; };
172 
173  /// @brief Get an openshot::Frame object for a specific frame number of this timeline.
174  ///
175  /// @returns The requested frame (containing the image)
176  /// @param requested_frame The frame number that is requested
177  std::shared_ptr<openshot::Frame> GetFrame(int64_t requested_frame);
178 
179  /// Open the internal reader
180  void Open();
181 
182  /// @brief Set the current reader
183  /// @param new_reader The reader to be used by this clip
184  void Reader(openshot::ReaderBase* new_reader);
185 
186  /// Get the current reader
188 
189  /// Override End() method
190  float End() const; ///< Get end position (in seconds) of clip (trim end of video), which can be affected by the time curve.
191  void End(float value) { end = value; } ///< Set end position (in seconds) of clip (trim end of video)
192 
193  /// Get and Set JSON methods
194  std::string Json() const override; ///< Generate JSON string of this object
195  void SetJson(const std::string value); ///< Load JSON string into this object
196  Json::Value JsonValue() const override; ///< Generate Json::Value for this object
197  void SetJsonValue(const Json::Value root); ///< Load Json::Value into this object
198 
199  /// Get all properties for a specific frame (perfect for a UI to display the current state
200  /// of all properties at any time)
201  std::string PropertiesJSON(int64_t requested_frame) const override;
202 
203  /// @brief Remove an effect from the clip
204  /// @param effect Remove an effect from the clip.
205  void RemoveEffect(openshot::EffectBase* effect);
206 
207  /// Waveform property
208  bool Waveform() { return waveform; } ///< Get the waveform property of this clip
209  void Waveform(bool value) { waveform = value; } ///< Set the waveform property of this clip
210 
211  // Scale and Location curves
212  openshot::Keyframe scale_x; ///< Curve representing the horizontal scaling in percent (0 to 1)
213  openshot::Keyframe scale_y; ///< Curve representing the vertical scaling in percent (0 to 1)
214  openshot::Keyframe location_x; ///< Curve representing the relative X position in percent based on the gravity (-1 to 1)
215  openshot::Keyframe location_y; ///< Curve representing the relative Y position in percent based on the gravity (-1 to 1)
216 
217  // Alpha and Rotation curves
218  openshot::Keyframe alpha; ///< Curve representing the alpha (1 to 0)
219  openshot::Keyframe rotation; ///< Curve representing the rotation (0 to 360)
220 
221  // Time and Volume curves
222  openshot::Keyframe time; ///< Curve representing the frames over time to play (used for speed and direction of video)
223  openshot::Keyframe volume; ///< Curve representing the volume (0 to 1)
224 
225  /// Curve representing the color of the audio wave form
227 
228  // Crop settings and curves
229  openshot::GravityType crop_gravity; ///< Cropping needs to have a gravity to determine what side we are cropping
230  openshot::Keyframe crop_width; ///< Curve representing width in percent (0.0=0%, 1.0=100%)
231  openshot::Keyframe crop_height; ///< Curve representing height in percent (0.0=0%, 1.0=100%)
232  openshot::Keyframe crop_x; ///< Curve representing X offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
233  openshot::Keyframe crop_y; ///< Curve representing Y offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
234 
235  // Shear and perspective curves
236  openshot::Keyframe shear_x; ///< Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
237  openshot::Keyframe shear_y; ///< Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
238  openshot::Keyframe perspective_c1_x; ///< Curves representing X for coordinate 1
239  openshot::Keyframe perspective_c1_y; ///< Curves representing Y for coordinate 1
240  openshot::Keyframe perspective_c2_x; ///< Curves representing X for coordinate 2
241  openshot::Keyframe perspective_c2_y; ///< Curves representing Y for coordinate 2
242  openshot::Keyframe perspective_c3_x; ///< Curves representing X for coordinate 3
243  openshot::Keyframe perspective_c3_y; ///< Curves representing Y for coordinate 3
244  openshot::Keyframe perspective_c4_x; ///< Curves representing X for coordinate 4
245  openshot::Keyframe perspective_c4_y; ///< Curves representing Y for coordinate 4
246 
247  /// Audio channel filter and mappings
248  openshot::Keyframe channel_filter; ///< A number representing an audio channel to filter (clears all other channels)
249  openshot::Keyframe channel_mapping; ///< A number representing an audio channel to output (only works when filtering a channel)
250 
251  /// Override has_video and has_audio properties of clip (and their readers)
252  openshot::Keyframe has_audio; ///< An optional override to determine if this clip has audio (-1=undefined, 0=no, 1=yes)
253  openshot::Keyframe has_video; ///< An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
254  };
255 
256 
257 }
258 
259 #endif
openshot::Clip::crop_width
openshot::Keyframe crop_width
Curve representing width in percent (0.0=0%, 1.0=100%)
Definition: Clip.h:230
openshot::Clip::crop_height
openshot::Keyframe crop_height
Curve representing height in percent (0.0=0%, 1.0=100%)
Definition: Clip.h:231
openshot::EffectBase
This abstract class is the base class, used by all effects in libopenshot.
Definition: EffectBase.h:67
openshot::Clip::Open
void Open()
Open the internal reader.
Definition: Clip.cpp:242
openshot::Clip::anchor
openshot::AnchorType anchor
The anchor determines what parent a clip should snap to.
Definition: Clip.h:145
openshot::Clip::getFrameCriticalSection
juce::CriticalSection getFrameCriticalSection
Section lock for multiple threads.
Definition: Clip.h:98
Fraction.h
Header file for Fraction class.
openshot::Clip::crop_y
openshot::Keyframe crop_y
Curve representing Y offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:233
openshot::Clip::Close
void Close()
Close the internal reader.
Definition: Clip.cpp:259
openshot::Clip::crop_x
openshot::Keyframe crop_x
Curve representing X offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:232
openshot
This namespace is the default namespace for all code in the openshot library.
Definition: AudioBufferSource.h:39
openshot::Clip::scale_y
openshot::Keyframe scale_y
Curve representing the vertical scaling in percent (0 to 1)
Definition: Clip.h:213
openshot::Clip::PropertiesJSON
std::string PropertiesJSON(int64_t requested_frame) const override
Definition: Clip.cpp:655
openshot::Clip::time
openshot::Keyframe time
Curve representing the frames over time to play (used for speed and direction of video)
Definition: Clip.h:222
openshot::Clip
This class represents a clip (used to arrange readers on the timeline)
Definition: Clip.h:95
openshot::Clip::alpha
openshot::Keyframe alpha
Curve representing the alpha (1 to 0)
Definition: Clip.h:218
openshot::Clip::Waveform
bool Waveform()
Waveform property.
Definition: Clip.h:208
AudioResampler.h
Header file for AudioResampler class.
openshot::Clip::location_y
openshot::Keyframe location_y
Curve representing the relative Y position in percent based on the gravity (-1 to 1)
Definition: Clip.h:215
openshot::GravityType
GravityType
This enumeration determines how clips are aligned to their parent container.
Definition: Enums.h:39
openshot::Clip::Effects
std::list< openshot::EffectBase * > Effects()
Return the list of effects on the timeline.
Definition: Clip.h:171
openshot::Clip::channel_mapping
openshot::Keyframe channel_mapping
A number representing an audio channel to output (only works when filtering a channel)
Definition: Clip.h:249
openshot::Clip::AddEffect
void AddEffect(openshot::EffectBase *effect)
Add an effect to the clip.
Definition: Clip.cpp:991
openshot::Clip::~Clip
virtual ~Clip()
Destructor.
Definition: Clip.cpp:203
EffectBase.h
Header file for EffectBase class.
openshot::Clip::Json
std::string Json() const override
Get and Set JSON methods.
Definition: Clip.cpp:648
openshot::Clip::Waveform
void Waveform(bool value)
Set the waveform property of this clip.
Definition: Clip.h:209
KeyFrame.h
Header file for the Keyframe class.
openshot::CompareClipEffects
Definition: Clip.h:54
Effects.h
This header includes all commonly used effects for libopenshot, for ease-of-use.
openshot::ClipBase::Layer
int Layer() const
Get layer of clip on timeline (lower number is covered by higher numbers)
Definition: ClipBase.h:78
openshot::Color
This class represents a color (used on the timeline and clips)
Definition: Color.h:45
openshot::Clip::display
openshot::FrameDisplayType display
The format to display the frame number (if any)
Definition: Clip.h:146
openshot::Clip::perspective_c2_y
openshot::Keyframe perspective_c2_y
Curves representing Y for coordinate 2.
Definition: Clip.h:241
openshot::Clip::scale_x
openshot::Keyframe scale_x
Curve representing the horizontal scaling in percent (0 to 1)
Definition: Clip.h:212
openshot::AudioResampler
This class is used to resample audio data for many sequential frames.
Definition: AudioResampler.h:46
openshot::Clip::perspective_c3_y
openshot::Keyframe perspective_c3_y
Curves representing Y for coordinate 3.
Definition: Clip.h:243
openshot::Clip::perspective_c4_y
openshot::Keyframe perspective_c4_y
Curves representing Y for coordinate 4.
Definition: Clip.h:245
openshot::Clip::has_video
openshot::Keyframe has_video
An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
Definition: Clip.h:253
openshot::Keyframe
A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
Definition: KeyFrame.h:64
openshot::Clip::gravity
openshot::GravityType gravity
The gravity of a clip determines where it snaps to its parent.
Definition: Clip.h:143
EffectInfo.h
Header file for the EffectInfo class.
openshot::Clip::SetJsonValue
void SetJsonValue(const Json::Value root)
Load Json::Value into this object.
Definition: Clip.cpp:815
openshot::Clip::End
float End() const
Override End() method.
Definition: Clip.cpp:273
openshot::Clip::GetFrame
std::shared_ptr< openshot::Frame > GetFrame(int64_t requested_frame)
Get an openshot::Frame object for a specific frame number of this timeline.
Definition: Clip.cpp:295
openshot::Clip::perspective_c1_x
openshot::Keyframe perspective_c1_x
Curves representing X for coordinate 1.
Definition: Clip.h:238
openshot::Clip::End
void End(float value)
Set end position (in seconds) of clip (trim end of video)
Definition: Clip.h:191
openshot::Clip::crop_gravity
openshot::GravityType crop_gravity
Cropping needs to have a gravity to determine what side we are cropping.
Definition: Clip.h:229
openshot::ClipBase::end
float end
The position in seconds to end playing (used to trim the ending of a clip)
Definition: ClipBase.h:55
path
path
Definition: FFmpegWriter.cpp:1410
openshot::Clip::Reader
openshot::ReaderBase * Reader()
Get the current reader.
Definition: Clip.cpp:232
openshot::Clip::perspective_c2_x
openshot::Keyframe perspective_c2_x
Curves representing X for coordinate 2.
Definition: Clip.h:240
openshot::Clip::volume
openshot::Keyframe volume
Curve representing the volume (0 to 1)
Definition: Clip.h:223
openshot::EffectBase::Order
int Order() const
Get the order that this effect should be executed.
Definition: EffectBase.h:104
ReaderBase.h
Header file for ReaderBase class.
openshot::Clip::perspective_c4_x
openshot::Keyframe perspective_c4_x
Curves representing X for coordinate 4.
Definition: Clip.h:244
openshot::Clip::perspective_c1_y
openshot::Keyframe perspective_c1_y
Curves representing Y for coordinate 1.
Definition: Clip.h:239
openshot::Clip::channel_filter
openshot::Keyframe channel_filter
Audio channel filter and mappings.
Definition: Clip.h:248
Enums.h
Header file for TextReader class.
openshot::Clip::Clip
Clip()
Default Constructor.
Definition: Clip.cpp:134
openshot::ReaderBase
This abstract class is the base class, used by all readers in libopenshot.
Definition: ReaderBase.h:98
openshot::ClipBase::Position
float Position() const
Get position on timeline (in seconds)
Definition: ClipBase.h:77
openshot::Clip::scale
openshot::ScaleType scale
The scale determines how a clip should be resized to fit its parent.
Definition: Clip.h:144
Color.h
Header file for Color class.
openshot::AnchorType
AnchorType
This enumeration determines what parent a clip should be aligned to.
Definition: Enums.h:62
openshot::ScaleType
ScaleType
This enumeration determines how clips are scaled to fit their parent container.
Definition: Enums.h:53
openshot::Clip::has_audio
openshot::Keyframe has_audio
Override has_video and has_audio properties of clip (and their readers)
Definition: Clip.h:252
openshot::Clip::rotation
openshot::Keyframe rotation
Curve representing the rotation (0 to 360)
Definition: Clip.h:219
openshot::Clip::SetJson
void SetJson(const std::string value)
Load JSON string into this object.
Definition: Clip.cpp:798
openshot::CompareClipEffects::operator()
bool operator()(openshot::EffectBase *lhs, openshot::EffectBase *rhs)
Definition: Clip.h:55
openshot::Clip::JsonValue
Json::Value JsonValue() const override
Generate Json::Value for this object.
Definition: Clip.cpp:743
openshot::Clip::perspective_c3_x
openshot::Keyframe perspective_c3_x
Curves representing X for coordinate 3.
Definition: Clip.h:242
openshot::ClipBase
This abstract class is the base class, used by all clips in libopenshot.
Definition: ClipBase.h:49
openshot::VolumeMixType
VolumeMixType
This enumeration determines the strategy when mixing audio with other clips.
Definition: Enums.h:78
ClipBase.h
Header file for ClipBase class.
openshot::Clip::wave_color
openshot::Color wave_color
Curve representing the color of the audio wave form.
Definition: Clip.h:226
openshot::Clip::shear_y
openshot::Keyframe shear_y
Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
Definition: Clip.h:237
openshot::Clip::RemoveEffect
void RemoveEffect(openshot::EffectBase *effect)
Remove an effect from the clip.
Definition: Clip.cpp:1001
openshot::Clip::mixing
openshot::VolumeMixType mixing
What strategy should be followed when mixing audio with other clips.
Definition: Clip.h:147
openshot::Clip::shear_x
openshot::Keyframe shear_x
Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
Definition: Clip.h:236
openshot::Clip::location_x
openshot::Keyframe location_x
Curve representing the relative X position in percent based on the gravity (-1 to 1)
Definition: Clip.h:214
openshot::FrameDisplayType
FrameDisplayType
This enumeration determines the display format of the clip's frame number (if any)....
Definition: Enums.h:69