19Controlling Your App’s Volume and Playback

A good user experience is a predictable one. If your app plays media it’s important that your users can control the volume of your app using the hardware or software volume controls of their device, bluetooth headset, or headphones.

用户可以使用硬件来控制程序的音量。

Similarly, where appropriate and available, the play, stop, pause, skip, and previous media playback keys should perform their respective actions on the audio stream used by your app.

Identify Which Audio Stream to Use

---

The first step to creating a predictable audio experience is understanding which audio stream your app will use.

Android maintains a separate audio stream for playing music, alarms, notifications, the incoming call ringer, system sounds, in-call volume, and DTMF tones. This is done primarily to allow users to control the volume of each stream independently.

Most of these streams are restricted to system events, so unless your app is a replacement alarm clock, you’ll almost certainly be playing your audio using the STREAM_MUSIC stream.

Android的音频流是相互独立的。使用the STREAM_MUSIC stream。

Use Hardware Volume Keys to Control Your App’s Audio Volume

---

By default, pressing the volume controls modify the volume of the active audio stream. If your app isn't currently playing anything, hitting the volume keys adjusts the ringer volume.

If you've got a game or music app, then chances are good that when the user hits the volume keys they want to control the volume of the game or music, even if they’re currently between songs or there’s no music in the current game location.

You may be tempted to try and listen for volume key presses and modify the volume of your audio stream that way. Resist the urge. Android provides the handy setVolumeControlStream() method to direct volume key presses to the audio stream you specify.

Having identified the audio stream your application will be using, you should set it as the volume stream target. You should make this call early in your app’s lifecycle—because you only need to call it once during the activity lifecycle, you should typically call it within the onCreate()method (of the Activity or Fragment that controls your media). This ensures that whenever your app is visible, the volume controls function as the user expects.

在Activity的onCreate()method方法中调用这个方法。

setVolumeControlStream(AudioManager.STREAM_MUSIC);

From this point onwards, pressing the volume keys on the device affect the audio stream you specify (in this case “music”) whenever the target activity or fragment is visible.

Use Hardware Playback Control Keys to Control Your App’s Audio Playback

---

Media playback buttons such as play, pause, stop, skip, and previous are available on some handsets and many connected or wireless headsets. Whenever a user presses one of these hardware keys, the system broadcasts an intent with the ACTION_MEDIA_BUTTON action.

在无线耳机或者其他的设备中，播放，暂停，停止，上一首，下一首，不管什么时候用户按下这些按钮，系统会发出带ACTION_MEDIA_BUTTON 动作的广播。

To respond to media button clicks, you need to register a BroadcastReceiver in your manifest that listens for this action broadcast as shown below.

在清单文件中注册一个广播接收者，指定Intent-filter的动作为：

android.intent.action.MEDIA_BUTTON

<receiver android:name=".RemoteControlReceiver">
    <intent-filter>
        <action android:name="android.intent.action.MEDIA_BUTTON" />
    </intent-filter>
</receiver>

The receiver implementation itself needs to extract which key was pressed to cause the broadcast. The Intent includes this under the EXTRA_KEY_EVENT key, while the KeyEvent class includes a listKEYCODE_MEDIA_* static constants that represents each of the possible media buttons, such asKEYCODE_MEDIA_PLAY_PAUSE and KEYCODE_MEDIA_NEXT.

得到按钮对应的常量。

The following snippet shows how to extract the media button pressed and affects the media playback accordingly.

public class RemoteControlReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
        if (Intent.ACTION_MEDIA_BUTTON.equals(intent.getAction())) {
            KeyEvent event = (KeyEvent)intent.getParcelableExtra(Intent.EXTRA_KEY_EVENT);
            if (KeyEvent.KEYCODE_MEDIA_PLAY == event.getKeyCode()) {
                // Handle key press.
            }
        }
    }
}

Because multiple applications might want to listen for media button presses, you must also programmatically control when your app should receive media button press events.

The following code can be used within your app to register and de-register your media button event receiver using the AudioManager. When registered, your broadcast receiver is the exclusive receiver of all media button broadcasts.

使用AudioManager来注册广播接收者。

AudioManager am = mContext.getSystemService(Context.AUDIO_SERVICE);
...

// Start listening for button presses
am.registerMediaButtonEventReceiver(RemoteControlReceiver);
...

// Stop listening for button presses
am.unregisterMediaButtonEventReceiver(RemoteControlReceiver);

Typically, apps should unregister most of their receivers whenever they become inactive or invisible (such as during the onStop() callback). However, it’s not that simple for media playback apps—in fact, responding to media playback buttons is most important when your application isn’t visible and therefore can’t be controlled by the on-screen UI.

A better approach is to register and unregister the media button event receiver when your application gains and loses the audio focus. This is covered in detail in the next lesson.