MPC-BE 播放器在鸿蒙PC上的状态调度实践:多格式播放列表解析、字幕时间轴偏移与会话恢复

MPC-BE 媒体播放器项目采用 Electron 壳方案,以 HTML、CSS 和 JavaScript 实现本地媒体播放界面、M3U/PLS/JSON 播放列表、SRT/VTT/ASS/MicroDVD 字幕解析、时间轴整体偏移、A-B 循环、WAV 文件头分析、窗口视口截图与会话保存恢复。本文按照实际业务源码、鸿蒙工程配置和三张应用截图,拆解播放器的状态调度、纯 JavaScript 引擎与文件交互链路,并说明格式兼容、字幕写回、目录范围和发布配置的边界。

这里的 MPC-BE 是参考 Media Player Classic - Black Edition 通用使用习惯的独立 JavaScript 播放器外壳,不是将上游原生播放器及其解码器、滤镜和全部功能完整移植到鸿蒙。文章中的本机验证仅覆盖 JavaScript 语法与少量引擎输入输出;截图来自项目提供的素材,不代表本文重新执行了 HAP 构建、设备安装或全格式播放验收。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_MPC-BE

一、技术架构分析

1.1 整体架构

本项目可以分成四层:

  • 鸿蒙宿主层:electron 是 entry 模块,通过本地依赖引入 web_engine;后者保存业务资源。
  • Electron 主进程:创建窗口,注册 19 条请求响应 IPC,处理文件对话框、文本读写、文件头读取、目录扫描、偏好与会话。
  • 渲染调度层:renderer.js 维护队列、当前索引、播放进度、字幕、A-B 标记、截图记录和界面状态。
  • 纯 JavaScript 引擎层:三个引擎分别处理播放列表、字幕时间轴和媒体头部信息,不依赖 DOM 完成核心计算。

实际播放链路与文本解析链路不同:字幕和列表内容通过 IPC 读取;媒体文件路径被转换为 file URL,直接赋给页面中的 video 元素,再由宿主提供的媒体内核读取和解码。

因此,不能把“渲染层没有直接调用 fs”扩展成“所有媒体读取都经过主进程 guard”。目前路径检查主要约束对应文件 IPC,video.src 的加载另走媒体内核路径。

1.2 技术方案

对比项上游原生播放器的移植目标当前工程实际方案
应用定位保留原生播放器实现与完整功能独立 JavaScript 播放器外壳
播放与解码需要适配原生播放管线及相关组件页面 video 元素与宿主媒体内核
队列管理原生程序内部逻辑PlsEngine 与渲染层状态
字幕处理可能包含复杂样式与多轨排版解析时间和纯文本,DOM 叠加一条当前字幕
媒体信息完整容器、流与编码参数分析扩展名标签、文件头嗅探、WAV 块解析与内核元数据
交互界面原生桌面控件五面板、三列布局、自定义下拉与弹层
文件操作原生文件接口主进程 Node.js fs 与 Electron 对话框
鸿蒙交付原生应用包electron entry 模块与 web_engine 资源组成的 HAP 工程

这里的“纯 JavaScript”指业务解析与调度实现,并不表示运行时没有原生依赖。工程的 arm64-v8a 库目录包含 libelectron.so、libadapter.so、libc++_shared.so 和 libffmpeg.so;这些文件的存在也不能直接证明某个编码配置已经可用。

1.3 核心功能清单

功能模块当前代码具备的能力需要保留的边界
媒体选择26 项媒体扩展名过滤、文件多选、目录扫描白名单不是解码支持报告
播放控制播放、暂停、停止、定位、音量、倍速、A-B 标记实际播放效果依赖宿主内核与设备
播放列表M3U/M3U8、PLS、JSON 解析,导出 M3U不属于 HLS 流媒体播放实现
队列调度顺序、单曲、随机,去重与排序顺序模式末项会回到首项
字幕解析SRT、VTT、ASS/SSA、MicroDVD 文本字幕不保留完整 ASS 样式,不支持图像型 SUB
时间轴秒级统一模型、整体偏移、字幕定位负偏移可能裁切或丢弃字幕
媒体信息WAV 块分析、容器特征嗅探、大小与平均码率不是完整媒体探针或解码器
画面截图capturePage 截取播放区域,保存 PNG截取页面合成画面,不是原始视频帧
偏好与会话JSON 持久化、启动恢复队列与字幕路径不是音视频文件及字幕内容的完整备份

二、环境准备

2.1 开发环境要求

项目当前工程信息或准备要求
业务技术栈HTML5、CSS、Vanilla JavaScript、Electron
本文引擎验证环境Windows,Node.js v22.20.0
鸿蒙开发工具DevEco Studio 与匹配工程的 SDK、Hvigor、ohpm
compatibleSdkVersion5.0.5(17)
runtimeOSHarmonyOS
构建产品default
入口模块与目标electron / default
deviceTypes2in1、tablet
工程原生库目录electron/libs/arm64-v8a
签名与设备需按实际应用标识、证书、Profile 和目标设备核对;本文未验证安装

以上 SDK、产品与设备类型来自当前工程配置,不直接套用其他壳项目。业务 package.json 没有锁定桌面 Electron 版本,因此本机 Node 检查的结果不能代替鸿蒙内置 Electron/Chromium 的运行结果。

2.2 项目结构

业务资源已位于 web_engine 的 resfile 目录,不需要假设存在另一份待同步的 electron-apps 开发副本:

ohos_MPC-BE_electron-main/
└── ohos_hap/
    ├── AppScope/
    ├── build-profile.json5
    ├── electron/
    │   ├── oh-package.json5
    │   ├── libs/arm64-v8a/
    │   └── src/main/module.json5
    └── web_engine/
        └── src/main/
            ├── module.json5
            └── resources/resfile/resources/app/
                ├── main.js
                ├── renderer.js
                ├── index.html
                ├── package.json
                ├── engines/
                │   ├── media-engine.js
                │   ├── pls-engine.js
                │   └── sub-engine.js
                ├── samples/
                │   ├── demo-tone.wav
                │   ├── demo-pulse.wav
                │   ├── demo-tone.srt
                │   └── demo-pulse.ass
                └── styles/mpcbe.css

三个引擎与页面分开,使文本和字节运算可以直接在 Node 中验证,不必为文章搭建 DOM 仿真环境。

2.3 依赖说明

依赖或模块用途
Electron窗口、IPC、文件对话框、剪贴板、文件管理器定位、页面截图
Node.js fs / path主进程文件读写、目录扫描和路径处理
HTMLMediaElement文件加载、播放状态、时长、分辨率、定位、音量与倍速
PlsEngine列表格式解析、路径拼接、去重、排序和索引推进
SubEngine字幕解析、时间转换、偏移、当前字幕查找和序列化
MediaEngineWAV 头部、容器特征、格式化与数值钳制

业务 package.json 的实际内容如下:

{
  "name": "mpcbe",
  "version": "1.0.0",
  "description": "MPC-BE 媒体播放器(鸿蒙 PC Electron 壳):本地音视频播放、播放列表、字幕同步、A-B 循环与截图",
  "main": "main.js",
  "author": "ohos_hap",
  "license": "GPL-3.0"
}

该文件未声明第三方业务包,也没有 scripts 字段,不能直接照搬 npm start。三个引擎通过脚本导出浏览器全局对象,同时支持 CommonJS 导出;媒体引擎的 base64 转换在有 Buffer 时使用 Buffer,否则尝试 atob。

许可证必须另行核对:package.json 写 GPL-3.0,关于弹层写 Apache-2.0。本文记录现状,不替项目选择许可证,也不把 Electron 自身的 MIT 协议当成本项目的授权结论。

三、核心适配流程

3.1 主进程实现:窗口、目录范围与 19 条 IPC

窗口创建与启动顺序。 main.js 根据主屏工作区设置窗口宽高,使用系统边框、非透明背景和可调整尺寸:

function createWindow() {
  try {
    var display = screen.getPrimaryDisplay();
    var width = display.workAreaSize.width;
    var height = display.workAreaSize.height;
    mainWindow = new BrowserWindow({
      width: Math.floor(width * 0.92),
      height: Math.floor(height * 0.86),
      minWidth: 1024,
      minHeight: 640,
      frame: true,
      transparent: false,
      resizable: true,
      backgroundColor: '#14141f',
      title: WINDOW_TITLE,
      webPreferences: {
        nodeIntegration: true,
        contextIsolation: false
      }
    });
    mainWindow.loadFile('index.html');
    mainWindow.on('closed', function () { mainWindow = null; });
  } catch (e) {
    console.warn('[MPCBE] 创建窗口失败:', String(e && e.message));
  }
}

启动时先登记用户数据目录与应用自身目录,再恢复历史根目录,随后注册 IPC 并创建窗口。和某些同批壳应用不同,这份 main.js 没有调用 app.disableHardwareAcceleration();不能把其他项目的禁用加速片段写成当前实现。

统一 IPC 包装。 主进程通过本地 handle 包装器注册通道:

function handle(channel, fn) {
  ipcMain.handle(channel, async function (event, req) {
    try {
      return await fn(req || {});
    } catch (e) {
      return { success: false, error: errText(e), code: e && e.code };
    }
  });
}

实际 19 条通道按职责分组如下:

分组通道
运行信息与样例app:info、samples:list
目录与文件选择dir:choose、dir:forget、files:choose
扫描与读取fs:scan、fs:stat、fs:readText、fs:readBinary
写入与另存fs:writeText、fs:writeBinary、file:saveText
系统交互clip:write、shell:reveal、window:capture
偏好与会话prefs:get、prefs:set、session:save、session:load

file:saveText 不仅保存文本,也接受 base64 图片另存。统计通道时应核对 registerIpc 中的调用,而不是数 ipcMain.handle 出现几次。

目录范围。 主进程的范围判定先执行 path.resolve,再通过 isInside 比较目录边界:

function isAllowed(p) {
  var full = fwd(path.resolve(String(p || '')));
  for (var i = 0; i < allowedRoots.length; i++) {
    if (isInside(full, allowedRoots[i])) return true;
  }
  return false;
}

isInside 会统一分隔符,并在 Windows 下忽略大小写。选择目录、选择文件及另存文件都可能登记根目录;登记结果写进偏好文件,下次启动恢复仍存在的目录。userData 和应用自身目录受到内置保护,不能通过 dir:forget 删除。

这里保存的是应用自己的目录范围记录,不等同于系统持久授权凭证。当前实现没有 realpath 规范化;Node 集成开启,媒体 URL 也不经过这个函数,因此不能称为强沙箱。撤销某个子目录记录时,如果父目录仍在授权表中,其范围仍可能被父目录覆盖。

读取上限。 字幕和列表文本超过上限时直接拒绝,不返回截断文本;二进制读取则只取文件前缀并报告 truncated:

操作当前限制
fs:readText默认及最大 8 MiB
fs:readBinary默认 64 KiB,最大 4 MiB
fs:scan最多 4000 条结果,递归深度 0~4,默认 1
fs:stat最多处理输入的前 500 条路径
window:capturePNG 编码后检查 32 MiB
fs:writeBinarybase64 解码后检查 32 MiB

这些限制不是全局内存配额。file:saveText 的二进制另存分支没有同样的 32 MiB 检查,文本写入也没有复用 8 MiB 读取限制。app:info 回传五项 limits 字段,但当前 renderEnv 并没有把这些限制全部展示在设置面板。

3.2 五面板布局与媒体播放调度

页面以“导航栏—内容区—信息坞”组成三列,包含播放视口、播放列表、字幕与时间轴、媒体信息、设置与授权五个面板。核心播放元素不是 Canvas 解码器,而是一个原生 video 标签:

<video id="videoEl" class="stage-video" preload="metadata"></video>

三个引擎先于 renderer.js 加载,渲染层取得全局对象:

var ipc = require('electron').ipcRenderer;

var PlsE = window.PlsEngine;
var SubE = window.SubEngine;
var MedE = window.MediaEngine;

路径转换与媒体加载。 fileUrl 将本地路径转为 file URL,同时处理路径中的井号和问号:

function fileUrl(p) {
  var s = String(p || '').replace(/\\/g, '/');
  if (!s) return '';
  var prefix = s.charAt(0) === '/' ? 'file://' : 'file:///';
  return prefix + encodeURI(s).replace(/#/g, '%23').replace(/\?/g, '%3F');
}

loadIndex 先记录旧位置、切换当前索引并清除 A-B 标记,再设置 video.src、调用 load、发起文件头探测。是否开始播放受全局 autoPlay 偏好和本次 autoplay 选项共同控制。loadedmetadata 事件会用内核返回的有效时长更新当前条目;没有取得元数据的队列项可能仍显示“未知”。

文件 stat 与头部探测在媒体加载之后异步执行,并不是播放前必须通过的授权或存在性检查。把它们写成“验证成功后才播放”会改变实际执行顺序。

时间轴更新。 tick 通过 requestAnimationFrame 读取 currentTime,刷新进度、字幕和 A-B 回跳。字幕文本仅在命中索引变化时更新:

function updateSubtitle(t) {
  var idx = S.cuesShift.length ? SubE.cueAt(S.cuesShift, t) : -1;
  if (idx === S.cueIdx) return;
  S.cueIdx = idx;
  var node = $('subText');
  if (!node) return;
  node.textContent = idx >= 0 ? S.cuesShift[idx].text : '';
}

字幕通过 textContent 显示,不将字幕正文作为 HTML 注入。它是单条纯文本叠加,不是多个字幕轨道的同步排版。

A-B 与倍速。 A-B 按钮依次设置起点、设置终点、清除标记,B 至少晚于 A 0.2 秒。播放中的回跳逻辑如下:

function needABLoop(t) {
  if (S.abA == null || S.abB == null) return false;
  if (t < S.abB - 0.02) return false;
  seekTo(S.abA);
  return true;
}

这里依赖动画帧调度,不是采样级无缝循环。ended 处理的优先级是 A-B、单曲或 loopFile、autoNext、普通队列推进;A-B 的 ended 分支只 seek,没有显式再调用 play,不能据此保证媒体结束边界仍能无缝续播。

倍速下拉提供 0.5、0.75、1、1.25、1.5、2 六档;底层 clampRate 允许 0.25~4 的数值范围。引擎数值范围、UI 预设档位和具体文件的可播放倍速是三个不同概念。

3.3 播放列表引擎:统一条目、路径与队列索引

PlsEngine 将三种列表输入转换为统一的 path、title、dur 条目,渲染层再补充 kind 与 size:

格式解析方式
M3U/M3U8按行扫描,读取 #EXTINF 时长与标题,随后匹配媒体路径
PLS收集 FileN、TitleN、LengthN,按数字序号排序
JSON接受数组或带 items 数组的对象,条目可为路径字符串或对象

M3U8 在这里复用 M3U 文本列表处理,并没有实现 HLS 清单、分片和网络播放管线。

相对路径不是目录隔离。 resolvePath 的实际算法如下:

function resolvePath(raw, baseDir) {
  var s = String(raw == null ? '' : raw).trim().replace(/^["']|["']$/g, '');
  if (!s) return '';
  s = s.replace(/\\/g, '/');
  if (/^[A-Za-z]:\//.test(s) || s.charAt(0) === '/') return s;
  var base = String(baseDir || '').replace(/\\/g, '/').replace(/\/$/, '');
  if (!base) return s;
  var parts = (base + '/' + s).split('/');
  var out = [];
  for (var i = 0; i < parts.length; i++) {
    var seg = parts[i];
    if (seg === '' && i === 0) { out.push(''); continue; }
    if (seg === '.' || seg === '') continue;
    if (seg === '..') { if (out.length > 1) out.pop(); continue; }
    out.push(seg);
  }
  return out.join('/');
}

它允许相对路径中的上级跳转;绝对路径直接返回。本机案例中,以 /media/lists 为基目录,…/demo-pulse.wav 得到 /media/demo-pulse.wav。因此列表所在目录不是这段算法的安全边界;HTTP URL 也没有专门分支,不应把路径解析器当作通用 URL 解析器。

三种队列模式。 nextIndex 的完整实现展示了顺序末项回到首项、单曲保持当前索引、随机避免本次选中当前项的规则:

function nextIndex(len, cur, mode, rand) {
  if (!len || len < 1) return -1;
  var m = normMode(mode);
  if (m === 'one') return cur >= 0 && cur < len ? cur : 0;
  if (m === 'rand') {
    if (len === 1) return 0;
    var r = typeof rand === 'function' ? rand() : Math.random();
    var idx = Math.floor(r * len);
    if (idx >= len) idx = len - 1;
    if (idx < 0) idx = 0;
    if (idx === cur) idx = (idx + 1) % len;
    return idx;
  }
  if (cur < 0 || cur >= len - 1) return 0;
  return cur + 1;
}

随机模式不维护“已经听过”的历史集合,也不是整轮不重复洗牌;上一项仍按相邻索引回退。渲染层在播放结束时还会检查新旧索引是否相同,所以不能仅凭这个函数推断单条队列必然循环重播。

去重会将路径斜杠归一并统一转为小写,保留首次出现的条目。这在区分大小写的文件系统上可能合并本来不同的文件。排序会创建数组副本,但渲染层按路径恢复当前索引,重复路径情况下并非稳定的条目身份标识。

3.4 字幕引擎:多格式解析、偏移与写回

统一字幕模型。 不同格式最终归一为 start、end、text,时间单位为秒。SRT 与 VTT 共用箭头时间行解析;ASS 读取 Events 段和 Format 字段表;MicroDVD 将帧号除以帧率。

输入格式关键处理兼容边界
SRT箭头时间行、空行分段、多行文本时间解析采用 parseFloat,不是严格语法验证器
VTT识别 WEBVTT、提取时间与文本不完整保留区域、样式和 cue 布局设置
ASS/SSA根据 Format 查找 start、end、text样式覆盖标签被剥离,不渲染字体、特效或位置
MicroDVD{起始帧}{结束帧}文本,竖线换行无有效帧率时默认 23.976,不支持图像字幕

ASS 的 Text 通常位于最后一列并允许逗号,因此不能简单对整行执行无限次 split。当前实现只切前 n-1 个逗号:

function splitFields(s, n) {
  var out = [], from = 0, i;
  for (i = 0; i < n - 1; i++) {
    var k = s.indexOf(',', from);
    if (k < 0) break;
    out.push(s.slice(from, k));
    from = k + 1;
  }
  out.push(s.slice(from));
  return out;
}

这解决了常见 Text 末列的逗号保留问题,但不是任意字段排列下的通用 CSV 解析。样例中“粗体标签”四个字会保留,控制粗体的标签本身被去掉,不能将样例文案当作粗体渲染已实现的证据。

当前字幕查找。 cueAt 先二分定位最后一个起点不晚于当前时刻的字幕,再进行有限回退:

function cueAt(cues, t) {
  var arr = cues || [], lo = 0, hi = arr.length - 1, hit = -1;
  while (lo <= hi) {
    var mid = (lo + hi) >> 1;
    if (arr[mid].start <= t) { hit = mid; lo = mid + 1; }
    else hi = mid - 1;
  }
  while (hit >= 0) {
    if (t < arr[hit].end) return hit;
    if (hit === 0) return -1;
    if (arr[hit - 1].end > t) { hit -= 1; continue; }
    return -1;
  }
  return -1;
}

它适用于常见顺序字幕,但不能保证任意嵌套重叠区间都正确。本机最小案例包含 [0,10)、[1,2)、[3,4) 三条字幕,在第 5 秒返回 -1,未命中仍有效的第一条长字幕。这个结果需要如实保留,不能写成“全部重叠字幕均能正确显示”。

整体偏移。 原始字幕保存在 S.cues,显示与导出使用 S.cuesShift。每次根据原始数组重新平移,避免同一会话内重复累加到已偏移结果上:

function shiftCues(cues, offsetSec) {
  var off = Number(offsetSec) || 0;
  var out = [];
  (cues || []).forEach(function (c) {
    var s = c.start + off, e = c.end + off;
    if (e <= 0) return;
    if (s < 0) s = 0;
    out.push({ start: s, end: e, text: c.text });
  });
  out.sort(function (a, b) { return a.start - b.start || a.end - b.end; });
  return out;
}

渲染层把偏移限制在 -3600~3600 秒,保留两位小数。按钮每次调整 0.5 秒,方括号快捷键每次调整 0.1 秒。负偏移后,结束时间不大于零的字幕会丢弃,跨零字幕的起点会截为零。

字幕解析最多接收 20000 条 cue;表格只显示前 400 条,播放查找和导出仍使用保存的字幕数组。两者分别是解析限制与界面显示限制。

导出与覆盖不是同一风险等级。 导出 SRT 通过另存对话框写入新目标;覆盖原字幕先显示确认框,然后执行以下请求。该片段来自 overwriteSub 的确认回调,依赖当前 S 状态和 ipcCall:

ipcCall('fs:writeText', {
  path: S.subPath,
  text: SubE.toSRT(S.cuesShift),
  encoding: 'utf8bom'
}).then(function (r) {
  if (!r.success) {
    fail(r.error || '覆盖字幕失败');
    return;
  }
  ok('已覆盖原字幕 ' + S.cuesShift.length + ' 条', r.path);
  setText('subEnc', '已写回 ' + MedE.fmtBytes(r.bytes) + ' · ' + r.encoding);
});

此操作统一写成 SRT + UTF-8 BOM,但不会把原来的 .ass、.vtt 或 .sub 文件名改为 .srt,也没有自动备份或撤销。写回成功后未重建 S.cues、未清零 S.offset;下次重新读取已偏移文件时,仍可能再次应用已保存的偏移。涉及原始字幕时,优先另存 .srt 副本并核对内容更稳妥。

3.5 WAV 头分析、页面截图与会话持久化

只读头部,不搬运整段媒体。 probeMedia 通过 fs:readBinary 请求前 65536 字节,使用 MediaEngine.sniff 识别 RIFF/WAVE、FLAC、Ogg、MPEG 音频、ISO 基媒体等特征。扩展名标签和字节特征是两个信息来源,并不是解码成功判定。

WAV 的 fmt 和 data 不应被假定为固定偏移。wavInfo 从第 12 字节开始按 chunk 长度前进,并处理奇数长度填充。下面是该函数内部的块遍历片段,依赖四字符码与小端整数读取函数:

var off = 12, fmt = null, dataBytes = 0, chunks = [];
while (off + 8 <= b.length) {
  var id = fourcc(b, off);
  var size = u32(b, off + 4);
  chunks.push({ id: id, size: size });
  if (id === 'fmt ' && off + 8 + 16 <= b.length) {
    fmt = {
      format: u16(b, off + 8),
      channels: u16(b, off + 10),
      sampleRate: u32(b, off + 12),
      byteRate: u32(b, off + 16),
      blockAlign: u16(b, off + 20),
      bits: u16(b, off + 22)
    };
  } else if (id === 'data') {
    dataBytes = size;
  }
  off += 8 + size + (size % 2);
  if (size === 0) break;
}

时长优先使用 dataBytes / byteRate 推算;字节率缺失时尝试由采样率、声道和位深计算。这里只分析头部声明:data 块位于读取范围之外时可能得不到有效时长;截断或损坏文件也不能通过头部推算完成完整性验收。扩展格式码的标签映射不等于已经解析全部子格式。

媒体信息中的“平均码率”由整个文件大小除以时长得到,包含容器开销,不是单独音轨或视频轨的编码参数。没有有效 videoWidth 时界面会显示“纯音频”,在元数据尚未加载或解码失败时也要谨慎解释。

截图链路。 takeShot 读取 stage 的页面矩形并传给 window:capture;主进程使用 capturePage,再转成 PNG。返回结果通过 fs:writeBinary 写入 userData/shots,渲染层记录尺寸、路径、时间点和 base64。

截图对象是页面当前合成区域,可能包含字幕、标题与 OSD,不等于媒体原始分辨率的一帧。播放面板隐藏后 stage 矩形可能不可用;连续截图的内存记录没有数量上限,文件名只精确到秒,同秒保存存在同名覆盖风险。这些都需要在实际交互验收中检查。

会话数据。 collectSession 保存队列和当前设置,代码如下:

function collectSession() {
  savePos();
  return {
    list: S.list.map(function (it) {
      return { path: it.path, title: it.title, dur: it.dur, size: it.size };
    }),
    index: S.index,
    pos: S.pos,
    offset: S.offset,
    mode: S.mode,
    volume: S.vol,
    rate: S.rate,
    subPath: S.subPath,
    savedAt: new Date().toISOString()
  };
}

主进程将偏好和会话分别保存到 MpcbePrefs.json、MpcbeSession.json。启动流程先读取偏好,再尝试恢复非空会话;不能恢复时载入内置样例。恢复队列时传入 autoplay:false,不主动立即播放。

不过,“保存字段”与“恢复字段”要分开核对:restoreSession 没有使用会话中的 volume、rate 覆盖播放设置,它们主要来自之前加载的偏好;字幕保存的是文件路径,不是字幕正文;截图列表和 A-B 标记也不在这个会话对象中。会话 JSON 不能替代媒体文件备份。

3.6 Catppuccin Mocha 深色主题

主题使用 CSS 变量统一背景、文字、选中态和提示语义。三列主体通过 Grid 排布,中间列允许收缩,避免长文件名直接撑开布局:

#mainArea {
  display: grid;
  grid-template-columns: var(--side-w) minmax(0, 1fr) var(--dock-w);
  min-height: 0;
  overflow: hidden;
}

基础背景为 #1e1e2e,侧栏层次使用 #181825,正文为 #cdd6f4,强调色为 #89b4fa。字幕字号与底部距离使用独立变量,允许渲染层按偏好覆盖。

窗口宽度不超过 1120px 时隐藏右侧信息坞,并将双列信息卡片收敛为单列:

@media (max-width: 1120px) {
  :root { --dock-w: 0px; }
  #dock { display: none; }
  .cols2 { grid-template-columns: 1fr; }
}

影院模式是切换 body.cine 后隐藏导航和信息坞、扩大播放区域,不是调用系统全屏接口。一般确认框在 appFrame 内绝对定位;关于弹层则使用 fixed,且放在 appFrame 外。不能仅根据 CSS 文件头注释就说“全项目都没有固定定位”。

四、鸿蒙稳定性适配

本章围绕当前工程采取的措施及待验证风险展开,不将其他项目的白屏、崩溃或 IPC 挂起经历写成本项目已经复现的事实。

4.1 禁用默认菜单栏

问题现象: 带默认菜单的桌面壳可能同时出现 File/Edit/View 菜单与应用自定义工具栏,入口与布局容易重复。这是该配置针对的场景,不是本文重新复现的设备故障。

根因分析: 页面已经提供媒体打开、目录选择、播放控制和保存入口,默认应用菜单不是这些业务控件的来源。

解决方案: 当前 main.js 在初始化阶段清除应用菜单,保留页面工具栏与系统窗口边框:

Menu.setApplicationMenu(null);

移除菜单不会自动补齐快捷键。当前快捷键由 renderer.js 的 document keydown 监听实现,只在应用页面获得事件时生效,不是系统全局热键。

4.2 自定义下拉、确认框与关于弹层

问题现象: 倍速、循环模式、字幕背景和确认操作需要统一交互;关于信息也需要在现有窗口中展示。自定义控件还需关注键盘与焦点行为。

根因分析: 下拉、确认框和关于弹层是不同实现:initSel 动态创建按钮和选项;askDlg 返回 Promise;关于弹层只切换 hidden 类。它们不会因为都属于 DOM 控件就自动具备完整模态语义。

解决方案: 当前关于弹层的开关逻辑如下:

function openAboutDialog() {
  var l = document.getElementById('aboutDialogLayer');
  if (l) l.classList.remove('hidden');
}
function closeAboutDialog() {
  var l = document.getElementById('aboutDialogLayer');
  if (l) l.classList.add('hidden');
}

三张素材中的关于截图可以确认弹层的外观与声明内容,但不能证明所有焦点和按键行为。当前自定义下拉主要通过鼠标选择;一般确认框没有完整焦点圈定逻辑;页面播放快捷键也没有统一的“模态框打开时暂停处理”判断。

后续若完善无障碍与键盘操作,应补充焦点进入/恢复、模态期间快捷键隔离、下拉键盘选择和语义属性。本文没有修改这些业务代码,也没有声称原生 alert 在本项目中已导致崩溃。

4.3 窗口配置与媒体运行边界

配置当前值或行为实际含义
初始宽高工作区宽 92%、高 86%按可用屏幕区域设置初始大小
最小尺寸1024 × 640保留桌面播放器的最低布局空间
frametrue使用窗口边框
transparentfalse非透明窗口
resizabletrue允许调整窗口尺寸
backgroundColor#14141f与播放区域背景衔接
nodeIntegrationtrue页面可以使用 Node 集成能力
contextIsolationfalse未启用上下文隔离
禁用硬件加速未调用不应臆断实际使用何种解码路径
createWindow 异常处理try/catch,输出警告处理该同步调用范围的异常,不保证原生层不崩溃

对媒体应用而言,是否禁用加速需要结合视频样本、驱动、解码路径与设备日志判断。仅因其他壳项目禁用了加速,就在文章中把这里补写成同样配置,既不符合源码,也无法替代性能与稳定性验证。

4.4 IPC 错误反馈与异步状态归属

问题现象: 文件读取失败、IPC 调用拒绝或快速切换媒体时,界面需要区分失败与过期结果;只有统一错误对象还不足以保证状态正确。

根因分析: 主进程包装器能处理业务函数抛错,但 IPC 传输仍可能拒绝。另一方面,probeMedia 的异步回调会更新全局头部信息,当前没有媒体请求序号来确认结果是否仍属于正在播放的条目。

解决方案: 当前渲染层确实保留了 invoke 的 catch:

function ipcCall(channel, payload) {
  return ipc.invoke(channel, payload || {}).then(function (r) {
    return r || { success: false, error: '主进程没有返回结果' };
  }).catch(function (e) {
    return { success: false, error: '调用失败:' + String((e && e.message) || e) };
  });
}

这避免把旧说明中的“永远不需要处理 reject”当作事实。当前也没有超时取消机制,本文未执行反复 IPC 或设备压力测试。

后续改进应将“错误反馈”和“结果归属”分别处理:为媒体探测与字幕扫描增加请求标识,只应用仍属于当前文件的结果;避免静默偏好写入失败后让内存状态与磁盘状态长期不一致;对同步扫描和大量字幕解析评估任务拆分。以上是基于当前调用结构的建议,不是已经落地的修复。

五、构建与部署

以下三张图片来自项目提供的 MPC-BE 素材目录,保持原始 JPG 内容,并以相对路径引用。它们展示界面状态,不替代本文未执行的设备验收。

在这里插入图片描述

图一:播放视口显示 demo-tone.wav,时长 00:12、进度 00:10,右侧队列为 2 项、总时长 00:20。当前是 WAV 音频场景,黑色视口不能被解释为视频解码故障;右侧字幕仍显示 demo-pulse.ass,也不能写成同名字幕随切曲自动切换已验证。

在这里插入图片描述

图二:播放列表包含 demo-pulse.wav 和 demo-tone.wav,界面分别显示 8 秒、12 秒及 344.6 KB、516.8 KB;来源标注“内置样例(2 个媒体 / 2 个字幕)”。这些是截图中的已有状态,不代表本文逐一点击验证了导出、排序或去重按钮。

在这里插入图片描述

图三:关于弹层说明独立 JavaScript 实现及参考的交互习惯,并显示 Apache-2.0 声明。该文字与当前 package.json 的 GPL-3.0 不一致,需要在发布前由项目维护者核对。

5.1 本地调试与本文验证结果

若已经准备好兼容的桌面 Electron 环境,可在业务 app 目录启动:

npx electron .

这是一条调试说明,本文未执行该启动命令。package.json 没有 scripts,也没有固定 Electron 版本;使用 npx 时还应留意它可能解析或下载外部版本,不能默认与鸿蒙内置运行时一致。

本文实际执行的是 5 个 JavaScript 文件的语法检查,以及直接调用三个引擎的只读或内存案例。未搭建无头 DOM,未覆盖字幕源文件,也未创建临时测试包。

检查项本机实际结果
Node.jsv22.20.0
main、renderer、三个引擎语法5 个文件通过
demo-tone.wav文件 529244 字节;前 64 KiB 解析得 PCM、22050 Hz、单声道、16 bit、12 秒
demo-pulse.wav文件 352844 字节;前 64 KiB 解析得 PCM、22050 Hz、单声道、16 bit、8 秒
WAV 数据长度tone 为 529200 字节,pulse 为 352800 字节;字节率均为 44100
demo-tone.srt4 条,首起点 0.2 秒,末结束 11.8 秒,解析错误 0
demo-pulse.ass3 条,首起点 0.1 秒,末结束 7.8 秒,解析错误 0;换行与正文逗号保留
样例字幕整体提前 0.5 秒tone 首条变为 [0,2.3),pulse 首条变为 [0,2.1)
偏移后 SRT 序列化再解析两个样例分别保持 4 条、3 条
最小 VTT 案例解析得到 [1,2) 秒的一条字幕
最小 MicroDVD 案例帧率 25,帧区间 25~75 转为 [1,3) 秒,竖线转换为换行
M3U 路径与时长两项合计 20 秒;上级相对路径可离开列表目录
最小 PLS / JSON 案例均得到 /x/a.wav、时长 12 秒的一项
路径去重/A.wav 与 /a.wav 合并为一项,体现全平台转小写策略
两项队列推进顺序末项回到 0,单曲保持 1;固定随机源案例从 0 转到 1
嵌套重叠字幕边界第 5 秒返回 -1,暴露仍有效长字幕被漏查的边界
负偏移越界整体提前 1.5 秒时丢弃已结束条目,跨零条目裁为 [0,1.5)

WAV 的头部解析结果与截图中的 8 秒、12 秒相符,但本文没有播放音频确认声音,没有验证视频解码、音画同步、截图落盘或多次会话恢复。语法通过也不等于运行逻辑全部正确,嵌套字幕案例正说明了这种区别。

5.2 业务资源与鸿蒙模块的衔接

electron 模块通过本地依赖引入 web_engine,以下节选来自 electron/oh-package.json5:

"dependencies": {
  "web_engine": 'file:../web_engine',
}

项目的实际业务来源是 web_engine/src/main/resources/resfile/resources/app。文章整理不需要清空该目录,也不需要从旧构建输出或未知开发副本回灌文件。

部署前应确认三件事:

  1. 当前编辑与打包所用的是同一份 app 资源,包含三个引擎、renderer、样式和四个样例文件。
  2. 入口模块、web_engine 本地依赖及工程原生库配置保持一致,不能把业务 package.json 当作 HAP 全部依赖描述。
  3. 产物来自本次实际构建,而不是仅凭已有 build 或 .hvigor 缓存推断代码已经生效。

5.3 HAP 构建与部署检查点

推荐使用 DevEco Studio 打开 ohos_hap,完成依赖同步后,以当前配置中的 default 产品、electron 模块和 default 目标进行构建。若采用命令行,应使用实际安装的 Hvigor 入口及其支持的参数,不将旧说明中的 product=ohos_hap@electron 当作当前产品名称。

发布前还需要逐项核对:

检查点当前观察与后续要求
应用标识AppScope/app.json5 仍为 com.huawei.ohos_electron
应用显示名AppScope 的 app_name 仍为 Electron;入口 Ability 另引用 EntryAbility_label
本地化资源发布名称应沿 AppScope、Ability 与各语言资源检查,不能只看窗口标题
签名bundleName、证书、Profile、设备范围与目标环境需要匹配,本文未验证
权限web_engine 仍声明网络、文件、定位、相机、麦克风等多类权限
模板入口入口模块仍有快捷方式 metadata 等配置,应核对是否对应实际业务
许可证package.json 与关于弹层的项目许可证不一致
设备验收使用目标设备核对文件对话框、解码、定位、字幕、截图、会话和窗口缩放

不能因为业务主要处理本地文件,就认定所有非文件权限都可直接删除;还应结合原生壳调用、系统能力与发布要求逐项确认。本文没有改动包名、权限、签名、原生库或 README,也没有生成、安装或发布 HAP。

六、常见问题与解决方案

以下问题区分当前代码行为、已执行的引擎案例与后续改进建议,不包装成已经完成的真机排障记录。

Q1:扩展名已经列入支持清单,为什么仍可能无法播放?

问题现象: 文件可以被添加到队列,甚至显示容器名称,但播放仍可能失败。

根因分析: 文件过滤、扩展名标签、文件头嗅探和内核解码是四个不同阶段。当前 26 项白名单只负责选择与分类,video 元素实际支持的编码组合还取决于宿主构建与设备环境。

解决: 结合 video.error 和 decodeHint 区分读取、解码、不支持等情况,以已知编码参数的文件逐项验证。界面推荐的 mp4/webm/mp3/wav/flac 同样不能替代当前设备的支持报告。

教训: “可以选中”“能够识别”“成功解码”“连续稳定播放”不是同一项验收结论。

Q2:切换到 demo-tone.wav,为什么字幕仍是 demo-pulse.ass?

问题现象: 提供的播放视口与关于截图中,媒体名称已是 tone,字幕栏仍显示 pulse。

根因分析: loadIndex 重置 A-B 与字幕命中索引,但保留 S.cues、S.cuesShift 和 S.subPath。内置样例只在加载首个媒体时选择匹配字幕;普通切曲并没有自动调用 autoSub。

解决: 当前可通过“自动匹配同名字幕”或手动选择字幕更新。需要注意,autoSub 实际采用不区分大小写的文件名前缀匹配并取首项,不是严格同名或带语言优先级的选择。后续自动切曲方案应明确字幕卸载、匹配和异步结果归属规则。

教训: 截图中出现了字幕文件名,不代表字幕与当前媒体已经建立可靠的一一对应关系。

Q3:覆盖原字幕后,为什么原格式和偏移可能发生变化?

问题现象: 原文件可能仍叫 .ass 或 .vtt,内容却变成 SRT;重新载入时还可能再次平移时间轴。

根因分析: overwriteSub 将 S.cuesShift 经 toSRT 序列化后写到原路径,统一使用 UTF-8 BOM,没有保留 ASS 样式和原始编码。成功后未将偏移清零,也未将当前字幕基线替换为写回后的内容。

解决: 处理重要字幕时先另存 .srt 副本并检查时间轴。后续若完善覆盖功能,应增加原始文件备份、格式与扩展名一致性策略,以及写回后基线和偏移的状态更新;本文未执行这些改动。

教训: 确认框只能明确用户意图,不能替代备份、格式保持和状态一致性设计。

Q4:为什么字幕解析有结果,却不能保证所有字幕都显示正确?

问题现象: 简单样例解析正常,复杂重叠字幕仍可能漏显,负偏移还可能减少条目。

根因分析: cueAt 的有限回退可能被已经结束的相邻短字幕挡住,漏掉更早开始、仍未结束的长字幕;界面只显示单条文本。shiftCues 则按定义丢弃结束时间不大于零的条目。文本解码也只是 BOM 识别与启发式判断,不是真正的 GBK 转码。

解决: 对嵌套区间引入区间索引或可靠的活动字幕集合;对负偏移显示裁切统计;遇到编码警告先在支持相应编码的工具中另存 UTF-8。当前引擎最小案例的漏查结果应保留在验证记录中。

教训: 解析成功只说明产生了结构,不能自动证明时间轴、样式与编码语义完整。

Q5:导入列表或撤销目录后,为什么不能说文件访问已经完全隔离?

问题现象: 列表相对路径可以指向上级目录;撤销某条根记录也不一定完全撤销其覆盖区域。

根因分析: resolvePath 允许上级跳转;父根可能继续覆盖子目录;guard 主要约束特定 IPC,媒体仍通过 file URL 加载。nodeIntegration:true 与 contextIsolation:false 也意味着目录表不是强安全隔离机制。

解决: 当前使用中只加载可信本地资源,并明确检查目标目录。若要建立更严格边界,需要统一媒体访问与 IPC 的路径策略、规范化真实路径,并限制渲染层能力;本文没有把这些建议描述成已实现能力。

教训: 应用范围记录、系统权限与运行时隔离必须分开描述。

Q6:媒体信息和截图看起来正确,能否代替完整播放验收?

问题现象: WAV 头部能推算时长,截图也能显示播放器画面,但这些结果没有覆盖连续音视频输出。

根因分析: WAV 分析只读取前 64 KiB;平均码率是文件级估算;capturePage 截取页面区域而非原始帧。快速切换媒体时,未校验归属的旧探测回调还可能影响当前面板。

解决: 将头部分析、实际播放、截图与异步切换分别测试,记录设备、运行时、编码参数和操作步骤。截图缓存应考虑数量上限,保存命名应考虑同秒冲突,探测结果应绑定当前媒体请求。

教训: 界面数字和静态图像是观察材料,不是音画同步、解码稳定性或文件完整性的替代证据。

Q7:业务窗口已经叫 MPC-BE,为什么还不能直接认定发布就绪?

问题现象: 窗口标题与文章配图已有业务名称,但应用标识、系统显示名和许可证仍未统一。

根因分析: WINDOW_TITLE 与 HTML title 只负责窗口和页面;AppScope 仍保留模板 bundleName、app_name。package.json 的 GPL-3.0 与关于弹层的 Apache-2.0 是同一项目的不同声明,不能用 Electron 的 MIT 来消解冲突。

解决: 发布前统一核对应用标识、本地化标签、许可证依据、隐私与权限、快捷方式和签名,再进行实际构建与设备验收。会话恢复也应单独验证:当前 rememberVol 选项并未约束所有音量与倍速保存/恢复路径,不能仅凭设置项存在认定偏好语义完整。

教训: 页面完成、业务可运行、配置一致与正式发布是不同阶段,文章应分别交代证据。

七、总结

MPC-BE 这份工程展示了媒体类 Electron 壳应用的清晰分工:媒体内核负责读取与解码,JavaScript 负责播放队列、字幕时间轴、文件头信息和交互调度,鸿蒙工程提供宿主与打包结构。

特性实现方案
五面板播放器三列 Grid、单个 video 元素、统一状态与事件调度
播放列表M3U/PLS/JSON 归一化,路径处理、索引推进、去重与排序
字幕时间轴四类文本格式解析、秒级 cue 模型、偏移与 SRT 导出
A-B 与倍速起终点标记、动画帧回跳、六档倍速 UI
媒体信息64 KiB 头部读取、WAV chunk 遍历、容器特征嗅探
画面截图页面区域 capturePage、PNG 保存与内存记录
偏好与会话主进程 JSON 持久化、队列与字幕路径恢复
鸿蒙衔接electron entry 本地依赖 web_engine,业务资源随壳工程打包

适配与文章整理中最值得保留的三个经验:

  1. 把解码能力与业务算法分开。 扩展名、头部信息和队列操作可以静态核对或单独验证,真实播放仍需要目标运行时和设备证据。
  2. 让时间轴转换具备明确的保存语义。 偏移、裁切、格式转换、覆盖原文件与再次载入之间存在状态依赖,不能只关注导出文本是否生成。
  3. 让每项结论与证据范围对应。 本机语法、引擎案例、已有截图、工程配置和设备验收分别回答不同问题;其中发现的嵌套字幕、异步归属、范围限制和许可证差异也应如实记录。

本文完成的是基于当前源码与素材的适配技术梳理及有限引擎验证,未修改业务实现,未执行 HAP 构建、设备安装、性能测试或上架发布。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐