Recordly扩展API完全指南：开发光标特效、渲染钩子与设备框架扩展

Recordly扩展API完全指南开发光标特效、渲染钩子与设备框架扩展【免费下载链接】RecordlyCreate polished demo videos without editing skills. Mac/Windows/Linux项目地址: https://gitcode.com/gh_mirrors/re/RecordlyRecordly 是一款开源的屏幕录制与演示视频编辑工具它的扩展 API允许开发者像安装插件一样为编辑器注入新能力注册光标特效cursor effects、插入渲染钩子render hooks、贡献设备框架device frames、壁纸、光标样式和设置面板。本指南带你从零理解 Recordly 扩展系统的架构、权限模型与开发流程让你快速做出自己的第一个扩展。什么是 Recordly 扩展扩展运行在编辑器的渲染进程中通过一套带权限门控的宿主 APIhost API与主程序交互。它能做到✨绘制进渲染管线在视频、光标、摄像头、标注等图层之后叠加自己的视觉效果️响应播放与导出事件跟随播放时间轴、监听点击、跟踪导出进度贡献打包资产设备框架、壁纸、光标样式、音效⚙️注册设置面板在编辑器侧边栏里添加自己的配置项官方 API 文档在仓库根目录的 EXTENSIONS.md完整参考手册建议配合阅读。扩展结构一个最小示例一个可安装的扩展只需要两个文件——清单manifest 入口脚本my-extension/ recordly-extension.json index.js清单文件声明身份与权限{ id: com.example.my-extension, name: My Extension, version: 1.0.0, description: A short description, main: index.js, permissions: [render] }入口脚本只需导出两个生命周期函数export function activate(api) { api.log(Hello from my extension); } export function deactivate() {}如果你习惯 TypeScript可以直接从仓库的types.ts导入RecordlyExtensionAPI类型获得完整的 IDE 自动补全与编译期检查编译打包成.js后即可加载。权限模型按需声明能力Recordly 扩展采用最小权限原则六大权限各司其职权限解锁的能力render注册渲染钩子cursor光标遥测与光标特效audio打包音效播放timeline播放与时间轴事件ui设置面板与设备框架注册assets资产解析、壁纸与光标样式注册export导出生命周期事件实践建议只申请你真正用到的权限清单在扩展加载时和上传市场时都会被校验。开发光标特效registerCursorEffect()光标特效是 Recordly 扩展里最出效果的一类。回调从点击发生后的每一帧开始执行直到你返回false为止——这让点击波纹点击脉冲这类短暂动画变得非常自然api.registerCursorEffect((ctx) { const progress ctx.elapsedMs / 400; if (progress 1) return false; const sceneWidth ctx.videoLayout?.maskRect.width ?? ctx.width; const x ctx.cx * ctx.width; const y ctx.cy * ctx.height; const radius sceneWidth * 0.03 * progress; ctx.ctx.beginPath(); ctx.ctx.arc(x, y, radius, 0, Math.PI * 2); ctx.ctx.stroke(); return true; });两个关键设计值得注意返回false即结束——不用手动清理特效自己谢幕场景相对缩放——特效上下文自带videoLayout、zoom、sceneTransform让你的特效随场景缩放而不是钉死在画布上渲染钩子把效果插入渲染管线registerRenderHook()是更强大的底层能力。Recordly 在渲染管线的特定阶段phase调用你的钩子参数是一个 Canvas 2D 上下文加上丰富的场景信息阶段说明post-video视频之后跟随场景变换缩放/运动post-zoom缩放处理后跟随场景变换post-cursor光标之后跟随场景变换post-webcam摄像头叠加后场景变换已还原post-annotations标注之后场景变换已还原final最后一遍适合 HUD 式全局叠加export function activate(api: RecordlyExtensionAPI) { api.registerRenderHook(final, (ctx) { ctx.ctx.fillStyle rgba(255,255,255,0.1); ctx.ctx.fillRect(0, 0, ctx.width, 30); }); }钩子上下文还提供了实用的像素级查询能力getPixelColor(x, y)— 取任意像素颜色getAverageSceneColor()— 场景平均色适合做随画面变色的动态效果getDominantColors(count)— 主色提取videoLayout.maskRect/videoLayout.borderRadius— 场景真实边界与圆角做出与画面严格对齐的边框效果所有注册函数含钩子、特效、面板都会返回一个 dispose 函数方便精细管理生命周期。设备框架、壁纸与光标样式扩展除了画东西扩展还能贡献整类资产让所有用户共享️registerFrame()— 设备框架手机壳、浏览器边框、窗口框。推荐使用draw(ctx, width, height)函数式绘制输出不依赖分辨率registerWallpaper()— 场景背景壁纸文件打包在扩展目录内️registerCursorStyle()— 光标图片包替换默认光标外观playSound(path, { volume })— 播放打包音效例如点击音效扩展这三类都依赖扩展根目录下的打包文件api.resolveAsset(images/overlay.png)负责解析相对路径。设置面板让你的扩展可配置通过registerSettingsPanel()可以把配置项直接挂进编辑器侧边栏用parentSection: cursor可嵌套进光标分区api.registerSettingsPanel({ id: my-settings, label: My Extension, fields: [ { id: enabled, label: Enable, type: toggle, defaultValue: true }, { id: size, label: Size, type: slider, defaultValue: 1, min: 0.1, max: 3, step: 0.1 }, { id: color, label: Color, type: color, defaultValue: #2563EB }, ], });支持的字段类型toggle、slider、select、color、text。配合getSetting()/setSetting()/onSettingChange()设置值会自动持久化无需自己写存储逻辑。事件系统与只读查询带timeline/cursor/export权限后你可以订阅整个编辑器的脉搏事件说明playback:timeupdate每次播放 tick 触发playback:play/playback:pause播放开始 / 暂停cursor:click/cursor:move光标点击 / 移动timeline:region-added/region-removed时间轴区域增删export:start/export:frame/export:complete导出生命周期同时有一批只读查询随时可用getVideoInfo()、getZoomState()、getCursorAt(timeMs)、getSmoothedCursor()、getKeystrokesInRange()、getActiveFrame()等。甚至可以直接调用api.drawIcon(ctx, Sparkle, x, y, 18, #ffffff)从 Recordly 内置的 Phosphor 图标集里画图标省掉打包自己的图标资源。扩展生命周期与最佳实践整个加载流程分四步理解它有助于排查问题发现DiscoveryRecordly 扫描内置扩展与用户扩展目录应用中通过Extensions - Open Directory可打开激活Activationactivate(api)执行在这里完成所有注册运行Runtime注册的回调用各自的阶段在预览与导出中执行停用Deactivationdeactivate()执行所有注册自动清理小贴士预览与导出走同一条场景逻辑所以你在预览里看到的效果会 1:1 出现在导出文件中用videoLayout做场景相对尺寸而不是画布绝对尺寸效果才能跨分辨率清单里的screenshots字段可以为市场展示图contributes目前只是元数据运行时行为必须在activate()里注册在哪里动手完整 API 参考EXTENSIONS.md扩展面板入口编辑器侧边栏src/components/video-editor/ExtensionManager.tsx侧边栏分区注册src/components/video-editor/layout/EditorSidebar.tsx项目总览与特性说明README.md从一段 10 行的registerCursorEffect开始到完整的渲染管线叠加、设置面板与音效——Recordly 的扩展 API 为社区留出了一整块创作空间。打开编辑器挑一个你喜欢的特效方向动手做第一个扩展吧。【免费下载链接】RecordlyCreate polished demo videos without editing skills. Mac/Windows/Linux项目地址: https://gitcode.com/gh_mirrors/re/Recordly创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考