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
23namespace 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
66enum 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
82enum 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
89struct AudioPlaybackRate {
90    float mSpeed;
91    float mPitch;
92    enum AudioTimestretchStretchMode  mStretchMode;
93    enum AudioTimestretchFallbackMode mFallbackMode;
94};
95
96static 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
103static 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
111static 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.
135static 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.
145static 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
154static 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
169static 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