Multimedia Manager

Multimedia Manager is a useful tool for organizing your audio and video multimedia files for a CommCare application. It allows you to upload, preview, and replace your audio and image files, verify that no files are missing, and enables one-click download of all your media files, with the correct file names.  When preparing your media files, be sure to follow the guidelines on the CommCare help site for file types and sizes.

You can add multimedia in the Form Builder, or you can add them in the Multimedia Manager.

Step by Step Guide

Add a multimedia reference 

1. Inside the form builder, chose the question or label where you want an image to be displayed, or from which you want an audio file to be playable.

2. There is a drop down menu in the top right corner of the question editing page.
   
   

   Open

   

    

   Selecting this button will open a drop down with 3 options - logic, media, and advanced. Select  Media, which presents the option to add image, audio, or video files:

Open

1. If you click on any of these buttons, you will see a file-path automatically generated. Here you can see what the Media section looks like with an image file-path added:

1. At this point you have the option of uploading an image direction into the form builder. Alternatively, you can just leave this reference and add the media through the Multimedia Manager. Note that if you add a reference but do not add a media file, your application will show the file-path instead of any image, so it is important to upload files for each reference you create. Don't worry, this is why the Multimedia Manager is there.

1. You can remove the reference by clicking on the red X.

1. You can also manually change the file-path by clicking on the Advanced: Show Path button.

1. Save the Form when you've finished your changes.

Note: You can also add multimedia (image, audio) in the module menu and the form menu using the same instructions found above for adding multimedia to a form. 

Each language of display text gets its own set of file-paths in case you want separate files, so this can be useful when you want to use different images for each language.  However, by default the automatically generated file-paths are the same for all languages; you'll have to manually adjust them if you want support for more than one language.  The file path automatically uses the Question ID, so here is what it looks like for an image for the question labeled hemoglobin_low_counsel: 

Images are automatically given the file type "png" and audio files "mp3" as well as a randomized part of the filename so the path does not collide with other media in the application. 

Upload Files

Option 1: Form Builder

1. You can add files directly in the form builder, if you choose to. If you do that, you will be able to see the files you have uploaded when viewing the Multimedia Manager. To upload a file, simply click on "Upload Image/Video/Audio" button in the Media Section of Question Properties.
   
   The filename of any file uploaded in the form builder will be randomized so it does not collide with other media in the application. If you want to assign a custom path, for example: when adding media for different languages, you must first assign the path in the form builder (but do not upload the file), and then use the Multimedia Manager (see below) to upload images for custom paths assigned in the form builder.

Option 2: Multimedia Manager - Manual Upload

Before you use the multimedia manager, make sure that you have followed Step 1 for all files that you want to upload. That means that for any question for which you want a media file, you should have added the reference in the form builder.

You can find the Multimedia Manager for your application within the Settings section. The settings icon is to the right of the Project name and the Multimedia section is the second tab. After clicking on "Multimedia" you will see the following:

You will use "Download ZIP" later to grab all of your files at once.  Below that there might be a note about how many references are missing files. Click on the blue "Multimedia Reference Checker" button to upload files for all the references.

A new window will open that will look like this:

Again, you can see if you have missing files, and have the option to download a ZIP of all the multimedia files. 

Let's try uploading an image file.

1. If you have not yet uploaded any files, after clicking on "Show Only Missing References" you will see a list of images that still need to be added:

2. The manager alerts you that each file is missing, and you will need to select the red button "Upload Image."  There is one row for each missing file.  After clicking on "Upload Image" you will see something like this:

3. Click on "Select File" to find the appropriate file on your computer.  

4. After you select a file, you will have the option to "Select another file" if it was not the correct file or to "Begin Upload."  

5. After you have uploaded the media file, your list will no longer have orange "missing" tags, but green "found" tags.  It should look more like this:

6. As you can see, your options from the Multimedia Manager have now changed.  You can preview the file by selecting "View Larger," to open the file in a new window (you'll have to open a new window to hear an uploaded audio file!).  If you want to change the image, click on "Replace Image" and follow the same instructions as before.  

Option 3: Multimedia Manager - Bulk Media Upload

In order to bulk upload your multimedia, you will need to do the following:

1. Label your multimedia files with the relevant question ID eg. if question ID=woman_name, then label the audio/image file as woman_name

   1. Once all your multimedia files are correctly labeled (with the relevant question ID), you now have the option to bulk upload your files (images/audio/video)

2. Place all your images/audio files into a directory structure that mirrors the file path

   1. You can see the file path in the Media section of the form builder by clicking on Advanced Show path  (see below)

      1. In the example below, the file path for the audio file is file/commcare/audio/data/show_edd

      2. In the below example, the file path for the image files is file/commcare/image/data/show_edd

3a. The directory structure/folder structure for those files will normally look like the following (please read 3b for questions in question groups)

commcare\image\data\show_edd

Such that the file called show_edd is in a folder called data.The data folder is in a folder called image and the image folder is in a folder called commcare (top level)

3b. NOTE when questions are part of a Question Group: If the question of interest is in a question group, then you will need to add an extra folder when bulk uploading eg. if question date_birth is in the question group age, then the file path on CommCareHQ will look like commcare/image/data/age/date_birth

Therefore, in your data folder, you can have both multimedia files (questions not in a group) as well as folders that contain multimedia files for grouped questions.

NB:  You can add all the relevant audio or image files into the appropriate data folder and now you can bulk upload them

4. You will need to make a Zip version of the commcare folder before proceeding to bulk upload on HQ.

5. Click on Multimedia tab in the setting section of CommCare HQ (see below)

6.  You can now click on multimedia reference checker.

7. The multimedia reference checker page will open and you can now click on Bulk Upload Multimedia (see below)

8. On this page, click on Choose File and then Upload multimedia files (see below)

• You will get confirmation of which files in your upload succeeded, and any that failed.

• This page also allows you to download your current multimedia as a ZIP, which will be in a directory structure matching your application. If you have already uploaded some multimedia, it can be less laborious to download this file, replace or add multimedia, and re-upload it, rather than building the ZIP file yourself from scratch.

Bulk uploading multimedia for an app with multiple languages:

If your app has multiple languages, it is still possible to bulk upload your multimedia files (audio/video). For the following, you should already have added the various languages to your app

Steps to take:

1. Go to the media section for a relevant question in your form

2. Click on the relevant section audio/video and you will see something like the below

(You will notice that the file path for the audio file is the same for French and English)

3. You will need to modify the file paths  for the audio files in the form

In the below example, we have added -en at the end of the English audio file and -fr at the end of the French audio file

• After doing this, you should see something that looks like the following on HQ

4. You will also have to name the corresponding audio/video files in the same way e.g nom_femme-en and nom_femme-fr

You should then be able to follow the steps above for bulk upload!

STEP 3: Download Your Media Files!

Once you have uploaded all of your media files you can easily download all of them in one click, with all the correct file names.  You can choose to download the Media ZIP from several locations on CommCareHQ:

1. On the main application page under "Multimedia"

2. In the Multimedia Manager main page (see above)

3. In the release manager of your application after clicking "deploy"
   The file will be downloaded as a ZIP and you will have to unzip the file in order to use it.  By storing and transmitting it as a ZIP is a good idea so that you don't lose any of those media files!

Important Notes:

• Other media types, such as video, are not currently supported by the Multimedia Manager.  These will have to be uploaded by adding a link to the file in the form, and then manually putting the correctly named file in the right place.

• If you change the name of a question ID, the file-path will not automatically update.  You can keep using the old file-path and any media you had previously uploaded.  If you want to use the new question id in the file-path, you will need to delete the reference and add it again, then go back to the multimedia manager to upload the media file again.

• The multimedia manager is not directly related to the release manager, it is related to the application in its current state.  This means that if you make a lot of changes to an application and download an old build, the multimedia manger will still reflect the current state of the application (most recent build).