1 /* 2 * Copyright (C) 2010 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_MEDIA_VISUALIZER_H 18 #define ANDROID_MEDIA_VISUALIZER_H 19 20 #include <media/AudioEffect.h> 21 #include <system/audio_effects/effect_visualizer.h> 22 #include <utils/Thread.h> 23 #include "android/content/AttributionSourceState.h" 24 25 /** 26 * The Visualizer class enables application to retrieve part of the currently playing audio for 27 * visualization purpose. It is not an audio recording interface and only returns partial and low 28 * quality audio content. However, to protect privacy of certain audio data (e.g voice mail) the use 29 * of the visualizer requires the permission android.permission.RECORD_AUDIO. 30 * The audio session ID passed to the constructor indicates which audio content should be 31 * visualized: 32 * - If the session is 0, the audio output mix is visualized 33 * - If the session is not 0, the audio from a particular MediaPlayer or AudioTrack 34 * using this audio session is visualized 35 * Two types of representation of audio content can be captured: 36 * - Waveform data: consecutive 8-bit (unsigned) mono samples by using the getWaveForm() method 37 * - Frequency data: 8-bit magnitude FFT by using the getFft() method 38 * 39 * The length of the capture can be retrieved or specified by calling respectively 40 * getCaptureSize() and setCaptureSize() methods. Note that the size of the FFT 41 * is half of the specified capture size but both sides of the spectrum are returned yielding in a 42 * number of bytes equal to the capture size. The capture size must be a power of 2 in the range 43 * returned by getMinCaptureSize() and getMaxCaptureSize(). 44 * In addition to the polling capture mode, a callback mode is also available by installing a 45 * callback function by use of the setCaptureCallBack() method. The rate at which the callback 46 * is called as well as the type of data returned is specified. 47 * Before capturing data, the Visualizer must be enabled by calling the setEnabled() method. 48 * When data capture is not needed any more, the Visualizer should be disabled. 49 */ 50 51 52 namespace android { 53 54 // ---------------------------------------------------------------------------- 55 56 class Visualizer: public AudioEffect { 57 public: 58 59 enum callback_flags { 60 CAPTURE_WAVEFORM = 0x00000001, // capture callback returns a PCM wave form 61 CAPTURE_FFT = 0x00000002, // apture callback returns a frequency representation 62 CAPTURE_CALL_JAVA = 0x00000004 // the callback thread can call java 63 }; 64 65 66 /* Constructor. 67 * See AudioEffect constructor for details on parameters. 68 */ 69 explicit Visualizer(const android::content::AttributionSourceState& attributionSource); 70 71 ~Visualizer(); 72 73 /** 74 * Initialize an uninitialized Visualizer. 75 * See AudioEffect 'set' function for details on parameters. 76 */ 77 status_t set(int32_t priority = 0, 78 effect_callback_t cbf = NULL, 79 void* user = NULL, 80 audio_session_t sessionId = AUDIO_SESSION_OUTPUT_MIX, 81 audio_io_handle_t io = AUDIO_IO_HANDLE_NONE, 82 const AudioDeviceTypeAddr& device = {}, 83 bool probe = false); 84 85 // Declared 'final' because we call this in ~Visualizer(). 86 status_t setEnabled(bool enabled) final; 87 88 // maximum capture size in samples getMaxCaptureSize()89 static uint32_t getMaxCaptureSize() { return VISUALIZER_CAPTURE_SIZE_MAX; } 90 // minimum capture size in samples getMinCaptureSize()91 static uint32_t getMinCaptureSize() { return VISUALIZER_CAPTURE_SIZE_MIN; } 92 // maximum capture rate in millihertz getMaxCaptureRate()93 static uint32_t getMaxCaptureRate() { return CAPTURE_RATE_MAX; } 94 95 // callback used to return periodic PCM or FFT captures to the application. Either one or both 96 // types of data are returned (PCM and FFT) according to flags indicated when installing the 97 // callback. When a type of data is not present, the corresponding size (waveformSize or 98 // fftSize) is 0. 99 typedef void (*capture_cbk_t)(void* user, 100 uint32_t waveformSize, 101 uint8_t *waveform, 102 uint32_t fftSize, 103 uint8_t *fft, 104 uint32_t samplingrate); 105 106 // install a callback to receive periodic captures. The capture rate is specified in milliHertz 107 // and the capture format is according to flags (see callback_flags). 108 status_t setCaptureCallBack(capture_cbk_t cbk, void* user, uint32_t flags, uint32_t rate); 109 110 // set the capture size capture size must be a power of two in the range 111 // [VISUALIZER_CAPTURE_SIZE_MAX. VISUALIZER_CAPTURE_SIZE_MIN] 112 // must be called when the visualizer is not enabled 113 status_t setCaptureSize(uint32_t size); getCaptureSize()114 uint32_t getCaptureSize() { return mCaptureSize; } 115 116 // returns the capture rate indicated when installing the callback getCaptureRate()117 uint32_t getCaptureRate() { return mCaptureRate; } 118 119 // returns the sampling rate of the audio being captured getSamplingRate()120 uint32_t getSamplingRate() { return mSampleRate; } 121 122 // set the way volume affects the captured data 123 // mode must one of VISUALIZER_SCALING_MODE_NORMALIZED, 124 // VISUALIZER_SCALING_MODE_AS_PLAYED 125 status_t setScalingMode(uint32_t mode); getScalingMode()126 uint32_t getScalingMode() { return mScalingMode; } 127 128 // set which measurements are done on the audio buffers processed by the effect. 129 // valid measurements (mask): MEASUREMENT_MODE_PEAK_RMS 130 status_t setMeasurementMode(uint32_t mode); getMeasurementMode()131 uint32_t getMeasurementMode() { return mMeasurementMode; } 132 133 // return a set of int32_t measurements 134 status_t getIntMeasurements(uint32_t type, uint32_t number, int32_t *measurements); 135 136 // return a capture in PCM 8 bit unsigned format. The size of the capture is equal to 137 // getCaptureSize() 138 status_t getWaveForm(uint8_t *waveform); 139 140 // return a capture in FFT 8 bit signed format. The size of the capture is equal to 141 // getCaptureSize() but the length of the FFT is half of the size (both parts of the spectrum 142 // are returned 143 status_t getFft(uint8_t *fft); 144 void release(); 145 146 protected: 147 // from IEffectClient 148 virtual void controlStatusChanged(bool controlGranted); 149 150 private: 151 152 static const uint32_t CAPTURE_RATE_MAX = 20000; 153 static const uint32_t CAPTURE_RATE_DEF = 10000; 154 static const uint32_t CAPTURE_SIZE_DEF = VISUALIZER_CAPTURE_SIZE_MAX; 155 156 /* internal class to handle the callback */ 157 class CaptureThread : public Thread 158 { 159 public: 160 CaptureThread(Visualizer* visualizer, uint32_t captureRate, bool bCanCallJava = false); 161 162 private: 163 friend class Visualizer; 164 virtual bool threadLoop(); 165 wp<Visualizer> mReceiver; 166 Mutex mLock; 167 uint32_t mSleepTimeUs; 168 }; 169 170 status_t doFft(uint8_t *fft, uint8_t *waveform); 171 void periodicCapture(); 172 uint32_t initCaptureSize(); 173 174 Mutex mCaptureLock; 175 uint32_t mCaptureRate = CAPTURE_RATE_DEF; 176 uint32_t mCaptureSize = CAPTURE_SIZE_DEF; 177 uint32_t mSampleRate = 44100000; 178 uint32_t mScalingMode = VISUALIZER_SCALING_MODE_NORMALIZED; 179 uint32_t mMeasurementMode = MEASUREMENT_MODE_NONE; 180 capture_cbk_t mCaptureCallBack = nullptr; 181 void *mCaptureCbkUser = nullptr; 182 sp<CaptureThread> mCaptureThread; 183 uint32_t mCaptureFlags = 0; 184 }; 185 186 187 }; // namespace android 188 189 #endif // ANDROID_MEDIA_VISUALIZER_H 190