基於 VLCJ 製作 Java 視頻播放器：從環境搭建到播放實現

基於 VLCJ 製作 Java 視頻播放器：從環境搭建到播放實現

Java 原生媒體播放能力有限，VLCJ 作為 LibVLC 的 Java 封裝，提供了強大的跨平台視頻播放能力。本文記錄從零搭建 Java 視頻播放器的完整流程。

一、環境準備

1. 安裝 VLC 播放器

• 下載地址：VideoLAN 官網
• 安裝後記住安裝目錄（如 C:\Program Files\VideoLAN\VLC）

2. 下載 VLCJ 庫

• Maven 坐標：

  <dependency>
      <groupId>uk.co.caprica</groupId>
      <artifactId>vlcj</artifactId>
      <version>4.7.1</version> <!-- 或最新版 -->
  </dependency>

• 或手動下載 JAR：vlcj-4.7.1.jar、jna-5.x.jar、jna-platform-5.x.jar

3. 下載 SLF4J 日志門面

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>1.7.30</version>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-nop</artifactId> <!-- 無操作實現，避免日志噪音 -->
    <version>1.7.30</version>
</dependency>

4. 複製 VLC 核心庫到項目

從 VLC 安裝目錄複製以下文件到項目資源目錄（如 src/main/resources/native）：

• libvlc.dll
• libvlccore.dll
• plugins 文件夾（整個目錄）

二、項目結構示例

project-root
├── src/main/java
│   └── com/example/player/VideoPlayer.java
├── src/main/resources
│   └── native
│       ├── libvlc.dll
│       ├── libvlccore.dll
│       └── plugins/...

三、核心播放代碼

import uk.co.caprica.vlcj.binding.LibVlc;
import uk.co.caprica.vlcj.player.MediaPlayerFactory;
import uk.co.caprica.vlcj.player.embedded.EmbeddedMediaPlayer;
import uk.co.caprica.vlcj.runtime.RuntimeUtil;
import uk.co.caprica.vlcj.runtime.windows.WindowsRuntimeUtil;

import javax.swing.*;
import java.awt.*;

public class VideoPlayer {
    public static void main(String[] args) {
        // 1. 設置原生庫搜索路徑（關鍵步驟）
        System.setProperty("jna.library.path", "src/main/resources/native");
        // 或使用 RuntimeUtil 設置
        RuntimeUtil.setLibVlcLibraryPath("src/main/resources/native");

        // 2. 創建媒體播放器工廠
        MediaPlayerFactory factory = new MediaPlayerFactory();

        // 3. 創建嵌入式播放器
        EmbeddedMediaPlayer mediaPlayer = factory.mediaPlayers().newEmbeddedMediaPlayer();

        // 4. 創建 Swing 界面
        JFrame frame = new JFrame("VLCJ Player");
        frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
        frame.setLayout(new BorderLayout());

        // 視頻顯示面板
        Canvas videoSurface = new Canvas();
        videoSurface.setBackground(Color.BLACK);
        frame.add(videoSurface, BorderLayout.CENTER);

        // 控制面板（簡易）
        JPanel controlPanel = new JPanel();
        JButton btnPlay = new JButton("播放");
        JButton btnPause = new JButton("暫停");
        JButton btnStop = new JButton("停止");
        controlPanel.add(btnPlay);
        controlPanel.add(btnPause);
        controlPanel.add(btnStop);
        frame.add(controlPanel, BorderLayout.SOUTH);

        // 5. 綁定視頻輸出面板
        mediaPlayer.videoSurface().set(videoSurface);

        // 6. 事件綁定
        btnPlay.addActionListener(e -> mediaPlayer.media().play("file:///D:/test.mp4"));
        btnPause.addActionListener(e -> mediaPlayer.controls().pause());
        btnStop.addActionListener(e -> mediaPlayer.controls().stop());

        frame.setSize(800, 600);
        frame.setLocationRelativeTo(null);
        frame.setVisible(true);
    }
}

四、關鍵配置詳解

五、常見問題排查

• UnsatisfiedLinkError：dll 路徑錯誤，檢查 jna.library.path 和 dll 是否存在
• 視頻無畫面只有聲音：Canvas 未正確綁定，或缺少 plugins 目錄
• 64 位系統報錯：確保 JDK、VLC、DLL 都是 64 位（或都是 32 位）
• Linux/Mac 部署：需安裝系統級 VLC，設置 vlcj.lib.path 指向 libvlc.so/libvlc.dylib

六、進階功能擴展

• 播放列表管理：mediaPlayer.media().prepare() 預加載
• 字幕支持：mediaPlayer.subPicture().setSubPictureFile()
• 截圖/錄製：mediaPlayer.saveSnapshot()
• JavaFX 集成：使用 JavaFXVideoSurface 替代 Canvas

VLCJ + LibVLC 是 Java 平台上功能最全、兼容性最好的視頻播放方案，掌握它能為應用快速添加專業級媒體播放能力。