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