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