If you are building an application with LibVLC and attempting to use audio processing filters like karaoke, you may encounter an unexpected hurdle: passing --audio-filter=karaoke to libvlc_new() works seamlessly from the VLC desktop CLI, but completely fails or gets ignored when using the C API.

Why Does libvlc_new() Ignore Audio Filters?

Starting with LibVLC 2.x and continuing through 3.x, the VLC development team deprecated and restricted passing many media-specific and playback-related configuration options directly to libvlc_new(). This design choice was implemented for security, process isolation, and thread safety.

Options passed to libvlc_new() are intended solely for process-wide instance configuration (such as logging verbosity or plugin paths). Playback options, including track selection and audio filters, must be applied to individual media items or configured through dedicated API functions.

The Solution: Apply Options to the Media Object

Instead of passing the argument to libvlc_new(), you should apply it directly to your media item using libvlc_media_add_option(). Note the syntax change: media-specific options use a colon (:) instead of a double-dash (--).

libvlc_media_add_option(m, ":audio-filter=karaoke");

Full Working Code Example

Here is the updated, working C implementation using VLC 3.0.x on Linux:

/* Compile with:
   gcc $(pkg-config --cflags libvlc) sample.c -o sample $(pkg-config --libs libvlc)
*/
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <vlc/vlc.h>

int main(int argc, char **argv)
{
    libvlc_instance_t *inst;
    libvlc_media_player_t *mp;
    libvlc_media_t *m;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <path_to_media_file>\n", argv[0]);
        return 1;
    }

    // 1. Initialize instance with generic arguments (e.g., enable verbosity for debugging)
    const char *args[] = {
        "--no-video-title-show",
        "--verbose=1"
    };
    inst = libvlc_new(2, args);
    if (!inst) {
        fprintf(stderr, "Failed to initialize LibVLC\n");
        return 1;
    }

    // 2. Create the media item
    m = libvlc_media_new_path(inst, argv[1]);
    if (!m) {
        fprintf(stderr, "Failed to create media instance\n");
        libvlc_release(inst);
        return 1;
    }

    // 3. Attach the karaoke filter to this specific media
    libvlc_media_add_option(m, ":audio-filter=karaoke");

    // 4. Create player environment
    mp = libvlc_media_player_new_from_media(m);

    // The media object can be released now that the player has it
    libvlc_media_release(m);

    // 5. Play media
    libvlc_media_player_play(mp);

    // Play for 10 seconds to verify voice removal/attenuation
    sleep(10);

    // 6. Cleanup
    libvlc_media_player_stop(mp);
    libvlc_media_player_release(mp);
    libvlc_release(inst);

    return 0;
}

Important Considerations & Troubleshooting

  • Colon vs. Double Hyphen: Always use :audio-filter=karaoke inside libvlc_media_add_option(). If you use --audio-filter, LibVLC will reject or ignore the option.
  • Audio Track Characteristics: The karaoke filter works by subtracting the right channel from the left channel to cancel out center-panned audio (where lead vocals are traditionally mixed). If you test with a mono file or a stereo file where vocals are off-center, the filter will not produce the expected vocal reduction.
  • Inspection with Verbose Logs: If you are unsure whether a filter is loading, instantiate LibVLC with "-vvv" or "--verbose=2". Look at the terminal output during playback initialization for messages from karaoke filter or audio filter modules confirming the filter was inserted into the audio chain.