File	Doc	Category	Size	Date	Package
Virtualizer.java	API Doc	Android 5.1 API	28848	Thu Mar 12 22:22:30 GMT 2015	android.media.audiofx

Virtualizer

• java.lang.Object
  • android.media.audiofx.AudioEffect

Fields Summary
private static final String	TAG
private static final boolean	DEBUG
public static final int	PARAM_STRENGTH_SUPPORTED Is strength parameter supported by virtualizer engine. Parameter ID for getParameter().
public static final int	PARAM_STRENGTH Virtualizer effect strength. Parameter ID for {@link android.media.audiofx.Virtualizer.OnParameterChangeListener}
public static final int	PARAM_VIRTUAL_SPEAKER_ANGLES
public static final int	PARAM_FORCE_VIRTUALIZATION_MODE
public static final int	PARAM_VIRTUALIZATION_MODE
private boolean	mStrengthSupported Indicates if strength parameter is supported by the virtualizer engine
private OnParameterChangeListener	mParamListener Registered listener for parameter changes.
private BaseParameterListener	mBaseParamListener Listener used internally to to receive raw parameter change event from AudioEffect super class
private final Object	mParamListenerLock Lock for access to mParamListener
public static final int	VIRTUALIZATION_MODE_OFF A virtualization mode indicating virtualization processing is not active. See {@link #getVirtualizationMode()} as one of the possible return value.
public static final int	VIRTUALIZATION_MODE_AUTO A virtualization mode used to indicate the virtualizer effect must stop forcing the processing to a particular mode in {@link #forceVirtualizationMode(int)}.
public static final int	VIRTUALIZATION_MODE_BINAURAL A virtualization mode typically used over headphones. Binaural virtualization describes an audio processing configuration for virtualization where the left and right channels are respectively reaching the left and right ear of the user, without also feeding the opposite ear (as is the case when listening over speakers). Such a mode is therefore meant to be used when audio is playing over stereo wired headphones or headsets, but also stereo headphones through a wireless A2DP Bluetooth link. See {@link #canVirtualize(int, int)} to verify this mode is supported by this Virtualizer.
public static final int	VIRTUALIZATION_MODE_TRANSAURAL A virtualization mode typically used over speakers. Transaural virtualization describes an audio processing configuration that differs from binaural (as described in {@link #VIRTUALIZATION_MODE_BINAURAL} in that cross-talk is present, i.e. audio played from the left channel also reaches the right ear of the user, and vice-versa. When supported, such a mode is therefore meant to be used when audio is playing over the built-in stereo speakers of a device, if they are featured. See {@link #canVirtualize(int, int)} to verify this mode is supported by this Virtualizer.

Constructors Summary

public Virtualizer(int priority, int audioSession) Class constructor. param priority the priority level requested by the application for controlling the Virtualizer engine. As the same engine can be shared by several applications, this parameter indicates how much the requesting application needs control of effect parameters. The normal priority is 0, above normal is a positive number, below normal a negative number. param audioSession system wide unique audio session identifier. The Virtualizer will be attached to the MediaPlayer or AudioTrack in the same audio session. throws java.lang.IllegalStateException throws java.lang.IllegalArgumentException throws java.lang.UnsupportedOperationException throws java.lang.RuntimeException super(EFFECT_TYPE_VIRTUALIZER, EFFECT_TYPE_NULL, priority, audioSession); if (audioSession == 0) { Log.w(TAG, "WARNING: attaching a Virtualizer to global output mix is deprecated!"); } int[] value = new int[1]; checkStatus(getParameter(PARAM_STRENGTH_SUPPORTED, value)); mStrengthSupported = (value[0] != 0);

Methods Summary
public boolean	canVirtualize(int inputChannelMask, int virtualizationMode) Checks if the combination of a channel mask and virtualization mode is supported by this virtualizer. Some virtualizer implementations may only support binaural processing (i.e. only support headphone output, see {@link #VIRTUALIZATION_MODE_BINAURAL}), some may support transaural processing (i.e. for speaker output, see {@link #VIRTUALIZATION_MODE_TRANSAURAL}) for the built-in speakers. Use this method to query the virtualizer implementation capabilities. param inputChannelMask the channel mask of the content to virtualize. param virtualizationMode the mode for which virtualization processing is to be performed, one of {@link #VIRTUALIZATION_MODE_BINAURAL}, {@link #VIRTUALIZATION_MODE_TRANSAURAL}. return true if the combination of channel mask and virtualization mode is supported, false otherwise. An indication that a certain channel mask is not supported doesn't necessarily mean you cannot play content with that channel mask, it more likely implies the content will be downmixed before being virtualized. For instance a virtualizer that only supports a mask such as {@link AudioFormat#CHANNEL_OUT_STEREO} will still be able to process content with a mask of {@link AudioFormat#CHANNEL_OUT_5POINT1}, but will downmix the content to stereo first, and then will virtualize, as opposed to virtualizing each channel individually. throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException return getAnglesInt(inputChannelMask, getDeviceForModeQuery(virtualizationMode), null);
private static int	deviceToMode(int deviceType) switch (deviceType) { case AudioDevice.TYPE_WIRED_HEADSET: case AudioDevice.TYPE_WIRED_HEADPHONES: case AudioDevice.TYPE_BLUETOOTH_SCO: case AudioDevice.TYPE_BUILTIN_EARPIECE: return VIRTUALIZATION_MODE_BINAURAL; case AudioDevice.TYPE_BUILTIN_SPEAKER: case AudioDevice.TYPE_LINE_ANALOG: case AudioDevice.TYPE_LINE_DIGITAL: case AudioDevice.TYPE_BLUETOOTH_A2DP: case AudioDevice.TYPE_HDMI: case AudioDevice.TYPE_HDMI_ARC: case AudioDevice.TYPE_USB_DEVICE: case AudioDevice.TYPE_USB_ACCESSORY: case AudioDevice.TYPE_DOCK: case AudioDevice.TYPE_FM: case AudioDevice.TYPE_AUX_LINE: return VIRTUALIZATION_MODE_TRANSAURAL; case AudioDevice.TYPE_UNKNOWN: default: return VIRTUALIZATION_MODE_OFF; }
public boolean	forceVirtualizationMode(int virtualizationMode) Forces the virtualizer effect to use the given processing mode. The effect must be enabled for the forced mode to be applied. param virtualizationMode one of {@link #VIRTUALIZATION_MODE_BINAURAL}, {@link #VIRTUALIZATION_MODE_TRANSAURAL} to force a particular processing mode, or {@value #VIRTUALIZATION_MODE_AUTO} to stop forcing a mode. return true if the processing mode is supported, and it is successfully set, or forcing was successfully disabled, false otherwise. throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException // convert Java device type to internal representation int deviceType = getDeviceForModeForce(virtualizationMode); int internalDevice = AudioDevice.convertDeviceTypeToInternalDevice(deviceType); int status = setParameter(PARAM_FORCE_VIRTUALIZATION_MODE, internalDevice); if (status >= 0) { return true; } else if (status == AudioEffect.ERROR_BAD_VALUE) { // a BAD_VALUE return from setParameter indicates the mode can't be forced // don't throw an exception, just return false return false; } else { // something wrong may have happened checkStatus(status); } // unexpected virtualizer behavior Log.e(TAG, "unexpected status code " + status + " after setParameter(PARAM_FORCE_VIRTUALIZATION_MODE)"); return false;
private boolean	getAnglesInt(int inputChannelMask, int deviceType, int[] angles) Checks if a configuration is supported, and query the virtual speaker angles. param inputChannelMask param deviceType param angles if non-null: array in which the angles will be written. If null, no angles are returned return true if the combination of channel mask and output device type is supported, false otherwise throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException // parameter check if (inputChannelMask == AudioFormat.CHANNEL_INVALID) { throw (new IllegalArgumentException( "Virtualizer: illegal CHANNEL_INVALID channel mask")); } int channelMask = inputChannelMask == AudioFormat.CHANNEL_OUT_DEFAULT ? AudioFormat.CHANNEL_OUT_STEREO : inputChannelMask; int nbChannels = AudioFormat.channelCountFromOutChannelMask(channelMask); if ((angles != null) && (angles.length < (nbChannels * 3))) { Log.e(TAG, "Size of array for angles cannot accomodate number of channels in mask (" + nbChannels + ")"); throw (new IllegalArgumentException( "Virtualizer: array for channel / angle pairs is too small: is " + angles.length + ", should be " + (nbChannels * 3))); } ByteBuffer paramsConverter = ByteBuffer.allocate(3 /* param + mask + device*/ * 4); paramsConverter.order(ByteOrder.nativeOrder()); paramsConverter.putInt(PARAM_VIRTUAL_SPEAKER_ANGLES); // convert channel mask to internal native representation paramsConverter.putInt(AudioFormat.convertChannelOutMaskToNativeMask(channelMask)); // convert Java device type to internal representation paramsConverter.putInt(AudioDevice.convertDeviceTypeToInternalDevice(deviceType)); // allocate an array to store the results byte[] result = new byte[nbChannels * 4/*int to byte*/ * 3/*for mask, azimuth, elevation*/]; // call into the effect framework int status = getParameter(paramsConverter.array(), result); if (DEBUG) { Log.v(TAG, "getAngles(0x" + Integer.toHexString(inputChannelMask) + ", 0x" + Integer.toHexString(deviceType) + ") returns " + status); } if (status >= 0) { if (angles != null) { // convert and copy the results ByteBuffer resultConverter = ByteBuffer.wrap(result); resultConverter.order(ByteOrder.nativeOrder()); for (int i = 0 ; i < nbChannels ; i++) { // write the channel mask angles[3 * i] = AudioFormat.convertNativeChannelMaskToOutMask( resultConverter.getInt((i * 4 * 3))); // write the azimuth angles[3 * i + 1] = resultConverter.getInt(i * 4 * 3 + 4); // write the elevation angles[3 * i + 2] = resultConverter.getInt(i * 4 * 3 + 8); if (DEBUG) { Log.v(TAG, "channel 0x" + Integer.toHexString(angles[3*i]).toUpperCase() + " at az=" + angles[3*i+1] + "deg" + " elev=" + angles[3*i+2] + "deg"); } } } return true; } else if (status == AudioEffect.ERROR_BAD_VALUE) { // a BAD_VALUE return from getParameter indicates the configuration is not supported // don't throw an exception, just return false return false; } else { // something wrong may have happened checkStatus(status); } // unexpected virtualizer behavior Log.e(TAG, "unexpected status code " + status + " after getParameter(PARAM_VIRTUAL_SPEAKER_ANGLES)"); return false;
private static int	getDeviceForModeForce(int virtualizationMode) if (virtualizationMode == VIRTUALIZATION_MODE_AUTO) { return AudioDevice.TYPE_UNKNOWN; } else { return getDeviceForModeQuery(virtualizationMode); }
private static int	getDeviceForModeQuery(int virtualizationMode) switch (virtualizationMode) { case VIRTUALIZATION_MODE_BINAURAL: return AudioDevice.TYPE_WIRED_HEADPHONES; case VIRTUALIZATION_MODE_TRANSAURAL: return AudioDevice.TYPE_BUILTIN_SPEAKER; default: throw (new IllegalArgumentException( "Virtualizer: illegal virtualization mode " + virtualizationMode)); }
public android.media.audiofx.Virtualizer$Settings	getProperties() Gets the virtualizer properties. This method is useful when a snapshot of current virtualizer settings must be saved by the application. return a Virtualizer.Settings object containing all current parameters values throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException Settings settings = new Settings(); short[] value = new short[1]; checkStatus(getParameter(PARAM_STRENGTH, value)); settings.strength = value[0]; return settings;
public short	getRoundedStrength() Gets the current strength of the effect. return the strength of the effect. The valid range for strength is [0, 1000], where 0 per mille designates the mildest effect and 1000 per mille the strongest throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException short[] value = new short[1]; checkStatus(getParameter(PARAM_STRENGTH, value)); return value[0];
public boolean	getSpeakerAngles(int inputChannelMask, int virtualizationMode, int[] angles) Queries the virtual speaker angles (azimuth and elevation) for a combination of a channel mask and virtualization mode. If the virtualization configuration (mask and mode) is supported (see {@link #canVirtualize(int, int)}, the array angles will contain upon return the definition of each virtual speaker and its azimuth and elevation angles relative to the listener. Note that in some virtualizer implementations, the angles may be strength-dependent. param inputChannelMask the channel mask of the content to virtualize. param virtualizationMode the mode for which virtualization processing is to be performed, one of {@link #VIRTUALIZATION_MODE_BINAURAL}, {@link #VIRTUALIZATION_MODE_TRANSAURAL}. param angles a non-null array whose length is 3 times the number of channels in the channel mask. If the method indicates the configuration is supported, the array will contain upon return triplets of values: for each channel i among the channels of the mask: the element at index 3*i in the array contains the speaker identification (e.g. {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT}), the element at index 3*i+1 contains its corresponding azimuth angle expressed in degrees, where 0 is the direction the listener faces, 180 is behind the listener, and -90 is to her/his left, the element at index 3*i+2 contains its corresponding elevation angle where +90 is directly above the listener, 0 is the horizontal plane, and -90 is directly below the listener. return true if the combination of channel mask and virtualization mode is supported, false otherwise. throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException if (angles == null) { throw (new IllegalArgumentException( "Virtualizer: illegal null channel / angle array")); } return getAnglesInt(inputChannelMask, getDeviceForModeQuery(virtualizationMode), angles);
public boolean	getStrengthSupported() Indicates whether setting strength is supported. If this method returns false, only one strength is supported and the setStrength() method always rounds to that value. return true is strength parameter is supported, false otherwise return mStrengthSupported;
public int	getVirtualizationMode() Return the virtualization mode being used, if any. return the virtualization mode being used. If virtualization is not active, the virtualization mode will be {@link #VIRTUALIZATION_MODE_OFF}. Otherwise the value will be {@link #VIRTUALIZATION_MODE_BINAURAL} or {@link #VIRTUALIZATION_MODE_TRANSAURAL}. Virtualization may not be active either because the effect is not enabled or because the current output device is not compatible with this virtualization implementation. throws IllegalStateException throws UnsupportedOperationException int[] value = new int[1]; int status = getParameter(PARAM_VIRTUALIZATION_MODE, value); if (status >= 0) { return deviceToMode(AudioDevice.convertInternalDeviceToDeviceType(value[0])); } else if (status == AudioEffect.ERROR_BAD_VALUE) { return VIRTUALIZATION_MODE_OFF; } else { // something wrong may have happened checkStatus(status); } // unexpected virtualizer behavior Log.e(TAG, "unexpected status code " + status + " after getParameter(PARAM_VIRTUALIZATION_MODE)"); return VIRTUALIZATION_MODE_OFF;
public void	setParameterListener(android.media.audiofx.Virtualizer$OnParameterChangeListener listener) Registers an OnParameterChangeListener interface. param listener OnParameterChangeListener interface registered synchronized (mParamListenerLock) { if (mParamListener == null) { mParamListener = listener; mBaseParamListener = new BaseParameterListener(); super.setParameterListener(mBaseParamListener); } }
public void	setProperties(android.media.audiofx.Virtualizer$Settings settings) Sets the virtualizer properties. This method is useful when virtualizer settings have to be applied from a previous backup. param settings a Virtualizer.Settings object containing the properties to apply throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException checkStatus(setParameter(PARAM_STRENGTH, settings.strength));
public void	setStrength(short strength) Sets the strength of the virtualizer effect. If the implementation does not support per mille accuracy for setting the strength, it is allowed to round the given strength to the nearest supported value. You can use the {@link #getRoundedStrength()} method to query the (possibly rounded) value that was actually set. param strength strength of the effect. The valid range for strength strength is [0, 1000], where 0 per mille designates the mildest effect and 1000 per mille designates the strongest. throws IllegalStateException throws IllegalArgumentException throws UnsupportedOperationException checkStatus(setParameter(PARAM_STRENGTH, strength));