/* * Copyright (c) 2022-2023 Huawei Device Co., Ltd. * 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. */ /** * @addtogroup HdiAudio * @{ * * @brief Provides unified APIs for audio services to access audio drivers. * * An audio service can obtain an audio driver object or agent and then call APIs provided by this object or agent to * access different types of audio devices based on the audio IDs, thereby obtaining audio information, * subscribing to or unsubscribing from audio data, enabling or disabling an audio, * setting the audio data reporting mode, and setting audio options such as the accuracy and measurement range. * * @since 4.0 * @version 1.0 */ package ohos.hdi.audio.v1_0; import ohos.hdi.audio.v1_0.AudioTypes; /** * @brief Provides capabilities for audio capturing, including controlling the capturing, setting audio attributes, * scenes, and volume, and capturing audio frames. * @since 4.0 * @version 1.0 */ interface IAudioCapture { /** * @brief Reads a frame of input data (uplink data) from the audio driver for capturing. * * @param capture Indicates the pointer to the IAudioCapture object to operate. * @param frame Indicates the pointer to the input data to read. * @param requestBytes Indicates the size of the input data, in bytes. * @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to read. * @return Returns 0 if the input data is read successfully; returns a negative value otherwise. */ CaptureFrame([out] byte[] frame, [out] unsigned long replyBytes); /** * @brief Obtains the last number of input audio frames. * * @param capture Indicates the pointer to the IAudioCapture object to operate. * @param frames Indicates the pointer to the last number of input audio frames. * @param time Indicates the pointer to the timestamp associated with the frame. * @return Returns 0 if the last number is obtained; returns a negative value otherwise. * @see CaptureFrame */ GetCapturePosition([out] unsigned long frames, [out] struct AudioTimeStamp time); /** * @brief Checks whether the configuration of an audio scene is supported. * * @param handle Indicates the audio handle. * @param scene Indicates the pointer to the descriptor of the audio scene. * @param supported Indicates the pointer to the variable specifying whether the configuration is supported. * Value true means that the configuration is supported, and false means the opposite. * @return Returns 0 if the result is obtained; returns a negative value otherwise. * @see SelectScene */ CheckSceneCapability([in] struct AudioSceneDescriptor scene, [out] boolean supported); /** * @brief Selects an audio scene. * * * @param handle Indicates the audio handle. * @param scene Indicates the pointer to the descriptor of the audio scene to select. * @return Returns 0 if the scene is selected successfully; returns a negative value otherwise. * @see CheckSceneCapability */ SelectScene([in] struct AudioSceneDescriptor scene); /** * @brief Sets the mute operation for the audio. * * @param handle Indicates the audio handle. * @param mute Specifies whether to mute the audio. Value true means to mute the audio, * and false means the opposite. * @return Returns 0 if the setting is successful; returns a negative value otherwise. * @see GetMute */ SetMute([in] boolean mute); /** * @brief Obtains the mute operation set for the audio. * * @param handle Indicates the audio handle. * @param mute Indicates the pointer to the mute operation set for the audio. Value true means that * the audio is muted, and false means the opposite. * @return Returns 0 if the mute operation is obtained; returns a negative value otherwise. * @see SetMute */ GetMute([out] boolean mute); /** * @brief Sets the audio volume. * * The volume ranges from 0.0 to 1.0. If the volume level in an audio service ranges from 0 to 15, * 0.0 indicates that the audio is muted, and 1.0 indicates the maximum volume level (15). * * @param handle Indicates the audio handle. * @param volume Indicates the volume to set. The value ranges from 0.0 to 1.0. * @return Returns 0 if the setting is successful; returns a negative value otherwise. * @see GetVolume */ SetVolume([in] float volume); /** * @brief Obtains the audio volume. * * @param handle Indicates the audio handle. * @param volume Indicates the pointer to the volume to obtain. The value ranges from 0.0 to 1.0. * @return Returns 0 if the volume is obtained; returns a negative value otherwise. * @see SetVolume */ GetVolume([out] float volume); /** * @brief Obtains the range of the audio gain. * * The audio gain can be expressed in one of the following two ways (depending on the chip platform), * corresponding to two types of value ranges: * * @param handle Indicates the audio handle. * @param min Indicates the pointer to the minimum value of the range. * @param max Indicates the pointer to the maximum value of the range. * @return Returns 0 if the range is obtained; returns a negative value otherwise. * @see GetGain * @see SetGain */ GetGainThreshold([out] float min, [out] float max); /** * @brief Obtains the audio gain. * * @param handle Indicates the audio handle. * @param gain Indicates the pointer to the audio gain. * @return Returns 0 if the audio gain is obtained; returns a negative value otherwise. * @see GetGainThreshold * @see SetGain */ GetGain([out] float gain); /** * @brief Sets the audio gain. * * @param handle Indicates the audio handle. * @param gain Indicates the audio gain to set. * @return Returns 0 if the setting is successful; returns a negative value otherwise. * @see GetGainThreshold * @see GetGain */ SetGain([in] float gain); /** * @brief Obtains the audio frame size, that is, the length (in bytes) of a frame. * * @param handle Indicates the audio handle. * @param size Indicates the pointer to the audio frame size (in bytes). * @return Returns 0 if the audio frame size is obtained; returns a negative value otherwise. */ GetFrameSize([out] unsigned long size); /** * @brief Obtains the number of audio frames in the audio buffer. * * @param handle Indicates the audio handle. * @param count Indicates the pointer to the number of audio frames in the audio buffer. * @return Returns 0 if the number of audio frames is obtained; returns a negative value otherwise. */ GetFrameCount([out] unsigned long count); /** * @brief Sets audio sampling attributes. * * @param handle Indicates the audio handle. * @param attrs Indicates the pointer to the audio sampling attributes to set, such as the sampling rate, * sampling precision, and channel. * @return Returns 0 if the setting is successful; returns a negative value otherwise. * @see GetSampleAttributes */ SetSampleAttributes([in] struct AudioSampleAttributes attrs); /** * @brief Obtains audio sampling attributes. * * @param handle Indicates the audio handle. * @param attrs Indicates the pointer to the audio sampling attributes, such as the sampling rate, * sampling precision, and channel. * @return Returns 0 if audio sampling attributes are obtained; returns a negative value otherwise. * @see SetSampleAttributes */ GetSampleAttributes([out] struct AudioSampleAttributes attrs); /** * @brief Obtains the data channel ID of the audio. * * @param handle Indicates the audio handle. * @param channelId Indicates the pointer to the data channel ID. * @return Returns 0 if the data channel ID is obtained; returns a negative value otherwise. */ GetCurrentChannelId([out] unsigned int channelId); /** * @brief Sets extra audio parameters. * * @param handle Indicates the audio handle. * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. * The format is key=value. Separate multiple key-value pairs by semicolons (;). * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ SetExtraParams([in] String keyValueList); /** * @brief Obtains extra audio parameters. * * @param handle Indicates the audio handle. * @param keyValueList Indicates the pointer to the key-value list of the extra audio parameters. * The format is key=value. Separate multiple key-value pairs by semicolons (;). * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ GetExtraParams([out] String keyValueList); /** * @brief Requests a mmap buffer. * * @param handle Indicates the audio handle. * @param reqSize Indicates the size of the request mmap buffer. * @param desc Indicates the pointer to the mmap buffer descriptor. * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ ReqMmapBuffer([in] int reqSize, [out] struct AudioMmapBufferDescriptor desc); /** * @brief Obtains the read/write position of the current mmap buffer. * * @param handle Indicates the audio handle. * @param frames Indicates the pointer to the frame where the read/write starts. * @param time Indicates the pointer to the timestamp associated with the frame where the read/write starts. * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ GetMmapPosition([out] unsigned long frames, [out] struct AudioTimeStamp time); /** * @brief Add the audio effect which the effectid indicated. * * @param handle Indicates the audio handle. * @param effectid Indicates the audio effect instance identifier which is going to be added. * @return Returns 0 if the audio effect were added succesffully; returns a negative value otherwise. */ AddAudioEffect([in] unsigned long effectid); /** * @brief Remove the audio effect which the effectid indicated. * * @param handle Indicates the audio handle. * @param effectid Indicates the audio effect which is going to be removed. * @return Returns 0 if the audio effect were removed succesffully; returns a negative value otherwise. */ RemoveAudioEffect([in] unsigned long effectid); /** * @brief Get the buffer size of render or capturer * * @param handle Indicates the audio handle. * @param bufferSize Indicates the buffer size (in bytes) queried from the vendor * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ GetFrameBufferSize([out] unsigned long bufferSize); /** * @brief Starts audio rendering or capturing. * * @param handle Indicates the audio handle. * @return Returns 0 if the rendering or capturing is successfully started; * returns a negative value otherwise. * @see Stop */ Start(); /** * @brief Stops audio rendering or capturing. * * @param handle Indicates the audio handle. * @return Returns 0 if the rendering or capturing is successfully stopped; * returns a negative value otherwise. * @see Start */ Stop(); /** * @brief Pauses audio rendering or capturing. * * @param handle Indicates the audio handle. * @return Returns 0 if the rendering or capturing is successfully paused; * returns a negative value otherwise. * @see Resume */ Pause(); /** * @brief Resumes audio rendering or capturing. * * @param handle Indicates the audio handle. * @return Returns 0 if the rendering or capturing is successfully resumed; * returns a negative value otherwise. * @see Pause */ Resume(); /** * @brief Flushes data in the audio buffer. * * @param handle Indicates the audio handle. * @return Returns 0 if the flush is successful; returns a negative value otherwise. */ Flush(); /** * @brief Sets or cancels the standby mode of the audio device. * * @param handle Indicates the audio handle. * @return Returns 0 if the device is set to standby mode; returns a positive value if the standby mode is * canceled; returns a negative value if the setting fails. */ TurnStandbyMode(); /** * @brief Dumps information about the audio device. * * @param handle Indicates the audio handle. * @param range Indicates the range of the device information to dump, which can be brief or full information. * @param fd Indicates the file to which the device information will be dumped. * @return Returns 0 if the operation is successful; returns a negative value otherwise. */ AudioDevDump([in] int range, [in] int fd); /** * @brief Query whether the vendor support pause and resume. * * @param handle Indicates the audio handle. * @param supportPause Indicates the state whether the vendor supports pausing. Value true means that * the vendor supports, and false means the opposite. * @param supportResume Indicates the state whether the vendor supports resuming. Value true means that * the vendor supports, and false means the opposite. * @return Returns 0 if the operation is successful; returns a negative value otherwise. * @see IsSupportsPauseAndResume */ IsSupportsPauseAndResume([out] boolean supportPause, [out] boolean supportResume); }