media/audiofx/Virtualizer.java

/*
 * Copyright (C) 2010 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.audiofx;

import android.media.AudioDevice;
import android.media.AudioFormat;
import android.media.audiofx.AudioEffect;
import android.util.Log;

import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.util.StringTokenizer;


/**
 * An audio virtualizer is a general name for an effect to spatialize audio channels. The exact
 * behavior of this effect is dependent on the number of audio input channels and the types and
 * number of audio output channels of the device. For example, in the case of a stereo input and
 * stereo headphone output, a stereo widening effect is used when this effect is turned on.
 * <p>An application creates a Virtualizer object to instantiate and control a virtualizer engine
 * in the audio framework.
 * <p>The methods, parameter types and units exposed by the Virtualizer implementation are directly
 * mapping those defined by the OpenSL ES 1.0.1 Specification (http://www.khronos.org/opensles/)
 * for the SLVirtualizerItf interface. Please refer to this specification for more details.
 * <p>To attach the Virtualizer to a particular AudioTrack or MediaPlayer, specify the audio session
 * ID of this AudioTrack or MediaPlayer when constructing the Virtualizer.
 * <p>NOTE: attaching a Virtualizer to the global audio output mix by use of session 0 is
 * deprecated.
 * <p>See {@link android.media.MediaPlayer#getAudioSessionId()} for details on audio sessions.
 * <p>See {@link android.media.audiofx.AudioEffect} class for more details on controlling
 * audio effects.
 */

public class Virtualizer extends AudioEffect {

    private final static String TAG = "Virtualizer";
    private final static boolean DEBUG = false;

    // These constants must be synchronized with those in
    //        system/media/audio_effects/include/audio_effects/effect_virtualizer.h
    /**
     * Is strength parameter supported by virtualizer engine. Parameter ID for getParameter().
     */
    public static final int PARAM_STRENGTH_SUPPORTED = 0;
    /**
     * Virtualizer effect strength. Parameter ID for
     * {@link android.media.audiofx.Virtualizer.OnParameterChangeListener}
     */
    public static final int PARAM_STRENGTH = 1;
    /**
     * @hide
     * Parameter ID to query the virtual speaker angles for a channel mask / device configuration.
     */
    public static final int PARAM_VIRTUAL_SPEAKER_ANGLES = 2;
    /**
     * @hide
     * Parameter ID to force the virtualization mode to be that of a specific device
     */
    public static final int PARAM_FORCE_VIRTUALIZATION_MODE = 3;
    /**
     * @hide
     * Parameter ID to query the current virtualization mode.
     */
    public static final int PARAM_VIRTUALIZATION_MODE = 4;

    /**
     * Indicates if strength parameter is supported by the virtualizer engine
     */
    private boolean mStrengthSupported = false;

    /**
     * Registered listener for parameter changes.
     */
    private OnParameterChangeListener mParamListener = null;

    /**
     * Listener used internally to to receive raw parameter change event from AudioEffect super class
     */
    private BaseParameterListener mBaseParamListener = null;

    /**
     * Lock for access to mParamListener
     */
    private final Object mParamListenerLock = new Object();

    /**
     * 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
     */
    public Virtualizer(int priority, int audioSession)
    throws IllegalStateException, IllegalArgumentException,
           UnsupportedOperationException, 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);
    }

    /**
     * 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
     */
    public boolean getStrengthSupported() {
       return mStrengthSupported;
    }

    /**
     * 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
     */
    public void setStrength(short strength)
    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        checkStatus(setParameter(PARAM_STRENGTH, strength));
    }

    /**
     * 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
     */
    public short getRoundedStrength()
    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        short[] value = new short[1];
        checkStatus(getParameter(PARAM_STRENGTH, value));
        return value[0];
    }

    /**
     * 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
     */
    private boolean getAnglesInt(int inputChannelMask, int deviceType, int[] angles)
            throws IllegalStateException, IllegalArgumentException, 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;
    }

    /**
     * @hide
     * CANDIDATE FOR PUBLIC API
     * Checks if the combination of a channel mask and device type is supported by this virtualizer.
     * Some virtualizer implementations may only support binaural processing (i.e. only support
     * headphone output), some may support transaural processing (i.e. for speaker output) 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 deviceType the device type for which virtualization processing is to be performed.
     *    Valid values are the device types defined in {@link AudioDevice}.
     * @return true if the combination of channel mask and output device type is supported, false
     *    otherwise.
     *    <br>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
     */
    public boolean canVirtualize(int inputChannelMask, int deviceType)
            throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        return getAnglesInt(inputChannelMask, deviceType, null);
    }

    /**
     * @hide
     * CANDIDATE FOR PUBLIC API
     * Queries the virtual speaker angles (azimuth and elevation) for a combination of a channel
     * mask and device type.
     * If the virtualization configuration (mask and device) 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.
     * <br>Note that in some virtualizer implementations, the angles may be strength-dependent.
     * @param inputChannelMask the channel mask of the content to virtualize.
     * @param deviceType the device type for which virtualization processing is to be performed.
     *    Valid values are the device types defined in {@link AudioDevice}.
     * @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 <code>i</code> among the channels of the mask:
     *    <ul>
     *      <li>the element at index <code>3*i</code> in the array contains the speaker
     *          identification (e.g. {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT}),</li>
     *      <li>the element at index <code>3*i+1</code> 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,</li>
     *      <li>the element at index <code>3*i+2</code> contains its corresponding elevation angle
     *          where +90 is directly above the listener, 0 is the horizontal plane, and -90 is
     *          directly below the listener.</li>
     * @return true if the combination of channel mask and output device type is supported, false
     *    otherwise.
     * @throws IllegalStateException
     * @throws IllegalArgumentException
     * @throws UnsupportedOperationException
     */
    public boolean getSpeakerAngles(int inputChannelMask, int deviceType, int[] angles)
            throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        if (angles == null) {
            throw (new IllegalArgumentException(
                    "Virtualizer: illegal null channel / angle array"));
        }

        return getAnglesInt(inputChannelMask, deviceType, angles);
    }

    /**
     * @hide
     * CANDIDATE FOR PUBLIC API
     * Forces the virtualizer effect to use the processing mode used for the given device type.
     * The effect must be enabled for the forced mode to be applied.
     * @param deviceType one of the device types defined in {@link AudioDevice}.
     *     Use {@link AudioDevice#DEVICE_TYPE_UNKNOWN} to return to the non-forced mode.
     * @return true if the processing mode for the device type is supported, and it is successfully
     *     set, or forcing was successfully disabled with {@link AudioDevice#DEVICE_TYPE_UNKNOWN},
     *     false otherwise.
     * @throws IllegalStateException
     * @throws IllegalArgumentException
     * @throws UnsupportedOperationException
     */
    public boolean forceVirtualizationMode(int deviceType)
            throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        // convert Java device type to internal representation
        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 to that
            // of this device, 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;
    }

    /**
     * @hide
     * CANDIDATE FOR PUBLIC API
     * Return the device type which reflects the virtualization mode being used, if any.
     * @return a device type (as defined in {@link AudioDevice}) which reflects the virtualization
     *     mode being used.
     *     If virtualization is not active, the device type will be
     *     {@link AudioDevice#DEVICE_TYPE_UNKNOWN}. 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.
     */
    public int getVirtualizationMode() {
        int[] value = new int[1];
        int status = getParameter(PARAM_VIRTUALIZATION_MODE, value);
        if (status >= 0) {
            return AudioDevice.convertInternalDeviceToDeviceType(value[0]);
        } else if (status == AudioEffect.ERROR_BAD_VALUE) {
            return AudioDevice.DEVICE_TYPE_UNKNOWN;
        } else {
            // something wrong may have happened
            checkStatus(status);
        }
        // unexpected virtualizer behavior
        Log.e(TAG, "unexpected status code " + status
                + " after getParameter(PARAM_VIRTUALIZATION_MODE)");
        return AudioDevice.DEVICE_TYPE_UNKNOWN;
    }

    /**
     * The OnParameterChangeListener interface defines a method called by the Virtualizer when a
     * parameter value has changed.
     */
    public interface OnParameterChangeListener  {
        /**
         * Method called when a parameter value has changed. The method is called only if the
         * parameter was changed by another application having the control of the same
         * Virtualizer engine.
         * @param effect the Virtualizer on which the interface is registered.
         * @param status status of the set parameter operation.
         * @param param ID of the modified parameter. See {@link #PARAM_STRENGTH} ...
         * @param value the new parameter value.
         */
        void onParameterChange(Virtualizer effect, int status, int param, short value);
    }

    /**
     * Listener used internally to receive unformatted parameter change events from AudioEffect
     * super class.
     */
    private class BaseParameterListener implements AudioEffect.OnParameterChangeListener {
        private BaseParameterListener() {

        }
        public void onParameterChange(AudioEffect effect, int status, byte[] param, byte[] value) {
            OnParameterChangeListener l = null;

            synchronized (mParamListenerLock) {
                if (mParamListener != null) {
                    l = mParamListener;
                }
            }
            if (l != null) {
                int p = -1;
                short v = -1;

                if (param.length == 4) {
                    p = byteArrayToInt(param, 0);
                }
                if (value.length == 2) {
                    v = byteArrayToShort(value, 0);
                }
                if (p != -1 && v != -1) {
                    l.onParameterChange(Virtualizer.this, status, p, v);
                }
            }
        }
    }

    /**
     * Registers an OnParameterChangeListener interface.
     * @param listener OnParameterChangeListener interface registered
     */
    public void setParameterListener(OnParameterChangeListener listener) {
        synchronized (mParamListenerLock) {
            if (mParamListener == null) {
                mParamListener = listener;
                mBaseParamListener = new BaseParameterListener();
                super.setParameterListener(mBaseParamListener);
            }
        }
    }

    /**
     * The Settings class regroups all virtualizer parameters. It is used in
     * conjuntion with getProperties() and setProperties() methods to backup and restore
     * all parameters in a single call.
     */
    public static class Settings {
        public short strength;

        public Settings() {
        }

        /**
         * Settings class constructor from a key=value; pairs formatted string. The string is
         * typically returned by Settings.toString() method.
         * @throws IllegalArgumentException if the string is not correctly formatted.
         */
        public Settings(String settings) {
            StringTokenizer st = new StringTokenizer(settings, "=;");
            int tokens = st.countTokens();
            if (st.countTokens() != 3) {
                throw new IllegalArgumentException("settings: " + settings);
            }
            String key = st.nextToken();
            if (!key.equals("Virtualizer")) {
                throw new IllegalArgumentException(
                        "invalid settings for Virtualizer: " + key);
            }
            try {
                key = st.nextToken();
                if (!key.equals("strength")) {
                    throw new IllegalArgumentException("invalid key name: " + key);
                }
                strength = Short.parseShort(st.nextToken());
             } catch (NumberFormatException nfe) {
                throw new IllegalArgumentException("invalid value for key: " + key);
            }
        }

        @Override
        public String toString() {
            String str = new String (
                    "Virtualizer"+
                    ";strength="+Short.toString(strength)
                    );
            return str;
        }
    };


    /**
     * 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
     */
    public Virtualizer.Settings getProperties()
    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        Settings settings = new Settings();
        short[] value = new short[1];
        checkStatus(getParameter(PARAM_STRENGTH, value));
        settings.strength = value[0];
        return 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
     */
    public void setProperties(Virtualizer.Settings settings)
    throws IllegalStateException, IllegalArgumentException, UnsupportedOperationException {
        checkStatus(setParameter(PARAM_STRENGTH, settings.strength));
    }
}