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

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