diff --git a/en/device_api/hdi/audio/audio_adapter.h b/en/device_api/hdi/audio/audio_adapter.h new file mode 100644 index 0000000000000000000000000000000000000000..7c8bbae0e34f6d7779e250e53d10e6b8b96df74b --- /dev/null +++ b/en/device_api/hdi/audio/audio_adapter.h @@ -0,0 +1,175 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_adapter.h + * + * @brief Declares APIs for operations related to the audio adapter. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_ADAPTER_H +#define AUDIO_ADAPTER_H + +#include "audio_types.h" +#include "audio_render.h" +#include "audio_capture.h" + +/** + * @brief Provides audio adapter capabilities, including initializing ports, creating rendering and capturing tasks, + * and obtaining the port capability set. + * + * @see AudioRender + * @see AudioCapture + * @since 1.0 + * @version 1.0 + */ +struct AudioAdapter { + /** + * @brief Initializes all ports of an audio adapter. + * + * Call this function before calling other driver functions to check whether the initialization is complete. + * If the initialization is not complete, wait for a while (for example, 100 ms) and perform the check again + * until the port initialization is complete. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @return Returns 0 if the initialization is successful; returns a negative value otherwise. + */ + int32_t (*InitAllPorts)(struct AudioAdapter *adapter); + + /** + * @brief Creates an AudioRender object. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param desc Indicates the pointer to the descriptor of the audio adapter to start. + * @param attrs Indicates the pointer to the audio sampling attributes to open. + * @param render Indicates the double pointer to the AudioRender object. + * @return Returns 0 if the AudioRender object is created successfully; + * returns a negative value otherwise. + * @see GetPortCapability + * @see DestroyRender + */ + int32_t (*CreateRender)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, + const struct AudioSampleAttributes *attrs, struct AudioRender **render); + + /** + * @brief Destroys an AudioRender object. + * + * @attention Do not destroy the object during audio rendering. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param render Indicates the pointer to the AudioRender object to operate. + * @return Returns 0 if the AudioRender object is destroyed; returns a negative value otherwise. + * @see CreateRender + */ + int32_t (*DestroyRender)(struct AudioAdapter *adapter, struct AudioRender *render); + + /** + * @brief Creates an AudioCapture object. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param desc Indicates the pointer to the descriptor of the audio adapter to start. + * @param attrs Indicates the pointer to the audio sampling attributes to open. + * @param capture Indicates the double pointer to the AudioCapture object. + * @return Returns 0 if the AudioCapture object is created successfully; + * returns a negative value otherwise. + * @see GetPortCapability + * @see DestroyCapture + */ + int32_t (*CreateCapture)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, + const struct AudioSampleAttributes *attrs, struct AudioCapture **capture); + + /** + * @brief Destroys an AudioCapture object. + * + * @attention Do not destroy the object during audio capturing. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param capture Indicates the pointer to the AudioCapture object to operate. + * @return Returns 0 if the AudioCapture object is destroyed; returns a negative value otherwise. + * @see CreateCapture + */ + int32_t (*DestroyCapture)(struct AudioAdapter *adapter, struct AudioCapture *capture); + + /** + * @brief Obtains the capability set of the port driver for the audio adapter. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param port Indicates the pointer to the port. + * @param capability Indicates the pointer to the capability set to obtain. + * @return Returns 0 if the capability set is successfully obtained; returns a negative value otherwise. + */ + int32_t (*GetPortCapability)(struct AudioAdapter *adapter, const struct AudioPort *port, + struct AudioPortCapability *capability); + + /** + * @brief Sets the passthrough data transmission mode of the audio port driver. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param port Indicates the pointer to the port. + * @param mode Indicates the passthrough transmission mode to set. + * @return Returns 0 if the setting is successful; returns a negative value otherwise. + * @see GetPassthroughMode + */ + int32_t (*SetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, + enum AudioPortPassthroughMode mode); + + /** + * @brief Obtains the passthrough data transmission mode of the audio port driver. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param port Indicates the pointer to the port. + * @param mode Indicates the pointer to the passthrough transmission mode to obtain. + * @return Returns 0 if the mode is successfully obtained; returns a negative value otherwise. + * @see SetPassthroughMode + */ + int32_t (*GetPassthroughMode)(struct AudioAdapter *adapter, const struct AudioPort *port, + enum AudioPortPassthroughMode *mode); + + /** + * @brief Update audio route on several source and sink ports. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param route Indicates route information. + * @param routeHandle Indicates route handle. + * @return Returns 0 if the mode is successfully obtained; returns a negative value otherwise. + */ + int32_t (*UpdateAudioRoute)(struct AudioAdapter *adapter, const struct AudioRoute *route, int32_t *routeHandle); + + /** + * @brief Release an audio route. + * + * @param adapter Indicates the pointer to the audio adapter to operate. + * @param routeHandle Indicates route handle. + * @return Returns 0 if the mode is successfully obtained; returns a negative value otherwise. + */ + int32_t (*ReleaseAudioRoute)(struct AudioAdapter *adapter, int32_t routeHandle); +}; + +#endif /* AUDIO_ADAPTER_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_attribute.h b/en/device_api/hdi/audio/audio_attribute.h new file mode 100644 index 0000000000000000000000000000000000000000..237b5c90c3d3334ee8bf3a80d7d9c75c76d1bca9 --- /dev/null +++ b/en/device_api/hdi/audio/audio_attribute.h @@ -0,0 +1,140 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_attribute.h + * + * @brief Declares APIs for audio attributes. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_ATTRIBUTE_H +#define AUDIO_ATTRIBUTE_H + +#include "audio_types.h" + +/** + * @brief Provides attribute-related APIs for audio rendering or capturing, including functions to + * obtain frame information and set audio sampling attributes. + * + * @since 1.0 + * @version 1.0 + */ +struct AudioAttribute { + /** + * @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. + */ + int32_t (*GetFrameSize)(AudioHandle handle, uint64_t *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. + */ + int32_t (*GetFrameCount)(AudioHandle handle, uint64_t *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 + */ + int32_t (*SetSampleAttributes)(AudioHandle handle, const 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 + */ + int32_t (*GetSampleAttributes)(AudioHandle handle, 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. + */ + int32_t (*GetCurrentChannelId)(AudioHandle handle, uint32_t *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. + */ + int32_t (*SetExtraParams)(AudioHandle handle, const char *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. + */ + int32_t (*GetExtraParams)(AudioHandle handle, char *keyValueList, int32_t listLenth); + + /** + * @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. + */ + int32_t (*ReqMmapBuffer)(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescripter *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. + */ + int32_t (*GetMmapPosition)(AudioHandle handle, uint64_t *frames, struct AudioTimeStamp *time); +}; + +#endif /* AUDIO_ATTRIBUTE_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_capture.h b/en/device_api/hdi/audio/audio_capture.h new file mode 100644 index 0000000000000000000000000000000000000000..d56ba362e965d371e8da0b3f17ab5ff6f7d3268a --- /dev/null +++ b/en/device_api/hdi/audio/audio_capture.h @@ -0,0 +1,98 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_capture.h + * + * @brief Declares APIs for audio capturing. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_CAPTURE_H +#define AUDIO_CAPTURE_H + +#include "audio_types.h" +#include "audio_control.h" +#include "audio_attribute.h" +#include "audio_scene.h" +#include "audio_volume.h" + +/** + * @brief Provides capabilities for audio capturing, including controlling the capturing, setting audio attributes, + * scenes, and volume, and capturing audio frames. + * + * @see AudioControl + * @see AudioAttribute + * @see AudioScene + * @see AudioVolume + * @since 1.0 + * @version 1.0 + */ +struct AudioCapture { + /** + * @brief Defines the audio control. For details, see {@link AudioControl}. + */ + struct AudioControl control; + /** + * @brief Defines the audio attribute. For details, see {@link AudioAttribute}. + */ + struct AudioAttribute attr; + /** + * @brief Defines the audio scene. For details, see {@link AudioScene}. + */ + struct AudioScene scene; + /** + * @brief Defines audio volume. For details, see {@link AudioVolume}. + */ + struct AudioVolume volume; + + /** + * @brief Reads a frame of input data (uplink data) from the audio driver for capturing. + * + * @param capture Indicates the pointer to the AudioCapture 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. + */ + int32_t (*CaptureFrame)(struct AudioCapture *capture, void *frame, uint64_t requestBytes, uint64_t *replyBytes); + + /** + * @brief Obtains the last number of input audio frames. + * + * @param capture Indicates the pointer to the AudioCapture 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 + */ + int32_t (*GetCapturePosition)(struct AudioCapture *capture, uint64_t *frames, struct AudioTimeStamp *time); +}; + +#endif /* AUDIO_CAPTURE_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_control.h b/en/device_api/hdi/audio/audio_control.h new file mode 100644 index 0000000000000000000000000000000000000000..cd17611a3a95c2b59dc083df4232e6d6a6f9c585 --- /dev/null +++ b/en/device_api/hdi/audio/audio_control.h @@ -0,0 +1,118 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_control.h + * + * @brief Declares APIs for audio control. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_CONTROL_H +#define AUDIO_CONTROL_H + +#include "audio_types.h" + +/** + * @brief Provides control-related APIs for audio rendering or capturing, including functions to + * start, stop, pause, and resume audio rendering or capturing, and flush data in the audio buffer. + * + * @since 1.0 + * @version 1.0 + */ +struct AudioControl { + /** + * @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 + */ + int32_t (*Start)(AudioHandle handle); + + /** + * @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 + */ + int32_t (*Stop)(AudioHandle handle); + + /** + * @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 + */ + int32_t (*Pause)(AudioHandle handle); + + /** + * @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 + */ + int32_t (*Resume)(AudioHandle handle); + + /** + * @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. + */ + int32_t (*Flush)(AudioHandle handle); + + /** + * @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. + */ + int32_t (*TurnStandbyMode)(AudioHandle handle); + + /** + * @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. + */ + int32_t (*AudioDevDump)(AudioHandle handle, int32_t range, int32_t fd); +}; + +#endif /* AUDIO_CONTROL_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_manager.h b/en/device_api/hdi/audio/audio_manager.h new file mode 100644 index 0000000000000000000000000000000000000000..06b2b9ef33b3790c29ecf0ca6f0eea07fa74fbae --- /dev/null +++ b/en/device_api/hdi/audio/audio_manager.h @@ -0,0 +1,111 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_manager.h + * + * @brief Declares APIs for audio adapter management and loading. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_MANAGER_H +#define AUDIO_MANAGER_H + +#include "audio_types.h" +#include "audio_adapter.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Manages audio adapters through a specific adapter driver program loaded based on the given audio + * adapter descriptor. + * + * @see AudioAdapter + * @since 1.0 + * @version 1.0 + */ +struct AudioManager { + /** + * @brief Obtains the list of all adapters supported by an audio driver. + * + * @param manager Indicates the pointer to the audio adapter manager to operate. + * @param descs Indicates the double pointer to the audio adapter list. + * @param size Indicates the pointer to the length of the list. + * @return Returns 0 if the list is obtained successfully; returns a negative value otherwise. + * @see LoadAdapter + */ + int32_t (*GetAllAdapters)(struct AudioManager *manager, struct AudioAdapterDescriptor **descs, int32_t *size); + + /** + * @brief Loads the driver for an audio adapter. + * + * For example, to load a USB driver, you may need to load a dynamic-link library (*.so) in specific implementation. + * + * @param manager Indicates the pointer to the audio adapter manager to operate. + * @param desc Indicates the pointer to the descriptor of the audio adapter. + * @param adapter Indicates the double pointer to the audio adapter. + * @return Returns 0 if the driver is loaded successfully; returns a negative value otherwise. + * @see GetAllAdapters + * @see UnloadAdapter + */ + int32_t (*LoadAdapter)(struct AudioManager *manager, const struct AudioAdapterDescriptor *desc, + struct AudioAdapter **adapter); + + /** + * @brief Unloads the driver of an audio adapter. + * + * @param manager Indicates the pointer to the audio adapter manager to operate. + * @param adapter Indicates the pointer to the audio adapter whose driver will be unloaded. + * @see LoadAdapter + */ + void (*UnloadAdapter)(struct AudioManager *manager, struct AudioAdapter *adapter); + + /** + * @brief Release the AudioManager Object. + * + * @param object Indicates the pointer to the audio adapter manager to operate. + * @return Returns true if the Object is released; returns false otherwise. + */ + bool (*ReleaseAudioManagerObject)(struct AudioManager *object); +}; + +/** + * @brief Obtains the operation function list of the {@link AudioManager} class. + * + * @return Returns the pointer to the AudioManager object if the list is obtained; returns NULL otherwise. + */ +struct AudioManager *GetAudioManagerFuncs(void); + +#ifdef __cplusplus +} +#endif + +#endif /* AUDIO_MANAGER_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_render.h b/en/device_api/hdi/audio/audio_render.h new file mode 100644 index 0000000000000000000000000000000000000000..7fa8d79b023f7bc483146ddd2fd35a0a56b002e7 --- /dev/null +++ b/en/device_api/hdi/audio/audio_render.h @@ -0,0 +1,170 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_render.h + * + * @brief Declares APIs for audio rendering. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_RENDER_H +#define AUDIO_RENDER_H + +#include "audio_types.h" +#include "audio_control.h" +#include "audio_attribute.h" +#include "audio_scene.h" +#include "audio_volume.h" + +/** + * @brief Provides capabilities for audio rendering, including controlling the rendering, setting audio attributes, + * scenes, and volume, obtaining hardware latency, and rendering audio frames. + * + * @see AudioControl + * @see AudioAttribute + * @see AudioScene + * @see AudioVolume + * @since 1.0 + * @version 1.0 + */ +struct AudioRender { + /** + * @brief Defines the audio control. For details, see {@link AudioControl}. + */ + struct AudioControl control; + /** + * @brief Defines the audio attribute. For details, see {@link AudioAttribute}. + */ + struct AudioAttribute attr; + /** + * @brief Defines the audio scene. For details, see {@link AudioScene}. + */ + struct AudioScene scene; + /** + * @brief Defines audio volume. For details, see {@link AudioVolume}. + */ + struct AudioVolume volume; + + /** + * @brief Obtains the estimated latency of the audio device driver. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param ms Indicates the pointer to the latency (in milliseconds) to be obtained. + * @return Returns 0 if the latency is obtained; returns a negative value otherwise. + */ + int32_t (*GetLatency)(struct AudioRender *render, uint32_t *ms); + + /** + * @brief Writes a frame of output data (downlink data) into the audio driver for rendering. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param frame Indicates the pointer to the frame to write. + * @param requestBytes Indicates the size of the frame, in bytes. + * @param replyBytes Indicates the pointer to the actual length (in bytes) of the audio data to write. + * @return Returns 0 if the data is written successfully; returns a negative value otherwise. + */ + int32_t (*RenderFrame)(struct AudioRender *render, const void *frame, uint64_t requestBytes, uint64_t *replyBytes); + + /** + * @brief Obtains the last number of output audio frames. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param frames Indicates the pointer to the last number of output 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 RenderFrame + */ + int32_t (*GetRenderPosition)(struct AudioRender *render, uint64_t *frames, struct AudioTimeStamp *time); + + /** + * @brief Sets the audio rendering speed. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param speed Indicates the rendering speed to set. + * @return Returns 0 if the setting is successful; returns a negative value otherwise. + * @see GetRenderSpeed + */ + int32_t (*SetRenderSpeed)(struct AudioRender *render, float speed); + + /** + * @brief Obtains the current audio rendering speed. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param speed Indicates the pointer to the current rendering speed to obtain. + * @return Returns 0 if the speed is successfully obtained; returns a negative value otherwise. + * @see SetRenderSpeed + */ + int32_t (*GetRenderSpeed)(struct AudioRender *render, float *speed); + + /** + * @brief Sets the channel mode for audio rendering. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param mode Indicates the channel mode to set. + * @return Returns 0 if the setting is successful; returns a negative value otherwise. + * @see GetChannelMode + */ + int32_t (*SetChannelMode)(struct AudioRender *render, enum AudioChannelMode mode); + + /** + * @brief Obtains the current channel mode for audio rendering. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param mode Indicates the pointer to the channel mode to obtain. + * @return Returns 0 if the mode is successfully obtained; returns a negative value otherwise. + * @see SetChannelMode + */ + int32_t (*GetChannelMode)(struct AudioRender *render, enum AudioChannelMode *mode); + + /** + * @brief Registers an audio callback that will be invoked during playback when buffer data writing or + * buffer drain is complete. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param callback Indicates the callback to register. + * @param cookie Indicates the pointer to the callback parameters. + * @return Returns 0 if the operation is successful; returns a negative value otherwise. + * @see RegCallback + */ + int32_t (*RegCallback)(struct AudioRender *render, RenderCallback callback, void* cookie); + + /** + * @brief Drains the buffer. + * + * @param render Indicates the pointer to the AudioRender object to operate. + * @param type Indicates the pointer to the execution type of this function. For details, + * see {@link AudioDrainNotifyType}. + * @return Returns 0 if the operation is successful; returns a negative value otherwise. + * @see RegCallback + */ + int32_t (*DrainBuffer)(struct AudioRender *render, enum AudioDrainNotifyType *type); +}; + +#endif /* AUDIO_RENDER_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_scene.h b/en/device_api/hdi/audio/audio_scene.h new file mode 100644 index 0000000000000000000000000000000000000000..7923bb89c4e578088348b04be69c759a4b0e0d79 --- /dev/null +++ b/en/device_api/hdi/audio/audio_scene.h @@ -0,0 +1,86 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_scene.h + * + * @brief Declares APIs for audio scenes. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_SCENE_H +#define AUDIO_SCENE_H + +#include "audio_types.h" + +/** + * @brief Provides scene-related APIs for audio rendering or capturing, including functions to + * select an audio scene and check whether the configuration of an audio scene is supported. + * + * @since 1.0 + * @version 1.0 + */ +struct AudioScene { + /** + * @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 + */ + int32_t (*CheckSceneCapability)(AudioHandle handle, const struct AudioSceneDescriptor *scene, bool *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 + */ + int32_t (*SelectScene)(AudioHandle handle, const struct AudioSceneDescriptor *scene); +}; + +#endif /* AUDIO_SCENE_H */ +/** @} */ diff --git a/en/device_api/hdi/audio/audio_types.h b/en/device_api/hdi/audio/audio_types.h new file mode 100644 index 0000000000000000000000000000000000000000..5b468a6d41651ce1d81055800753bc80a38f0e9d --- /dev/null +++ b/en/device_api/hdi/audio/audio_types.h @@ -0,0 +1,425 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_types.h + * + * @brief Defines custom data types used in API declarations for the audio module, including audio ports, + * adapter descriptors, device descriptors, scene descriptors, sampling attributes, and timestamp. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_TYPES_H +#define AUDIO_TYPES_H + +#include +#include + +/** + * @brief Defines the audio handle. + */ +typedef void *AudioHandle; + +/** + * @brief Enumerates the audio port type. + */ +enum AudioPortDirection { + PORT_OUT = 0x1u, /**< Output port */ + PORT_IN = 0x2u, /**< Input port */ + PORT_OUT_IN = 0x3u, /**< Input/output port, supporting both audio input and output */ +}; + +/** + * @brief Defines the audio port. + */ +struct AudioPort { + enum AudioPortDirection dir; /**< Audio port type. For details, see {@link AudioPortDirection} */ + uint32_t portId; /**< Audio port ID */ + const char *portName; /**< Audio port name */ +}; + +/** + * @brief Defines the audio adapter descriptor. + * + * An audio adapter is a set of port drivers for a sound card, including the output and input ports. + * One port corresponds to multiple pins, and each pin belongs to a physical component (such as a + * speaker or a wired headset). + */ +struct AudioAdapterDescriptor { + const char *adapterName; /**< Name of the audio adapter */ + uint32_t portNum; /**< Number of ports supported by an audio adapter */ + struct AudioPort *ports; /**< List of ports supported by an audio adapter */ +}; + +/** + * @brief Enumerates the pin of an audio adapter. + */ +enum AudioPortPin { + PIN_NONE = 0x0u, /**< Invalid pin */ + PIN_OUT_SPEAKER = 0x1u, /**< Speaker output pin */ + PIN_OUT_HEADSET = 0x2u, /**< Wired headset pin for output */ + PIN_OUT_LINEOUT = 0x4u, /**< Line-out pin */ + PIN_OUT_HDMI = 0x8u, /**< HDMI output pin */ + PIN_OUT_USB = 0x10u, /**< USB device output */ + PIN_OUT_USB_EXT = 0x20u, /**< Extended USB device output */ + PIN_IN_MIC = 0x8000001u, /**< Microphone input pin */ + PIN_IN_HS_MIC = 0x8000002u, /**< Wired headset microphone pin for input */ + PIN_IN_LINEIN = 0x8000004u, /**< Line-in pin */ + PIN_IN_USB_EXT = 0x8000008u, /**< Extended USB device input */ +}; + +/** + * @brief Defines the audio device descriptor. + */ +struct AudioDeviceDescriptor { + uint32_t portId; /**< Audio port ID */ + enum AudioPortPin pins; /**< Pins of audio ports (input and output). For details, see {@link AudioPortPin}. */ + const char *desc; /**< Audio device name */ +}; + +/** + * @brief Enumerates the audio category. + */ +enum AudioCategory { + AUDIO_IN_MEDIA = 0, /**< Media */ + AUDIO_IN_COMMUNICATION, /**< Communications */ + AUDIO_IN_RINGTONE, /**< Ringtone */ + AUDIO_IN_CALL, /**< Call */ +}; + +/** + * @brief Defines the audio scene descriptor. + */ +struct AudioSceneDescriptor { + /** + * @brief Describes the audio scene. + */ + union SceneDesc { + uint32_t id; /**< Audio scene ID */ + const char *desc; /**< Name of the audio scene */ + } scene; /**< The scene object */ + struct AudioDeviceDescriptor desc; /**< Audio device descriptor */ +}; + +/** + * @brief Enumerates the audio format. + */ +enum AudioFormat { + AUDIO_FORMAT_PCM_8_BIT = 0x1u, /**< 8-bit PCM */ + AUDIO_FORMAT_PCM_16_BIT = 0x2u, /**< 16-bit PCM */ + AUDIO_FORMAT_PCM_24_BIT = 0x3u, /**< 24-bit PCM */ + AUDIO_FORMAT_PCM_32_BIT = 0x4u, /**< 32-bit PCM */ + AUDIO_FORMAT_AAC_MAIN = 0x1000001u, /**< AAC main */ + AUDIO_FORMAT_AAC_LC = 0x1000002u, /**< AAC LC */ + AUDIO_FORMAT_AAC_LD = 0x1000003u, /**< AAC LD */ + AUDIO_FORMAT_AAC_ELD = 0x1000004u, /**< AAC ELD */ + AUDIO_FORMAT_AAC_HE_V1 = 0x1000005u, /**< AAC HE_V1 */ + AUDIO_FORMAT_AAC_HE_V2 = 0x1000006u, /**< AAC HE_V2 */ + AUDIO_FORMAT_G711A = 0x2000001u, /**< G711A */ + AUDIO_FORMAT_G711U = 0x2000002u, /**< G711u */ + AUDIO_FORMAT_G726 = 0x2000003u, /**< G726 */ +}; + +/** + * @brief Enumerates the audio channel mask. + * + * A mask describes an audio channel position. + */ +enum AudioChannelMask { + AUDIO_CHANNEL_FRONT_LEFT = 0x1, /**< Front left channel */ + AUDIO_CHANNEL_FRONT_RIGHT = 0x2, /**< Front right channel */ + AUDIO_CHANNEL_MONO = 0x1u, /**< Mono channel */ + AUDIO_CHANNEL_STEREO = 0x3u, /**< Stereo channel, consisting of front left and front right channels */ +}; + +/** + * @brief Enumerates masks of audio sampling rates. + */ +enum AudioSampleRatesMask { + AUDIO_SAMPLE_RATE_MASK_8000 = 0x1u, /**< 8 kHz */ + AUDIO_SAMPLE_RATE_MASK_12000 = 0x2u, /**< 12 kHz */ + AUDIO_SAMPLE_RATE_MASK_11025 = 0x4u, /**< 11.025 kHz */ + AUDIO_SAMPLE_RATE_MASK_16000 = 0x8u, /**< 16 kHz */ + AUDIO_SAMPLE_RATE_MASK_22050 = 0x10u, /**< 22.050 kHz */ + AUDIO_SAMPLE_RATE_MASK_24000 = 0x20u, /**< 24 kHz */ + AUDIO_SAMPLE_RATE_MASK_32000 = 0x40u, /**< 32 kHz */ + AUDIO_SAMPLE_RATE_MASK_44100 = 0x80u, /**< 44.1 kHz */ + AUDIO_SAMPLE_RATE_MASK_48000 = 0x100u, /**< 48 kHz */ + AUDIO_SAMPLE_RATE_MASK_64000 = 0x200u, /**< 64 kHz */ + AUDIO_SAMPLE_RATE_MASK_96000 = 0x400u, /**< 96 kHz */ + AUDIO_SAMPLE_RATE_MASK_INVALID = 0xFFFFFFFFu, /**< Invalid sampling rate */ +}; + +/** + * @brief Defines audio sampling attributes. + */ +struct AudioSampleAttributes { + enum AudioCategory type; /**< Audio type. For details, see {@link AudioCategory} */ + bool interleaved; /**< Interleaving flag of audio data */ + enum AudioFormat format; /**< Audio data format. For details, see {@link AudioFormat}. */ + uint32_t sampleRate; /**< Audio sampling rate */ + uint32_t channelCount; /**< Number of audio channels. For example, for the mono channel, the value is 1, + * and for the stereo channel, the value is 2. + */ + uint32_t period; /**< Audio sampling period */ + uint32_t frameSize; /**< Frame size of the audio data */ + bool isBigEndian; /**< Big endian flag of audio data */ + bool isSignedData; /**< Signed or unsigned flag of audio data */ + uint32_t startThreshold; /**< Audio render start threshold. */ + uint32_t stopThreshold; /**< Audio render stop threshold. */ + uint32_t silenceThreshold; /**< Audio capture buffer threshold. */ + int32_t streamId; /**< Audio Identifier of render or capture */ +}; + +/** + * @brief Defines the audio timestamp, which is a substitute for POSIX timespec. + */ +struct AudioTimeStamp { + int64_t tvSec; /**< Seconds */ + int64_t tvNSec; /**< Nanoseconds */ +}; + +/** + * @brief Enumerates the passthrough data transmission mode of an audio port. + */ +enum AudioPortPassthroughMode { + PORT_PASSTHROUGH_LPCM = 0x1, /**< Stereo PCM */ + PORT_PASSTHROUGH_RAW = 0x2, /**< HDMI passthrough */ + PORT_PASSTHROUGH_HBR2LBR = 0x4, /**< Blu-ray next-generation audio output with reduced specifications */ + PORT_PASSTHROUGH_AUTO = 0x8, /**< Mode automatically matched based on the HDMI EDID */ +}; + +/** + * @brief Defines the sub-port capability. + */ +struct AudioSubPortCapability { + uint32_t portId; /**< Sub-port ID */ + const char *desc; /**< Sub-port name */ + enum AudioPortPassthroughMode mask; /**< Passthrough mode of data transmission. For details, + * see {@link AudioPortPassthroughMode}. + */ +}; + +/** + * @brief Defines formats of raw audio samples. + */ +enum AudioSampleFormat { + /* 8 bits */ + AUDIO_SAMPLE_FORMAT_S8, /**< Signed 8 bit sample */ + AUDIO_SAMPLE_FORMAT_S8P, /**< Signed 8 bit planar sample */ + AUDIO_SAMPLE_FORMAT_U8, /**< Unsigned 8 bit sample */ + AUDIO_SAMPLE_FORMAT_U8P, /**< Unsigned 8 bit planar sample */ + /* 16 bits */ + AUDIO_SAMPLE_FORMAT_S16, /**< signed 16 bit sample */ + AUDIO_SAMPLE_FORMAT_S16P, /**< signed 16 bit planar sample */ + AUDIO_SAMPLE_FORMAT_U16, /**< Unsigned 16 bit sample */ + AUDIO_SAMPLE_FORMAT_U16P, /**< Unsigned 16 bit planar sample */ + /* 24 bits */ + AUDIO_SAMPLE_FORMAT_S24, /**< Signed 24 bit sample */ + AUDIO_SAMPLE_FORMAT_S24P, /**< Signed 24 bit planar sample */ + AUDIO_SAMPLE_FORMAT_U24, /**< Unsigned 24 bit sample */ + AUDIO_SAMPLE_FORMAT_U24P, /**< Unsigned 24 bit planar sample */ + /* 32 bits */ + AUDIO_SAMPLE_FORMAT_S32, /**< Signed 32 bit sample */ + AUDIO_SAMPLE_FORMAT_S32P, /**< Signed 32 bit planar sample */ + AUDIO_SAMPLE_FORMAT_U32, /**< Unsigned 32 bit sample */ + AUDIO_SAMPLE_FORMAT_U32P, /**< Unsigned 32 bit planar sample */ + /* 64 bits */ + AUDIO_SAMPLE_FORMAT_S64, /**< Signed 64 bit sample */ + AUDIO_SAMPLE_FORMAT_S64P, /**< Signed 64 bit planar sample */ + AUDIO_SAMPLE_FORMAT_U64, /**< Unsigned 64 bit sample */ + AUDIO_SAMPLE_FORMAT_U64P, /**< Unsigned 64 bit planar sample */ + /* float double */ + AUDIO_SAMPLE_FORMAT_F32, /**< Float 32 bit sample */ + AUDIO_SAMPLE_FORMAT_F32P, /**< Float 32 bit planar sample */ + AUDIO_SAMPLE_FORMAT_F64, /**< Double 64 bit sample */ + AUDIO_SAMPLE_FORMAT_F64P, /**< Double 64 bit planar sample */ +}; + +/** + * @brief Defines the audio port capability. + */ +struct AudioPortCapability { + uint32_t deviceType; /**< Device type (output or input) */ + uint32_t deviceId; /**< Device ID used for device binding */ + bool hardwareMode; /**< Whether to support device binding */ + uint32_t formatNum; /**< Number of the supported audio formats */ + enum AudioFormat *formats; /**< Supported audio formats. For details, see {@link AudioFormat}. */ + uint32_t sampleRateMasks; /**< Supported audio sampling rates (8 kHz, 16 kHz, 32 kHz, and 48 kHz) */ + enum AudioChannelMask channelMasks; /**< Audio channel layout mask of the device. For details, + * see {@link AudioChannelMask}. + */ + uint32_t channelCount; /**< Supported maximum number of audio channels */ + uint32_t subPortsNum; /**< Number of supported sub-ports (for output devices only) */ + struct AudioSubPortCapability *subPorts; /**< List of supported sub-ports */ + uint32_t supportSampleFormatNum; /**< Number of the supported audio sample format enum. */ + enum AudioSampleFormat *supportSampleFormats; /**< Supported audio sample formats. For details, + * see {@link AudioSampleFormat}. + */ +}; + +/** + * @brief Enumerates channel modes for audio rendering. + * + * @attention The following modes are set for rendering dual-channel audios. Others are not supported. + */ +enum AudioChannelMode { + AUDIO_CHANNEL_NORMAL = 0, /**< Normal mode. No processing is required. */ + AUDIO_CHANNEL_BOTH_LEFT, /**< Two left channels */ + AUDIO_CHANNEL_BOTH_RIGHT, /**< Two right channels */ + AUDIO_CHANNEL_EXCHANGE, /**< Data exchange between the left and right channels. The left channel takes the audio + * stream of the right channel, and the right channel takes that of the left channel. + */ + AUDIO_CHANNEL_MIX, /**< Mix of streams of the left and right channels */ + AUDIO_CHANNEL_LEFT_MUTE, /**< Left channel muted. The stream of the right channel is output. */ + AUDIO_CHANNEL_RIGHT_MUTE, /**< Right channel muted. The stream of the left channel is output. */ + AUDIO_CHANNEL_BOTH_MUTE, /**< Both left and right channels muted */ +}; + +/** + * @brief Enumerates the execution types of the DrainBuffer function. + */ +enum AudioDrainNotifyType { + AUDIO_DRAIN_NORMAL_MODE, /**< The DrainBuffer function returns after all data finishes playback. */ + AUDIO_DRAIN_EARLY_MODE, /**< The DrainBuffer function returns before all the data of the current track + * finishes playback to reserve time for a smooth track switch by the audio service. + */ +}; + +/** + * @brief Enumerates callback notification events. + */ +enum AudioCallbackType { + AUDIO_NONBLOCK_WRITE_COMPELETED, /**< The non-block write is complete. */ + AUDIO_DRAIN_COMPELETED, /**< The draining is complete. */ + AUDIO_FLUSH_COMPLETED, /**< The flush is complete. */ + AUDIO_RENDER_FULL, /**< The render buffer is full.*/ + AUDIO_ERROR_OCCUR, /**< An error occurs.*/ +}; + +/** + * @brief Describes a mmap buffer. + */ +struct AudioMmapBufferDescripter { + void *memoryAddress; /**< Pointer to the mmap buffer */ + int32_t memoryFd; /**< File descriptor of the mmap buffer */ + int32_t totalBufferFrames; /**< Total size of the mmap buffer (unit: frame )*/ + int32_t transferFrameSize; /**< Transfer size (unit: frame) */ + int32_t isShareable; /**< Whether the mmap buffer can be shared among processes */ + uint32_t offset; +}; + +/** + * @brief Describes AudioPortRole. + */ +enum AudioPortRole { + AUDIO_PORT_UNASSIGNED_ROLE = 0, /**< Unassigned port role */ + AUDIO_PORT_SOURCE_ROLE = 1, /**< Assigned source role */ + AUDIO_PORT_SINK_ROLE = 2, /**< Assigned sink role */ +}; + +/** + * @brief Describes AudioPortType. + */ +enum AudioPortType { + AUDIO_PORT_UNASSIGNED_TYPE = 0, /**< Unassigned port type */ + AUDIO_PORT_DEVICE_TYPE = 1, /**< Assigned device type */ + AUDIO_PORT_MIX_TYPE = 2, /**< Assigned mix type */ + AUDIO_PORT_SESSION_TYPE = 3, /**< Assigned session type */ +}; + +/** + * @brief Describes AudioDevExtInfo. + */ +struct AudioDevExtInfo { + int32_t moduleId; /**< Identifier of the module stream is attached to */ + enum AudioPortPin type; /**< Device type For details, see {@link AudioPortPin}. */ + const char *desc; /**< Address */ +}; + +/** + * @brief Describes AudioMixInfo. + */ +struct AudioMixExtInfo { + int32_t moduleId; /**< Identifier of the module stream is attached to */ + int32_t streamId; /**< Identifier of the capture or render passed by caller */ +}; + +/** + * @brief Describes AudioSessionType. + */ +enum AudioSessionType { + AUDIO_OUTPUT_STAGE_SESSION = 0, /**< Session attached to output stream */ + AUDIO_OUTPUT_MIX_SESSION, /**< Session attached to output mix */ + AUDIO_ALLOCATE_SESSION, /**< Session id have to be allocated */ + AUDIO_INVALID_SESSION, /**< Invalid session type */ +}; + +/** + * @brief Describes AudioSessionExtInfo. + */ +struct AudioSessionExtInfo { + enum AudioSessionType sessionType; /**< Audio session type */ +}; + +/** + * @brief Describes AudioRouteNode. + */ +struct AudioRouteNode { + int32_t portId; /**< Audio port ID */ + enum AudioPortRole role; /**< Audio port as a sink or a source */ + enum AudioPortType type; /**< device, mix ... */ + union { + struct AudioDevExtInfo device; /* Specific Device Ext info */ + struct AudioMixExtInfo mix; /* Specific mix info */ + struct AudioSessionExtInfo session; /* Session specific info */ + } ext; +}; + +/** + * @brief Describes AudioRoute. + */ +struct AudioRoute { + uint32_t sourcesNum; /**< Audio source number */ + const struct AudioRouteNode *sources; /**< List of audio sources */ + uint32_t sinksNum; /**< Audio sink number */ + const struct AudioRouteNode *sinks; /**< List of audio sinks */ +}; + +/** + * @brief Called when an event defined in {@link AudioCallbackType} occurs. + * + * @param AudioCallbackType Indicates the occurred event that triggers this callback. + * @param reserved Indicates the pointer to a reserved field. + * @param cookie Indicates the pointer to the cookie for data transmission. + * @return Returns 0 if the callback is successfully executed; returns a negative value otherwise. + * @see RegCallback + */ +typedef int32_t (*RenderCallback)(enum AudioCallbackType, void *reserved, void *cookie); + +#endif /* AUDIO_TYPES_H */ diff --git a/en/device_api/hdi/audio/audio_volume.h b/en/device_api/hdi/audio/audio_volume.h new file mode 100644 index 0000000000000000000000000000000000000000..f750f40ad23d1bdbd2b072c318ded9f361dfef26 --- /dev/null +++ b/en/device_api/hdi/audio/audio_volume.h @@ -0,0 +1,137 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Defines audio-related APIs, including custom data types and functions for loading drivers, + * accessing a driver adapter, and rendering and capturing audios. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_volume.h + * + * @brief Declares APIs for audio volume. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_VOLUME_H +#define AUDIO_VOLUME_H + +#include "audio_types.h" + +/** + * @brief Provides volume-related APIs for audio rendering or capturing, including functions to + * set the mute operation, volume, and gain. + * + * @since 1.0 + * @version 1.0 + */ +struct AudioVolume { + /** + * @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 + */ + int32_t (*SetMute)(AudioHandle handle, bool 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 + */ + int32_t (*GetMute)(AudioHandle handle, bool *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 + */ + int32_t (*SetVolume)(AudioHandle handle, 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 + */ + int32_t (*GetVolume)(AudioHandle handle, 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 + */ + int32_t (*GetGainThreshold)(AudioHandle handle, float *min, 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 + */ + int32_t (*GetGain)(AudioHandle handle, 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 + */ + int32_t (*SetGain)(AudioHandle handle, float gain); +}; + +#endif /* AUDIO_VOLUME_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_adapter.h b/zh-cn/device_api/hdi/audio/audio_adapter.h new file mode 100644 index 0000000000000000000000000000000000000000..8284a7331d4ddc39b6df6635434936e9d464994a --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_adapter.h @@ -0,0 +1,167 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_adapter.h + * + * @brief Audio适配器的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_ADAPTER_H +#define AUDIO_ADAPTER_H + +/** + * @brief AudioAdapter音频适配器接口 + * + * 提供音频适配器（声卡）对外支持的驱动能力，包括初始化端口、创建render、创建capture、获取端口能力集等 + * + * @see AudioRender + * @see AudioCapture + * @since 1.0 + * @version 1.0 + */ +struct AudioAdapter { + /** + * @brief 初始化一个音频适配器所有的端口驱动 + * + * 在音频服务中，调用其他驱动接口前需要首先调用该接口检查端口是否已经初始化完成，如果端口驱动初始化完成，则函数返回值0， + * 否则返回负值，如果端口没有初始化完成，则需要等待一段时间（例如100ms）后重新进行检查，直到端口初始化完成后再继续操作 + * + * @param adapter 待操作的音频适配器对象 + * @return 成功返回值0，失败返回负值 + */ + int (*InitAllPorts)(struct AudioAdapter *adapter); + + /** + * @brief 创建一个音频播放（render）接口的对象 + * + * @param adapter 待操作的音频适配器对象 + * @param desc 待打开的音频设备描述符 + * @param attrs 待打开的音频采样属性 + * @param render 获取的音频播放接口的对象实例保存到render中 + * @return 成功返回值0，失败返回负值 + * @see GetPortCapability + * @see DestroyRender + */ + int32_t (*CreateRender)(struct AudioAdapter *adapter, const struct AudioDeviceDescriptor *desc, + const struct AudioSampleAttributes *attrs, struct AudioRender **render); + + /** + * @brief 销毁一个音频播放（render）接口的对象 + * + * @attention 在音频播放过程中，不能销毁该接口对象 + * + * @param adapter 待操作的音频适配器对象 + * @param render 待操作的音频播放接口对象 + * @return 成功返回值0，失败返回负值 + * @see CreateRender + */ + int32_t (*DestroyRender)(struct AudioAdapter *adapter, struct AudioRender *render); + + /** + * @brief 销毁一个音频录音（capture）接口的对象 + * + * @attention 在音频录音过程中，不能销毁该接口对象 + * + * @param adapter 待操作的音频适配器对象 + * @param capture 待操作的音频录音接口对象 + * @return 成功返回值0，失败返回负值 + * @see CreateCapture + */ + int32_t (*DestroyCapture)(struct AudioAdapter *adapter, struct AudioCapture *capture); + + /** + * @brief 销毁一个音频录音（capture）接口的对象 + * + * @attention 在音频录音过程中，不能销毁该接口对象 + * + * @param adapter 待操作的音频适配器对象 + * @param capture 待操作的音频录音接口对象 + * @return 成功返回值0，失败返回负值 + * @see CreateCapture + */ + int32_t (*DestroyCapture)(struct AudioAdapter *adapter, struct AudioCapture *capture); + + /** + * @brief 获取一个音频适配器的端口驱动的能力集 + * + * @param adapter 待操作的音频适配器对象 + * @param port 待获取的端口 + * @param capability 获取的端口能力保存到capability中 + * @return 成功返回值0，失败返回负值 + */ + int (*GetPortCapability)(struct AudioAdapter *adapter, struct AudioPort *port, + struct AudioPortCapability *capability); + /** + * @brief 设置音频端口驱动的数据透传模式 + * + * @param adapter 待操作的音频适配器对象 + * @param port 待设置的端口 + * @param mode 待设置的传输模式 + * @return 成功返回值0，失败返回负值 + * @see GetPassthroughMode + */ + int (*SetPassthroughMode)(struct AudioAdapter *adapter, struct AudioPort *port, + enum AudioPortPassthroughMode mode); + + /** + * @brief 获取音频端口驱动的数据透传模式 + * + * @param adapter 待操作的音频适配器对象 + * @param port 待获取的端口 + * @param mode 获取的传输模式保存到mode中 + * @return 成功返回值0，失败返回负值 + * @see SetPassthroughMode + */ + int (*GetPassthroughMode)(struct AudioAdapter *adapter, struct AudioPort *port, + enum AudioPortPassthroughMode *mode); + + /** + * @brief 更新一个或多个发送端和接受端之间的路由 + * + * @param adapter 待操作的音频适配器对象 + * @param route 路由信息 + * @param routeHandle 生成的路由句柄 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*UpdateAudioRoute)(struct AudioAdapter *adapter, const struct AudioRoute *route, int32_t *routeHandle); + + /** + * @brief 释放一个音频路由. + * + * @param adapter 待操作的音频适配器对象 + * @param routeHandle 待释放的路由句柄. + * @return 成功返回值0，失败返回负值 + */ + int32_t (*ReleaseAudioRoute)(struct AudioAdapter *adapter, int32_t routeHandle); +}; + +#endif /* AUDIO_ADAPTER_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_attribute.h b/zh-cn/device_api/hdi/audio/audio_attribute.h new file mode 100644 index 0000000000000000000000000000000000000000..42f79c61718a1ed18570202007b92d6c0ab2f552 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_attribute.h @@ -0,0 +1,138 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_attribute.h + * + * @brief Audio属性的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_ATTRIBUTE_H +#define AUDIO_ATTRIBUTE_H +/** + * @brief AudioAttribute音频属性接口 + * + * 提供音频播放（render）或录音（capture）需要的公共属性驱动能力，包括获取帧（frame）信息、设置采样属性等 + * + * @since 1.0 + * @version 1.0 + */ + +struct AudioAttribute { + /** + * @brief 获取音频帧（frame）的大小 + * + * 获取一帧音频数据的长度（字节数） + * + * @param handle 待操作的音频句柄 + * @param size 获取的音频帧大小（字节数）保存到size中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetFrameSize)(AudioHandle handle, uint64_t *size); + + /** + * @brief 获取音频buffer中的音频帧数 + * + * @param handle 待操作的音频句柄 + * @param count 一个音频buffer中包含的音频帧数，获取后保存到count中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetFrameCount)(AudioHandle handle, uint64_t *count); + + /** + * @brief 设置音频采样的属性参数 + * + * @param handle 待操作的音频句柄 + * @param attrs 待设置的音频采样属性，例如采样频率、采样精度、通道 + * @return 成功返回值0，失败返回负值 + * @see GetSampleAttributes + */ + int32_t (*SetSampleAttributes)(AudioHandle handle, const struct AudioSampleAttributes *attrs); + + /** + * @brief 获取音频采样的属性参数 + * + * @param handle 待操作的音频句柄 + * @param attrs 获取的音频采样属性（例如采样频率、采样精度、通道）保存到attrs中 + * @return 成功返回值0，失败返回负值 + * @see SetSampleAttributes + */ + int32_t (*GetSampleAttributes)(AudioHandle handle, struct AudioSampleAttributes *attrs); + + /** + * @brief 获取音频的数据通道ID + * + * @param handle 待操作的音频句柄 + * @param channelId 获取的通道ID保存到channelId中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetCurrentChannelId)(AudioHandle handle, uint32_t *channelId); + + /** + * @brief 设置音频拓展参数 + * + * @param handle 待操作的音频句柄 + * @param keyValueList 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*SetExtraParams)(AudioHandle handle, const char *keyValueList); + + /** + * @brief 获取音频拓展参数 + * + * @param handle 待操作的音频句柄 + * @param keyValueList 拓展参数键值对字符串列表，格式为key=value，多个键值对通过分号分割 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetExtraParams)(AudioHandle handle, char *keyValueList); + + /** + * @brief 请求mmap缓冲区 + * + * @param handle 待操作的音频句柄 + * @param reqSize 请求缓冲区的大小 + * @param desc 缓冲区描述符 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*ReqMmapBuffer)(AudioHandle handle, int32_t reqSize, struct AudioMmapBufferDescripter *desc); + + /** + * @brief 获取当前mmap的读/写位置 + * + * @param handle 待操作的音频句柄 + * @param frames 获取的音频帧计数保存到frames中 + * @param time 获取的关联时间戳保存到time中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetMmapPosition)(AudioHandle handle, uint64_t *frames, struct AudioTimeStamp *time); +}; + +#endif /* AUDIO_ATTRIBUTE_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_capture.h b/zh-cn/device_api/hdi/audio/audio_capture.h new file mode 100644 index 0000000000000000000000000000000000000000..ac01c43fb24ab2e700bc45c4a91370c5365519f2 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_capture.h @@ -0,0 +1,85 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_capture.h + * + * @brief Audio录音的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_CAPTURE_H +#define AUDIO_CAPTURE_H + +struct AudioCapture { + /** + * @brief 音频控制能力接口，详情参考{@link AudioControl} + */ + struct AudioControl control; + + /** + * @brief 音频属性能力接口，详情参考{@link AudioAttribute} + */ + struct AudioAttribute attr; + + /** + * @brief 音频场景能力接口，详情参考{@link AudioScene} + */ + struct AudioScene scene; + + /** + * @brief 音频音量能力接口，详情参考{@link AudioVolume} + */ + struct AudioVolume volume; + + /** + * @brief 从音频驱动中录制（capture）一帧输入数据（录音，音频上行数据） + * + * @param capture 待操作的音频录音接口对象 + * @param frame 待存放输入数据的音频frame + * @param requestBytes 待存放输入数据的音频frame大小（字节数） + * @param replyBytes 实际读取到的音频数据长度（字节数），获取后保存到replyBytes中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*CaptureFrame)(struct AudioCapture *capture, void *frame, uint64_t requestBytes, uint64_t *replyBytes); + + /** + * @brief 获取音频输入帧数的上一次计数 + * + * @param capture 待操作的音频录音接口对象 + * @param frames 获取的音频帧计数保存到frames中 + * @param time 获取的关联时间戳保存到time中 + * @return 成功返回值0，失败返回负值 + * @see CaptureFrame + */ + int32_t (*GetCapturePosition)(struct AudioCapture *capture, uint64_t *frames, struct AudioTimeStamp *time); +}; + +#endif /* AUDIO_CAPTURE_H */ +/** @} */ \ No newline at end of file diff --git a/zh-cn/device_api/hdi/audio/audio_control.h b/zh-cn/device_api/hdi/audio/audio_control.h new file mode 100644 index 0000000000000000000000000000000000000000..fb8962da8048014b1a4e151f7e8dda46f1750238 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_control.h @@ -0,0 +1,112 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_control.h + * + * @brief Audio控制的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_CONTROL_H +#define AUDIO_CONTROL_H +/** + * @brief AudioControl音频控制接口 + * + * 提供音频播放（render）或录音（capture）需要的公共控制驱动能力，包括Start、Stop、Pause、Resume、Flush等 + * + * @since 1.0 + * @version 1.0 + */ +struct AudioControl { + /** + * @brief 启动一个音频播放（render）或录音（capture）处理 + * + * @param handle 待操作的音频句柄 + * @return 成功返回值0，失败返回负值 + * @see Stop + */ + int32_t (*Start)(AudioHandle handle); + + /** + * @brief 停止一个音频播放（render）或录音（capture）处理 + * + * @param handle 待操作的音频句柄 + * @return 成功返回值0，失败返回负值 + * @see Start + */ + int32_t (*Stop)(AudioHandle handle); + + /** + * @brief 暂停一个音频播放（render）或录音（capture）处理 + * + * @param handle 待操作的音频句柄 + * @return 成功返回值0，失败返回负值 + * @see Resume + */ + int32_t (*Pause)(AudioHandle handle); + + /** + * @brief 恢复一个音频播放（render）或录音（capture）处理 + * + * @param handle 待操作的音频句柄 + * @return 成功返回值0，失败返回负值 + * @see Pause + */ + int32_t (*Resume)(AudioHandle handle); + + /** + * @brief 刷新音频缓冲区buffer中的数据 + * + * @param handle 待操作的音频句柄 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*Flush)(AudioHandle handle); + + /** + * @brief 设置或去设置设备的待机模式 + * + * @param handle 待操作的音频句柄 + * @return 设置设备待机模式成功返回值0，再次执行后去设置待机模式成功返回正值，失败返回负值 + */ + int32_t (*TurnStandbyMode)(AudioHandle handle); + + /** + * @brief Dump音频设备信息 + * + * @param handle 待操作的音频句柄 + * @param range Dump信息范围，分为简要信息、全量信息 + * @param fd 指定Dump目标文件 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*AudioDevDump)(AudioHandle handle, int32_t range, int32_t fd); +}; + +#endif /* AUDIO_CONTROL_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_manager.h b/zh-cn/device_api/hdi/audio/audio_manager.h new file mode 100644 index 0000000000000000000000000000000000000000..d0f6efcce30aacec9a1d85ccaa8627bc9278cd6a --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_manager.h @@ -0,0 +1,100 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_manager.h + * + * @brief Audio适配器管理及加载的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_MANAGER_H +#define AUDIO_MANAGER_H +/** + * @brief AudioManager音频适配器管理接口 + * + * 按照音频服务下发的音频适配器（声卡）描述符加载一个具体的音频适配器驱动程序 + * + * @see AudioAdapter + * @since 1.0 + * @version 1.0 + */ +struct AudioManager { + /** + * @brief 获取音频驱动中支持的所有适配器的列表 + * + * @param manager 待操作的音频管理接口对象 + * @param descs 获取到的音频适配器列表保存到descs中 + * @param size 获取到的音频适配器列表的长度保存到size中 + * @return 成功返回值0，失败返回负值 + * @see LoadAdapter + */ + int (*GetAllAdapters)(struct AudioAdapterManager *manager, struct AudioAdapterDescriptor **descs, int *size); + + /** + * @brief 加载一个音频适配器（声卡）的驱动 + * + * 加载一个具体的音频驱动，例如usb驱动，在具体实现中可能加载的是一个动态链接库（*.so） + * + * @param manager 待操作的音频管理接口对象 + * @param desc 待加载的音频适配器描述符 + * @param adapter 获取的音频适配器接口的对象实例保存到adapter中 + * @return 成功返回值0，失败返回负值 + * @see GetAllAdapters + * @see UnloadAdapter + */ + int (*LoadAdapter)(struct AudioAdapterManager *manager, const struct AudioAdapterDescriptor *desc, + struct AudioAdapter **adapter); + + /** + * @brief 卸载音频适配器（声卡）的驱动 + * + * @param manager 待操作的音频管理接口对象 + * @param adapter 待卸载的音频适配器接口的对象 + * @see LoadAdapter + */ + void (*UnloadAdapter)(struct AudioAdapterManager *manager, struct AudioAdapter *adapter); + + /** + * @brief 释放音频管理接口对象 + * + * @param 待操作的音频管理接口对象 + * @return 功返回值0，失败返回负值 + */ + bool (*ReleaseAudioManagerObject)(struct AudioManager *object); +}; +/** + * @brief 获取音频适配器管理接口的操作函数列表，详情参考{@link AudioManager} + * + * @return 成功返回一个音频适配器管理接口的对象，失败返回NULL + */ +struct AudioManager *GetAudioManagerFuncs(void); + +#endif /* AUDIO_MANAGER_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_render.h b/zh-cn/device_api/hdi/audio/audio_render.h new file mode 100644 index 0000000000000000000000000000000000000000..0a610363213fe23b9632600bbd96516e695d0247 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_render.h @@ -0,0 +1,164 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_render.h + * + * @brief Audio播放的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_RENDER_H +#define AUDIO_RENDER_H +/** + * @brief AudioRender音频播放接口 + * + * 提供音频播放支持的驱动能力，包括音频控制、音频属性、音频场景、音频音量、获取硬件延迟时间、播放音频帧数据（render frame）等 + * + * @see AudioControl + * @see AudioAttribute + * @see AudioScene + * @see AudioVolume + * @since 1.0 + * @version 1.0 + */ +struct AudioRender { + /** + * @brief 音频控制能力接口，详情参考{@link AudioControl} + */ + struct AudioControl control; + + /** + * @brief 音频属性能力接口，详情参考{@link AudioAttribute} + */ + struct AudioAttribute attr; + + /** + * @brief 音频场景能力接口，详情参考{@link AudioScene} + */ + struct AudioScene scene; + + /** + * @brief 音频音量能力接口，详情参考{@link AudioVolume} + */ + struct AudioVolume volume; + + /** + * @brief 获取音频硬件驱动估计的延迟时间 + * + * @param render 待操作的音频播放接口对象 + * @param ms 获取的延迟时间（单位：毫秒）保存到ms中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*GetLatency)(struct AudioRender *render, uint32_t *ms); + + /** + * @brief 往音频驱动中播放（render）一帧输出数据（放音，音频下行数据） + * + * @param render 待操作的音频播放接口对象 + * @param frame 待写入的输出数据的音频frame + * @param requestBytes 待写入的输出数据的音频frame大小（字节数） + * @param replyBytes 实际写入的音频数据长度（字节数），获取后保存到replyBytes中 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*RenderFrame)(struct AudioRender *render, const void *frame, uint64_t requestBytes, uint64_t *replyBytes); + + /** + * @brief 获取音频输出帧数的上一次计数 + * + * @param render 待操作的音频播放接口对象 + * @param frames 获取的音频帧计数保存到frames中 + * @param time 获取的关联时间戳保存到time中 + * @return 成功返回值0，失败返回负值 + * @see RenderFrame + */ + int32_t (*GetRenderPosition)(struct AudioRender *render, uint64_t *frames, struct AudioTimeStamp *time); + + /** + * @brief 设置一个音频的播放速度 + * + * @param render 待操作的音频播放接口对象 + * @param speed 待设置的播放速度 + * @return 成功返回值0，失败返回负值 + * @see GetRenderSpeed + */ + int32_t (*SetRenderSpeed)(struct AudioRender *render, float speed); + + /** + * @brief 获取一个音频当前的播放速度 + * + * @param render 待操作的音频播放接口对象 + * @param speed 获取的播放速度保存到speed中 + * @return 成功返回值0，失败返回负值 + * @see SetRenderSpeed + */ + int32_t (*GetRenderSpeed)(struct AudioRender *render, float *speed); + + /** + * @brief 设置音频播放的通道模式 + * + * @param render 待操作的音频播放接口对象 + * @param speed 待设置的通道模式 + * @return 成功返回值0，失败返回负值 + * @see GetChannelMode + */ + int32_t (*SetChannelMode)(struct AudioRender *render, enum AudioChannelMode mode); + + /** + * @brief 获取音频播放当前的通道模式 + * + * @param render 待操作的音频播放接口对象 + * @param mode 获取的通道模式保存到mode中 + * @return 成功返回值0，失败返回负值 + * @see SetChannelMode + */ + int32_t (*GetChannelMode)(struct AudioRender *render, enum AudioChannelMode *mode); + + /** + * @brief 注册音频回调函数，用于放音过程中缓冲区数据写、DrainBuffer完成通知 + * @param render 待操作的音频播放接口对象 + * @param callback 注册的回调函数 + * @param cookie 回调函数的入参 + * @return 成功返回值0，失败返回负值 + * @see RegCallback + */ + int32_t (*RegCallback)(struct AudioRender *render, RenderCallback callback, void* cookie); + + /** + * @brief 排空缓冲区中的数据 + * + * @param render 待操作的音频播放接口对象 + * @param type DrainBuffer的操作类型 + * @return 成功返回值0，失败返回负值 + * @see RegCallback + */ + int32_t (*DrainBuffer)(struct AudioRender *render, enum AudioDrainNotifyType *type); +}; +#endif /* AUDIO_RENDER_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_scene.h b/zh-cn/device_api/hdi/audio/audio_scene.h new file mode 100644 index 0000000000000000000000000000000000000000..9d95a18abb2cfbbccabaa968e54bbf58a8a55246 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_scene.h @@ -0,0 +1,80 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_scene.h + * + * @brief Audio场景的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_SCENE_H +#define AUDIO_SCENE_H +/** + * @brief AudioScene音频场景接口 + * + * 提供音频播放（render）或录音（capture）需要的公共场景驱动能力，包括选择音频场景等 + * + * @since 1.0 + * @version 1.0 + */ +struct AudioScene { + /** + * @brief 是否支持某个音频场景的配置 + * + * @param handle 待操作的音频句柄 + * @param scene 待获取的音频场景描述符 + * @param supported 是否支持的状态保存到supported中，true表示支持，false表示不支持 + * @return 成功返回值0，失败返回负值 + * @see SelectScene + */ + int32_t (*CheckSceneCapability)(AudioHandle handle, const struct AudioSceneDescriptor *scene, bool *supported); + + /** + * @brief 选择音频场景 + * + * + * @param handle 待操作的音频句柄 + * @param scene 待设置的音频场景描述符 + * @return 成功返回值0，失败返回负值 + * @see CheckSceneCapability + */ + int32_t (*SelectScene)(AudioHandle handle, const struct AudioSceneDescriptor *scene); +}; + +#endif /* AUDIO_SCENE_H */ +/** @} */ diff --git a/zh-cn/device_api/hdi/audio/audio_types.h b/zh-cn/device_api/hdi/audio/audio_types.h new file mode 100644 index 0000000000000000000000000000000000000000..5349673193224595fa05d0808d254e7902eb3095 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_types.h @@ -0,0 +1,398 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_types.h + * + * @brief Audio模块接口定义中使用的自定义数据类型 + * + * Audio模块接口定义中使用的自定义数据类型，包括音频端口、适配器描述符、设备描述符、场景描述符、采样属性、时间戳等 + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef AUDIO_TYPES_H +#define AUDIO_TYPES_H +/** + * @brief 音频句柄 + */ +typedef void *AudioHandle; + +/** + * @brief 音频端口的类型 + */ +enum AudioPortDirection { + PORT_OUT = 0x1u, /**< 音频输出端口 */ + PORT_IN = 0x2u, /**< 音频输入端口 */ + PORT_OUT_IN = 0x3u, /**< 音频输出/入端口, 同时支持输出和输入能力（OUT | IN） */ +}; + +/** + * @brief 音频端口 + */ +struct AudioPort { + enum AudioPortDirection dir; /**< 音频端口的类型，详情参考{@link AudioPortDirection} */ + unsigned int portId; /**< 音频端口的ID */ + const char *portName; /**< 音频端口的名称 */ +}; + +/** + * @brief 音频适配器描述符 + * + * 一个音频适配器（adapter）是一个声卡的端口驱动集合，包含输出端口、输入端口， + * 其中一个端口对应着多个PIN脚，一个PIN脚对应着一个实体的器件（例如喇叭、有线耳机） + */ +struct AudioAdapterDescriptor { + const char *adapterName; /**< 音频适配器的名称 */ + unsigned int portNum; /**< 一个音频适配器支持的端口数目 */ + struct AudioPort *ports; /**< 一个音频适配器支持的端口列表 */ +}; + +/** + * @brief 音频适配器端口的PIN脚 + */ +enum AudioPortPin { + PIN_NONE = 0x0u, /**< 无效PIN */ + PIN_OUT_SPEAKER = 0x1u, /**< 喇叭输出 */ + PIN_OUT_HEADSET = 0x2u, /**< 有线耳机输出 */ + PIN_OUT_LINEOUT = 0x4u, /**< Lineout输出 */ + PIN_OUT_HDMI = 0x8u, /**< HDMI输出 */ + PIN_IN_MIC = 0x8000001u, /**< Mic输入 */ + PIN_IN_HS_MIC = 0x8000002u, /**< 有线耳机Mic输入 */ + PIN_IN_LINEIN = 0x8000004u, /**< Linein输入 */ +}; + +/** + * @brief 音频设备描述符 + */ +struct AudioDeviceDescriptor { + unsigned int portId; /**< 音频端口ID */ + enum AudioPortPin pins; /**< 音频端口上的PIN脚（输出、输入），详情参考{@link AudioPortPin} */ + const char *desc; /**< 以字符串命名的音频设备 */ +}; + +/** + * @brief 音频类型（category） + */ +enum AudioCategory { + AUDIO_IN_MEDIA = 0, /**< 媒体 */ + AUDIO_IN_COMMUNICATION, /**< 通信 */ +}; + +/** + * @brief 音频场景描述符 + */ +struct AudioSceneDescriptor { + /** + * @brief 音频场景描述 + */ + union SceneDesc { + unsigned int id; /**< 音频场景的ID */ + const char *desc; /**< 以字符串命名的音频场景 */ + } scene; /**< 音频场景的名称 */ + struct AudioDeviceDescriptor desc; /**< 音频设备描述符 */ +}; + +/** + * @brief 音频格式 + */ +enum AudioFormat { + AUDIO_FORMAT_PCM_8_BIT = 0x1u, /**< 8bit位宽pcm格式 */ + AUDIO_FORMAT_PCM_16_BIT = 0x2u, /**< 16bit位宽pcm格式 */ + AUDIO_FORMAT_PCM_24_BIT = 0x3u, /**< 24bit位宽pcm格式 */ + AUDIO_FORMAT_PCM_32_BIT = 0x4u, /**< 32bit位宽pcm格式 */ + AUDIO_FORMAT_AAC_MAIN = 0x1000001u, /**< AAC MAIN格式 */ + AUDIO_FORMAT_AAC_LC = 0x1000002u, /**< AAC LC格式 */ + AUDIO_FORMAT_AAC_LD = 0x1000003u, /**< AAC LD格式 */ + AUDIO_FORMAT_AAC_ELD = 0x1000004u, /**< AAC ELD格式 */ + AUDIO_FORMAT_AAC_HE_V1 = 0x1000005u, /**< AAC HE_V1格式 */ + AUDIO_FORMAT_AAC_HE_V2 = 0x1000006u, /**< AAC HE_V2格式 */ +}; + +/** + * @brief 音频通道掩码（mask） + * + * 定义音频声道的位置 + */ +enum AudioChannelMask { + AUDIO_CHANNEL_FRONT_LEFT = 0x1, /**< 声道布局前左 */ + AUDIO_CHANNEL_FRONT_RIGHT = 0x2, /**< 声道布局前右 */ + AUDIO_CHANNEL_MONO = 0x1u, /**< 单声道 */ + AUDIO_CHANNEL_STEREO = 0x3u, /**< 立体声，由左右声道组成（FRONT_LEFT | FRONT_RIGHT） */ +}; + +/** + * @brief 音频采样频率MASK + */ +enum AudioSampleRatesMask { + AUDIO_SAMPLE_RATE_MASK_8000 = 0x1u, /**< 8K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_12000 = 0x2u, /**< 12K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_11025 = 0x4u, /**< 11.025K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_16000 = 0x8u, /**< 16K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_22050 = 0x10u, /**< 22.050K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_24000 = 0x20u, /**< 24K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_32000 = 0x40u, /**< 32K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_44100 = 0x80u, /**< 44.1K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_48000 = 0x100u, /**< 48K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_64000 = 0x200u, /**< 64K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_96000 = 0x400u, /**< 96K 采样频率 */ + AUDIO_SAMPLE_RATE_MASK_INVALID = 0xFFFFFFFFu, /**< 无效的采样频率 */ +}; + +/** + * @brief 音频采样属性 + */ +struct AudioSampleAttributes { + enum AudioCategory type; /**< 音频类型，详情参考{@link AudioCategory} */ + bool interleaved; /**< 音频数据交织的标记 */ + enum AudioFormat format; /**< 音频数据格式，详情参考{@link AudioFormat} */ + unsigned int sampleRate; /**< 音频采样频率 */ + uint32_t channelCount; /**< 音频通道数目，如单通道（mono）为1、立体声（stereo）为2 */ +}; + +/** + * @brief 音频时间戳 + * + * 时间定义，POSIX timespec的替代品 + */ +struct AudioTimeStamp { + int64_t tvSec; /**< tvSec时间，单位：秒 */ + int64_t tvNSec; /**< tvNSec时间，单位：纳秒 */ +}; + +/** + * @brief 音频端口的数据透传模式 + */ +enum AudioPortPassthroughMode { + PORT_PASSTHROUGH_LPCM = 0x1, /**< 立体声pcm */ + PORT_PASSTHROUGH_RAW = 0x2, /**< HDMI透传 */ + PORT_PASSTHROUGH_HBR2LBR = 0x4, /**< 蓝光次世代音频降规格输出 */ + PORT_PASSTHROUGH_AUTO = 0x8, /**< 根据HDMI EDID能力自动匹配 */ +}; + +/** + * @brief 音频子端口的支持能力 + */ +struct AudioSubPortCapability { + unsigned int portId; /**< 子端口ID */ + const char *desc; /**< 以字符串命名的子端口 */ + enum AudioPortPassthroughMode mask; /**< 数据透传模式，详情参考{@link AudioPortPassthroughMode} */ +}; + +/** + * @brief 原始音频样本格式 + */ +enum AudioSampleFormat { + /* 8 bits */ + AUDIO_SAMPLE_FORMAT_S8, /**< 8bit位宽有符号交织样本 */ + AUDIO_SAMPLE_FORMAT_S8P, /**< 8bit位宽有符号非交织样本 */ + AUDIO_SAMPLE_FORMAT_U8, /**< 8bit位宽无符号交织样本 */ + AUDIO_SAMPLE_FORMAT_U8P, /**< 8bit位宽无符号非交织样本 */ + /* 16 bits */ + AUDIO_SAMPLE_FORMAT_S16, /**< 16bit位宽有符号交织样本 */ + AUDIO_SAMPLE_FORMAT_S16P, /**< 16bit位宽有符号非交织样本 */ + AUDIO_SAMPLE_FORMAT_U16, /**< 16bit位宽无符号符号交织样本 */ + AUDIO_SAMPLE_FORMAT_U16P, /**< 16bit位宽无符号符号非交织样本 */ + /* 24 bits */ + AUDIO_SAMPLE_FORMAT_S24, /**< 24bit位宽有符号交织样本 */ + AUDIO_SAMPLE_FORMAT_S24P, /**< 24bit位宽有符号非交织样本 */ + AUDIO_SAMPLE_FORMAT_U24, /**< 24bit位宽无符号符号交织样本 */ + AUDIO_SAMPLE_FORMAT_U24P, /**< 24bit位宽无符号非交织样本 */ + /* 32 bits */ + AUDIO_SAMPLE_FORMAT_S32, /**< 32bit位宽有符号交织样本 */ + AUDIO_SAMPLE_FORMAT_S32P, /**< 32bit位宽有符号非交织样本 */ + AUDIO_SAMPLE_FORMAT_U32, /**< 32bit位宽无符号交织样本 */ + AUDIO_SAMPLE_FORMAT_U32P, /**< 32bit位宽无符号非交织样本 */ + /* 64 bits */ + AUDIO_SAMPLE_FORMAT_S64, /**< 64bit位宽有符号交织样本 */ + AUDIO_SAMPLE_FORMAT_S64P, /**< 64bit位宽有符号非交织样本 */ + AUDIO_SAMPLE_FORMAT_U64, /**< 64bit位宽无符号交织样本 */ + AUDIO_SAMPLE_FORMAT_U64P, /**< 64bit位宽无符号非交织样本 */ + /* float double */ + AUDIO_SAMPLE_FORMAT_F32, /**< 32bit位宽浮点型交织样本 */ + AUDIO_SAMPLE_FORMAT_F32P, /**< 64bit位宽浮点型非交织样本 */ + AUDIO_SAMPLE_FORMAT_F64, /**< 64bit位宽双精度浮点型交织样本 */ + AUDIO_SAMPLE_FORMAT_F64P, /**< 64bit位宽双精度浮点型非交织样本 */ +}; + +/** + * @brief 音频端口的支持能力 + */ +struct AudioPortCapability { + unsigned int deviceType; /**< 设备输出、输入类型 */ + unsigned int deviceId; /**< 绑定（bind）设备ID，唯一的设备识别符 */ + bool hardwareMode; /**< 是否支持设备绑定处理 */ + unsigned int formatNum; /**< 支持的音频格式数目 */ + enum AudioFormat *formats; /**< 支持的音频格式，详情参考{@link AudioFormat} */ + unsigned int sampleRateMasks; /**< 支持的音频采样频率（8k、16k、32k、48k） */ + enum AudioChannelMask channelMasks; /**< 设备的声道布局掩码（mask），详情参考{@link AudioChannelMask} */ + unsigned int channelCount; /**< 最大支持的声道总数 */ + unsigned int subPortsNum; /**< 支持的子端口数目（仅用于输出设备） */ + struct AudioSubPortCapability *subPorts; /**< 支持的子端口列表 */ +}; + +/** + * @brief 音频播放的通道模式 + * + * @attention 下面的模式是针对双通道立体声的音频播放而设置，其他不支持 + */ +enum AudioChannelMode { + AUDIO_CHANNEL_NORMAL = 0, /**< 正常模式，不做处理 */ + AUDIO_CHANNEL_BOTH_LEFT, /**< 两个声道全部为左声道声音 */ + AUDIO_CHANNEL_BOTH_RIGHT, /**< 两个声道全部为右声道声音 */ + AUDIO_CHANNEL_EXCHANGE, /**< 左右声道数据互换，左声道为右声道声音，右声道为左声道声音 */ + AUDIO_CHANNEL_MIX, /**< 左右两个声道输出为左右声道相加（混音） */ + AUDIO_CHANNEL_LEFT_MUTE, /**< 左声道静音，右声道播放原右声道声音 */ + AUDIO_CHANNEL_RIGHT_MUTE, /**< 右声道静音，左声道播放原左声道声音 */ + AUDIO_CHANNEL_BOTH_MUTE, /**< 左右声道均静音 */ +}; + +/** + * @brief DrainBuffer函数结束类型 + */ +enum AudioDrainNotifyType { + AUDIO_DRAIN_NORMAL_MODE, /**< DrainBuffer在所有数据播放结束后返回 */ + AUDIO_DRAIN_EARLY_MODE, /**< DrainBuffer()在当前曲目的所有数据播放完之前返回，以便留出时间给音频服务做连续性曲目切换 */ +}; + +/** + * @brief 回调函数通知事件类型 + */ +enum AudioCallbackType { + AUDIO_NONBLOCK_WRITE_COMPELETED, /**< 非阻塞式写完成 */ + AUDIO_DRAIN_COMPELETED, /**< DrainBuffer完成 */ + AUDIO_FLUSH_COMPLETED, /**< Flush完成 */ + AUDIO_RENDER_FULL, /**< Render缓冲区已满 */ + AUDIO_ERROR_OCCUR, /**< 发生了错误 */ +}; + +/** + * @brief mmap缓冲区描述符 + */ +struct AudioMmapBufferDescripter { + void *memoryAddress; /**< 指向mmap缓冲区的指针 */ + int32_t memoryFd; /**< mmap缓冲区的文件描述符 */ + int32_t totalBufferFrames; /**< 缓冲区总大小，单位：帧 */ + int32_t transferFrameSize; /**< 传输大小，单位：帧 */ + int32_t isShareable; /**< mmap缓冲区是否可以在进程间共享 */ +}; + +/** + * @brief 音频端口角色 + */ +enum AudioPortRole { + AUDIO_PORT_UNASSIGNED_ROLE = 0, /**< 未指定端口角色 */ + AUDIO_PORT_SOURCE_ROLE = 1, /**< 指定端口为发送端角色 */ + AUDIO_PORT_SINK_ROLE = 2, /**< 指定端口为接受端角色 */ +}; + +/** + * @brief 音频端口类型. + */ +enum AudioPortType { + AUDIO_PORT_UNASSIGNED_TYPE = 0, /**< 未指定端口类型 */ + AUDIO_PORT_DEVICE_TYPE = 1, /**< 指定端口为设备类型 */ + AUDIO_PORT_MIX_TYPE = 2, /**< 指定端口类型为复合类型 */ + AUDIO_PORT_SESSION_TYPE = 3, /**< 指定端口为会话类型 */ +}; + +/** + * @brief 音频设备拓展信息. + */ +struct AudioDevExtInfo { + int32_t moduleId; /**< 音频流绑定的模块ID */ + enum AudioPortPin type; /**< 音频端口上的PIN脚（输出、输入），详情参考{@link AudioPortPin} */ + const char *desc; /**< 地址描述 */ +}; + +/** + * @brief 音轨拓展信息 + */ +struct AudioMixExtInfo { + int32_t moduleId; /**< 流所属模块标识符 */ + int32_t streamId; /**< 由调用者传递的Render或Capture标识符 */ +}; + +/** + * @brief 端口会话类型 + */ +enum AudioSessionType { + AUDIO_OUTPUT_STAGE_SESSION = 0, /**< 会话绑定到指定输出流 */ + AUDIO_OUTPUT_MIX_SESSION, /**< 会话绑定到特定音轨 */ + AUDIO_ALLOCATE_SESSION, /**< 会话ID需重新申请 */ + AUDIO_INVALID_SESSION, /**< 无效会话类型 */ +}; + +/** + * @brief 会话拓展信息 + * @see AudioSessionType + */ +struct AudioSessionExtInfo { + enum AudioSessionType sessionType; /**< 音频会话类型 */ +}; + +/** + * @brief 音频路由节点. + * @see AudioPortRole + * @see AudioPortType + * @see AudioDevExtInfo + * + */ +struct AudioRouteNode { + int32_t portId; /**< 音频端口ID */ + enum AudioPortRole role; /**< 指定端口角色为sink或source */ + enum AudioPortType type; /**< 指定端口类型为device, mix ... */ + union { + struct AudioDevExtInfo device; /* 设备特定信息 */ + struct AudioMixExtInfo mix; /* 音轨特定信息 */ + struct AudioSessionExtInfo session; /* 会话特定信息 */ + } ext; +}; + +/** + * @brief 音频路由信息. + */ +struct AudioRoute { + uint32_t sourcesNum; /**< 发送端节点数量 */ + const struct AudioRouteNode *sources; /**< 发送端列表 */ + uint32_t sinksNum; /**< 接受端节点数量 */ + const struct AudioRouteNode *sinks; /**< 接受端列表 */ +}; + +/** + * @brief 回调函数指针 + * + * @param AudioCallbackType 回调函数响应类型 + * @param reserved 保留字段 + * @param cookie 用于传递数据 + * @return 成功返回值0，失败返回负值 + * @see RegCallback + */ +typedef int32_t (*RenderCallback)(enum AudioCallbackType, void *reserved, void *cookie); + +#endif /* AUDIO_TYPES_H */ diff --git a/zh-cn/device_api/hdi/audio/audio_volume.h b/zh-cn/device_api/hdi/audio/audio_volume.h new file mode 100644 index 0000000000000000000000000000000000000000..baa5ba0d7819e1ae174fd8a7d390a9ae7b31fd36 --- /dev/null +++ b/zh-cn/device_api/hdi/audio/audio_volume.h @@ -0,0 +1,133 @@ +/* + * Copyright (c) 2022 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 Audio + * @{ + * + * @brief Audio模块接口定义 + * + * 音频接口涉及自定义类型、驱动加载接口、驱动适配器接口、音频播放（render）接口、音频录音（capture）接口等 + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file audio_volume.h + * + * @brief Audio音量的接口定义文件 + * + * @since 1.0 + * @version 1.0 + */ + + +#ifndef AUDIO_VOLUME_H +#define AUDIO_VOLUME_H +/** + * @brief AudioVolume音频音量接口 + * + * 提供音频播放（render）或录音（capture）需要的公共音量驱动能力，包括静音操作、设置音量、设置增益等 + * + * @since 1.0 + * @version 1.0 + */ +struct AudioVolume { + /** + * @brief 设置音频的静音状态 + * + * @param handle 待操作的音频句柄 + * @param mute 待设置的静音状态，true表示静音操作、false表示取消静音操作 + * @return 成功返回值0，失败返回负值 + * @see GetMute + */ + int32_t (*SetMute)(AudioHandle handle, bool mute); + + /** + * @brief 获取音频的静音状态 + * + * @param handle 待操作的音频句柄 + * @param mute 获取的静音状态保存到mute中，true表示静音操作、false表示取消静音操作 + * @return 成功返回值0，失败返回负值 + * @see SetMute + */ + int32_t (*GetMute)(AudioHandle handle, bool *mute); + + /** + * @brief 设置一个音频流的音量 + * + * 音量的取值范围是0.0~1.0，如果音频服务中的音量等级为15级（0 ~ 15）， + * 则音量的映射关系为0.0表示静音，1.0表示最大音量等级（15） + * + * @param handle 待操作的音频句柄 + * @param volume 待设置的音量，范围0.0~1.0 + * @return 成功返回值0，失败返回负值 + */ + int32_t (*SetVolume)(AudioHandle handle, float volume); + + /** + * @brief 获取一个音频流的音量 + * + * @param handle 待操作的音频句柄 + * @param volume 获取的音量保存到volume中，范围0.0~1.0 + * @return 成功返回值0，失败返回负值 + * @see SetVolume + */ + int32_t (*GetVolume)(AudioHandle handle, float *volume); + + /** + * @brief 获取音频流增益的阈值 + * + * 在具体的功能实现中，可以根据芯片平台的实际情况来进行处理： + * + * @param handle 待操作的音频句柄 + * @param min 获取的音频增益的阈值下限保存到min中 + * @param max 获取的音频增益的阈值上限保存到max中 + * @return 成功返回值0，失败返回负值 + * @see GetGain + * @see SetGain + */ + int32_t (*GetGainThreshold)(AudioHandle handle, float *min, float *max); + + /** + * @brief 获取音频流的增益 + * + * @param handle 待操作的音频句柄 + * @param gain 保存当前获取到的增益到gain中 + * @return 成功返回值0，失败返回负值 + * @see GetGainThreshold + * @see SetGain + */ + int32_t (*GetGain)(AudioHandle handle, float *gain); + + /** + * @brief 设置音频流的增益 + * + * @param handle 待操作的音频句柄 + * @param gain gain 待设置的增益 + * @return 成功返回值0，失败返回负值 + * @see GetGainThreshold + * @see GetGain + */ + int32_t (*SetGain)(AudioHandle handle, float gain); +}; + +#endif /* AUDIO_VOLUME_H */ +/** @} */