MPC-BE 播放器在鸿蒙PC上的状态调度实践:多格式播放列表解析、字幕时间轴偏移与会话恢复
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 |
| compatibleSdkVersion | 5.0.5(17) |
| runtimeOS | HarmonyOS |
| 构建产品 | default |
| 入口模块与目标 | electron / default |
| deviceTypes | 2in1、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 | 字幕解析、时间转换、偏移、当前字幕查找和序列化 |
| MediaEngine | WAV 头部、容器特征、格式化与数值钳制 |
业务 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:capture | PNG 编码后检查 32 MiB |
| fs:writeBinary | base64 解码后检查 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 | 保留桌面播放器的最低布局空间 |
| frame | true | 使用窗口边框 |
| transparent | false | 非透明窗口 |
| resizable | true | 允许调整窗口尺寸 |
| backgroundColor | #14141f | 与播放区域背景衔接 |
| nodeIntegration | true | 页面可以使用 Node 集成能力 |
| contextIsolation | false | 未启用上下文隔离 |
| 禁用硬件加速 | 未调用 | 不应臆断实际使用何种解码路径 |
| 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.js | v22.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.srt | 4 条,首起点 0.2 秒,末结束 11.8 秒,解析错误 0 |
| demo-pulse.ass | 3 条,首起点 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。文章整理不需要清空该目录,也不需要从旧构建输出或未知开发副本回灌文件。
部署前应确认三件事:
- 当前编辑与打包所用的是同一份 app 资源,包含三个引擎、renderer、样式和四个样例文件。
- 入口模块、web_engine 本地依赖及工程原生库配置保持一致,不能把业务 package.json 当作 HAP 全部依赖描述。
- 产物来自本次实际构建,而不是仅凭已有 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,业务资源随壳工程打包 |
适配与文章整理中最值得保留的三个经验:
- 把解码能力与业务算法分开。 扩展名、头部信息和队列操作可以静态核对或单独验证,真实播放仍需要目标运行时和设备证据。
- 让时间轴转换具备明确的保存语义。 偏移、裁切、格式转换、覆盖原文件与再次载入之间存在状态依赖,不能只关注导出文本是否生成。
- 让每项结论与证据范围对应。 本机语法、引擎案例、已有截图、工程配置和设备验收分别回答不同问题;其中发现的嵌套字幕、异步归属、范围限制和许可证差异也应如实记录。
本文完成的是基于当前源码与素材的适配技术梳理及有限引擎验证,未修改业务实现,未执行 HAP 构建、设备安装、性能测试或上架发布。
更多推荐



所有评论(0)