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_yuv422:
 513                                 size *= 2;
 514                                 size += *width * 2;
 515                                 *buffer = mlt_pool_alloc( size );
 516                                 if ( *buffer )
 517                                 {
 518                                         register uint8_t *p = *buffer;
 519                                         register uint8_t *q = p + size;
 520                                         while ( p != NULL && p != q )
 521                                         {
 522                                                 *p ++ = 235;
 523                                                 *p ++ = 128;
 524                                         }
 525                                 }
 526                                 break;
 527                         case mlt_image_yuv420p:
 528                                 *buffer = mlt_pool_alloc( size * 3 / 2 );
 529                                 if ( *buffer )
 530                                 {
 531                                         memset( *buffer, 235, size );
 532                                         memset( *buffer + size, 128, size / 2 );
 533                                 }
 534                                 break;
 535                         default:
 536                                 size = 0;
 537                                 break;
 538                 }
 539                 mlt_properties_set_data( properties, "image", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 540                 mlt_properties_set_int( properties, "test_image", 1 );
 541                 error = 0;
 542         }
 543         return error;
 544 }
 545
 546
 547 /** Get the image associated to the frame.
 548  *
 549  * You should express the desired format, width, and height as inputs. As long
 550  * as the loader producer was used to generate this or the imageconvert filter
 551  * was attached, then you will get the image back in the format you desire.
 552  * However, you do not always get the width and height you request depending
 553  * on properties and filters. You do not need to supply a pre-allocated
 554  * buffer, but you should always supply the desired image format.
 555  *
 556  * \public \memberof mlt_frame_s
 557  * \param self a frame
 558  * \param[out] buffer an image buffer
 559  * \param[in,out] format the image format
 560  * \param[in,out] width the horizontal size in pixels
 561  * \param[in,out] height the vertical size in pixels
 562  * \param writable whether or not you will need to be able to write to the memory returned in \p buffer
 563  * \return true if error
 564  * \todo Better describe the width and height as inputs.
 565  */
 566
 567 int mlt_frame_get_image( mlt_frame self, uint8_t **buffer, mlt_image_format *format, int *width, int *height, int writable )
 568 {
 569         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 570         mlt_get_image get_image = mlt_frame_pop_get_image( self );
 571         mlt_image_format requested_format = *format;
 572         int error = 0;
 573
 574         if ( get_image )
 575         {
 576                 mlt_properties_set_int( properties, "image_count", mlt_properties_get_int( properties, "image_count" ) - 1 );
 577                 error = get_image( self, buffer, format, width, height, writable );
 578                 if ( !error && buffer && *buffer )
 579                 {
 580                         mlt_properties_set_int( properties, "width", *width );
 581                         mlt_properties_set_int( properties, "height", *height );
 582                         if ( self->convert_image && requested_format != mlt_image_none )
 583                                 self->convert_image( self, buffer, format, requested_format );
 584                         mlt_properties_set_int( properties, "format", *format );
 585                 }
 586                 else
 587                 {
 588                         error = generate_test_image( properties, buffer, format, width, height, writable );
 589                 }
 590         }
 591         else if ( mlt_properties_get_data( properties, "image", NULL ) && buffer )
 592         {
 593                 *format = mlt_properties_get_int( properties, "format" );
 594                 *buffer = mlt_properties_get_data( properties, "image", NULL );
 595                 *width = mlt_properties_get_int( properties, "width" );
 596                 *height = mlt_properties_get_int( properties, "height" );
 597                 if ( self->convert_image && *buffer && requested_format != mlt_image_none )
 598                 {
 599                         self->convert_image( self, buffer, format, requested_format );
 600                         mlt_properties_set_int( properties, "format", *format );
 601                 }
 602         }
 603         else
 604         {
 605                 error = generate_test_image( properties, buffer, format, width, height, writable );
 606         }
 607
 608         return error;
 609 }
 610
 611 /** Get the alpha channel associated to the frame.
 612  *
 613  * \public \memberof mlt_frame_s
 614  * \param self a frame
 615  * \return the alpha channel
 616  */
 617
 618 uint8_t *mlt_frame_get_alpha_mask( mlt_frame self )
 619 {
 620         uint8_t *alpha = NULL;
 621         if ( self != NULL )
 622         {
 623                 if ( self->get_alpha_mask != NULL )
 624                         alpha = self->get_alpha_mask( self );
 625                 if ( alpha == NULL )
 626                         alpha = mlt_properties_get_data( &self->parent, "alpha", NULL );
 627                 if ( alpha == NULL )
 628                 {
 629                         int size = mlt_properties_get_int( &self->parent, "width" ) * mlt_properties_get_int( &self->parent, "height" );
 630                         alpha = mlt_pool_alloc( size );
 631                         memset( alpha, 255, size );
 632                         mlt_properties_set_data( &self->parent, "alpha", alpha, size, mlt_pool_release, NULL );
 633                 }
 634         }
 635         return alpha;
 636 }
 637
 638 /** Get the short name for an audio format.
 639  *
 640  * You do not need to deallocate the returned string.
 641  * \public \memberof mlt_frame_s
 642  * \param format an audio format enum
 643  * \return a string for the name of the image format
 644  */
 645
 646 const char * mlt_audio_format_name( mlt_audio_format format )
 647 {
 648         switch ( format )
 649         {
 650                 case mlt_audio_none:   return "none";
 651                 case mlt_audio_s16:    return "s16";
 652                 case mlt_audio_s32:    return "s32";
 653                 case mlt_audio_s32le:  return "s32le";
 654                 case mlt_audio_float:  return "float";
 655                 case mlt_audio_f32le:  return "f32le";
 656                 case mlt_audio_u8:     return "u8";
 657         }
 658         return "invalid";
 659 }
 660
 661 /** Get the amount of bytes needed for a block of audio.
 662   *
 663   * \public \memberof mlt_frame_s
 664   * \param format an audio format enum
 665   * \param samples the number of samples per channel
 666   * \param channels the number of channels
 667   * \return the number of bytes
 668   */
 669
 670 int mlt_audio_format_size( mlt_audio_format format, int samples, int channels )
 671 {
 672         switch ( format )
 673         {
 674                 case mlt_audio_none:   return 0;
 675                 case mlt_audio_s16:    return samples * channels * sizeof( int16_t );
 676                 case mlt_audio_s32le:
 677                 case mlt_audio_s32:    return samples * channels * sizeof( int32_t );
 678                 case mlt_audio_f32le:
 679                 case mlt_audio_float:  return samples * channels * sizeof( float );
 680                 case mlt_audio_u8:     return samples * channels;
 681         }
 682         return 0;
 683 }
 684
 685 /** Get the audio associated to the frame.
 686  *
 687  * You should express the desired format, frequency, channels, and samples as inputs. As long
 688  * as the loader producer was used to generate this or the audioconvert filter
 689  * was attached, then you will get the audio back in the format you desire.
 690  * However, you do not always get the channels and samples you request depending
 691  * on properties and filters. You do not need to supply a pre-allocated
 692  * buffer, but you should always supply the desired audio format.
 693  * The audio is always in interleaved format.
 694  * You should use the \p mlt_sample_calculator to determine the number of samples you want.
 695  *
 696  * \public \memberof mlt_frame_s
 697  * \param self a frame
 698  * \param[out] buffer an audio buffer
 699  * \param[in,out] format the audio format
 700  * \param[in,out] frequency the sample rate
 701  * \param[in,out] channels
 702  * \param[in,out] samples the number of samples per frame
 703  * \return true if error
 704  */
 705
 706 int mlt_frame_get_audio( mlt_frame self, void **buffer, mlt_audio_format *format, int *frequency, int *channels, int *samples )
 707 {
 708         mlt_get_audio get_audio = mlt_frame_pop_audio( self );
 709         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 710         int hide = mlt_properties_get_int( properties, "test_audio" );
 711         mlt_audio_format requested_format = *format;
 712
 713         if ( hide == 0 && get_audio != NULL )
 714         {
 715                 get_audio( self, buffer, format, frequency, channels, samples );
 716                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 717                 mlt_properties_set_int( properties, "audio_channels", *channels );
 718                 mlt_properties_set_int( properties, "audio_samples", *samples );
 719                 mlt_properties_set_int( properties, "audio_format", *format );
 720                 if ( self->convert_audio && *buffer && requested_format != mlt_audio_none )
 721                         self->convert_audio( self, buffer, format, requested_format );
 722         }
 723         else if ( mlt_properties_get_data( properties, "audio", NULL ) )
 724         {
 725                 *buffer = mlt_properties_get_data( properties, "audio", NULL );
 726                 *format = mlt_properties_get_int( properties, "audio_format" );
 727                 *frequency = mlt_properties_get_int( properties, "audio_frequency" );
 728                 *channels = mlt_properties_get_int( properties, "audio_channels" );
 729                 *samples = mlt_properties_get_int( properties, "audio_samples" );
 730                 if ( self->convert_audio && *buffer && requested_format != mlt_audio_none )
 731                         self->convert_audio( self, buffer, format, requested_format );
 732         }
 733         else
 734         {
 735                 int size = 0;
 736                 *samples = *samples <= 0 ? 1920 : *samples;
 737                 *channels = *channels <= 0 ? 2 : *channels;
 738                 *frequency = *frequency <= 0 ? 48000 : *frequency;
 739                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 740                 mlt_properties_set_int( properties, "audio_channels", *channels );
 741                 mlt_properties_set_int( properties, "audio_samples", *samples );
 742                 mlt_properties_set_int( properties, "audio_format", *format );
 743
 744                 size = mlt_audio_format_size( *format, *samples, *channels );
 745                 if ( size )
 746                         *buffer = mlt_pool_alloc( size );
 747                 else
 748                         *buffer = NULL;
 749                 if ( *buffer )
 750                         memset( *buffer, 0, size );
 751                 mlt_properties_set_data( properties, "audio", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 752                 mlt_properties_set_int( properties, "test_audio", 1 );
 753         }
 754
 755         // TODO: This does not belong here
 756         if ( *format == mlt_audio_s16 && mlt_properties_get( properties, "meta.volume" ) )
 757         {
 758                 double value = mlt_properties_get_double( properties, "meta.volume" );
 759
 760                 if ( value == 0.0 )
 761                 {
 762                         memset( *buffer, 0, *samples * *channels * 2 );
 763                 }
 764                 else if ( value != 1.0 )
 765                 {
 766                         int total = *samples * *channels;
 767                         int16_t *p = *buffer;
 768                         while ( total -- )
 769                         {
 770                                 *p = *p * value;
 771                                 p ++;
 772                         }
 773                 }
 774
 775                 mlt_properties_set( properties, "meta.volume", NULL );
 776         }
 777
 778         return 0;
 779 }
 780
 781 /** Set the audio on a frame.
 782  *
 783  * \public \memberof mlt_frame_s
 784  * \param self a frame
 785  * \param buffer an buffer containing audio samples
 786  * \param format the format of the audio in the \p buffer
 787  * \param size the total size of the buffer (optional)
 788  * \param destructor a function that releases or deallocates the \p buffer
 789  * \return true if error
 790  */
 791
 792 int mlt_frame_set_audio( mlt_frame self, void *buffer, mlt_audio_format format, int size, mlt_destructor destructor )
 793 {
 794         mlt_properties_set_int( MLT_FRAME_PROPERTIES( self ), "audio_format", format );
 795         return mlt_properties_set_data( MLT_FRAME_PROPERTIES( self ), "audio", buffer, size, destructor, NULL );
 796 }
 797
 798 /** Get audio on a frame as a waveform image.
 799  *
 800  * This generates an 8-bit grayscale image representation of the audio in a
 801  * frame. Currently, this only really works for 2 channels.
 802  * This allocates the bitmap using mlt_pool so you should release the return
 803  * value with \p mlt_pool_release.
 804  *
 805  * \public \memberof mlt_frame_s
 806  * \param self a frame
 807  * \param w the width of the image
 808  * \param h the height of the image to create
 809  * \return a pointer to a new bitmap
 810  */
 811
 812 unsigned char *mlt_frame_get_waveform( mlt_frame self, int w, int h )
 813 {
 814         int16_t *pcm = NULL;
 815         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
 816         mlt_audio_format format = mlt_audio_s16;
 817         int frequency = 16000;
 818         int channels = 2;
 819         mlt_producer producer = mlt_frame_get_original_producer( self );
 820         double fps = mlt_producer_get_fps( mlt_producer_cut_parent( producer ) );
 821         int samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( self ) );
 822
 823         // Increase audio resolution proportional to requested image size
 824         while ( samples < w )
 825         {
 826                 frequency += 16000;
 827                 samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( self ) );
 828         }
 829
 830         // Get the pcm data
 831         mlt_frame_get_audio( self, (void**)&pcm, &format, &frequency, &channels, &samples );
 832
 833         // Make an 8-bit buffer large enough to hold rendering
 834         int size = w * h;
 835         if ( size <= 0 )
 836                 return NULL;
 837         unsigned char *bitmap = ( unsigned char* )mlt_pool_alloc( size );
 838         if ( bitmap != NULL )
 839                 memset( bitmap, 0, size );
 840         else
 841                 return NULL;
 842         mlt_properties_set_data( properties, "waveform", bitmap, size, ( mlt_destructor )mlt_pool_release, NULL );
 843
 844         // Render vertical lines
 845         int16_t *ubound = pcm + samples * channels;
 846         int skip = samples / w;
 847         skip = !skip ? 1 : skip;
 848         unsigned char gray = 0xFF / skip;
 849         int i, j, k;
 850
 851         // Iterate sample stream and along x coordinate
 852         for ( i = 0; pcm < ubound; i++ )
 853         {
 854                 // pcm data has channels interleaved
 855                 for ( j = 0; j < channels; j++, pcm++ )
 856                 {
 857                         // Determine sample's magnitude from 2s complement;
 858                         int pcm_magnitude = *pcm < 0 ? ~(*pcm) + 1 : *pcm;
 859                         // The height of a line is the ratio of the magnitude multiplied by
 860                         // the vertical resolution of a single channel
 861                                 int height = h * pcm_magnitude / channels / 2 / 32768;
 862                         // Determine the starting y coordinate - left top, right bottom
 863                         int displacement = h * (j * 2 + 1) / channels / 2 - ( *pcm < 0 ? 0 : height );
 864                         // Position buffer pointer using y coordinate, stride, and x coordinate
 865                         unsigned char *p = bitmap + i / skip + displacement * w;
 866
 867                         // Draw vertical line
 868                         for ( k = 0; k < height + 1; k++ )
 869                                 if ( *pcm < 0 )
 870                                         p[ w * k ] = ( k == 0 ) ? 0xFF : p[ w * k ] + gray;
 871                                 else
 872                                         p[ w * k ] = ( k == height ) ? 0xFF : p[ w * k ] + gray;
 873                 }
 874         }
 875
 876         return bitmap;
 877 }
 878
 879 /** Get the end service that produced self frame.
 880  *
 881  * This fetches the first producer of the frame and not any producers that
 882  * encapsulate it.
 883  *
 884  * \public \memberof mlt_frame_s
 885  * \param self a frame
 886  * \return a producer
 887  */
 888
 889 mlt_producer mlt_frame_get_original_producer( mlt_frame self )
 890 {
 891         if ( self != NULL )
 892                 return mlt_properties_get_data( MLT_FRAME_PROPERTIES( self ), "_producer", NULL );
 893         return NULL;
 894 }
 895
 896 /** Destroy the frame.
 897  *
 898  * \public \memberof mlt_frame_s
 899  * \param self a frame
 900  */
 901
 902 void mlt_frame_close( mlt_frame self )
 903 {
 904         if ( self != NULL && mlt_properties_dec_ref( MLT_FRAME_PROPERTIES( self ) ) <= 0 )
 905         {
 906                 mlt_deque_close( self->stack_image );
 907                 mlt_deque_close( self->stack_audio );
 908                 while( mlt_deque_peek_back( self->stack_service ) )
 909                         mlt_service_close( mlt_deque_pop_back( self->stack_service ) );
 910                 mlt_deque_close( self->stack_service );
 911                 mlt_properties_close( &self->parent );
 912                 free( self );
 913         }
 914 }
 915
 916 /***** convenience functions *****/
 917
 918 /** Determine the number of samples that belong in a frame at a time position.
 919  *
 920  * \public \memberof mlt_frame_s
 921  * \param fps the frame rate
 922  * \param frequency the sample rate
 923  * \param position the time position
 924  * \return the number of samples per channel
 925  */
 926
 927 int mlt_sample_calculator( float fps, int frequency, int64_t position )
 928 {
 929         /* Compute the cumulative number of samples until the start of this frame and the
 930         cumulative number of samples until the start of the next frame. Round each to the
 931         nearest integer and take the difference to determine the number of samples in
 932         this frame.
 933
 934         This approach should prevent rounding errors that can accumulate over a large number
 935         of frames causing A/V sync problems. */
 936         return mlt_sample_calculator_to_now( fps, frequency, position + 1 )
 937                  - mlt_sample_calculator_to_now( fps, frequency, position );
 938 }
 939
 940 /** Determine the number of samples that belong before a time position.
 941  *
 942  * \public \memberof mlt_frame_s
 943  * \param fps the frame rate
 944  * \param frequency the sample rate
 945  * \param position the time position
 946  * \return the number of samples per channel
 947  * \bug Will this break when mlt_position is converted to double?
 948  */
 949
 950 int64_t mlt_sample_calculator_to_now( float fps, int frequency, int64_t position )
 951 {
 952         int64_t samples = 0;
 953
 954         if ( fps )
 955         {
 956                 samples = (int64_t)( (double) position * (double) frequency / (double) fps +
 957                         ( position < 0 ? -0.5 : 0.5 ) );
 958         }
 959
 960         return samples;
 961 }
 962
 963 void mlt_frame_write_ppm( mlt_frame frame )
 964 {
 965         int width = 0;
 966         int height = 0;
 967         mlt_image_format format = mlt_image_rgb24;
 968         uint8_t *image;
 969
 970         if ( mlt_frame_get_image( frame, &image, &format, &width, &height, 0 ) == 0 )
 971         {
 972                 FILE *file;
 973                 char filename[16];
 974
 975                 sprintf( filename, "frame-%05d.ppm", (int)mlt_frame_get_position( frame ) );
 976                 file = fopen( filename, "wb" );
 977                 if ( !file )
 978                         return;
 979                 fprintf( file, "P6\n%d %d\n255\n", width, height);
 980                 fwrite( image, width * height * 3, 1, file );
 981                 fclose( file );
 982         }
 983 }
 984
 985 /** Get or create a properties object unique to this service instance.
 986  *
 987  * Use this function to hold a service's processing parameters for this
 988  * particular frame. Set the parameters in the service's process function.
 989  * Then, get the parameters in the function it pushes to the frame's audio
 990  * or image stack. This makes the service more parallel by reducing race
 991  * conditions and less sensitive to multiple instances (by not setting a
 992  * non-unique property on the frame). Creation and destruction of the
 993  * properties object is handled automatically.
 994  *
 995  * \public \memberof mlt_frame_s
 996  * \param self a frame
 997  * \param service a service
 998  * \return a properties object
 999  */
1000
1001 mlt_properties mlt_frame_unique_properties( mlt_frame self, mlt_service service )
1002 {
1003         mlt_properties frame_props = MLT_FRAME_PROPERTIES( self );
1004         mlt_properties service_props = MLT_SERVICE_PROPERTIES( service );
1005         char *unique = mlt_properties_get( service_props, "_unique_id" );
1006         mlt_properties instance_props = mlt_properties_get_data( frame_props, unique, NULL );
1007
1008         if ( !instance_props )
1009         {
1010                 instance_props = mlt_properties_new();
1011                 mlt_properties_set_data( frame_props, unique, instance_props, 0, (mlt_destructor) mlt_properties_close, NULL );
1012         }
1013
1014         return instance_props;
1015 }
1016
1017 /** Make a copy of a frame.
1018  *
1019  * This does not copy the get_image/get_audio processing stacks or any
1020  * data properties other than the audio and image.
1021  *
1022  * \public \memberof mlt_frame_s
1023  * \param self the frame to clone
1024  * \param is_deep a boolean to indicate whether to make a deep copy of the audio
1025  * and video data chunks or to make a shallow copy by pointing to the supplied frame
1026  * \return a almost-complete copy of the frame
1027  * \todo copy the processing deques
1028  */
1029
1030 mlt_frame mlt_frame_clone( mlt_frame self, int is_deep )
1031 {
1032         mlt_frame new_frame = mlt_frame_init( NULL );
1033         mlt_properties properties = MLT_FRAME_PROPERTIES( self );
1034         mlt_properties new_props = MLT_FRAME_PROPERTIES( new_frame );
1035         void *data, *copy;
1036         int size;
1037
1038         mlt_properties_inherit( new_props, properties );
1039
1040         // Carry over some special data properties for the multi consumer.
1041         mlt_properties_set_data( new_props, "_producer",
1042                 mlt_frame_get_original_producer( self ), 0, NULL, NULL );
1043         mlt_properties_set_data( new_props, "movit.convert",
1044                 mlt_properties_get_data( properties, "movit.convert", NULL), 0, NULL, NULL );
1045
1046         if ( is_deep )
1047         {
1048                 data = mlt_properties_get_data( properties, "audio", &size );
1049                 if ( data )
1050                 {
1051                         if ( !size )
1052                                 size = mlt_audio_format_size( mlt_properties_get_int( properties, "audio_format" ),
1053                                         mlt_properties_get_int( properties, "audio_samples" ),
1054                                         mlt_properties_get_int( properties, "audio_channels" ) );
1055                         copy = mlt_pool_alloc( size );
1056                         memcpy( copy, data, size );
1057                         mlt_properties_set_data( new_props, "audio", copy, size, mlt_pool_release, NULL );
1058                 }
1059                 data = mlt_properties_get_data( properties, "image", &size );
1060                 if ( data )
1061                 {
1062                         int width = mlt_properties_get_int( properties, "width" );
1063                         int height = mlt_properties_get_int( properties, "height" );
1064
1065                         if ( ! size )
1066                                 size = mlt_image_format_size( mlt_properties_get_int( properties, "format" ),
1067                                         width, height, NULL );
1068                         copy = mlt_pool_alloc( size );
1069                         memcpy( copy, data, size );
1070                         mlt_properties_set_data( new_props, "image", copy, size, mlt_pool_release, NULL );
1071
1072                         data = mlt_properties_get_data( properties, "alpha", &size );
1073                         if ( data )
1074                         {
1075                                 if ( ! size )
1076                                         size = width * height;
1077                                 copy = mlt_pool_alloc( size );
1078                                 memcpy( copy, data, size );
1079                                 mlt_properties_set_data( new_props, "alpha", copy, size, mlt_pool_release, NULL );
1080                         };
1081                 }
1082         }
1083         else
1084         {
1085                 // This frame takes a reference on the original frame since the data is a shallow copy.
1086                 mlt_properties_inc_ref( properties );
1087                 mlt_properties_set_data( new_props, "_cloned_frame", self, 0,
1088                         (mlt_destructor) mlt_frame_close, NULL );
1089
1090                 // Copy properties
1091                 data = mlt_properties_get_data( properties, "audio", &size );
1092                 mlt_properties_set_data( new_props, "audio", data, size, NULL, NULL );
1093                 data = mlt_properties_get_data( properties, "image", &size );
1094                 mlt_properties_set_data( new_props, "image", data, size, NULL, NULL );
1095                 data = mlt_properties_get_data( properties, "alpha", &size );
1096                 mlt_properties_set_data( new_props, "alpha", data, size, NULL, NULL );
1097         }
1098
1099         return new_frame;
1100 }