1 /*
2 * Copyright 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef ANDROID_AUDIO_POWER_H
18 #define ANDROID_AUDIO_POWER_H
19
20 #include <math.h>
21 #include <stdint.h>
22 #include <sys/cdefs.h>
23 #include <system/audio.h>
24
25 /** \cond */
26 __BEGIN_DECLS
27 /** \endcond */
28
29 /**
30 * \brief Compute signal power on a scale of 0 dBFS.
31 *
32 * \param buffer buffer of samples.
33 * \param format one of AUDIO_FORMAT_PCM_8_BIT, AUDIO_FORMAT_PCM_16_BIT,
34 * AUDIO_FORMAT_PCM_24_BIT_PACKED, AUDIO_FORMAT_PCM_8_24_BIT,
35 * AUDIO_FORMAT_PCM_32_BIT, AUDIO_FORMAT_PCM_FLOAT.
36 * \param samples number of samples in buffer. This is not audio frames;
37 * usually the number of samples is the number of audio frames
38 * multiplied by channel count.
39 *
40 * \return
41 * signal power of the samples in the buffer. It is possible to return negative infinity
42 * if the power is zero.
43 */
44
45 float audio_utils_compute_power_mono(const void *buffer, audio_format_t format, size_t samples);
46
47 /**
48 * \brief Compute signal energy (sum of squared amplitudes).
49 *
50 * \param buffer buffer of samples.
51 * \param format one of AUDIO_FORMAT_PCM_8_BIT, AUDIO_FORMAT_PCM_16_BIT,
52 * AUDIO_FORMAT_PCM_24_BIT_PACKED, AUDIO_FORMAT_PCM_8_24_BIT,
53 * AUDIO_FORMAT_PCM_32_BIT, AUDIO_FORMAT_PCM_FLOAT.
54 * \param samples number of samples in buffer. This is not audio frames;
55 * usually the number of samples is the number of audio frames
56 * multiplied by channel count.
57 *
58 * \return
59 * signal energy of the samples in the buffer (sum of squares) where each sample is
60 * normalized to peak to peak range of 1.f.
61 */
62
63 float audio_utils_compute_energy_mono(const void *buffer, audio_format_t format, size_t samples);
64
65 /**
66 * \brief Compute for each channel signal energy (sum of squared amplitudes).
67 *
68 * \param buffer buffer of samples.
69 * \param format one of AUDIO_FORMAT_PCM_8_BIT, AUDIO_FORMAT_PCM_16_BIT,
70 * AUDIO_FORMAT_PCM_24_BIT_PACKED, AUDIO_FORMAT_PCM_8_24_BIT,
71 * AUDIO_FORMAT_PCM_32_BIT, AUDIO_FORMAT_PCM_FLOAT.
72 * \param samples number of samples in buffer. This is not audio frames;
73 * usually the number of samples is the number of audio frames
74 * multiplied by channel count.
75 * \param numChannels the number of channels for which the energy is computed.
76 * \param out interleaved buffer containing for each channel the sample
77 * energy. Must be initialized with zero values or pre-existing
78 * energy to accumulate to.
79 *
80 * \return
81 * out array is updated by adding for each channel the signal energy of the samples
82 * in the buffer (sum of squares).
83 */
84 void audio_utils_accumulate_energy(const void* buffer,
85 audio_format_t format,
86 size_t samples,
87 size_t numChannels,
88 float* out);
89
90 /**
91 * \brief Returns true if the format is supported for compute_energy_for_mono()
92 * and compute_power_for_mono().
93 * \param format format under consideration.
94 * \return true if supported.
95 */
96 bool audio_utils_is_compute_power_format_supported(audio_format_t format);
97
98 /**
99 * \brief Returns the signal power from amplitude.
100 * \param amplitude the signal amplitude. A negative amplitude is treated
101 * the same as a positive amplitude.
102 * \return signal power in dB. It is possible to return negative infinity
103 * if the input is zero.
104 */
audio_utils_power_from_amplitude(float amplitude)105 static inline float audio_utils_power_from_amplitude(float amplitude)
106 {
107 return 20.f * log10f(fabsf(amplitude));
108 }
109
110 /**
111 * \brief Returns the signal power from energy.
112 * \param energy the signal energy. This should be non-negative.
113 * \return signal power in dB. It is possible to return NaN if the input is
114 * negative, or negative infinity if the input is zero.
115 */
audio_utils_power_from_energy(float energy)116 static inline float audio_utils_power_from_energy(float energy)
117 {
118 return 10.f * log10f(energy);
119 }
120
121 /** \cond */
122 __END_DECLS
123 /** \endcond */
124
125 #endif // !ANDROID_AUDIO_POWER_H
126