OpenShot Library | libopenshot  0.2.7
Public Member Functions | Public Attributes | List of all members
openshot::Timeline Class Reference

This class represents a timeline. More...

#include <Timeline.h>

Inheritance diagram for openshot::Timeline:
openshot::TimelineBase openshot::ReaderBase

Public Member Functions

void AddClip (openshot::Clip *clip)
 Add an openshot::Clip to the timeline. More...
 
void AddEffect (openshot::EffectBase *effect)
 Add an effect to the timeline. More...
 
void AddTrackedObject (std::shared_ptr< openshot::TrackedObjectBase > trackedObject)
 Add to the tracked_objects map a pointer to a tracked object (TrackedObjectBBox) More...
 
std::shared_ptr< openshot::Frameapply_effects (std::shared_ptr< openshot::Frame > frame, int64_t timeline_frame_number, int layer)
 Apply global/timeline effects to the source frame (if any) More...
 
void ApplyJsonDiff (std::string value)
 Apply a special formatted JSON object, which represents a change to the timeline (add, update, delete) This is primarily designed to keep the timeline (and its child objects... such as clips and effects) in sync with another application... such as OpenShot Video Editor (http://www.openshot.org). More...
 
void ApplyMapperToClips ()
 Apply the timeline's framerate and samplerate to all clips. More...
 
bool AutoMapClips ()
 Determine if clips are automatically mapped to the timeline's framerate and samplerate. More...
 
void AutoMapClips (bool auto_map)
 Automatically map all clips to the timeline's framerate and samplerate. More...
 
void ClearAllCache ()
 Clear all cache for this timeline instance, and all clips, mappers, and readers under it. More...
 
std::list< openshot::EffectBase * > ClipEffects () const
 Return the list of effects on all clips. More...
 
std::list< openshot::Clip * > Clips ()
 Return a list of clips on the timeline. More...
 
void Close () override
 Close the timeline reader (and any resources it was consuming) More...
 
std::list< openshot::EffectBase * > Effects ()
 Return the list of effects on the timeline. More...
 
openshot::CacheBaseGetCache () override
 Get the cache object used by this reader. More...
 
openshot::ClipGetClip (const std::string &id)
 Look up a single clip by ID. More...
 
openshot::EffectBaseGetClipEffect (const std::string &id)
 Look up a clip effect by ID. More...
 
openshot::EffectBaseGetEffect (const std::string &id)
 Look up a timeline effect by ID. More...
 
std::shared_ptr< openshot::FrameGetFrame (int64_t requested_frame) override
 
int64_t GetMaxFrame ()
 Look up the end frame number of the latest element on the timeline. More...
 
double GetMaxTime ()
 Look up the end time of the latest timeline element. More...
 
std::shared_ptr< openshot::TrackedObjectBaseGetTrackedObject (std::string id) const
 Return tracked object pointer by it's id. More...
 
std::list< std::string > GetTrackedObjectsIds () const
 Return the ID's of the tracked objects as a list of strings. More...
 
std::string GetTrackedObjectValues (std::string id, int64_t frame_number) const
 Return the trackedObject's properties as a JSON string. More...
 
bool IsOpen () override
 Determine if reader is open or closed. More...
 
std::string Json () const override
 Generate JSON string of this object. More...
 
Json::Value JsonValue () const override
 Generate Json::Value for this object. More...
 
std::string Name () override
 Return the type name of the class. More...
 
void Open () override
 Open the reader (and start consuming resources) More...
 
void RemoveClip (openshot::Clip *clip)
 Remove an openshot::Clip from the timeline. More...
 
void RemoveEffect (openshot::EffectBase *effect)
 Remove an effect from the timeline. More...
 
void SetCache (openshot::CacheBase *new_cache)
 
void SetJson (const std::string value) override
 Load JSON string into this object. More...
 
void SetJsonValue (const Json::Value root) override
 Load Json::Value into this object. More...
 
void SetMaxSize (int width, int height)
 
 Timeline (int width, int height, openshot::Fraction fps, int sample_rate, int channels, openshot::ChannelLayout channel_layout)
 Constructor for the timeline (which configures the default frame properties) More...
 
 Timeline (ReaderInfo info)
 Constructor which takes a ReaderInfo struct to configure parameters. More...
 
 Timeline (const std::string &projectPath, bool convert_absolute_paths)
 Project-file constructor for the timeline. More...
 
virtual ~Timeline ()
 
- Public Member Functions inherited from openshot::TimelineBase
virtual void Clips (int test)
 
 TimelineBase ()
 Constructor for the base timeline. More...
 
- Public Member Functions inherited from openshot::ReaderBase
void DisplayInfo ()
 Display file information in the standard output stream (stdout) More...
 
openshot::ClipBaseParentClip ()
 Parent clip object of this reader (which can be unparented and NULL) More...
 
void ParentClip (openshot::ClipBase *new_clip)
 Set parent clip object of this reader. More...
 
 ReaderBase ()
 Constructor for the base reader, where many things are initialized. More...
 
virtual ~ReaderBase ()=default
 

Public Attributes

openshot::Color color
 Background color of timeline canvas. More...
 
openshot::Keyframe viewport_scale
 Curve representing the scale of the viewport (0 to 100) More...
 
openshot::Keyframe viewport_x
 Curve representing the x coordinate for the viewport. More...
 
openshot::Keyframe viewport_y
 Curve representing the y coordinate for the viewport. More...
 
- Public Attributes inherited from openshot::TimelineBase
int preview_height
 Optional preview width of timeline image. If your preview window is smaller than the timeline, it's recommended to set this. More...
 
int preview_width
 Optional preview width of timeline image. If your preview window is smaller than the timeline, it's recommended to set this. More...
 
- Public Attributes inherited from openshot::ReaderBase
openshot::ReaderInfo info
 Information about the current media file. More...
 

Additional Inherited Members

- Protected Attributes inherited from openshot::ReaderBase
openshot::ClipBaseclip
 Pointer to the parent clip instance (if any) More...
 
juce::CriticalSection getFrameCriticalSection
 Section lock for multiple threads. More...
 
juce::CriticalSection processingCriticalSection
 

Detailed Description

This class represents a timeline.

The timeline is one of the most important features of a video editor, and controls all aspects of how video, image, and audio clips are combined together, and how the final video output will be rendered. It has a collection of layers and clips, that arrange, sequence, and generate the final video output.

The following graphic displays a timeline, and how clips can be arranged, scaled, and layered together. It also demonstrates how the viewport can be scaled smaller than the canvas, which can be used to zoom and pan around the canvas (i.e. pan & scan).

Timeline_Layers.png

The following graphic displays how the playhead determines which frames to combine and layer.

Playhead.png

Lets take a look at what the code looks like:

// Create a Timeline
Timeline t(1280, // width
720, // height
Fraction(25,1), // framerate
44100, // sample rate
2 // channels
);
// Create some clips
Clip c1(new ImageReader("MyAwesomeLogo.jpeg"));
Clip c2(new FFmpegReader("BackgroundVideo.webm"));
// CLIP 1 (logo) - Set some clip properties (with Keyframes)
c1.Position(0.0); // Set the position or location (in seconds) on the timeline
c1.gravity = GRAVITY_LEFT; // Set the alignment / gravity of the clip (position on the screen)
c1.scale = SCALE_CROP; // Set the scale mode (how the image is resized to fill the screen)
c1.Layer(1); // Set the layer of the timeline (higher layers cover up images of lower layers)
c1.Start(0.0); // Set the starting position of the video (trim the left side of the video)
c1.End(16.0); // Set the ending position of the video (trim the right side of the video)
c1.alpha.AddPoint(1, 0.0); // Set the alpha to transparent on frame #1
c1.alpha.AddPoint(500, 0.0); // Keep the alpha transparent until frame #500
c1.alpha.AddPoint(565, 1.0); // Animate the alpha from transparent to visible (between frame #501 and #565)
// CLIP 2 (background video) - Set some clip properties (with Keyframes)
c2.Position(0.0); // Set the position or location (in seconds) on the timeline
c2.Start(10.0); // Set the starting position of the video (trim the left side of the video)
c2.Layer(0); // Set the layer of the timeline (higher layers cover up images of lower layers)
c2.alpha.AddPoint(1, 1.0); // Set the alpha to visible on frame #1
c2.alpha.AddPoint(150, 0.0); // Animate the alpha to transparent (between frame 2 and frame #150)
c2.alpha.AddPoint(360, 0.0, LINEAR); // Keep the alpha transparent until frame #360
c2.alpha.AddPoint(384, 1.0); // Animate the alpha to visible (between frame #360 and frame #384)
// Add clips to timeline
t.AddClip(&c1);
t.AddClip(&c2);
// Open the timeline reader
t.Open();
// Get frame number 1 from the timeline (This will generate a new frame, made up from the previous clips and settings)
std::shared_ptr<Frame> f = t.GetFrame(1);
// Now that we have an openshot::Frame object, lets have some fun!
f->Display(); // Display the frame on the screen
// Close the timeline reader
t.Close();

Definition at line 168 of file Timeline.h.

Constructor & Destructor Documentation

◆ Timeline() [1/3]

Timeline::Timeline ( int  width,
int  height,
openshot::Fraction  fps,
int  sample_rate,
int  channels,
openshot::ChannelLayout  channel_layout 
)

Constructor for the timeline (which configures the default frame properties)

Parameters
widthThe image width of generated openshot::Frame objects
heightThe image height of generated openshot::Frame objects
fpsThe frame rate of the generated video
sample_rateThe audio sample rate
channelsThe number of audio channels
channel_layoutThe channel layout (i.e. mono, stereo, 3 point surround, etc...)

Definition at line 46 of file Timeline.cpp.

◆ Timeline() [2/3]

Timeline::Timeline ( ReaderInfo  info)

Constructor which takes a ReaderInfo struct to configure parameters.

Parameters
infoThe reader parameters to configure the new timeline with

Definition at line 91 of file Timeline.cpp.

◆ Timeline() [3/3]

Timeline::Timeline ( const std::string &  projectPath,
bool  convert_absolute_paths 
)

Project-file constructor for the timeline.

Loads a JSON structure from a file path, and initializes the timeline described within.

Parameters
projectPathThe path of the UTF-8 *.osp project file (JSON contents). Contents will be loaded automatically.
convert_absolute_pathsShould all paths be converted to absolute paths (relative to the location of projectPath)

Definition at line 96 of file Timeline.cpp.

◆ ~Timeline()

Timeline::~Timeline ( )
virtual

Definition at line 222 of file Timeline.cpp.

Member Function Documentation

◆ AddClip()

void Timeline::AddClip ( openshot::Clip clip)

Add an openshot::Clip to the timeline.

Parameters
clipAdd an openshot::Clip to the timeline. A clip can contain any type of Reader.

Definition at line 356 of file Timeline.cpp.

Referenced by ApplyJsonDiff(), SetJsonValue(), and openshot::QtPlayer::SetSource().

◆ AddEffect()

void Timeline::AddEffect ( openshot::EffectBase effect)

Add an effect to the timeline.

Parameters
effectAdd an effect to the timeline. An effect can modify the audio or video of an openshot::Frame.

Definition at line 379 of file Timeline.cpp.

Referenced by ApplyJsonDiff(), and SetJsonValue().

◆ AddTrackedObject()

void Timeline::AddTrackedObject ( std::shared_ptr< openshot::TrackedObjectBase trackedObject)

Add to the tracked_objects map a pointer to a tracked object (TrackedObjectBBox)

Definition at line 247 of file Timeline.cpp.

Referenced by openshot::Clip::AddEffect().

◆ apply_effects()

std::shared_ptr< Frame > Timeline::apply_effects ( std::shared_ptr< openshot::Frame frame,
int64_t  timeline_frame_number,
int  layer 
)

Apply global/timeline effects to the source frame (if any)

Definition at line 537 of file Timeline.cpp.

Referenced by openshot::Clip::GetFrame().

◆ ApplyJsonDiff()

void Timeline::ApplyJsonDiff ( std::string  value)

Apply a special formatted JSON object, which represents a change to the timeline (add, update, delete) This is primarily designed to keep the timeline (and its child objects... such as clips and effects) in sync with another application... such as OpenShot Video Editor (http://www.openshot.org).

Parameters
valueA JSON string containing a key, value, and type of change.

Definition at line 1117 of file Timeline.cpp.

◆ ApplyMapperToClips()

void Timeline::ApplyMapperToClips ( )

Apply the timeline's framerate and samplerate to all clips.

Definition at line 513 of file Timeline.cpp.

◆ AutoMapClips() [1/2]

bool openshot::Timeline::AutoMapClips ( )
inline

Determine if clips are automatically mapped to the timeline's framerate and samplerate.

Definition at line 275 of file Timeline.h.

◆ AutoMapClips() [2/2]

void openshot::Timeline::AutoMapClips ( bool  auto_map)
inline

Automatically map all clips to the timeline's framerate and samplerate.

Definition at line 278 of file Timeline.h.

◆ ClearAllCache()

void Timeline::ClearAllCache ( )

Clear all cache for this timeline instance, and all clips, mappers, and readers under it.

Definition at line 1496 of file Timeline.cpp.

Referenced by ApplyJsonDiff(), ApplyMapperToClips(), and GetFrame().

◆ ClipEffects()

std::list< openshot::EffectBase * > Timeline::ClipEffects ( ) const

Return the list of effects on all clips.

Definition at line 440 of file Timeline.cpp.

Referenced by openshot::EffectBase::SetJsonValue().

◆ Clips()

std::list<openshot::Clip*> openshot::Timeline::Clips ( )
inline

Return a list of clips on the timeline.

Definition at line 284 of file Timeline.h.

◆ Close()

void Timeline::Close ( )
overridevirtual

Close the timeline reader (and any resources it was consuming)

Implements openshot::ReaderBase.

Definition at line 739 of file Timeline.cpp.

Referenced by SetJsonValue(), and ~Timeline().

◆ Effects()

std::list<openshot::EffectBase*> openshot::Timeline::Effects ( )
inline

Return the list of effects on the timeline.

Definition at line 304 of file Timeline.h.

◆ GetCache()

openshot::CacheBase* openshot::Timeline::GetCache ( )
inlineoverridevirtual

Get the cache object used by this reader.

Implements openshot::ReaderBase.

Definition at line 310 of file Timeline.h.

◆ GetClip()

openshot::Clip * Timeline::GetClip ( const std::string &  id)

Look up a single clip by ID.

Definition at line 404 of file Timeline.cpp.

Referenced by openshot::Clip::AttachToObject(), openshot::Tracker::GetFrame(), and openshot::ObjectDetection::GetFrame().

◆ GetClipEffect()

openshot::EffectBase * Timeline::GetClipEffect ( const std::string &  id)

Look up a clip effect by ID.

Definition at line 427 of file Timeline.cpp.

Referenced by openshot::EffectBase::SetParentEffect().

◆ GetEffect()

openshot::EffectBase * Timeline::GetEffect ( const std::string &  id)

Look up a timeline effect by ID.

Definition at line 416 of file Timeline.cpp.

◆ GetFrame()

std::shared_ptr< Frame > Timeline::GetFrame ( int64_t  requested_frame)
overridevirtual

Get an openshot::Frame object for a specific frame number of this timeline.

Returns
The requested frame (containing the image)
Parameters
requested_frameThe frame number that is requested.

Implements openshot::ReaderBase.

Definition at line 771 of file Timeline.cpp.

◆ GetMaxFrame()

int64_t Timeline::GetMaxFrame ( )

Look up the end frame number of the latest element on the timeline.

Definition at line 477 of file Timeline.cpp.

◆ GetMaxTime()

double Timeline::GetMaxTime ( )

Look up the end time of the latest timeline element.

Definition at line 459 of file Timeline.cpp.

Referenced by GetMaxFrame().

◆ GetTrackedObject()

std::shared_ptr< openshot::TrackedObjectBase > Timeline::GetTrackedObject ( std::string  id) const

Return tracked object pointer by it's id.

Definition at line 265 of file Timeline.cpp.

Referenced by openshot::Clip::AttachToObject().

◆ GetTrackedObjectsIds()

std::list< std::string > Timeline::GetTrackedObjectsIds ( ) const

Return the ID's of the tracked objects as a list of strings.

Definition at line 282 of file Timeline.cpp.

◆ GetTrackedObjectValues()

std::string Timeline::GetTrackedObjectValues ( std::string  id,
int64_t  frame_number 
) const

Return the trackedObject's properties as a JSON string.

Definition at line 298 of file Timeline.cpp.

◆ IsOpen()

bool openshot::Timeline::IsOpen ( )
inlineoverridevirtual

Determine if reader is open or closed.

Implements openshot::ReaderBase.

Definition at line 331 of file Timeline.h.

◆ Json()

std::string Timeline::Json ( ) const
overridevirtual

Generate JSON string of this object.

Implements openshot::ReaderBase.

Definition at line 980 of file Timeline.cpp.

◆ JsonValue()

Json::Value Timeline::JsonValue ( ) const
overridevirtual

Generate Json::Value for this object.

Implements openshot::ReaderBase.

Definition at line 987 of file Timeline.cpp.

Referenced by Json().

◆ Name()

std::string openshot::Timeline::Name ( )
inlineoverridevirtual

Return the type name of the class.

Implements openshot::ReaderBase.

Definition at line 334 of file Timeline.h.

◆ Open()

void Timeline::Open ( )
overridevirtual

Open the reader (and start consuming resources)

Implements openshot::ReaderBase.

Definition at line 759 of file Timeline.cpp.

Referenced by SetJsonValue(), and openshot::QtPlayer::SetSource().

◆ RemoveClip()

void Timeline::RemoveClip ( openshot::Clip clip)

Remove an openshot::Clip from the timeline.

Parameters
clipRemove an openshot::Clip from the timeline.

Definition at line 398 of file Timeline.cpp.

Referenced by ApplyJsonDiff().

◆ RemoveEffect()

void Timeline::RemoveEffect ( openshot::EffectBase effect)

Remove an effect from the timeline.

Parameters
effectRemove an effect from the timeline.

Definition at line 392 of file Timeline.cpp.

Referenced by ApplyJsonDiff().

◆ SetCache()

void Timeline::SetCache ( openshot::CacheBase new_cache)

Set the cache object used by this reader. You must now manage the lifecycle of this cache object though (Timeline will not delete it for you).

Definition at line 967 of file Timeline.cpp.

◆ SetJson()

void Timeline::SetJson ( const std::string  value)
overridevirtual

Load JSON string into this object.

Implements openshot::ReaderBase.

Definition at line 1021 of file Timeline.cpp.

Referenced by Timeline().

◆ SetJsonValue()

void Timeline::SetJsonValue ( const Json::Value  root)
overridevirtual

Load Json::Value into this object.

Implements openshot::ReaderBase.

Definition at line 1041 of file Timeline.cpp.

Referenced by SetJson().

◆ SetMaxSize()

void Timeline::SetMaxSize ( int  width,
int  height 
)

Set Max Image Size (used for performance optimization). Convenience function for setting Settings::Instance()->MAX_WIDTH and Settings::Instance()->MAX_HEIGHT.

Definition at line 1522 of file Timeline.cpp.

Referenced by Timeline().

Member Data Documentation

◆ color

openshot::Color openshot::Timeline::color

Background color of timeline canvas.

Definition at line 328 of file Timeline.h.

Referenced by ApplyJsonDiff(), GetFrame(), JsonValue(), and Timeline().

◆ viewport_scale

openshot::Keyframe openshot::Timeline::viewport_scale

Curve representing the scale of the viewport (0 to 100)

Definition at line 323 of file Timeline.h.

Referenced by ApplyJsonDiff(), JsonValue(), and Timeline().

◆ viewport_x

openshot::Keyframe openshot::Timeline::viewport_x

Curve representing the x coordinate for the viewport.

Definition at line 324 of file Timeline.h.

Referenced by ApplyJsonDiff(), JsonValue(), and Timeline().

◆ viewport_y

openshot::Keyframe openshot::Timeline::viewport_y

Curve representing the y coordinate for the viewport.

Definition at line 325 of file Timeline.h.

Referenced by ApplyJsonDiff(), JsonValue(), and Timeline().


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