This class represents a timeline. More...

#include <Timeline.h>

Inheritance diagram for openshot::Timeline:

Collaboration diagram for openshot::Timeline:

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::Frame >	apply_effects (std::shared_ptr< openshot::Frame > frame, int64_t timeline_frame_number, int layer, TimelineInfoStruct *options)
	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...

uint64_t	CacheEpoch () const
	Return the current cache invalidation epoch. More...

void	Clear ()
	Clear all clips, effects, and frame mappers from timeline (and free memory) More...

void	ClearAllCache (bool deep=false)

std::list< openshot::EffectBase * >	ClipEffects () const
	Return the list of effects on all clips. More...

std::list< openshot::Clip * >	Clips () override
	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::CacheBase *	GetCache () override
	Get the cache object used by this reader. More...

openshot::Clip *	GetClip (const std::string &id)
	Look up a single clip by ID. More...

openshot::EffectBase *	GetClipEffect (const std::string &id)
	Look up a clip effect by ID. More...

openshot::EffectBase *	GetEffect (const std::string &id)
	Look up a timeline effect by ID. More...

std::shared_ptr< openshot::Frame >	GetFrame (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...

int64_t	GetMinFrame ()
	Look up the start frame number of the first element on the timeline (first frame is 1) More...

double	GetMinTime ()
	Look up the position/start time of the first timeline element. More...

std::shared_ptr< openshot::TrackedObjectBase >	GetTrackedObject (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...

int	SafeEditFramesRemaining () const

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)

void	SortTimeline ()
	Sort all clips and effects on timeline - which affects the internal order of clips and effects arrays This is called automatically when Clips or Effects modify the Layer(), Position(), Start(), or End(). More...

	Timeline (const std::string &projectPath, bool convert_absolute_paths)
	Project-file constructor for the timeline. More...

	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...

virtual	~Timeline ()

Public Member Functions inherited from openshot::TimelineBase
	TimelineBase ()
	Constructor for the base timeline. More...

virtual	~TimelineBase ()=default

Public Member Functions inherited from openshot::ReaderBase
void	DisplayInfo (std::ostream *out=&std::cout)
	Display file information in the standard output stream (stdout) More...

virtual bool	HardwareDecodeSuccessful () const

openshot::ClipBase *	ParentClip ()
	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::ClipBase *	clip
	Pointer to the parent clip instance (if any) More...

std::recursive_mutex	getFrameMutex
	Mutex for multiple threads. More...

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).

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

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
           ChannelLayout::LAYOUT_STEREO,
           );
 
// 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 152 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

width	The image width of generated openshot::Frame objects
height	The image height of generated openshot::Frame objects
fps	The frame rate of the generated video
sample_rate	The audio sample rate
channels	The number of audio channels
channel_layout	The channel layout (i.e. mono, stereo, 3 point surround, etc...)

Definition at line 33 of file Timeline.cpp.

◆ Timeline() [2/3]

Timeline::Timeline ( ReaderInfo info )

Constructor which takes a ReaderInfo struct to configure parameters.

Parameters

info	The reader parameters to configure the new timeline with

Definition at line 79 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

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

Definition at line 84 of file Timeline.cpp.

◆ ~Timeline()

Timeline::~Timeline ( )

virtual

Definition at line 211 of file Timeline.cpp.

Member Function Documentation

◆ AddClip()

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

Add an openshot::Clip to the timeline.

Parameters

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

Definition at line 337 of file Timeline.cpp.

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

◆ AddEffect()

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

Add an effect to the timeline.

Parameters

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

Definition at line 363 of file Timeline.cpp.

Referenced by 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 228 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,
		TimelineInfoStruct *	options
	)

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

Definition at line 550 of file Timeline.cpp.

◆ 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

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

Definition at line 1364 of file Timeline.cpp.

◆ ApplyMapperToClips()

void Timeline::ApplyMapperToClips ( )

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

Definition at line 526 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 269 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 272 of file Timeline.h.

◆ CacheEpoch()

uint64_t openshot::Timeline::CacheEpoch ( ) const

inline

Return the current cache invalidation epoch.

Definition at line 320 of file Timeline.h.

Referenced by openshot::VideoCacheThread::run().

◆ Clear()

void Timeline::Clear ( )

Clear all clips, effects, and frame mappers from timeline (and free memory)

Definition at line 862 of file Timeline.cpp.

Referenced by ~Timeline().

◆ ClearAllCache()

void Timeline::ClearAllCache ( bool deep = false )

Clear all cache for this timeline instance, including all clips' cache

Parameters

deep	If True, clear all FrameMappers and nested Readers (QtImageReader, FFmpegReader, etc...)

Definition at line 1778 of file Timeline.cpp.

Referenced by ApplyMapperToClips(), Close(), and openshot::VideoCacheThread::run().

◆ ClipEffects()

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

Return the list of effects on all clips.

Definition at line 453 of file Timeline.cpp.

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

◆ Clips()

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

inlineoverridevirtual

Return a list of clips on the timeline.

Implements openshot::TimelineBase.

Definition at line 282 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 908 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 307 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 313 of file Timeline.h.

◆ GetClip()

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

Look up a single clip by ID.

Definition at line 417 of file Timeline.cpp.

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

◆ GetClipEffect()

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

Look up a clip effect by ID.

Definition at line 440 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 429 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_frame The frame number that is requested.

Implements openshot::ReaderBase.

Definition at line 942 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 478 of file Timeline.cpp.

Referenced by GetFrame().

◆ GetMaxTime()

double Timeline::GetMaxTime ( )

Look up the end time of the latest timeline element.

Definition at line 472 of file Timeline.cpp.

Referenced by GetMaxFrame().

◆ GetMinFrame()

int64_t Timeline::GetMinFrame ( )

Look up the start frame number of the first element on the timeline (first frame is 1)

Definition at line 486 of file Timeline.cpp.

◆ GetMinTime()

double Timeline::GetMinTime ( )

Look up the position/start time of the first timeline element.

Definition at line 494 of file Timeline.cpp.

Referenced by GetMinFrame().

◆ GetTrackedObject()

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

Return tracked object pointer by it's id.

Definition at line 246 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 263 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 279 of file Timeline.cpp.

◆ IsOpen()

bool openshot::Timeline::IsOpen ( )

inlineoverridevirtual

Determine if reader is open or closed.

Implements openshot::ReaderBase.

Definition at line 338 of file Timeline.h.

◆ Json()

std::string Timeline::Json ( ) const

overridevirtual

Generate JSON string of this object.

Implements openshot::ReaderBase.

Definition at line 1201 of file Timeline.cpp.

◆ JsonValue()

Json::Value Timeline::JsonValue ( ) const

overridevirtual

Generate Json::Value for this object.

Implements openshot::ReaderBase.

Definition at line 1208 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 341 of file Timeline.h.

◆ Open()

void Timeline::Open ( )

overridevirtual

Open the reader (and start consuming resources)

Implements openshot::ReaderBase.

Definition at line 930 of file Timeline.cpp.

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

◆ RemoveClip()

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

Remove an openshot::Clip from the timeline.

Parameters

clip	Remove an openshot::Clip from the timeline.

Definition at line 398 of file Timeline.cpp.

◆ RemoveEffect()

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

Remove an effect from the timeline.

Parameters

effect Remove an effect from the timeline.

Definition at line 379 of file Timeline.cpp.

◆ SafeEditFramesRemaining()

int openshot::Timeline::SafeEditFramesRemaining ( ) const

inline

Definition at line 321 of file Timeline.h.

◆ 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 1185 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 1242 of file Timeline.cpp.

Referenced by openshot::QtPlayer::SetTimelineSource(), and Timeline().

◆ SetJsonValue()

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

overridevirtual

Load Json::Value into this object.

Implements openshot::ReaderBase.

Definition at line 1262 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 1819 of file Timeline.cpp.

Referenced by Timeline().

◆ SortTimeline()

void openshot::Timeline::SortTimeline ( )

inline

Sort all clips and effects on timeline - which affects the internal order of clips and effects arrays This is called automatically when Clips or Effects modify the Layer(), Position(), Start(), or End().

Definition at line 372 of file Timeline.h.

Referenced by openshot::ClipBase::End(), openshot::ClipBase::Layer(), openshot::ClipBase::Position(), and openshot::ClipBase::Start().

Member Data Documentation

◆ color

openshot::Color openshot::Timeline::color

Background color of timeline canvas.

Definition at line 335 of file Timeline.h.

Referenced by 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 330 of file Timeline.h.

Referenced by JsonValue(), and Timeline().

◆ viewport_x

openshot::Keyframe openshot::Timeline::viewport_x

Curve representing the x coordinate for the viewport.

Definition at line 331 of file Timeline.h.

Referenced by JsonValue(), and Timeline().

◆ viewport_y

openshot::Keyframe openshot::Timeline::viewport_y

Curve representing the y coordinate for the viewport.

Definition at line 332 of file Timeline.h.

Referenced by JsonValue(), and Timeline().

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

Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Timeline() [1/3]

◆ Timeline() [2/3]

◆ Timeline() [3/3]

◆ ~Timeline()

Member Function Documentation

◆ AddClip()

◆ AddEffect()

◆ AddTrackedObject()

◆ apply_effects()

◆ ApplyJsonDiff()

◆ ApplyMapperToClips()

◆ AutoMapClips() [1/2]

◆ AutoMapClips() [2/2]

◆ CacheEpoch()

◆ Clear()

◆ ClearAllCache()

◆ ClipEffects()

◆ Clips()

◆ Close()

◆ Effects()

◆ GetCache()

◆ GetClip()

◆ GetClipEffect()

◆ GetEffect()

◆ GetFrame()

◆ GetMaxFrame()

◆ GetMaxTime()

◆ GetMinFrame()

◆ GetMinTime()

◆ GetTrackedObject()

◆ GetTrackedObjectsIds()

◆ GetTrackedObjectValues()

◆ IsOpen()

◆ Json()

◆ JsonValue()

◆ Name()

◆ Open()

◆ RemoveClip()

◆ RemoveEffect()

◆ SafeEditFramesRemaining()

◆ SetCache()

◆ SetJson()

◆ SetJsonValue()

◆ SetMaxSize()

◆ SortTimeline()

Member Data Documentation

◆ color

◆ viewport_scale

◆ viewport_x

◆ viewport_y