From 1072c425965eb91744c5fa2b655a80c3bd6bec7e Mon Sep 17 00:00:00 2001 From: "shashank.kumar@sky.uk" Date: Mon, 6 Jul 2026 13:12:56 +0100 Subject: [PATCH 1/2] gh#197: Enable/Disable applicatio specific audio configuration data. --- include/dsAVDTypes.h | 27 +++++++++++++++ include/dsAudio.h | 82 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) diff --git a/include/dsAVDTypes.h b/include/dsAVDTypes.h index bb025025..cee71af6 100644 --- a/include/dsAVDTypes.h +++ b/include/dsAVDTypes.h @@ -436,6 +436,33 @@ typedef struct _dsAudioPortConfig_t { const dsVideoPortPortId_t *connectedVOPs; ///< Connected video port } dsAudioPortConfig_t; +/** + * @brief Maximum number of application audio configurations. + */ +#define DS_MAX_APPLICATION_AUDIO_CONFIGS 64 +/** + * @brief Maximum length of the audio configuration name, including the terminating NUL. + */ +#define DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN 64 + +/** + * @brief Structure that holds audio configuration name. + * @note Used in @link dsAudio.h @endlink + */ +typedef struct _dsApplicationAudioConfig_t { + char configName[DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN]; ///< NUL-terminated configuration name +} dsApplicationAudioConfig_t; + +/** + * @brief List of supported application audio configurations. + * count indicates the number of entries in config[]. + * @note Used in @link dsAudio.h @endlink + */ +typedef struct _dsApplicationAudioConfigList_t { + dsApplicationAudioConfig_t config[DS_MAX_APPLICATION_AUDIO_CONFIGS]; ///< Supported configurations + int count; ///< Number of valid entries in config[] (0..DS_MAX_APPLICATION_AUDIO_CONFIGS) +} dsApplicationAudioConfigList_t; + /* End of DSHAL_AUDIO_TYPES doxygen group */ /** * @} diff --git a/include/dsAudio.h b/include/dsAudio.h index f02cbf21..7d863c13 100644 --- a/include/dsAudio.h +++ b/include/dsAudio.h @@ -1744,6 +1744,88 @@ 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 - audio configuration name (see ::dsApplicationAudioConfig_t) + * @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 - When parameter passed to this function is invalid 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 - audio configuration name (see ::dsApplicationAudioConfig_t) + * @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 - When parameter passed to this function is invalid 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. + * + * @param[in] handle - Pass 0 for global audio configuration (currently the only supported scope). + * @param[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 or handle is non-zero + * @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 From 8a8b8936408579476b29529e450511ac17dd2f6b Mon Sep 17 00:00:00 2001 From: "shashank.kumar@sky.uk" Date: Mon, 13 Jul 2026 12:16:49 +0100 Subject: [PATCH 2/2] Added changes as per review comments --- include/dsAVDTypes.h | 33 ++++++++++++++++++++++++++------- include/dsAudio.h | 25 ++++++++++++++++++------- 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/include/dsAVDTypes.h b/include/dsAVDTypes.h index cee71af6..a23c44de 100644 --- a/include/dsAVDTypes.h +++ b/include/dsAVDTypes.h @@ -437,30 +437,49 @@ typedef struct _dsAudioPortConfig_t { } dsAudioPortConfig_t; /** - * @brief Maximum number of application audio configurations. + * @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 Maximum length of the audio configuration name, including the terminating NUL. + * @brief Canonical application audio configuration names. + * Platform support is discovered via dsGetApplicationAudioConfigList(). */ -#define DS_MAX_APPLICATION_AUDIO_CONFIG_NAME_LEN 64 +#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 + 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. - * count indicates the number of entries in config[]. + * 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 { - dsApplicationAudioConfig_t config[DS_MAX_APPLICATION_AUDIO_CONFIGS]; ///< Supported configurations - int count; ///< Number of valid entries in config[] (0..DS_MAX_APPLICATION_AUDIO_CONFIGS) + 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 7d863c13..4a5ed8cd 100644 --- a/include/dsAudio.h +++ b/include/dsAudio.h @@ -1759,13 +1759,17 @@ dsError_t dsSetAudioMixerLevels (intptr_t handle, dsAudioInput_t aInput, int vol * 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 - audio configuration name (see ::dsApplicationAudioConfig_t) + * @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 - When parameter passed to this function is invalid or handle is non-zero + * @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 * @@ -1786,13 +1790,17 @@ dsError_t dsSetApplicationAudioConfig(intptr_t handle, const dsApplicationAudio * is currently enabled or disabled. * * @param[in] handle - Pass 0 for global audio configuration (currently the only supported scope). - * @param[in] audioConfig - audio configuration name (see ::dsApplicationAudioConfig_t) + * @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 - When parameter passed to this function is invalid or handle is non-zero + * @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 * @@ -1802,19 +1810,22 @@ dsError_t dsSetApplicationAudioConfig(intptr_t handle, const dsApplicationAudio * @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[out] audioConfigList - pointer to List of supported audio configurations (see ::dsApplicationAudioConfigList_t) + * @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 or handle is non-zero + * @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 *