diff --git a/include/dsAVDTypes.h b/include/dsAVDTypes.h index bb02502..a23c44d 100644 --- a/include/dsAVDTypes.h +++ b/include/dsAVDTypes.h @@ -436,6 +436,52 @@ typedef struct _dsAudioPortConfig_t { const dsVideoPortPortId_t *connectedVOPs; ///< Connected video port } dsAudioPortConfig_t; +/** + * @brief Maximum length of the audio configuration name, including the terminating NUL. + * This value is frozen, it is part of the inter-process ABI and must never change. + */ +#define DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN 64 + +/** + * @brief Default capacity of dsApplicationAudioConfigList_t::config. + * Implementations must derive the caller's real capacity from + * dsApplicationAudioConfigList_t::size to remain compatible with callers built + * against different DS_MAX_APPLICATION_AUDIO_CONFIGS values. + */ +#define DS_MAX_APPLICATION_AUDIO_CONFIGS 64 + +/** + * @brief Canonical application audio configuration names. + * Platform support is discovered via dsGetApplicationAudioConfigList(). + */ +#define DS_APPLICATION_AUDIO_CONFIG_CONTINUOUS_AUDIO_OUTPUT "CONTINUOUS_AUDIO_OUTPUT" ///< Digital outputs continuously emit valid silent frames in the currently-active output format across brief input interruptions, keeping the downstream decoder locked + +/** + * @brief Structure that holds audio configuration name. + * Layout is frozen — fields are never added, removed, or reordered. + * @note Used in @link dsAudio.h @endlink + */ +typedef struct _dsApplicationAudioConfig_t { + char configName[DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN]; ///< NUL-terminated configuration name, a NUL must occur within the bound +} dsApplicationAudioConfig_t; + +/** + * @brief List of supported application audio configurations. + * The caller sets @c size to its compiled sizeof(dsApplicationAudioConfigList_t). + * The implementation derives the caller's capacity as + * (size - offsetof(dsApplicationAudioConfigList_t, config)) / sizeof(dsApplicationAudioConfig_t) + * and writes returnedCount = min(totalCount, capacity) entries. + * totalCount > returnedCount means the caller's view was smaller than the platform's + * configuration set — truncation is explicit and detectable, never silent. + * @note Used in @link dsAudio.h @endlink + */ +typedef struct _dsApplicationAudioConfigList_t { + uint32_t size; ///< [in] sizeof(dsApplicationAudioConfigList_t) as compiled by the caller + uint32_t totalCount; ///< [out] total number of configurations supported by the platform + uint32_t returnedCount; ///< [out] number of entries written to config[] + dsApplicationAudioConfig_t config[DS_MAX_APPLICATION_AUDIO_CONFIGS]; ///< [out] configuration entries; config[0..returnedCount-1] are valid +} dsApplicationAudioConfigList_t; + /* End of DSHAL_AUDIO_TYPES doxygen group */ /** * @} diff --git a/include/dsAudio.h b/include/dsAudio.h index f02cbf2..4a5ed8c 100644 --- a/include/dsAudio.h +++ b/include/dsAudio.h @@ -1744,6 +1744,99 @@ dsError_t dsGetSecondaryLanguage(intptr_t handle, char* sLang); */ dsError_t dsSetAudioMixerLevels (intptr_t handle, dsAudioInput_t aInput, int volume); +/** + * @brief Sets the application-specific audio configuration. + * + * Some applications may require custom audio settings, such as enabling + * continuous audio output to prevent audio glitches, muting, or format + * re-lock events on downstream devices when the input stream to MS12 is + * temporarily interrupted. + * + * This interface is designed to be extensible and can accommodate additional + * application-specific audio configuration requirements in the future. + * + * Applications should call dsGetApplicationAudioConfigList() to retrieve the list of supported audio configurations + * and then call dsSetApplicationAudioConfig() with a supported audioConfig name (audioConfig->configName). + * + * @param[in] handle - Pass 0 for global audio configuration (currently the only supported scope). + * @param[in] audioConfig - Configuration name entry (see ::dsApplicationAudioConfig_t). + * configName must contain a NUL terminator within + * DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN bytes; implementations + * must validate this bound and must not read beyond it. + * @param[in] enable - enable/disable audio configuration ( @a true to enable, @a false to disable) + * + * @return dsError_t - Status + * @retval dsERR_NONE - Success + * @retval dsERR_NOT_INITIALIZED - Module is not initialised + * @retval dsERR_INVALID_PARAM - audioConfig is NULL, configName has no NUL terminator within + * DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN bytes, or handle is non-zero + * @retval dsERR_OPERATION_NOT_SUPPORTED - When the specified audio configuration is not supported by the platform + * @retval dsERR_GENERAL - Underlying undefined platform error + * + * @pre dsAudioPortInit() should be called before calling this API. + * @post The setting is not retained across dsAudioPortTerm() / power cycle, + * Caller should re-apply it as needed. + * @note Idempotent - calling with the value already set returns dsERR_NONE. + * @note Default state should be disabled for audio configuration. + * @warning This API is Not thread safe. + * @see dsGetApplicationAudioConfigList() + * + */ +dsError_t dsSetApplicationAudioConfig(intptr_t handle, const dsApplicationAudioConfig_t* audioConfig, bool enable); + +/** + * @brief Gets the application-specific audio configuration. + * Returns whether the requested specific audio configuration (see dsSetApplicationAudioConfig()) + * is currently enabled or disabled. + * + * @param[in] handle - Pass 0 for global audio configuration (currently the only supported scope). + * @param[in] audioConfig - Configuration name entry (see ::dsApplicationAudioConfig_t). + * configName must contain a NUL terminator within + * DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN bytes; implementations + * must validate this bound and must not read beyond it. + * @param[out] enable - True if audio configuration is enabled, false otherwise. + * + * @return dsError_t - Status + * @retval dsERR_NONE - Success + * @retval dsERR_NOT_INITIALIZED - Module is not initialised + * @retval dsERR_INVALID_PARAM - audioConfig is NULL, enable is NULL, configName has no NUL terminator within + * DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN bytes, or handle is non-zero + * @retval dsERR_OPERATION_NOT_SUPPORTED - When the specified audio configuration is not supported by the platform + * @retval dsERR_GENERAL - Underlying undefined platform error + * + * @pre dsAudioPortInit() should be called before calling this API. + * @note Default state should be disabled for audio configuration. + * @warning This API is Not thread safe. + * @see dsSetApplicationAudioConfig() + * + */ +dsError_t dsGetApplicationAudioConfig(intptr_t handle, const dsApplicationAudioConfig_t* audioConfig, bool *enable); + +/** + * @brief Gets the list of supported audio configurations. + * The caller must set audioConfigList->size = sizeof(dsApplicationAudioConfigList_t) + * before calling. See ::dsApplicationAudioConfigList_t for the capacity and + * truncation contract. + * + * @param[in] handle - Pass 0 for global audio configuration (currently the only supported scope). + * @param[in,out] audioConfigList - pointer to List of supported audio configurations (see ::dsApplicationAudioConfigList_t) + * + * @return dsError_t - Status + * @retval dsERR_NONE - Success + * @retval dsERR_NOT_INITIALIZED - Module is not initialised + * @retval dsERR_INVALID_PARAM - audioConfigList is NULL, handle is non-zero, or size is smaller than + * offsetof(dsApplicationAudioConfigList_t, config) + sizeof(dsApplicationAudioConfig_t) + * @retval dsERR_OPERATION_NOT_SUPPORTED - The attempted operation is not supported + * @retval dsERR_GENERAL - Underlying undefined platform error + * + * @pre dsAudioPortInit() should be called before calling this API. + * + * @warning This API is Not thread safe. + * + * @see dsSetApplicationAudioConfig() + */ +dsError_t dsGetApplicationAudioConfigList(intptr_t handle, dsApplicationAudioConfigList_t* audioConfigList); + #ifdef __cplusplus } #endif