Bilibili-Evolved 逐帧调整seek-by-frames功能源码解析帧步长计算、控制栏按钮与快捷键实现【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved本指南以 Bilibili-Evolved 仓库中「逐帧调整」seek-by-frames组件为研究对象完整讲解该功能如何在哔哩哔哩播放器的时间显示右侧插入「上一帧 / 下一帧」按钮如何根据当前画质估算视频帧率并换算为精确的时间步长以及如何与「快捷键扩展」联动实现Shift←/→的逐帧快捷键。读完本文你将掌握该组件的核心调用链按钮注入 → 帧率估算 →changeTime跳转、插件式快捷键注册机制以及它为什么「很难做到绝对精准」的根本原因。功能概览在时间显示右侧添加逐帧微调按钮组件官方说明见 组件文档非常简短核心能力只有一句话在播放器的时间右边增加两个按钮用于较精细地调整视频时间。装有「快捷键扩展」时支持键盘快捷键Shift←/→。即在视频控制栏的「当前时间 / 总时长」显示区域右侧追加两个带图标的按钮「上一帧」与「下一帧」每次点击按一帧的时间长度向前或向后跳转用于逐帧查看画面细节——例如分析动作镜头、截图、检查一闪而过的画面等。从组件元数据index.ts可以看到它的注册信息export const component defineComponentMetadata({ name: seekByFrames, displayName: 启用逐帧调整, tags: [componentsTags.video], entry, reload: () document.body.classList.remove(SeekByFramesDisabledClass), unload: () document.body.classList.add(SeekByFramesDisabledClass), urlInclude: playerUrls, plugin: { ... }, })name: seekByFrames组件唯一标识displayName: 启用逐帧调整在设置面板中呈现的名称tags: [componentsTags.video]归类到「视频」标签下urlInclude: playerUrls只在播放页playerUrls匹配的 URL生效reload/unload通过向document.body添加/移除seek-by-frame-disable类常量SeekByFramesDisabledClass见 index.ts实现热重载时的样式级禁用卸载组件时按钮相关的样式随之失效。帧步长frameTime是如何算出来的逐帧调整的前提是知道「一帧有多长」。由于 B 站视频的帧率并不统一组件选择了按当前画质档位推断帧率的策略。入口函数在 index.tsawait playerReady() const { playerAgent } await import(/components/video/player-agent) let frameTime 0 attributesSubtree(${playerAgent.query.control.buttons.quality.selector} ul, () { const selectedQuality dq( ${playerAgent.query.control.buttons.quality.selector} .bui-select-item-active, ${playerAgent.query.control.buttons.quality.selector} .active, ) const quality selectedQuality ? parseInt(selectedQuality.getAttribute(data-value)) : 0 const fps (() { switch (quality) { // 60fps case 116: case 74: return 60000 / 1001 // 30fps default: return 30000 / 1001 } })() frameTime 1 / fps })关键逻辑分三步监听画质切换attributesSubtree观察画质选择列表 DOM...quality.selector ul的属性变化一旦用户切换画质就重新计算读取当前画质从激活项.bui-select-item-active或.active的data-value属性解析出画质编号quality画质 → 帧率 → 帧时长画质编号116、74被认定为 60fps 档帧率取60000 / 1001 ≈ 59.94NTSC 电视制式标准帧率帧时长frameTime ≈ 16.68ms其余画质含data-value缺失或为 0 的情况统一按 30fps 档处理帧率30000 / 1001 ≈ 29.97帧时长frameTime ≈ 33.37msframeTime 1 / fps将帧率换算为单帧时间长度秒。画质按钮的 CSS 选择器来自播放器适配层新版 b 站播放器bpx为.bpx-player-ctrl-quality见 bpx.ts旧版播放器为.bilibili-player-btn-quality见 video-player-v2.tsplayerAgent.query.control.buttons.quality会根据当前播放器内核自动解析出正确选择器。注意这里60000 / 1001、30000 / 1001是逐帧跳转时传入changeTime的帧时长而组件文档特别提示「视频的实际播放帧率」同时取决于视频源帧率与显示器刷新率很难精确计算因此该策略是工程上的近似估计详见下文「精准度限制」一节。控制栏按钮的注入addControlBarButton 与 changeTime按钮注入帧时长确定后组件通过addControlBarButton注册两个按钮index.tsconst setFrame (num: number) { playerAgent.changeTime(num * frameTime) } addControlBarButton({ name: seekPrevFrame, displayName: 上一帧, icon: seek-left, order: 1, action: () { setFrame(-1) }, }) addControlBarButton({ name: seekNextFrame, displayName: 下一帧, icon: seek-right, order: 2, action: () { setFrame(1) }, })name作为按钮的唯一标识同时被快捷键插件用作 DOM 查询锚点data-nameseekPrevFrame/data-nameseekNextFrameorder控制按钮在扩展栏中的排列顺序上一帧1在左、下一帧2在右图标seek-left/seek-right由组件自带的 seek-left.svg 与 seek-right.svg 提供通过addData(ui.icons, ...)注册进图标表index.ts点击action时setFrame(±1)计算num * frameTime作为时间增量。addControlBarButton的实现在 video-control-bar.ts它保证控制栏扩展容器.be-video-control-bar-extend只初始化一次lodash.once等待videoChange事件后把 VideoControlBar.vue 挂载到播放器时间显示playerAgent.query.control.buttons.time()的afterend随后将新按钮 push 进扩展栏的items数组完成渲染。这意味着任何组件都可以通过同一套接口向控制栏追加自定义按钮逐帧调整只是其中一个用例。跳转实现按钮动作最终落到 player-agent 的changeTimebase.tschangeTime(change: number) { if (!this.nativeApi) { return null } const video this.query.video.element.sync() as HTMLVideoElement if (!video) { return null } this.nativeApi.seek(video.currentTime change, video.paused) return this.nativeApi.getCurrentTime() }以当前播放进度video.currentTime为基准叠加增量change即±frameTimeseek(targetTime, video.paused)跳转时带上暂停状态若视频处于暂停跳转后仍保持暂停从而能稳定地停在目标帧上供人观察若原生播放器 API 不可用nativeApi为空或找不到视频元素则静默返回null不会抛错影响播放器。快捷键联动Shift← / Shift→ 的实现原理逐帧按钮不仅可鼠标点击还支持键盘操作。组件元数据中的plugin字段index.ts向「快捷键扩展」keymap 组件注册了两类数据plugin: { displayName: 逐帧调整 - 快捷键支持, setup: () { addData(keymap.actions, (actions: Recordstring, KeyBindingAction) { actions.previousFrame { displayName: 上一帧, run: context { const { clickElement } context return clickElement(.be-video-control-bar-extend [data-nameseekPrevFrame], context) }, } actions.nextFrame { displayName: 下一帧, run: context { const { clickElement } context return clickElement(.be-video-control-bar-extend [data-nameseekNextFrame], context) }, } }) addData(keymap.presets, (presetBase: Recordstring, string) { presetBase.previousFrame shift arrowLeft presetBase.nextFrame shift arrowRight }) }, },机制拆解动作注册通过addData(keymap.actions, ...)注册两个命名动作previousFrame上一帧与nextFrame下一帧动作实现是「模拟点击」动作体不直接调用跳转逻辑而是使用 keymap 提供的clickElement辅助函数actions.ts它内部通过simulateClick模拟一次携带键盘修饰键ctrl/shift/alt/meta的鼠标点击目标选择器为.be-video-control-bar-extend [data-nameseekPrevFrame]/[data-nameseekNextFrame]——也就是复用控制栏上已注入的按钮。这样快捷键与鼠标点击共用同一套setFrame逻辑避免了行为不一致默认按键预设通过addData(keymap.presets, ...)写入previousFrame shift arrowLeft、nextFrame shift arrowRight即默认Shift←/Shift→。用户可在 keymap 组件的设置里按需改绑条件生效由于这些数据通过addData的插件通道注册见 plugins/data.ts 与 bindings.ts只有同时启用了「快捷键扩展」组件Shift←/→才会生效未启用时功能退化为纯按钮操作这也正对应文档中「装有快捷键扩展时」的前提表述。精准度限制为什么有些帧「停不住」组件文档给出了明确的已知限制注视频的实际播放帧率跟视频本身的帧率和显示器的刷新率有关很难计算一个精准的数值部分视频仍然会有暂停不到那种一闪而过的图的情况。结合源码可以解释这一限制的成因帧率是估算而非读取index.ts只根据画质编号116/74 → 60fps其余 → 30fps做二选一的近似推断并没有从视频元数据中读取真实帧率。UP 主上传的 24fps、25fps、48fps、120fps 等视频都会被归入上述两类显示器刷新率不可控视频实际呈现的帧节奏还受显示器刷新率如 60Hz、144Hz与播放器渲染策略影响脚本无法获得该信息seek 精度受限于解码器跳转由浏览器/播放器原生解码器执行最终落点取决于关键帧与解码器实现changeTime传入的只是期望增量。因此「逐帧」是相对精细的近似调整对常规 24/30fps 内容效果明显对高帧率或强同步需求的内容如逐帧分析快速动作仍可能出现跨帧或停不准的情况这属于浏览器播放器生态下的客观限制而非组件缺陷。小结「逐帧调整」是 Bilibili-Evolved 中一个麻雀虽小、五脏俱全的典型组件串联起项目的多条基础设施关注点具体实现参考文件帧时长估算按画质编号116/74 → 60fps其余 → 30fps换算frameTime 1 / fpsseek-by-frames/index.ts按钮注入addControlBarButton将按钮 push 进.be-video-control-bar-extend扩展栏video-control-bar.ts时间跳转changeTime(±frameTime)→nativeApi.seek(currentTime change, paused)player-agent/base.ts快捷键注册previousFrame/nextFrame动作与shift arrowLeft/arrowRight预设动作内clickElement模拟点击按钮seek-by-frames/index.ts生效范围urlInclude: playerUrls仅播放页加载卸载时通过seek-by-frame-disable类禁用样式seek-by-frames/index.ts若想在播放器中体验启用「逐帧调整」组件后控制栏时间显示右侧即出现「上一帧 / 下一帧」按钮再启用「快捷键扩展」组件即可用Shift←/→在不离开键盘的情况下逐帧检视视频画面。源码中frameTime的画质判定表与changeTime的暂停态 seek 逻辑是理解这套「近似逐帧」方案设计取舍的关键入口。【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考