CarAudioManager.java revision c5dc1964a09d266243ba418e96f1937b199ec93e
1a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung/* 2a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * Copyright (C) 2015 The Android Open Source Project 3a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * 4a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * Licensed under the Apache License, Version 2.0 (the "License"); 5a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * you may not use this file except in compliance with the License. 6a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * You may obtain a copy of the License at 7a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * 8a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * http://www.apache.org/licenses/LICENSE-2.0 9a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * 10a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * Unless required by applicable law or agreed to in writing, software 11a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * distributed under the License is distributed on an "AS IS" BASIS, 12a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * See the License for the specific language governing permissions and 14a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung * limitations under the License. 15a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung */ 16a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoungpackage android.support.car.media; 17a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung 18df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkivimport android.Manifest; 19a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoungimport android.media.AudioAttributes; 20df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkivimport android.media.AudioFormat; 216f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkivimport android.media.AudioManager.OnAudioFocusChangeListener; 225672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Parkimport android.support.annotation.IntDef; 23df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkivimport android.support.annotation.RequiresPermission; 24a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoungimport android.support.car.CarManagerBase; 25eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chenimport android.support.car.CarNotConnectedException; 26c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrupimport android.support.car.CarNotSupportedException; 27a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung 285672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Parkimport java.lang.annotation.Retention; 295672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Parkimport java.lang.annotation.RetentionPolicy; 305672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park 315672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park/** 325672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * APIs for handling car specific audio stuffs. 335672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 34e54ac276796c6535558f8444d882adecd19ce2bdKeun-young Parkpublic abstract class CarAudioManager implements CarManagerBase { 35a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung 36a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung /** 375672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for unspecified type. 385672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 395672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_DEFAULT = 0; 405672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 415672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for playing music. 425672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 435672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_MUSIC = 1; 445672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 455672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for H/W radio. 465672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 475672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_RADIO = 2; 485672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 495672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for playing navigation guidance. 505672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 515672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_NAVIGATION_GUIDANCE = 3; 525672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 535672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for voice call 545672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 555672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_VOICE_CALL = 4; 565672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 575672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for voice search or voice command. 585672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 595672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_VOICE_COMMAND = 5; 605672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 615672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for playing alarm. 62a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung */ 635672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_ALARM = 6; 645672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 655672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for notification sound. 665672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 675672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_NOTIFICATION = 7; 685672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 695672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for system sound like UI feedback. 705672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 715672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_SYSTEM_SOUND = 8; 725672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 735672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Audio usage for playing safety alert. 745672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 755672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_SYSTEM_SAFETY_ALERT = 9; 765672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park 775672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** @hide */ 785672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public static final int CAR_AUDIO_USAGE_MAX = CAR_AUDIO_USAGE_SYSTEM_SAFETY_ALERT; 795672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park 805672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** @hide */ 815672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park @IntDef({CAR_AUDIO_USAGE_DEFAULT, CAR_AUDIO_USAGE_MUSIC, CAR_AUDIO_USAGE_RADIO, 825672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park CAR_AUDIO_USAGE_NAVIGATION_GUIDANCE, CAR_AUDIO_USAGE_VOICE_CALL, 835672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park CAR_AUDIO_USAGE_VOICE_COMMAND, CAR_AUDIO_USAGE_ALARM, CAR_AUDIO_USAGE_NOTIFICATION, 845672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park CAR_AUDIO_USAGE_SYSTEM_SOUND, CAR_AUDIO_USAGE_SYSTEM_SAFETY_ALERT}) 855672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park @Retention(RetentionPolicy.SOURCE) 865672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park public @interface CarAudioUsage {} 87a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung 885672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park /** 895672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * Get {@link AudioAttrbutes} relevant for the given usage in car. 905672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * @param carUsage 915672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park * @return 925672e85bdf82f6a2350afb942dfe17b7c699af87Keun-young Park */ 93e54ac276796c6535558f8444d882adecd19ce2bdKeun-young Park public abstract AudioAttributes getAudioAttributesForCarUsage(@CarAudioUsage int carUsage); 946f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv 956f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv /** 966f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * Request audio focus. 976f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * Send a request to obtain the audio focus. 986f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param l 996f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param requestAttributes 1006f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param durationHint 1016f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param flags 1026f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv */ 1036f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv public abstract int requestAudioFocus(OnAudioFocusChangeListener l, 1046f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv AudioAttributes requestAttributes, 1056f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv int durationHint, 1066f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv int flags) throws IllegalArgumentException; 1076f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv /** 1086f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * Abandon audio focus. Causes the previous focus owner, if any, to receive focus. 1096f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param l 1106f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @param aa 1116f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv * @return {@link #AUDIOFOCUS_REQUEST_FAILED} or {@link #AUDIOFOCUS_REQUEST_GRANTED} 1126f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv */ 1136f3f402a7469e300fbfe65d950204fef995d4d8dVitalii Tomkiv public abstract int abandonAudioFocus(OnAudioFocusChangeListener l, AudioAttributes aa); 114df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv 115df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv /** 116df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * Get {@link AudioFormat} for audio record. 117df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @return {@link AudioFormat} for audio record. 118df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv */ 119df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv public abstract AudioFormat getAudioRecordAudioFormat(); 120df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv 121df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv /** 122df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * Get minimum buffer size for {@link CarAudioRecord}. 123c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * 124df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @return buffer size in bytes. 125df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv */ 126c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup public abstract int getAudioRecordMinBufferSize() 127c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup throws CarNotConnectedException, CarNotSupportedException; 128df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv 129df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv /** 130df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * Get maximum buffer size for {@link CarAudioRecord}. 131c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * 132df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @return buffer size in bytes. 133df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv */ 134c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup public abstract int getAudioRecordMaxBufferSize() 135c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup throws CarNotConnectedException, CarNotSupportedException; 136df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv 137df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv /** 138df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * Create a {@link CarAudioRecord} for the current {@link CarAudioManager}. There can be 139c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * multiple instances of {@link CarAudioRecord}. This requires {@link 140c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * android.Manifest.permission#RECORD_AUDIO} permission. 141c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * 142c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * @param bufferSize It should be a multiple of minimum buffer size acquired from {@link 143c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * #getAudioRecordMinBufferSize()}. This cannot exceed {@link #getAudioRecordMaxBufferSize()}. 144c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * 145df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @return {@link CarAudioRecord} instance for the given stream. 146df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @throws IllegalArgumentException if passed parameter like bufferSize is wrong. 147df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv * @throws SecurityException if client does not have 148c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * {@link android.Manifest.permission#RECORD_AUDIO} 149c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup * permission. 150df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv */ 151df5e37387b5bcbed7345b11c0e8393d2d8959306Vitalii Tomkiv @RequiresPermission(Manifest.permission.RECORD_AUDIO) 152c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup public abstract CarAudioRecord createCarAudioRecord(int bufferSize) 153c5dc1964a09d266243ba418e96f1937b199ec93eJason Tholstrup throws SecurityException, CarNotConnectedException, CarNotSupportedException; 154eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen 155eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen /** 156eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * Check if media audio is muted or not. This will include music and radio. Any application 157eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * taking audio focus for media stream will get it out of mute state. 158eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * 159eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * @return {@code true} if media is muted. 160eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen */ 161eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen public abstract boolean isMediaMuted() throws CarNotConnectedException; 162eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen 163eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen /** 164eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * Mute or unmute media stream including radio. This can involve audio focus change to stop 165eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * whatever app holding audio focus now. If requester is currently holding audio focus, 166eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * it will get LOSS_TRANSIENT focus loss. 167eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * This API requires {@link android.car.Car.PERMISSION_CAR_CONTROL_AUDIO_VOLUME} permission. 168eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * 169eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * @param mute {@code true} if media stream should be muted. 170eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * @return Mute state of system after the request. Note that mute request can fail if there 171eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * is higher priority audio already being played like phone call. 172eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen * @hide 173eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen */ 174eaad6efb79308bed2fca49e6dd19f7608071ee27Anthony Chen public abstract boolean setMediaMute(boolean mute) throws CarNotConnectedException; 175a74b9caa2fb6435f1c01c5e8766b89235c4e3d5akeunyoung} 176