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