| /* |
| * Copyright (C) 2021 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package android.media; |
| |
| import android.annotation.CallbackExecutor; |
| import android.annotation.IntDef; |
| import android.annotation.IntRange; |
| import android.annotation.NonNull; |
| import android.annotation.Nullable; |
| import android.annotation.RequiresPermission; |
| import android.annotation.SuppressLint; |
| import android.annotation.SystemApi; |
| import android.media.CallbackUtil.ListenerInfo; |
| import android.media.permission.ClearCallingIdentityContext; |
| import android.media.permission.SafeCloseable; |
| import android.os.RemoteException; |
| import android.util.Log; |
| |
| import com.android.internal.annotations.GuardedBy; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.RetentionPolicy; |
| import java.util.ArrayList; |
| import java.util.List; |
| import java.util.Objects; |
| import java.util.concurrent.Executor; |
| |
| /** |
| * Spatializer provides access to querying capabilities and behavior of sound spatialization |
| * on the device. |
| * Sound spatialization simulates sounds originating around the listener as if they were coming |
| * from virtual speakers placed around the listener.<br> |
| * Support for spatialization is optional, use {@link AudioManager#getSpatializer()} to obtain an |
| * instance of this class if the feature is supported. |
| * |
| */ |
| public class Spatializer { |
| |
| private final @NonNull AudioManager mAm; |
| |
| private static final String TAG = "Spatializer"; |
| |
| /** |
| * @hide |
| * Constructor with AudioManager acting as proxy to AudioService |
| * @param am a non-null AudioManager |
| */ |
| protected Spatializer(@NonNull AudioManager am) { |
| mAm = Objects.requireNonNull(am); |
| } |
| |
| /** |
| * Returns whether spatialization is enabled or not. |
| * A false value can originate for instance from the user electing to |
| * disable the feature, or when the feature is not supported on the device (indicated |
| * by {@link #getImmersiveAudioLevel()} returning {@link #SPATIALIZER_IMMERSIVE_LEVEL_NONE}). |
| * <br> |
| * Note that this state reflects a platform-wide state of the "desire" to use spatialization, |
| * but availability of the audio processing is still dictated by the compatibility between |
| * the effect and the hardware configuration, as indicated by {@link #isAvailable()}. |
| * @return {@code true} if spatialization is enabled |
| * @see #isAvailable() |
| */ |
| public boolean isEnabled() { |
| try { |
| return mAm.getService().isSpatializerEnabled(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error querying isSpatializerEnabled, returning false", e); |
| return false; |
| } |
| } |
| |
| /** |
| * Returns whether spatialization is available. |
| * Reasons for spatialization being unavailable include situations where audio output is |
| * incompatible with sound spatialization, such as playback on a monophonic speaker.<br> |
| * Note that spatialization can be available, but disabled by the user, in which case this |
| * method would still return {@code true}, whereas {@link #isEnabled()} |
| * would return {@code false}.<br> |
| * Also when the feature is not supported on the device (indicated |
| * by {@link #getImmersiveAudioLevel()} returning {@link #SPATIALIZER_IMMERSIVE_LEVEL_NONE}), |
| * the return value will be false. |
| * @return {@code true} if the spatializer effect is available and capable |
| * of processing the audio for the current configuration of the device, |
| * {@code false} otherwise. |
| * @see #isEnabled() |
| */ |
| public boolean isAvailable() { |
| try { |
| return mAm.getService().isSpatializerAvailable(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error querying isSpatializerAvailable, returning false", e); |
| return false; |
| } |
| } |
| |
| /** |
| * @hide |
| * Returns whether spatialization is available for a given audio device |
| * Reasons for spatialization being unavailable include situations where audio output is |
| * incompatible with sound spatialization, such as the device being a monophonic speaker, or |
| * the spatializer effect not supporting transaural processing when querying for speaker. |
| * @param device the audio device for which spatializer availability is queried |
| * @return {@code true} if the spatializer effect is available and capable |
| * of processing the audio over the given audio device, |
| * {@code false} otherwise. |
| * @see #isEnabled() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public boolean isAvailableForDevice(@NonNull AudioDeviceAttributes device) { |
| Objects.requireNonNull(device); |
| try { |
| return mAm.getService().isSpatializerAvailableForDevice(device); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| return false; |
| } |
| |
| /** |
| * @hide |
| * Returns whether the given device has an associated headtracker |
| * @param device the audio device to query |
| * @return true if the device has a head tracker, false otherwise |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public boolean hasHeadTracker(@NonNull AudioDeviceAttributes device) { |
| Objects.requireNonNull(device); |
| try { |
| return mAm.getService().hasHeadTracker(device); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| return false; |
| } |
| |
| /** |
| * @hide |
| * Enables or disables the head tracker of the given device |
| * @param enabled true to enable, false to disable |
| * @param device the device whose head tracker state is changed |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setHeadTrackerEnabled(boolean enabled, @NonNull AudioDeviceAttributes device) { |
| Objects.requireNonNull(device); |
| try { |
| mAm.getService().setHeadTrackerEnabled(enabled, device); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| } |
| |
| /** |
| * @hide |
| * Returns whether the head tracker of the device is enabled |
| * @param device the device to query |
| * @return true if the head tracker is enabled, false if disabled or if there isn't one |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public boolean isHeadTrackerEnabled(@NonNull AudioDeviceAttributes device) { |
| Objects.requireNonNull(device); |
| try { |
| return mAm.getService().isHeadTrackerEnabled(device); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| return false; |
| } |
| |
| /** |
| * Returns whether a head tracker is currently available for the audio device used by the |
| * spatializer effect. |
| * @return true if a head tracker is available and the effect is enabled, false otherwise. |
| * @see OnHeadTrackerAvailableListener |
| * @see #addOnHeadTrackerAvailableListener(Executor, OnHeadTrackerAvailableListener) |
| */ |
| public boolean isHeadTrackerAvailable() { |
| try { |
| return mAm.getService().isHeadTrackerAvailable(); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| return false; |
| } |
| |
| /** |
| * Adds a listener to be notified of changes to the availability of a head tracker. |
| * @param executor the {@code Executor} handling the callback |
| * @param listener the listener to receive availability updates |
| * @see #removeOnHeadTrackerAvailableListener(OnHeadTrackerAvailableListener) |
| */ |
| public void addOnHeadTrackerAvailableListener(@NonNull @CallbackExecutor Executor executor, |
| @NonNull OnHeadTrackerAvailableListener listener) { |
| mHeadTrackerListenerMgr.addListener(executor, listener, |
| "addOnHeadTrackerAvailableListener", |
| () -> new SpatializerHeadTrackerAvailableDispatcherStub()); |
| } |
| |
| /** |
| * Removes a previously registered listener for the availability of a head tracker. |
| * @param listener the listener previously registered with |
| * {@link #addOnHeadTrackerAvailableListener(Executor, OnHeadTrackerAvailableListener)} |
| */ |
| public void removeOnHeadTrackerAvailableListener( |
| @NonNull OnHeadTrackerAvailableListener listener) { |
| mHeadTrackerListenerMgr.removeListener(listener, "removeOnHeadTrackerAvailableListener"); |
| } |
| |
| /** @hide */ |
| @IntDef(flag = false, value = { |
| SPATIALIZER_IMMERSIVE_LEVEL_OTHER, |
| SPATIALIZER_IMMERSIVE_LEVEL_NONE, |
| SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface ImmersiveAudioLevel {}; |
| |
| /** |
| * Constant indicating the {@code Spatializer} on this device supports a spatialization |
| * mode that differs from the ones available at this SDK level. |
| * @see #getImmersiveAudioLevel() |
| */ |
| public static final int SPATIALIZER_IMMERSIVE_LEVEL_OTHER = -1; |
| |
| /** |
| * Constant indicating there are no spatialization capabilities supported on this device. |
| * @see #getImmersiveAudioLevel() |
| */ |
| public static final int SPATIALIZER_IMMERSIVE_LEVEL_NONE = 0; |
| |
| /** |
| * Constant indicating the {@code Spatializer} on this device supports multichannel |
| * spatialization. |
| * @see #getImmersiveAudioLevel() |
| */ |
| public static final int SPATIALIZER_IMMERSIVE_LEVEL_MULTICHANNEL = 1; |
| |
| /** |
| * @hide |
| * Constant indicating the {@code Spatializer} on this device supports the spatialization of |
| * multichannel bed plus objects. |
| * @see #getImmersiveAudioLevel() |
| */ |
| public static final int SPATIALIZER_IMMERSIVE_LEVEL_MCHAN_BED_PLUS_OBJECTS = 2; |
| |
| /** @hide */ |
| @IntDef(flag = false, value = { |
| HEAD_TRACKING_MODE_UNSUPPORTED, |
| HEAD_TRACKING_MODE_DISABLED, |
| HEAD_TRACKING_MODE_RELATIVE_WORLD, |
| HEAD_TRACKING_MODE_RELATIVE_DEVICE, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface HeadTrackingMode {}; |
| |
| /** @hide */ |
| @IntDef(flag = false, value = { |
| HEAD_TRACKING_MODE_DISABLED, |
| HEAD_TRACKING_MODE_RELATIVE_WORLD, |
| HEAD_TRACKING_MODE_RELATIVE_DEVICE, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface HeadTrackingModeSet {}; |
| |
| /** @hide */ |
| @IntDef(flag = false, value = { |
| HEAD_TRACKING_MODE_RELATIVE_WORLD, |
| HEAD_TRACKING_MODE_RELATIVE_DEVICE, |
| }) |
| @Retention(RetentionPolicy.SOURCE) |
| public @interface HeadTrackingModeSupported {}; |
| |
| /** |
| * @hide |
| * Constant indicating head tracking is not supported by this {@code Spatializer} |
| * @see #getHeadTrackingMode() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public static final int HEAD_TRACKING_MODE_UNSUPPORTED = -2; |
| |
| /** |
| * @hide |
| * Constant indicating head tracking is disabled on this {@code Spatializer} |
| * @see #getHeadTrackingMode() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public static final int HEAD_TRACKING_MODE_DISABLED = -1; |
| |
| /** |
| * @hide |
| * Constant indicating head tracking is in a mode whose behavior is unknown. This is not an |
| * error state but represents a customized behavior not defined by this API. |
| * @see #getHeadTrackingMode() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public static final int HEAD_TRACKING_MODE_OTHER = 0; |
| |
| /** |
| * @hide |
| * Constant indicating head tracking is tracking the user's position / orientation relative to |
| * the world around them |
| * @see #getHeadTrackingMode() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public static final int HEAD_TRACKING_MODE_RELATIVE_WORLD = 1; |
| |
| /** |
| * @hide |
| * Constant indicating head tracking is tracking the user's position / orientation relative to |
| * the device |
| * @see #getHeadTrackingMode() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public static final int HEAD_TRACKING_MODE_RELATIVE_DEVICE = 2; |
| |
| /** |
| * @hide |
| * Head tracking mode to string conversion |
| * @param mode a valid head tracking mode |
| * @return a string containing the matching constant name |
| */ |
| public static final String headtrackingModeToString(int mode) { |
| switch(mode) { |
| case HEAD_TRACKING_MODE_UNSUPPORTED: |
| return "HEAD_TRACKING_MODE_UNSUPPORTED"; |
| case HEAD_TRACKING_MODE_DISABLED: |
| return "HEAD_TRACKING_MODE_DISABLED"; |
| case HEAD_TRACKING_MODE_OTHER: |
| return "HEAD_TRACKING_MODE_OTHER"; |
| case HEAD_TRACKING_MODE_RELATIVE_WORLD: |
| return "HEAD_TRACKING_MODE_RELATIVE_WORLD"; |
| case HEAD_TRACKING_MODE_RELATIVE_DEVICE: |
| return "HEAD_TRACKING_MODE_RELATIVE_DEVICE"; |
| default: |
| return "head tracking mode unknown " + mode; |
| } |
| } |
| |
| /** |
| * Return the level of support for the spatialization feature on this device. |
| * This level of support is independent of whether the {@code Spatializer} is currently |
| * enabled or available and will not change over time. |
| * @return the level of spatialization support |
| * @see #isEnabled() |
| * @see #isAvailable() |
| */ |
| public @ImmersiveAudioLevel int getImmersiveAudioLevel() { |
| int level = Spatializer.SPATIALIZER_IMMERSIVE_LEVEL_NONE; |
| try { |
| level = mAm.getService().getSpatializerImmersiveAudioLevel(); |
| } catch (Exception e) { /* using NONE */ } |
| return level; |
| } |
| |
| /** |
| * @hide |
| * Enables / disables the spatializer effect. |
| * Changing the enabled state will trigger the public |
| * {@link OnSpatializerStateChangedListener#onSpatializerEnabledChanged(Spatializer, boolean)} |
| * registered listeners. |
| * @param enabled {@code true} for enabling the effect |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setEnabled(boolean enabled) { |
| try { |
| mAm.getService().setSpatializerEnabled(enabled); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling setSpatializerEnabled", e); |
| } |
| } |
| |
| /** |
| * An interface to be notified of changes to the state of the spatializer effect. |
| */ |
| public interface OnSpatializerStateChangedListener { |
| /** |
| * Called when the enabled state of the spatializer effect changes |
| * @param spat the {@code Spatializer} instance whose state changed |
| * @param enabled {@code true} if the spatializer effect is enabled on the device, |
| * {@code false} otherwise |
| * @see #isEnabled() |
| */ |
| void onSpatializerEnabledChanged(@NonNull Spatializer spat, boolean enabled); |
| |
| /** |
| * Called when the availability of the spatializer effect changes |
| * @param spat the {@code Spatializer} instance whose state changed |
| * @param available {@code true} if the spatializer effect is available and capable |
| * of processing the audio for the current configuration of the device, |
| * {@code false} otherwise. |
| * @see #isAvailable() |
| */ |
| void onSpatializerAvailableChanged(@NonNull Spatializer spat, boolean available); |
| } |
| |
| /** |
| * @hide |
| * An interface to be notified of changes to the head tracking mode, used by the spatializer |
| * effect. |
| * Changes to the mode may come from explicitly setting a different mode |
| * (see {@link #setDesiredHeadTrackingMode(int)}) or a change in system conditions (see |
| * {@link #getHeadTrackingMode()} |
| * @see #addOnHeadTrackingModeChangedListener(Executor, OnHeadTrackingModeChangedListener) |
| * @see #removeOnHeadTrackingModeChangedListener(OnHeadTrackingModeChangedListener) |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| public interface OnHeadTrackingModeChangedListener { |
| /** |
| * Called when the actual head tracking mode of the spatializer changed. |
| * @param spatializer the {@code Spatializer} instance whose head tracking mode is changing |
| * @param mode the new head tracking mode |
| */ |
| void onHeadTrackingModeChanged(@NonNull Spatializer spatializer, |
| @HeadTrackingMode int mode); |
| |
| /** |
| * Called when the desired head tracking mode of the spatializer changed |
| * @param spatializer the {@code Spatializer} instance whose head tracking mode was set |
| * @param mode the newly set head tracking mode |
| */ |
| void onDesiredHeadTrackingModeChanged(@NonNull Spatializer spatializer, |
| @HeadTrackingModeSet int mode); |
| } |
| |
| /** |
| * Interface to be notified of changes to the availability of a head tracker on the audio |
| * device to be used by the spatializer effect. |
| */ |
| public interface OnHeadTrackerAvailableListener { |
| /** |
| * Called when the availability of the head tracker changed. |
| * @param spatializer the {@code Spatializer} instance for which the head tracker |
| * availability was updated |
| * @param available true if the audio device that would output audio processed by |
| * the {@code Spatializer} has a head tracker associated with it, false |
| * otherwise. |
| */ |
| void onHeadTrackerAvailableChanged(@NonNull Spatializer spatializer, |
| boolean available); |
| } |
| |
| /** |
| * @hide |
| * An interface to be notified of changes to the output stream used by the spatializer |
| * effect. |
| * @see #getOutput() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| public interface OnSpatializerOutputChangedListener { |
| /** |
| * Called when the id of the output stream of the spatializer effect changed. |
| * @param spatializer the {@code Spatializer} instance whose output is updated |
| * @param output the id of the output stream, or 0 when there is no spatializer output |
| */ |
| void onSpatializerOutputChanged(@NonNull Spatializer spatializer, |
| @IntRange(from = 0) int output); |
| } |
| |
| /** |
| * @hide |
| * An interface to be notified of updates to the head to soundstage pose, as represented by the |
| * current head tracking mode. |
| * @see #setOnHeadToSoundstagePoseUpdatedListener(Executor, OnHeadToSoundstagePoseUpdatedListener) |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| public interface OnHeadToSoundstagePoseUpdatedListener { |
| /** |
| * Called when the head to soundstage transform is updated |
| * @param spatializer the {@code Spatializer} instance affected by the pose update |
| * @param pose the new pose data representing the transform between the frame |
| * of reference for the current head tracking mode (see |
| * {@link #getHeadTrackingMode()}) and the device being tracked (for |
| * instance a pair of headphones with a head tracker).<br> |
| * The head pose data is represented as an array of six float values, where |
| * the first three values are the translation vector, and the next three |
| * are the rotation vector. |
| */ |
| void onHeadToSoundstagePoseUpdated(@NonNull Spatializer spatializer, |
| @NonNull float[] pose); |
| } |
| |
| /** |
| * Returns whether audio of the given {@link AudioFormat}, played with the given |
| * {@link AudioAttributes} can be spatialized. |
| * Note that the result reflects the capabilities of the device and may change when |
| * audio accessories are connected/disconnected (e.g. wired headphones plugged in or not). |
| * The result is independent from whether spatialization processing is enabled or not. |
| * @param attributes the {@code AudioAttributes} of the content as used for playback |
| * @param format the {@code AudioFormat} of the content as used for playback |
| * @return {@code true} if the device is capable of spatializing the combination of audio format |
| * and attributes, {@code false} otherwise. |
| */ |
| public boolean canBeSpatialized( |
| @NonNull AudioAttributes attributes, @NonNull AudioFormat format) { |
| try { |
| return mAm.getService().canBeSpatialized( |
| Objects.requireNonNull(attributes), Objects.requireNonNull(format)); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error querying canBeSpatialized for attr:" + attributes |
| + " format:" + format + " returning false", e); |
| return false; |
| } |
| } |
| |
| /** |
| * Adds a listener to be notified of changes to the enabled state of the |
| * {@code Spatializer}. |
| * @param executor the {@code Executor} handling the callback |
| * @param listener the listener to receive enabled state updates |
| * @see #isEnabled() |
| */ |
| public void addOnSpatializerStateChangedListener( |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull OnSpatializerStateChangedListener listener) { |
| mStateListenerMgr.addListener(executor, listener, "addOnSpatializerStateChangedListener", |
| () -> new SpatializerInfoDispatcherStub()); |
| } |
| |
| /** |
| * Removes a previously added listener for changes to the enabled state of the |
| * {@code Spatializer}. |
| * @param listener the listener to receive enabled state updates |
| * @see #isEnabled() |
| */ |
| public void removeOnSpatializerStateChangedListener( |
| @NonNull OnSpatializerStateChangedListener listener) { |
| mStateListenerMgr.removeListener(listener, "removeOnSpatializerStateChangedListener"); |
| } |
| |
| /** |
| * @hide |
| * Returns the list of playback devices that are compatible with the playback of multichannel |
| * audio through virtualization |
| * @return a list of devices. An empty list indicates virtualization is not supported. |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public @NonNull List<AudioDeviceAttributes> getCompatibleAudioDevices() { |
| try { |
| return mAm.getService().getSpatializerCompatibleAudioDevices(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error querying getSpatializerCompatibleAudioDevices(), " |
| + " returning empty list", e); |
| return new ArrayList<AudioDeviceAttributes>(0); |
| } |
| } |
| |
| /** |
| * @hide |
| * Adds a playback device to the list of devices compatible with the playback of multichannel |
| * audio through spatialization. |
| * @see #getCompatibleAudioDevices() |
| * @param ada the audio device compatible with spatialization |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void addCompatibleAudioDevice(@NonNull AudioDeviceAttributes ada) { |
| try { |
| mAm.getService().addSpatializerCompatibleAudioDevice(Objects.requireNonNull(ada)); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling addSpatializerCompatibleAudioDevice(), ", e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Remove a playback device from the list of devices compatible with the playback of |
| * multichannel audio through spatialization. |
| * @see #getCompatibleAudioDevices() |
| * @param ada the audio device incompatible with spatialization |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void removeCompatibleAudioDevice(@NonNull AudioDeviceAttributes ada) { |
| try { |
| mAm.getService().removeSpatializerCompatibleAudioDevice(Objects.requireNonNull(ada)); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling removeSpatializerCompatibleAudioDevice(), ", e); |
| } |
| } |
| |
| /** |
| * manages the OnSpatializerStateChangedListener listeners and the |
| * SpatializerInfoDispatcherStub |
| */ |
| private final CallbackUtil.LazyListenerManager<OnSpatializerStateChangedListener> |
| mStateListenerMgr = new CallbackUtil.LazyListenerManager(); |
| |
| private final class SpatializerInfoDispatcherStub extends ISpatializerCallback.Stub |
| implements CallbackUtil.DispatcherStub { |
| @Override |
| public void register(boolean register) { |
| try { |
| if (register) { |
| mAm.getService().registerSpatializerCallback(this); |
| } else { |
| mAm.getService().unregisterSpatializerCallback(this); |
| } |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| } |
| |
| @Override |
| @SuppressLint("GuardedBy") // lock applied inside callListeners method |
| public void dispatchSpatializerEnabledChanged(boolean enabled) { |
| mStateListenerMgr.callListeners( |
| (listener) -> listener.onSpatializerEnabledChanged( |
| Spatializer.this, enabled)); |
| } |
| |
| @Override |
| @SuppressLint("GuardedBy") // lock applied inside callListeners method |
| public void dispatchSpatializerAvailableChanged(boolean available) { |
| mStateListenerMgr.callListeners( |
| (listener) -> listener.onSpatializerAvailableChanged( |
| Spatializer.this, available)); |
| } |
| } |
| |
| |
| /** |
| * @hide |
| * Return the current head tracking mode as used by the system. |
| * Note this may differ from the desired head tracking mode. Reasons for the two to differ |
| * include: a head tracking device is not available for the current audio output device, |
| * the transmission conditions between the tracker and device have deteriorated and tracking |
| * has been disabled. |
| * @see #getDesiredHeadTrackingMode() |
| * @return the current head tracking mode |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public @HeadTrackingMode int getHeadTrackingMode() { |
| try { |
| return mAm.getService().getActualHeadTrackingMode(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling getActualHeadTrackingMode", e); |
| return HEAD_TRACKING_MODE_UNSUPPORTED; |
| } |
| |
| } |
| |
| /** |
| * @hide |
| * Return the desired head tracking mode. |
| * Note this may differ from the actual head tracking mode, reflected by |
| * {@link #getHeadTrackingMode()}. |
| * @return the desired head tring mode |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public @HeadTrackingMode int getDesiredHeadTrackingMode() { |
| try { |
| return mAm.getService().getDesiredHeadTrackingMode(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling getDesiredHeadTrackingMode", e); |
| return HEAD_TRACKING_MODE_UNSUPPORTED; |
| } |
| } |
| |
| /** |
| * @hide |
| * Returns the list of supported head tracking modes. |
| * @return the list of modes that can be used in {@link #setDesiredHeadTrackingMode(int)} to |
| * enable head tracking. The list will be empty if {@link #getHeadTrackingMode()} |
| * is {@link #HEAD_TRACKING_MODE_UNSUPPORTED}. Values can be |
| * {@link #HEAD_TRACKING_MODE_OTHER}, |
| * {@link #HEAD_TRACKING_MODE_RELATIVE_WORLD} or |
| * {@link #HEAD_TRACKING_MODE_RELATIVE_DEVICE} |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public @NonNull List<Integer> getSupportedHeadTrackingModes() { |
| try { |
| final int[] modes = mAm.getService().getSupportedHeadTrackingModes(); |
| final ArrayList<Integer> list = new ArrayList<>(0); |
| for (int mode : modes) { |
| list.add(mode); |
| } |
| return list; |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling getSupportedHeadTrackModes", e); |
| return new ArrayList(0); |
| } |
| } |
| |
| /** |
| * @hide |
| * Sets the desired head tracking mode. |
| * Note a set desired mode may differ from the actual head tracking mode. |
| * @see #getHeadTrackingMode() |
| * @param mode the desired head tracking mode, one of the values returned by |
| * {@link #getSupportedHeadTrackModes()}, or {@link #HEAD_TRACKING_MODE_DISABLED} to |
| * disable head tracking. |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setDesiredHeadTrackingMode(@HeadTrackingModeSet int mode) { |
| try { |
| mAm.getService().setDesiredHeadTrackingMode(mode); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling setDesiredHeadTrackingMode to " + mode, e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Recenters the head tracking at the current position / orientation. |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void recenterHeadTracker() { |
| try { |
| mAm.getService().recenterHeadTracker(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling recenterHeadTracker", e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Adds a listener to be notified of changes to the head tracking mode of the |
| * {@code Spatializer} |
| * @param executor the {@code Executor} handling the callbacks |
| * @param listener the listener to register |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void addOnHeadTrackingModeChangedListener( |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull OnHeadTrackingModeChangedListener listener) { |
| mHeadTrackingListenerMgr.addListener(executor, listener, |
| "addOnHeadTrackingModeChangedListener", |
| () -> new SpatializerHeadTrackingDispatcherStub()); |
| } |
| |
| /** |
| * @hide |
| * Removes a previously added listener for changes to the head tracking mode of the |
| * {@code Spatializer}. |
| * @param listener the listener to unregister |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void removeOnHeadTrackingModeChangedListener( |
| @NonNull OnHeadTrackingModeChangedListener listener) { |
| mHeadTrackingListenerMgr.removeListener(listener, |
| "removeOnHeadTrackingModeChangedListener"); |
| } |
| |
| /** |
| * @hide |
| * Set the listener to receive head to soundstage pose updates. |
| * @param executor the {@code Executor} handling the callbacks |
| * @param listener the listener to register |
| * @see #clearOnHeadToSoundstagePoseUpdatedListener() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setOnHeadToSoundstagePoseUpdatedListener( |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull OnHeadToSoundstagePoseUpdatedListener listener) { |
| Objects.requireNonNull(executor); |
| Objects.requireNonNull(listener); |
| synchronized (mPoseListenerLock) { |
| if (mPoseListener != null) { |
| throw new IllegalStateException("Trying to overwrite existing listener"); |
| } |
| mPoseListener = |
| new ListenerInfo<OnHeadToSoundstagePoseUpdatedListener>(listener, executor); |
| mPoseDispatcher = new SpatializerPoseDispatcherStub(); |
| try { |
| mAm.getService().registerHeadToSoundstagePoseCallback(mPoseDispatcher); |
| } catch (RemoteException e) { |
| mPoseListener = null; |
| mPoseDispatcher = null; |
| } |
| } |
| } |
| |
| /** |
| * @hide |
| * Clears the listener for head to soundstage pose updates |
| * @see #setOnHeadToSoundstagePoseUpdatedListener(Executor, OnHeadToSoundstagePoseUpdatedListener) |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void clearOnHeadToSoundstagePoseUpdatedListener() { |
| synchronized (mPoseListenerLock) { |
| if (mPoseDispatcher == null) { |
| throw (new IllegalStateException("No listener to clear")); |
| } |
| try { |
| mAm.getService().unregisterHeadToSoundstagePoseCallback(mPoseDispatcher); |
| } catch (RemoteException e) { } |
| mPoseListener = null; |
| mPoseDispatcher = null; |
| } |
| } |
| |
| /** |
| * @hide |
| * Sets an additional transform over the soundstage. |
| * The transform represents the pose of the soundstage, relative |
| * to either the device (in {@link #HEAD_TRACKING_MODE_RELATIVE_DEVICE} mode), the world (in |
| * {@link #HEAD_TRACKING_MODE_RELATIVE_WORLD}) or the listener’s head (in |
| * {@link #HEAD_TRACKING_MODE_DISABLED} mode). |
| * @param transform an array of 6 float values, the first 3 are the translation vector, the |
| * other 3 are the rotation vector. |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setGlobalTransform(@NonNull float[] transform) { |
| if (Objects.requireNonNull(transform).length != 6) { |
| throw new IllegalArgumentException("transform array must be of size 6, was " |
| + transform.length); |
| } |
| try { |
| mAm.getService().setSpatializerGlobalTransform(transform); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling setGlobalTransform", e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Sets a parameter on the platform spatializer effect implementation. |
| * This is to be used for vendor-specific configurations of their effect, keys and values are |
| * not reuseable across implementations. |
| * @param key the parameter to change |
| * @param value an array for the value of the parameter to change |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setEffectParameter(int key, @NonNull byte[] value) { |
| Objects.requireNonNull(value); |
| try { |
| mAm.getService().setSpatializerParameter(key, value); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling setEffectParameter", e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Retrieves a parameter value from the platform spatializer effect implementation. |
| * This is to be used for vendor-specific configurations of their effect, keys and values are |
| * not reuseable across implementations. |
| * @param key the parameter for which the value is queried |
| * @param value a non-empty array to contain the return value. The caller is responsible for |
| * passing an array of size matching the parameter. |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void getEffectParameter(int key, @NonNull byte[] value) { |
| Objects.requireNonNull(value); |
| try { |
| mAm.getService().getSpatializerParameter(key, value); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling getEffectParameter", e); |
| } |
| } |
| |
| /** |
| * @hide |
| * Returns the id of the output stream used for the spatializer effect playback. |
| * This getter or associated listener {@link OnSpatializerOutputChangedListener} can be used for |
| * handling spatializer output-specific configurations (e.g. disabling speaker post-processing |
| * to avoid double-processing of the spatialized path). |
| * @return id of the output stream, or 0 if no spatializer playback is active |
| * @see #setOnSpatializerOutputChangedListener(Executor, OnSpatializerOutputChangedListener) |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public @IntRange(from = 0) int getOutput() { |
| try { |
| return mAm.getService().getSpatializerOutput(); |
| } catch (RemoteException e) { |
| Log.e(TAG, "Error calling getSpatializerOutput", e); |
| return 0; |
| } |
| } |
| |
| /** |
| * @hide |
| * Sets the listener to receive spatializer effect output updates |
| * @param executor the {@code Executor} handling the callbacks |
| * @param listener the listener to register |
| * @see #clearOnSpatializerOutputChangedListener() |
| * @see #getOutput() |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void setOnSpatializerOutputChangedListener( |
| @NonNull @CallbackExecutor Executor executor, |
| @NonNull OnSpatializerOutputChangedListener listener) { |
| Objects.requireNonNull(executor); |
| Objects.requireNonNull(listener); |
| synchronized (mOutputListenerLock) { |
| if (mOutputListener != null) { |
| throw new IllegalStateException("Trying to overwrite existing listener"); |
| } |
| mOutputListener = |
| new ListenerInfo<OnSpatializerOutputChangedListener>(listener, executor); |
| mOutputDispatcher = new SpatializerOutputDispatcherStub(); |
| try { |
| mAm.getService().registerSpatializerOutputCallback(mOutputDispatcher); |
| // immediately report the current output |
| mOutputDispatcher.dispatchSpatializerOutputChanged(getOutput()); |
| } catch (RemoteException e) { |
| mOutputListener = null; |
| mOutputDispatcher = null; |
| } |
| } |
| } |
| |
| /** |
| * @hide |
| * Clears the listener for spatializer effect output updates |
| * @see #setOnSpatializerOutputChangedListener(Executor, OnSpatializerOutputChangedListener) |
| */ |
| @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS) |
| @RequiresPermission(android.Manifest.permission.MODIFY_DEFAULT_AUDIO_EFFECTS) |
| public void clearOnSpatializerOutputChangedListener() { |
| synchronized (mOutputListenerLock) { |
| if (mOutputDispatcher == null) { |
| throw (new IllegalStateException("No listener to clear")); |
| } |
| try { |
| mAm.getService().unregisterSpatializerOutputCallback(mOutputDispatcher); |
| } catch (RemoteException e) { } |
| mOutputListener = null; |
| mOutputDispatcher = null; |
| } |
| } |
| |
| //----------------------------------------------------------------------------- |
| // head tracking callback management and stub |
| |
| /** |
| * manages the OnHeadTrackingModeChangedListener listeners and the |
| * SpatializerHeadTrackingDispatcherStub |
| */ |
| private final CallbackUtil.LazyListenerManager<OnHeadTrackingModeChangedListener> |
| mHeadTrackingListenerMgr = new CallbackUtil.LazyListenerManager(); |
| |
| private final class SpatializerHeadTrackingDispatcherStub |
| extends ISpatializerHeadTrackingModeCallback.Stub |
| implements CallbackUtil.DispatcherStub { |
| @Override |
| public void register(boolean register) { |
| try { |
| if (register) { |
| mAm.getService().registerSpatializerHeadTrackingCallback(this); |
| } else { |
| mAm.getService().unregisterSpatializerHeadTrackingCallback(this); |
| } |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| } |
| |
| @Override |
| @SuppressLint("GuardedBy") // lock applied inside callListeners method |
| public void dispatchSpatializerActualHeadTrackingModeChanged(int mode) { |
| mHeadTrackingListenerMgr.callListeners( |
| (listener) -> listener.onHeadTrackingModeChanged(Spatializer.this, mode)); |
| } |
| |
| @Override |
| @SuppressLint("GuardedBy") // lock applied inside callListeners method |
| public void dispatchSpatializerDesiredHeadTrackingModeChanged(int mode) { |
| mHeadTrackingListenerMgr.callListeners( |
| (listener) -> listener.onDesiredHeadTrackingModeChanged( |
| Spatializer.this, mode)); |
| } |
| } |
| |
| //----------------------------------------------------------------------------- |
| // head tracker availability callback management and stub |
| /** |
| * manages the OnHeadTrackerAvailableListener listeners and the |
| * SpatializerHeadTrackerAvailableDispatcherStub |
| */ |
| private final CallbackUtil.LazyListenerManager<OnHeadTrackerAvailableListener> |
| mHeadTrackerListenerMgr = new CallbackUtil.LazyListenerManager(); |
| |
| private final class SpatializerHeadTrackerAvailableDispatcherStub |
| extends ISpatializerHeadTrackerAvailableCallback.Stub |
| implements CallbackUtil.DispatcherStub { |
| @Override |
| public void register(boolean register) { |
| try { |
| mAm.getService().registerSpatializerHeadTrackerAvailableCallback(this, register); |
| } catch (RemoteException e) { |
| e.rethrowFromSystemServer(); |
| } |
| } |
| |
| @Override |
| @SuppressLint("GuardedBy") // lock applied inside callListeners method |
| public void dispatchSpatializerHeadTrackerAvailable(boolean available) { |
| mHeadTrackerListenerMgr.callListeners( |
| (listener) -> listener.onHeadTrackerAvailableChanged( |
| Spatializer.this, available)); |
| } |
| } |
| |
| //----------------------------------------------------------------------------- |
| // head pose callback management and stub |
| private final Object mPoseListenerLock = new Object(); |
| /** |
| * Listener for head to soundstage updates |
| */ |
| @GuardedBy("mPoseListenerLock") |
| private @Nullable ListenerInfo<OnHeadToSoundstagePoseUpdatedListener> mPoseListener; |
| @GuardedBy("mPoseListenerLock") |
| private @Nullable SpatializerPoseDispatcherStub mPoseDispatcher; |
| |
| private final class SpatializerPoseDispatcherStub |
| extends ISpatializerHeadToSoundStagePoseCallback.Stub { |
| |
| @Override |
| public void dispatchPoseChanged(float[] pose) { |
| // make a copy of ref to listener so callback is not executed under lock |
| final ListenerInfo<OnHeadToSoundstagePoseUpdatedListener> listener; |
| synchronized (mPoseListenerLock) { |
| listener = mPoseListener; |
| } |
| if (listener == null) { |
| return; |
| } |
| try (SafeCloseable ignored = ClearCallingIdentityContext.create()) { |
| listener.mExecutor.execute(() -> listener.mListener |
| .onHeadToSoundstagePoseUpdated(Spatializer.this, pose)); |
| } |
| } |
| } |
| |
| //----------------------------------------------------------------------------- |
| // output callback management and stub |
| private final Object mOutputListenerLock = new Object(); |
| /** |
| * Listener for output updates |
| */ |
| @GuardedBy("mOutputListenerLock") |
| private @Nullable ListenerInfo<OnSpatializerOutputChangedListener> mOutputListener; |
| @GuardedBy("mOutputListenerLock") |
| private @Nullable SpatializerOutputDispatcherStub mOutputDispatcher; |
| |
| private final class SpatializerOutputDispatcherStub |
| extends ISpatializerOutputCallback.Stub { |
| |
| @Override |
| public void dispatchSpatializerOutputChanged(int output) { |
| // make a copy of ref to listener so callback is not executed under lock |
| final ListenerInfo<OnSpatializerOutputChangedListener> listener; |
| synchronized (mOutputListenerLock) { |
| listener = mOutputListener; |
| } |
| if (listener == null) { |
| return; |
| } |
| try (SafeCloseable ignored = ClearCallingIdentityContext.create()) { |
| listener.mExecutor.execute(() -> listener.mListener |
| .onSpatializerOutputChanged(Spatializer.this, output)); |
| } |
| } |
| } |
| } |
