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
Header file for AudioResampler class.
Header file for ClipBase class.
Header file for Color class.
Header file for EffectBase class.
Header file for the EffectInfo class.
This header includes all commonly used effects for libopenshot, for ease-of-use.
Header file for TextReader class.
Header file for Fraction class.
Header file for the Keyframe class.
Header file for ReaderBase class.
This class is used to resample audio data for many sequential frames.
This abstract class is the base class, used by all clips in libopenshot.
Definition: ClipBase.h:49
int Layer() const
Get layer of clip on timeline (lower number is covered by higher numbers)
Definition: ClipBase.h:78
float Position() const
Get position on timeline (in seconds)
Definition: ClipBase.h:77
float end
The position in seconds to end playing (used to trim the ending of a clip)
Definition: ClipBase.h:55
This class represents a clip (used to arrange readers on the timeline)
Definition: Clip.h:95
openshot::Keyframe scale_x
Curve representing the horizontal scaling in percent (0 to 1)
Definition: Clip.h:212
openshot::Keyframe location_y
Curve representing the relative Y position in percent based on the gravity (-1 to 1)
Definition: Clip.h:215
std::list< openshot::EffectBase * > Effects()
Return the list of effects on the timeline.
Definition: Clip.h:171
openshot::Keyframe shear_x
Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
Definition: Clip.h:236
openshot::Keyframe perspective_c4_x
Curves representing X for coordinate 4.
Definition: Clip.h:244
openshot::AnchorType anchor
The anchor determines what parent a clip should snap to.
Definition: Clip.h:145
void SetJsonValue(const Json::Value root)
Load Json::Value into this object.
Definition: Clip.cpp:815
juce::CriticalSection getFrameCriticalSection
Section lock for multiple threads.
Definition: Clip.h:98
openshot::VolumeMixType mixing
What strategy should be followed when mixing audio with other clips.
Definition: Clip.h:147
openshot::Keyframe rotation
Curve representing the rotation (0 to 360)
Definition: Clip.h:219
openshot::Keyframe channel_filter
Audio channel filter and mappings.
Definition: Clip.h:248
openshot::GravityType crop_gravity
Cropping needs to have a gravity to determine what side we are cropping.
Definition: Clip.h:229
openshot::FrameDisplayType display
The format to display the frame number (if any)
Definition: Clip.h:146
Clip()
Default Constructor.
Definition: Clip.cpp:134
openshot::Keyframe crop_height
Curve representing height in percent (0.0=0%, 1.0=100%)
Definition: Clip.h:231
openshot::Keyframe perspective_c1_x
Curves representing X for coordinate 1.
Definition: Clip.h:238
float End() const
Override End() method.
Definition: Clip.cpp:273
openshot::Keyframe crop_width
Curve representing width in percent (0.0=0%, 1.0=100%)
Definition: Clip.h:230
std::string Json() const override
Get and Set JSON methods.
Definition: Clip.cpp:648
openshot::Keyframe alpha
Curve representing the alpha (1 to 0)
Definition: Clip.h:218
openshot::Keyframe has_audio
Override has_video and has_audio properties of clip (and their readers)
Definition: Clip.h:252
void Open()
Open the internal reader.
Definition: Clip.cpp:242
openshot::Keyframe perspective_c3_x
Curves representing X for coordinate 3.
Definition: Clip.h:242
openshot::Keyframe perspective_c1_y
Curves representing Y for coordinate 1.
Definition: Clip.h:239
Json::Value JsonValue() const override
Generate Json::Value for this object.
Definition: Clip.cpp:743
openshot::Keyframe crop_x
Curve representing X offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:232
openshot::Keyframe perspective_c4_y
Curves representing Y for coordinate 4.
Definition: Clip.h:245
openshot::Keyframe time
Curve representing the frames over time to play (used for speed and direction of video)
Definition: Clip.h:222
bool Waveform()
Waveform property.
Definition: Clip.h:208
void Close()
Close the internal reader.
Definition: Clip.cpp:259
void SetJson(const std::string value)
Load JSON string into this object.
Definition: Clip.cpp:798
openshot::GravityType gravity
The gravity of a clip determines where it snaps to its parent.
Definition: Clip.h:143
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::Keyframe perspective_c3_y
Curves representing Y for coordinate 3.
Definition: Clip.h:243
void AddEffect(openshot::EffectBase *effect)
Add an effect to the clip.
Definition: Clip.cpp:991
void Waveform(bool value)
Set the waveform property of this clip.
Definition: Clip.h:209
virtual ~Clip()
Destructor.
Definition: Clip.cpp:203
openshot::Keyframe perspective_c2_y
Curves representing Y for coordinate 2.
Definition: Clip.h:241
openshot::Keyframe volume
Curve representing the volume (0 to 1)
Definition: Clip.h:223
openshot::Keyframe shear_y
Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
Definition: Clip.h:237
openshot::Keyframe scale_y
Curve representing the vertical scaling in percent (0 to 1)
Definition: Clip.h:213
openshot::ReaderBase * Reader()
Get the current reader.
Definition: Clip.cpp:232
void RemoveEffect(openshot::EffectBase *effect)
Remove an effect from the clip.
Definition: Clip.cpp:1001
openshot::Keyframe channel_mapping
A number representing an audio channel to output (only works when filtering a channel)
Definition: Clip.h:249
openshot::Keyframe has_video
An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
Definition: Clip.h:253
std::string PropertiesJSON(int64_t requested_frame) const override
Definition: Clip.cpp:655
openshot::Keyframe crop_y
Curve representing Y offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:233
openshot::Color wave_color
Curve representing the color of the audio wave form.
Definition: Clip.h:226
void End(float value)
Set end position (in seconds) of clip (trim end of video)
Definition: Clip.h:191
openshot::Keyframe perspective_c2_x
Curves representing X for coordinate 2.
Definition: Clip.h:240
openshot::ScaleType scale
The scale determines how a clip should be resized to fit its parent.
Definition: Clip.h:144
openshot::Keyframe location_x
Curve representing the relative X position in percent based on the gravity (-1 to 1)
Definition: Clip.h:214
This class represents a color (used on the timeline and clips)
Definition: Color.h:45
This abstract class is the base class, used by all effects in libopenshot.
Definition: EffectBase.h:67
int Order() const
Get the order that this effect should be executed.
Definition: EffectBase.h:104
A Keyframe is a collection of Point instances, which is used to vary a number or property over time.
Definition: KeyFrame.h:64
This abstract class is the base class, used by all readers in libopenshot.
Definition: ReaderBase.h:98
This namespace is the default namespace for all code in the openshot library.
AnchorType
This enumeration determines what parent a clip should be aligned to.
Definition: Enums.h:62
GravityType
This enumeration determines how clips are aligned to their parent container.
Definition: Enums.h:39
ScaleType
This enumeration determines how clips are scaled to fit their parent container.
Definition: Enums.h:53
VolumeMixType
This enumeration determines the strategy when mixing audio with other clips.
Definition: Enums.h:78
FrameDisplayType
This enumeration determines the display format of the clip's frame number (if any)....
Definition: Enums.h:69
bool operator()(openshot::EffectBase *lhs, openshot::EffectBase *rhs)
Definition: Clip.h:55