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