Metadata Editor: Editing Metadata from an Input Audio File

This tutorial demonstrates how you can edit metadata and artwork in audio files.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Metadata Editor API basics by learning about:

• Initializing the Metadata Editor

  Initialize the metadata editor for use.

• Editing Metadata and Artwork

  Create a metadata editor handle, bind the handle with an audio file, edit the metadata and artwork, and apply the edits to the file.

Initializing the Metadata Editor

To initialize the metadata editor for use:

1. To use the functions and data types of the Metadata Editor API, include the <metadata_editor.h> header file in your application:

   #include <metadata_editor.h>
   

2. To work with the Metadata Editor API, define a handle variable for the metadata editor:

   static metadata_editor_h g_metadata_h = NULL;
   

   This tutorial uses a global variable for the handle.

3. Make sure you have access to the file whose metadata and artwork you want to edit.

   This tutorial uses an MP3 audio file, which is accessed through its file path. The following example code uses an internal storage, so you must include the storage.h header file for the code to work.

   int internal_storage_id;
   char *internal_music_storage_path;
   char *music_file_name = "test_music.mp3";
   char *music_test_path;
   
   static bool
   storage_cb(int storage_id, storage_type_e type, storage_state_e state,
              const char *path, void *user_data)
   {
      if (type == STORAGE_TYPE_INTERNAL)
      {
         internal_storage_id = storage_id;
   
         return false;
      }
   
      return true;
   }
   
   void
   _get_internal_storage_path()
   {
      int error;
      char *path = NULL;
   
      error = storage_foreach_device_supported(storage_cb, NULL);
      error = storage_get_directory(internal_storage_id, STORAGE_DIRECTORY_MUSIC, &path);
      if (error != STORAGE_ERROR_NONE)
      {
         internal_music_storage_path = strdup(path);
         free(path);
      }
   }
   
   void
   _make_test_path()
   {
      int path_len = 0;
   
      path_len = strlen(internal_music_storage_path) + strlen(music_file_name) + 1;
      music_test_path = malloc(path_len);
      memset(music_test_path, 0x0, path_len);
   
      strncat(music_test_path, internal_music_storage_path, strlen(internal_music_storage_path));
      strncat(music_test_path, music_file_name, strlen(music_file_name));
   }
   

Editing Metadata and Artwork

To edit the metadata and artwork in the file:

1. Create the metadata editor handle using the metadata_editor_create() function:

   ret = metadata_editor_create(&g_metadata_h);
   

2. Set the path to the file you want to edit using the metadata_editor_set_path() function:

   ret = metadata_editor_set_path(g_metadata_h, music_test_path);
   

   The function binds the metadata editor handle (first parameter) with the file specified in the music_test_path variable (second parameter).

3. Edit the metadata in the file using the metadata_editor_set_metadata() function. Edit each piece of metadata (each metadata attribute) individually.

   As parameters, define the metadata editor handle, the attribute you want to edit, and the new value you want to set to the attribute. The possible attributes are defined in the metadata_editor_attr_e enumeration.

   The following example code edits the title of the audio content. You can edit other attributes by defining a different attribute enumerator (and a corresponding new value).

   char *value = "My Song";
   
   ret = metadata_editor_set_metadata(g_metadata_h, METADATA_EDITOR_ATTR_TITLE, value);
   

   After calling the function, check whether the return value is METADATA_EDITOR_ERROR_NONE. If it is, you can check the updated metadata using the metadata_editor_get_metadata() function. Otherwise, the function failed because of an error, which you need to handle.

   Note
   The updated metadata is applied to the file only after you call the metadata_editor_update_metadata() function, which is discussed below.

4. Add artwork to the file using the metadata_editor_append_picture() function.

   As parameters, define the metadata editor handle and the path of the image file that contains the artwork. The image file must be in the JPEG or PNG format. The image is added to the last image file position. You can add multiple image files to the same audio file.

   char *artwork = "append_image.jpg";
   
   ret = metadata_editor_append_picture(g_metadata_h, artwork);
   

   To remove artwork from the file, use the metadata_editor_remove_picture() function. As parameters, define the metadata editor handle and the index number of the image file you want to remove.

   To retrieve the number of images in the file, use the metadata_editor_get_metadata() function. To retrieve a specific image, use the metadata_editor_get_picture() function.

   int index = 0;
   
   ret = metadata_editor_remove_picture(g_metadata_h, index);
   

   Note
   The artwork is added to the file or removed from the file only after you call the metadata_editor_update_metadata() function, which is discussed below.

5. Apply the metadata and artwork edits to the file using the metadata_editor_update_metadata() function:

   ret = metadata_editor_update_metadata(g_metadata_h);
   

6. When no longer needed, destroy the metadata editor handle using the metadata_editor_destroy() function:

   metadata_editor_destroy(g_metadata_h);