X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=src%2Fframework%2Fmlt_playlist.c;h=91f9fa81d5d48a57323bcfc280d1ea852f0f6dfc;hb=93ba5329ea2cadd2ce01b4cceb20f1309fd37bed;hp=7dbbd7b07c073792d7e6cccfb6f0c41014d7b101;hpb=f7e7842cf52946218db15c6a45958644a96248d6;p=melted

diff --git a/src/framework/mlt_playlist.c b/src/framework/mlt_playlist.c
index 7dbbd7b..91f9fa8 100644
--- a/src/framework/mlt_playlist.c
+++ b/src/framework/mlt_playlist.c
@@ -1,7 +1,10 @@
-/*
- * mlt_playlist.c -- playlist service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_playlist.c
+ * \brief playlist service class
+ * \see mlt_playlist_s
+ *
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -18,8 +21,6 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-#include "config.h"
-
 #include "mlt_playlist.h"
 #include "mlt_tractor.h"
 #include "mlt_multitrack.h"
@@ -31,7 +32,7 @@
 #include <stdlib.h>
 #include <string.h>
 
-/** Virtual playlist entry.
+/** \brief Virtual playlist entry used by mlt_playlist_s
 */
 
 struct playlist_entry_s
@@ -46,15 +47,20 @@ struct playlist_entry_s
 	int preservation_hack;
 };
 
-/** Forward declarations
+/* Forward declarations
 */
 
 static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int index );
 static int mlt_playlist_unmix( mlt_playlist this, int clip );
 static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out );
 
-/** Constructor.
-*/
+/** Construct a playlist.
+ *
+ * Sets the resource property to "<playlist>".
+ * Set the mlt_type to property to "mlt_producer".
+ * \public \memberof mlt_playlist_s
+ * \return a new playlist
+ */
 
 mlt_playlist mlt_playlist_init( )
 {
@@ -92,12 +98,17 @@ mlt_playlist mlt_playlist_init( )
 		this->size = 10;
 		this->list = malloc( this->size * sizeof( playlist_entry * ) );
 	}
-	
+
 	return this;
 }
 
 /** Get the producer associated to this playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the producer interface
+ * \see MLT_PLAYLIST_PRODUCER
+ */
 
 mlt_producer mlt_playlist_producer( mlt_playlist this )
 {
@@ -105,15 +116,25 @@ mlt_producer mlt_playlist_producer( mlt_playlist this )
 }
 
 /** Get the service associated to this playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the service interface
+ * \see MLT_PLAYLIST_SERVICE
+ */
 
 mlt_service mlt_playlist_service( mlt_playlist this )
 {
 	return MLT_PRODUCER_SERVICE( &this->parent );
 }
 
-/** Get the propertues associated to this playlist.
-*/
+/** Get the properties associated to this playlist.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the playlist's properties list
+ * \see MLT_PLAYLIST_PROPERTIES
+ */
 
 mlt_properties mlt_playlist_properties( mlt_playlist this )
 {
@@ -121,7 +142,11 @@ mlt_properties mlt_playlist_properties( mlt_playlist this )
 }
 
 /** Refresh the playlist after a clip has been changed.
-*/
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return false
+ */
 
 static int mlt_playlist_virtual_refresh( mlt_playlist this )
 {
@@ -134,28 +159,31 @@ static int mlt_playlist_virtual_refresh( mlt_playlist this )
 	{
 		// Get the producer
 		mlt_producer producer = this->list[ i ]->producer;
-		int current_length = mlt_producer_get_out( producer ) - mlt_producer_get_in( producer ) + 1;
-
-		// Check if the length of the producer has changed
-		if ( this->list[ i ]->frame_in != mlt_producer_get_in( producer ) ||
-			 this->list[ i ]->frame_out != mlt_producer_get_out( producer ) )
+		if ( producer )
 		{
-			// This clip should be removed...
-			if ( current_length < 1 )
-			{
-				this->list[ i ]->frame_in = 0;
-				this->list[ i ]->frame_out = -1;
-				this->list[ i ]->frame_count = 0;
-			}
-			else 
+			int current_length = mlt_producer_get_out( producer ) - mlt_producer_get_in( producer ) + 1;
+
+			// Check if the length of the producer has changed
+			if ( this->list[ i ]->frame_in != mlt_producer_get_in( producer ) ||
+				this->list[ i ]->frame_out != mlt_producer_get_out( producer ) )
 			{
-				this->list[ i ]->frame_in = mlt_producer_get_in( producer );
-				this->list[ i ]->frame_out = mlt_producer_get_out( producer );
-				this->list[ i ]->frame_count = current_length;
-			}
+				// This clip should be removed...
+				if ( current_length < 1 )
+				{
+					this->list[ i ]->frame_in = 0;
+					this->list[ i ]->frame_out = -1;
+					this->list[ i ]->frame_count = 0;
+				}
+				else
+				{
+					this->list[ i ]->frame_in = mlt_producer_get_in( producer );
+					this->list[ i ]->frame_out = mlt_producer_get_out( producer );
+					this->list[ i ]->frame_count = current_length;
+				}
 
-			// Update the producer_length
-			this->list[ i ]->producer_length = current_length;
+				// Update the producer_length
+				this->list[ i ]->producer_length = current_length;
+			}
 		}
 
 		// Calculate the frame_count
@@ -175,7 +203,12 @@ static int mlt_playlist_virtual_refresh( mlt_playlist this )
 }
 
 /** Listener for producers on the playlist.
-*/
+ *
+ * Refreshes the playlist whenever an entry receives producer-changed.
+ * \private \memberof mlt_playlist_s
+ * \param producer a producer
+ * \param this a playlist
+ */
 
 static void mlt_playlist_listener( mlt_producer producer, mlt_playlist this )
 {
@@ -183,7 +216,14 @@ static void mlt_playlist_listener( mlt_producer producer, mlt_playlist this )
 }
 
 /** Append to the virtual playlist.
-*/
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param source a producer
+ * \param in the producer's starting time
+ * \param out the producer's ending time
+ * \return true if there was an error
+ */
 
 static int mlt_playlist_virtual_append( mlt_playlist this, mlt_producer source, mlt_position in, mlt_position out )
 {
@@ -285,6 +325,16 @@ static int mlt_playlist_virtual_append( mlt_playlist this, mlt_producer source,
 	return mlt_playlist_virtual_refresh( this );
 }
 
+/** Locate a producer by index.
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param[in, out] position the time at which to locate the producer, returns the time relative to the producer's starting point
+ * \param[out] clip the index of the playlist entry
+ * \param[out] total the duration of the playlist up to and including this producer
+ * \return a producer or NULL if not found
+ */
+
 static mlt_producer mlt_playlist_locate( mlt_playlist this, mlt_position *position, int *clip, int *total )
 {
 	// Default producer to NULL
@@ -315,7 +365,17 @@ static mlt_producer mlt_playlist_locate( mlt_playlist this, mlt_position *positi
 }
 
 /** Seek in the virtual playlist.
-*/
+ *
+ * This gets the producer at the current position and seeks on the producer
+ * while doing repeat and end-of-file handling. This is also responsible for
+ * closing producers previous to the preceding playlist if the autoclose
+ * property is set.
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param[out] progressive true if the producer should be displayed progressively
+ * \return the service interface of the producer at the play head
+ * \see producer_get_frame
+ */
 
 static mlt_service mlt_playlist_virtual_seek( mlt_playlist this, int *progressive )
 {
@@ -335,6 +395,27 @@ static mlt_service mlt_playlist_virtual_seek( mlt_playlist this, int *progressiv
 	// Get the properties
 	mlt_properties properties = MLT_PLAYLIST_PROPERTIES( this );
 
+	// Automatically close previous producers if requested
+	if ( i > 1 // keep immediate previous in case app wants to get info about what just finished
+		&& position < 2 // tolerate off-by-one error on going to next clip
+		&& mlt_properties_get_int( properties, "autoclose" ) )
+	{
+		int j;
+		// They might have jumped ahead!
+		for ( j = 0; j < i - 1; j++ )
+		{
+			mlt_service_lock( MLT_PRODUCER_SERVICE( this->list[ j ]->producer ) );
+			mlt_producer p = this->list[ j ]->producer;
+			if ( p )
+			{
+				this->list[ j ]->producer = NULL;
+				mlt_service_unlock( MLT_PRODUCER_SERVICE( p ) );
+				mlt_producer_close( p );
+			}
+			// If p is null, the lock will not have been "taken"
+		}
+	}
+
 	// Get the eof handling
 	char *eof = mlt_properties_get( properties, "eof" );
 
@@ -374,7 +455,12 @@ static mlt_service mlt_playlist_virtual_seek( mlt_playlist this, int *progressiv
 }
 
 /** Invoked when a producer indicates that it has prematurely reached its end.
-*/
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return a producer
+ * \see producer_get_frame
+ */
 
 static mlt_producer mlt_playlist_virtual_set_out( mlt_playlist this )
 {
@@ -417,7 +503,11 @@ static mlt_producer mlt_playlist_virtual_set_out( mlt_playlist this )
 }
 
 /** Obtain the current clips index.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the index of the playlist entry at the current position
+ */
 
 int mlt_playlist_current_clip( mlt_playlist this )
 {
@@ -445,7 +535,11 @@ int mlt_playlist_current_clip( mlt_playlist this )
 }
 
 /** Obtain the current clips producer.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the producer at the current position
+ */
 
 mlt_producer mlt_playlist_current( mlt_playlist this )
 {
@@ -457,7 +551,14 @@ mlt_producer mlt_playlist_current( mlt_playlist this )
 }
 
 /** Get the position which corresponds to the start of the next clip.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param whence the location from which to make the index relative:
+ * start of playlist, end of playlist, or current position
+ * \param index the playlist entry index relative to whence
+ * \return the time at which the referenced clip starts
+ */
 
 mlt_position mlt_playlist_clip( mlt_playlist this, mlt_whence whence, int index )
 {
@@ -495,11 +596,17 @@ mlt_position mlt_playlist_clip( mlt_playlist this, mlt_whence whence, int index
 }
 
 /** Get all the info about the clip specified.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param info a clip info struct
+ * \param index a playlist entry index
+ * \return true if there was an error
+ */
 
 int mlt_playlist_get_clip_info( mlt_playlist this, mlt_playlist_clip_info *info, int index )
 {
-	int error = index < 0 || index >= this->count;
+	int error = index < 0 || index >= this->count || this->list[ index ]->producer == NULL;
 	memset( info, 0, sizeof( mlt_playlist_clip_info ) );
 	if ( !error )
 	{
@@ -522,7 +629,11 @@ int mlt_playlist_get_clip_info( mlt_playlist this, mlt_playlist_clip_info *info,
 }
 
 /** Get number of clips in the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return the number of playlist entries
+ */
 
 int mlt_playlist_count( mlt_playlist this )
 {
@@ -530,7 +641,11 @@ int mlt_playlist_count( mlt_playlist this )
 }
 
 /** Clear the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \return true if there was an error
+ */
 
 int mlt_playlist_clear( mlt_playlist this )
 {
@@ -545,7 +660,12 @@ int mlt_playlist_clear( mlt_playlist this )
 }
 
 /** Append a producer to the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param producer the producer to append
+ * \return true if there was an error
+ */
 
 int mlt_playlist_append( mlt_playlist this, mlt_producer producer )
 {
@@ -554,7 +674,14 @@ int mlt_playlist_append( mlt_playlist this, mlt_producer producer )
 }
 
 /** Append a producer to the playlist with in/out points.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param producer the producer to append
+ * \param in the starting point on the producer
+ * \param out the ending point on the producer
+ * \return true if there was an error
+ */
 
 int mlt_playlist_append_io( mlt_playlist this, mlt_producer producer, mlt_position in, mlt_position out )
 {
@@ -566,16 +693,32 @@ int mlt_playlist_append_io( mlt_playlist this, mlt_producer producer, mlt_positi
 }
 
 /** Append a blank to the playlist of a given length.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param length the ending time of the blank entry, not its duration
+ * \return true if there was an error
+ */
 
 int mlt_playlist_blank( mlt_playlist this, mlt_position length )
 {
 	// Append to the virtual list
-	return mlt_playlist_virtual_append( this, &this->blank, 0, length );
+	if (length >= 0)
+		return mlt_playlist_virtual_append( this, &this->blank, 0, length );
+	else
+		return 1;
 }
 
 /** Insert a producer into the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param producer the producer to insert
+ * \param where the producer's playlist entry index
+ * \param in the starting point on the producer
+ * \param out the ending point on the producer
+ * \return true if there was an error
+ */
 
 int mlt_playlist_insert( mlt_playlist this, mlt_producer producer, int where, mlt_position in, mlt_position out )
 {
@@ -591,7 +734,12 @@ int mlt_playlist_insert( mlt_playlist this, mlt_producer producer, int where, ml
 }
 
 /** Remove an entry in the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param where the playlist entry index
+ * \return true if there was an error
+ */
 
 int mlt_playlist_remove( mlt_playlist this, int where )
 {
@@ -610,11 +758,11 @@ int mlt_playlist_remove( mlt_playlist this, int where )
 		// Loop variable
 		int i = 0;
 
-		// Get the clip info 
+		// Get the clip info
 		mlt_playlist_get_clip_info( this, &where_info, where );
 
 		// Make sure the clip to be removed is valid and correct if necessary
-		if ( where < 0 ) 
+		if ( where < 0 )
 			where = 0;
 		if ( where >= this->count )
 			where = this->count - 1;
@@ -637,7 +785,7 @@ int mlt_playlist_remove( mlt_playlist this, int where )
 				mlt_properties mix = mlt_properties_get_data( properties, "mix_out", NULL );
 				mlt_properties_set_data( mix, "mix_in", NULL, 0, NULL, NULL );
 			}
-	
+
 			if ( mlt_properties_ref_count( MLT_PRODUCER_PROPERTIES( entry->producer ) ) == 1 )
 				mlt_producer_clear( entry->producer );
 		}
@@ -665,23 +813,29 @@ int mlt_playlist_remove( mlt_playlist this, int where )
 }
 
 /** Move an entry in the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param src an entry index
+ * \param dest an entry index
+ * \return false
+ */
 
 int mlt_playlist_move( mlt_playlist this, int src, int dest )
 {
 	int i;
 
 	/* We need to ensure that the requested indexes are valid and correct it as necessary */
-	if ( src < 0 ) 
+	if ( src < 0 )
 		src = 0;
 	if ( src >= this->count )
 		src = this->count - 1;
 
-	if ( dest < 0 ) 
+	if ( dest < 0 )
 		dest = 0;
 	if ( dest >= this->count )
 		dest = this->count - 1;
-	
+
 	if ( src != dest && this->count > 1 )
 	{
 		int current = mlt_playlist_current_clip( this );
@@ -723,7 +877,13 @@ int mlt_playlist_move( mlt_playlist this, int src, int dest )
 }
 
 /** Repeat the specified clip n times.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip a playlist entry index
+ * \param repeat the number of times to repeat the clip
+ * \return true if there was an error
+ */
 
 int mlt_playlist_repeat_clip( mlt_playlist this, int clip, int repeat )
 {
@@ -738,7 +898,14 @@ int mlt_playlist_repeat_clip( mlt_playlist this, int clip, int repeat )
 }
 
 /** Resize the specified clip.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param in the new starting time on the clip's producer
+ * \param out the new ending time on the clip's producer
+ * \return true if there was an error
+ */
 
 int mlt_playlist_resize_clip( mlt_playlist this, int clip, mlt_position in, mlt_position out )
 {
@@ -783,7 +950,14 @@ int mlt_playlist_resize_clip( mlt_playlist this, int clip, mlt_position in, mlt_
 }
 
 /** Split a clip on the playlist at the given position.
-*/
+ *
+ * This splits after the specified frame.
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param position the time at which to split relative to the beginning of the clip or its end if negative
+ * \return true if there was an error
+ */
 
 int mlt_playlist_split( mlt_playlist this, int clip, mlt_position position )
 {
@@ -829,7 +1003,13 @@ int mlt_playlist_split( mlt_playlist this, int clip, mlt_position position )
 }
 
 /** Split the playlist at the absolute position.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position the time at which to split relative to the beginning of the clip
+ * \param left true to split before the frame starting at position
+ * \return true if there was an error
+ */
 
 int mlt_playlist_split_at( mlt_playlist this, mlt_position position, int left )
 {
@@ -860,7 +1040,14 @@ int mlt_playlist_split_at( mlt_playlist this, mlt_position position, int left )
 }
 
 /** Join 1 or more consecutive clips.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the starting playlist entry index
+ * \param count the number of entries to merge
+ * \param merge ignored
+ * \return true if there was an error
+ */
 
 int mlt_playlist_join( mlt_playlist this, int clip, int count, int merge )
 {
@@ -888,7 +1075,14 @@ int mlt_playlist_join( mlt_playlist this, int clip, int count, int merge )
 }
 
 /** Mix consecutive clips for a specified length and apply transition if specified.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param length the number of frames over which to create the mix
+ * \param transition the transition to use for the mix
+ * \return true if there was an error
+ */
 
 int mlt_playlist_mix( mlt_playlist this, int clip, int length, mlt_transition transition )
 {
@@ -984,7 +1178,13 @@ int mlt_playlist_mix( mlt_playlist this, int clip, int length, mlt_transition tr
 }
 
 /** Add a transition to an existing mix.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param transition a transition
+ * \return true if there was an error
+ */
 
 int mlt_playlist_mix_add( mlt_playlist this, int clip, mlt_transition transition )
 {
@@ -1002,7 +1202,12 @@ int mlt_playlist_mix_add( mlt_playlist this, int clip, mlt_transition transition
 }
 
 /** Return the clip at the clip index.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of a playlist entry
+ * \return a producer or NULL if there was an error
+ */
 
 mlt_producer mlt_playlist_get_clip( mlt_playlist this, int clip )
 {
@@ -1012,7 +1217,12 @@ mlt_producer mlt_playlist_get_clip( mlt_playlist this, int clip )
 }
 
 /** Return the clip at the specified position.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position a time relative to the beginning of the playlist
+ * \return a producer or NULL if not found
+ */
 
 mlt_producer mlt_playlist_get_clip_at( mlt_playlist this, mlt_position position )
 {
@@ -1021,7 +1231,12 @@ mlt_producer mlt_playlist_get_clip_at( mlt_playlist this, mlt_position position
 }
 
 /** Return the clip index of the specified position.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position a time relative to the beginning of the playlist
+ * \return the index of the playlist entry
+ */
 
 int mlt_playlist_get_clip_index_at( mlt_playlist this, mlt_position position )
 {
@@ -1031,7 +1246,12 @@ int mlt_playlist_get_clip_index_at( mlt_playlist this, mlt_position position )
 }
 
 /** Determine if the clip is a mix.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return true if the producer is a mix
+ */
 
 int mlt_playlist_clip_is_mix( mlt_playlist this, int clip )
 {
@@ -1042,12 +1262,17 @@ int mlt_playlist_clip_is_mix( mlt_playlist this, int clip )
 }
 
 /** Remove a mixed clip - ensure that the cuts included in the mix find their way
-	back correctly on to the playlist.
-*/
+ * back correctly on to the playlist.
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return true if there was an error
+ */
 
 static int mlt_playlist_unmix( mlt_playlist this, int clip )
 {
-	int error = ( clip < 0 || clip >= this->count ); 
+	int error = ( clip < 0 || clip >= this->count );
 
 	// Ensure that the clip request is actually a mix
 	if ( error == 0 )
@@ -1097,9 +1322,19 @@ static int mlt_playlist_unmix( mlt_playlist this, int clip )
 	return error;
 }
 
+/** Resize a mix clip.
+ *
+ * \private \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param in the new starting point
+ * \param out the new ending point
+ * \return true if there was an error
+ */
+
 static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out )
 {
-	int error = ( clip < 0 || clip >= this->count ); 
+	int error = ( clip < 0 || clip >= this->count );
 
 	// Ensure that the clip request is actually a mix
 	if ( error == 0 )
@@ -1141,8 +1376,12 @@ static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out
 	return error;
 }
 
-/** Consolodate adjacent blank producers.
-*/
+/** Consolidate adjacent blank producers.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param keep_length set false to remove the last entry if it is blank
+ */
 
 void mlt_playlist_consolidate_blanks( mlt_playlist this, int keep_length )
 {
@@ -1177,7 +1416,12 @@ void mlt_playlist_consolidate_blanks( mlt_playlist this, int keep_length )
 }
 
 /** Determine if the specified clip index is a blank.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return true if there was an error
+ */
 
 int mlt_playlist_is_blank( mlt_playlist this, int clip )
 {
@@ -1185,7 +1429,12 @@ int mlt_playlist_is_blank( mlt_playlist this, int clip )
 }
 
 /** Determine if the specified position is a blank.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position a time relative to the start or end (negative) of the playlist
+ * \return true if there was an error
+ */
 
 int mlt_playlist_is_blank_at( mlt_playlist this, mlt_position position )
 {
@@ -1193,7 +1442,12 @@ int mlt_playlist_is_blank_at( mlt_playlist this, mlt_position position )
 }
 
 /** Replace the specified clip with a blank and return the clip.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return a producer or NULL if there was an error
+ */
 
 mlt_producer mlt_playlist_replace_with_blank( mlt_playlist this, int clip )
 {
@@ -1217,6 +1471,14 @@ mlt_producer mlt_playlist_replace_with_blank( mlt_playlist this, int clip )
 	return producer;
 }
 
+/** Insert blank space.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the new blank section
+ * \param length the ending time of the new blank section (duration - 1)
+ */
+
 void mlt_playlist_insert_blank( mlt_playlist this, int clip, int length )
 {
 	if ( this != NULL && length >= 0 )
@@ -1230,6 +1492,14 @@ void mlt_playlist_insert_blank( mlt_playlist this, int clip, int length )
 	}
 }
 
+/** Resize a blank entry.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position the time at which the blank entry exists relative to the start or end (negative) of the playlist.
+ * \param length the additional amount of blank frames to add
+ * \param find true to fist locate the blank after the clip at position
+ */
 void mlt_playlist_pad_blanks( mlt_playlist this, mlt_position position, int length, int find )
 {
 	if ( this != NULL && length != 0 )
@@ -1257,6 +1527,16 @@ void mlt_playlist_pad_blanks( mlt_playlist this, mlt_position position, int leng
 	}
 }
 
+/** Insert a clip at a specific time.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position the time at which to insert
+ * \param producer the producer to insert
+ * \param mode true if you want to overwrite any blank section
+ * \return true if there was an error
+ */
+
 int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_producer producer, int mode )
 {
 	int ret = this == NULL || position < 0 || producer == NULL;
@@ -1299,10 +1579,10 @@ int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_produc
 			mlt_playlist_insert( this, producer, clip, -1, -1 );
 			ret = clip;
 		}
-		else 
+		else
 		{
 			if ( mode == 1 ) {
-				if ( position == info.start ) 
+				if ( position == info.start )
 					mlt_playlist_remove( this, clip );
 				else
 					mlt_playlist_blank( this, position - mlt_properties_get_int( properties, "length" ) - 1 );
@@ -1320,6 +1600,14 @@ int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_produc
 	return ret;
 }
 
+/** Get the time at which the clip starts relative to the playlist.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return the starting time
+ */
+
 int mlt_playlist_clip_start( mlt_playlist this, int clip )
 {
 	mlt_playlist_clip_info info;
@@ -1328,6 +1616,14 @@ int mlt_playlist_clip_start( mlt_playlist this, int clip )
 	return clip < 0 ? 0 : mlt_producer_get_playtime( MLT_PLAYLIST_PRODUCER( this ) );
 }
 
+/** Get the playable duration of the clip.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \return the duration of the playlist entry
+ */
+
 int mlt_playlist_clip_length( mlt_playlist this, int clip )
 {
 	mlt_playlist_clip_info info;
@@ -1336,6 +1632,15 @@ int mlt_playlist_clip_length( mlt_playlist this, int clip )
 	return 0;
 }
 
+/** Get the duration of a blank space.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param clip the index of the playlist entry
+ * \param bounded the maximum number of blank entries or 0 for all
+ * \return the duration of a blank section
+ */
+
 int mlt_playlist_blanks_from( mlt_playlist this, int clip, int bounded )
 {
 	int count = 0;
@@ -1359,6 +1664,15 @@ int mlt_playlist_blanks_from( mlt_playlist this, int clip, int bounded )
 	return count;
 }
 
+/** Remove a portion of the playlist by time.
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ * \param position the starting time
+ * \param length the duration of time to remove
+ * \return the new entry index at the position
+ */
+
 int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int length )
 {
 	int index = mlt_playlist_get_clip_index_at( this, position );
@@ -1386,7 +1700,7 @@ int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int le
 			length -= mlt_playlist_clip_length( this, index );
 			mlt_playlist_remove( this, index );
 		}
-	
+
 		mlt_playlist_consolidate_blanks( this, 0 );
 		mlt_events_unblock( properties, this );
 		mlt_playlist_virtual_refresh( this );
@@ -1397,6 +1711,17 @@ int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int le
 	return index;
 }
 
+/** Not implemented
+ *
+ * \deprecated not implemented
+ * \public \memberof mlt_playlist_s
+ * \param this
+ * \param position
+ * \param length
+ * \param new_position
+ * \return
+ */
+
 int mlt_playlist_move_region( mlt_playlist this, mlt_position position, int length, int new_position )
 {
 	if ( this != NULL )
@@ -1406,15 +1731,22 @@ int mlt_playlist_move_region( mlt_playlist this, mlt_position position, int leng
 }
 
 /** Get the current frame.
-*/
+ *
+ * The implementation of the get_frame virtual function.
+ * \private \memberof mlt_playlist_s
+ * \param producer a producer
+ * \param frame a frame by reference
+ * \param index the time at which to get the frame
+ * \return false
+ */
 
 static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int index )
 {
 	// Check that we have a producer
 	if ( producer == NULL )
 	{
-		*frame = mlt_frame_init( );
-		return 0;
+		*frame = NULL;
+		return -1;
 	}
 
 	// Get this mlt_playlist
@@ -1429,7 +1761,7 @@ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int i
 	// Check that we have a producer
 	if ( real == NULL )
 	{
-		*frame = mlt_frame_init( );
+		*frame = mlt_frame_init( MLT_PRODUCER_SERVICE( producer ) );
 		return 0;
 	}
 
@@ -1441,7 +1773,7 @@ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int i
 	else
 	{
 		mlt_producer parent = mlt_producer_cut_parent( ( mlt_producer )real );
-		*frame = mlt_frame_init( );
+		*frame = mlt_frame_init( MLT_PRODUCER_SERVICE( parent ) );
 		mlt_properties_set_int( MLT_FRAME_PROPERTIES( *frame ), "fx_cut", 1 );
 		mlt_frame_push_service( *frame, NULL );
 		mlt_frame_push_audio( *frame, NULL );
@@ -1482,7 +1814,10 @@ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int i
 }
 
 /** Close the playlist.
-*/
+ *
+ * \public \memberof mlt_playlist_s
+ * \param this a playlist
+ */
 
 void mlt_playlist_close( mlt_playlist this )
 {