AudioPresentation.java revision 6b2394899f6792528de1636c7a6ed5f85c4573ad
158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo/* 258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Copyright (C) 2018 The Android Open Source Project 358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Licensed under the Apache License, Version 2.0 (the "License"); 558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * you may not use this file except in compliance with the License. 658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * You may obtain a copy of the License at 758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * http://www.apache.org/licenses/LICENSE-2.0 958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 1058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Unless required by applicable law or agreed to in writing, software 1158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * distributed under the License is distributed on an "AS IS" BASIS, 1258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * See the License for the specific language governing permissions and 1458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * limitations under the License. 1558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 1658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 1758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroopackage android.media; 1858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 1958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport android.annotation.IntDef; 206b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganovimport android.annotation.NonNull; 216b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov 226b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganovimport com.android.internal.annotations.VisibleForTesting; 2358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.lang.annotation.Retention; 2558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.lang.annotation.RetentionPolicy; 2658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.HashMap; 2858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.Locale; 2958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.Map; 3058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 3158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 3258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo/** 3358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The AudioPresentation class encapsulates the information that describes an audio presentation 3458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * which is available in next generation audio content. 3558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 3658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Used by {@link MediaExtractor} {@link MediaExtractor#getAudioPresentations(int)} and 3758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link AudioTrack} {@link AudioTrack#setPresentation(AudioPresentation)} to query available 3858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * presentations and to select one. 3958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 4058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * A list of available audio presentations in a media source can be queried using 4158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link MediaExtractor#getAudioPresentations(int)}. This list can be presented to a user for 4258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * selection. 4358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * An AudioPresentation can be passed to an offloaded audio decoder via 4458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link AudioTrack#setPresentation(AudioPresentation)} to request decoding of the selected 4558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * presentation. An audio stream may contain multiple presentations that differ by language, 4658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * accessibility, end point mastering and dialogue enhancement. An audio presentation may also have 4758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * a set of description labels in different languages to help the user to make an informed 4858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * selection. 4958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 5058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroopublic final class AudioPresentation { 5158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final int mPresentationId; 5258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final int mProgramId; 5358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final Map<String, String> mLabels; 5458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final String mLanguage; 5558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 5658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** @hide */ 5758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @IntDef( 5858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo value = { 5958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERING_NOT_INDICATED, 6058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_STEREO, 6158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_SURROUND, 6258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_3D, 6358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_HEADPHONE, 6458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo }) 6558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @Retention(RetentionPolicy.SOURCE) 6658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public @interface MasteringIndicationType {} 6758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 6858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final @MasteringIndicationType int mMasteringIndication; 6958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mAudioDescriptionAvailable; 7058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mSpokenSubtitlesAvailable; 7158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mDialogueEnhancementAvailable; 7258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 7358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 7458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * No preferred reproduction channel layout. 7558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 7658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERING_NOT_INDICATED = 0; 7758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 7858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Stereo speaker layout. 7958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_STEREO = 1; 8158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 8258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Two-dimensional (e.g. 5.1) speaker layout. 8358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_SURROUND = 2; 8558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 8658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Three-dimensional (e.g. 5.1.2) speaker layout. 8758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_3D = 3; 8958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 9058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Prerendered for headphone playback. 9158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 9258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_HEADPHONE = 4; 9358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 946b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov /** 956b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov * @hide 966b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov */ 976b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov @VisibleForTesting(visibility = VisibleForTesting.Visibility.PACKAGE) 986b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov public AudioPresentation(int presentationId, 9958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo int programId, 1006b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov @NonNull Map<String, String> labels, 1016b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov @NonNull String language, 10258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @MasteringIndicationType int masteringIndication, 10358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean audioDescriptionAvailable, 10458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean spokenSubtitlesAvailable, 10558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean dialogueEnhancementAvailable) { 10658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mPresentationId = presentationId; 10758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mProgramId = programId; 10858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mLanguage = language; 10958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mMasteringIndication = masteringIndication; 11058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mAudioDescriptionAvailable = audioDescriptionAvailable; 11158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mSpokenSubtitlesAvailable = spokenSubtitlesAvailable; 11258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mDialogueEnhancementAvailable = dialogueEnhancementAvailable; 11358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 11458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mLabels = new HashMap<String, String>(labels); 11558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 11658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 11758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 11858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The framework uses this presentation id to select an audio presentation rendered by a 11958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * decoder. Presentation id is typically sequential, but does not have to be. 12058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @hide 12158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 1226b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov @VisibleForTesting 12358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getPresentationId() { 12458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mPresentationId; 12558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 12658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 12758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 12858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The framework uses this program id to select an audio presentation rendered by a decoder. 12958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Program id can be used to further uniquely identify the presentation to a decoder. 13058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @hide 13158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 1326b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov @VisibleForTesting 13358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getProgramId() { 13458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mProgramId; 13558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 13658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 13758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 13858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return a map of available text labels for this presentation. Each label is indexed by its 1396b2394899f6792528de1636c7a6ed5f85c4573adMikhail Naganov * locale corresponding to the language code as specified by ISO 639-2. Either ISO 639-2/B 14058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * or ISO 639-2/T could be used. 14158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 14258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public Map<Locale, String> getLabels() { 14358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo Map<Locale, String> localeLabels = new HashMap<>(); 14458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo for (Map.Entry<String, String> entry : mLabels.entrySet()) { 14558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo localeLabels.put(new Locale(entry.getKey()), entry.getValue()); 14658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 14758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return localeLabels; 14858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 14958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 15058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 15158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return the locale corresponding to audio presentation's ISO 639-1/639-2 language code. 15258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 15358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public Locale getLocale() { 15458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return new Locale(mLanguage); 15558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 15658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 15758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 15858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return the mastering indication of the audio presentation. 15958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * See {@link #MASTERING_NOT_INDICATED}, {@link #MASTERED_FOR_STEREO}, 16058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link #MASTERED_FOR_SURROUND}, {@link #MASTERED_FOR_3D}, {@link #MASTERED_FOR_HEADPHONE} 16158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 16258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @MasteringIndicationType 16358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getMasteringIndication() { 16458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mMasteringIndication; 16558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 16658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 16758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 16858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether an audio description for the visually impaired is available. 16958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if audio description is available. 17058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 17158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasAudioDescription() { 17258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mAudioDescriptionAvailable; 17358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 17458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 17558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 17658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether spoken subtitles for the visually impaired are available. 17758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if spoken subtitles are available. 17858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 17958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasSpokenSubtitles() { 18058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mSpokenSubtitlesAvailable; 18158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 18258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 18358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 18458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether dialogue enhancement is available. 18558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if dialogue enhancement is available. 18658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 18758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasDialogueEnhancement() { 18858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mDialogueEnhancementAvailable; 18958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 19058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo} 191