xref: /hardware/interfaces/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.
     *
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    reset() generates (Result retval);

    /*
     * 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.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setDevice(AudioDevice device) generates (Result retval);

    /*
     * 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.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setAndGetVolume(vec<uint32_t> volumes)
            generates (Result retval, vec<uint32_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.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setAudioMode(AudioMode mode) generates (Result retval);

    /*
     * 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.
     * @return retval operation completion status.
     */
    @callflow(next={"*"})
    setInputDevice(AudioDevice device) generates (Result retval);

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

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

    /*
     * Queries for supported combinations of main and auxiliary channels
     * (e.g. for a multi-microphone noise suppressor).
     *
     * @param maxConfigs maximum number of the combinations to return.
     * @return retval absence of the feature support is indicated using
     *                NOT_SUPPORTED code. RESULT_TOO_BIG is returned if
     *                the number of supported combinations exceeds 'maxConfigs'.
     * @return result list of configuration descriptors.
     */
    @callflow(next={"*"})
    getSupportedAuxChannelsConfigs(uint32_t maxConfigs)
            generates (Result retval, vec<EffectAuxChannelsConfig> result);

    /*
     * Retrieves the current configuration of main and auxiliary channels.
     *
     * @return retval absence of the feature support is indicated using
     *                NOT_SUPPORTED code.
     * @return result configuration descriptor.
     */
    @callflow(next={"*"})
    getAuxChannelsConfig()
            generates (Result retval, EffectAuxChannelsConfig result);

    /*
     * Sets the current configuration of main and auxiliary channels.
     *
     * @return retval operation completion status; absence of the feature
     *                support is indicated using NOT_SUPPORTED code.
     */
    @callflow(next={"*"})
    setAuxChannelsConfig(EffectAuxChannelsConfig config)
            generates (Result retval);

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

    /*
     * 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 retval operation completion status.
     * @return descriptor effect descriptor.
     */
    @callflow(next={"*"})
    getDescriptor() generates (Result retval, 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.
     *
     * Output audio buffer must contain no more frames than the input audio
     * buffer. Since the effect may transform input channels into a different
     * amount of channels, the caller provides the output frame size.
     *
     * @param inBuffer input audio buffer.
     * @param outFrameSize output frame size in bytes.
     * @return retval operation completion status.
     * @return outBuffer output audio buffer.
     */
    // TODO(mnaganov): replace with FMQ version.
    @callflow(next={"*"})
    process(AudioBuffer inBuffer, uint32_t outFrameSize)
            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.
     *
     * Output audio buffer must contain no more frames than the input audio
     * buffer. Since the effect may transform input channels into a different
     * amount of channels, the caller provides the output frame size.
     *
     * @param inBuffer input audio buffer.
     * @param outFrameSize output frame size in bytes.
     * @return retval operation completion status.
     * @return outBuffer output audio buffer.
     */
    // TODO(mnaganov): replace with FMQ version.
    @callflow(next={"*"})
    processReverse(AudioBuffer inBuffer, uint32_t outFrameSize)
            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.
     * @param resultMaxSize maximum size in bytes of the result; can be 0.
     * @return status command completion status.
     * @return result result data.
     */
    command(uint32_t commandId, vec<uint8_t> data, uint32_t resultMaxSize)
            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.
     * @param valueMaxSize maximum size in bytes of the value.
     * @return retval operation completion status.
     * @return result the value of the parameter.
     */
    @callflow(next={"*"})
    getParameter(vec<uint8_t> parameter, uint32_t valueMaxSize)
            generates (Result retval, vec<uint8_t> value);

    /*
     * Get supported configs for a vendor-specific feature. The configs returned
     * 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 feature ID is
     * unknown. If the effect does not support getting vendor-specific feature
     * configs, it must return NOT_SUPPORTED. If the feature is supported but
     * the total number of supported configurations exceeds the maximum number
     * indicated by the caller, the method must return RESULT_TOO_BIG.
     *
     * 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 featureId feature identifier.
     * @param maxConfigs maximum number of configs to return.
     * @param configSize size of each config in bytes.
     * @return retval operation completion status.
     * @return configsCount number of configs returned.
     * @return configsData data for all the configs returned.
     */
    @callflow(next={"*"})
    getSupportedConfigsForFeature(
            uint32_t featureId,
            uint32_t maxConfigs,
            uint32_t configSize) generates (
                    Result retval,
                    uint32_t configsCount,
                    vec<uint8_t> configsData);

    /*
     * Get the current config for a vendor-specific feature. The config returned
     * is not interpreted by Android Framework and is passed as-is between the
     * application and the effect.
     *
     * The effect must use INVALID_ARGUMENTS return code if the feature ID is
     * unknown. If the effect does not support getting vendor-specific
     * feature configs, 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 featureId feature identifier.
     * @param configSize size of the config in bytes.
     * @return retval operation completion status.
     * @return configData config data.
     */
    @callflow(next={"*"})
    getCurrentConfigForFeature(uint32_t featureId, uint32_t configSize)
            generates (Result retval, vec<uint8_t> configData);

    /*
     * Set the current config for a vendor-specific feature. The config data
     * is not interpreted by Android Framework and is passed as-is between the
     * application and the effect.
     *
     * The effect must use INVALID_ARGUMENTS return code if the feature ID is
     * unknown. If the effect does not support getting vendor-specific
     * feature configs, 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 featureId feature identifier.
     * @param configData config data.
     * @return retval operation completion status.
     */
    setCurrentConfigForFeature(uint32_t featureId, vec<uint8_t> configData)
            generates (Result retval);
};