Which AudioAttributes usage a workout coaching cue should declare

Every Android player and every focus request carries an AudioAttributes, and most cue code fills it in by copying the first snippet it finds. The usage you pick is not a label. It changes whether Android 12's forced fade-out applies to you, whether you are muted during a call, whether other apps can capture your audio, and how the system treats the user's music while you speak.

Google publishes no usage constant that names exercise coaching. So this is the one page in the cluster where the recommendation is mostly ours, and it shows the documented facts it rests on.

What usage and content type mean#

Google's AudioAttributes reference: usage is ""why" you are playing a sound, what is this sound used for," and "Usage is the most important information to supply in AudioAttributes and it is recommended to build any instance with this information supplied." Content type is ""what" you are playing," which "is optional," and which "might be used by the audio framework to selectively configure some audio post-processing blocks." Attributes "supersede the notion of stream types."

The candidates, in Google's words#

Content types that matter: CONTENT_TYPE_SPEECH, "the content type is speech"; CONTENT_TYPE_SONIFICATION, "a sound used to accompany a user action, such as a beep or sound effect"; and CONTENT_TYPE_MUSIC.

Documented consequence 1: the Android 12 rules key on USAGE_MEDIA#

Google's Manage audio focus guide describes two system behaviours on Android 12 and higher, and both are scoped by usage. The forced fade-out applies when the playing app "has either the AudioAttributes.USAGE_MEDIA or AudioAttributes.USAGE_GAME usage attribute," and another app requests AUDIOFOCUS_GAIN. The incoming-call mute applies to an app that "has either the AudioAttributes.USAGE_MEDIA or AudioAttributes.USAGE_GAME usage attribute," has focus, and is playing: "its playback is muted until the call ends."

For a cue played with USAGE_MEDIA, the call mute is arguably what you want. For a long guided session it is exactly what you want. Either way, it is a behaviour you get or lose by choosing the usage.

Documented consequence 2: CONTENT_TYPE_SPEECH changes how you are ducked#

The same guide: automatic ducking only happens when the playing app "is not playing audio with content type AudioAttributes.CONTENT_TYPE_SPEECH." The AudioFocusRequest reference says this "behavior is independent of the use of AudioFocusRequest, but tied to the use of AudioAttributes," and that speech players get AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK through their listener "so they can pause instead."

This matters if your app plays long spoken content of its own: a guided run, an audio class. Mark it CONTENT_TYPE_SPEECH and a navigation prompt or a notification will not talk over your coach; your listener gets the chance to pause. The flip side is that you must implement that listener, because the system will no longer duck you.

For a three-second cue, the content type of your own player barely matters to ducking; what matters is the content type of the app you are interrupting.

Documented consequence 3: capture#

The reference's capture policy note: "For privacy, the following usages cannot be recorded: VOICE_COMMUNICATION*, USAGE_NOTIFICATION*, USAGE_ASSISTANCE* and USAGE_ASSISTANT." And on Android 10: "only USAGE_UNKNOWN, USAGE_MEDIA and USAGE_GAME may be captured." If your users record their workouts with a screen-recording or streaming app and expect the coaching voice in the recording, an assistance usage will leave it out. That is a product consideration, not a reason to pick one usage over another.

Google's general guidance points the other way#

Google's Handling changes in audio output guide gives broader advice: "Unless your app is an alarm clock, you should play audio with usage AudioAttributes.USAGE_MEDIA," so that the volume keys adjust the right stream, using setVolumeControlStream() with the stream from AudioAttributes.getVolumeControlStream. That sentence is written for apps whose audio is media. It is also the strongest general instruction Google gives, and we are not going to pretend it does not exist.

What we could not verify is which volume stream each assistance usage maps to on current devices. That decides which volume the user's buttons change while a cue plays, and it is the part to test on hardware before you commit.

Our recommendation#

What follows is judgement, built on the facts above.

USAGE_ASSISTANT is a defensible alternative for spoken cues: "audio instructions" is close to what a coach says. We lean to navigation guidance because Google's transient-ducking examples are written around it. Whatever you choose, use the same attributes in the focus request and the player; Google's focus guide says to, and a mismatch means the focus request describes a different sound from the one you play.

val spokenCue = AudioAttributes.Builder()
    .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
    .build()

val tone = AudioAttributes.Builder()
    .setUsage(AudioAttributes.USAGE_ASSISTANCE_SONIFICATION)
    .setContentType(AudioAttributes.CONTENT_TYPE_SONIFICATION)
    .build()

Monday morning#

List every AudioAttributes.Builder in the app and write down what each one plays. Make cue, tone, guided-session and music-bed attributes four named constants instead of inline builders. Pass the same constant to the player and the focus request. Then, on a real device, press the volume keys while a cue is speaking and confirm the user is changing the volume they expect; that is the part no reference we read could tell us.