File	Doc	Category	Size	Date	Package
Visualizer.java	API Doc	Android 5.1 API	30097	Thu Mar 12 22:22:30 GMT 2015	android.media.audiofx

Visualizer

• java.lang.Object

Fields Summary
private static final String	TAG
public static final int	STATE_UNINITIALIZED State of a Visualizer object that was not successfully initialized upon creation
public static final int	STATE_INITIALIZED State of a Visualizer object that is ready to be used.
public static final int	STATE_ENABLED State of a Visualizer object that is active.
public static final int	SCALING_MODE_NORMALIZED Defines a capture mode where amplification is applied based on the content of the captured data. This is the default Visualizer mode, and is suitable for music visualization.
public static final int	SCALING_MODE_AS_PLAYED Defines a capture mode where the playback volume will affect (scale) the range of the captured data. A low playback volume will lead to low sample and fft values, and vice-versa.
public static final int	MEASUREMENT_MODE_NONE Defines a measurement mode in which no measurements are performed.
public static final int	MEASUREMENT_MODE_PEAK_RMS Defines a measurement mode which computes the peak and RMS value in mB, where 0mB is the maximum sample value, and -9600mB is the minimum value. Values for peak and RMS can be retrieved with {@link #getMeasurementPeakRms(MeasurementPeakRms)}.
private static final int	NATIVE_EVENT_PCM_CAPTURE
private static final int	NATIVE_EVENT_FFT_CAPTURE
private static final int	NATIVE_EVENT_SERVER_DIED
public static final int	SUCCESS Successful operation.
public static final int	ERROR Unspecified error.
public static final int	ALREADY_EXISTS Internal operation status. Not returned by any method.
public static final int	ERROR_NO_INIT Operation failed due to bad object initialization.
public static final int	ERROR_BAD_VALUE Operation failed due to bad parameter value.
public static final int	ERROR_INVALID_OPERATION Operation failed because it was requested in wrong state.
public static final int	ERROR_NO_MEMORY Operation failed due to lack of memory.
public static final int	ERROR_DEAD_OBJECT Operation failed due to dead remote object.
private int	mState Indicates the state of the Visualizer instance
private final Object	mStateLock Lock to synchronize access to mState
private int	mId System wide unique Identifier of the visualizer engine used by this Visualizer instance
private final Object	mListenerLock Lock to protect listeners updates against event notifications
private NativeEventHandler	mNativeEventHandler Handler for events coming from the native code
private OnDataCaptureListener	mCaptureListener PCM and FFT capture listener registered by client
private OnServerDiedListener	mServerDiedListener Server Died listener registered by client
private long	mNativeVisualizer
private long	mJniData

Constructors Summary

public Visualizer(int audioSession) Class constructor. param audioSession system wide unique audio session identifier. If audioSession is not 0, the visualizer will be attached to the MediaPlayer or AudioTrack in the same audio session. Otherwise, the Visualizer will apply to the output mix. throws java.lang.UnsupportedOperationException throws java.lang.RuntimeException //-------------------------------------------------------------------------- // Constructor, Finalize //-------------------- int[] id = new int[1]; synchronized (mStateLock) { mState = STATE_UNINITIALIZED; // native initialization int result = native_setup(new WeakReference<Visualizer>(this), audioSession, id); if (result != SUCCESS && result != ALREADY_EXISTS) { Log.e(TAG, "Error code "+result+" when initializing Visualizer."); switch (result) { case ERROR_INVALID_OPERATION: throw (new UnsupportedOperationException("Effect library not loaded")); default: throw (new RuntimeException("Cannot initialize Visualizer engine, error: " +result)); } } mId = id[0]; if (native_getEnabled()) { mState = STATE_ENABLED; } else { mState = STATE_INITIALIZED; } }

Methods Summary
protected void	finalize() native_finalize();
public int	getCaptureSize() Returns current capture size. return the capture size in bytes. synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("getCaptureSize() called in wrong state: "+mState)); } return native_getCaptureSize(); }
public static native int[]	getCaptureSizeRange() Returns the capture size range. return the mininum capture size is returned in first array element and the maximum in second array element.
public boolean	getEnabled() Get current activation state of the visualizer. return true if the visualizer is active, false otherwise synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("getEnabled() called in wrong state: "+mState)); } return native_getEnabled(); }
public int	getFft(byte[] fft) Returns a frequency capture of currently playing audio content. This method must be called when the Visualizer is enabled. The capture is an 8-bit magnitude FFT, the frequency range covered being 0 (DC) to half of the sampling rate returned by {@link #getSamplingRate()}. The capture returns the real and imaginary parts of a number of frequency points equal to half of the capture size plus one. Note: only the real part is returned for the first point (DC) and the last point (sampling frequency / 2). The layout in the returned byte array is as follows: n is the capture size returned by getCaptureSize() Rfk, Ifk are respectively the real and imaginary parts of the kth frequency component If Fs is the sampling frequency retuned by getSamplingRate() the kth frequency is: (k*Fs)/(n/2) Index 0 1 2 3 4 5 ... n - 2 n - 1 Data Rf0 Rf(n/2) Rf1 If1 Rf2 If2 ... Rf(n-1)/2 If(n-1)/2 param fft array of bytes where the FFT should be returned return {@link #SUCCESS} in case of success, {@link #ERROR_NO_MEMORY}, {@link #ERROR_INVALID_OPERATION} or {@link #ERROR_DEAD_OBJECT} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState != STATE_ENABLED) { throw(new IllegalStateException("getFft() called in wrong state: "+mState)); } return native_getFft(fft); }
public static native int	getMaxCaptureRate() Returns the maximum capture rate for the callback capture method. This is the maximum value for the rate parameter of the {@link #setDataCaptureListener(OnDataCaptureListener, int, boolean, boolean)} method. return the maximum capture rate expressed in milliHertz
public int	getMeasurementMode() Returns the current measurement modes performed by this audio effect return the mask of the measurements, {@link #MEASUREMENT_MODE_NONE} (when no measurements are performed) or {@link #MEASUREMENT_MODE_PEAK_RMS}. throws IllegalStateException synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("getMeasurementMode() called in wrong state: " + mState)); } return native_getMeasurementMode(); }
public int	getMeasurementPeakRms(android.media.audiofx.Visualizer$MeasurementPeakRms measurement) Retrieves the latest peak and RMS measurement. Sets the peak and RMS fields of the supplied {@link Visualizer.MeasurementPeakRms} to the latest measured values. param measurement a non-null {@link Visualizer.MeasurementPeakRms} instance to store the measurement values. return {@link #SUCCESS} in case of success, {@link #ERROR_BAD_VALUE}, {@link #ERROR_NO_MEMORY}, {@link #ERROR_INVALID_OPERATION} or {@link #ERROR_DEAD_OBJECT} in case of failure. if (measurement == null) { Log.e(TAG, "Cannot store measurements in a null object"); return ERROR_BAD_VALUE; } synchronized (mStateLock) { if (mState != STATE_ENABLED) { throw (new IllegalStateException("getMeasurementPeakRms() called in wrong state: " + mState)); } return native_getPeakRms(measurement); }
public int	getSamplingRate() Returns the sampling rate of the captured audio. return the sampling rate in milliHertz. synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("getSamplingRate() called in wrong state: "+mState)); } return native_getSamplingRate(); }
public int	getScalingMode() Returns the current scaling mode on the captured visualization data. return the scaling mode, see {@link #SCALING_MODE_NORMALIZED} and {@link #SCALING_MODE_AS_PLAYED}. throws IllegalStateException synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("getScalingMode() called in wrong state: " + mState)); } return native_getScalingMode(); }
public int	getWaveForm(byte[] waveform) Returns a waveform capture of currently playing audio content. The capture consists in a number of consecutive 8-bit (unsigned) mono PCM samples equal to the capture size returned by {@link #getCaptureSize()}. This method must be called when the Visualizer is enabled. param waveform array of bytes where the waveform should be returned return {@link #SUCCESS} in case of success, {@link #ERROR_NO_MEMORY}, {@link #ERROR_INVALID_OPERATION} or {@link #ERROR_DEAD_OBJECT} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState != STATE_ENABLED) { throw(new IllegalStateException("getWaveForm() called in wrong state: "+mState)); } return native_getWaveForm(waveform); }
private final native void	native_finalize()
private final native int	native_getCaptureSize()
private final native boolean	native_getEnabled()
private final native int	native_getFft(byte[] fft)
private final native int	native_getMeasurementMode()
private final native int	native_getPeakRms(android.media.audiofx.Visualizer$MeasurementPeakRms measurement)
private final native int	native_getSamplingRate()
private final native int	native_getScalingMode()
private final native int	native_getWaveForm(byte[] waveform)
private static final native void	native_init()
private final native void	native_release()
private final native int	native_setCaptureSize(int size)
private final native int	native_setEnabled(boolean enabled)
private final native int	native_setMeasurementMode(int mode)
private final native int	native_setPeriodicCapture(int rate, boolean waveForm, boolean fft)
private final native int	native_setScalingMode(int mode)
private final native int	native_setup(java.lang.Object audioeffect_this, int audioSession, int[] id)
private static void	postEventFromNative(java.lang.Object effect_ref, int what, int arg1, int arg2, java.lang.Object obj) Visualizer visu = (Visualizer)((WeakReference)effect_ref).get(); if (visu == null) { return; } if (visu.mNativeEventHandler != null) { Message m = visu.mNativeEventHandler.obtainMessage(what, arg1, arg2, obj); visu.mNativeEventHandler.sendMessage(m); }
public void	release() Releases the native Visualizer resources. It is a good practice to release the visualization engine when not in use. synchronized (mStateLock) { native_release(); mState = STATE_UNINITIALIZED; }
public int	setCaptureSize(int size) Sets the capture size, i.e. the number of bytes returned by {@link #getWaveForm(byte[])} and {@link #getFft(byte[])} methods. The capture size must be a power of 2 in the range returned by {@link #getCaptureSizeRange()}. This method must not be called when the Visualizer is enabled. param size requested capture size return {@link #SUCCESS} in case of success, {@link #ERROR_BAD_VALUE} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState != STATE_INITIALIZED) { throw(new IllegalStateException("setCaptureSize() called in wrong state: "+mState)); } return native_setCaptureSize(size); }
public int	setDataCaptureListener(android.media.audiofx.Visualizer$OnDataCaptureListener listener, int rate, boolean waveform, boolean fft) Registers an OnDataCaptureListener interface and specifies the rate at which the capture should be updated as well as the type of capture requested. Call this method with a null listener to stop receiving the capture updates. param listener OnDataCaptureListener registered param rate rate in milliHertz at which the capture should be updated param waveform true if a waveform capture is requested: the onWaveFormDataCapture() method will be called on the OnDataCaptureListener interface. param fft true if a frequency capture is requested: the onFftDataCapture() method will be called on the OnDataCaptureListener interface. return {@link #SUCCESS} in case of success, {@link #ERROR_NO_INIT} or {@link #ERROR_BAD_VALUE} in case of failure. synchronized (mListenerLock) { mCaptureListener = listener; } if (listener == null) { // make sure capture callback is stopped in native code waveform = false; fft = false; } int status = native_setPeriodicCapture(rate, waveform, fft); if (status == SUCCESS) { if ((listener != null) && (mNativeEventHandler == null)) { Looper looper; if ((looper = Looper.myLooper()) != null) { mNativeEventHandler = new NativeEventHandler(this, looper); } else if ((looper = Looper.getMainLooper()) != null) { mNativeEventHandler = new NativeEventHandler(this, looper); } else { mNativeEventHandler = null; status = ERROR_NO_INIT; } } } return status;
public int	setEnabled(boolean enabled) Enable or disable the visualization engine. param enabled requested enable state return {@link #SUCCESS} in case of success, {@link #ERROR_INVALID_OPERATION} or {@link #ERROR_DEAD_OBJECT} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("setEnabled() called in wrong state: "+mState)); } int status = SUCCESS; if ((enabled && (mState == STATE_INITIALIZED)) || (!enabled && (mState == STATE_ENABLED))) { status = native_setEnabled(enabled); if (status == SUCCESS) { mState = enabled ? STATE_ENABLED : STATE_INITIALIZED; } } return status; }
public int	setMeasurementMode(int mode) Sets the combination of measurement modes to be performed by this audio effect. param mode a mask of the measurements to perform. The valid values are {@link #MEASUREMENT_MODE_NONE} (to cancel any measurement) or {@link #MEASUREMENT_MODE_PEAK_RMS}. return {@link #SUCCESS} in case of success, {@link #ERROR_BAD_VALUE} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("setMeasurementMode() called in wrong state: " + mState)); } return native_setMeasurementMode(mode); }
public int	setScalingMode(int mode) Set the type of scaling applied on the captured visualization data. param mode see {@link #SCALING_MODE_NORMALIZED} and {@link #SCALING_MODE_AS_PLAYED} return {@link #SUCCESS} in case of success, {@link #ERROR_BAD_VALUE} in case of failure. throws IllegalStateException synchronized (mStateLock) { if (mState == STATE_UNINITIALIZED) { throw(new IllegalStateException("setScalingMode() called in wrong state: " + mState)); } return native_setScalingMode(mode); }
public int	setServerDiedListener(android.media.audiofx.Visualizer$OnServerDiedListener listener) hide Registers an OnServerDiedListener interface. Call this method with a null listener to stop receiving server death notifications. return {@link #SUCCESS} in case of success, synchronized (mListenerLock) { mServerDiedListener = listener; } return SUCCESS;