1 /*
2 * Copyright (C) 2014 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_RESAMPLER_PUBLIC_H
18 #define ANDROID_AUDIO_RESAMPLER_PUBLIC_H
19
20 #include <stdint.h>
21 #include <math.h>
22
23 namespace android {
24
25 // AUDIO_RESAMPLER_DOWN_RATIO_MAX is the maximum ratio between the original
26 // audio sample rate and the target rate when downsampling,
27 // as permitted in the audio framework, e.g. AudioTrack and AudioFlinger.
28 // In practice, it is not recommended to downsample more than 6:1
29 // for best audio quality, even though the audio framework permits a larger
30 // downsampling ratio.
31 // TODO: replace with an API
32 #define AUDIO_RESAMPLER_DOWN_RATIO_MAX 256
33
34 // AUDIO_RESAMPLER_UP_RATIO_MAX is the maximum suggested ratio between the original
35 // audio sample rate and the target rate when upsampling. It is loosely enforced by
36 // the system. One issue with large upsampling ratios is the approximation by
37 // an int32_t of the phase increments, making the resulting sample rate inexact.
38 #define AUDIO_RESAMPLER_UP_RATIO_MAX 65536
39
40 // AUDIO_TIMESTRETCH_SPEED_MIN and AUDIO_TIMESTRETCH_SPEED_MAX define the min and max time stretch
41 // speeds supported by the system. These are enforced by the system and values outside this range
42 // will result in a runtime error.
43 // Depending on the AudioPlaybackRate::mStretchMode, the effective limits might be narrower than
44 // the ones specified here
45 // AUDIO_TIMESTRETCH_SPEED_MIN_DELTA is the minimum absolute speed difference that might trigger a
46 // parameter update
47 #define AUDIO_TIMESTRETCH_SPEED_MIN 0.01f
48 #define AUDIO_TIMESTRETCH_SPEED_MAX 20.0f
49 #define AUDIO_TIMESTRETCH_SPEED_NORMAL 1.0f
50 #define AUDIO_TIMESTRETCH_SPEED_MIN_DELTA 0.0001f
51
52 // AUDIO_TIMESTRETCH_PITCH_MIN and AUDIO_TIMESTRETCH_PITCH_MAX define the min and max time stretch
53 // pitch shifting supported by the system. These are not enforced by the system and values
54 // outside this range might result in a pitch different than the one requested.
55 // Depending on the AudioPlaybackRate::mStretchMode, the effective limits might be narrower than
56 // the ones specified here.
57 // AUDIO_TIMESTRETCH_PITCH_MIN_DELTA is the minimum absolute pitch difference that might trigger a
58 // parameter update
59 #define AUDIO_TIMESTRETCH_PITCH_MIN 0.25f
60 #define AUDIO_TIMESTRETCH_PITCH_MAX 4.0f
61 #define AUDIO_TIMESTRETCH_PITCH_NORMAL 1.0f
62 #define AUDIO_TIMESTRETCH_PITCH_MIN_DELTA 0.0001f
63
64
65 //Determines the current algorithm used for stretching
66 enum AudioTimestretchStretchMode : int32_t {
67 AUDIO_TIMESTRETCH_STRETCH_DEFAULT = 0,
68 AUDIO_TIMESTRETCH_STRETCH_SPEECH = 1,
69 //TODO: add more stretch modes/algorithms
70 };
71
72 //Limits for AUDIO_TIMESTRETCH_STRETCH_SPEECH mode
73 #define TIMESTRETCH_SONIC_SPEED_MIN 0.1f
74 #define TIMESTRETCH_SONIC_SPEED_MAX 6.0f
75
76 //Determines behavior of Timestretch if current algorithm can't perform
77 //with current parameters.
78 // FALLBACK_CUT_REPEAT: (internal only) for speed <1.0 will truncate frames
79 // for speed > 1.0 will repeat frames
80 // FALLBACK_MUTE: will set all processed frames to zero
81 // FALLBACK_FAIL: will stop program execution and log a fatal error
82 enum AudioTimestretchFallbackMode : int32_t {
83 AUDIO_TIMESTRETCH_FALLBACK_CUT_REPEAT = -1,
84 AUDIO_TIMESTRETCH_FALLBACK_DEFAULT = 0,
85 AUDIO_TIMESTRETCH_FALLBACK_MUTE = 1,
86 AUDIO_TIMESTRETCH_FALLBACK_FAIL = 2,
87 };
88
89 struct AudioPlaybackRate {
90 float mSpeed;
91 float mPitch;
92 enum AudioTimestretchStretchMode mStretchMode;
93 enum AudioTimestretchFallbackMode mFallbackMode;
94 };
95
96 static const AudioPlaybackRate AUDIO_PLAYBACK_RATE_DEFAULT = {
97 AUDIO_TIMESTRETCH_SPEED_NORMAL,
98 AUDIO_TIMESTRETCH_PITCH_NORMAL,
99 AUDIO_TIMESTRETCH_STRETCH_DEFAULT,
100 AUDIO_TIMESTRETCH_FALLBACK_DEFAULT
101 };
102
isAudioPlaybackRateEqual(const AudioPlaybackRate & pr1,const AudioPlaybackRate & pr2)103 static inline bool isAudioPlaybackRateEqual(const AudioPlaybackRate &pr1,
104 const AudioPlaybackRate &pr2) {
105 return fabs(pr1.mSpeed - pr2.mSpeed) < AUDIO_TIMESTRETCH_SPEED_MIN_DELTA &&
106 fabs(pr1.mPitch - pr2.mPitch) < AUDIO_TIMESTRETCH_PITCH_MIN_DELTA &&
107 pr2.mStretchMode == pr2.mStretchMode &&
108 pr2.mFallbackMode == pr2.mFallbackMode;
109 }
110
isAudioPlaybackRateValid(const AudioPlaybackRate & playbackRate)111 static inline bool isAudioPlaybackRateValid(const AudioPlaybackRate &playbackRate) {
112 if (playbackRate.mFallbackMode == AUDIO_TIMESTRETCH_FALLBACK_FAIL &&
113 (playbackRate.mStretchMode == AUDIO_TIMESTRETCH_STRETCH_SPEECH ||
114 playbackRate.mStretchMode == AUDIO_TIMESTRETCH_STRETCH_DEFAULT)) {
115 //test sonic specific constraints
116 return playbackRate.mSpeed >= TIMESTRETCH_SONIC_SPEED_MIN &&
117 playbackRate.mSpeed <= TIMESTRETCH_SONIC_SPEED_MAX &&
118 playbackRate.mPitch >= AUDIO_TIMESTRETCH_PITCH_MIN &&
119 playbackRate.mPitch <= AUDIO_TIMESTRETCH_PITCH_MAX;
120 } else {
121 return playbackRate.mSpeed >= AUDIO_TIMESTRETCH_SPEED_MIN &&
122 playbackRate.mSpeed <= AUDIO_TIMESTRETCH_SPEED_MAX &&
123 playbackRate.mPitch >= AUDIO_TIMESTRETCH_PITCH_MIN &&
124 playbackRate.mPitch <= AUDIO_TIMESTRETCH_PITCH_MAX;
125 }
126 }
127
128 // TODO: Consider putting these inlines into a class scope
129
130 // Returns the source frames needed to resample to destination frames. This is not a precise
131 // value and depends on the resampler (and possibly how it handles rounding internally).
132 // Nevertheless, this should be an upper bound on the requirements of the resampler.
133 // If srcSampleRate and dstSampleRate are equal, then it returns destination frames, which
134 // may not be true if the resampler is asynchronous.
sourceFramesNeeded(uint32_t srcSampleRate,size_t dstFramesRequired,uint32_t dstSampleRate)135 static inline size_t sourceFramesNeeded(
136 uint32_t srcSampleRate, size_t dstFramesRequired, uint32_t dstSampleRate) {
137 // +1 for rounding - always do this even if matched ratio (resampler may use phases not ratio)
138 // +1 for additional sample needed for interpolation
139 return srcSampleRate == dstSampleRate ? dstFramesRequired :
140 size_t((uint64_t)dstFramesRequired * srcSampleRate / dstSampleRate + 1 + 1);
141 }
142
143 // An upper bound for the number of destination frames possible from srcFrames
144 // after sample rate conversion. This may be used for buffer sizing.
destinationFramesPossible(size_t srcFrames,uint32_t srcSampleRate,uint32_t dstSampleRate)145 static inline size_t destinationFramesPossible(size_t srcFrames, uint32_t srcSampleRate,
146 uint32_t dstSampleRate) {
147 if (srcSampleRate == dstSampleRate) {
148 return srcFrames;
149 }
150 uint64_t dstFrames = (uint64_t)srcFrames * dstSampleRate / srcSampleRate;
151 return dstFrames > 2 ? dstFrames - 2 : 0;
152 }
153
sourceFramesNeededWithTimestretch(uint32_t srcSampleRate,size_t dstFramesRequired,uint32_t dstSampleRate,float speed)154 static inline size_t sourceFramesNeededWithTimestretch(
155 uint32_t srcSampleRate, size_t dstFramesRequired, uint32_t dstSampleRate,
156 float speed) {
157 // required is the number of input frames the resampler needs
158 size_t required = sourceFramesNeeded(srcSampleRate, dstFramesRequired, dstSampleRate);
159 // to deliver this, the time stretcher requires:
160 return required * (double)speed + 1 + 1; // accounting for rounding dependencies
161 }
162
163 // Identifies sample rates that we associate with music
164 // and thus eligible for better resampling and fast capture.
165 // This is somewhat less than 44100 to allow for pitch correction
166 // involving resampling as well as asynchronous resampling.
167 #define AUDIO_PROCESSING_MUSIC_RATE 40000
168
isMusicRate(uint32_t sampleRate)169 static inline bool isMusicRate(uint32_t sampleRate) {
170 return sampleRate >= AUDIO_PROCESSING_MUSIC_RATE;
171 }
172
173 } // namespace android
174
175 // ---------------------------------------------------------------------------
176
177 #endif // ANDROID_AUDIO_RESAMPLER_PUBLIC_H
178