李钟意讲前端

外观

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

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

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

方法概览 ​

方法名称描述参数返回值备注
initializeVLC初始化 libVLC 实例。pluginPath (string, 可选): 插件路径。Promise<void>在执行其他操作之前必须先调用此方法。
registerEventCallback注册一个回调函数以接收媒体播放器事件。callback (Function): 一个用于处理事件的 JavaScript 函数。void每当事件发生时，回调函数将被调用并传递事件数据。
playMedia播放指定的媒体文件或流。mediaPath (string): 媒体文件的路径或 URL。
cache (number, 可选): 网络缓存时间（毫秒，默认 5000）。		void在播放前需要设置输出窗口。
stopMedia停止当前正在播放的媒体。无void停止播放并释放媒体播放器资源。
pauseMedia暂停或恢复媒体播放。无boolean返回 true 表示播放已恢复，false 表示已暂停。
setOutputWindow设置输出窗口，用于渲染视频。nsViewPtr (Buffer): 包含 NSView 指针的 Buffer。void仅适用于 macOS 平台，用于将视频渲染到指定的 NSView。
setVolume设置音量等级。volume (number): 期望的音量等级（通常在 0 到 100 之间）。void
getVolume获取当前的音量等级。无number返回当前的音量等级。
getPlaybackProgress获取当前的播放进度。无number返回一个介于 0.0 和 1.0 之间的浮点数，表示播放进度。
setPlaybackProgress设置播放进度。progress (number): 一个介于 0.0 和 1.0 之间的浮点数，表示期望的播放位置。void如果媒体已结束，则从指定位置重新开始播放。
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。
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 表示成功，其他数字表示特定错误。

详细方法说明 ​

initializeVLC(pluginPath?: string) ​

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

  • 参数:

    • pluginPath (string, 可选): 插件的路径。如果提供，将使用该路径加载 libVLC 插件。

  • 返回值:

    • Promise<void>: 初始化完成时解析。如果初始化失败，Promise 将被拒绝。

  • 使用示例:

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

registerEventCallback(callback: Function) ​

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

  • 参数:

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

  • 返回值:

    • void

  • 使用示例:

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

playMedia(mediaPath: string, cache?: number) ​

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

  • 参数:

    • mediaPath (string): 媒体文件的路径或 URL。
    • cache (number, 可选): 网络缓存时间，单位毫秒（默认值为 5000）。

  • 返回值:

    • void

  • 备注:

    • 在播放前需要调用 setOutputWindow 方法设置输出窗口。

  • 使用示例:

    javascript
    addon.playMedia("path/to/media.mp4", 3000);

stopMedia() ​

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

  • 参数:

    • 无

  • 返回值:

    • void

  • 使用示例:

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

pauseMedia() ​

暂停或恢复媒体播放。

  • 参数:

    • 无

  • 返回值:

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

  • 使用示例:

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

setOutputWindow(nsViewPtr: Buffer) ​

设置输出窗口，用于渲染视频。仅适用于 macOS 平台。

  • 参数:

    • nsViewPtr (Buffer): 包含 NSView 指针的 Buffer。

  • 返回值:

    • void

  • 使用示例:

    javascript
    const nsViewBuffer = Buffer.from([
  /* NSView 指针数据 */
]);
addon.setOutputWindow(nsViewBuffer);

setVolume(volume: number) ​

设置音量等级。

  • 参数:

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

  • 返回值:

    • void

  • 使用示例:

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

getVolume() ​

获取当前的音量等级。

  • 参数:

    • 无

  • 返回值:

    • number: 当前的音量等级。

  • 使用示例:

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

getPlaybackProgress() ​

获取当前的播放进度。

  • 参数:

    • 无

  • 返回值:

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

  • 使用示例:

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

setPlaybackProgress(progress: number) ​

设置播放进度。

  • 参数:

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

  • 返回值:

    • void

  • 备注:

    • 如果媒体已结束，则从指定位置重新开始播放。

  • 使用示例:

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

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 表示正常速度）。

  • 返回值:

    • void

  • 使用示例:

    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}`);

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 表示成功，其他值表示特定错误）。

  • 备注:

    • 本地文件需要以 file:/// 开头才能生效。

  • 使用示例:

    javascript
    const status = addon.addSubtitleFile("file:///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() 来处理异步操作。
  • 错误处理: 某些方法返回状态码以指示成功或特定错误。请确保在应用程序中适当处理这些状态码。
  • 平台相关参数: setOutputWindow 方法仅适用于 macOS 平台，用于将视频渲染到指定的 NSView。确保传递正确的 NSView 指针。
  • 日志记录: 日志记录在代码中默认启用。如果需要调整日志设置，请根据需要修改源代码或添加相应的方法。
  • 事件处理: 确保使用 registerEventCallback 注册事件回调，以有效地处理媒体播放器事件。

示例用法 ​

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

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

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

    // 设置输出窗口（假设你有一个 NSView 指针的 Buffer）
    const nsViewBuffer = Buffer.from([
      /* NSView 指针数据 */
    ]);
    addon.setOutputWindow(nsViewBuffer);

    // 播放媒体
    addon.playMedia("file:///path/to/media.mp4", 3000);

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

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

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

    // 设置播放进度
    addon.setPlaybackProgress(0.5); // 跳转到媒体的中间位置

    // 5 秒后暂停播放
    setTimeout(() => {
      const isPlaying = addon.pauseMedia();
      console.log(`播放状态已 ${isPlaying ? "恢复" : "暂停"}。`);
    }, 5000);
  })
  .catch((err) => {
    console.error("初始化 VLC 失败:", err);
  });

方法对比 ​

通用方法名称macOS 特定方法名称描述
pauseOrResumepauseMedia在通用版本中，此方法用于切换暂停和恢复播放。在 macOS 版本中，名称更改为 pauseMedia，功能相同。
setOutputWindow无macOS 版本新增的方法，用于设置输出窗口。

确保在使用这些方法时，按照文档中的说明传递正确的参数，尤其是 macOS 平台特有的参数，如 nsViewPtr。