Tutorial: Custom sounds

The sounds you include in your app 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 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 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

Before you begin

You should have the following things ready:

  • The BlackBerry 10 Native SDK
  • A device or simulator running BlackBerry 10

You can download the tools that you need and learn how to create, build, and run your first Cascades project.

Downloading the full source code

This tutorial uses a step-by-step approach to build our custom sounds app from scratch.The complete source code for the finished app is shown at the end of this tutorial and is available for download.

Download the full source code

Set up your project

Let's begin by creating a Cascades project using the template for a standard empty project. For more information about creating a project, see Tutorial: Create your first Cascades app.

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: custom_sounds_tutorial_assets.zip.

When you've downloaded the custom_sounds_tutorial_assets.zip file, extract the sound files to your desktop (or another folder on your computer) 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.
Project files showing the assets 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.

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.

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 Container) 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
            }
        ]
    }
}

Add UI controls

Let's create our app's UI by adding two UI controls that we can use to play custom sounds.

We add a DropDown that's used to select a custom sound, and add our two sounds to the set of options that the user can select.

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 your app plays the sound files from that location.

In this sample, 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 in the code sample below.

// ...

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"
            }
        }
    }
}

After the DropDown, we add a Button whose onClicked signal handler is used to set the player's sourceUrl property with the setSourceUrl() function, and play the sound selected in the DropDown by calling the play() function of the MediaPlayer class.

// ...

Page {
    Container {
        // ...

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

That's it. Build your project and try it out!

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: 2015-03-31



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus