public class

Visualizer

extends Object
java.lang.Object
   ↳android.media.audiofx.Visualizer

Class Overview

The Visualizer class enables application to retrieve part of the currently playing audio for visualization purpose. It is not an audio recording interface and only returns partial and low quality audio content. However, to protect privacy of certain audio data (e.g voice mail) the use of the visualizer requires the permission android.permission.RECORD_AUDIO.

The audio session ID passed to the constructor indicates which audio content should be visualized:

  • If the session is 0, the audio output mix is visualized
  • If the session is not 0, the audio from a particular MediaPlayer or AudioTrack using this audio session is visualized

Two types of representation of audio content can be captured:

  • Waveform data: consecutive 8-bit (unsigned) mono samples by using the getWaveForm(byte[]) method
  • Frequency data: 8-bit magnitude FFT by using the getFft(byte[]) method

The length of the capture can be retrieved or specified by calling respectively getCaptureSize() and setCaptureSize(int) methods. Note that the size of the FFT is half of the specified capture size but both sides of the spectrum are returned yielding in a number of bytes equal to the capture size. The capture size must be a power of 2 in the range returned by getCaptureSizeRange().

In addition to the polling capture mode described above with getWaveForm(byte[]) and getFft(byte[]) methods, a callback mode is also available by installing a listener by use of the setDataCaptureListener(OnDataCaptureListener, int, boolean, boolean) method. The rate at which the listener capture method is called as well as the type of data returned is specified.

Before capturing data, the Visualizer must be enabled by calling the setEnabled(boolean) method. When data capture is not needed any more, the Visualizer should be disabled.

It is good practice to call the release() method when the Visualizer is not used anymore to free up native resources associated to the Visualizer instance.

Creating a Visualizer on the output mix (audio session 0) requires permission MODIFY_AUDIO_SETTINGS

Summary

Nested Classes
interfaceVisualizer.OnDataCaptureListenerThe OnDataCaptureListener interface defines methods called by the Visualizer to periodically update the audio visualization capture. 
Constants
intALREADY_EXISTSInternal opreation status.
intERRORUnspecified error.
intERROR_BAD_VALUEOperation failed due to bad parameter value.
intERROR_DEAD_OBJECTOperation failed due to dead remote object.
intERROR_INVALID_OPERATIONOperation failed because it was requested in wrong state.
intERROR_NO_INITOperation failed due to bad object initialization.
intERROR_NO_MEMORYOperation failed due to lack of memory.
intSTATE_ENABLEDState of a Visualizer object that is active.
intSTATE_INITIALIZEDState of a Visualizer object that is ready to be used.
intSTATE_UNINITIALIZEDState of a Visualizer object that was not successfully initialized upon creation
intSUCCESSSuccessful operation.
Public Constructors
Visualizer(int audioSession)
Class constructor.
Public Methods
int getCaptureSize()
Returns current capture size.
static int[] getCaptureSizeRange()
Returns the capture size range.
boolean getEnabled()
Get current activation state of the visualizer.
int getFft(byte[] fft)
Returns a frequency capture of currently playing audio content.
static int getMaxCaptureRate()
Returns the maximum capture rate for the callback capture method.
int getSamplingRate()
Returns the sampling rate of the captured audio.
int getWaveForm(byte[] waveform)
Returns a waveform capture of currently playing audio content.
void release()
Releases the native Visualizer resources.
int setCaptureSize(int size)
Sets the capture size, i.e.
int setDataCaptureListener(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.
int setEnabled(boolean enabled)
Enable or disable the visualization engine.
Protected Methods
void finalize()
Called before the object's memory is reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int ALREADY_EXISTS

Since: API Level 9

Internal opreation status. Not returned by any method.

Constant Value: -2 (0xfffffffe)

public static final int ERROR

Since: API Level 9

Unspecified error.

Constant Value: -1 (0xffffffff)

public static final int ERROR_BAD_VALUE

Since: API Level 9

Operation failed due to bad parameter value.

Constant Value: -4 (0xfffffffc)

public static final int ERROR_DEAD_OBJECT

Since: API Level 9

Operation failed due to dead remote object.

Constant Value: -7 (0xfffffff9)

public static final int ERROR_INVALID_OPERATION

Since: API Level 9

Operation failed because it was requested in wrong state.

Constant Value: -5 (0xfffffffb)

public static final int ERROR_NO_INIT

Since: API Level 9

Operation failed due to bad object initialization.

Constant Value: -3 (0xfffffffd)

public static final int ERROR_NO_MEMORY

Since: API Level 9

Operation failed due to lack of memory.

Constant Value: -6 (0xfffffffa)

public static final int STATE_ENABLED

Since: API Level 9

State of a Visualizer object that is active.

Constant Value: 2 (0x00000002)

public static final int STATE_INITIALIZED

Since: API Level 9

State of a Visualizer object that is ready to be used.

Constant Value: 1 (0x00000001)

public static final int STATE_UNINITIALIZED

Since: API Level 9

State of a Visualizer object that was not successfully initialized upon creation

Constant Value: 0 (0x00000000)

public static final int SUCCESS

Since: API Level 9

Successful operation.

Constant Value: 0 (0x00000000)

Public Constructors

public Visualizer (int audioSession)

Since: API Level 9

Class constructor.

Parameters
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
RuntimeException
UnsupportedOperationException

Public Methods

public int getCaptureSize ()

Since: API Level 9

Returns current capture size.

Returns
  • the capture size in bytes.

public static int[] getCaptureSizeRange ()

Since: API Level 9

Returns the capture size range.

Returns
  • the mininum capture size is returned in first array element and the maximum in second array element.

public boolean getEnabled ()

Since: API Level 9

Get current activation state of the visualizer.

Returns
  • true if the visualizer is active, false otherwise

public int getFft (byte[] fft)

Since: API Level 9

Returns a frequency capture of currently playing audio content. The capture is a 8-bit magnitude FFT. Note that the size of the FFT is half of the specified capture size but both sides of the spectrum are returned yielding in a number of bytes equal to the capture size. .

This method must be called when the Visualizer is enabled.

Parameters
fft array of bytes where the FFT should be returned
Returns
See Also

public static int getMaxCaptureRate ()

Since: API Level 9

Returns the maximum capture rate for the callback capture method. This is the maximum value for the rate parameter of the setDataCaptureListener(OnDataCaptureListener, int, boolean, boolean) method.

Returns
  • the maximum capture rate expressed in milliHertz

public int getSamplingRate ()

Since: API Level 9

Returns the sampling rate of the captured audio.

Returns
  • the sampling rate in milliHertz.

public int getWaveForm (byte[] waveform)

Since: API Level 9

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 getCaptureSize().

This method must be called when the Visualizer is enabled.

Parameters
waveform array of bytes where the waveform should be returned
Returns

public void release ()

Since: API Level 9

Releases the native Visualizer resources. It is a good practice to release the visualization engine when not in use.

public int setCaptureSize (int size)

Since: API Level 9

Sets the capture size, i.e. the number of bytes returned by getWaveForm(byte[]) and getFft(byte[]) methods. The capture size must be a power of 2 in the range returned by getCaptureSizeRange(). This method must not be called when the Visualizer is enabled.

Parameters
size requested capture size
Returns

public int setDataCaptureListener (Visualizer.OnDataCaptureListener listener, int rate, boolean waveform, boolean fft)

Since: API Level 9

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.

Parameters
listener OnDataCaptureListener registered
rate rate in milliHertz at which the capture should be updated
waveform true if a waveform capture is requested: the onWaveFormDataCapture() method will be called on the OnDataCaptureListener interface.
fft true if a frequency capture is requested: the onFftDataCapture() method will be called on the OnDataCaptureListener interface.
Returns

public int setEnabled (boolean enabled)

Since: API Level 9

Enable or disable the visualization engine.

Parameters
enabled requested enable state
Returns

Protected Methods

protected void finalize ()

Since: API Level 9

Called before the object's memory is reclaimed by the VM. This can only happen once the garbage collector has detected that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.