OpenShot Library | libopenshot  0.2.0
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 "FFmpegReader.h"
48 #include "Fraction.h"
49 #include "FrameMapper.h"
50 #ifdef USE_IMAGEMAGICK
51  #include "ImageReader.h"
52  #include "TextReader.h"
53 #endif
54 #include "QtImageReader.h"
55 #include "ChunkReader.h"
56 #include "KeyFrame.h"
57 #include "ReaderBase.h"
58 #include "DummyReader.h"
59 
60 using namespace std;
61 using namespace openshot;
62 
63 namespace openshot {
64 
65  /// Comparison method for sorting effect pointers (by Position, Layer, and Order). Effects are sorted
66  /// from lowest layer to top layer (since that is sequence clips are combined), and then by
67  /// position, and then by effect order.
69  bool operator()( EffectBase* lhs, EffectBase* rhs){
70  if( lhs->Layer() < rhs->Layer() ) return true;
71  if( lhs->Layer() == rhs->Layer() && lhs->Position() < rhs->Position() ) return true;
72  if( lhs->Layer() == rhs->Layer() && lhs->Position() == rhs->Position() && lhs->Order() > rhs->Order() ) return true;
73  return false;
74  }};
75 
76  /**
77  * @brief This class represents a clip (used to arrange readers on the timeline)
78  *
79  * Each image, video, or audio file is represented on a layer as a clip. A clip has many
80  * properties that affect how it behaves on the timeline, such as its size, position,
81  * transparency, rotation, speed, volume, etc...
82  *
83  * @code
84  * // Create some clips
85  * Clip c1(new ImageReader("MyAwesomeLogo.jpeg"));
86  * Clip c2(new FFmpegReader("BackgroundVideo.webm"));
87  *
88  * // CLIP 1 (logo) - Set some clip properties (with Keyframes)
89  * c1.Position(0.0); // Set the position or location (in seconds) on the timeline
90  * c1.gravity = GRAVITY_LEFT; // Set the alignment / gravity of the clip (position on the screen)
91  * c1.scale = SCALE_CROP; // Set the scale mode (how the image is resized to fill the screen)
92  * c1.Layer(1); // Set the layer of the timeline (higher layers cover up images of lower layers)
93  * c1.Start(0.0); // Set the starting position of the video (trim the left side of the video)
94  * c1.End(16.0); // Set the ending position of the video (trim the right side of the video)
95  * c1.alpha.AddPoint(1, 0.0); // Set the alpha to transparent on frame #1
96  * c1.alpha.AddPoint(500, 0.0); // Keep the alpha transparent until frame #500
97  * c1.alpha.AddPoint(565, 1.0); // Animate the alpha from transparent to visible (between frame #501 and #565)
98  *
99  * // CLIP 2 (background video) - Set some clip properties (with Keyframes)
100  * c2.Position(0.0); // Set the position or location (in seconds) on the timeline
101  * c2.Start(10.0); // Set the starting position of the video (trim the left side of the video)
102  * c2.Layer(0); // Set the layer of the timeline (higher layers cover up images of lower layers)
103  * c2.alpha.AddPoint(1, 1.0); // Set the alpha to visible on frame #1
104  * c2.alpha.AddPoint(150, 0.0); // Animate the alpha to transparent (between frame 2 and frame #150)
105  * c2.alpha.AddPoint(360, 0.0, LINEAR); // Keep the alpha transparent until frame #360
106  * c2.alpha.AddPoint(384, 1.0); // Animate the alpha to visible (between frame #360 and frame #384)
107  * @endcode
108  */
109  class Clip : public ClipBase {
110  protected:
111  /// Section lock for multiple threads
112  CriticalSection getFrameCriticalSection;
113 
114  private:
115  bool waveform; ///< Should a waveform be used instead of the clip's image
116  list<EffectBase*> effects; ///<List of clips on this timeline
117 
118  // Audio resampler (if time mapping)
119  AudioResampler *resampler;
120  AudioSampleBuffer *audio_cache;
121 
122  // File Reader object
123  ReaderBase* reader;
124  bool manage_reader;
125 
126  /// Adjust frame number minimum value
127  int64_t adjust_frame_number_minimum(int64_t frame_number);
128 
129  /// Apply effects to the source frame (if any)
130  std::shared_ptr<Frame> apply_effects(std::shared_ptr<Frame> frame);
131 
132  /// Get file extension
133  string get_file_extension(string path);
134 
135  /// Get a frame object or create a blank one
136  std::shared_ptr<Frame> GetOrCreateFrame(int64_t number);
137 
138  /// Adjust the audio and image of a time mapped frame
139  std::shared_ptr<Frame> get_time_mapped_frame(std::shared_ptr<Frame> frame, int64_t frame_number);
140 
141  /// Init default settings for a clip
142  void init_settings();
143 
144  /// Update default rotation from reader
145  void init_reader_rotation();
146 
147  /// Sort effects by order
148  void sort_effects();
149 
150  /// Reverse an audio buffer
151  void reverse_buffer(juce::AudioSampleBuffer* buffer);
152 
153  public:
154  GravityType gravity; ///< The gravity of a clip determines where it snaps to it's parent
155  ScaleType scale; ///< The scale determines how a clip should be resized to fit it's parent
156  AnchorType anchor; ///< The anchor determines what parent a clip should snap to
157  FrameDisplayType display; ///< The format to display the frame number (if any)
158  VolumeMixType mixing; ///< What strategy should be followed when mixing audio with other clips
159 
160  /// Default Constructor
161  Clip();
162 
163  /// @brief Constructor with filepath (reader is automatically created... by guessing file extensions)
164  /// @param path The path of a reader (video file, image file, etc...). The correct reader will be used automatically.
165  Clip(string path);
166 
167  /// @brief Constructor with reader
168  /// @param new_reader The reader to be used by this clip
169  Clip(ReaderBase* new_reader);
170 
171  /// Destructor
172  ~Clip();
173 
174  /// @brief Add an effect to the clip
175  /// @param effect Add an effect to the clip. An effect can modify the audio or video of an openshot::Frame.
176  void AddEffect(EffectBase* effect);
177 
178  /// Close the internal reader
179  void Close();
180 
181  /// Return the list of effects on the timeline
182  list<EffectBase*> Effects() { return effects; };
183 
184  /// @brief Get an openshot::Frame object for a specific frame number of this timeline.
185  ///
186  /// @returns The requested frame (containing the image)
187  /// @param requested_frame The frame number that is requested
188  std::shared_ptr<Frame> GetFrame(int64_t requested_frame);
189 
190  /// Open the internal reader
191  void Open();
192 
193  /// @brief Set the current reader
194  /// @param new_reader The reader to be used by this clip
195  void Reader(ReaderBase* new_reader);
196 
197  /// Get the current reader
198  ReaderBase* Reader();
199 
200  /// Override End() method
201  float End(); ///< Get end position (in seconds) of clip (trim end of video), which can be affected by the time curve.
202  void End(float value) { end = value; } ///< Set end position (in seconds) of clip (trim end of video)
203 
204  /// Get and Set JSON methods
205  string Json(); ///< Generate JSON string of this object
206  void SetJson(string value); ///< Load JSON string into this object
207  Json::Value JsonValue(); ///< Generate Json::JsonValue for this object
208  void SetJsonValue(Json::Value root); ///< Load Json::JsonValue into this object
209 
210  /// Get all properties for a specific frame (perfect for a UI to display the current state
211  /// of all properties at any time)
212  string PropertiesJSON(int64_t requested_frame);
213 
214  /// @brief Remove an effect from the clip
215  /// @param effect Remove an effect from the clip.
216  void RemoveEffect(EffectBase* effect);
217 
218  /// Waveform property
219  bool Waveform() { return waveform; } ///< Get the waveform property of this clip
220  void Waveform(bool value) { waveform = value; } ///< Set the waveform property of this clip
221 
222  // Scale and Location curves
223  Keyframe scale_x; ///< Curve representing the horizontal scaling in percent (0 to 1)
224  Keyframe scale_y; ///< Curve representing the vertical scaling in percent (0 to 1)
225  Keyframe location_x; ///< Curve representing the relative X position in percent based on the gravity (-1 to 1)
226  Keyframe location_y; ///< Curve representing the relative Y position in percent based on the gravity (-1 to 1)
227 
228  // Alpha and Rotation curves
229  Keyframe alpha; ///< Curve representing the alpha (1 to 0)
230  Keyframe rotation; ///< Curve representing the rotation (0 to 360)
231 
232  // Time and Volume curves
233  Keyframe time; ///< Curve representing the frames over time to play (used for speed and direction of video)
234  Keyframe volume; ///< Curve representing the volume (0 to 1)
235 
236  /// Curve representing the color of the audio wave form
238 
239  // Crop settings and curves
240  GravityType crop_gravity; ///< Cropping needs to have a gravity to determine what side we are cropping
241  Keyframe crop_width; ///< Curve representing width in percent (0.0=0%, 1.0=100%)
242  Keyframe crop_height; ///< Curve representing height in percent (0.0=0%, 1.0=100%)
243  Keyframe crop_x; ///< Curve representing X offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
244  Keyframe crop_y; ///< Curve representing Y offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
245 
246  // Shear and perspective curves
247  Keyframe shear_x; ///< Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
248  Keyframe shear_y; ///< Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
249  Keyframe perspective_c1_x; ///< Curves representing X for coordinate 1
250  Keyframe perspective_c1_y; ///< Curves representing Y for coordinate 1
251  Keyframe perspective_c2_x; ///< Curves representing X for coordinate 2
252  Keyframe perspective_c2_y; ///< Curves representing Y for coordinate 2
253  Keyframe perspective_c3_x; ///< Curves representing X for coordinate 3
254  Keyframe perspective_c3_y; ///< Curves representing Y for coordinate 3
255  Keyframe perspective_c4_x; ///< Curves representing X for coordinate 4
256  Keyframe perspective_c4_y; ///< Curves representing Y for coordinate 4
257 
258  /// Audio channel filter and mappings
259  Keyframe channel_filter; ///< A number representing an audio channel to filter (clears all other channels)
260  Keyframe channel_mapping; ///< A number representing an audio channel to output (only works when filtering a channel)
261 
262  /// Override has_video and has_audio properties of clip (and their readers)
263  Keyframe has_audio; ///< An optional override to determine if this clip has audio (-1=undefined, 0=no, 1=yes)
264  Keyframe has_video; ///< An optional override to determine if this clip has video (-1=undefined, 0=no, 1=yes)
265  };
266 
267 
268 }
269 
270 #endif
Keyframe perspective_c3_x
Curves representing X for coordinate 3.
Definition: Clip.h:253
Header file for Fraction class.
Keyframe scale_y
Curve representing the vertical scaling in percent (0 to 1)
Definition: Clip.h:224
Keyframe perspective_c4_x
Curves representing X for coordinate 4.
Definition: Clip.h:255
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:249
Keyframe perspective_c2_x
Curves representing X for coordinate 2.
Definition: Clip.h:251
Keyframe crop_x
Curve representing X offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:243
Header file for DummyReader class.
Keyframe perspective_c3_y
Curves representing Y for coordinate 3.
Definition: Clip.h:254
Header file for ReaderBase class.
GravityType gravity
The gravity of a clip determines where it snaps to it&#39;s parent.
Definition: Clip.h:154
Keyframe volume
Curve representing the volume (0 to 1)
Definition: Clip.h:234
This header includes all commonly used effects for libopenshot, for ease-of-use.
Header file for FFmpegReader class.
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:69
Keyframe time
Curve representing the frames over time to play (used for speed and direction of video) ...
Definition: Clip.h:233
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:96
int Layer()
Get layer of clip on timeline (lower number is covered by higher numbers)
Definition: ClipBase.h:84
Keyframe has_audio
Override has_video and has_audio properties of clip (and their readers)
Definition: Clip.h:263
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:264
Color wave_color
Curve representing the color of the audio wave form.
Definition: Clip.h:237
Keyframe crop_width
Curve representing width in percent (0.0=0%, 1.0=100%)
Definition: Clip.h:241
Keyframe location_x
Curve representing the relative X position in percent based on the gravity (-1 to 1) ...
Definition: Clip.h:225
Keyframe location_y
Curve representing the relative Y position in percent based on the gravity (-1 to 1) ...
Definition: Clip.h:226
This class represents a clip (used to arrange readers on the timeline)
Definition: Clip.h:109
Keyframe perspective_c1_y
Curves representing Y for coordinate 1.
Definition: Clip.h:250
Keyframe crop_y
Curve representing Y offset in percent (-1.0=-100%, 0.0=0%, 1.0=100%)
Definition: Clip.h:244
Keyframe shear_x
Curve representing X shear angle in degrees (-45.0=left, 45.0=right)
Definition: Clip.h:247
bool Waveform()
Waveform property.
Definition: Clip.h:219
ScaleType scale
The scale determines how a clip should be resized to fit it&#39;s parent.
Definition: Clip.h:155
Header file for ChunkReader class.
Header file for AudioResampler class.
FrameDisplayType
This enumeration determines the display format of the clip&#39;s frame number (if any). Useful for debugging.
Definition: Enums.h:65
Keyframe channel_filter
Audio channel filter and mappings.
Definition: Clip.h:259
Header file for TextReader class.
float Position()
Get position on timeline (in seconds)
Definition: ClipBase.h:83
list< EffectBase * > Effects()
Return the list of effects on the timeline.
Definition: Clip.h:182
FrameDisplayType display
The format to display the frame number (if any)
Definition: Clip.h:157
Header file for the FrameMapper class.
Keyframe channel_mapping
A number representing an audio channel to output (only works when filtering a channel) ...
Definition: Clip.h:260
void End(float value)
Set end position (in seconds) of clip (trim end of video)
Definition: Clip.h:202
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:230
Header file for Color class.
Keyframe shear_y
Curve representing Y shear angle in degrees (-45.0=down, 45.0=up)
Definition: Clip.h:248
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:240
This namespace is the default namespace for all code in the openshot library.
Header file for EffectBase class.
AnchorType anchor
The anchor determines what parent a clip should snap to.
Definition: Clip.h:156
Keyframe alpha
Curve representing the alpha (1 to 0)
Definition: Clip.h:229
Header file for QtImageReader class.
Keyframe scale_x
Curve representing the horizontal scaling in percent (0 to 1)
Definition: Clip.h:223
Keyframe perspective_c2_y
Curves representing Y for coordinate 2.
Definition: Clip.h:252
CriticalSection getFrameCriticalSection
Section lock for multiple threads.
Definition: Clip.h:112
Header file for ImageReader class.
VolumeMixType mixing
What strategy should be followed when mixing audio with other clips.
Definition: Clip.h:158
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:220
Keyframe perspective_c4_y
Curves representing Y for coordinate 4.
Definition: Clip.h:256
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:242