Media Tool: Managing Media Handles

This tutorial demonstrates how you can create, set, and get media handles.

Warm-up

Become familiar with the Media Tool API basics by learning about:

• Managing the Media Format Handle

  Create, set, and get the media_format_h handle.

• Managing the Media Packet Handle

  Create, set, and get the media_packet_h handle.

Managing the Media Format Handle

To manage the media format handle:

1. To use the media format handle of the Media Tool API (in mobile and wearable applications), include the <media_format.h> header file in your application:

   #include <media_format.h>
   

2. Define a media_format_h variable for the media format handle, and pass the variable to the media_format_create() function, which returns the handle.

   To set the video information when creating the handle:

   media_format_h format;
   if (media_format_create(&format) == MEDIA_FORMAT_ERROR_NONE)
   {
      media_format_set_video_mime(format, MEDIA_FORMAT_H264_HP);
      media_format_set_video_width(format, 640);
      media_format_set_video_height(format, 480);
      media_format_set_video_avg_bps(format, 10000000);
      media_format_set_video_max_bps(format, 15000000);
   }
   else
   {
      printf("media_format_create() failed!");
   }
   

   To set the audio information, replace the media_format_set_video_XXX() functions with the relevant media_format_set_audio_XXX() functions in the above example code.

3. To retrieve the video format information, use the media_format_get_video_info() function:

   media_format_h fmt;
   
   media_format_mimetype_e mime;
   int w;
   int h;
   int avg_bps;
   int max_bps;
   
   if (media_format_get_video_info(fmt, &mimetype, &w, &h, &avg_bps, &max_bps) == MEDIA_PACKET_ERROR_NONE)
   {
      printf("media_format_get_video_info success! width = %d, height = %d", w, h);
   }
   else
   {
      print("media_format_get_video is failed...");
   }
   

   To retrieve the audio format information, use the media_format_get_audio_info() function.

Managing the Media Packet Handle

To manage the media packet handle:

1. To use the media packet handle of the Media Tool API (in mobile and wearable applications), include the <media_packet.h> header file in your application:

   #include <media_packet.h>
   

2. Define a media_packet_h variable for the media packet handle, and pass the variable to the appropriate media_packet_create_XXX() function (as the last parameter) with an existing media format handle (as the first parameter).

   After creating the media packet handle, call the media_format_unref() function for the media format handle. Because all functions that create a media packet handle increase the reference count of the media format handle, you must decrease the count.

   To reuse the media packet handle even after the media_packet_destroy() function is called, define a callback (the third last parameter of the media_packet_create_XXX() function), which is called when the handle is destroyed. Set the callback to return MEDIA_PACKET_REUSE.

   The following example codes show the different ways you create the media packet handle:

   • To create the handle and allocate a buffer into the heap or TBM surface, use the media_packet_create_alloc() function:

     {
        media_format_h fmt;
        media_packet_h packet;
     
        media_format_create(&fmt);
        media_format_set_video_mime(format, MEDIA_FORMAT_H264_HP);
        media_format_set_video_width(format, 640);
        media_format_set_video_height(format, 480);
        media_format_set_video_avg_bps(format, 10000000);
        media_format_set_video_max_bps(format, 15000000);
     
        // MEDIA_FORMAT_H264_HP data type is MEDIA_FORMAT_ENCODED and the buffer is allocated into the heap
        // If the data type is MEDIA_FORMAT_RAW, the buffer is allocated into the TBM surface
     
        media_packet_create_alloc(fmt, _finalize_callback, fcb_data, &packet);
        media_format_unref(fmt);
     
        media_packet_destroy(packet);
     }
     
     int
     _finalize_callback(media_packet_h packet, int err, void* userdata)
     {
        return MEDIA_PACKET_REUSE;
     }
     

   • To create only the handle, use the media_packet_create() function:

     {
        media_format_h fmt;
        media_packet_h packet;
     
        media_format_create(&fmt);
        media_format_set_video_mime(format, MEDIA_FORMAT_H264_HP);
        media_format_set_video_width(format, 640);
        media_format_set_video_height(format, 480);
        media_format_set_video_avg_bps(format, 10000000);
        media_format_set_video_max_bps(format, 15000000);
     
        // Only create the handle, do not allocate a buffer
        media_packet_create(fmt, _finalize_callback, fcb_data, &packet);
        media_format_unref(fmt);
     }
     
     int
     _finalize_callback(media_packet_h packet, int err, void* userdata)
     {
        return MEDIA_PACKET_FINALIZE;
     }
     

   • To create the handle and store the TBM surface data, use the media_packet_create_from_tbm_surface() function:

     {
        media_format_h fmt;
        media_packet_h packet;
     
        media_format_create(&fmt);
        media_format_set_video_mime(format, MEDIA_FORMAT_RGBA);
        media_format_set_video_width(format, 128);
        media_format_set_video_height(format, 128);
        media_format_set_video_avg_bps(format, 10000000);
        media_format_set_video_avg_bps(format, 15000000);
     
        media_packet_create_from_tbm_surface(fmt, surface, _finalize_callback, fcb_data, &packet);
        media_format_unref(fmt);
     }
     
     int
     _finalize_callback(media_packet_h packet, int err, void* userdata)
     {
        return MEDIA_PACKET_FINALIZE;
     }
     

   • To create the handle with an already allocated external buffer, use the media_packet_create_from_external_memory() function:

     {
        media_format_h fmt;
        media_packet_h packet;
     
        media_format_create(&fmt);
        media_format_set_video_mime(format, MEDIA_FORMAT_H264_HP);
        media_format_set_video_width(format, 640);
        media_format_set_video_height(format, 480);
        media_format_set_video_avg_bps(format, 10000000);
        media_format_set_video_avg_bps(format, 15000000);
     
        media_packet_create_from_external_memory(fmt, mem_ptr, size, _finalize_callback, fcb_data, &packet);
        media_format_unref(fmt);
     }
     
     int
     _finalize_callback(media_packet_h packet, int err, void* userdata)
     {
        // Do something
     
        return MEDIA_PACKET_FINALIZE;
     }
     

3. Set and get the metadata with the media packet handle:

   int ret = MEDIA_PACKET_ERROR_NONE;
   
   // format1 already exists
   
   media_packet_create_alloc(format1, NULL, NULL, &packet);
   
   ret = media_packet_set_duration(packet, duration);
   
   // After media_packet_get_format(), use media_format_unref()
   media_format_h tmp;
   media_packet_get_format(packet, &tmp);
   media_format_unref(tmp);
   
   // Set previously created format2 to packet
   // After media_packet_set_format(), use media_format_unref()
   media_packet_set_format(packet, format2);
   
   // Packet format is format2
   // If format2 ref_count is 1, format2 is free
   // If format2 ref_count is bigger than 1, it is not free
   media_packet_destroy(packet);