FileDocCategorySizeDatePackage
AudioAttributes.javaAPI DocAndroid 5.1 API31336Thu Mar 12 22:22:30 GMT 2015android.media

AudioAttributes

public final class AudioAttributes extends Object implements android.os.Parcelable
A class to encapsulate a collection of attributes describing information about an audio stream.

AudioAttributes supersede the notion of stream types (see for instance {@link AudioManager#STREAM_MUSIC} or {@link AudioManager#STREAM_ALARM}) for defining the behavior of audio playback. Attributes allow an application to specify more information than is conveyed in a stream type by allowing the application to define:

  • usage: "why" you are playing a sound, what is this sound used for. This is achieved with the "usage" information. Examples of usage are {@link #USAGE_MEDIA} and {@link #USAGE_ALARM}. These two examples are the closest to stream types, but more detailed use cases are available. Usage information is more expressive than a stream type, and allows certain platforms or routing policies to use this information for more refined volume or routing decisions. Usage is the most important information to supply in AudioAttributes and it is recommended to build any instance with this information supplied, see {@link AudioAttributes.Builder} for exceptions.
  • content type: "what" you are playing. The content type expresses the general category of the content. This information is optional. But in case it is known (for instance {@link #CONTENT_TYPE_MOVIE} for a movie streaming service or {@link #CONTENT_TYPE_MUSIC} for a music playback application) this information might be used by the audio framework to selectively configure some audio post-processing blocks.
  • flags: "how" is playback to be affected, see the flag definitions for the specific playback behaviors they control.

AudioAttributes are used for example in one of the {@link AudioTrack} constructors (see {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}), to configure a {@link MediaPlayer} (see {@link MediaPlayer#setAudioAttributes(AudioAttributes)} or a {@link android.app.Notification} (see {@link android.app.Notification#audioAttributes}). An AudioAttributes instance is built through its builder, {@link AudioAttributes.Builder}.

Fields Summary
private static final String
TAG
public static final int
CONTENT_TYPE_UNKNOWN
Content type value to use when the content type is unknown, or other than the ones defined.
public static final int
CONTENT_TYPE_SPEECH
Content type value to use when the content type is speech.
public static final int
CONTENT_TYPE_MUSIC
Content type value to use when the content type is music.
public static final int
CONTENT_TYPE_MOVIE
Content type value to use when the content type is a soundtrack, typically accompanying a movie or TV program.
public static final int
CONTENT_TYPE_SONIFICATION
Content type value to use when the content type is a sound used to accompany a user action, such as a beep or sound effect expressing a key click, or event, such as the type of a sound for a bonus being received in a game. These sounds are mostly synthesized or short Foley sounds.
public static final int
USAGE_UNKNOWN
Usage value to use when the usage is unknown.
public static final int
USAGE_MEDIA
Usage value to use when the usage is media, such as music, or movie soundtracks.
public static final int
USAGE_VOICE_COMMUNICATION
Usage value to use when the usage is voice communications, such as telephony or VoIP.
public static final int
USAGE_VOICE_COMMUNICATION_SIGNALLING
Usage value to use when the usage is in-call signalling, such as with a "busy" beep, or DTMF tones.
public static final int
USAGE_ALARM
Usage value to use when the usage is an alarm (e.g. wake-up alarm).
public static final int
USAGE_NOTIFICATION
Usage value to use when the usage is notification. See other notification usages for more specialized uses.
public static final int
USAGE_NOTIFICATION_RINGTONE
Usage value to use when the usage is telephony ringtone.
public static final int
USAGE_NOTIFICATION_COMMUNICATION_REQUEST
Usage value to use when the usage is a request to enter/end a communication, such as a VoIP communication or video-conference.
public static final int
USAGE_NOTIFICATION_COMMUNICATION_INSTANT
Usage value to use when the usage is notification for an "instant" communication such as a chat, or SMS.
public static final int
USAGE_NOTIFICATION_COMMUNICATION_DELAYED
Usage value to use when the usage is notification for a non-immediate type of communication such as e-mail.
public static final int
USAGE_NOTIFICATION_EVENT
Usage value to use when the usage is to attract the user's attention, such as a reminder or low battery warning.
public static final int
USAGE_ASSISTANCE_ACCESSIBILITY
Usage value to use when the usage is for accessibility, such as with a screen reader.
public static final int
USAGE_ASSISTANCE_NAVIGATION_GUIDANCE
Usage value to use when the usage is driving or navigation directions.
public static final int
USAGE_ASSISTANCE_SONIFICATION
Usage value to use when the usage is sonification, such as with user interface sounds.
public static final int
USAGE_GAME
Usage value to use when the usage is for game audio.
public static final int
USAGE_VIRTUAL_SOURCE
public static final int
FLAG_AUDIBILITY_ENFORCED
Flag defining a behavior where the audibility of the sound will be ensured by the system.
public static final int
FLAG_SECURE
public static final int
FLAG_SCO
public static final int
FLAG_BEACON
public static final int
FLAG_HW_AV_SYNC
Flag requesting the use of an output stream supporting hardware A/V synchronization.
public static final int
FLAG_HW_HOTWORD
private static final int
FLAG_ALL
private static final int
FLAG_ALL_PUBLIC
private int
mUsage
private int
mContentType
private int
mSource
private int
mFlags
private HashSet
mTags
private String
mFormattedTags
public static final int
FLATTEN_TAGS
private static final int
ALL_PARCEL_FLAGS
When adding tags for writeToParcel(Parcel, int), add them in the list of flags (| NEW_FLAG)
public static final Parcelable.Creator
CREATOR
Constructors Summary
private AudioAttributes()
private AudioAttributes(android.os.Parcel in)

        mUsage = in.readInt();
        mContentType = in.readInt();
        mSource = in.readInt();
        mFlags = in.readInt();
        boolean hasFlattenedTags = ((in.readInt() & FLATTEN_TAGS) == FLATTEN_TAGS);
        mTags = new HashSet<String>();
        if (hasFlattenedTags) {
            mFormattedTags = new String(in.readString());
            mTags.add(mFormattedTags);
        } else {
            String[] tagsArray = in.readStringArray();
            for (int i = tagsArray.length - 1 ; i >= 0 ; i--) {
                mTags.add(tagsArray[i]);
            }
            mFormattedTags = TextUtils.join(";", mTags);
        }
Methods Summary
public intdescribeContents()

        return 0;
public booleanequals(java.lang.Object o)


    
        
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;

        AudioAttributes that = (AudioAttributes) o;

        return ((mContentType == that.mContentType)
                && (mFlags == that.mFlags)
                && (mSource == that.mSource)
                && (mUsage == that.mUsage)
                //mFormattedTags is never null due to assignment in Builder or unmarshalling
                && (mFormattedTags.equals(that.mFormattedTags)));
public intgetAllFlags()

hide
Return all the flags, even the non-public ones. Internal use only
return
a combined mask of all flags

        return (mFlags & FLAG_ALL);
public intgetCapturePreset()

hide
Return the capture preset.
return
one of the values that can be set in {@link Builder#setCapturePreset(int)} or a negative value if none has been set.

        return mSource;
public intgetContentType()
Return the content type.

return
one of the values that can be set in {@link Builder#setContentType(int)}

        return mContentType;
public intgetFlags()
Return the flags.

return
a combined mask of all flags

        // only return the flags that are public
        return (mFlags & (FLAG_ALL_PUBLIC));
public java.util.SetgetTags()

hide
Return the set of tags.
return
a read-only set of all tags stored as strings.

        return Collections.unmodifiableSet(mTags);
public intgetUsage()
Return the usage.

return
one of the values that can be set in {@link Builder#setUsage(int)}

        return mUsage;
public inthashCode()

        return Objects.hash(mContentType, mFlags, mSource, mUsage, mFormattedTags);
public static inttoLegacyStreamType(android.media.AudioAttributes aa)

hide

        // flags to stream type mapping
        if ((aa.getFlags() & FLAG_AUDIBILITY_ENFORCED) == FLAG_AUDIBILITY_ENFORCED) {
            return AudioSystem.STREAM_SYSTEM_ENFORCED;
        }
        if ((aa.getFlags() & FLAG_SCO) == FLAG_SCO) {
            return AudioSystem.STREAM_BLUETOOTH_SCO;
        }

        // usage to stream type mapping
        switch (aa.getUsage()) {
            case USAGE_MEDIA:
            case USAGE_GAME:
            case USAGE_ASSISTANCE_ACCESSIBILITY:
            case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE:
                return AudioSystem.STREAM_MUSIC;
            case USAGE_ASSISTANCE_SONIFICATION:
                return AudioSystem.STREAM_SYSTEM;
            case USAGE_VOICE_COMMUNICATION:
                return AudioSystem.STREAM_VOICE_CALL;
            case USAGE_VOICE_COMMUNICATION_SIGNALLING:
                return AudioSystem.STREAM_DTMF;
            case USAGE_ALARM:
                return AudioSystem.STREAM_ALARM;
            case USAGE_NOTIFICATION_RINGTONE:
                return AudioSystem.STREAM_RING;
            case USAGE_NOTIFICATION:
            case USAGE_NOTIFICATION_COMMUNICATION_REQUEST:
            case USAGE_NOTIFICATION_COMMUNICATION_INSTANT:
            case USAGE_NOTIFICATION_COMMUNICATION_DELAYED:
            case USAGE_NOTIFICATION_EVENT:
                return AudioSystem.STREAM_NOTIFICATION;
            case USAGE_UNKNOWN:
            default:
                return AudioSystem.STREAM_MUSIC;
        }
public java.lang.StringtoString()

        return new String("AudioAttributes:"
                + " usage=" + mUsage
                + " content=" + mContentType
                + " flags=0x" + Integer.toHexString(mFlags).toUpperCase()
                + " tags=" + mFormattedTags);
public static intusageForLegacyStreamType(int streamType)

hide

        switch(streamType) {
            case AudioSystem.STREAM_VOICE_CALL:
                return USAGE_VOICE_COMMUNICATION;
            case AudioSystem.STREAM_SYSTEM_ENFORCED:
            case AudioSystem.STREAM_SYSTEM:
                return USAGE_ASSISTANCE_SONIFICATION;
            case AudioSystem.STREAM_RING:
                return USAGE_NOTIFICATION_RINGTONE;
            case AudioSystem.STREAM_MUSIC:
                return USAGE_MEDIA;
            case AudioSystem.STREAM_ALARM:
                return USAGE_ALARM;
            case AudioSystem.STREAM_NOTIFICATION:
                return USAGE_NOTIFICATION;
            case AudioSystem.STREAM_BLUETOOTH_SCO:
                return USAGE_VOICE_COMMUNICATION;
            case AudioSystem.STREAM_DTMF:
                return USAGE_VOICE_COMMUNICATION_SIGNALLING;
            case AudioSystem.STREAM_TTS:
                return USAGE_ASSISTANCE_ACCESSIBILITY;
            default:
                return USAGE_UNKNOWN;
        }
public java.lang.StringusageToString()

hide

        return usageToString(mUsage);
public static java.lang.StringusageToString(int usage)

hide

        switch(usage) {
            case USAGE_UNKNOWN:
                return new String("USAGE_UNKNOWN");
            case USAGE_MEDIA:
                return new String("USAGE_MEDIA");
            case USAGE_VOICE_COMMUNICATION:
                return new String("USAGE_VOICE_COMMUNICATION");
            case USAGE_VOICE_COMMUNICATION_SIGNALLING:
                return new String("USAGE_VOICE_COMMUNICATION");
            case USAGE_ALARM:
                return new String("USAGE_ALARM");
            case USAGE_NOTIFICATION:
                return new String("USAGE_NOTIFICATION");
            case USAGE_NOTIFICATION_RINGTONE:
                return new String("USAGE_NOTIFICATION");
            case USAGE_NOTIFICATION_COMMUNICATION_REQUEST:
                return new String("USAGE_NOTIFICATION");
            case USAGE_NOTIFICATION_COMMUNICATION_INSTANT:
                return new String("USAGE_NOTIFICATION_COMMUNICATION_INSTANT");
            case USAGE_NOTIFICATION_COMMUNICATION_DELAYED:
                return new String("USAGE_NOTIFICATION_COMMUNICATION_DELAYED");
            case USAGE_NOTIFICATION_EVENT:
                return new String("USAGE_NOTIFICATION_EVENT");
            case USAGE_ASSISTANCE_ACCESSIBILITY:
                return new String("USAGE_ASSISTANCE_ACCESSIBILITY");
            case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE:
                return new String("USAGE_ASSISTANCE_NAVIGATION_GUIDANCE");
            case USAGE_ASSISTANCE_SONIFICATION:
                return new String("USAGE_ASSISTANCE_SONIFICATION");
            case USAGE_GAME:
                return new String("USAGE_GAME");
            default:
                return new String("unknown usage " + usage);
        }
public voidwriteToParcel(android.os.Parcel dest, int flags)

    
          
        dest.writeInt(mUsage);
        dest.writeInt(mContentType);
        dest.writeInt(mSource);
        dest.writeInt(mFlags);
        dest.writeInt(flags & ALL_PARCEL_FLAGS);
        if ((flags & FLATTEN_TAGS) == 0) {
            String[] tagsArray = new String[mTags.size()];
            mTags.toArray(tagsArray);
            dest.writeStringArray(tagsArray);
        } else if ((flags & FLATTEN_TAGS) == FLATTEN_TAGS) {
            dest.writeString(mFormattedTags);
        }