李钟意讲前端

外观

咨询/接单/付费bug修复/学习交流群

Electron Node Addon libVLC 接口文档（Windows 版本） ​

本文档详细介绍了 Node.js 插件中用于调用 libVLC 的各个方法。每个方法都包括其功能描述、参数说明、返回值以及相关备注。

方法概览 ​

方法名称描述参数返回值备注
registerEventCallback注册一个回调函数以接收媒体播放器事件。callback (Function): 一个用于处理事件的 JavaScript 函数。void每当事件发生时，回调函数将被调用并传递事件数据。
initializeVLC初始化 libVLC 实例。无Promise<void>在执行其他操作之前必须先调用此方法。
playMedia播放指定的媒体文件或流。mediaPath (string): 媒体文件的路径或 URL。
cache (number, 可选): 网络缓存时间（毫秒，默认 5000）。
hwnd (number|Buffer, 可选): 窗口句柄（平台相关）。		Promise<number>成功启动播放后返回媒体播放器实例标识符。
stopMedia停止当前正在播放的媒体。无void停止播放并释放媒体播放器资源。
pauseOrResume切换暂停和恢复媒体播放状态。无boolean返回 true 表示播放已恢复，false 表示已暂停。
setPlaybackProgress设置播放进度。progress (number): 一个介于 0.0 和 1.0 之间的浮点数，表示期望的播放位置。void如果媒体已结束，则从指定位置重新开始播放。
getPlaybackProgress获取当前的播放进度。无number返回一个介于 0.0 和 1.0 之间的浮点数，表示播放进度。
setVolume设置音量等级。volume (number): 期望的音量等级（通常在 0 到 100 之间）。void
getVolume获取当前的音量等级。无number返回当前的音量等级。
getMediaLength获取媒体的总长度（毫秒）。无number如果无法获取长度，则基于当前播放时间和位置进行估算。
getCurrentPlaybackTime获取当前的播放时间（毫秒）。无number返回已播放的时间，以毫秒为单位。
getPlaybackRate获取当前的播放速率。无number返回播放速率（例如，1.0 表示正常速度）。
setPlaybackRate设置播放速率。rate (number): 期望的播放速率（例如，1.0 表示正常速度）。void允许加快或减慢播放速度。
getPlayerState获取媒体播放器的当前状态。无string可能的状态包括 "nothing-special"、"opening"、
"buffering"、"playing"、"paused"、"stopped"、
"ended"、"error"、"unknown"。
isMediaEnded检查媒体播放是否已结束。无boolean如果播放已结束，返回 true，否则返回 false。
setLoggingEnabled启用或禁用日志记录。enabled (boolean): true 启用日志，false 禁用日志。void默认情况下日志记录是禁用的。
setMaxLogSize设置日志文件的最大大小。maxSize (number): 日志文件的最大大小（字节，例如 1048576 表示 1MB）。void日志文件超过此大小后将进行日志轮换。
setLogFilePath设置日志文件的路径。path (string): 日志文件的完整路径。void如果日志文件已打开，将关闭当前文件并使用新路径。
getSubtitleTracks获取可用的字幕轨道。无Array<Object>每个对象包含 id (number)、name (string)
和 isActive (boolean)。
setSubtitleTrack设置活动的字幕轨道。trackID (number): 要激活的字幕轨道 ID。number返回 0 表示成功，其他数字表示特定错误。
addSubtitleFile添加一个字幕文件到媒体播放器。subtitlePath (string): 字幕文件的路径。number返回 0 表示成功，其他数字表示特定错误。
getAudioTracks获取可用的音频轨道。无Array<Object>每个对象包含 id (number)、name (string)
和 isActive (boolean)。
setAudioTrack设置活动的音频轨道。trackID (number): 要激活的音频轨道 ID。number返回 0 表示成功，其他数字表示特定错误。

详细方法说明 ​

registerEventCallback(callback: Function) ​

注册一个 JavaScript 回调函数，用于处理媒体播放器事件。

  • 参数:

    • callback (Function): 一个函数，当事件发生时将被调用，并接收事件数据。

  • 使用示例:

    javascript
    addon.registerEventCallback((eventType, value) => {
  console.log(`事件: ${eventType}, 值: ${value}`);
});

initializeVLC() ​

初始化 libVLC 实例。必须在执行其他操作之前调用此方法。

  • 返回值:

    • Promise<void>: 初始化完成时解析。

  • 使用示例:

    javascript
    addon
  .initializeVLC()
  .then(() => {
    console.log("VLC 初始化成功。");
  })
  .catch((err) => {
    console.error("VLC 初始化失败:", err);
  });

playMedia(mediaPath: string, cache?: number, hwnd?: number | Buffer) ​

播放指定的媒体文件或流。

  • 参数:

    • mediaPath (string): 媒体文件的路径或 URL。
    • cache (number, 可选): 网络缓存时间，单位毫秒（默认值为 5000）。
    • hwnd (number | Buffer, 可选): 用于渲染的窗口句柄（平台相关）。

  • 返回值:

    • Promise<number>: 成功启动播放后解析，并返回媒体播放器实例标识符。

  • 使用示例:

    javascript
    addon
  .playMedia("path/to/media.mp4", 3000)
  .then((playerId) => {
    console.log("媒体正在播放，播放器 ID:", playerId);
  })
  .catch((err) => {
    console.error("播放媒体失败:", err);
  });

stopMedia() ​

停止当前正在播放的媒体并释放媒体播放器资源。

  • 使用示例:

    javascript
    addon.stopMedia();
console.log("媒体播放已停止。");

pauseOrResume() ​

切换暂停和恢复媒体播放状态。

  • 返回值:

    • boolean: true 表示播放已恢复，false 表示已暂停。

  • 使用示例:

    javascript
    const isPlaying = addon.pauseOrResume();
console.log(`播放状态已 ${isPlaying ? "恢复" : "暂停"}。`);

setPlaybackProgress(progress: number) ​

设置播放进度。

  • 参数:

    • progress (number): 一个介于 0.0 和 1.0 之间的浮点数，表示期望的播放位置。

  • 使用示例:

    javascript
    addon.setPlaybackProgress(0.5); // 跳转到媒体的中间位置

getPlaybackProgress() ​

获取当前的播放进度。

  • 返回值:

    • number: 一个介于 0.0 和 1.0 之间的浮点数，表示播放进度。

  • 使用示例:

    javascript
    const progress = addon.getPlaybackProgress();
console.log(`当前播放进度: ${(progress * 100).toFixed(2)}%`);

setVolume(volume: number) ​

设置音量等级。

  • 参数:

    • volume (number): 期望的音量等级（通常在 0 到 100 之间）。

  • 使用示例:

    javascript
    addon.setVolume(75); // 设置音量为 75%

getVolume() ​

获取当前的音量等级。

  • 返回值:

    • number: 当前的音量等级。

  • 使用示例:

    javascript
    const currentVolume = addon.getVolume();
console.log(`当前音量: ${currentVolume}%`);

getMediaLength() ​

获取媒体的总长度（毫秒）。

  • 返回值:

    • number: 媒体的总长度，以毫秒为单位。

  • 使用示例:

    javascript
    const length = addon.getMediaLength();
console.log(`媒体长度: ${length} 毫秒`);

getCurrentPlaybackTime() ​

获取当前的播放时间（毫秒）。

  • 返回值:

    • number: 已播放的时间，以毫秒为单位。

  • 使用示例:

    javascript
    const currentTime = addon.getCurrentPlaybackTime();
console.log(`当前播放时间: ${currentTime} 毫秒`);

getPlaybackRate() ​

获取当前的播放速率。

  • 返回值:

    • number: 当前的播放速率（例如，1.0 表示正常速度）。

  • 使用示例:

    javascript
    const rate = addon.getPlaybackRate();
console.log(`当前播放速率: ${rate}x`);

setPlaybackRate(rate: number) ​

设置播放速率。

  • 参数:

    • rate (number): 期望的播放速率（例如，1.0 表示正常速度）。

  • 使用示例:

    javascript
    addon.setPlaybackRate(1.5); // 将播放速度提高到 1.5 倍

getPlayerState() ​

获取媒体播放器的当前状态。

  • 返回值:

    • string: 播放器的当前状态（例如，"playing"、"paused"）。

  • 使用示例:

    javascript
    const state = addon.getPlayerState();
console.log(`播放器状态: ${state}`);

isMediaEnded() ​

检查媒体播放是否已结束。

  • 返回值:

    • boolean: 如果播放已结束，返回 true，否则返回 false。

  • 使用示例:

    javascript
    const ended = addon.isMediaEnded();
console.log(`媒体播放已结束? ${ended}`);

setLoggingEnabled(enabled: boolean) ​

启用或禁用日志记录。

  • 参数:

    • enabled (boolean): true 启用日志，false 禁用日志。

  • 使用示例:

    javascript
    addon.setLoggingEnabled(true); // 启用日志记录

setMaxLogSize(maxSize: number) ​

设置日志文件的最大大小。

  • 参数:

    • maxSize (number): 日志文件的最大大小，单位为字节（例如，1048576 表示 1MB）。

  • 使用示例:

    javascript
    addon.setMaxLogSize(2097152); // 设置日志文件最大大小为 2MB

setLogFilePath(path: string) ​

设置日志文件的路径。

  • 参数:

    • path (string): 日志文件的完整路径。

  • 使用示例:

    javascript
    addon.setLogFilePath("/var/logs/vlc_addon.log");

getSubtitleTracks() ​

获取可用的字幕轨道。

  • 返回值:

    • Array<Object>: 包含字幕轨道对象的数组，每个对象包括：
      • id (number): 轨道标识符。
      • name (string): 轨道名称。
      • isActive (boolean): 表示该轨道是否当前激活。

  • 使用示例:

    javascript
    const subtitles = addon.getSubtitleTracks();
subtitles.forEach((track) => {
  console.log(
    `ID: ${track.id}, 名称: ${track.name}, 活动状态: ${track.isActive}`
  );
});

setSubtitleTrack(trackID: number) ​

设置活动的字幕轨道。

  • 参数:

    • trackID (number): 要激活的字幕轨道 ID。

  • 返回值:

    • number: 状态码（0 表示成功，其他值表示特定错误）。

  • 使用示例:

    javascript
    const status = addon.setSubtitleTrack(2);
if (status === 0) {
  console.log("字幕轨道设置成功。");
} else {
  console.error(`设置字幕轨道失败。状态码: ${status}`);
}

addSubtitleFile(subtitlePath: string) ​

向媒体播放器添加一个字幕文件。

  • 参数:

    • subtitlePath (string): 字幕文件的路径。

  • 返回值:

    • number: 状态码（0 表示成功，其他值表示特定错误）。

  • 使用示例:

    javascript
    const status = addon.addSubtitleFile("path/to/subtitle.srt");
if (status === 0) {
  console.log("字幕文件添加成功。");
} else {
  console.error(`添加字幕文件失败。状态码: ${status}`);
}

getAudioTracks() ​

获取可用的音频轨道。

  • 返回值:

    • Array<Object>: 包含音频轨道对象的数组，每个对象包括：
      • id (number): 轨道标识符。
      • name (string): 轨道名称。
      • isActive (boolean): 表示该轨道是否当前激活。

  • 使用示例:

    javascript
    const audioTracks = addon.getAudioTracks();
audioTracks.forEach((track) => {
  console.log(
    `ID: ${track.id}, 名称: ${track.name}, 活动状态: ${track.isActive}`
  );
});

setAudioTrack(trackID: number) ​

设置活动的音频轨道。

  • 参数:

    • trackID (number): 要激活的音频轨道 ID。

  • 返回值:

    • number: 状态码（0 表示成功，其他值表示特定错误）。

  • 使用示例:

    javascript
    const status = addon.setAudioTrack(1);
if (status === 0) {
  console.log("音频轨道设置成功。");
} else {
  console.error(`设置音频轨道失败。状态码: ${status}`);
}

注意事项 ​

  • Promises: 返回 Promise 的方法应使用 .then() 和 .catch() 来处理异步操作。
  • 错误处理: 某些方法返回状态码以指示成功或特定错误。请确保在应用程序中适当处理这些状态码。
  • 平台相关参数: playMedia 方法中的 hwnd 参数是平台相关的。在 Windows 上，它期望一个数字类型的窗口句柄，而在 macOS 上，它期望一个包含 NSView 指针的 Buffer。
  • 日志记录: 必须使用 setLoggingEnabled(true) 启用日志记录后，日志信息才会被记录。日志文件路径和最大日志大小可以分别使用 setLogFilePath 和 setMaxLogSize 进行配置。
  • 事件处理: 确保使用 registerEventCallback 注册事件回调，以有效地处理媒体播放器事件。

示例用法 ​

javascript
const addon = require("./build/Release/addon");

// 初始化 VLC
addon
  .initializeVLC()
  .then(() => {
    console.log("VLC 初始化完成。");

    // 注册事件回调
    addon.registerEventCallback((eventType, value) => {
      console.log(`事件: ${eventType}, 值: ${value}`);
    });

    // 播放媒体
    return addon.playMedia("path/to/media.mp4");
  })
  .then((playerId) => {
    console.log(`媒体正在播放，播放器 ID: ${playerId}`);

    // 设置音量
    addon.setVolume(80);

    // 5 秒后暂停播放
    setTimeout(() => {
      const isPlaying = addon.pauseOrResume();
      console.log(`播放状态已 ${isPlaying ? "恢复" : "暂停"}。`);
    }, 5000);
  })
  .catch((err) => {
    console.error("错误:", err);
  });