# 教程录屏工具-跟随鼠标放大聚焦

**Repository Path**: chunfff/recorder

## Basic Information

- **Project Name**: 教程录屏工具-跟随鼠标放大聚焦
- **Description**: 教程录屏工具，自动跟随鼠标移动并放大聚焦焦点区域，助力高效制作清晰演示视频。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 闪念录屏 · Flash Recorder

> 一款基于 Electron 的「点击即聚焦」丝滑局部放大录屏工具。
> 点击屏幕任意位置（或按下快捷键），画面会以鼠标为中心平滑放大到 2x / 3x / 5x，
> 停留片刻后自动还原 —— 适合做教程演示、代码讲解、操作高亮类视频。

---

## ✨ 功能特性

- **点击即聚焦**：屏幕任意位置点击鼠标左键即触发局部放大，动画丝滑（zoom-in → hold → zoom-out）
- **快捷键驱动**：`Ctrl+Shift+R` 开始/停止录制、`Ctrl+Shift+Z` 开关聚焦、`Ctrl+Shift+F` 手动聚焦，全部可自定义
- **双击触发**：支持 ScrollLock / F13-F24 等单键连按两次触发聚焦
- **多录制源**：整屏 / 应用窗口 / 自定义框选区域，自动过滤不可捕获的系统窗口
- **尺寸预设**：4K / 2K / 1080p / 720p / 竖屏 / 正方形 / 自定义等比输出
- **6 种光标造型**：箭头 / 圆点 / 圆环 / 光晕 / 十字准星 / 不绘制，颜色尺寸可调
- **5 种点击特效**：扩散圆环 / 粒子爆发 / 聚光灯 / 冲击波 / 脉冲圈
- **导出格式**：MP4（自动 WebM→MP4 转换）/ H.264 WebM / VP9 / VP8，快照 PNG / JPEG
- **音画同录**：麦克风 + 系统声音，可仅导出音频
- **安全保存**：自动写入可写安全目录，避开系统关键位置与「受控文件夹访问」保护目录

---

## 📸 界面截图

### 主界面

主界面左侧为实时预览（含光标与点击特效），右侧为控制面板（录制源 / 聚焦设置 / 光标样式 / 点击特效 / 音频 / 画质 / 导出 / 快捷键）：

![主界面](docs/主界面.png)

### 自定义区域选择

全屏半透明遮罩 + 拖拽框选，实时显示物理像素尺寸，按 `Esc` 取消：

![区域选择](docs/区域选择.png)

---

## 🏗️ 架构设计

三层结构，遵循 Electron 安全最佳实践（`contextIsolation: true`、`nodeIntegration: false`、CSP 白名单）。

```
zoom-recorder/
├── main.js          # 主进程：窗口、桌面捕获源、IPC、ffmpeg 转换、保存目录管理
├── preload.js       # contextBridge 安全桥接，仅暴露白名单 API
├── index.html       # UI 结构（预览区 + 控制面板）
├── renderer.js      # 渲染逻辑：源选择、预览、MediaRecorder 录制、UI 绑定
├── zoom-engine.js   # 缩放引擎：canvas 双缓冲绘制、聚焦状态机、光标/特效
├── styles.css       # 深色主题样式
└── package.json     # 依赖与 electron-builder 打包配置
```

### 三层职责

| 层 | 职责 |
|---|---|
| **主进程** | 桌面源枚举与过滤、全局鼠标钩子（uiohook-napi）、全局快捷键、区域选择窗口、WebM→MP4 转换、可写保存目录探测 |
| **preload** | 通过 `contextBridge` 暴露 `window.api`，渲染层无法直接访问 Node / 文件系统 |
| **渲染层** | `getUserMedia` 桌面流 → 隐藏 `<video>` 作数据源 → canvas 逐帧绘制（叠加光标与特效）→ `MediaRecorder` 录制 |

---

## 🧠 核心技术点

### 1. 局部放大引擎（zoom-engine.js）

- **按需绘制**：无自定义区域时直接从视频帧 `drawImage` 到输出画布（裁剪放大一步完成），省去中间源画布拷贝；仅框选区域时才使用中间缓冲，显著降低每帧开销。
- **三段式状态机**：`zoomingIn → holding → zoomingOut → idle`，缩放与焦点由「相位进度 + 三次缓动（easeOutCubic / easeInOutCubic）」驱动，停留期画面完全稳定不漂移，运镜更自然。
- **帧率节流**：预览渲染按 60fps 上限节流，避免高刷屏（120/144Hz）满帧重复渲染；颜色解析结果缓存复用，减少每帧字符串与解析开销。
- **色彩一致性**：两个 canvas 的 `2d` 上下文均显式指定 `{ alpha: false, colorSpace: 'srgb' }`，与捕获流色彩空间对齐，防止预乘 alpha 导致画面变淡。

### 2. 触发方式：全局点击 + 快捷键

- 通过原生模块 **uiohook-napi** 注册全局鼠标钩子，屏幕上任意位置点击都会推送坐标给渲染层触发聚焦；
- 全局快捷键用 Electron `globalShortcut`，支持动态改键与双击单键（连按两次 `ScrollLock`）。

### 3. 屏幕源过滤

用 `desktopCapturer.getSources` 枚举整屏与窗口源，过滤掉 `DWM`、输入法、`Windows Shell Experience Host` 等不可捕获或无关的窗口，避免用户选到无效源。

### 4. 颜色管理踩坑：整屏源「泛白」

选择整屏源时画面明显泛白、窗口源正常。经 **WebCodecs** 采样捕获帧原始 YUV 元数据确认：整屏源由 WGC 输出 BT.601 限幅 I420 帧，Chromium 的 HDR/色彩管理链路会进行错误的 YUV→sRGB 转换。最终通过主进程命令行开关组合修复：

```js
app.commandLine.appendSwitch('force-color-profile', 'srgb');
app.commandLine.appendSwitch('disable-features',
  'HDRCaptureMode,UseHDRTransferFunction,HDRVideoPlayback,VideoCaptureColorManagement,' +
  'ColorProviderReduction,SkiaColorTransferFunctionReduction');
app.commandLine.appendSwitch('force-fieldtrials', 'WebRTC-HDRVideo/Disabled/');
```

> 关键坑：**不要关闭 GPU 硬件加速**。软件解码路径的 YUV→RGB 系数不同，反而会引入新的偏色。

### 5. MP4 导出：WebM 录制 + ffmpeg 转换

Electron 31 的 `MediaRecorder.isTypeSupported('video/mp4')` 返回 `false`（Chromium 未内置 MP4 封装）。方案：

1. 按用户选择的编码器录制 WebM（VP9 / VP8 / H.264）；
2. 用户期望 MP4 时，先落盘临时 `.webm`，再用系统 `ffmpeg` 转码：

```bash
ffmpeg -y -i input.webm -c:v libx264 -preset medium -crf 23 \
       -c:a aac -b:a 128k -movflags +faststart output.mp4
```

3. 转换失败自动回退保留 WebM，不丢数据。

### 6. 保存目录策略：Windows「受控文件夹访问」实战

用户曾遇到「没有权限在此位置保存」。排查结论：

- `dialog.showSaveDialog` 会**记忆上次目录**并忽略 `defaultPath`，双击启动时可能定位到 `system32` 等无权限目录；
- Windows **受控文件夹访问（Controlled Folder Access）** 保护「视频 / 文档 / 图片 / 下载」等已知文件夹，非白名单应用写入直接返回 `EPERM`，且 `fs.accessSync` 探测不到该拦截。

最终方案：**不弹保存对话框**，改用「实际写入探针」探测可写安全目录，按序回退：

```
E:/F:/D: 盘的 FlashRecorder → 用户主目录 FlashRecorder → 主目录 → cwd/recordings → temp
```

写入失败的目录记入 `failedDirs` 集合自动避开；用户也可在设置里手动「更改保存位置」。

### 7. 安全实践

- 渲染层启用 `contextIsolation`，禁用 `nodeIntegration`，仅通过 preload 白名单 API 通信；
- 页面声明 CSP：`default-src 'self'`，禁远程脚本与样式；
- 文件写入 / MP4 转换 / 显示所在目录等 IPC 均校验**绝对路径且拒绝 `..` 穿越**；
- ffmpeg 以参数数组方式 `spawn`，无 shell 注入面。

---

## 🚀 运行与打包

```bash
# 安装依赖（自动重建 uiohook-napi 原生模块）
npm install

# 开发运行
npm start

# 打包 Windows 便携版 exe（输出到 dist/）
npm run dist
```

`npm run dist` 生成 **`dist/闪念录屏-2.0.0.exe`**：单文件便携版，双击即用，无需安装。

> 提示：MP4 转换依赖系统 PATH 中的 `ffmpeg`；未安装时录制自动回退为 WebM。

---

## 📜 开源协议

MIT License