/* Copyright (C) 2014 by Leonhard Oelke This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ #pragma once #include "obs.h" /** * @file * @brief header for audio controls * * @brief Audio controls for use in GUIs */ #ifdef __cplusplus extern "C" { #endif /** * @brief Fader types */ enum obs_fader_type { /** * @brief A simple cubic fader for controlling audio levels * * This is a very common type of software fader since it yields good * results while being quite performant. * The input value is mapped to mul values with the simple formula x^3. */ OBS_FADER_CUBIC, /** * @brief A fader compliant to IEC 60-268-18 * * This type of fader has several segments with different slopes that * map deflection linearly to dB values. The segments are defined as * in the following table: * @code Deflection | Volume ------------------------------------------ [ 100 %, 75 % ] | [ 0 dB, -9 dB ] [ 75 %, 50 % ] | [ -9 dB, -20 dB ] [ 50 %, 30 % ] | [ -20 dB, -30 dB ] [ 30 %, 15 % ] | [ -30 dB, -40 dB ] [ 15 %, 7.5 % ] | [ -40 dB, -50 dB ] [ 7.5 %, 2.5 % ] | [ -50 dB, -60 dB ] [ 2.5 %, 0 % ] | [ -60 dB, -inf dB ] @endcode */ OBS_FADER_IEC, /** * @brief Logarithmic fader */ OBS_FADER_LOG }; /** * @brief Create a fader * @param type the type of the fader * @return pointer to the fader object * * A fader object is used to map input values from a gui element to dB and * subsequently multiplier values used by libobs to mix audio. * The current "position" of the fader is internally stored as dB value. */ EXPORT obs_fader_t *obs_fader_create(enum obs_fader_type type); /** * @brief Destroy a fader * @param fader pointer to the fader object * * Destroy the fader and free all related data */ EXPORT void obs_fader_destroy(obs_fader_t *fader); /** * @brief Set the fader dB value * @param fader pointer to the fader object * @param db new dB value * @return true if value was set without clamping */ EXPORT bool obs_fader_set_db(obs_fader_t *fader, const float db); /** * @brief Get the current fader dB value * @param fader pointer to the fader object * @return current fader dB value */ EXPORT float obs_fader_get_db(obs_fader_t *fader); /** * @brief Set the fader value from deflection * @param fader pointer to the fader object * @param def new deflection * @return true if value was set without clamping * * This sets the new fader value from the supplied deflection, in case the * resulting value was clamped due to limits this function will return false. * The deflection is typically in the range [0.0, 1.0] but may be higher in * order to provide some amplification. In order for this to work the high dB * limit has to be set. */ EXPORT bool obs_fader_set_deflection(obs_fader_t *fader, const float def); /** * @brief Get the current fader deflection * @param fader pointer to the fader object * @return current fader deflection */ EXPORT float obs_fader_get_deflection(obs_fader_t *fader); /** * @brief Set the fader value from multiplier * @param fader pointer to the fader object * @return true if the value was set without clamping */ EXPORT bool obs_fader_set_mul(obs_fader_t *fader, const float mul); /** * @brief Get the current fader multiplier value * @param fader pointer to the fader object * @return current fader multiplier */ EXPORT float obs_fader_get_mul(obs_fader_t *fader); /** * @brief Attach the fader to a source * @param fader pointer to the fader object * @param source pointer to the source object * @return true on success * * When the fader is attached to a source it will automatically sync it's state * to the volume of the source. */ EXPORT bool obs_fader_attach_source(obs_fader_t *fader, obs_source_t *source); /** * @brief Detach the fader from the currently attached source * @param fader pointer to the fader object */ EXPORT void obs_fader_detach_source(obs_fader_t *fader); typedef void (*obs_fader_changed_t)(void *param, float db); EXPORT void obs_fader_add_callback(obs_fader_t *fader, obs_fader_changed_t callback, void *param); EXPORT void obs_fader_remove_callback(obs_fader_t *fader, obs_fader_changed_t callback, void *param); /** * @brief Create a volume meter * @param type the mapping type to use for the volume meter * @return pointer to the volume meter object * * A volume meter object is used to prepare the sound levels reported by audio * sources for display in a GUI. * It will automatically take source volume into account and map the levels * to a range [0.0f, 1.0f]. */ EXPORT obs_volmeter_t *obs_volmeter_create(enum obs_fader_type type); /** * @brief Destroy a volume meter * @param volmeter pointer to the volmeter object * * Destroy the volume meter and free all related data */ EXPORT void obs_volmeter_destroy(obs_volmeter_t *volmeter); /** * @brief Attach the volume meter to a source * @param volmeter pointer to the volume meter object * @param source pointer to the source object * @return true on success * * When the volume meter is attached to a source it will start to listen to * volume updates on the source and after preparing the data emit its own * signal. */ EXPORT bool obs_volmeter_attach_source(obs_volmeter_t *volmeter, obs_source_t *source); /** * @brief Detach the volume meter from the currently attached source * @param volmeter pointer to the volume meter object */ EXPORT void obs_volmeter_detach_source(obs_volmeter_t *volmeter); /** * @brief Set the update interval for the volume meter * @param volmeter pointer to the volume meter object * @param ms update interval in ms * * This sets the update interval in milliseconds that should be processed before * the resulting values are emitted by the levels_updated signal. The resulting * number of audio samples is rounded to an integer. * * Please note that due to way obs does receive audio data from the sources * this is no hard guarantee for the timing of the signal itself. When the * volume meter receives a chunk of data that is multiple the size of the sample * interval, all data will be sampled and the values updated accordingly, but * only the signal for the last segment is actually emitted. * On the other hand data might be received in a way that will cause the signal * to be emitted in shorter intervals than specified here under some * circumstances. */ EXPORT void obs_volmeter_set_update_interval(obs_volmeter_t *volmeter, const unsigned int ms); /** * @brief Get the update interval currently used for the volume meter * @param volmeter pointer to the volume meter object * @return update interval in ms */ EXPORT unsigned int obs_volmeter_get_update_interval(obs_volmeter_t *volmeter); /** * @brief Set the peak hold time for the volume meter * @param volmeter pointer to the volume meter object * @param ms peak hold time in ms */ EXPORT void obs_volmeter_set_peak_hold(obs_volmeter_t *volmeter, const unsigned int ms); /** * @brief Get the peak hold time for the volume meter * @param volmeter pointer to the volume meter object * @return the peak hold time in ms */ EXPORT unsigned int obs_volmeter_get_peak_hold(obs_volmeter_t *volmeter); typedef void (*obs_volmeter_updated_t)(void *param, float level, float magnitude, float peak, float muted); EXPORT void obs_volmeter_add_callback(obs_volmeter_t *volmeter, obs_volmeter_updated_t callback, void *param); EXPORT void obs_volmeter_remove_callback(obs_volmeter_t *volmeter, obs_volmeter_updated_t callback, void *param); #ifdef __cplusplus } #endif