Audio Equalizer

Building on previous tutorials, we will now show you how to use the audio equalizer.

The audio equalizer enables you to dynamically adjust the sound coming out of your media player by amplifying the audio signals in various frequency ranges.

The audio equalizer was first introduced with VLC 2.2.0.

Let's Get Started

You should now already have a basic template for how to create a vlcj application, so this tutorial will no longer duplicate all of the code each time - instead we'll just show the new code fragments.

Creating an Equalizer

To create an equalizer instance, you need to use a media player factory. How you get a media player factory depends on how you created your media player. You either create a factory directly, or if you use an EmbeddedMediaPlayerComponent as these tutorials have done, you simply get the factory from the media player component.

MediaPlayerFactory factory = mediaPlayerComponent.getMediaPlayerFactory();

You can create a blank equalizer with initially zeroed values:

MediaPlayerFactory factory = mediaPlayerComponent.getMediaPlayerFactory();
Equalizer equalizer = factory.newEqualizer();

You can create an equalizer from one of the named presets:

MediaPlayerFactory factory = mediaPlayerComponent.getMediaPlayerFactory();
Equalizer equalizer = factory.newEqualizer(presetName);

The presetName parameter must match one of the presets known to LibVLC, you can get a list of these names from the factory:

List<String> presetNames = factory.getEqualizerPresetNames();

The preset names are things like Flat, Classical, Club, Dance, Headphones and so on.

Setting the Equalizer

When you have created an equalizer instance you must associate it with a media player instance before it has any effect.

mediaPlayerComponent.getMediaPlayer().setEqualizer(equalizer);

This equalizer instance is now associated with the media player. The media player will listen for any subsequent changes to the equalizer properties and will dynamically and automatically apply the new equalizer settings.

To disable the equalizer, you disaccociate it from the media player by setting the value to null.

mediaPlayerComponent.getMediaPlayer().setEqualizer(null);

Setting Equalizer Values

The equalizer instance is essentially a value object with a preamp property and a collection of individual frequency amplification amp properties. You can get and set these values as you would any other value object.

As mentioned previously, if the equalizer instance is associated with a media player then the changes will be automatically and immediately applied.

An equalizer instance created from a preset is nothing special, it is just like a regular equalizer instance but is initialised with different values. You can change the values in equalizer instances created from a preset just like any other.

equalizer.setPreamp(newPreamp);
equalizer.setAmp(ampNumber, newAmpValue);

The ampNumber is the index of the frequency value to set (or get). The allowable numbers range from 0 to equalizer.getBandCount().

The maximum and minimum allowable amplification values are defined in LibVlcConst.MAX_GAIN and LibVlcConst.MIN_GAIN.

User Interface Components

Ordinarily equalizer instance values will be set by hooking up user interface slider controls, and responding to change events. The preamp and each individual frequency will each have their own slider control and your application will listen for value change events on each slider and update the equalizer instance accordingly.

Your user interface component should also add a listener to the equalizer instance so that it may update the slider control values if the equalizer instance is changed by some other means.

When building a user interface component it is useful to label the slider controls with the corresponding frequency band. Leaving aside the preamp, the frequency bands are available from the media player factory.

List<Float> bands = factory.getEqualizerBandFrequencies();

Each element in the returned list is a frequency value in Hz and can be used to create an appropriate label for a slider control.

Summary

This tutorial has sketched out how to use the vlcj audio equalizer. You have seen how to create equalizer instances, how to use presets, how to enable and disable the audio equalizer and how to change values. You have also seen how you can create a set of user interface controls to interact with the equalizer.