git.sesse.net Git - mlt/blob - src/framework/mlt_frame.c

   1 /**
   2  * \file mlt_frame.c
   3  * \brief interface for all frame classes
   4  * \see mlt_frame_s
   5  *
   6  * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
   7  * \author Charles Yates <charles.yates@pandora.be>
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public
  11  * License as published by the Free Software Foundation; either
  12  * version 2.1 of the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  22  */
  23
  24 #include "mlt_frame.h"
  25 #include "mlt_producer.h"
  26 #include "mlt_factory.h"
  27 #include "mlt_profile.h"
  28 #include "mlt_log.h"
  29
  30 #include <stdio.h>
  31 #include <stdlib.h>
  32 #include <string.h>
  33
  34 /** Construct a frame object.
  35  *
  36  * \public \memberof mlt_frame_s
  37  * \param service the pointer to any service that can provide access to the profile
  38  * \return a frame object on success or NULL if there was an allocation error
  39  */
  40
  41 mlt_frame mlt_frame_init( mlt_service service )
  42 {
  43         // Allocate a frame
  44         mlt_frame self = calloc( 1, sizeof( struct mlt_frame_s ) );
  45
  46         if ( self != NULL )
  47         {
  48                 mlt_profile profile = mlt_service_profile( service );
  49
  50                 // Initialise the properties
  51                 mlt_properties properties = &self->parent;
  52                 mlt_properties_init( properties, self );
  53
  54                 // Set default properties on the frame
  55                 mlt_properties_set_position( properties, "_position", 0.0 );
  56                 mlt_properties_set_data( properties, "image", NULL, 0, NULL, NULL );
  57                 mlt_properties_set_int( properties, "width", profile? profile->width : 720 );
  58                 mlt_properties_set_int( properties, "height", profile? profile->height : 576 );
  59                 mlt_properties_set_double( properties, "aspect_ratio", mlt_profile_sar( NULL ) );
  60                 mlt_properties_set_data( properties, "audio", NULL, 0, NULL, NULL );
  61                 mlt_properties_set_data( properties, "alpha", NULL, 0, NULL, NULL );
  62
  63                 // Construct stacks for frames and methods
  64                 self->stack_image = mlt_deque_init( );
  65                 self->stack_audio = mlt_deque_init( );
  66                 self->stack_service = mlt_deque_init( );
  67         }
  68
  69         return self;
  70 }
  71
  72 /** Get a frame's properties.
  73  *
  74  * \public \memberof mlt_frame_s
  75  * \param self a frame
  76  * \return the frame's properties or NULL if an invalid frame is supplied
  77  */
  78
  79 mlt_properties mlt_frame_properties( mlt_frame self )
  80 {
  81         return self != NULL ? &self->parent : NULL;
  82 }
  83
  84 /** Determine if the frame will produce a test card image.
  85  *
  86  * \public \memberof mlt_frame_s
  87  * \param self a frame
  88  * \return true (non-zero) if this will produce from a test card
  89  */
  90
  91 int mlt_frame_is_test_card( mlt_frame self )
  92 {
  93         return mlt_deque_count( self->stack_image ) == 0 || mlt_properties_get_int( MLT_FRAME_PROPERTIES( self ), "test_image" );
  94 }
  95
  96 /** Determine if the frame will produce audio from a test card.
  97  *
  98  * \public \memberof mlt_frame_s
  99  * \param self a frame
 100  * \return true (non-zero) if this will produce from a test card
 101  */
 102
 103 int mlt_frame_is_test_audio( mlt_frame self )
 104 {
 105         return mlt_deque_count( self->stack_audio ) == 0 || mlt_properties_get_int( MLT_FRAME_PROPERTIES( self ), "test_audio" );
 106 }
 107
 108 /** Get the sample aspect ratio of the frame.
 109  *
 110  * \public \memberof  mlt_frame_s
 111  * \param self a frame
 112  * \return the aspect ratio
 113  */
 114
 115 double mlt_frame_get_aspect_ratio( mlt_frame self )
 116 {
 117         return mlt_properties_get_double( MLT_FRAME_PROPERTIES( self ), "aspect_ratio" );
 118 }
 119
 120 /** Set the sample aspect ratio of the frame.
 121  *
 122  * \public \memberof mlt_frame_s
 123  * \param self a frame
 124  * \param value the new image sample aspect ratio
 125  * \return true if error
 126  */
 127
 128 int mlt_frame_set_aspect_ratio( mlt_frame self, double value )
 129 {
 130         return mlt_properties_set_double( MLT_FRAME_PROPERTIES( self ), "aspect_ratio", value );
 131 }
 132
 133 /** Get the time position of this frame.
 134  *
 135  * This position is not necessarily the position as the original
 136  * producer knows it. It could be the position that the playlist,
 137  * multitrack, or tractor producer set.
 138  *
 139  * \public \memberof mlt_frame_s
 140  * \param self a frame
 141  * \return the position
 142  * \see mlt_frame_original_position
 143  */
 144
 145 mlt_position mlt_frame_get_position( mlt_frame self )
 146 {
 147         int pos = mlt_properties_get_position( MLT_FRAME_PROPERTIES( self ), "_position" );
 148         return pos < 0 ? 0 : pos;
 149 }
 150
 151 /** Get the original time position of this frame.
 152  *
 153  * This is the position that the original producer set on the frame.
 154  *
 155  * \public \memberof mlt_frame_s
 156  * \param self a frame
 157  * \return the position
 158  */
 159
 160 mlt_position mlt_frame_original_position( mlt_frame self )
 161 {
 162         int pos = mlt_properties_get_position( MLT_FRAME_PROPERTIES( self ), "original_position" );
 163         return pos < 0 ? 0 : pos;
 164 }
 165
 166 /** Set the time position of this frame.
 167  *
 168  * \public \memberof mlt_frame_s
 169  * \param self a frame
 170  * \param value the position
 171  * \return true if error
 172  */
 173
 174 int mlt_frame_set_position( mlt_frame self, mlt_position value )
 175 {
 176         // Only set the original_position the first time.
 177         if ( ! mlt_properties_get( MLT_FRAME_PROPERTIES( self ), "original_position" ) )
 178                 mlt_properties_set_position( MLT_FRAME_PROPERTIES( self ), "original_position", value );
 179         return mlt_properties_set_position( MLT_FRAME_PROPERTIES( self ), "_position", value );
 180 }
 181
 182 /** Stack a get_image callback.
 183  *
 184  * \public \memberof mlt_frame_s
 185  * \param self a frame
 186  * \param the get_image callback
 187  * \return true if error
 188  */
 189
 190 int mlt_frame_push_get_image( mlt_frame self, mlt_get_image get_image )
 191 {
 192         return mlt_deque_push_back( self->stack_image, get_image );
 193 }
 194
 195 /** Pop a get_image callback.
 196  *
 197  * \public \memberof mlt_frame_s
 198  * \param self a frame
 199  * \return the get_image callback
 200  */
 201
 202 mlt_get_image mlt_frame_pop_get_image( mlt_frame self )
 203 {
 204         return mlt_deque_pop_back( self->stack_image );
 205 }
 206
 207 /** Push a frame.
 208  *
 209  * \public \memberof mlt_frame_s
 210  * \param self a frame
 211  * \param that the frame to push onto \p self
 212  * \return true if error
 213  */
 214
 215 int mlt_frame_push_frame( mlt_frame self, mlt_frame that )
 216 {
 217         return mlt_deque_push_back( self->stack_image, that );
 218 }
 219
 220 /** Pop a frame.
 221  *
 222  * \public \memberof mlt_frame_s
 223  * \param self a frame
 224  * \return a frame that was previously pushed
 225  */
 226
 227 mlt_frame mlt_frame_pop_frame( mlt_frame self )
 228 {
 229         return mlt_deque_pop_back( self->stack_image );
 230 }
 231
 232 /** Push a service.
 233  *
 234  * \public \memberof mlt_frame_s
 235  * \param self a frame
 236  * \param that an opaque pointer
 237  * \return true if error
 238  */
 239
 240 int mlt_frame_push_service( mlt_frame self, void *that )
 241 {
 242         return mlt_deque_push_back( self->stack_image, that );
 243 }
 244
 245 /** Pop a service.
 246  *
 247  * \public \memberof mlt_frame_s
 248  * \param self a frame
 249  * \return an opaque pointer to something previously pushed
 250  */
 251
 252 void *mlt_frame_pop_service( mlt_frame self )
 253 {
 254         return mlt_deque_pop_back( self->stack_image );
 255 }
 256
 257 /** Push a number.
 258  *
 259  * \public \memberof mlt_frame_s
 260  * \param self a frame
 261  * \param that an integer
 262  * \return true if error
 263  */
 264
 265 int mlt_frame_push_service_int( mlt_frame self, int that )
 266 {
 267         return mlt_deque_push_back_int( self->stack_image, that );
 268 }
 269
 270 /** Pop a number.
 271  *
 272  * \public \memberof mlt_frame_s
 273  * \param self a frame
 274  * \return an integer that was previously pushed
 275  */
 276
 277 int mlt_frame_pop_service_int( mlt_frame self )
 278 {
 279         return mlt_deque_pop_back_int( self->stack_image );
 280 }
 281
 282 /** Push an audio item on the stack.
 283  *
 284  * \public \memberof mlt_frame_s
 285  * \param self a frame
 286  * \param that an opaque pointer
 287  * \return true if error
 288  */
 289
 290 int mlt_frame_push_audio( mlt_frame self, void *that )
 291 {
 292         return mlt_deque_push_back( self->stack_audio, that );
 293 }
 294
 295 /** Pop an audio item from the stack
 296  *
 297  * \public \memberof mlt_frame_s
 298  * \param self a frame
 299  * \return an opaque pointer to something that was pushed onto the frame's audio stack
 300  */
 301
 302 void *mlt_frame_pop_audio( mlt_frame self )
 303 {
 304         return mlt_deque_pop_back( self->stack_audio );
 305 }
 306
 307 /** Return the service stack
 308  *
 309  * \public \memberof mlt_frame_s
 310  * \param self a frame
 311  * \return the service stack
 312  */
 313
 314 mlt_deque mlt_frame_service_stack( mlt_frame self )
 315 {
 316         return self->stack_service;
 317 }
 318
 319 /** Set a new image on the frame.
 320   *
 321   * \public \memberof mlt_frame_s
 322   * \param self a frame
 323   * \param image a pointer to the raw image data
 324   * \param size the size of the image data in bytes (optional)
 325   * \param destroy a function to deallocate \p image when the frame is closed (optional)
 326   * \return true if error
 327   */
 328
 329 int mlt_frame_set_image( mlt_frame self, uint8_t *image, int size, mlt_destructor destroy )
 330 {
 331         return mlt_properties_set_data( MLT_FRAME_PROPERTIES( self ), "image", image, size, destroy, NULL );
 332 }
 333
 334 /** Set a new alpha channel on the frame.
 335   *
 336   * \public \memberof mlt_frame_s
 337   * \param self a frame
 338   * \param alpha a pointer to the alpha channel
 339   * \param size the size of the alpha channel in bytes (optional)
 340   * \param destroy a function to deallocate \p alpha when the frame is closed (optional)
 341   * \return true if error
 342   */
 343
 344 int mlt_frame_set_alpha( mlt_frame self, uint8_t *alpha, int size, mlt_destructor destroy )
 345 {
 346         self->get_alpha_mask = NULL;
 347         return mlt_properties_set_data( MLT_FRAME_PROPERTIES( self ), "alpha", alpha, size, destroy, NULL );
 348 }
 349
 350 /** Replace image stack with the information provided.
 351  *
 352  * This might prove to be unreliable and restrictive - the idea is that a transition
 353  * which normally uses two images may decide to only use the b frame (ie: in the case
 354  * of a composite where the b frame completely obscures the a frame).
 355  *
 356  * The image must be writable and the destructor for the image itself must be taken
 357  * care of on another frame and that frame cannot have a replace applied to it...
 358  * Further it assumes that no alpha mask is in use.
 359  *
 360  * For these reasons, it can only be used in a specific situation - when you have
 361  * multiple tracks each with their own transition and these transitions are applied
 362  * in a strictly reversed order (ie: highest numbered [lowest track] is processed
 363  * first).
 364  *
 365  * More reliable approach - the cases should be detected during the process phase
 366  * and the upper tracks should simply not be invited to stack...
 367  *
 368  * \public \memberof mlt_frame_s
 369  * \param self a frame
 370  * \param image a new image
 371  * \param format the image format
 372  * \param width the width of the new image
 373  * \param height the height of the new image
 374  */
 375
 376 void mlt_frame_replace_image( mlt_frame self, uint8_t *image, mlt_image_format format, int width, int height )
 377 {
 378         // Remove all items from the stack
 379         while( mlt_deque_pop_back( self->stack_image ) ) ;
 380
 381         // Update the information
 382         mlt_properties_set_data( MLT_FRAME_PROPERTIES( self ), "image", image, 0, NULL, NULL );
 383         mlt_properties_set_int( MLT_FRAME_PROPERTIES( self ), "width", width );
 384         mlt_properties_set_int( MLT_FRAME_PROPERTIES( self ), "height", height );
 385         mlt_properties_set_int( MLT_FRAME_PROPERTIES( self ), "format", format );
 386         self->get_alpha_mask = NULL;
 387 }
 388
 389 /** Get the short name for an image format.
 390  *
 391  * \public \memberof mlt_frame_s
 392  * \param format the image format
 393  * \return a string
 394  */
 395
 396 const char * mlt_image_format_name( mlt_image_format format )
 397 {
 398         switch ( format )
 399         {
 400                 case mlt_image_none:    return "none";
 401                 case mlt_image_rgb24:   return "rgb24";
 402                 case mlt_image_rgb24a:  return "rgb24a";
 403                 case mlt_image_yuv422:  return "yuv422";
 404                 case mlt_image_yuv420p: return "yuv420p";
 405                 case mlt_image_opengl:  return "opengl";
 406         }
 407         return "invalid";
 408 }
 409
 410 /** Get the number of bytes needed for an image.
 411   *
 412   * \public \memberof mlt_frame_s
 413   * \param format the image format
 414   * \param width width of the image in pixels
 415   * \param height height of the image in pixels
 416   * \param[out] bpp the number of bytes per pixel (optional)
 417   * \return the number of bytes
 418   */
 419 int mlt_image_format_size( mlt_image_format format, int width, int height, int *bpp )
 420 {
 421         height += 1;
 422         switch ( format )
 423         {
 424                 case mlt_image_none:
 425                         if ( bpp ) *bpp = 0;
 426                         return 0;
 427                 case mlt_image_rgb24:
 428                         if ( bpp ) *bpp = 3;
 429                         return width * height * 3;
 430                 case mlt_image_opengl:
 431                 case mlt_image_rgb24a:
 432                         if ( bpp ) *bpp = 4;
 433                         return width * height * 4;
 434                 case mlt_image_yuv422:
 435                         if ( bpp ) *bpp = 2;
 436                         return width * height * 2;
 437                 case mlt_image_yuv420p:
 438                         if ( bpp ) *bpp = 3 / 2;
 439                         return width * height * 3 / 2;
 440         }
 441         return 0;
 442 }
 443
 444 /** Get the image associated to the frame.
 445  *
 446  * You should express the desired format, width, and height as inputs. As long
 447  * as the loader producer was used to generate this or the imageconvert filter
 448  * was attached, then you will get the image back in the format you desire.
 449  * However, you do not always get the width and height you request depending
 450  * on properties and filters. You do not need to supply a pre-allocated
 451  * buffer, but you should always supply the desired image format.
 452  *
 453  * \public \memberof mlt_frame_s
 454  * \param self a frame
 455  * \param[out] buffer an image buffer
 456  * \param[in,out] format the image format
 457  * \param[in,out] width the horizontal size in pixels
 458  * \param[in,out] height the vertical size in pixels
 459  * \param writable whether or not you will need to be able to write to the memory returned in \p buffer
 460  * \return true if error
 461  * \todo Better describe the width and height as inputs.
 462  */
 463
 464 int mlt_frame_get_image( mlt_frame self, uint8_t **buffer, mlt_image_format *format, int *width, int *height, int writable )
 465 {
 466         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 467         mlt_get_image get_image = mlt_frame_pop_get_image( self );
 468         mlt_producer producer = mlt_properties_get_data( properties, "test_card_producer", NULL );
 469         mlt_image_format requested_format = *format;
 470         int error = 0;
 471
 472         if ( get_image )
 473         {
 474                 mlt_properties_set_int( properties, "image_count", mlt_properties_get_int( properties, "image_count" ) - 1 );
 475                 error = get_image( self, buffer, format, width, height, writable );
 476                 if ( !error && *buffer )
 477                 {
 478                         mlt_properties_set_int( properties, "width", *width );
 479                         mlt_properties_set_int( properties, "height", *height );
 480                         if ( self->convert_image && *buffer && requested_format != mlt_image_none )
 481                                 self->convert_image( self, buffer, format, requested_format );
 482                         mlt_properties_set_int( properties, "format", *format );
 483                 }
 484                 else
 485                 {
 486                         // Cause the image to be loaded from test card or fallback (white) below.
 487                         mlt_frame_get_image( self, buffer, format, width, height, writable );
 488                 }
 489         }
 490         else if ( mlt_properties_get_data( properties, "image", NULL ) )
 491         {
 492                 *format = mlt_properties_get_int( properties, "format" );
 493                 *buffer = mlt_properties_get_data( properties, "image", NULL );
 494                 *width = mlt_properties_get_int( properties, "width" );
 495                 *height = mlt_properties_get_int( properties, "height" );
 496                 if ( self->convert_image && *buffer && requested_format != mlt_image_none )
 497                 {
 498                         self->convert_image( self, buffer, format, requested_format );
 499                         mlt_properties_set_int( properties, "format", *format );
 500                 }
 501         }
 502         else if ( producer )
 503         {
 504                 mlt_frame test_frame = NULL;
 505                 mlt_service_get_frame( MLT_PRODUCER_SERVICE( producer ), &test_frame, 0 );
 506                 if ( test_frame )
 507                 {
 508                         mlt_properties test_properties = MLT_FRAME_PROPERTIES( test_frame );
 509                         mlt_properties_set( test_properties, "rescale.interp", mlt_properties_get( properties, "rescale.interp" ) );
 510                         mlt_frame_get_image( test_frame, buffer, format, width, height, writable );
 511                         mlt_properties_set_data( properties, "test_card_frame", test_frame, 0, ( mlt_destructor )mlt_frame_close, NULL );
 512                         mlt_properties_set_double( properties, "aspect_ratio", mlt_frame_get_aspect_ratio( test_frame ) );
 513 //                      mlt_properties_set_data( properties, "image", *buffer, *width * *height * 2, NULL, NULL );
 514 //                      mlt_properties_set_int( properties, "width", *width );
 515 //                      mlt_properties_set_int( properties, "height", *height );
 516 //                      mlt_properties_set_int( properties, "format", *format );
 517                 }
 518                 else
 519                 {
 520                         mlt_properties_set_data( properties, "test_card_producer", NULL, 0, NULL, NULL );
 521                         mlt_frame_get_image( self, buffer, format, width, height, writable );
 522                 }
 523         }
 524         else
 525         {
 526                 register uint8_t *p;
 527                 register uint8_t *q;
 528                 int size = 0;
 529
 530                 *width = *width == 0 ? 720 : *width;
 531                 *height = *height == 0 ? 576 : *height;
 532                 size = *width * *height;
 533
 534                 mlt_properties_set_int( properties, "format", *format );
 535                 mlt_properties_set_int( properties, "width", *width );
 536                 mlt_properties_set_int( properties, "height", *height );
 537                 mlt_properties_set_int( properties, "aspect_ratio", 0 );
 538
 539                 switch( *format )
 540                 {
 541                         case mlt_image_none:
 542                                 size = 0;
 543                                 *buffer = NULL;
 544                                 break;
 545                         case mlt_image_rgb24:
 546                                 size *= 3;
 547                                 size += *width * 3;
 548                                 *buffer = mlt_pool_alloc( size );
 549                                 if ( *buffer )
 550                                         memset( *buffer, 255, size );
 551                                 break;
 552                         case mlt_image_rgb24a:
 553                         case mlt_image_opengl:
 554                                 size *= 4;
 555                                 size += *width * 4;
 556                                 *buffer = mlt_pool_alloc( size );
 557                                 if ( *buffer )
 558                                         memset( *buffer, 255, size );
 559                                 break;
 560                         case mlt_image_yuv422:
 561                                 size *= 2;
 562                                 size += *width * 2;
 563                                 *buffer = mlt_pool_alloc( size );
 564                                 p = *buffer;
 565                                 q = p + size;
 566                                 while ( p != NULL && p != q )
 567                                 {
 568                                         *p ++ = 235;
 569                                         *p ++ = 128;
 570                                 }
 571                                 break;
 572                         case mlt_image_yuv420p:
 573                                 size = size * 3 / 2;
 574                                 *buffer = mlt_pool_alloc( size );
 575                                 if ( *buffer )
 576                                         memset( *buffer, 255, size );
 577                                 break;
 578                 }
 579
 580                 mlt_properties_set_data( properties, "image", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 581                 mlt_properties_set_int( properties, "test_image", 1 );
 582         }
 583
 584         return error;
 585 }
 586
 587 /** Get the alpha channel associated to the frame.
 588  *
 589  * \public \memberof mlt_frame_s
 590  * \param self a frame
 591  * \return the alpha channel
 592  */
 593
 594 uint8_t *mlt_frame_get_alpha_mask( mlt_frame self )
 595 {
 596         uint8_t *alpha = NULL;
 597         if ( self != NULL )
 598         {
 599                 if ( self->get_alpha_mask != NULL )
 600                         alpha = self->get_alpha_mask( self );
 601                 if ( alpha == NULL )
 602                         alpha = mlt_properties_get_data( &self->parent, "alpha", NULL );
 603                 if ( alpha == NULL )
 604                 {
 605                         int size = mlt_properties_get_int( &self->parent, "width" ) * mlt_properties_get_int( &self->parent, "height" );
 606                         alpha = mlt_pool_alloc( size );
 607                         memset( alpha, 255, size );
 608                         mlt_properties_set_data( &self->parent, "alpha", alpha, size, mlt_pool_release, NULL );
 609                 }
 610         }
 611         return alpha;
 612 }
 613
 614 /** Get the short name for an audio format.
 615  *
 616  * You do not need to deallocate the returned string.
 617  * \public \memberof mlt_frame_s
 618  * \param format an audio format enum
 619  * \return a string for the name of the image format
 620  */
 621
 622 const char * mlt_audio_format_name( mlt_audio_format format )
 623 {
 624         switch ( format )
 625         {
 626                 case mlt_audio_none:   return "none";
 627                 case mlt_audio_s16:    return "s16";
 628                 case mlt_audio_s32:    return "s32";
 629                 case mlt_audio_s32le:  return "s32le";
 630                 case mlt_audio_float:  return "float";
 631                 case mlt_audio_f32le:  return "f32le";
 632                 case mlt_audio_u8:     return "u8";
 633         }
 634         return "invalid";
 635 }
 636
 637 /** Get the amount of bytes needed for a block of audio.
 638   *
 639   * \public \memberof mlt_frame_s
 640   * \param format an audio format enum
 641   * \param samples the number of samples per channel
 642   * \param channels the number of channels
 643   * \return the number of bytes
 644   */
 645
 646 int mlt_audio_format_size( mlt_audio_format format, int samples, int channels )
 647 {
 648         switch ( format )
 649         {
 650                 case mlt_audio_none:   return 0;
 651                 case mlt_audio_s16:    return samples * channels * sizeof( int16_t );
 652                 case mlt_audio_s32le:
 653                 case mlt_audio_s32:    return samples * channels * sizeof( int32_t );
 654                 case mlt_audio_f32le:
 655                 case mlt_audio_float:  return samples * channels * sizeof( float );
 656                 case mlt_audio_u8:     return samples * channels;
 657         }
 658         return 0;
 659 }
 660
 661 /** Get the audio associated to the frame.
 662  *
 663  * You should express the desired format, frequency, channels, and samples as inputs. As long
 664  * as the loader producer was used to generate this or the audioconvert filter
 665  * was attached, then you will get the audio back in the format you desire.
 666  * However, you do not always get the channels and samples you request depending
 667  * on properties and filters. You do not need to supply a pre-allocated
 668  * buffer, but you should always supply the desired audio format.
 669  * The audio is always in interleaved format.
 670  * You should use the \p mlt_sample_calculator to determine the number of samples you want.
 671  *
 672  * \public \memberof mlt_frame_s
 673  * \param self a frame
 674  * \param[out] buffer an audio buffer
 675  * \param[in,out] format the audio format
 676  * \param[in,out] frequency the sample rate
 677  * \param[in,out] channels
 678  * \param[in,out] samples the number of samples per frame
 679  * \return true if error
 680  */
 681
 682 int mlt_frame_get_audio( mlt_frame self, void **buffer, mlt_audio_format *format, int *frequency, int *channels, int *samples )
 683 {
 684         mlt_get_audio get_audio = mlt_frame_pop_audio( self );
 685         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 686         int hide = mlt_properties_get_int( properties, "test_audio" );
 687         mlt_audio_format requested_format = *format;
 688
 689         if ( hide == 0 && get_audio != NULL )
 690         {
 691                 get_audio( self, buffer, format, frequency, channels, samples );
 692                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 693                 mlt_properties_set_int( properties, "audio_channels", *channels );
 694                 mlt_properties_set_int( properties, "audio_samples", *samples );
 695                 mlt_properties_set_int( properties, "audio_format", *format );
 696                 if ( self->convert_audio && *buffer && requested_format != mlt_audio_none )
 697                         self->convert_audio( self, buffer, format, requested_format );
 698         }
 699         else if ( mlt_properties_get_data( properties, "audio", NULL ) )
 700         {
 701                 *buffer = mlt_properties_get_data( properties, "audio", NULL );
 702                 *format = mlt_properties_get_int( properties, "audio_format" );
 703                 *frequency = mlt_properties_get_int( properties, "audio_frequency" );
 704                 *channels = mlt_properties_get_int( properties, "audio_channels" );
 705                 *samples = mlt_properties_get_int( properties, "audio_samples" );
 706                 if ( self->convert_audio && *buffer && requested_format != mlt_audio_none )
 707                         self->convert_audio( self, buffer, format, requested_format );
 708         }
 709         else
 710         {
 711                 int size = 0;
 712                 *samples = *samples <= 0 ? 1920 : *samples;
 713                 *channels = *channels <= 0 ? 2 : *channels;
 714                 *frequency = *frequency <= 0 ? 48000 : *frequency;
 715                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 716                 mlt_properties_set_int( properties, "audio_channels", *channels );
 717                 mlt_properties_set_int( properties, "audio_samples", *samples );
 718                 mlt_properties_set_int( properties, "audio_format", *format );
 719
 720                 switch( *format )
 721                 {
 722                         case mlt_image_none:
 723                                 size = 0;
 724                                 *buffer = NULL;
 725                                 break;
 726                         case mlt_audio_s16:
 727                                 size = *samples * *channels * sizeof( int16_t );
 728                                 break;
 729                         case mlt_audio_s32:
 730                                 size = *samples * *channels * sizeof( int32_t );
 731                                 break;
 732                         case mlt_audio_float:
 733                                 size = *samples * *channels * sizeof( float );
 734                                 break;
 735                         default:
 736                                 break;
 737                 }
 738                 if ( size )
 739                         *buffer = mlt_pool_alloc( size );
 740                 if ( *buffer )
 741                         memset( *buffer, 0, size );
 742                 mlt_properties_set_data( properties, "audio", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 743                 mlt_properties_set_int( properties, "test_audio", 1 );
 744         }
 745
 746         // TODO: This does not belong here
 747         if ( *format == mlt_audio_s16 && mlt_properties_get( properties, "meta.volume" ) )
 748         {
 749                 double value = mlt_properties_get_double( properties, "meta.volume" );
 750
 751                 if ( value == 0.0 )
 752                 {
 753                         memset( *buffer, 0, *samples * *channels * 2 );
 754                 }
 755                 else if ( value != 1.0 )
 756                 {
 757                         int total = *samples * *channels;
 758                         int16_t *p = *buffer;
 759                         while ( total -- )
 760                         {
 761                                 *p = *p * value;
 762                                 p ++;
 763                         }
 764                 }
 765
 766                 mlt_properties_set( properties, "meta.volume", NULL );
 767         }
 768
 769         return 0;
 770 }
 771
 772 /** Set the audio on a frame.
 773  *
 774  * \public \memberof mlt_frame_s
 775  * \param self a frame
 776  * \param buffer an buffer containing audio samples
 777  * \param format the format of the audio in the \p buffer
 778  * \param size the total size of the buffer (optional)
 779  * \param destructor a function that releases or deallocates the \p buffer
 780  * \return true if error
 781  */
 782
 783 int mlt_frame_set_audio( mlt_frame self, void *buffer, mlt_audio_format format, int size, mlt_destructor destructor )
 784 {
 785         mlt_properties_set_int( MLT_FRAME_PROPERTIES( self ), "audio_format", format );
 786         return mlt_properties_set_data( MLT_FRAME_PROPERTIES( self ), "audio", buffer, size, destructor, NULL );
 787 }
 788
 789 /** Get audio on a frame as a waveform image.
 790  *
 791  * This generates an 8-bit grayscale image representation of the audio in a
 792  * frame. Currently, this only really works for 2 channels.
 793  * This allocates the bitmap using mlt_pool so you should release the return
 794  * value with \p mlt_pool_release.
 795  *
 796  * \public \memberof mlt_frame_s
 797  * \param self a frame
 798  * \param w the width of the image
 799  * \param h the height of the image to create
 800  * \return a pointer to a new bitmap
 801  */
 802
 803 unsigned char *mlt_frame_get_waveform( mlt_frame self, int w, int h )
 804 {
 805         int16_t *pcm = NULL;
 806         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 807         mlt_audio_format format = mlt_audio_s16;
 808         int frequency = 16000;
 809         int channels = 2;
 810         mlt_producer producer = mlt_frame_get_original_producer( self );
 811         double fps = mlt_producer_get_fps( mlt_producer_cut_parent( producer ) );
 812         int samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( self ) );
 813
 814         // Increase audio resolution proportional to requested image size
 815         while ( samples < w )
 816         {
 817                 frequency += 16000;
 818                 samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( self ) );
 819         }
 820
 821         // Get the pcm data
 822         mlt_frame_get_audio( self, (void**)&pcm, &format, &frequency, &channels, &samples );
 823
 824         // Make an 8-bit buffer large enough to hold rendering
 825         int size = w * h;
 826         if ( size <= 0 )
 827                 return NULL;
 828         unsigned char *bitmap = ( unsigned char* )mlt_pool_alloc( size );
 829         if ( bitmap != NULL )
 830                 memset( bitmap, 0, size );
 831         else
 832                 return NULL;
 833         mlt_properties_set_data( properties, "waveform", bitmap, size, ( mlt_destructor )mlt_pool_release, NULL );
 834
 835         // Render vertical lines
 836         int16_t *ubound = pcm + samples * channels;
 837         int skip = samples / w;
 838         skip = !skip ? 1 : skip;
 839         unsigned char gray = 0xFF / skip;
 840         int i, j, k;
 841
 842         // Iterate sample stream and along x coordinate
 843         for ( i = 0; pcm < ubound; i++ )
 844         {
 845                 // pcm data has channels interleaved
 846                 for ( j = 0; j < channels; j++, pcm++ )
 847                 {
 848                         // Determine sample's magnitude from 2s complement;
 849                         int pcm_magnitude = *pcm < 0 ? ~(*pcm) + 1 : *pcm;
 850                         // The height of a line is the ratio of the magnitude multiplied by
 851                         // the vertical resolution of a single channel
 852                                 int height = h * pcm_magnitude / channels / 2 / 32768;
 853                         // Determine the starting y coordinate - left top, right bottom
 854                         int displacement = h * (j * 2 + 1) / channels / 2 - ( *pcm < 0 ? 0 : height );
 855                         // Position buffer pointer using y coordinate, stride, and x coordinate
 856                         unsigned char *p = bitmap + i / skip + displacement * w;
 857
 858                         // Draw vertical line
 859                         for ( k = 0; k < height + 1; k++ )
 860                                 if ( *pcm < 0 )
 861                                         p[ w * k ] = ( k == 0 ) ? 0xFF : p[ w * k ] + gray;
 862                                 else
 863                                         p[ w * k ] = ( k == height ) ? 0xFF : p[ w * k ] + gray;
 864                 }
 865         }
 866
 867         return bitmap;
 868 }
 869
 870 /** Get the end service that produced self frame.
 871  *
 872  * This fetches the first producer of the frame and not any producers that
 873  * encapsulate it.
 874  *
 875  * \public \memberof mlt_frame_s
 876  * \param self a frame
 877  * \return a producer
 878  */
 879
 880 mlt_producer mlt_frame_get_original_producer( mlt_frame self )
 881 {
 882         if ( self != NULL )
 883                 return mlt_properties_get_data( MLT_FRAME_PROPERTIES( self ), "_producer", NULL );
 884         return NULL;
 885 }
 886
 887 /** Destroy the frame.
 888  *
 889  * \public \memberof mlt_frame_s
 890  * \param self a frame
 891  */
 892
 893 void mlt_frame_close( mlt_frame self )
 894 {
 895         if ( self != NULL && mlt_properties_dec_ref( MLT_FRAME_PROPERTIES( self ) ) <= 0 )
 896         {
 897                 mlt_deque_close( self->stack_image );
 898                 mlt_deque_close( self->stack_audio );
 899                 while( mlt_deque_peek_back( self->stack_service ) )
 900                         mlt_service_close( mlt_deque_pop_back( self->stack_service ) );
 901                 mlt_deque_close( self->stack_service );
 902                 mlt_properties_close( &self->parent );
 903                 free( self );
 904         }
 905 }
 906
 907 /***** convenience functions *****/
 908
 909 /** Determine the number of samples that belong in a frame at a time position.
 910  *
 911  * \public \memberof mlt_frame_s
 912  * \param fps the frame rate
 913  * \param frequency the sample rate
 914  * \param position the time position
 915  * \return the number of samples per channel
 916  */
 917
 918 int mlt_sample_calculator( float fps, int frequency, int64_t position )
 919 {
 920         /* Compute the cumulative number of samples until the start of this frame and the
 921         cumulative number of samples until the start of the next frame. Round each to the
 922         nearest integer and take the difference to determine the number of samples in
 923         this frame.
 924
 925         This approach should prevent rounding errors that can accumulate over a large number
 926         of frames causing A/V sync problems. */
 927         return mlt_sample_calculator_to_now( fps, frequency, position + 1 )
 928                  - mlt_sample_calculator_to_now( fps, frequency, position );
 929 }
 930
 931 /** Determine the number of samples that belong before a time position.
 932  *
 933  * \public \memberof mlt_frame_s
 934  * \param fps the frame rate
 935  * \param frequency the sample rate
 936  * \param position the time position
 937  * \return the number of samples per channel
 938  * \bug Will this break when mlt_position is converted to double?
 939  */
 940
 941 int64_t mlt_sample_calculator_to_now( float fps, int frequency, int64_t position )
 942 {
 943         int64_t samples = 0;
 944
 945         if ( fps )
 946         {
 947                 samples = (int64_t)( (double) position * (double) frequency / (double) fps +
 948                         ( position < 0 ? -0.5 : 0.5 ) );
 949         }
 950
 951         return samples;
 952 }
 953
 954 void mlt_frame_write_ppm( mlt_frame frame )
 955 {
 956         int width = 0;
 957         int height = 0;
 958         mlt_image_format format = mlt_image_rgb24;
 959         uint8_t *image;
 960
 961         if ( mlt_frame_get_image( frame, &image, &format, &width, &height, 0 ) == 0 )
 962         {
 963                 FILE *file;
 964                 char filename[16];
 965
 966                 sprintf( filename, "frame-%05d.ppm", mlt_frame_get_position( frame ) );
 967                 file = fopen( filename, "wb" );
 968                 if ( !file )
 969                         return;
 970                 fprintf( file, "P6\n%d %d\n255\n", width, height);
 971                 fwrite( image, width * height * 3, 1, file );
 972                 fclose( file );
 973         }
 974 }
 975
 976 /** Get or create a properties object unique to this service instance.
 977  *
 978  * Use this function to hold a service's processing parameters for this
 979  * particular frame. Set the parameters in the service's process function.
 980  * Then, get the parameters in the function it pushes to the frame's audio
 981  * or image stack. This makes the service more parallel by reducing race
 982  * conditions and less sensitive to multiple instances (by not setting a
 983  * non-unique property on the frame). Creation and destruction of the
 984  * properties object is handled automatically.
 985  *
 986  * \public \memberof mlt_frame_s
 987  * \param self a frame
 988  * \param service a service
 989  * \return a properties object
 990  */
 991
 992 mlt_properties mlt_frame_unique_properties( mlt_frame self, mlt_service service )
 993 {
 994         mlt_properties frame_props = MLT_FRAME_PROPERTIES( self );
 995         mlt_properties service_props = MLT_SERVICE_PROPERTIES( service );
 996         char *unique = mlt_properties_get( service_props, "_unique_id" );
 997         mlt_properties instance_props = mlt_properties_get_data( frame_props, unique, NULL );
 998
 999         if ( !instance_props )
1000         {
1001                 instance_props = mlt_properties_new();
1002                 mlt_properties_set_data( frame_props, unique, instance_props, 0, (mlt_destructor) mlt_properties_close, NULL );
1003         }
1004
1005         return instance_props;
1006 }
1007
1008 /** Make a copy of a frame.
1009  *
1010  * This does not copy the get_image/get_audio processing stacks or any
1011  * data properties other than the audio and image.
1012  *
1013  * \public \memberof mlt_frame_s
1014  * \param self the frame to clone
1015  * \param is_deep a boolean to indicate whether to make a deep copy of the audio
1016  * and video data chunks or to make a shallow copy by pointing to the supplied frame
1017  * \return a almost-complete copy of the frame
1018  * \todo copy the processing deques
1019  */
1020
1021 mlt_frame mlt_frame_clone( mlt_frame self, int is_deep )
1022 {
1023         mlt_frame new_frame = mlt_frame_init( NULL );
1024         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
1025         mlt_properties new_props = MLT_FRAME_PROPERTIES( new_frame );
1026         void *data, *copy;
1027         int size;
1028
1029         mlt_properties_inherit( new_props, properties );
1030         if ( is_deep )
1031         {
1032                 data = mlt_properties_get_data( properties, "audio", &size );
1033                 if ( data )
1034                 {
1035                         if ( !size )
1036                                 size = mlt_audio_format_size( mlt_properties_get_int( properties, "audio_format" ),
1037                                         mlt_properties_get_int( properties, "audio_samples" ),
1038                                         mlt_properties_get_int( properties, "audio_channels" ) );
1039                         copy = mlt_pool_alloc( size );
1040                         memcpy( copy, data, size );
1041                         mlt_properties_set_data( new_props, "audio", copy, size, mlt_pool_release, NULL );
1042                 }
1043                 data = mlt_properties_get_data( properties, "image", &size );
1044                 if ( data )
1045                 {
1046                         if ( ! size )
1047                                 size = mlt_image_format_size( mlt_properties_get_int( properties, "format" ),
1048                                         mlt_properties_get_int( properties, "width" ),
1049                                         mlt_properties_get_int( properties, "height" ), NULL );
1050                         copy = mlt_pool_alloc( size );
1051                         memcpy( copy, data, size );
1052                         mlt_properties_set_data( new_props, "image", copy, size, mlt_pool_release, NULL );
1053
1054                         data = mlt_properties_get_data( properties, "alpha", &size );
1055                         if ( data )
1056                         {
1057                                 if ( ! size )
1058                                         size = mlt_properties_get_int( properties, "width" ) *
1059                                                 mlt_properties_get_int( properties, "height" );
1060                                 copy = mlt_pool_alloc( size );
1061                                 memcpy( copy, data, size );
1062                                 mlt_properties_set_data( new_props, "alpha", copy, size, mlt_pool_release, NULL );
1063                         };
1064                 }
1065         }
1066         else
1067         {
1068                 // This frame takes a reference on the original frame since the data is a shallow copy.
1069                 mlt_properties_inc_ref( properties );
1070                 mlt_properties_set_data( new_props, "_cloned_frame", self, 0,
1071                         (mlt_destructor) mlt_frame_close, NULL );
1072
1073                 // Copy properties
1074                 data = mlt_properties_get_data( properties, "audio", &size );
1075                 mlt_properties_set_data( new_props, "audio", data, size, NULL, NULL );
1076                 data = mlt_properties_get_data( properties, "image", &size );
1077                 mlt_properties_set_data( new_props, "image", data, size, NULL, NULL );
1078                 data = mlt_properties_get_data( properties, "alpha", &size );
1079                 mlt_properties_set_data( new_props, "alpha", data, size, NULL, NULL );
1080         }
1081
1082         return new_frame;
1083 }