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                 case mlt_image_rgb24_full:  return "rgb24_full";
 355                 case mlt_image_rgb24a_full: return "rgb24a_full";
 356                 case mlt_image_yuv422_709:  return "yuv422_709";
 357         }
 358         return "invalid";
 359 }
 360
 361 /** Get the image associated to the frame.
 362  *
 363  * You should express the desired format, width, and height as inputs. As long
 364  * as the loader producer was used to generate this or the imageconvert filter
 365  * was attached, then you will get the image back in the format you desire.
 366  * However, you do not always get the width and height you request depending
 367  * on properties and filters. You do not need to supply a pre-allocated
 368  * buffer, but you should always supply the desired image format.
 369  *
 370  * \public \memberof mlt_frame_s
 371  * \param this a frame
 372  * \param[out] buffer an image buffer
 373  * \param[in,out] format the image format
 374  * \param[in,out] width the horizontal size in pixels
 375  * \param[in,out] height the vertical size in pixels
 376  * \param writable whether or not you will need to be able to write to the memory returned in \p buffer
 377  * \return true if error
 378  * \todo Better describe the width and height as inputs.
 379  */
 380
 381 int mlt_frame_get_image( mlt_frame this, uint8_t **buffer, mlt_image_format *format, int *width, int *height, int writable )
 382 {
 383         mlt_properties properties = MLT_FRAME_PROPERTIES( this );
 384         mlt_get_image get_image = mlt_frame_pop_get_image( this );
 385         mlt_producer producer = mlt_properties_get_data( properties, "test_card_producer", NULL );
 386         mlt_image_format requested_format = *format;
 387         int error = 0;
 388
 389         if ( get_image )
 390         {
 391                 mlt_properties_set_int( properties, "image_count", mlt_properties_get_int( properties, "image_count" ) - 1 );
 392                 error = get_image( this, buffer, format, width, height, writable );
 393                 if ( !error && *buffer )
 394                 {
 395                         mlt_properties_set_int( properties, "width", *width );
 396                         mlt_properties_set_int( properties, "height", *height );
 397                         mlt_properties_set_int( properties, "format", *format );
 398                         if ( this->convert_image )
 399                                 this->convert_image( this, buffer, format, requested_format );
 400                 }
 401                 else
 402                 {
 403                         // Cause the image to be loaded from test card or fallback (white) below.
 404                         mlt_frame_get_image( this, buffer, format, width, height, writable );
 405                 }
 406         }
 407         else if ( mlt_properties_get_data( properties, "image", NULL ) )
 408         {
 409                 *format = mlt_properties_get_int( properties, "format" );
 410                 *buffer = mlt_properties_get_data( properties, "image", NULL );
 411                 *width = mlt_properties_get_int( properties, "width" );
 412                 *height = mlt_properties_get_int( properties, "height" );
 413                 if ( this->convert_image && *buffer )
 414                         this->convert_image( this, buffer, format, requested_format );
 415         }
 416         else if ( producer )
 417         {
 418                 mlt_frame test_frame = NULL;
 419                 mlt_service_get_frame( MLT_PRODUCER_SERVICE( producer ), &test_frame, 0 );
 420                 if ( test_frame )
 421                 {
 422                         mlt_properties test_properties = MLT_FRAME_PROPERTIES( test_frame );
 423                         mlt_properties_set_double( test_properties, "consumer_aspect_ratio", mlt_properties_get_double( properties, "consumer_aspect_ratio" ) );
 424                         mlt_properties_set( test_properties, "rescale.interp", mlt_properties_get( properties, "rescale.interp" ) );
 425                         mlt_frame_get_image( test_frame, buffer, format, width, height, writable );
 426                         mlt_properties_set_data( properties, "test_card_frame", test_frame, 0, ( mlt_destructor )mlt_frame_close, NULL );
 427                         mlt_properties_set_double( properties, "aspect_ratio", mlt_frame_get_aspect_ratio( test_frame ) );
 428 //                      mlt_properties_set_data( properties, "image", *buffer, *width * *height * 2, NULL, NULL );
 429 //                      mlt_properties_set_int( properties, "width", *width );
 430 //                      mlt_properties_set_int( properties, "height", *height );
 431 //                      mlt_properties_set_int( properties, "format", *format );
 432                 }
 433                 else
 434                 {
 435                         mlt_properties_set_data( properties, "test_card_producer", NULL, 0, NULL, NULL );
 436                         mlt_frame_get_image( this, buffer, format, width, height, writable );
 437                 }
 438         }
 439         else
 440         {
 441                 register uint8_t *p;
 442                 register uint8_t *q;
 443                 int size = 0;
 444
 445                 *width = *width == 0 ? 720 : *width;
 446                 *height = *height == 0 ? 576 : *height;
 447                 size = *width * *height;
 448
 449                 mlt_properties_set_int( properties, "format", *format );
 450                 mlt_properties_set_int( properties, "width", *width );
 451                 mlt_properties_set_int( properties, "height", *height );
 452                 mlt_properties_set_int( properties, "aspect_ratio", 0 );
 453
 454                 switch( *format )
 455                 {
 456                         case mlt_image_none:
 457                                 size = 0;
 458                                 *buffer = NULL;
 459                                 break;
 460                         case mlt_image_rgb24:
 461                         case mlt_image_rgb24_full:
 462                                 size *= 3;
 463                                 size += *width * 3;
 464                                 *buffer = mlt_pool_alloc( size );
 465                                 if ( *buffer )
 466                                         memset( *buffer, 255, size );
 467                                 break;
 468                         case mlt_image_rgb24a:
 469                         case mlt_image_rgb24a_full:
 470                         case mlt_image_opengl:
 471                                 size *= 4;
 472                                 size += *width * 4;
 473                                 *buffer = mlt_pool_alloc( size );
 474                                 if ( *buffer )
 475                                         memset( *buffer, 255, size );
 476                                 break;
 477                         case mlt_image_yuv422:
 478                                 size *= 2;
 479                                 size += *width * 2;
 480                                 *buffer = mlt_pool_alloc( size );
 481                                 p = *buffer;
 482                                 q = p + size;
 483                                 while ( p != NULL && p != q )
 484                                 {
 485                                         *p ++ = 235;
 486                                         *p ++ = 128;
 487                                 }
 488                                 break;
 489                         case mlt_image_yuv420p:
 490                                 size = size * 3 / 2;
 491                                 *buffer = mlt_pool_alloc( size );
 492                                 if ( *buffer )
 493                                         memset( *buffer, 255, size );
 494                                 break;
 495                 }
 496
 497                 mlt_properties_set_data( properties, "image", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 498                 mlt_properties_set_int( properties, "test_image", 1 );
 499         }
 500
 501         return error;
 502 }
 503
 504 /** Get the alpha channel associated to the frame.
 505  *
 506  * \public \memberof mlt_frame_s
 507  * \param this a frame
 508  * \return the alpha channel
 509  */
 510
 511 uint8_t *mlt_frame_get_alpha_mask( mlt_frame this )
 512 {
 513         uint8_t *alpha = NULL;
 514         if ( this != NULL )
 515         {
 516                 if ( this->get_alpha_mask != NULL )
 517                         alpha = this->get_alpha_mask( this );
 518                 if ( alpha == NULL )
 519                         alpha = mlt_properties_get_data( &this->parent, "alpha", NULL );
 520                 if ( alpha == NULL )
 521                 {
 522                         int size = mlt_properties_get_int( &this->parent, "width" ) * mlt_properties_get_int( &this->parent, "height" );
 523                         alpha = mlt_pool_alloc( size );
 524                         memset( alpha, 255, size );
 525                         mlt_properties_set_data( &this->parent, "alpha", alpha, size, mlt_pool_release, NULL );
 526                 }
 527         }
 528         return alpha;
 529 }
 530
 531 /** Get the short name for an audio format.
 532  *
 533  * You do not need to deallocate the returned string.
 534  * \public \memberof mlt_frame_s
 535  * \param this a frame
 536  * \param format an image format enum
 537  * \return a string for the name of the image format
 538  */
 539
 540 const char * mlt_audio_format_name( mlt_audio_format format )
 541 {
 542         switch ( format )
 543         {
 544                 case mlt_audio_none:   return "none";
 545                 case mlt_audio_s16:    return "s16";
 546                 case mlt_audio_s32:    return "s32";
 547                 case mlt_audio_float:  return "float";
 548         }
 549         return "invalid";
 550 }
 551
 552 /** Get the audio associated to the frame.
 553  *
 554  * You should express the desired format, frequency, channels, and samples as inputs. As long
 555  * as the loader producer was used to generate this or the audioconvert filter
 556  * was attached, then you will get the audio back in the format you desire.
 557  * However, you do not always get the channels and samples you request depending
 558  * on properties and filters. You do not need to supply a pre-allocated
 559  * buffer, but you should always supply the desired audio format.
 560  * The audio is always in interleaved format.
 561  * You should use the \p mlt_sample_calculator to determine the number of samples you want.
 562  *
 563  * \public \memberof mlt_frame_s
 564  * \param this a frame
 565  * \param[out] buffer an audio buffer
 566  * \param[in,out] format the audio format
 567  * \param[in,out] frequency the sample rate
 568  * \param[in,out] channels
 569  * \param[in,out] samples the number of samples per frame
 570  * \return true if error
 571  */
 572
 573 int mlt_frame_get_audio( mlt_frame this, void **buffer, mlt_audio_format *format, int *frequency, int *channels, int *samples )
 574 {
 575         mlt_get_audio get_audio = mlt_frame_pop_audio( this );
 576         mlt_properties properties = MLT_FRAME_PROPERTIES( this );
 577         int hide = mlt_properties_get_int( properties, "test_audio" );
 578         mlt_audio_format requested_format = *format;
 579
 580         if ( hide == 0 && get_audio != NULL )
 581         {
 582                 get_audio( this, buffer, format, frequency, channels, samples );
 583                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 584                 mlt_properties_set_int( properties, "audio_channels", *channels );
 585                 mlt_properties_set_int( properties, "audio_samples", *samples );
 586                 mlt_properties_set_int( properties, "audio_format", *format );
 587                 if ( this->convert_audio )
 588                         this->convert_audio( this, buffer, format, requested_format );
 589         }
 590         else if ( mlt_properties_get_data( properties, "audio", NULL ) )
 591         {
 592                 *buffer = mlt_properties_get_data( properties, "audio", NULL );
 593                 *format = mlt_properties_get_int( properties, "audio_format" );
 594                 *frequency = mlt_properties_get_int( properties, "audio_frequency" );
 595                 *channels = mlt_properties_get_int( properties, "audio_channels" );
 596                 *samples = mlt_properties_get_int( properties, "audio_samples" );
 597                 if ( this->convert_audio )
 598                         this->convert_audio( this, buffer, format, requested_format );
 599         }
 600         else
 601         {
 602                 int size = 0;
 603                 *samples = *samples <= 0 ? 1920 : *samples;
 604                 *channels = *channels <= 0 ? 2 : *channels;
 605                 *frequency = *frequency <= 0 ? 48000 : *frequency;
 606                 mlt_properties_set_int( properties, "audio_frequency", *frequency );
 607                 mlt_properties_set_int( properties, "audio_channels", *channels );
 608                 mlt_properties_set_int( properties, "audio_samples", *samples );
 609                 mlt_properties_set_int( properties, "audio_format", *format );
 610
 611                 switch( *format )
 612                 {
 613                         case mlt_image_none:
 614                                 size = 0;
 615                                 *buffer = NULL;
 616                                 break;
 617                         case mlt_audio_s16:
 618                                 size = *samples * *channels * sizeof( int16_t );
 619                                 break;
 620                         case mlt_audio_s32:
 621                                 size = *samples * *channels * sizeof( int32_t );
 622                                 break;
 623                         case mlt_audio_float:
 624                                 size = *samples * *channels * sizeof( float );
 625                                 break;
 626                 }
 627                 if ( size )
 628                         *buffer = mlt_pool_alloc( size );
 629                 if ( *buffer )
 630                         memset( *buffer, 0, size );
 631                 mlt_properties_set_data( properties, "audio", *buffer, size, ( mlt_destructor )mlt_pool_release, NULL );
 632                 mlt_properties_set_int( properties, "test_audio", 1 );
 633         }
 634
 635         // TODO: This does not belong here
 636         if ( *format == mlt_audio_s16 && mlt_properties_get( properties, "meta.volume" ) )
 637         {
 638                 double value = mlt_properties_get_double( properties, "meta.volume" );
 639
 640                 if ( value == 0.0 )
 641                 {
 642                         memset( *buffer, 0, *samples * *channels * 2 );
 643                 }
 644                 else if ( value != 1.0 )
 645                 {
 646                         int total = *samples * *channels;
 647                         int16_t *p = *buffer;
 648                         while ( total -- )
 649                         {
 650                                 *p = *p * value;
 651                                 p ++;
 652                         }
 653                 }
 654
 655                 mlt_properties_set( properties, "meta.volume", NULL );
 656         }
 657
 658         return 0;
 659 }
 660
 661 /** Set the audio on a frame.
 662  *
 663  * \public \memberof mlt_frame_s
 664  * \param this a frame
 665  * \param buffer an buffer containing audio samples
 666  * \param format the format of the audio in the \p buffer
 667  * \param size the total size of the buffer (optional)
 668  * \param destructor a function that releases or deallocates the \p buffer
 669  * \return true if error
 670  */
 671
 672 int mlt_frame_set_audio( mlt_frame this, void *buffer, mlt_audio_format format, int size, mlt_destructor destructor )
 673 {
 674         mlt_properties_set_int( MLT_FRAME_PROPERTIES( this ), "audio_format", format );
 675         return mlt_properties_set_data( MLT_FRAME_PROPERTIES( this ), "audio", buffer, size, destructor, NULL );
 676 }
 677
 678 /** Get audio on a frame as a waveform image.
 679  *
 680  * This generates an 8-bit grayscale image representation of the audio in a
 681  * frame. Currently, this only really works for 2 channels.
 682  * This allocates the bitmap using mlt_pool so you should release the return
 683  * value with \p mlt_pool_release.
 684  *
 685  * \public \memberof mlt_frame_s
 686  * \param this a frame
 687  * \param w the width of the image
 688  * \param h the height of the image to create
 689  * \return a pointer to a new bitmap
 690  */
 691
 692 unsigned char *mlt_frame_get_waveform( mlt_frame this, int w, int h )
 693 {
 694         int16_t *pcm = NULL;
 695         mlt_properties properties = MLT_FRAME_PROPERTIES( this );
 696         mlt_audio_format format = mlt_audio_s16;
 697         int frequency = 16000;
 698         int channels = 2;
 699         mlt_producer producer = mlt_frame_get_original_producer( this );
 700         double fps = mlt_producer_get_fps( mlt_producer_cut_parent( producer ) );
 701         int samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( this ) );
 702
 703         // Increase audio resolution proportional to requested image size
 704         while ( samples < w )
 705         {
 706                 frequency += 16000;
 707                 samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( this ) );
 708         }
 709
 710         // Get the pcm data
 711         mlt_frame_get_audio( this, (void**)&pcm, &format, &frequency, &channels, &samples );
 712
 713         // Make an 8-bit buffer large enough to hold rendering
 714         int size = w * h;
 715         unsigned char *bitmap = ( unsigned char* )mlt_pool_alloc( size );
 716         if ( bitmap != NULL )
 717                 memset( bitmap, 0, size );
 718         mlt_properties_set_data( properties, "waveform", bitmap, size, ( mlt_destructor )mlt_pool_release, NULL );
 719
 720         // Render vertical lines
 721         int16_t *ubound = pcm + samples * channels;
 722         int skip = samples / w;
 723         skip = !skip ? 1 : skip;
 724         unsigned char gray = 0xFF / skip;
 725         int i, j, k;
 726
 727         // Iterate sample stream and along x coordinate
 728         for ( i = 0; pcm < ubound; i++ )
 729         {
 730                 // pcm data has channels interleaved
 731                 for ( j = 0; j < channels; j++, pcm++ )
 732                 {
 733                         // Determine sample's magnitude from 2s complement;
 734                         int pcm_magnitude = *pcm < 0 ? ~(*pcm) + 1 : *pcm;
 735                         // The height of a line is the ratio of the magnitude multiplied by
 736                         // the vertical resolution of a single channel
 737                                 int height = h * pcm_magnitude / channels / 2 / 32768;
 738                         // Determine the starting y coordinate - left top, right bottom
 739                         int displacement = h * (j * 2 + 1) / channels / 2 - ( *pcm < 0 ? 0 : height );
 740                         // Position buffer pointer using y coordinate, stride, and x coordinate
 741                         unsigned char *p = bitmap + i / skip + displacement * w;
 742
 743                         // Draw vertical line
 744                         for ( k = 0; k < height + 1; k++ )
 745                                 if ( *pcm < 0 )
 746                                         p[ w * k ] = ( k == 0 ) ? 0xFF : p[ w * k ] + gray;
 747                                 else
 748                                         p[ w * k ] = ( k == height ) ? 0xFF : p[ w * k ] + gray;
 749                 }
 750         }
 751
 752         return bitmap;
 753 }
 754
 755 /** Get the end service that produced this frame.
 756  *
 757  * This fetches the first producer of the frame and not any producers that
 758  * encapsulate it.
 759  *
 760  * \public \memberof mlt_frame_s
 761  * \param this a frame
 762  * \return a producer
 763  */
 764
 765 mlt_producer mlt_frame_get_original_producer( mlt_frame this )
 766 {
 767         if ( this != NULL )
 768                 return mlt_properties_get_data( MLT_FRAME_PROPERTIES( this ), "_producer", NULL );
 769         return NULL;
 770 }
 771
 772 /** Destroy the frame.
 773  *
 774  * \public \memberof mlt_frame_s
 775  * \param this a frame
 776  */
 777
 778 void mlt_frame_close( mlt_frame this )
 779 {
 780         if ( this != NULL && mlt_properties_dec_ref( MLT_FRAME_PROPERTIES( this ) ) <= 0 )
 781         {
 782                 mlt_deque_close( this->stack_image );
 783                 mlt_deque_close( this->stack_audio );
 784                 while( mlt_deque_peek_back( this->stack_service ) )
 785                         mlt_service_close( mlt_deque_pop_back( this->stack_service ) );
 786                 mlt_deque_close( this->stack_service );
 787                 mlt_properties_close( &this->parent );
 788                 free( this );
 789         }
 790 }
 791
 792 /***** convenience functions *****/
 793
 794 /** Determine the number of samples that belong in a frame at a time position.
 795  *
 796  * \public \memberof mlt_frame_s
 797  * \param fps the frame rate
 798  * \param frequency the sample rate
 799  * \param position the time position
 800  * \return the number of samples per channel
 801  */
 802
 803 int mlt_sample_calculator( float fps, int frequency, int64_t position )
 804 {
 805         /* Compute the cumulative number of samples until the start of this frame and the
 806         cumulative number of samples until the start of the next frame. Round each to the
 807         nearest integer and take the difference to determine the number of samples in
 808         this frame.
 809
 810         This approach should prevent rounding errors that can accumulate over a large number
 811         of frames causing A/V sync problems. */
 812         return mlt_sample_calculator_to_now( fps, frequency, position + 1 )
 813                  - mlt_sample_calculator_to_now( fps, frequency, position );
 814 }
 815
 816 /** Determine the number of samples that belong before a time position.
 817  *
 818  * \public \memberof mlt_frame_s
 819  * \param fps the frame rate
 820  * \param frequency the sample rate
 821  * \param position the time position
 822  * \return the number of samples per channel
 823  * \bug Will this break when mlt_position is converted to double?
 824  */
 825
 826 int64_t mlt_sample_calculator_to_now( float fps, int frequency, int64_t position )
 827 {
 828         int64_t samples = 0;
 829
 830         if ( fps )
 831         {
 832                 samples = (int64_t)( (double) position * (double) frequency / (double) fps +
 833                         ( position < 0 ? -0.5 : 0.5 ) );
 834         }
 835
 836         return samples;
 837 }