Tutorial: Custom sounds

The sounds you include in your apps play a critical role in creating an enhanced user experience. The user performs some action in your app, and the app responds by playing a sound. This sound can be the sound of a camera shutter in a camera app, the sound of a doorbell when the user clicks on a specific Button, or any other sounds you include to respond to other events in your apps. In short, sounds make your apps come alive.

This tutorial shows you how to play custom sounds in an app. We'll create the app shown in the image to the right using two controls. A DropDown that's used to choose a custom sound, and a play button that's used to play the sound chosen.

You will learn to:

  • Set up your app to play custom sounds
  • Play custom sounds in response to UI signals

The image to the right shows the two custom sound files that can be selected from the DropDown control.

Custom sound app UI

Custom sound app UI showing a dropdown to choose a custom sound, and a play button

Set up your project

Let's begin by creating a new Cascades project using the Standard empty project template.

For more information on creating a project, see Create your first Cascades app.

This tutorial assumes that you've created a Cascades project, and have it open in your Momentics IDE.

Add sound file assets

Let's add two sound files to your project's assets folder. You can use your own custom sound files, or you can download the two sound files from here: sounds.zip.

When you've downloaded the sounds.zip file, extract the sound files to your desktop (or another folder on your machine) and add them to your app by following these steps:

  1. In your project's assets folder, create a sounds folder.
  2. Right-click the sounds folder and click Import.
  3. In the Import box, select General > File System and click Next.
  4. Click Browse, locate the folder where your sound files are stored, select it and click OK.
  5. In the right pane, select the check boxes beside each of the sound files that you want to import.
  6. Click Finish to import the sound files into your sounds folder.

As you can see, we've added two sound files called Doorbell_001.wav and Doorbell_002.wav to our newly created sounds folder.

Project files showing the assets folder

After you've successfully imported your custom sound files, it's time to put some QML code into your project's main.qml file to create the app's UI.

Add UI controls

Let's create our app's UI by adding two UI controls that we can use to play custom sounds. We'll add a DropDown that's used to select a custom sound, and a Button whose onClicked signal handler is used to first set the player's sourceUrl property with the setSourceUrl() function, and play the sound selected in the DropDown by making a call to the play() function of the MediaPlayer class.

// ...

Page {
    Container {
        // ...

        Button {
            id: btnPlaySound
            text: "Play Sound"
            onClicked: {
               myPlayer.setSourceUrl(ddlSoundSelector.selectedValue);
               myPlayer.play()
            }
        }
    }
}

Note how the paths to our sound files are referenced. The MediaPlayer can play sound files from many locations including remote locations. For example, if sound files are stored on a remote server, then you can use the URL to those sound files to set the sourceUrl of the MediaPlayer, and it'll play the sound files from that location.

In this case, the sound files are in our assets folder, within the sounds folder. To use these sound resources, you can define their path in the value property of each Option object using the format "asset:///path/to/sound_file", as shown below in the code sample.

// ...

Page {
    Container {
        // ...

        DropDown {
            id: ddlSoundSelector
            title: "Sound: "

            Option {
                text: "Doorbell 1"
                value: "asset:///sounds/Doorbell_001.wav"
                selected: true
            }
            Option {
                text: "Doorbell 2"
                value: "asset:///sounds/Doorbell_002.wav"
            }
        }

        // ...
    }
}

Define a MediaPlayer object

You must put an import statement in your main.qml file to import the multimedia library. This import statement allows you to use the MediaPlayer to play your custom sounds. Here's a QML code sample showing the import statement.

import bb.multimedia 1.2

To play custom sounds, you must also define a MediaPlayer object and attach it to the root element (such as the Page) in your main.qml file. Here's a QML code sample showing the import statement and the MediaPlayer object definition.

import bb.cascades 1.2
import bb.multimedia 1.2

Page {
    Container {
        // ...

        attachedObjects: [
            MediaPlayer {
                id: myPlayer
            }
        ]
        
        // ...
    }
}

Here's a QML code sample that shows you how to play custom sounds that are saved locally on the device in .wav files. As you can see, the DropDown has the value property of each of its Option objects set to the locations of different custom .wav sound files. The btnPlaySound button uses its onClicked handler to call the MediaPlayer to set the URL of the custom sound file that's selected from the DropDown control, and play it.

import bb.cascades 1.2
import bb.multimedia 1.2

Page {
    Container {
        id: customSoundsContainer
        layout: StackLayout {
        }

        attachedObjects: [
            MediaPlayer {
                id: myPlayer
            }
        ]

        DropDown {
            id: ddlSoundSelector
            title: "Sound: "

            Option {
                text: "Doorbell 1"
                value: "asset:///sounds/Doorbell_001.wav"
                selected: true
            }
            Option {
                text: "Doorbell 2"
                value: "asset:///sounds/Doorbell_002.wav"
            }
        }
        
        Button {
            id: btnPlaySound
            text: "Play Sound"
            onClicked: {
              myPlayer.setSourceUrl(ddlSoundSelector.selectedValue);
              myPlayer.play()
            }
        }
    }
}

Last modified: 2013-12-20

comments powered by Disqus