Producer abstract service class. More...

#include <mlt_producer.h>

Inheritance diagram for mlt_producer_s:

Public Member Functions
int	mlt_producer_attach (mlt_producer self, mlt_filter filter)
	Attach a filter.
int	mlt_producer_clear (mlt_producer self)
	Physically reduce the producer (typically a cut) to a 0 length.
void	mlt_producer_close (mlt_producer self)
	Close the producer.
mlt_producer	mlt_producer_cut (mlt_producer self, int in, int out)
	Create a cut of this producer.
mlt_producer	mlt_producer_cut_parent (mlt_producer self)
	Obtain the parent producer.
int	mlt_producer_detach (mlt_producer self, mlt_filter filter)
	Detach a filter.
mlt_filter	mlt_producer_filter (mlt_producer self, int index)
	Retrieve a filter.
mlt_position	mlt_producer_frame (mlt_producer self)
	Get the current position (relative to start of producer).
double	mlt_producer_get_fps (mlt_producer self)
	Get the frames per second.
mlt_position	mlt_producer_get_in (mlt_producer self)
	Get the in point.
mlt_position	mlt_producer_get_length (mlt_producer self)
	Get the total, unedited length of the producer.
mlt_position	mlt_producer_get_out (mlt_producer self)
	Get the out point.
mlt_position	mlt_producer_get_playtime (mlt_producer self)
	Get the total play time.
double	mlt_producer_get_speed (mlt_producer self)
	Get the playing speed.
int	mlt_producer_init (mlt_producer self, void *child)
	Initialize a producer service.
int	mlt_producer_is_blank (mlt_producer self)
	Determine if the producer is a blank.
int	mlt_producer_is_cut (mlt_producer self)
	Determine if producer is a cut.
int	mlt_producer_is_mix (mlt_producer self)
	Determine if producer is a mix.
mlt_producer	mlt_producer_new (mlt_profile profile)
	Create and initialize a new producer.
int	mlt_producer_optimise (mlt_producer self)
	Optimise for overlapping cuts from the same clip.
mlt_position	mlt_producer_position (mlt_producer self)
	Get the current position (relative to in point).
void	mlt_producer_prepare_next (mlt_producer self)
	Prepare for next frame.
mlt_properties	mlt_producer_properties (mlt_producer self)
	Get the producer properties.
int	mlt_producer_seek (mlt_producer self, mlt_position position)
	Seek to a specified position.
mlt_service	mlt_producer_service (mlt_producer self)
	Get the parent service object.
int	mlt_producer_set_in_and_out (mlt_producer self, mlt_position in, mlt_position out)
	Set the in and out points.
int	mlt_producer_set_speed (mlt_producer self, double speed)
	Set the playing speed.
Data Fields
mlt_destructor	close
	the destructor virtual function
void *	close_object
	the object supplied to the close virtual function
int(*	get_frame )(mlt_producer, mlt_frame_ptr, int)
	Get a frame of data (virtual function).
struct mlt_service_s	parent
	A producer is a service.
Private Member Functions
static mlt_producer	mlt_producer_clone (mlt_producer self)
	Clone a producer.
static void	mlt_producer_property_changed (mlt_service owner, mlt_producer self, char *name)
	Listener for property changes.
static void	mlt_producer_service_changed (mlt_service owner, mlt_producer self)
	Listener for service changes.
static void	mlt_producer_set_clones (mlt_producer self, int clones)
	Create clones.
static int	producer_get_frame (mlt_service service, mlt_frame_ptr frame, int index)
	Get a frame.
Private Attributes
void *	child
	the object of a subclass
void *	local
	instance object

Detailed Description

Producer abstract service class.

A producer is a service that generates audio, video, and metadata. Some day it may also generate text (subtitles). This is not to say a producer "synthesizes," rather that is an origin of data within the service network - that could be through synthesis or reading a stream.

Event:: producer-changed

Property:: mlt_type the name of the service subclass, e.g. mlt_producer

Property:: mlt_service the name of a producer subclass

Property:: _position the current position of the play head, relative to the in point

Property:: _frame the current position of the play head, relative to the beginning of the resource

Property:: _speed the current speed factor, where 1.0 is normal

Property:: aspect_ratio sample aspect ratio

Property:: length the duration of the cut in frames

Property:: eof the end-of-file behavior, one of: pause, continue, loop

Property:: resource the file name, stream address, or the class name in angle brackets

Property:: _cut set if this producer is a "cut" producer

Property:: mlt_mix stores the data for a "mix" producer

Property:: _cut_parent holds a reference to the cut's parent producer

Property:: ignore_points Set this to temporarily disable the in and out points.

Property:: use_clone holds a reference to a clone's producer, as created by mlt_producer_optimise

Property:: _clone is the index of the clone in the list of clones stored on the clone's producer

Property:: _clones is the number of clones of the producer, as created by mlt_producer_optimise

Property:: _clone.{N} holds a reference to the N'th clone of the producer, as created by mlt_producer_optimise

Property:: meta.* holds metadata - there is a loose taxonomy to be defined

Property:: set.* holds properties to set on a frame produced

Todo:: define the media metadata taxonomy

Member Function Documentation

int mlt_producer_attach	(	mlt_producer	self,
		mlt_filter	filter
	)

Attach a filter.

Parameters:

self	a producer
filter	the filter to attach

Returns:: true if there was an error

int mlt_producer_clear ( mlt_producer self )

Physically reduce the producer (typically a cut) to a 0 length.

Essentially, all 0 length cuts should be immediately removed by containers.

Parameters:

self	a producer

Returns:: false

static mlt_producer mlt_producer_clone ( mlt_producer self ) [private]

Clone a producer.

Parameters:

self	a producer

Returns:: a new producer that is a copy of self

See also:: mlt_producer_set_clones

void mlt_producer_close ( mlt_producer self )

Close the producer.

Destroys the producer and deallocates its resources managed by its properties list. This will call the close virtual function. Therefore, a subclass that defines its own close function should set its virtual close function to NULL prior to calling this to avoid circular calls.

Parameters:

self	a producer

mlt_producer mlt_producer_cut	(	mlt_producer	self,
		int	in,
		int	out
	)

Create a cut of this producer.

A "cut" is a portion of another (parent) producer.

Parameters:

self	a producer
in	the beginning
out	the end

Returns:: the new producer

Todo:: Expand on the value of a cut.

mlt_producer mlt_producer_cut_parent ( mlt_producer self )

Obtain the parent producer.

Parameters:

self	a producer

Returns:: either the parent producer if self is a "cut" producer or self otherwise.

int mlt_producer_detach	(	mlt_producer	self,
		mlt_filter	filter
	)

Detach a filter.

Parameters:

self	a service
filter	the filter to detach

Returns:: true if there was an error

mlt_filter mlt_producer_filter	(	mlt_producer	self,
		int	index
	)

Retrieve a filter.

Parameters:

self	a service
index	which filter to retrieve

Returns:: the filter or null if there was an error

mlt_position mlt_producer_frame ( mlt_producer self )

Get the current position (relative to start of producer).

Parameters:

self	a producer

Returns:: the position of the "play head" regardless of the in point

double mlt_producer_get_fps ( mlt_producer self )

Get the frames per second.

This is determined by the producer's profile.

Parameters:

self	a producer

Returns:: the video refresh rate

mlt_position mlt_producer_get_in ( mlt_producer self )

Get the in point.

Parameters:

self	a producer

Returns:: the in point

mlt_position mlt_producer_get_length ( mlt_producer self )

Get the total, unedited length of the producer.

The value returned by a live streaming producer is unknown.

Parameters:

self	a producer

Returns:: the duration of the producer regardless of in and out points

mlt_position mlt_producer_get_out ( mlt_producer self )

Get the out point.

Parameters:

self	a producer

Returns:: the out point

mlt_position mlt_producer_get_playtime ( mlt_producer self )

Get the total play time.

Parameters:

self	a producer

Returns:: the playable (based on in and out points) duration

double mlt_producer_get_speed ( mlt_producer self )

Get the playing speed.

Parameters:

self	a producer

Returns:: the speed as a relative factor (1.0 = normal)

int mlt_producer_init	(	mlt_producer	self,
		void *	child
	)

Initialize a producer service.

Parameters:

self	the producer structure to initialize
child	a pointer to the child object for the subclass

Returns:: true if there was an error

int mlt_producer_is_blank ( mlt_producer self )

Determine if the producer is a blank.

Blank producers should only appear as an item in a playlist.

Parameters:

self	a producer

Returns:: true if self is a "blank" producer

See also:: mlt_playlist_insert_blank

int mlt_producer_is_cut ( mlt_producer self )

Determine if producer is a cut.

Parameters:

self	a producer

Returns:: true if self is a "cut" producer

See also:: mlt_producer_cut

int mlt_producer_is_mix ( mlt_producer self )

Determine if producer is a mix.

Parameters:

self	a producer

Returns:: true if self is a "mix" producer

Todo:: Define a mix producer.

mlt_producer mlt_producer_new ( mlt_profile profile )

Create and initialize a new producer.

Returns:: the new producer

int mlt_producer_optimise ( mlt_producer self )

Optimise for overlapping cuts from the same clip.

Todo:: learn more about this

Parameters:

self	a producer

Returns:: true if there was an error

mlt_position mlt_producer_position ( mlt_producer self )

Get the current position (relative to in point).

Parameters:

self	a producer

Returns:: the position of the "play head" relative to its beginning

void mlt_producer_prepare_next ( mlt_producer self )

Prepare for next frame.

Advance the play out position. If the speed is less than zero, it will move the play out position in the reverse direction.

Parameters:

self	a producer

mlt_properties mlt_producer_properties ( mlt_producer self )

Get the producer properties.

Parameters:

self	a producer

Returns:: the producer's property list

See also:: MLT_PRODUCER_PROPERTIES

static void mlt_producer_property_changed	(	mlt_service	owner,
		mlt_producer	self,
		char *	name
	)		`[private]`

Listener for property changes.

If the in, out, or length properties changed, fire a "producer-changed" event.

Parameters:

owner	a service (ignored)
self	the producer
name	the property that changed

int mlt_producer_seek	(	mlt_producer	self,
		mlt_position	position
	)

Seek to a specified position.

Parameters:

self	a producer
position	set the "play head" position of the producer

Returns:: false

Todo:: Document how the properties affect behavior.

mlt_service mlt_producer_service ( mlt_producer self )

Get the parent service object.

Parameters:

self	a producer

Returns:: the service parent class

See also:: MLT_PRODUCER_SERVICE

static void mlt_producer_service_changed	(	mlt_service	owner,
		mlt_producer	self
	)		`[private]`

Listener for service changes.

Fires the "producer-changed" event.

Parameters:

owner	a service (ignored)
self	the producer

static void mlt_producer_set_clones	(	mlt_producer	self,
		int	clones
	)		`[private]`

Create clones.

Parameters:

self	a producer
clones	the number of copies to make

See also:: mlt_producer_optimise

int mlt_producer_set_in_and_out	(	mlt_producer	self,
		mlt_position	in,
		mlt_position	out
	)

Set the in and out points.

The in point is where play out should start relative to the natural start of the underlying file. The out point is where play out should end, also relative to the start of the underlying file. If the underlying resource is a live stream, then the in point is an offset relative to first usable sample.

Parameters:

self	a producer
in	the relative starting time; a negative value is the same as 0
out	the relative ending time; a negative value is the same as length - 1

Returns:: false

int mlt_producer_set_speed	(	mlt_producer	self,
		double	speed
	)

Set the playing speed.

Parameters:

self	a producer
speed	the new speed as a relative factor (1.0 = normal)

Returns:: true if error

static int producer_get_frame	(	mlt_service	service,
		mlt_frame_ptr	frame,
		int	index
	)		`[private]`

Get a frame.

This is the implementation of the get_frame virtual function. It requests a new frame object from the actual producer for the current play out position. The producer and its filters can add information and operations to the frame object in their get_frame handlers.

Parameters: