AudioPresentation.java revision 58822bec4eb6e0930f2efc0da5b6e464b193c558
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; 2058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.lang.annotation.Retention; 2258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.lang.annotation.RetentionPolicy; 2358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.HashMap; 2558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.Locale; 2658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangrooimport java.util.Map; 2758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 2958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo/** 3058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The AudioPresentation class encapsulates the information that describes an audio presentation 3158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * which is available in next generation audio content. 3258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 3358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Used by {@link MediaExtractor} {@link MediaExtractor#getAudioPresentations(int)} and 3458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link AudioTrack} {@link AudioTrack#setPresentation(AudioPresentation)} to query available 3558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * presentations and to select one. 3658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * 3758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * A list of available audio presentations in a media source can be queried using 3858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link MediaExtractor#getAudioPresentations(int)}. This list can be presented to a user for 3958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * selection. 4058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * An AudioPresentation can be passed to an offloaded audio decoder via 4158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link AudioTrack#setPresentation(AudioPresentation)} to request decoding of the selected 4258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * presentation. An audio stream may contain multiple presentations that differ by language, 4358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * accessibility, end point mastering and dialogue enhancement. An audio presentation may also have 4458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * a set of description labels in different languages to help the user to make an informed 4558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * selection. 4658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 4758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroopublic final class AudioPresentation { 4858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final int mPresentationId; 4958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final int mProgramId; 5058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final Map<String, String> mLabels; 5158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final String mLanguage; 5258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 5358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** @hide */ 5458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @IntDef( 5558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo value = { 5658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERING_NOT_INDICATED, 5758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_STEREO, 5858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_SURROUND, 5958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_3D, 6058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo MASTERED_FOR_HEADPHONE, 6158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo }) 6258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @Retention(RetentionPolicy.SOURCE) 6358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public @interface MasteringIndicationType {} 6458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 6558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final @MasteringIndicationType int mMasteringIndication; 6658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mAudioDescriptionAvailable; 6758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mSpokenSubtitlesAvailable; 6858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo private final boolean mDialogueEnhancementAvailable; 6958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 7058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 7158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * No preferred reproduction channel layout. 7258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 7358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERING_NOT_INDICATED = 0; 7458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 7558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Stereo speaker layout. 7658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 7758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_STEREO = 1; 7858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 7958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Two-dimensional (e.g. 5.1) speaker layout. 8058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_SURROUND = 2; 8258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 8358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Three-dimensional (e.g. 5.1.2) speaker layout. 8458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_3D = 3; 8658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 8758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Prerendered for headphone playback. 8858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 8958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public static final int MASTERED_FOR_HEADPHONE = 4; 9058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 9158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo AudioPresentation(int presentationId, 9258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo int programId, 9358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo Map<String, String> labels, 9458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo String language, 9558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @MasteringIndicationType int masteringIndication, 9658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean audioDescriptionAvailable, 9758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean spokenSubtitlesAvailable, 9858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo boolean dialogueEnhancementAvailable) { 9958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mPresentationId = presentationId; 10058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mProgramId = programId; 10158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mLanguage = language; 10258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mMasteringIndication = masteringIndication; 10358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mAudioDescriptionAvailable = audioDescriptionAvailable; 10458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mSpokenSubtitlesAvailable = spokenSubtitlesAvailable; 10558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mDialogueEnhancementAvailable = dialogueEnhancementAvailable; 10658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 10758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo this.mLabels = new HashMap<String, String>(labels); 10858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 10958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 11058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 11158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The framework uses this presentation id to select an audio presentation rendered by a 11258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * decoder. Presentation id is typically sequential, but does not have to be. 11358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @hide 11458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 11558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getPresentationId() { 11658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mPresentationId; 11758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 11858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 11958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 12058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * The framework uses this program id to select an audio presentation rendered by a decoder. 12158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Program id can be used to further uniquely identify the presentation to a decoder. 12258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @hide 12358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 12458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getProgramId() { 12558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mProgramId; 12658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 12758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 12858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 12958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return a map of available text labels for this presentation. Each label is indexed by its 13058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * locale corresponding to the language code as specified by ISO 639-2 [42]. Either ISO 639-2/B 13158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * or ISO 639-2/T could be used. 13258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 13358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public Map<Locale, String> getLabels() { 13458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo Map<Locale, String> localeLabels = new HashMap<>(); 13558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo for (Map.Entry<String, String> entry : mLabels.entrySet()) { 13658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo localeLabels.put(new Locale(entry.getKey()), entry.getValue()); 13758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 13858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return localeLabels; 13958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 14058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 14158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 14258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return the locale corresponding to audio presentation's ISO 639-1/639-2 language code. 14358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 14458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public Locale getLocale() { 14558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return new Locale(mLanguage); 14658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 14758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 14858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 14958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return the mastering indication of the audio presentation. 15058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * See {@link #MASTERING_NOT_INDICATED}, {@link #MASTERED_FOR_STEREO}, 15158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * {@link #MASTERED_FOR_SURROUND}, {@link #MASTERED_FOR_3D}, {@link #MASTERED_FOR_HEADPHONE} 15258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 15358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo @MasteringIndicationType 15458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public int getMasteringIndication() { 15558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mMasteringIndication; 15658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 15758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 15858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 15958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether an audio description for the visually impaired is available. 16058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if audio description is available. 16158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 16258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasAudioDescription() { 16358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mAudioDescriptionAvailable; 16458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 16558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 16658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 16758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether spoken subtitles for the visually impaired are available. 16858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if spoken subtitles are available. 16958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 17058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasSpokenSubtitles() { 17158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mSpokenSubtitlesAvailable; 17258822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 17358822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo 17458822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo /** 17558822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * Indicates whether dialogue enhancement is available. 17658822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo * @return {@code true} if dialogue enhancement is available. 17758822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo */ 17858822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo public boolean hasDialogueEnhancement() { 17958822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo return mDialogueEnhancementAvailable; 18058822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo } 18158822bec4eb6e0930f2efc0da5b6e464b193c558Previr Rangroo} 182