audio/effect/2.0/IEffect.hal

/*
 * Copyright (C) 2016 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.hardware.audio.effect@2.0;

import android.hardware.audio.common@2.0;
import IEffectBufferProviderCallback;

interface IEffect {
    /*
     * Initialize effect engine--all configurations return to default.
     *
     * @return retval operation completion status.
     */
    @entry
    @callflow(next={"*"})
    init() generates (Result retval);

    /*
     * Apply new audio parameters configurations for input and output buffers.
     * The provider callbacks may be empty, but in this case the buffer
     * must be provided in the EffectConfig structure.
     *
     * @param config configuration descriptor.
     * @param inputBufferProvider optional buffer provider reference.
     * @param outputBufferProvider optional buffer provider reference.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setConfig(EffectConfig config,
            IEffectBufferProviderCallback inputBufferProvider,
            IEffectBufferProviderCallback outputBufferProvider)
            generates (Result retval);

    /*
     * Reset the effect engine. Keep configuration but resets state and buffer
     * content.
     */
    @callflow(next={"*"})
    reset();

    /*
     * Enable processing.
     *
     * @return retval operation completion status.
     */
    @callflow(next={"process"})
    enable() generates (Result retval);

    /*
     * Disable processing.
     *
     * @return retval operation completion status.
     */
    @exit
    disable() generates (Result retval);

    /*
     * Set the rendering device the audio output path is connected to.  The
     * effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its
     * descriptor to receive this command when the device changes.
     *
     * @param device output device specification.
     */
    @callflow(next={"*"})
    setDevice(AudioDevice device);

    /*
     * Set and get volume. Used by audio framework to delegate volume control to
     * effect engine.  The effect implementation must set EFFECT_FLAG_VOLUME_IND
     * or EFFECT_FLAG_VOLUME_CTRL flag in its descriptor to receive this command
     * before every call to 'process' function If EFFECT_FLAG_VOLUME_CTRL flag
     * is set in the effect descriptor, the effect engine must return the volume
     * that should be applied before the effect is processed. The overall volume
     * (the volume actually applied by the effect engine multiplied by the
     * returned value) should match the value indicated in the command.
     *
     * @param volumes vector containing volume for each channel defined in
     *                EffectConfig for output buffer expressed in 8.24 fixed
     *                point format.
     * @return result updated volume values. It is OK to receive an empty vector
     *                as a result in which case the effect framework has
     *                delegated volume control to another effect.
     */
    @callflow(next={"*"})
    setAndGetVolume(vec<int32_t> volumes) generates (vec<int32_t> result);

    /*
     * Set the audio mode. The effect implementation must set
     * EFFECT_FLAG_AUDIO_MODE_IND flag in its descriptor to receive this command
     * when the audio mode changes.
     *
     * @param mode desired audio mode.
     */
    @callflow(next={"*"})
    setAudioMode(AudioMode mode);

    /*
     * Apply new audio parameters configurations for input and output buffers of
     * reverse stream.  An example of reverse stream is the echo reference
     * supplied to an Acoustic Echo Canceler.
     *
     * @param config configuration descriptor.
     * @param inputBufferProvider optional buffer provider reference.
     * @param outputBufferProvider optional buffer provider reference.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setConfigReverse(EffectConfig config,
            IEffectBufferProviderCallback inputBufferProvider,
            IEffectBufferProviderCallback outputBufferProvider)
            generates (Result retval);

    /*
     * Set the capture device the audio input path is connected to. The effect
     * implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to
     * receive this command when the device changes.
     *
     * @param device input device specification.
     */
    @callflow(next={"*"})
    setInputDevice(AudioDevice device);

    /*
     * Read audio parameters configurations for input and output buffers.
     *
     * @return config configuration descriptor.
     */
    @callflow(next={"*"})
    getConfig() generates (EffectConfig config);

    /*
     * Read audio parameters configurations for input and output buffers of
     * reverse stream.
     *
     * @return config configuration descriptor.
     */
    @callflow(next={"*"})
    getConfigReverse() generates (EffectConfig config);

    /*
     * Queries for supported configurations for a particular feature (e.g. get
     * the supported combinations of main and auxiliary channels for a noise
     * suppressor).  The command parameter is a list of the feature identifiers.
     *
     * @return retval absence of the feature support is indicated using
     *                NOT_SUPPORTED code.
     * @return result list of configuration descriptors.
     */
    @callflow(next={"*"})
    getFeatureSupportedConfigs(vec<EffectFeature> features)
            generates (Result retval, vec<EffectFeatureConfig> result);

    /*
     * Retrieves current configuration for a given feature.
     *
     * @return retval absence of the feature support is indicated using
     *                NOT_SUPPORTED code.
     * @return result configuration descriptor.
     */
    @callflow(next={"*"})
    getFeatureConfig(EffectFeature feature)
            generates (Result retval, EffectFeatureConfig result);

    /*
     * Sets current configuration for a given feature.
     *
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setFeatureConfig(EffectFeatureConfig featureConfig)
            generates (Result retval);

    /*
     * Set the audio source the capture path is configured for (Camcorder, voice
     * recognition...).
     *
     * @param source source descriptor.
     */
    @callflow(next={"*"})
    setAudioSource(AudioSource source);

    /*
     * This command indicates if the playback thread the effect is attached to
     * is offloaded or not, and updates the I/O handle of the playback thread
     * the effect is attached to.
     *
     * @param param effect offload descriptor.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    offload(EffectOffloadParameter param) generates (Result retval);

    /*
     * Returns the effect descriptor.
     *
     * @return descriptor effect descriptor.
     */
    @callflow(next={"*"})
    getDescriptor() generates (EffectDescriptor descriptor);

    /*
     * Effect process function. Takes input samples as specified (count and
     * location) in input buffer and returns processed samples as specified in
     * output buffer. If the buffer descriptor is empty the function must use
     * either the buffer or the buffer provider callback installed by the
     * setConfig command.  The effect framework must call the 'process' function
     * after the 'enable' command is received and until the 'disable' is
     * received. When the engine receives the 'disable' command it should turn
     * off the effect gracefully and when done indicate that it is OK to stop
     * calling the 'process' function by returning the INVALID_STATE status.
     *
     * @param inBuffer input audio buffer.
     * @return retval operation completion status.
     * @return outBuffer output audio buffer.
     */
    // TODO(mnaganov): replace with FMQ version.
    @callflow(next={"*"})
    process(AudioBuffer inBuffer)
            generates (Result retval, AudioBuffer outBuffer);

    /*
     * Process reverse stream function. This function is used to pass a
     * reference stream to the effect engine. If the engine does not need a
     * reference stream, this function MUST return NOT_SUPPORTED. For example,
     * this function would typically implemented by an Echo Canceler.
     *
     * @param inBuffer input audio buffer.
     * @return retval operation completion status.
     * @return outBuffer output audio buffer.
     */
    // TODO(mnaganov): replace with FMQ version.
    @callflow(next={"*"})
    processReverse(AudioBuffer inBuffer)
            generates (Result retval, AudioBuffer outBuffer);

    /*
     * Execute a vendor specific command on the effect. The command code
     * and data, as well as result data are not interpreted by Android
     * Framework and are passed as-is between the application and the effect.
     *
     * The effect must use standard POSIX.1-2001 error codes for the operation
     * completion status.
     *
     * Use this method only if the effect is provided by a third party, and
     * there is no interface defined for it. This method only works for effects
     * implemented in software.
     *
     * @param commandId the ID of the command.
     * @param data command data.
     * @return status command completion status.
     * @return result result data.
     */
    command(uint32_t commandId, vec<uint8_t> data)
            generates (int32_t status, vec<uint8_t> result);

    /*
     * Set a vendor-specific parameter and apply it immediately. The parameter
     * code and data are not interpreted by Android Framework and are passed
     * as-is between the application and the effect.
     *
     * The effect must use INVALID_ARGUMENTS return code if the parameter ID is
     * unknown or if provided parameter data is invalid. If the effect does not
     * support setting vendor-specific parameters, it must return NOT_SUPPORTED.
     *
     * Use this method only if the effect is provided by a third party, and
     * there is no interface defined for it. This method only works for effects
     * implemented in software.
     *
     * @param parameter identifying data of the parameter.
     * @param value the value of the parameter.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setParameter(vec<uint8_t> parameter, vec<uint8_t> value)
            generates (Result retval);

    /*
     * Get a vendor-specific parameter value. The parameter code and returned
     * data are not interpreted by Android Framework and are passed as-is
     * between the application and the effect.
     *
     * The effect must use INVALID_ARGUMENTS return code if the parameter ID is
     * unknown. If the effect does not support setting vendor-specific
     * parameters, it must return NOT_SUPPORTED.
     *
     * Use this method only if the effect is provided by a third party, and
     * there is no interface defined for it.  This method only works for effects
     * implemented in software.
     *
     * @param parameter identifying data of the parameter.
     * @return retval operation completion status.
     * @return result the value of the parameter.
     */
    @callflow(next={"*"})
    getParameter(vec<uint8_t> parameter)
            generates (Result retval, vec<uint8_t> value);
};