+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program. If not, see
-
-
-
-# OpenScreen
-
-Beautiful screen recordings with zoom animation.
-
-
-If you don't want to pay $29/month for Screen Studio but want a much simpler version that does what most people seem to need, making beautiful product demos and walkthroughs, here's a free-to-use app for you. OpenScreen does not offer all Screen Studio features, but covers the basics well!
-
-
-OpenScreen is 100% free for personal and commercial use. Use it, modify it, distribute it. (Just be cool 😁 and give a shoutout if you feel like it !)
-
-
-
-**⚠️ DISCLAIMER: This is very much in beta and might be buggy here and there (but hope you have a good experience!).**
-
-
-
-
-
-
-## Core Features
-- Record your whole screen or specific apps
-- Add manual zooms (customizable depth levels)
-- Customize the duration and position of zooms however you please
-- Crop video recordings to hide parts
-- Choose between wallpapers, solid colors, or gradients for your background
-- Motion blur and exponential easing for smoother pan and zoom effects
-
-**Note:**
-- OpenScreen is designed to support both Windows and macOS. We did not use any native APIs specific to one OS, so it should work on both. However, it hasn't been fully tested on Windows yet, if you run into issues, please let me know!
-- After you install the app, you'll need to grant it accessibility and screen recording permissions for it to work properly.
-
-**Contribution:**
-Planning to add a contribution guide soon so people can contribute to this repo. Stay tuned!
-
-## Getting Started
-Download the latest installer for your platform from the [GitHub Releases](https://github.com/siddharthvaddem/openscreen/releases) page.
-
-## Built with
-- Electron
-- React
-- TypeScript
-- Vite
-- PixiJS
-- dnd-timeline
-
----
-
-
-_I'm new to open source, idk what I'm doing lol. If something is wrong please raise an issue 🙏_
-
-## License
-MIT License: You can use, modify, and distribute this software for any purpose, including commercial use, without restriction. See the LICENSE file for details.
+Language: EN | [简中](README.zh-CN.md)
+
+
+
+
+
+
+
+### Create polished demo videos in minutes
+[Recordly](https://www.recordly.dev) is your **open-source screen recorder** and editor for **walkthroughs, demos, product videos**, and more.
+**Accepting PRs.**
+
+
+
+
+## Dynamic webcam bubble overlays
+Add webcam footage as an overlay bubble, position it with presets or custom coordinates, mirror it, control shadow and roundness, and optionally make it react to zoom so it stays visually balanced during motion.
+
+
+
+
+## Timeline editing built for demos
+Use drag-and-drop timeline tools for zooms, trims, speed regions, annotations, extra audio regions, and crop-aware edits. Save and reopen work as `.recordly` project files.
+
+
+
+
+## Extensions & Marketplace
+
+Recordly has a community-driven extension system. Anyone can build and publish extensions that add new capabilities to Recordly — cursor click sounds, device frames, browser mockups, wallpapers, render hooks, settings panels, and more.
+
+Browse and install community extensions from the [Recordly Marketplace](https://marketplace.recordly.dev/extensions).
+
+---
+
+## All Features
+
+### Recording
+
+- Record an entire display or a single app window
+- Jump directly from recording into the editor
+- Capture microphone audio and system audio
+- Use native capture backends where supported
+- Resume editing from saved `.recordly` project files
+- Open existing recordings or existing project files from the app
+
+### Timeline and Editing
+
+- Drag-and-drop timeline editing
+- Trim unwanted sections
+- Add manual zoom regions
+- Use automatic zoom suggestions based on cursor activity
+- Add speed-up and slow-down regions
+- Add text, image, and figure annotations
+- Add extra audio regions on the timeline
+- Crop the recorded frame
+- Save and reopen projects with editor state preserved
+
+### Cursor Controls
+
+- Show or hide the rendered cursor overlay
+- Cursor size adjustment
+- Cursor smoothing
+- Cursor motion blur
+- Cursor click bounce
+- Cursor sway
+- Cursor loop mode for cleaner looping exports
+- macOS-style cursor assets for the rendered overlay
+
+### Webcam Overlay
+
+- Enable or disable webcam overlay footage
+- Upload, replace, or remove webcam footage
+- Mirror webcam footage
+- Size control
+- Preset positions and custom X/Y placement
+- Margin control
+- Roundness control
+- Shadow control
+- Optional zoom-reactive webcam scaling
+
+### Frame Styling and Backgrounds
+
+- Built-in wallpapers
+- Runtime wallpaper discovery from the wallpapers directory
+- Custom uploaded backgrounds
+- Solid color backgrounds
+- Gradient backgrounds
+- Frame padding
+- Rounded corners
+- Background blur
+- Drop shadows
+- Aspect ratio presets for the final frame
+
+### Export
+
+- MP4 export
+- GIF export
+- Export quality selection
+- GIF frame-rate selection
+- GIF loop toggle
+- GIF size presets
+- Aspect ratio and output dimension controls
+- Reveal exported files in the system file manager
+
+### Workflow and Usability
+
+- Customizable keyboard shortcuts
+- In-app shortcut reference
+- Feedback and issue links from the editor
+- Project persistence for editor preferences
+- Faster preview recovery after export
+---
+
+# Screenshots
+
+
+
+
+
+
+
+
+
+
+---
+
+# Installation
+
+## Download a build
+
+Prebuilt releases are available at:
+
+https://github.com/webadderallorg/Recordly/releases
+
+---
+
+## Arch Linux / Manjaro (yay)
+
+Install from the AUR ([recordly-bin](https://aur.archlinux.org/packages/recordly-bin)):
+
+```bash
+yay -S recordly-bin
+```
+
+PKGBUILD, desktop entry, release sync, and optional **local-from-source** packaging live in **[recordly-aur](https://github.com/firtoz/recordly-aur)** so this repository stays free of Arch release chores. For maintainer contact and how the package is updated, see that repo or the AUR package page.
+
+---
+
+## Build from source
+
+### Prerequisites
+
+**macOS:** Xcode Command Line Tools (`xcode-select --install`).
+
+**Linux (Ubuntu/Debian):**
+
+```bash
+sudo apt install build-essential cmake libx11-dev libxtst-dev libxrandr-dev libxt-dev
+```
+
+**Windows:** Visual Studio 2022 (or Build Tools) with the C++ workload and CMake.
+
+### Steps
+
+```bash
+git clone https://github.com/webadderallorg/Recordly.git recordly
+cd recordly
+npm install
+npm run dev
+```
+
+For packaged builds:
+
+```bash
+npm run build
+```
+
+Target-specific build commands are also available:
+
+- `npm run build:mac`
+- `npm run build:win`
+- `npm run build:linux`
+
+---
+
+## macOS: "App cannot be opened"
+
+Locally built apps may be quarantined by macOS.
+
+Remove the quarantine flag with:
+
+```bash
+xattr -rd com.apple.quarantine /Applications/Recordly.app
+```
+
+---
+
+# System Requirements
+
+| Platform | Minimum version | Notes |
+|---|---|---|
+| **macOS** | macOS 14.0 (Sonoma) | Required for ScreenCaptureKit audio and microphone capture. |
+| **Windows** | Windows 10 20H1 (Build 19041, May 2020) | Required for the native Windows Graphics Capture (WGC) helper and best cursor-hiding behavior. |
+| **Linux** | Any modern distro | Recording works through Electron capture. System audio generally requires PipeWire. |
+
+> [!IMPORTANT]
+> On Windows builds older than 19041, recording can still work through fallback capture, but the real OS cursor may remain visible in recordings.
+
+---
+
+# Usage
+
+## Record
+
+1. Launch Recordly.
+2. Select a screen or window.
+3. Choose microphone and system-audio options.
+4. Start recording.
+5. Stop recording to open the editor.
+
+## Edit
+
+Inside the editor you can:
+
+- add trims, zooms, speed regions, and annotations
+- tune cursor behavior and preview volume
+- style the frame with wallpapers, colors, gradients, blur, padding, and corners
+- add or adjust webcam overlay footage
+- add extra audio regions
+- crop the frame and choose an aspect ratio
+
+Save your work anytime as a `.recordly` project.
+
+## Export
+
+Export options include:
+
+- **MP4** for standard video output
+- **GIF** for lightweight sharing and loops
+
+You can adjust format-specific settings such as quality, GIF frame rate, GIF looping, and output size before export.
+
+---
+
+# Limitations
+
+### Cursor capture
+
+Recordly renders a polished cursor overlay on top of the recording. Platform cursor-hiding behavior still depends on OS support.
+
+**macOS**
+- ScreenCaptureKit can exclude the real cursor cleanly.
+
+**Windows**
+- Best results require Windows 10 Build 19041+ and the native capture helper.
+- Older builds fall back to Electron capture, so the real cursor may remain visible.
+
+**Linux**
+- Electron desktop capture does not currently support cursor hiding.
+- If you also enable the rendered cursor overlay, exports may show both the real cursor and the styled cursor.
+
+### System audio
+
+System audio support varies by platform.
+
+**Windows**
+- Native WASAPI support
+
+**Linux**
+- Usually requires PipeWire
+
+**macOS**
+- Requires macOS 14.0+ and the ScreenCaptureKit-based workflow
+
+---
+
+# How It Works
+
+Recordly combines a platform-specific capture layer with a renderer-driven editor and export pipeline.
+
+**Capture**
+- Electron coordinates recording and application flow
+- macOS uses native ScreenCaptureKit helpers
+- Windows uses a native Windows Graphics Capture (WGC) helper and native audio helpers where available
+
+**Editing**
+- Timeline regions define zooms, trims, speed changes, audio overlays, and annotations
+- Cursor and webcam styling are applied in the editor state
+
+**Rendering**
+- Scene composition is handled by **PixiJS**
+
+**Export**
+- The same scene logic used in preview is rendered into exported MP4 or GIF output
+
+**Projects**
+- `.recordly` files store the source media path plus editor state so work can be reopened later
+
+---
+
+# Contribution
+
+Contributions are welcome.
+
+Areas where help is especially useful:
+
+- Linux capture and cursor behavior
+- Export performance and stability
+- UI and UX refinement
+- Localisation work
+- Additional editor tools and workflow polish
+
+Please keep pull requests focused, test recording/edit/export flows, and avoid unrelated refactors.
+
+See `CONTRIBUTING.md` for guidelines.
+
+---
+
+# Community
+
+Bug reports and feature requests:
+
+https://github.com/webadderallorg/Recordly/issues
+
+Pull requests are welcome.
+
+---
+
+# Hall of Supporters
+
+[](https://ko-fi.com/webadderall)
+
+- Tom Egan @tomegan on X
+- Robin Ebers @robinebers on X
+- Tadees
+- buildwithfur
+- piccinato
+- Tobias
+- Anonymous Supporter
+- Tandava Appadoo
+- Digitalfastmind
+- Roberto Marcelino
+- Tony
+- Rajan RK
+- Francesco
+- Erwan
+- Anonymous supporter
+
+---
+
+# License
+
+Recordly is licensed under the **AGPL 3.0**.
+
+---
+
+# Credits
+
+## Acknowledgements
+
+Recordly originally started as a fork of [OpenScreen](https://github.com/siddharthvaddem/openscreen). Over 80% of code has diverged since.
+Many features of OpenScreen such as its zoom animations are directly ported from early versions of Recordly.
+
+Created by
+[@webadderall](https://x.com/webadderall)
+
+---
diff --git a/README.zh-CN.md b/README.zh-CN.md
new file mode 100644
index 000000000..b1ca9f556
--- /dev/null
+++ b/README.zh-CN.md
@@ -0,0 +1,400 @@
+语言: [EN](README.md) | 简中
+
+
+
+
+
+
+
+### 无需额外剪辑，也能做出精致的屏幕录制。
+[Recordly](https://www.recordly.dev) 是一款**开源屏幕录制器**和编辑器，适合制作**操作讲解、演示、产品视频**等内容。
+**欢迎提交 PR。** [赞助](https://ko-fi.com/webadderall/goal?g=0)
+
+https://github.com/user-attachments/assets/9b66c71d-ac97-49ff-a0c9-63ac26edf2e4
+
+---
+
+## Recordly 是什么？
+
+Recordly 是一款桌面应用，用于录制并编辑屏幕内容，内置面向演示视频的动态呈现工具。你不需要再把原始素材交给动效设计师去补缩放、光标润色或样式化背景，Recordly 可以在一个地方免费完成整套流程。
+
+Recordly 支持：
+
+- **macOS** 14.0+
+- **Windows** 10 Build 19041+
+- **Linux** 现代发行版
+
+平台说明：
+
+- **macOS** 使用基于 ScreenCaptureKit 的原生捕获辅助程序。
+- **Windows** 在支持的系统版本上使用原生 Windows Graphics Capture（WGC）辅助程序，并支持原生 WASAPI 音频。
+- **Linux** 通过 Electron 捕获 API 录制。目前 Linux 还不支持隐藏真实光标。
+
+---
+
+# 核心功能
+
+## 自动缩放、光标润色与样式化画面
+Recordly 可以根据操作自动强调重点区域，平滑光标运动，添加动态效果，并将最终画面放进带有壁纸、纯色、渐变、模糊、留白和阴影的样式化边框中。
+
+
+
+
+## 动态摄像头气泡叠加
+你可以把摄像头素材作为气泡叠加层加入画面，使用预设位置或自定义坐标摆放，支持镜像、阴影和圆角调节，也可以让它跟随缩放变化，保证动态镜头里整体视觉更协调。
+
+
+
+
+## 为演示设计的时间线编辑
+使用拖拽式时间线工具处理缩放、裁剪、变速区域、注释、额外音频区域以及裁切感知编辑，并将工作保存为 `.recordly` 项目文件，之后随时回来继续编辑。
+
+
+
+
+## 扩展与市场
+
+Recordly 拥有一个社区驱动的扩展系统。任何人都可以构建和发布扩展来为 Recordly 添加新功能，例如光标点击音效、设备边框、浏览器模拟外壳、壁纸、渲染钩子、设置面板等等。
+
+浏览并安装社区扩展：[Recordly 扩展市场](https://marketplace.recordly.dev/extensions)。
+
+---
+
+## 全部功能
+
+### 录制
+
+- 录制整个显示器或单个应用窗口
+- 录制完成后直接进入编辑器
+- 录制麦克风音频和系统音频
+- 在支持的平台上使用原生捕获后端
+- 从保存的 `.recordly` 项目文件继续编辑
+- 可在应用中打开已有录像或已有项目文件
+
+### 时间线与编辑
+
+- 拖拽式时间线编辑
+- 裁掉不需要的片段
+- 添加手动缩放区域
+- 根据光标活动生成自动缩放建议
+- 添加加速和减速区域
+- 添加文本、图片和图形注释
+- 在时间线上添加额外音频区域
+- 裁切录制画面
+- 保存并重新打开项目，保留编辑状态
+
+### 光标控制
+
+- 显示或隐藏渲染后的光标叠加层
+- 调整光标大小
+- 光标平滑
+- 光标运动模糊
+- 点击弹跳效果
+- 光标摆动效果
+- 光标循环模式，方便导出更自然的循环片段
+- 使用 macOS 风格的渲染光标素材
+
+### 摄像头叠加
+
+- 启用或禁用摄像头叠加素材
+- 上传、替换或移除摄像头素材
+- 镜像摄像头画面
+- 调整尺寸
+- 使用预设位置或自定义 X/Y 坐标
+- 调整边距
+- 调整圆角程度
+- 调整阴影强度
+- 可选的缩放联动摄像头缩放效果
+
+### 画面样式与背景
+
+- 内置壁纸
+- 运行时自动发现 wallpapers 目录中的壁纸
+- 上传自定义背景图片
+- 纯色背景
+- 渐变背景
+- 画面留白
+- 圆角
+- 背景模糊
+- 投影阴影
+- 最终画面的宽高比预设
+
+### 导出
+
+- MP4 导出
+- GIF 导出
+- 导出质量选择
+- GIF 帧率选择
+- GIF 循环开关
+- GIF 尺寸预设
+- 宽高比和输出尺寸控制
+- 在系统文件管理器中定位导出文件
+
+### 工作流与易用性
+
+- 可自定义键盘快捷键
+- 应用内快捷键说明
+- 在编辑器中直接打开反馈和问题链接
+- 编辑器偏好设置持久化
+- 导出后更快恢复预览
+
+---
+
+# 截图
+
+
+
+
+
+
+
+
+
+
+---
+
+# 安装
+
+## 下载构建版本
+
+预构建发布版本请见：
+
+https://github.com/webadderallorg/Recordly/releases
+
+---
+
+## Arch Linux / Manjaro（yay）
+
+可通过 AUR 安装（[recordly-bin](https://aur.archlinux.org/packages/recordly-bin)）：
+
+```bash
+yay -S recordly-bin
+```
+
+PKGBUILD、桌面入口、发布同步，以及可选的**本地源码打包**都维护在 **[recordly-aur](https://github.com/firtoz/recordly-aur)** 中，因此这个仓库本身不需要承担 Arch 发布维护工作。关于维护者联系方式和软件包更新方式，请查看该仓库或 AUR 软件包页面。
+
+---
+
+## 从源码构建
+
+### 前置依赖
+
+**macOS：** 安装 Xcode Command Line Tools（`xcode-select --install`）。
+
+**Linux（Ubuntu / Debian）：**
+
+```bash
+sudo apt install build-essential cmake libx11-dev libxtst-dev libxrandr-dev libxt-dev
+```
+
+**Windows：** 安装 Visual Studio 2022（或 Build Tools），并勾选 C++ 工作负载和 CMake。
+
+### 步骤
+
+```bash
+git clone https://github.com/webadderallorg/Recordly.git recordly
+cd recordly
+npm install
+npm run dev
+```
+
+如果需要打包构建：
+
+```bash
+npm run build
+```
+
+也可以使用平台专用构建命令：
+
+- `npm run build:mac`
+- `npm run build:win`
+- `npm run build:linux`
+
+---
+
+## macOS：“App cannot be opened”
+
+本地构建的应用可能会被 macOS 隔离。
+
+可以用以下命令移除隔离标记：
+
+```bash
+xattr -rd com.apple.quarantine /Applications/Recordly.app
+```
+
+---
+
+# 系统要求
+
+| 平台 | 最低版本 | 说明 |
+|---|---|---|
+| **macOS** | macOS 14.0 (Sonoma) | 使用 ScreenCaptureKit 捕获音频和麦克风所必需。 |
+| **Windows** | Windows 10 20H1（Build 19041，2020 年 5 月） | 原生 Windows Graphics Capture（WGC）辅助程序及最佳光标隐藏行为所必需。 |
+| **Linux** | 任意现代发行版 | 通过 Electron 捕获录制。系统音频通常需要 PipeWire。 |
+
+> [!IMPORTANT]
+> 在 Windows 19041 之前的版本上，录制仍可能通过回退捕获方式工作，但真实系统光标可能仍会出现在视频中。
+
+---
+
+# 使用方法
+
+## 录制
+
+1. 启动 Recordly。
+2. 选择屏幕或窗口。
+3. 选择麦克风和系统音频选项。
+4. 开始录制。
+5. 停止录制后进入编辑器。
+
+## 编辑
+
+在编辑器中，你可以：
+
+- 添加裁剪、缩放、变速区域和注释
+- 调整光标行为和预览音量
+- 使用壁纸、纯色、渐变、模糊、留白和圆角来美化画面
+- 添加或调整摄像头叠加素材
+- 添加额外音频区域
+- 裁切画面并选择宽高比
+
+你可以随时将工作保存为 `.recordly` 项目。
+
+## 导出
+
+支持以下导出格式：
+
+- **MP4**，适合常规视频输出
+- **GIF**，适合轻量分享和循环片段
+
+你可以在导出前调整格式相关设置，例如质量、GIF 帧率、GIF 循环方式和输出尺寸。
+
+---
+
+# 限制
+
+### 光标捕获
+
+Recordly 会在录制画面上渲染一个经过美化的光标叠加层，但真实系统光标是否能被隐藏仍取决于平台能力。
+
+**macOS**
+- ScreenCaptureKit 可以较干净地排除真实光标。
+
+**Windows**
+- 最佳效果需要 Windows 10 Build 19041+ 和原生捕获辅助程序。
+- 较旧版本会回退到 Electron 捕获，因此真实光标可能仍会显示。
+
+**Linux**
+- Electron 桌面捕获目前不支持隐藏真实光标。
+- 如果同时启用渲染光标叠加，导出中可能会同时看到真实光标和样式化光标。
+
+### 系统音频
+
+系统音频支持因平台而异。
+
+**Windows**
+- 原生 WASAPI 支持
+
+**Linux**
+- 通常需要 PipeWire
+
+**macOS**
+- 需要 macOS 14.0+ 和基于 ScreenCaptureKit 的工作流
+
+---
+
+# 工作原理
+
+Recordly 将平台相关的捕获层与基于渲染器的编辑、导出流程结合在一起。
+
+**捕获**
+- Electron 负责录制流程和应用级控制
+- macOS 使用原生 ScreenCaptureKit 辅助程序
+- Windows 在可用时使用原生 Windows Graphics Capture（WGC）辅助程序和原生音频辅助程序
+
+**编辑**
+- 时间线区域定义缩放、裁剪、变速、音频叠加和注释
+- 光标和摄像头样式都保存在编辑器状态中
+
+**渲染**
+- 场景合成由 **PixiJS** 负责
+
+**导出**
+- 预览使用的同一套场景逻辑会被用于导出 MP4 或 GIF
+
+**项目**
+- `.recordly` 文件会保存源媒体路径和编辑器状态，方便后续继续编辑
+
+---
+
+# 贡献
+
+欢迎贡献。
+
+特别需要帮助的方向包括：
+
+- Linux 录制与光标行为改进
+- 导出性能与稳定性优化
+- UI 和 UX 打磨
+- 本地化工作
+- 更多编辑工具与工作流优化
+
+请尽量让 Pull Request 保持聚焦，测试录制、编辑、导出流程，并避免无关重构。
+
+请参阅 `CONTRIBUTING.md` 了解具体指南。
+
+---
+
+# 社区
+
+问题反馈和功能建议：
+
+https://github.com/webadderallorg/Recordly/issues
+
+欢迎提交 Pull Request。
+
+---
+
+# 支持者名单
+
+[](https://ko-fi.com/webadderall)
+
+- Tadees
+- buildwithfur
+- Tobias
+- Anonymous Supporter
+- Tandava Appadoo
+- Digitalfastmind
+- Roberto Marcelino
+- Rajan RK
+- Francesco
+- Erwan
+- Anonymous supporter
+
+---
+
+# 许可证
+
+Recordly 基于 **AGPL 3.0** 发布。
+
+---
+
+# 致谢
+
+## 鸣谢
+
+Recordly 最初是从 [OpenScreen](https://github.com/siddharthvaddem/openscreen) 分叉而来，之后已逐步演变为一个不同的项目。
+
+创建者
+[@webadderall](https://x.com/webadderall)
+
+---
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 000000000..4ec8e22ad
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,103 @@
+# Releasing Recordly
+
+This repository now uses `electron-builder` + `electron-updater` for macOS, Windows, and Linux auto-updates.
+
+For this Electron app, that is the right path instead of wiring Sparkle.framework directly. On macOS, `electron-updater` handles the release metadata and update flow that Sparkle would otherwise cover in a native app, while still sharing the same GitHub Releases pipeline used by Windows and Linux.
+
+## What the release workflow does
+
+When you publish a GitHub release tagged like `v1.2.3`, `.github/workflows/release.yml` will:
+
+- validate that `package.json` is also `1.2.3`
+- build signed macOS x64 and arm64 artifacts
+- notarize the macOS builds
+- merge the dual-architecture `latest-mac.yml` metadata into one release asset
+- build and sign the Windows NSIS installer
+- build the Linux AppImage
+- publish installer artifacts and auto-update metadata files to the GitHub release
+- dispatch the Homebrew tap workflow after the release assets are available
+
+The packaged app then checks GitHub Releases for:
+
+- `latest-mac.yml`
+- `latest.yml`
+- `latest-linux.yml`
+
+## Required GitHub secrets
+
+### macOS signing and notarization
+
+Set these repository secrets:
+
+- `APPLE_SIGNING_CERTIFICATE_P12_BASE64`
+- `APPLE_SIGNING_CERTIFICATE_PASSWORD`
+- `APPLE_ID`
+- `APPLE_APP_SPECIFIC_PASSWORD`
+- `APPLE_TEAM_ID`
+
+`APPLE_SIGNING_CERTIFICATE_P12_BASE64` must be a base64-encoded `.p12` export of a `Developer ID Application` certificate.
+
+If the certificate you currently have is only `Apple Development`, that is not enough for public notarized releases and auto-update distribution. You need `Developer ID Application`.
+
+To export and encode the certificate:
+
+```bash
+security export -k ~/Library/Keychains/login.keychain-db -t identities -f pkcs12 -P "YOUR_P12_PASSWORD" -o recordly-mac-signing.p12
+base64 < recordly-mac-signing.p12 | pbcopy
+```
+
+Paste the copied base64 into `APPLE_SIGNING_CERTIFICATE_P12_BASE64` and the export password into `APPLE_SIGNING_CERTIFICATE_PASSWORD`.
+
+### Windows signing
+
+Set these repository secrets:
+
+- `WINDOWS_SIGNING_CERTIFICATE_P12_BASE64`
+- `WINDOWS_SIGNING_CERTIFICATE_PASSWORD`
+
+These should point to an Authenticode code-signing certificate exported as `.p12` and then base64-encoded.
+
+### Homebrew tap automation
+
+Set this repository secret if you want the cask PR to open automatically:
+
+- `HOMEBREW_TAP_TOKEN`
+
+Optional repository variables:
+
+- `HOMEBREW_TAP_REPO`
+- `HOMEBREW_TAP_AUTO_MERGE`
+
+## Release flow
+
+1. Bump `package.json` to the version you want to ship.
+2. Commit and push that version.
+3. Create a Git tag in the form `vX.Y.Z`.
+4. Create and publish a GitHub release for that tag. Prefer the helper so custom notes are prepended while GitHub still generates the contributor section:
+
+```bash
+npm run release:create -- --tag v1.2.3 --title "v1.2.3" --notes-file ./release-notes.md
+```
+
+For prereleases:
+
+```bash
+npm run release:create -- --tag v1.2.0-beta.2 --title "v1.2.0 beta-2" --prerelease --notes-file ./release-notes.md
+```
+
+This uses `gh release create --generate-notes`, which keeps GitHub's generated change summary and contributor list instead of replacing it with a fully manual release body.
+
+5. The `Publish Release` workflow builds, signs, notarizes, uploads, and publishes update metadata.
+
+That is the normal path if you want “click new release and let CI do the rest.”
+
+## Rebuilding an existing release
+
+If you need to rerun publishing for an existing tag, use the manual dispatch for `.github/workflows/release.yml` and provide the existing tag.
+
+## Notes
+
+- macOS auto-updates require the `zip` target in addition to `dmg`, because `latest-mac.yml` is generated from the zipped build.
+- macOS arm64 and x64 builds both publish updater zips, and the release workflow merges them into one `latest-mac.yml` so `electron-updater` can choose the correct architecture automatically.
+- The release workflow publishes versioned artifact names so the generated update metadata matches the uploaded files.
+- `build.yml` is intentionally forced to `--publish never` so ad hoc CI builds do not accidentally upload to a draft release.
diff --git a/TRANSLATION_GUIDE.md b/TRANSLATION_GUIDE.md
new file mode 100644
index 000000000..b0b599d72
--- /dev/null
+++ b/TRANSLATION_GUIDE.md
@@ -0,0 +1,65 @@
+# Translation Guide
+
+This project uses a namespace-based i18n setup so contributors can localize safely without changing app logic.
+
+## Locale Files
+
+All locale files live under:
+
+- `src/i18n/locales/en/`
+- `src/i18n/locales/es/`
+- `src/i18n/locales/zh-CN/`
+
+Each locale has the same namespace files:
+
+- `common.json`
+- `launch.json`
+- `editor.json`
+- `timeline.json`
+- `settings.json`
+- `dialogs.json`
+- `shortcuts.json`
+
+English (`en`) is the source of truth for key structure.
+
+## Key Rules
+
+- Keep the same key paths across locales.
+- Do not rename existing keys unless coordinated with code changes.
+- Add new keys to `en` first, then mirror into all other locales.
+- Prefer descriptive, stable keys. Example: `app.editorTitle`.
+- Interpolation is supported with `{{name}}` style placeholders.
+
+## How Translation Is Read
+
+- Keys with a namespace prefix like `settings.export.title` use that namespace.
+- Keys without a namespace default to `common`.
+- Missing translations fall back to English, then to the provided fallback string, then to the key.
+
+## Validate Locale Structure
+
+Run:
+
+```bash
+npm run i18n:check
+```
+
+This checks for:
+
+- Missing namespace files
+- Missing keys compared to `en`
+- Extra keys not present in `en`
+
+## Contributor Workflow
+
+1. Pull latest `main`.
+2. Update `en/.json` with new keys if needed.
+3. Add matching keys to other locale files.
+4. Run `npm run i18n:check`.
+5. Run app locally (`npm run dev`) and spot-check UI text.
+6. Open PR with a short summary of changed namespaces.
+
+## Scope Notes
+
+Current framework is app-wide and ready for full localization rollout.
+Not every UI string is migrated yet. Migration should be done incrementally by namespace to keep PRs reviewable and low-risk.
diff --git a/announcements.json b/announcements.json
new file mode 100644
index 000000000..f7e39713e
--- /dev/null
+++ b/announcements.json
@@ -0,0 +1,6 @@
+{
+ "settings": {
+ "aspectRatio": "4:3"
+ },
+ "announcements": []
+}
diff --git a/biome.json b/biome.json
new file mode 100644
index 000000000..6c8695eb4
--- /dev/null
+++ b/biome.json
@@ -0,0 +1,190 @@
+{
+ "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
+ "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+ "files": {
+ "ignoreUnknown": false,
+ "includes": [
+ "**",
+ "!!**/dist",
+ "!!**/dist-electron",
+ "!!**/dist-ssr",
+ "!!**/release",
+ "!!**/.tmp",
+ "!!**/electron/native/**/build"
+ ]
+ },
+ "formatter": {
+ "enabled": true,
+ "indentStyle": "tab",
+ "formatWithErrors": true,
+ "lineEnding": "lf",
+ "lineWidth": 100,
+ "attributePosition": "auto",
+ "indentWidth": 4
+ },
+ "linter": {
+ "enabled": true,
+ "rules": {
+ "recommended": false,
+ "complexity": {
+ "noAdjacentSpacesInRegex": "error",
+ "noBannedTypes": "error",
+ "noExtraBooleanCast": "error",
+ "noUselessCatch": "error",
+ "noUselessEscapeInRegex": "error",
+ "noUselessThisAlias": "error",
+ "noUselessTypeConstraint": "error"
+ },
+ "correctness": {
+ "noConstAssign": "error",
+ "noConstantCondition": "error",
+ "noEmptyCharacterClassInRegex": "error",
+ "noEmptyPattern": "error",
+ "noGlobalObjectCalls": "error",
+ "noInnerDeclarations": "error",
+ "noInvalidConstructorSuper": "error",
+ "noNonoctalDecimalEscape": "error",
+ "noPrecisionLoss": "error",
+ "noSelfAssign": "error",
+ "noSetterReturn": "error",
+ "noSwitchDeclarations": "error",
+ "noUndeclaredVariables": "error",
+ "noUnreachable": "error",
+ "noUnreachableSuper": "error",
+ "noUnsafeFinally": "error",
+ "noUnsafeOptionalChaining": "error",
+ "noUnusedLabels": "error",
+ "noUnusedVariables": "error",
+ "useExhaustiveDependencies": "warn",
+ "useHookAtTopLevel": "error",
+ "useIsNan": "error",
+ "useValidForDirection": "error",
+ "useValidTypeof": "error",
+ "useYield": "error"
+ },
+ "style": {
+ "noNamespace": "error",
+ "useArrayLiterals": "error",
+ "useAsConstAssertion": "error",
+ "useComponentExportOnlyModules": "off"
+ },
+ "suspicious": {
+ "noAssignInExpressions": "error",
+ "noAsyncPromiseExecutor": "error",
+ "noCatchAssign": "error",
+ "noClassAssign": "error",
+ "noCompareNegZero": "error",
+ "noControlCharactersInRegex": "error",
+ "noDebugger": "error",
+ "noDuplicateCase": "error",
+ "noDuplicateClassMembers": "error",
+ "noDuplicateElseIf": "error",
+ "noDuplicateObjectKeys": "error",
+ "noDuplicateParameters": "error",
+ "noEmptyBlockStatements": "error",
+ "noExplicitAny": "error",
+ "noExtraNonNullAssertion": "error",
+ "noFallthroughSwitchClause": "error",
+ "noFunctionAssign": "error",
+ "noGlobalAssign": "error",
+ "noImportAssign": "error",
+ "noIrregularWhitespace": "error",
+ "noMisleadingCharacterClass": "error",
+ "noMisleadingInstantiator": "error",
+ "noNonNullAssertedOptionalChain": "error",
+ "noPrototypeBuiltins": "error",
+ "noRedeclare": "error",
+ "noShadowRestrictedNames": "error",
+ "noSparseArray": "error",
+ "noTsIgnore": "error",
+ "noUnsafeDeclarationMerging": "error",
+ "noUnsafeNegation": "error",
+ "noUselessRegexBackrefs": "error",
+ "noWith": "error",
+ "useGetterReturn": "error"
+ }
+ }
+ },
+ "javascript": { "formatter": { "quoteStyle": "double" } },
+ "css": { "parser": { "cssModules": true, "tailwindDirectives": true } },
+ "overrides": [
+ {
+ "includes": ["*.ts", "*.tsx", "*.mts", "*.cts"],
+ "linter": {
+ "rules": {
+ "complexity": { "noArguments": "error" },
+ "correctness": {
+ "noConstAssign": "off",
+ "noGlobalObjectCalls": "off",
+ "noInvalidBuiltinInstantiation": "off",
+ "noInvalidConstructorSuper": "off",
+ "noSetterReturn": "off",
+ "noUndeclaredVariables": "off",
+ "noUnreachable": "off",
+ "noUnreachableSuper": "off"
+ },
+ "style": { "useConst": "error" },
+ "suspicious": {
+ "noDuplicateClassMembers": "off",
+ "noDuplicateObjectKeys": "off",
+ "noDuplicateParameters": "off",
+ "noFunctionAssign": "off",
+ "noImportAssign": "off",
+ "noRedeclare": "off",
+ "noUnsafeNegation": "off",
+ "noVar": "error",
+ "useGetterReturn": "off"
+ }
+ }
+ }
+ },
+ {
+ "includes": ["electron/electron-env.d.ts"],
+ "linter": {
+ "rules": {
+ "style": {
+ "noNamespace": "off"
+ },
+ "suspicious": {
+ "noExplicitAny": "off"
+ }
+ }
+ }
+ },
+ {
+ "includes": ["**/*.test.ts", "**/*.test.tsx"],
+ "linter": {
+ "rules": {
+ "correctness": {
+ "noEmptyPattern": "off"
+ },
+ "suspicious": {
+ "noEmptyBlockStatements": "off"
+ }
+ }
+ }
+ },
+ {
+ "includes": [
+ "src/components/video-editor/audio.test.ts",
+ "src/lib/exporter/frameRenderer.test.ts",
+ "src/lib/exporter/localMediaSource.test.ts",
+ "src/lib/exporter/modernFrameRenderer.test.ts"
+ ],
+ "linter": {
+ "rules": {
+ "correctness": {
+ "noUnusedVariables": "off"
+ },
+ "suspicious": {
+ "noExplicitAny": "off"
+ }
+ }
+ }
+ }
+ ],
+ "assist": {
+ "enabled": true,
+ "actions": { "source": { "organizeImports": "on" } }
+ }
+}
diff --git a/branding/source-assets/1024-mac.png b/branding/source-assets/1024-mac.png
new file mode 100644
index 000000000..7602ca8eb
Binary files /dev/null and b/branding/source-assets/1024-mac.png differ
diff --git a/branding/source-assets/128-mac.png b/branding/source-assets/128-mac.png
new file mode 100644
index 000000000..94ad18d1b
Binary files /dev/null and b/branding/source-assets/128-mac.png differ
diff --git a/branding/source-assets/16-mac.png b/branding/source-assets/16-mac.png
new file mode 100644
index 000000000..90118bdf0
Binary files /dev/null and b/branding/source-assets/16-mac.png differ
diff --git a/branding/source-assets/256-mac.png b/branding/source-assets/256-mac.png
new file mode 100644
index 000000000..fac38ff6e
Binary files /dev/null and b/branding/source-assets/256-mac.png differ
diff --git a/branding/source-assets/32-mac.png b/branding/source-assets/32-mac.png
new file mode 100644
index 000000000..2e21b5e13
Binary files /dev/null and b/branding/source-assets/32-mac.png differ
diff --git a/branding/source-assets/512-mac.png b/branding/source-assets/512-mac.png
new file mode 100644
index 000000000..3a0647e1a
Binary files /dev/null and b/branding/source-assets/512-mac.png differ
diff --git a/branding/source-assets/64-mac.png b/branding/source-assets/64-mac.png
new file mode 100644
index 000000000..15ec012b2
Binary files /dev/null and b/branding/source-assets/64-mac.png differ
diff --git a/branding/source-assets/Recordly.svg b/branding/source-assets/Recordly.svg
new file mode 100644
index 000000000..a936f4979
--- /dev/null
+++ b/branding/source-assets/Recordly.svg
@@ -0,0 +1,11 @@
+
+
+
+
+
+
+
diff --git a/branding/source-assets/recordlygeneric.svg b/branding/source-assets/recordlygeneric.svg
new file mode 100644
index 000000000..57910c64a
--- /dev/null
+++ b/branding/source-assets/recordlygeneric.svg
@@ -0,0 +1,16 @@
+
+
+
+
+
+
+
+
+
+
diff --git a/branding/source-assets/recordlymac.png b/branding/source-assets/recordlymac.png
new file mode 100644
index 000000000..6e4baf246
Binary files /dev/null and b/branding/source-assets/recordlymac.png differ
diff --git a/build/entitlements.mac.inherit.plist b/build/entitlements.mac.inherit.plist
new file mode 100644
index 000000000..a0414705f
--- /dev/null
+++ b/build/entitlements.mac.inherit.plist
@@ -0,0 +1,18 @@
+
+
+
+
+ com.apple.security.cs.allow-jit
+ com.apple.security.cs.allow-unsigned-executable-memory
+ com.apple.security.cs.disable-library-validation
+ com.apple.security.device.camera
+ com.apple.security.device.audio-input
+ com.apple.security.inherit
+
+
\ No newline at end of file
diff --git a/build/entitlements.mac.plist b/build/entitlements.mac.plist
new file mode 100644
index 000000000..98652b7fb
--- /dev/null
+++ b/build/entitlements.mac.plist
@@ -0,0 +1,16 @@
+
+
+
+
+ com.apple.security.cs.allow-jit
+ com.apple.security.cs.allow-unsigned-executable-memory
+ com.apple.security.cs.disable-library-validation
+ com.apple.security.device.camera
+ com.apple.security.device.audio-input
+
+
\ No newline at end of file
diff --git a/components.json b/components.json
index b4f439552..f6dc1d599 100644
--- a/components.json
+++ b/components.json
@@ -1,22 +1,22 @@
{
- "$schema": "https://ui.shadcn.com/schema.json",
- "style": "new-york",
- "rsc": false,
- "tsx": true,
- "tailwind": {
- "config": "tailwind.config.cjs",
- "css": "src/index.css",
- "baseColor": "stone",
- "cssVariables": true,
- "prefix": ""
- },
- "iconLibrary": "lucide",
- "aliases": {
- "components": "@/components",
- "utils": "@/lib/utils",
- "ui": "@/components/ui",
- "lib": "@/lib",
- "hooks": "@/hooks"
- },
- "registries": {}
+ "$schema": "https://ui.shadcn.com/schema.json",
+ "style": "new-york",
+ "rsc": false,
+ "tsx": true,
+ "tailwind": {
+ "config": "tailwind.config.cjs",
+ "css": "src/index.css",
+ "baseColor": "stone",
+ "cssVariables": true,
+ "prefix": ""
+ },
+ "iconLibrary": "lucide",
+ "aliases": {
+ "components": "@/components",
+ "utils": "@/lib/utils",
+ "ui": "@/components/ui",
+ "lib": "@/lib",
+ "hooks": "@/hooks"
+ },
+ "registries": {}
}
diff --git a/dist-electron/main.js b/dist-electron/main.js
deleted file mode 100644
index 0634f7dc0..000000000
--- a/dist-electron/main.js
+++ /dev/null
@@ -1,342 +0,0 @@
-import { BrowserWindow as E, screen as O, ipcMain as c, desktopCapturer as W, shell as V, app as d, nativeImage as L, Tray as U, Menu as A } from "electron";
-import { fileURLToPath as S } from "node:url";
-import t from "node:path";
-import p from "node:fs/promises";
-import { uIOhook as w } from "uiohook-napi";
-const P = t.dirname(S(import.meta.url)), C = t.join(P, ".."), y = process.env.VITE_DEV_SERVER_URL, x = t.join(C, "dist");
-function N() {
- const e = new E({
- width: 250,
- height: 80,
- minWidth: 250,
- maxWidth: 250,
- minHeight: 80,
- maxHeight: 80,
- frame: !1,
- transparent: !0,
- resizable: !1,
- alwaysOnTop: !0,
- skipTaskbar: !0,
- hasShadow: !1,
- webPreferences: {
- preload: t.join(P, "preload.mjs"),
- nodeIntegration: !1,
- contextIsolation: !0,
- backgroundThrottling: !1
- }
- });
- return e.webContents.on("did-finish-load", () => {
- e == null || e.webContents.send("main-process-message", (/* @__PURE__ */ new Date()).toLocaleString());
- }), y ? e.loadURL(y + "?windowType=hud-overlay") : e.loadFile(t.join(x, "index.html"), {
- query: { windowType: "hud-overlay" }
- }), e;
-}
-function H() {
- const e = new E({
- width: 1200,
- height: 800,
- minWidth: 800,
- minHeight: 600,
- frame: !0,
- transparent: !1,
- resizable: !0,
- alwaysOnTop: !1,
- skipTaskbar: !1,
- title: "",
- webPreferences: {
- preload: t.join(P, "preload.mjs"),
- nodeIntegration: !1,
- contextIsolation: !0,
- webSecurity: !1
- }
- });
- return e.maximize(), e.webContents.on("did-finish-load", () => {
- e == null || e.webContents.send("main-process-message", (/* @__PURE__ */ new Date()).toLocaleString());
- }), y ? e.loadURL(y + "?windowType=editor") : e.loadFile(t.join(x, "index.html"), {
- query: { windowType: "editor" }
- }), e;
-}
-function z() {
- const { width: e, height: n } = O.getPrimaryDisplay().workAreaSize, i = new E({
- width: 620,
- height: 420,
- minHeight: 350,
- maxHeight: 500,
- x: Math.round((e - 620) / 2),
- y: Math.round((n - 420) / 2),
- frame: !1,
- resizable: !1,
- alwaysOnTop: !0,
- transparent: !0,
- backgroundColor: "#00000000",
- webPreferences: {
- preload: t.join(P, "preload.mjs"),
- nodeIntegration: !1,
- contextIsolation: !0
- }
- });
- return y ? i.loadURL(y + "?windowType=source-selector") : i.loadFile(t.join(x, "index.html"), {
- query: { windowType: "source-selector" }
- }), i;
-}
-let u = !1, b = !1, m = 0, f = [];
-function q() {
- if (u)
- return { success: !1, message: "Already tracking" };
- if (u = !0, m = performance.now(), f = [], b)
- return { success: !0, message: "Mouse tracking resumed", startTime: m };
- $();
- try {
- return w.start(), b = !0, { success: !0, message: "Mouse tracking started", startTime: m };
- } catch (e) {
- return console.error("Failed to start mouse tracking:", e), u = !1, { success: !1, message: "Failed to start hook", error: e };
- }
-}
-function B() {
- if (!u)
- return { success: !1, message: "Not currently tracking" };
- u = !1;
- const e = performance.now() - m;
- return {
- success: !0,
- message: "Mouse tracking stopped",
- data: {
- startTime: m,
- events: f,
- duration: e
- }
- };
-}
-function $() {
- w.on("mousemove", (e) => {
- if (u) {
- const i = {
- type: "move",
- timestamp: performance.now() - m,
- x: e.x,
- y: e.y
- };
- f.push(i);
- }
- }), w.on("mousedown", (e) => {
- if (u) {
- const i = {
- type: "down",
- timestamp: performance.now() - m,
- x: e.x,
- y: e.y,
- button: e.button,
- clicks: e.clicks
- };
- f.push(i);
- }
- }), w.on("mouseup", (e) => {
- if (u) {
- const i = {
- type: "up",
- timestamp: performance.now() - m,
- x: e.x,
- y: e.y,
- button: e.button
- };
- f.push(i);
- }
- }), w.on("click", (e) => {
- if (u) {
- const i = {
- type: "click",
- timestamp: performance.now() - m,
- x: e.x,
- y: e.y,
- button: e.button,
- clicks: e.clicks
- };
- f.push(i);
- }
- });
-}
-function G() {
- return [...f];
-}
-function I() {
- if (b)
- try {
- w.stop(), b = !1, u = !1, f = [];
- } catch (e) {
- console.error("Error cleaning up mouse tracking:", e);
- }
-}
-let _ = null;
-function J(e, n, i, v, T) {
- c.handle("get-sources", async (o, a) => (await W.getSources(a)).map((r) => ({
- id: r.id,
- name: r.name,
- display_id: r.display_id,
- thumbnail: r.thumbnail ? r.thumbnail.toDataURL() : null,
- appIcon: r.appIcon ? r.appIcon.toDataURL() : null
- }))), c.handle("select-source", (o, a) => {
- _ = a;
- const s = v();
- return s && s.close(), _;
- }), c.handle("get-selected-source", () => _), c.handle("open-source-selector", () => {
- const o = v();
- if (o) {
- o.focus();
- return;
- }
- n();
- }), c.handle("switch-to-editor", () => {
- const o = i();
- o && o.close(), e();
- }), c.handle("start-mouse-tracking", () => q()), c.handle("stop-mouse-tracking", () => B()), c.handle("store-recorded-video", async (o, a, s) => {
- try {
- const r = t.join(h, s);
- return await p.writeFile(r, Buffer.from(a)), {
- success: !0,
- path: r,
- message: "Video stored successfully"
- };
- } catch (r) {
- return console.error("Failed to store video:", r), {
- success: !1,
- message: "Failed to store video",
- error: String(r)
- };
- }
- }), c.handle("store-mouse-tracking-data", async (o, a) => {
- try {
- const s = G();
- if (s.length === 0)
- return { success: !1, message: "No tracking data to save" };
- const r = t.join(h, a);
- return await p.writeFile(r, JSON.stringify(s, null, 2), "utf-8"), {
- success: !0,
- path: r,
- eventCount: s.length,
- message: "Mouse tracking data stored successfully"
- };
- } catch (s) {
- return console.error("Failed to store mouse tracking data:", s), {
- success: !1,
- message: "Failed to store mouse tracking data",
- error: String(s)
- };
- }
- }), c.handle("get-recorded-video-path", async () => {
- try {
- const a = (await p.readdir(h)).filter((R) => R.endsWith(".webm"));
- if (a.length === 0)
- return { success: !1, message: "No recorded video found" };
- const s = a.sort().reverse()[0];
- return { success: !0, path: t.join(h, s) };
- } catch (o) {
- return console.error("Failed to get video path:", o), { success: !1, message: "Failed to get video path", error: String(o) };
- }
- }), c.handle("set-recording-state", (o, a) => {
- T && T(a, (_ || { name: "Screen" }).name);
- }), c.handle("open-external-url", async (o, a) => {
- try {
- return await V.openExternal(a), { success: !0 };
- } catch (s) {
- return console.error("Failed to open URL:", s), { success: !1, error: String(s) };
- }
- }), c.handle("get-asset-base-path", () => {
- try {
- return d.isPackaged ? t.join(process.resourcesPath, "assets") : t.join(d.getAppPath(), "public", "assets");
- } catch (o) {
- return console.error("Failed to resolve asset base path:", o), null;
- }
- }), c.handle("save-exported-video", async (o, a, s) => {
- try {
- const r = d.getPath("downloads"), R = t.join(r, s);
- return await p.writeFile(R, Buffer.from(a)), {
- success: !0,
- path: R,
- message: "Video exported successfully"
- };
- } catch (r) {
- return console.error("Failed to save exported video:", r), {
- success: !1,
- message: "Failed to save exported video",
- error: String(r)
- };
- }
- });
-}
-const K = t.dirname(S(import.meta.url)), h = t.join(d.getPath("userData"), "recordings");
-async function Q() {
- try {
- const e = await p.readdir(h), n = Date.now(), i = 1 * 24 * 60 * 60 * 1e3;
- for (const v of e) {
- const T = t.join(h, v), o = await p.stat(T);
- n - o.mtimeMs > i && (await p.unlink(T), console.log(`Deleted old recording: ${v}`));
- }
- } catch (e) {
- console.error("Failed to cleanup old recordings:", e);
- }
-}
-async function X() {
- try {
- await p.mkdir(h, { recursive: !0 }), console.log("Recordings directory ready:", h);
- } catch (e) {
- console.error("Failed to create recordings directory:", e);
- }
-}
-process.env.APP_ROOT = t.join(K, "..");
-const Y = process.env.VITE_DEV_SERVER_URL, ie = t.join(process.env.APP_ROOT, "dist-electron"), j = t.join(process.env.APP_ROOT, "dist");
-process.env.VITE_PUBLIC = Y ? t.join(process.env.APP_ROOT, "public") : j;
-let l = null, k = null, g = null, D = "";
-function F() {
- l = N();
-}
-function Z() {
- const e = t.join(process.env.VITE_PUBLIC || j, "rec-button.png");
- let n = L.createFromPath(e);
- n = n.resize({ width: 24, height: 24, quality: "best" }), g = new U(n), M();
-}
-function M() {
- if (!g) return;
- const e = [
- {
- label: "Stop Recording",
- click: () => {
- l && !l.isDestroyed() && l.webContents.send("stop-recording-from-tray");
- }
- }
- ], n = A.buildFromTemplate(e);
- g.setContextMenu(n), g.setToolTip(`Recording: ${D}`);
-}
-function ee() {
- l && (l.close(), l = null), l = H();
-}
-function te() {
- return k = z(), k.on("closed", () => {
- k = null;
- }), k;
-}
-d.on("window-all-closed", () => {
- process.platform !== "darwin" && (I(), d.quit(), l = null);
-});
-d.on("activate", () => {
- E.getAllWindows().length === 0 && F();
-});
-d.on("before-quit", async (e) => {
- e.preventDefault(), I(), await Q(), d.exit(0);
-});
-d.whenReady().then(async () => {
- await X(), J(
- ee,
- te,
- () => l,
- () => k,
- (e, n) => {
- D = n, e ? (g || Z(), M(), l && l.minimize()) : (g && (g.destroy(), g = null), l && l.restore());
- }
- ), F();
-});
-export {
- ie as MAIN_DIST,
- h as RECORDINGS_DIR,
- j as RENDERER_DIST,
- Y as VITE_DEV_SERVER_URL
-};
diff --git a/dist-electron/preload.mjs b/dist-electron/preload.mjs
deleted file mode 100644
index 92d0779b1..000000000
--- a/dist-electron/preload.mjs
+++ /dev/null
@@ -1 +0,0 @@
-"use strict";const e=require("electron");e.contextBridge.exposeInMainWorld("electronAPI",{getAssetBasePath:async()=>await e.ipcRenderer.invoke("get-asset-base-path"),getSources:async r=>await e.ipcRenderer.invoke("get-sources",r),switchToEditor:()=>e.ipcRenderer.invoke("switch-to-editor"),openSourceSelector:()=>e.ipcRenderer.invoke("open-source-selector"),selectSource:r=>e.ipcRenderer.invoke("select-source",r),getSelectedSource:()=>e.ipcRenderer.invoke("get-selected-source"),startMouseTracking:()=>e.ipcRenderer.invoke("start-mouse-tracking"),stopMouseTracking:()=>e.ipcRenderer.invoke("stop-mouse-tracking"),storeRecordedVideo:(r,t)=>e.ipcRenderer.invoke("store-recorded-video",r,t),storeMouseTrackingData:r=>e.ipcRenderer.invoke("store-mouse-tracking-data",r),getRecordedVideoPath:()=>e.ipcRenderer.invoke("get-recorded-video-path"),setRecordingState:r=>e.ipcRenderer.invoke("set-recording-state",r),onStopRecordingFromTray:r=>{const t=()=>r();return e.ipcRenderer.on("stop-recording-from-tray",t),()=>e.ipcRenderer.removeListener("stop-recording-from-tray",t)},openExternalUrl:r=>e.ipcRenderer.invoke("open-external-url",r),saveExportedVideo:(r,t)=>e.ipcRenderer.invoke("save-exported-video",r,t)});
diff --git a/docs/announcements.md b/docs/announcements.md
new file mode 100644
index 000000000..51637ff42
--- /dev/null
+++ b/docs/announcements.md
@@ -0,0 +1,96 @@
+# In-app announcements
+
+Recordly can show dismissible announcements in the editor as a popup, carousel slide, lightweight live notification, or header banner. Popups can contain images or video; notifications and banners are text-only with optional buttons.
+
+## Remote announcements
+
+Edit [`announcements.json`](../announcements.json) on the `main` branch to publish an announcement without releasing a new app version. Released clients check the raw GitHub file at most once every six hours per running app instance. Fetch failures are silent and never block startup.
+
+```json
+{
+ "settings": {
+ "aspectRatio": "4:3"
+ },
+ "announcements": [
+ {
+ "id": "recordly-1.4-release",
+ "title": "A faster Recordly is here",
+ "body": "Exports are faster and cursor motion is smoother. Thanks for using Recordly!",
+ "presentation": "popup",
+ "audience": "editor",
+ "priority": 10,
+ "mediaMode": "cover",
+ "displayDurationSeconds": 15,
+ "maxImpressions": 3,
+ "controls": {
+ "close": true,
+ "dismiss": false,
+ "action": true,
+ "navigation": false,
+ "indicators": true
+ },
+ "startsAt": "2026-09-01T00:00:00Z",
+ "endsAt": "2026-10-01T00:00:00Z",
+ "minVersion": "1.4.0",
+ "media": {
+ "type": "image",
+ "url": "https://example.com/recordly-1.4-banner.jpg",
+ "alt": "Recordly 1.4 feature preview"
+ },
+ "action": {
+ "label": "See what changed",
+ "url": "https://github.com/webadderallorg/Recordly/releases"
+ }
+ },
+ {
+ "id": "recordly-maintenance-notice",
+ "title": "Quick service notice",
+ "body": "Cloud sharing will undergo brief maintenance tonight.",
+ "presentation": "notification",
+ "audience": "editor",
+ "displayDurationSeconds": 10,
+ "maxImpressions": 2,
+ "startsAt": "2026-09-05T00:00:00Z",
+ "endsAt": "2026-09-06T00:00:00Z"
+ },
+ {
+ "id": "recordly-editor-banner",
+ "title": "Try the new editor",
+ "body": "The redesigned timeline is now available.",
+ "presentation": "banner",
+ "audience": "editor",
+ "maxImpressions": 3,
+ "action": {
+ "label": "Open settings",
+ "section": "settings"
+ }
+ }
+ ]
+}
+```
+
+Use a new stable `id` whenever an announcement should appear again. Once a user dismisses an ID, it remains dismissed. Remote items with the same ID override bundled items.
+
+Supported fields:
+
+- `settings.aspectRatio` sets one shared `width:height` ratio for the entire popup carousel, such as `16:9`, `4:3`, or `1:1`. All slides keep that same size. If omitted, the bundled default is used.
+- `id`, `title`, and `body` are required.
+- `presentation` is `popup`, `notification`, or `banner` and defaults to `popup`. Notifications appear as text-only non-modal toasts, while banners appear only in the editor directly beneath its header. Media and `mediaMode` are ignored for notifications and banners. At most five notifications are shown from one feed load; banners are shown one at a time by priority.
+- `audience` is `all` or `editor` and defaults to `all`.
+- `priority` controls carousel order; larger numbers appear first.
+- `mediaMode` is `banner` or `cover`. `banner` is the default current layout; `cover` fills the popup with the media and overlays the text.
+- `startsAt` and `endsAt` are optional ISO timestamps.
+- `displayDurationSeconds` accepts 3–300 seconds. It auto-advances popup slides; for notifications it controls how long the toast remains visible and defaults to 10 seconds.
+- `maxImpressions` optionally limits an announcement to 1–100 app sessions. Each announcement counts at most once per session; an explicit dismissal always hides it permanently.
+- `controls` can independently show or hide `close`, `dismiss`, `action`, `navigation`, and `indicators`. Every control defaults to `true`. Notifications and banners use only `close` and `action`; popup carousels use the other controls. Escape and clicking outside a popup remain available even when visible close controls are hidden.
+- `minVersion` and `maxVersion` are optional inclusive app-version bounds.
+- `media.type` is `image` or `video` for popups. Media URLs must be HTTPS or root-relative bundled assets. Videos can also specify `posterUrl`.
+- `action` has a label and exactly one destination: an HTTPS `url` opened in the system browser, or an editor `section` opened inside the app. Supported sections are `scene`, `cursor`, `webcam`, `captions`, `settings`, and `extensions`. An action containing both destinations, neither destination, or an unknown section is ignored.
+
+Set `RECORDLY_ANNOUNCEMENTS_URL` before launching the app to use a different HTTPS feed. Set it to `off` to disable remote announcements.
+
+## Announcements bundled with an update
+
+Add typed entries to `src/content/announcements.ts`. Bundled items use the same schema and are available offline. This is useful when a message should ship atomically with a new release.
+
+Remote content is treated as data only: HTML is not rendered, URLs are restricted, feeds are size-limited and time-limited, and malformed items are ignored.
diff --git a/docs/media/CursorLoop.gif b/docs/media/CursorLoop.gif
new file mode 100644
index 000000000..e4844abb8
Binary files /dev/null and b/docs/media/CursorLoop.gif differ
diff --git a/docs/media/CursorSwayDemo.gif b/docs/media/CursorSwayDemo.gif
new file mode 100644
index 000000000..352e82e08
Binary files /dev/null and b/docs/media/CursorSwayDemo.gif differ
diff --git a/docs/media/demo.gif b/docs/media/demo.gif
new file mode 100644
index 000000000..d307f34b1
Binary files /dev/null and b/docs/media/demo.gif differ
diff --git a/public/wallpapers/wallpaper8.jpg b/docs/media/feature1.gif
similarity index 52%
rename from public/wallpapers/wallpaper8.jpg
rename to docs/media/feature1.gif
index 9cf1193f6..3ff0ae37b 100644
Binary files a/public/wallpapers/wallpaper8.jpg and b/docs/media/feature1.gif differ
diff --git a/docs/media/feature2.gif b/docs/media/feature2.gif
new file mode 100644
index 000000000..2b4ebb2ad
Binary files /dev/null and b/docs/media/feature2.gif differ
diff --git a/docs/media/feature3.png b/docs/media/feature3.png
new file mode 100644
index 000000000..b8330b154
Binary files /dev/null and b/docs/media/feature3.png differ
diff --git a/electron-builder.json5 b/electron-builder.json5
index 327778bfe..a333a8723 100644
--- a/electron-builder.json5
+++ b/electron-builder.json5
@@ -1,52 +1,114 @@
-// @see - https://www.electron.build/configuration/configuration
-{
- "$schema": "https://raw.githubusercontent.com/electron-userland/electron-builder/master/packages/app-builder-lib/scheme.json",
- "appId": "com.siddharthvaddem.openscreen",
- "asar": true,
- "productName": "Openscreen",
- "directories": {
- "output": "release/${version}"
- },
- "files": [
- "dist",
- "dist-electron"
- ],
- "extraResources": [
- {
- "from": "public/wallpapers",
- "to": "assets/wallpapers"
- }
- ],
- "mac": {
- "target": [
- "dmg"
- ],
- "icon": "icons/icons/mac/icon.icns",
- "artifactName": "${productName}-Mac-${version}-Installer.${ext}"
- },
- "win": {
- "target": [
- {
- "target": "nsis",
- "arch": [
- "x64"
- ]
- }
- ],
- "icon": "icons/icons/win/icon.ico",
- "artifactName": "${productName}-Windows-${version}-Setup.${ext}",
- "requestedExecutionLevel": "asInvoker"
- },
- "nsis": {
- "oneClick": false,
- "perMachine": false,
- "allowToChangeInstallationDirectory": true,
- "deleteAppDataOnUninstall": false
- },
- "linux": {
- "target": [
- "AppImage"
- ],
- "artifactName": "${productName}-Linux-${version}.${ext}"
- }
-}
+// @see - https://www.electron.build/configuration/configuration
+{
+ "$schema": "https://raw.githubusercontent.com/electron-userland/electron-builder/master/packages/app-builder-lib/scheme.json",
+ "appId": "dev.recordly.app",
+ "electronUpdaterCompatibility": ">=2.16",
+ "asar": true,
+ "asarUnpack": [
+ "node_modules/ffmpeg-static/**",
+ "node_modules/ffprobe-static/**",
+ "node_modules/uiohook-napi/**",
+ "electron/native/**"
+ ],
+ "productName": "Recordly",
+ "npmRebuild": true,
+ "buildDependenciesFromSource": true,
+ "compression": "normal",
+ "directories": {
+ "output": "release"
+ },
+ "files": [
+ "dist",
+ "dist-electron",
+ "electron/native",
+ "!node_modules/ffprobe-static/bin/darwin/**",
+ "!node_modules/ffprobe-static/bin/linux/**",
+ "!node_modules/ffprobe-static/bin/win32/ia32/**",
+ "!electron/native/**/build/**",
+ "!*.png",
+ "!preview*.png",
+ "!*.md",
+ "!README.md",
+ "!CONTRIBUTING.md",
+ "!LICENSE"
+ ],
+ "extraResources": [
+ {
+ "from": "public/wallpapers",
+ "to": "assets/wallpapers"
+ }
+ ],
+ "publish": [
+ {
+ "provider": "github",
+ "owner": "webadderall",
+ "repo": "Recordly",
+ "tagNamePrefix": "v",
+ "publishAutoUpdate": true
+ }
+ ],
+
+ "mac": {
+ "hardenedRuntime": true,
+ "entitlements": "build/entitlements.mac.plist",
+ "entitlementsInherit": "build/entitlements.mac.inherit.plist",
+ "target": [
+ {
+ "target": "dmg",
+ "arch": ["x64", "arm64"]
+ },
+ {
+ "target": "zip",
+ "arch": ["x64", "arm64"]
+ }
+ ],
+ "icon": "icons/icons/mac/icon.icns",
+ "artifactName": "${productName}-${arch}.${ext}",
+ "extendInfo": {
+ "NSAudioCaptureUsageDescription": "Recordly needs audio capture permission to record system audio.",
+ "NSCameraUsageDescription": "Recordly needs camera access to record webcam video.",
+ "NSMicrophoneUsageDescription": "Recordly needs microphone access to record voice audio.",
+ "NSCameraUseContinuityCameraDeviceType": true,
+ "com.apple.security.device.audio-input": true,
+ "CFBundleDocumentTypes": [
+ {
+ "CFBundleTypeName": "Recordly Project",
+ "CFBundleTypeRole": "Editor",
+ "CFBundleTypeExtensions": ["recordly"],
+ "CFBundleTypeIconFile": "icon.icns",
+ "LSHandlerRank": "Owner",
+ "LSItemContentTypes": ["dev.recordly.app.project"]
+ }
+ ],
+ "UTExportedTypeDeclarations": [
+ {
+ "UTTypeIdentifier": "dev.recordly.app.project",
+ "UTTypeDescription": "Recordly Project",
+ "UTTypeConformsTo": ["public.json"],
+ "UTTypeTagSpecification": {
+ "public.filename-extension": ["recordly"],
+ "public.mime-type": "application/x-recordly-project"
+ }
+ }
+ ]
+ }
+ },
+ "linux": {
+ "target": [
+ "AppImage"
+ ],
+ "icon": "icons/icons/png",
+ "artifactName": "${productName}-linux-x64.${ext}",
+ "category": "AudioVideo"
+ },
+ "win": {
+ "target": [
+ "nsis"
+ ],
+ "icon": "icons/icons/win/icon.ico"
+ ,
+ "executableName": "Recordly",
+ "artifactName": "${productName}-windows-${arch}.${ext}"
+ }
+}
+
diff --git a/electron/appPaths.ts b/electron/appPaths.ts
new file mode 100644
index 000000000..68d6cfc39
--- /dev/null
+++ b/electron/appPaths.ts
@@ -0,0 +1,11 @@
+import path from "node:path";
+import { app } from "electron";
+
+if (process.env["VITE_DEV_SERVER_URL"]) {
+ const devUserDataPath = path.join(app.getPath("appData"), "Recordly-dev");
+ app.setPath("userData", devUserDataPath);
+ app.setPath("sessionData", path.join(devUserDataPath, "session"));
+}
+
+export const USER_DATA_PATH = app.getPath("userData");
+export const RECORDINGS_DIR = path.join(USER_DATA_PATH, "recordings");
diff --git a/electron/appSettingsStore.ts b/electron/appSettingsStore.ts
new file mode 100644
index 000000000..c777b1004
--- /dev/null
+++ b/electron/appSettingsStore.ts
@@ -0,0 +1,36 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { APP_SETTINGS_FILE } from "./ipc/constants";
+import { parseJsonWithByteOrderMark } from "./ipc/utils";
+
+export function readAppSettingsStore(): Record {
+ try {
+ const content = readFileSync(APP_SETTINGS_FILE, "utf-8");
+ const parsed = parseJsonWithByteOrderMark(content);
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ return {};
+ }
+
+ return parsed as Record;
+ } catch {
+ return {};
+ }
+}
+
+export function writeAppSettingsStore(store: Record) {
+ writeFileSync(APP_SETTINGS_FILE, JSON.stringify(store, null, 2), "utf-8");
+}
+
+export function hasAppSetting(store: Record, key: string): boolean {
+ return Reflect.getOwnPropertyDescriptor(store, key) !== undefined;
+}
+
+export function readAppSetting(key: string): unknown {
+ const store = readAppSettingsStore();
+ return hasAppSetting(store, key) ? store[key] : null;
+}
+
+export function writeAppSetting(key: string, value: unknown) {
+ const store = readAppSettingsStore();
+ store[key] = value;
+ writeAppSettingsStore(store);
+}
diff --git a/electron/cursorHider.ts b/electron/cursorHider.ts
new file mode 100644
index 000000000..266d111a9
--- /dev/null
+++ b/electron/cursorHider.ts
@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+
+const PY_HIDE_WIN = `
+import ctypes, sys
+
+class POINT(ctypes.Structure):
+ _fields_ = [("x", ctypes.c_long), ("y", ctypes.c_long)]
+
+class CURSORINFO(ctypes.Structure):
+ _fields_ = [
+ ("cbSize", ctypes.c_uint),
+ ("flags", ctypes.c_uint),
+ ("hCursor", ctypes.c_void_p),
+ ("ptScreenPos", POINT),
+ ]
+
+user32 = ctypes.windll.user32
+CURSOR_SHOWING = 0x00000001
+
+for _ in range(32):
+ info = CURSORINFO()
+ info.cbSize = ctypes.sizeof(CURSORINFO)
+ if user32.GetCursorInfo(ctypes.byref(info)) and not (info.flags & CURSOR_SHOWING):
+ sys.exit(0)
+ user32.ShowCursor(False)
+
+sys.exit(0)
+`.trim();
+
+const PY_SHOW_WIN = `
+import ctypes, sys
+
+class POINT(ctypes.Structure):
+ _fields_ = [("x", ctypes.c_long), ("y", ctypes.c_long)]
+
+class CURSORINFO(ctypes.Structure):
+ _fields_ = [
+ ("cbSize", ctypes.c_uint),
+ ("flags", ctypes.c_uint),
+ ("hCursor", ctypes.c_void_p),
+ ("ptScreenPos", POINT),
+ ]
+
+user32 = ctypes.windll.user32
+CURSOR_SHOWING = 0x00000001
+
+for _ in range(32):
+ info = CURSORINFO()
+ info.cbSize = ctypes.sizeof(CURSORINFO)
+ if user32.GetCursorInfo(ctypes.byref(info)) and (info.flags & CURSOR_SHOWING):
+ sys.exit(0)
+ user32.ShowCursor(True)
+
+sys.exit(0)
+`.trim();
+
+function getPowerShellCommand(show: boolean) {
+ const desiredFlag = show ? 1 : 0;
+ const showLiteral = show ? "$true" : "$false";
+
+ return [
+ '$signature = @"',
+ "using System;",
+ "using System.Runtime.InteropServices;",
+ "public struct POINT { public int X; public int Y; }",
+ "public struct CURSORINFO { public int cbSize; public int flags; public IntPtr hCursor; public POINT ptScreenPos; }",
+ "public static class CursorNative {",
+ ' [DllImport("user32.dll")] public static extern int ShowCursor(bool show);',
+ ' [DllImport("user32.dll")] public static extern bool GetCursorInfo(ref CURSORINFO info);',
+ "}",
+ '"@;',
+ "Add-Type -TypeDefinition $signature -Language CSharp -ErrorAction SilentlyContinue | Out-Null;",
+ "$info = New-Object CURSORINFO;",
+ "$info.cbSize = [Runtime.InteropServices.Marshal]::SizeOf([type]CURSORINFO);",
+ "for ($i = 0; $i -lt 32; $i++) {",
+ " if ([CursorNative]::GetCursorInfo([ref]$info) -and (($info.flags -band 1) -eq " +
+ desiredFlag +
+ ")) { exit 0 }",
+ " [CursorNative]::ShowCursor(" + showLiteral + ") | Out-Null;",
+ "}",
+ "exit 0",
+ ].join(" ");
+}
+
+function runPythonSnippet(code: string) {
+ for (const executable of ["python", "python3", "py"]) {
+ const result = spawnSync(executable, ["-c", code], { timeout: 5000 });
+ if (!result.error && result.status === 0) {
+ return true;
+ }
+ }
+
+ return false;
+}
+
+function runPowerShellSnippet(command: string) {
+ const result = spawnSync(
+ "powershell.exe",
+ ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", command],
+ { timeout: 8000 },
+ );
+
+ return !result.error && result.status === 0;
+}
+
+let cursorHidden = false;
+
+export function hideCursor() {
+ if (process.platform !== "win32" || cursorHidden) {
+ return false;
+ }
+
+ try {
+ const didHide =
+ runPythonSnippet(PY_HIDE_WIN) || runPowerShellSnippet(getPowerShellCommand(false));
+
+ if (didHide) {
+ cursorHidden = true;
+ }
+
+ return didHide;
+ } catch (error) {
+ console.error("[cursorHider] Failed to hide Windows cursor:", error);
+ return false;
+ }
+}
+
+export function showCursor() {
+ if (process.platform !== "win32" || !cursorHidden) {
+ return false;
+ }
+
+ try {
+ const didShow =
+ runPythonSnippet(PY_SHOW_WIN) || runPowerShellSnippet(getPowerShellCommand(true));
+ if (didShow) {
+ cursorHidden = false;
+ }
+ return didShow;
+ } catch (error) {
+ console.error("[cursorHider] Failed to show Windows cursor:", error);
+ return false;
+ }
+}
diff --git a/electron/electron-env.d.ts b/electron/electron-env.d.ts
index 0853fc160..c00ef3226 100644
--- a/electron/electron-env.d.ts
+++ b/electron/electron-env.d.ts
@@ -1,50 +1,965 @@
-///
- switchToEditor: () => Promise
- openSourceSelector: () => Promise
- selectSource: (source: any) => Promise
- getSelectedSource: () => Promise
- startMouseTracking: () => Promise
- stopMouseTracking: () => Promise
- storeRecordedVideo: (videoData: ArrayBuffer, fileName: string) => Promise<{ success: boolean; path?: string; message?: string }>
- storeMouseTrackingData: (fileName: string) => Promise<{ success: boolean; path?: string; eventCount?: number; message?: string }>
- getRecordedVideoPath: () => Promise<{ success: boolean; path?: string; message?: string }>
- setRecordingState: (recording: boolean) => Promise
- onStopRecordingFromTray: (callback: () => void) => () => void
- openExternalUrl: (url: string) => Promise<{ success: boolean; error?: string }>
- saveExportedVideo: (videoData: ArrayBuffer, fileName: string) => Promise<{ success: boolean; path?: string; message?: string }>
- }
-}
-
-interface ProcessedDesktopSource {
- id: string
- name: string
- display_id: string
- thumbnail: string | null
- appIcon: string | null
-}
+/// ;
+ getSources: (opts: Electron.SourcesOptions) => Promise;
+ switchToEditor: () => Promise;
+ openSourceSelector: () => Promise;
+ selectSource: (source: ProcessedDesktopSource) => Promise;
+ showSourceHighlight: (source: ProcessedDesktopSource) => Promise<{ success: boolean }>;
+ getSelectedSource: () => Promise;
+ onSelectedSourceChanged: (
+ callback: (source: ProcessedDesktopSource | null) => void,
+ ) => () => void;
+ startNativeScreenRecording: (
+ source: ProcessedDesktopSource,
+ options?: {
+ capturesSystemAudio?: boolean;
+ capturesMicrophone?: boolean;
+ microphoneDeviceId?: string;
+ microphoneLabel?: string;
+ },
+ ) => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ userNotified?: boolean;
+ microphoneFallbackRequired?: boolean;
+ }>;
+ stopNativeScreenRecording: () => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ }>;
+ recoverNativeScreenRecording: () => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ }>;
+ getLastNativeCaptureDiagnostics: () => Promise<{
+ success: boolean;
+ diagnostics?: NativeCaptureDiagnostics | null;
+ }>;
+ pauseNativeScreenRecording: () => Promise<{
+ success: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ resumeNativeScreenRecording: () => Promise<{
+ success: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ pauseCursorCapture: (pausedAtMs?: number) => Promise<{
+ success: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ resumeCursorCapture: (resumedAtMs?: number) => Promise<{
+ success: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ startFfmpegRecording: (
+ source: ProcessedDesktopSource,
+ ) => Promise<{ success: boolean; path?: string; message?: string; error?: string }>;
+ stopFfmpegRecording: () => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ }>;
+ storeRecordedVideo: (
+ videoData: ArrayBuffer,
+ fileName: string,
+ ) => Promise<{ success: boolean; path?: string; message?: string }>;
+ storeMicrophoneSidecar: (
+ audioData: ArrayBuffer,
+ videoPath: string,
+ options?: {
+ startDelayMs?: number;
+ browserMicrophoneProfile?: string;
+ requestedBrowserMicrophoneProfile?: string | null;
+ requestedConstraints?: unknown;
+ mediaTrackSettings?: Record;
+ audioInputDevices?: Array<{
+ deviceId: string;
+ groupId?: string;
+ label: string;
+ }>;
+ mediaRecorder?: {
+ mimeType?: string;
+ audioBitsPerSecond?: number;
+ timesliceMs?: number;
+ };
+ chunkEvents?: Array<{
+ index: number;
+ size: number;
+ elapsedMs: number;
+ deltaMs: number | null;
+ recordedElapsedMs?: number;
+ recordedDeltaMs?: number | null;
+ }>;
+ pauseIntervals?: Array<{
+ startElapsedMs: number;
+ endElapsedMs?: number;
+ durationMs?: number;
+ }>;
+ },
+ ) => Promise<{ success: boolean; path?: string; error?: string }>;
+ getRecordedVideoPath: () => Promise<{ success: boolean; path?: string; message?: string }>;
+ listAssetDirectory: (relativeDir: string) => Promise<{
+ success: boolean;
+ files?: string[];
+ error?: string;
+ }>;
+ readLocalFile: (
+ filePath: string,
+ ) => Promise<{ success: boolean; data?: Uint8Array; error?: string }>;
+ generateWallpaperThumbnail: (
+ filePath: string,
+ ) => Promise<{ success: boolean; data?: Uint8Array; error?: string }>;
+ probeNativeVideoMetadata: (filePath: string) => Promise<{
+ success: boolean;
+ metadata?: RendererNativeVideoMetadataProbe;
+ error?: string;
+ }>;
+ getNativeExportCapabilities: () => Promise<{
+ success: boolean;
+ capabilities?: RendererNativeExportCapabilities;
+ error?: string;
+ }>;
+ nativeStaticLayoutExport: (options: {
+ sessionId?: string;
+ inputPath: string;
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: "fast" | "balanced" | "quality";
+ durationSec: number;
+ contentWidth: number;
+ contentHeight: number;
+ offsetX: number;
+ offsetY: number;
+ sourceCropX?: number;
+ sourceCropY?: number;
+ sourceCropWidth?: number;
+ sourceCropHeight?: number;
+ backgroundColor: string;
+ backgroundImagePath?: string | null;
+ backgroundBlurPx?: number;
+ borderRadius?: number;
+ shadowIntensity?: number;
+ webcamInputPath?: string | null;
+ webcamLeft?: number;
+ webcamTop?: number;
+ webcamSize?: number;
+ webcamRadius?: number;
+ webcamShadowIntensity?: number;
+ webcamMirror?: boolean;
+ webcamTimeOffsetMs?: number;
+ cursorTelemetry?: Array<{
+ timeMs: number;
+ cx: number;
+ cy: number;
+ cursorTypeIndex?: number;
+ bounceScale?: number;
+ visible?: boolean;
+ }>;
+ cursorSize?: number;
+ cursorAtlasPngDataUrl?: string | null;
+ cursorAtlasEntries?: Array<{
+ index: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ anchorX: number;
+ anchorY: number;
+ aspectRatio: number;
+ }>;
+ zoomTelemetry?: Array<{ timeMs: number; scale: number; x: number; y: number }>;
+ timelineSegments?: Array<{
+ sourceStartMs: number;
+ sourceEndMs: number;
+ outputStartMs: number;
+ outputEndMs: number;
+ speed: number;
+ }>;
+ chunkDurationSec?: number;
+ experimentalWindowsGpuCompositor?: boolean;
+ experimentalNvidiaCudaExport?: boolean;
+ audioOptions?: {
+ audioMode?: "none" | "copy-source" | "trim-source" | "edited-track";
+ audioSourcePath?: string | null;
+ audioSourceCodec?: string | null;
+ audioSourceSampleRate?: number;
+ outputDurationSec?: number;
+ trimSegments?: Array<{ startMs: number; endMs: number }>;
+ editedTrackStrategy?: "filtergraph-fast-path" | "offline-render-fallback";
+ editedTrackSegments?: Array<{ startMs: number; endMs: number; speed: number }>;
+ editedAudioData?: ArrayBuffer;
+ editedAudioMimeType?: string | null;
+ };
+ }) => Promise<{
+ success: boolean;
+ tempPath?: string;
+ encoderName?: string;
+ error?: string;
+ metrics?: RendererNativeStaticLayoutMetrics;
+ }>;
+ nativeStaticLayoutExportCancel: (sessionId: string) => Promise<{
+ success: boolean;
+ }>;
+ onNativeStaticLayoutExportProgress: (
+ callback: (progress: RendererNativeStaticLayoutProgress) => void,
+ ) => () => void;
+ nativeVideoExportStart: (options: {
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: "fast" | "balanced" | "quality";
+ inputMode?: "rawvideo" | "h264-stream";
+ }) => Promise<{
+ success: boolean;
+ sessionId?: string;
+ encoderName?: string;
+ error?: string;
+ }>;
+ nativeVideoExportWriteFrame: (
+ sessionId: string,
+ frameData: Uint8Array,
+ ) => Promise<{ success: boolean; error?: string }>;
+ nativeVideoExportWriteFrames: (
+ sessionId: string,
+ frameDataList: Uint8Array[],
+ ) => Promise<{ success: boolean; error?: string }>;
+ nativeVideoExportFinish: (
+ sessionId: string,
+ options?: {
+ audioMode?: "none" | "copy-source" | "trim-source" | "edited-track";
+ audioSourcePath?: string | null;
+ audioSourceCodec?: string | null;
+ audioSourceSampleRate?: number;
+ outputDurationSec?: number;
+ trimSegments?: Array<{ startMs: number; endMs: number }>;
+ editedTrackStrategy?: "filtergraph-fast-path" | "offline-render-fallback";
+ editedTrackSegments?: Array<{ startMs: number; endMs: number; speed: number }>;
+ editedAudioData?: ArrayBuffer;
+ editedAudioMimeType?: string | null;
+ },
+ ) => Promise<{
+ success: boolean;
+ tempPath?: string;
+ encoderName?: string;
+ error?: string;
+ metrics?: RendererFfmpegAudioMuxMetrics;
+ }>;
+ nativeVideoExportCancel: (
+ sessionId: string,
+ ) => Promise<{ success: boolean; error?: string }>;
+ muxExportedVideoAudio: (
+ videoData: ArrayBuffer,
+ options?: {
+ audioMode?: "none" | "copy-source" | "trim-source" | "edited-track";
+ audioSourcePath?: string | null;
+ audioSourceCodec?: string | null;
+ audioSourceSampleRate?: number;
+ outputDurationSec?: number;
+ trimSegments?: Array<{ startMs: number; endMs: number }>;
+ editedTrackStrategy?: "filtergraph-fast-path" | "offline-render-fallback";
+ editedTrackSegments?: Array<{ startMs: number; endMs: number; speed: number }>;
+ editedAudioData?: ArrayBuffer;
+ editedAudioMimeType?: string | null;
+ },
+ ) => Promise<{
+ success: boolean;
+ tempPath?: string;
+ error?: string;
+ metrics?: RendererFfmpegAudioMuxMetrics;
+ }>;
+ muxExportedVideoAudioFromPath: (
+ videoPath: string,
+ options?: {
+ audioMode?: "none" | "copy-source" | "trim-source" | "edited-track";
+ audioSourcePath?: string | null;
+ audioSourceCodec?: string | null;
+ audioSourceSampleRate?: number;
+ outputDurationSec?: number;
+ trimSegments?: Array<{ startMs: number; endMs: number }>;
+ editedTrackStrategy?: "filtergraph-fast-path" | "offline-render-fallback";
+ editedTrackSegments?: Array<{ startMs: number; endMs: number; speed: number }>;
+ editedAudioData?: ArrayBuffer;
+ editedAudioMimeType?: string | null;
+ },
+ ) => Promise<{
+ success: boolean;
+ tempPath?: string;
+ error?: string;
+ metrics?: RendererFfmpegAudioMuxMetrics;
+ }>;
+ openExportStream: (options?: { extension?: string }) => Promise<{
+ success: boolean;
+ streamId?: string;
+ tempPath?: string;
+ error?: string;
+ }>;
+ writeExportStreamChunk: (
+ streamId: string,
+ position: number,
+ chunk: Uint8Array,
+ ) => Promise<{ success: boolean; error?: string }>;
+ closeExportStream: (
+ streamId: string,
+ options?: { abort?: boolean },
+ ) => Promise<{
+ success: boolean;
+ tempPath?: string;
+ bytesWritten?: number;
+ error?: string;
+ }>;
+ finalizeExportedVideo: (payload: {
+ tempPath: string;
+ fileName: string;
+ outputPath?: string | null;
+ captionSidecar?: {
+ format: "srt" | "vtt" | "both";
+ cues: Array<{
+ startMs: number;
+ endMs: number;
+ text: string;
+ }>;
+ };
+ }) => Promise<{
+ success: boolean;
+ path?: string;
+ canceled?: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ discardExportedTemp: (tempPath: string) => Promise<{ success: boolean; error?: string }>;
+ getVideoAudioFallbackPaths: (videoPath: string) => Promise<{
+ success: boolean;
+ paths: string[];
+ startDelayMsByPath?: Record;
+ error?: string;
+ }>;
+ setRecordingState: (recording: boolean) => Promise;
+ getCursorTelemetry: (videoPath?: string) => Promise<{
+ success: boolean;
+ samples: CursorTelemetryPoint[];
+ message?: string;
+ error?: string;
+ }>;
+ setCursorTelemetry: (
+ videoPath: string | undefined,
+ samples: CursorTelemetryPoint[],
+ ) => Promise<{
+ success: boolean;
+ samples: CursorTelemetryPoint[];
+ message?: string;
+ error?: string;
+ }>;
+ getSystemCursorAssets: () => Promise<{
+ success: boolean;
+ cursors: Record;
+ error?: string;
+ }>;
+ onStopRecordingFromTray: (callback: () => void) => () => void;
+ onRecordingStateChanged: (
+ callback: (state: { recording: boolean; sourceName: string }) => void,
+ ) => () => void;
+ onRecordingSessionChanged: (
+ callback: (session: RendererRecordingSessionData | null) => void,
+ ) => () => void;
+ onRecordingInterrupted: (
+ callback: (state: { reason: string; message: string }) => void,
+ ) => () => void;
+ onCursorStateChanged: (
+ callback: (state: { cursorType: CursorTelemetryPoint["cursorType"] }) => void,
+ ) => () => void;
+ openExternalUrl: (url: string) => Promise<{ success: boolean; error?: string }>;
+ getAccessibilityPermissionStatus: () => Promise<{
+ success: boolean;
+ trusted: boolean;
+ prompted: boolean;
+ error?: string;
+ }>;
+ requestAccessibilityPermission: () => Promise<{
+ success: boolean;
+ trusted: boolean;
+ prompted: boolean;
+ error?: string;
+ }>;
+ getScreenRecordingPermissionStatus: () => Promise<{
+ success: boolean;
+ status: string;
+ error?: string;
+ }>;
+ openScreenRecordingPreferences: () => Promise<{ success: boolean; error?: string }>;
+ openAccessibilityPreferences: () => Promise<{ success: boolean; error?: string }>;
+ saveExportedVideo: (
+ videoData: ArrayBuffer,
+ fileName: string,
+ captionSidecar?: {
+ format: "srt" | "vtt" | "both";
+ cues: Array<{
+ startMs: number;
+ endMs: number;
+ text: string;
+ }>;
+ },
+ ) => Promise<{ success: boolean; path?: string; message?: string; canceled?: boolean }>;
+ writeExportedVideoToPath: (
+ videoData: ArrayBuffer,
+ outputPath: string,
+ captionSidecar?: {
+ format: "srt" | "vtt" | "both";
+ cues: Array<{
+ startMs: number;
+ endMs: number;
+ text: string;
+ }>;
+ },
+ ) => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ canceled?: boolean;
+ }>;
+ openVideoFilePicker: (options?: { includeProjects?: boolean }) => Promise<{
+ success: boolean;
+ kind?: "media" | "project";
+ path?: string;
+ project?: unknown;
+ extension?: string;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ openAudioFilePicker: () => Promise<{ success: boolean; path?: string; canceled?: boolean }>;
+ openWhisperExecutablePicker: () => Promise<{
+ success: boolean;
+ path?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ openWhisperModelPicker: () => Promise<{
+ success: boolean;
+ path?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ getWhisperSmallModelStatus: () => Promise<{
+ success: boolean;
+ exists: boolean;
+ path?: string | null;
+ error?: string;
+ }>;
+ downloadWhisperSmallModel: () => Promise<{
+ success: boolean;
+ path?: string;
+ alreadyDownloaded?: boolean;
+ error?: string;
+ }>;
+ deleteWhisperSmallModel: () => Promise<{ success: boolean; error?: string }>;
+ onWhisperSmallModelDownloadProgress: (
+ callback: (state: {
+ status: "idle" | "downloading" | "downloaded" | "error";
+ progress: number;
+ path?: string | null;
+ error?: string;
+ }) => void,
+ ) => () => void;
+ generateAutoCaptions: (options: {
+ videoPath: string;
+ whisperExecutablePath?: string;
+ whisperModelPath: string;
+ language?: string;
+ }) => Promise<{
+ success: boolean;
+ cues?: AutoCaptionCue[];
+ message?: string;
+ error?: string;
+ }>;
+ setCurrentVideoPath: (
+ path: string,
+ options?: {
+ preserveProjectPath?: boolean;
+ hideOverlayCursorByDefault?: boolean;
+ },
+ ) => Promise<{ success: boolean; webcamPath: string | null }>;
+ setCurrentRecordingSession: (
+ session: {
+ videoPath: string;
+ webcamPath?: string | null;
+ timeOffsetMs?: number;
+ hideOverlayCursorByDefault?: boolean;
+ },
+ options?: { preserveProjectPath?: boolean },
+ ) => Promise<{ success: boolean }>;
+ getCurrentRecordingSession: () => Promise<{
+ success: boolean;
+ session?: {
+ videoPath: string;
+ webcamPath?: string | null;
+ timeOffsetMs?: number;
+ hideOverlayCursorByDefault?: boolean;
+ };
+ }>;
+ getCurrentVideoPath: () => Promise<{ success: boolean; path?: string }>;
+ clearCurrentVideoPath: () => Promise<{ success: boolean }>;
+ deleteRecordingFile: (filePath: string) => Promise<{ success: boolean; error?: string }>;
+ getLocalMediaUrl: (
+ filePath: string,
+ ) => Promise<{ success: true; url: string } | { success: false }>;
+ saveProjectFile: (
+ projectData: unknown,
+ suggestedName?: string,
+ existingProjectPath?: string,
+ thumbnailDataUrl?: string | null,
+ ) => Promise<{
+ success: boolean;
+ path?: string;
+ projectId?: string;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ saveProjectFileNamed: (
+ projectData: unknown,
+ projectName: string,
+ thumbnailDataUrl?: string | null,
+ mode?: "rename" | "copy",
+ ) => Promise<{
+ success: boolean;
+ path?: string;
+ projectId?: string;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ loadProjectFile: () => Promise<{
+ success: boolean;
+ path?: string;
+ project?: unknown;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ loadCurrentProjectFile: () => Promise<{
+ success: boolean;
+ path?: string;
+ project?: unknown;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ getProjectsDirectory: () => Promise<{
+ success: boolean;
+ path?: string;
+ error?: string;
+ }>;
+ listProjectFiles: () => Promise<{
+ success: boolean;
+ projectsDir?: string | null;
+ entries: Array<{
+ path: string;
+ name: string;
+ updatedAt: number;
+ thumbnailPath: string | null;
+ isCurrent: boolean;
+ isInProjectsDirectory: boolean;
+ }>;
+ error?: string;
+ }>;
+ openProjectFileAtPath: (filePath: string) => Promise<{
+ success: boolean;
+ path?: string;
+ project?: unknown;
+ message?: string;
+ canceled?: boolean;
+ error?: string;
+ }>;
+ openProjectsDirectory: () => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ }>;
+ installDownloadedUpdate: () => Promise<{ success: boolean }>;
+ downloadAvailableUpdate: (
+ installAfterDownload?: boolean,
+ ) => Promise<{ success: boolean; message?: string }>;
+ deferDownloadedUpdate: (delayMs?: number) => Promise<{
+ success: boolean;
+ message?: string;
+ }>;
+ dismissUpdateToast: () => Promise<{ success: boolean }>;
+ skipUpdateVersion: () => Promise<{ success: boolean; message?: string }>;
+ getCurrentUpdateToastPayload: () => Promise;
+ getUpdateStatusSummary: () => Promise;
+ getExperimentalUpdatesEnabled: () => Promise;
+ setExperimentalUpdatesEnabled: (enabled: boolean) => Promise<{
+ success: boolean;
+ enabled: boolean;
+ error?: string;
+ }>;
+ previewUpdateToast: () => Promise<{ success: boolean }>;
+ checkForAppUpdates: () => Promise<{ success: boolean; logPath: string }>;
+ onUpdateToastStateChanged: (
+ callback: (payload: UpdateToastState | null) => void,
+ ) => () => void;
+ onUpdateReadyToast: (
+ callback: (payload: {
+ version: string;
+ detail: string;
+ delayMs: number;
+ isPreview?: boolean;
+ }) => void,
+ ) => () => void;
+ onMenuLoadProject: (callback: () => void) => () => void;
+ onMenuSaveProject: (callback: () => void) => () => void;
+ onMenuSaveProjectAs: (callback: () => void) => () => void;
+ getPlatform: () => Promise;
+ getLinuxWindowSystem: () => Promise<"wayland" | "x11" | null>;
+ revealInFolder: (
+ filePath: string,
+ ) => Promise<{ success: boolean; error?: string; message?: string }>;
+ openRecordingsFolder: () => Promise<{ success: boolean; error?: string; message?: string }>;
+ getRecordingsDirectory: () => Promise<{
+ success: boolean;
+ path: string;
+ isDefault: boolean;
+ error?: string;
+ }>;
+ chooseRecordingsDirectory: () => Promise<{
+ success: boolean;
+ canceled?: boolean;
+ path?: string;
+ isDefault?: boolean;
+ message?: string;
+ error?: string;
+ }>;
+ getShortcuts: () => Promise | null>;
+ saveShortcuts: (shortcuts: unknown) => Promise<{ success: boolean; error?: string }>;
+ getAppSetting: (key: string) => unknown;
+ setAppSetting: (key: string, value: unknown) => boolean;
+ setHasUnsavedChanges: (hasChanges: boolean) => void;
+ onRequestSaveBeforeClose: (callback: () => Promise) => () => void;
+ isNativeWindowsCaptureAvailable: () => Promise<{ available: boolean }>;
+ muxNativeWindowsRecording: (expectedDurationMs?: number) => Promise<{
+ success: boolean;
+ path?: string;
+ message?: string;
+ error?: string;
+ }>;
+ /** Returns the app version from package.json */
+ getAppVersion: () => Promise;
+ /** Returns the configured remote announcement feed, or null when unavailable. */
+ getAnnouncements: () => Promise;
+ /** Hide the OS cursor before browser capture starts. */
+ hideOsCursor: () => Promise<{ success: boolean }>;
+ /** Recording preferences (mic, system audio, webcam) */
+ getRecordingPreferences: () => Promise<{
+ success: boolean;
+ microphoneEnabled: boolean;
+ microphoneDeviceId?: string;
+ systemAudioEnabled: boolean;
+ webcamEnabled: boolean;
+ webcamDeviceId?: string;
+ }>;
+ getRecordingAudioLabConfig: () => Promise<{
+ browserMicrophoneProfile: string;
+ requestedBrowserMicrophoneProfile: string | null;
+ }>;
+ setRecordingPreferences: (prefs: {
+ microphoneEnabled?: boolean;
+ microphoneDeviceId?: string;
+ systemAudioEnabled?: boolean;
+ webcamEnabled?: boolean;
+ webcamDeviceId?: string;
+ }) => Promise<{ success: boolean; error?: string }>;
+ /** Countdown timer before recording */
+ getCountdownDelay: () => Promise<{ success: boolean; delay: number }>;
+ setCountdownDelay: (delay: number) => Promise<{ success: boolean; error?: string }>;
+ startCountdown: (seconds: number) => Promise<{ success: boolean; cancelled?: boolean }>;
+ cancelCountdown: () => Promise<{ success: boolean }>;
+ getActiveCountdown: () => Promise<{ success: boolean; seconds: number | null }>;
+ onCountdownTick: (callback: (seconds: number) => void) => () => void;
+ };
+}
+
+interface ProcessedDesktopSource {
+ id: string;
+ name: string;
+ display_id: string;
+ thumbnail: string | null;
+ appIcon: string | null;
+ originalName?: string;
+ sourceType?: "screen" | "window";
+ appName?: string;
+ windowTitle?: string;
+}
+
+interface CursorTelemetryPoint {
+ timeMs: number;
+ cx: number;
+ cy: number;
+ pressure?: number;
+ interactionType?:
+ | "move"
+ | "click"
+ | "double-click"
+ | "right-click"
+ | "middle-click"
+ | "mouseup";
+ cursorType?:
+ | "arrow"
+ | "text"
+ | "pointer"
+ | "crosshair"
+ | "open-hand"
+ | "closed-hand"
+ | "resize-ew"
+ | "resize-ns"
+ | "not-allowed";
+}
+
+interface SystemCursorAsset {
+ dataUrl: string;
+ hotspotX: number;
+ hotspotY: number;
+ width: number;
+ height: number;
+}
+
+interface AutoCaptionCue {
+ id: string;
+ startMs: number;
+ endMs: number;
+ text: string;
+ words?: Array<{
+ text: string;
+ startMs: number;
+ endMs: number;
+ leadingSpace?: boolean;
+ }>;
+}
diff --git a/electron/gpuSwitches.test.ts b/electron/gpuSwitches.test.ts
new file mode 100644
index 000000000..4cbb1cdf4
--- /dev/null
+++ b/electron/gpuSwitches.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { getGpuSwitches, shouldForceLinuxEgl } from "./gpuSwitches";
+
+describe("shouldForceLinuxEgl", () => {
+ it("does not force EGL in a Wayland session", () => {
+ expect(
+ shouldForceLinuxEgl({
+ XDG_SESSION_TYPE: "wayland",
+ WAYLAND_DISPLAY: "wayland-0",
+ }),
+ ).toBe(false);
+ });
+
+ it("does not force EGL when Wayland is explicitly requested via Ozone", () => {
+ expect(
+ shouldForceLinuxEgl({
+ OZONE_PLATFORM: "wayland",
+ XDG_SESSION_TYPE: "x11",
+ }),
+ ).toBe(false);
+ });
+
+ it("falls back to Electron's ozone hint when OZONE_PLATFORM is invalid", () => {
+ expect(
+ shouldForceLinuxEgl({
+ OZONE_PLATFORM: "auto",
+ ELECTRON_OZONE_PLATFORM_HINT: "wayland",
+ XDG_SESSION_TYPE: "x11",
+ }),
+ ).toBe(false);
+ });
+
+ it("forces EGL in an X11 session", () => {
+ expect(shouldForceLinuxEgl({ XDG_SESSION_TYPE: "x11" })).toBe(true);
+ });
+
+ it("forces EGL when x11 is explicitly requested via Electron's ozone hint", () => {
+ expect(
+ shouldForceLinuxEgl({
+ ELECTRON_OZONE_PLATFORM_HINT: "x11",
+ WAYLAND_DISPLAY: "wayland-0",
+ }),
+ ).toBe(true);
+ });
+});
+
+describe("getGpuSwitches", () => {
+ it("returns the Linux VAAPI workaround without forcing EGL on Wayland", () => {
+ expect(
+ getGpuSwitches("linux", {
+ XDG_SESSION_TYPE: "wayland",
+ WAYLAND_DISPLAY: "wayland-0",
+ }),
+ ).toEqual({
+ useGl: undefined,
+ disableFeatures: ["VaapiVideoDecoder", "VaapiVideoEncoder"],
+ });
+ });
+
+ it("returns the X11 EGL workaround on Linux X11", () => {
+ expect(getGpuSwitches("linux", { XDG_SESSION_TYPE: "x11" })).toEqual({
+ useGl: "egl",
+ disableFeatures: ["VaapiVideoDecoder", "VaapiVideoEncoder"],
+ });
+ });
+});
diff --git a/electron/gpuSwitches.ts b/electron/gpuSwitches.ts
new file mode 100644
index 000000000..7b7c81ee8
--- /dev/null
+++ b/electron/gpuSwitches.ts
@@ -0,0 +1,66 @@
+export interface GpuSwitches {
+ useAngle?: string;
+ useGl?: string;
+ disableFeatures?: string[];
+}
+
+function normalizeLinuxWindowSystem(value: string | undefined): "wayland" | "x11" | null {
+ const normalized = value?.trim().toLowerCase();
+ if (normalized === "wayland" || normalized === "x11") {
+ return normalized;
+ }
+
+ return null;
+}
+
+function getForcedLinuxWindowSystem(env: NodeJS.ProcessEnv): "wayland" | "x11" | null {
+ return (
+ normalizeLinuxWindowSystem(env.OZONE_PLATFORM) ??
+ normalizeLinuxWindowSystem(env.ELECTRON_OZONE_PLATFORM_HINT)
+ );
+}
+
+export function shouldForceLinuxEgl(env: NodeJS.ProcessEnv): boolean {
+ const forcedWindowSystem = getForcedLinuxWindowSystem(env);
+ if (forcedWindowSystem === "wayland") {
+ return false;
+ }
+ if (forcedWindowSystem === "x11") {
+ return true;
+ }
+
+ const sessionType = env.XDG_SESSION_TYPE?.toLowerCase();
+ if (sessionType === "wayland") {
+ return false;
+ }
+ if (sessionType === "x11") {
+ return true;
+ }
+
+ return !env.WAYLAND_DISPLAY;
+}
+
+export function getGpuSwitches(
+ platform: NodeJS.Platform,
+ env: NodeJS.ProcessEnv = process.env,
+): GpuSwitches {
+ if (platform === "darwin") {
+ return {
+ useAngle: "metal",
+ disableFeatures: ["MacCatapLoopbackAudioForScreenShare"],
+ };
+ }
+
+ if (platform === "win32") {
+ return { useAngle: "d3d11" };
+ }
+
+ if (platform === "linux") {
+ return {
+ useGl: shouldForceLinuxEgl(env) ? "egl" : undefined,
+ disableFeatures: ["VaapiVideoDecoder", "VaapiVideoEncoder"],
+ };
+ }
+
+ return {};
+}
diff --git a/electron/hudOverlayBounds.test.ts b/electron/hudOverlayBounds.test.ts
new file mode 100644
index 000000000..db21e92bd
--- /dev/null
+++ b/electron/hudOverlayBounds.test.ts
@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ getHudOverlayWindowBounds,
+ resizeHudOverlayFallbackBounds,
+ shouldExpandHudOverlayFallback,
+} from "./hudOverlayBounds";
+
+describe("getHudOverlayWindowBounds", () => {
+ const workArea = {
+ x: 120,
+ y: 40,
+ width: 1920,
+ height: 1040,
+ };
+
+ it("uses the full work area when mouse passthrough is supported", () => {
+ expect(getHudOverlayWindowBounds(workArea, true)).toEqual(workArea);
+ });
+
+ it("uses a bottom-centered compact fallback when mouse passthrough is unavailable", () => {
+ expect(getHudOverlayWindowBounds(workArea, false)).toEqual({
+ x: 650,
+ y: 920,
+ width: 860,
+ height: 160,
+ });
+ });
+
+ it("expands the non-passthrough fallback for HUD menus and hover interaction", () => {
+ expect(getHudOverlayWindowBounds(workArea, false, true)).toEqual({
+ x: 650,
+ y: 540,
+ width: 860,
+ height: 540,
+ });
+ });
+
+ it("keeps the compact fallback inside small displays", () => {
+ expect(
+ getHudOverlayWindowBounds(
+ {
+ x: -100,
+ y: 20,
+ width: 640,
+ height: 420,
+ },
+ false,
+ ),
+ ).toEqual({
+ x: -100,
+ y: 280,
+ width: 640,
+ height: 160,
+ });
+ });
+
+ it("fits the expanded fallback inside small displays", () => {
+ expect(
+ getHudOverlayWindowBounds(
+ {
+ x: -100,
+ y: 20,
+ width: 640,
+ height: 420,
+ },
+ false,
+ true,
+ ),
+ ).toEqual({
+ x: -100,
+ y: 20,
+ width: 640,
+ height: 420,
+ });
+ });
+});
+
+describe("resizeHudOverlayFallbackBounds", () => {
+ const workArea = {
+ x: 0,
+ y: 0,
+ width: 1920,
+ height: 1080,
+ };
+
+ it("preserves the dragged bottom edge when expanding", () => {
+ expect(
+ resizeHudOverlayFallbackBounds(
+ workArea,
+ {
+ x: 420,
+ y: 700,
+ width: 860,
+ height: 160,
+ },
+ true,
+ ),
+ ).toEqual({
+ x: 420,
+ y: 320,
+ width: 860,
+ height: 540,
+ });
+ });
+
+ it("preserves the dragged bottom edge when compacting", () => {
+ expect(
+ resizeHudOverlayFallbackBounds(
+ workArea,
+ {
+ x: 420,
+ y: 320,
+ width: 860,
+ height: 540,
+ },
+ false,
+ ),
+ ).toEqual({
+ x: 420,
+ y: 700,
+ width: 860,
+ height: 160,
+ });
+ });
+
+ it("keeps resized fallback bounds inside the display work area", () => {
+ expect(
+ resizeHudOverlayFallbackBounds(
+ workArea,
+ {
+ x: 1500,
+ y: 900,
+ width: 860,
+ height: 160,
+ },
+ true,
+ ),
+ ).toEqual({
+ x: 1060,
+ y: 520,
+ width: 860,
+ height: 540,
+ });
+ });
+});
+
+describe("shouldExpandHudOverlayFallback", () => {
+ it("expands while recording only when the floating webcam preview is visible", () => {
+ expect(
+ shouldExpandHudOverlayFallback({
+ fallbackExpanded: false,
+ recordingActive: true,
+ webcamPreviewVisible: true,
+ }),
+ ).toBe(true);
+ });
+
+ it("keeps the compact recording fallback when there is no webcam preview", () => {
+ expect(
+ shouldExpandHudOverlayFallback({
+ fallbackExpanded: false,
+ recordingActive: true,
+ webcamPreviewVisible: false,
+ }),
+ ).toBe(false);
+ });
+
+ it("preserves manual fallback expansion outside recording", () => {
+ expect(
+ shouldExpandHudOverlayFallback({
+ fallbackExpanded: true,
+ recordingActive: false,
+ webcamPreviewVisible: false,
+ }),
+ ).toBe(true);
+ });
+
+ it("does not expand for webcam visibility outside recording", () => {
+ expect(
+ shouldExpandHudOverlayFallback({
+ fallbackExpanded: false,
+ recordingActive: false,
+ webcamPreviewVisible: true,
+ }),
+ ).toBe(false);
+ });
+});
diff --git a/electron/hudOverlayBounds.ts b/electron/hudOverlayBounds.ts
new file mode 100644
index 000000000..8c51b88c7
--- /dev/null
+++ b/electron/hudOverlayBounds.ts
@@ -0,0 +1,67 @@
+export interface HudOverlayWorkArea {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+const NON_PASSTHROUGH_HUD_WIDTH_DIP = 860;
+const NON_PASSTHROUGH_HUD_COMPACT_HEIGHT_DIP = 160;
+const NON_PASSTHROUGH_HUD_EXPANDED_HEIGHT_DIP = 540;
+
+function clamp(value: number, min: number, max: number): number {
+ return Math.min(Math.max(value, min), max);
+}
+
+export function getHudOverlayWindowBounds(
+ workArea: HudOverlayWorkArea,
+ mousePassthroughSupported: boolean,
+ fallbackExpanded = false,
+): HudOverlayWorkArea {
+ if (mousePassthroughSupported) {
+ return { ...workArea };
+ }
+
+ const width = Math.min(workArea.width, NON_PASSTHROUGH_HUD_WIDTH_DIP);
+ const height = Math.min(
+ workArea.height,
+ fallbackExpanded
+ ? NON_PASSTHROUGH_HUD_EXPANDED_HEIGHT_DIP
+ : NON_PASSTHROUGH_HUD_COMPACT_HEIGHT_DIP,
+ );
+
+ return {
+ x: Math.round(workArea.x + (workArea.width - width) / 2),
+ y: Math.round(workArea.y + workArea.height - height),
+ width,
+ height,
+ };
+}
+
+export function shouldExpandHudOverlayFallback({
+ fallbackExpanded,
+ recordingActive,
+ webcamPreviewVisible,
+}: {
+ fallbackExpanded: boolean;
+ recordingActive: boolean;
+ webcamPreviewVisible: boolean;
+}): boolean {
+ return fallbackExpanded || (recordingActive && webcamPreviewVisible);
+}
+
+export function resizeHudOverlayFallbackBounds(
+ workArea: HudOverlayWorkArea,
+ currentBounds: HudOverlayWorkArea,
+ fallbackExpanded: boolean,
+): HudOverlayWorkArea {
+ const nextBounds = getHudOverlayWindowBounds(workArea, false, fallbackExpanded);
+ const maxX = workArea.x + workArea.width - nextBounds.width;
+ const maxY = workArea.y + workArea.height - nextBounds.height;
+
+ return {
+ ...nextBounds,
+ x: clamp(currentBounds.x, workArea.x, maxX),
+ y: clamp(currentBounds.y + currentBounds.height - nextBounds.height, workArea.y, maxY),
+ };
+}
diff --git a/electron/hudOverlayWindowOptions.test.ts b/electron/hudOverlayWindowOptions.test.ts
new file mode 100644
index 000000000..08f8c6531
--- /dev/null
+++ b/electron/hudOverlayWindowOptions.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { getHudOverlayTaskbarOptions } from "./hudOverlayWindowOptions";
+
+describe("getHudOverlayTaskbarOptions", () => {
+ it("keeps a focusable HUD in the Windows taskbar", () => {
+ expect(getHudOverlayTaskbarOptions("win32")).toEqual({
+ skipTaskbar: false,
+ focusable: true,
+ });
+ });
+
+ it.each([
+ "darwin",
+ "linux",
+ ] as const)("keeps the HUD non-focusable and out of the taskbar on %s", (platform) => {
+ expect(getHudOverlayTaskbarOptions(platform)).toEqual({
+ skipTaskbar: true,
+ focusable: false,
+ });
+ });
+});
diff --git a/electron/hudOverlayWindowOptions.ts b/electron/hudOverlayWindowOptions.ts
new file mode 100644
index 000000000..27fcd2dea
--- /dev/null
+++ b/electron/hudOverlayWindowOptions.ts
@@ -0,0 +1,12 @@
+export interface HudOverlayTaskbarOptions {
+ skipTaskbar: boolean;
+ focusable: boolean;
+}
+
+export function getHudOverlayTaskbarOptions(platform: NodeJS.Platform): HudOverlayTaskbarOptions {
+ const showInWindowsTaskbar = platform === "win32";
+ return {
+ skipTaskbar: !showInWindowsTaskbar,
+ focusable: showInWindowsTaskbar,
+ };
+}
diff --git a/electron/ipc/captions/audioCandidates.test.ts b/electron/ipc/captions/audioCandidates.test.ts
new file mode 100644
index 000000000..c08b49ff1
--- /dev/null
+++ b/electron/ipc/captions/audioCandidates.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { getCaptionCompanionAudioCandidates } from "./audioCandidates";
+
+describe("getCaptionCompanionAudioCandidates", () => {
+ it("prefers microphone audio and includes system audio when both sidecars exist", () => {
+ expect(
+ getCaptionCompanionAudioCandidates([
+ {
+ platform: "win",
+ micPath: "recording.mic.wav",
+ systemPath: "recording.system.wav",
+ usablePaths: ["recording.system.wav", "recording.mic.wav"],
+ },
+ ]),
+ ).toEqual([
+ { path: "recording.mic.wav", label: "microphone audio sidecar" },
+ { path: "recording.system.wav", label: "system audio sidecar" },
+ ]);
+ });
+
+ it("omits companion paths that were not found on disk", () => {
+ expect(
+ getCaptionCompanionAudioCandidates([
+ {
+ platform: "win",
+ micPath: "recording.mic.wav",
+ systemPath: "recording.system.wav",
+ usablePaths: ["recording.mic.wav"],
+ },
+ ]),
+ ).toEqual([{ path: "recording.mic.wav", label: "microphone audio sidecar" }]);
+ });
+});
diff --git a/electron/ipc/captions/audioCandidates.ts b/electron/ipc/captions/audioCandidates.ts
new file mode 100644
index 000000000..33e62d2e1
--- /dev/null
+++ b/electron/ipc/captions/audioCandidates.ts
@@ -0,0 +1,21 @@
+import type { CompanionAudioCandidate } from "../types";
+
+export type CaptionAudioCandidate = {
+ path: string;
+ label: string;
+};
+
+export function getCaptionCompanionAudioCandidates(
+ companions: CompanionAudioCandidate[],
+): CaptionAudioCandidate[] {
+ return companions.flatMap((companion) => {
+ const candidates: CaptionAudioCandidate[] = [];
+ if (companion.usablePaths.includes(companion.micPath)) {
+ candidates.push({ path: companion.micPath, label: "microphone audio sidecar" });
+ }
+ if (companion.usablePaths.includes(companion.systemPath)) {
+ candidates.push({ path: companion.systemPath, label: "system audio sidecar" });
+ }
+ return candidates;
+ });
+}
diff --git a/electron/ipc/captions/generate.test.ts b/electron/ipc/captions/generate.test.ts
new file mode 100644
index 000000000..9844fecc8
--- /dev/null
+++ b/electron/ipc/captions/generate.test.ts
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { isMissingWindowsWhisperRuntimeDependency } from "./runtimeErrors";
+
+describe("isMissingWindowsWhisperRuntimeDependency", () => {
+ it("recognizes the signed and unsigned STATUS_DLL_NOT_FOUND exit codes on Windows", () => {
+ if (process.platform !== "win32") return;
+
+ expect(isMissingWindowsWhisperRuntimeDependency({ code: -1073741515 })).toBe(true);
+ expect(isMissingWindowsWhisperRuntimeDependency({ code: 3221225781 })).toBe(true);
+ });
+
+ it("does not classify ordinary Whisper failures as missing runtimes", () => {
+ expect(isMissingWindowsWhisperRuntimeDependency({ code: 1 })).toBe(false);
+ expect(isMissingWindowsWhisperRuntimeDependency(new Error("bad model"))).toBe(false);
+ });
+});
diff --git a/electron/ipc/captions/generate.ts b/electron/ipc/captions/generate.ts
new file mode 100644
index 000000000..246c4f1aa
--- /dev/null
+++ b/electron/ipc/captions/generate.ts
@@ -0,0 +1,323 @@
+import { execFile, spawnSync } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { app } from "electron";
+import { getFfmpegBinaryPath } from "../ffmpeg/binary";
+import { getBundledWhisperExecutableCandidates } from "../paths/binaries";
+import { resolveRecordingSession } from "../project/session";
+import { getUsableCompanionAudioCandidates } from "../recording/diagnostics";
+import { normalizeVideoSourcePath } from "../utils";
+import { getCaptionCompanionAudioCandidates } from "./audioCandidates";
+import { parseSrtCues, parseWhisperJsonCues, shouldRetryWhisperWithoutJson } from "./parser";
+import { isMissingWindowsWhisperRuntimeDependency } from "./runtimeErrors";
+import { segmentCuesIntoPhrases } from "./segment";
+import {
+ parseSilenceIntervals,
+ SILENCE_DETECT_MIN_S,
+ SILENCE_NOISE_DB,
+ type SilenceInterval,
+} from "./silence";
+
+const execFileAsync = promisify(execFile);
+
+async function executeWhisper(whisperExecutablePath: string, args: string[]) {
+ try {
+ await execFileAsync(whisperExecutablePath, args, {
+ timeout: 30 * 60 * 1000,
+ maxBuffer: 20 * 1024 * 1024,
+ });
+ } catch (error) {
+ if (isMissingWindowsWhisperRuntimeDependency(error)) {
+ throw new Error(
+ "Whisper could not start because the Microsoft Visual C++ x64 Redistributable is missing. Install it from https://aka.ms/vc14/vc_redist.x64.exe, then restart Recordly.",
+ );
+ }
+ throw error;
+ }
+}
+
+export async function ensureReadableFile(filePath: string, options?: { executable?: boolean }) {
+ await fs.access(filePath, fsConstants.R_OK);
+ if (options?.executable) {
+ try {
+ await fs.access(filePath, fsConstants.X_OK);
+ } catch {
+ throw new Error("The selected Whisper executable is not marked as executable.");
+ }
+ }
+}
+
+export async function isExecutableFile(filePath: string) {
+ try {
+ await fs.access(filePath, fsConstants.R_OK | fsConstants.X_OK);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export async function resolveWhisperExecutablePath(preferredPath?: string | null) {
+ const candidatePaths = [
+ preferredPath?.trim() || null,
+ ...getBundledWhisperExecutableCandidates(),
+ process.env["WHISPER_CPP_PATH"]?.trim() || null,
+ process.platform === "darwin" ? "/opt/homebrew/bin/whisper-cli" : null,
+ process.platform === "darwin" ? "/usr/local/bin/whisper-cli" : null,
+ process.platform === "darwin" ? "/opt/homebrew/bin/whisper-cpp" : null,
+ process.platform === "darwin" ? "/usr/local/bin/whisper-cpp" : null,
+ ].filter((value): value is string => Boolean(value));
+
+ for (const candidate of candidatePaths) {
+ const normalized = path.resolve(candidate);
+ if (await isExecutableFile(normalized)) {
+ return normalized;
+ }
+ }
+
+ const pathCommand = process.platform === "win32" ? "where" : "which";
+ const binaryNames =
+ process.platform === "win32"
+ ? ["whisper-cli.exe", "whisper.exe", "main.exe"]
+ : ["whisper-cli", "whisper-cpp", "whisper", "main"];
+
+ for (const binaryName of binaryNames) {
+ const result = spawnSync(pathCommand, [binaryName], { encoding: "utf-8" });
+ if (result.status === 0) {
+ const resolvedPath = result.stdout
+ .split(/\r?\n/)
+ .map((line) => line.trim())
+ .find(Boolean);
+
+ if (resolvedPath && (await isExecutableFile(resolvedPath))) {
+ return resolvedPath;
+ }
+ }
+ }
+
+ throw new Error(
+ `No Whisper runtime was found for ${process.platform}/${process.arch}. ` +
+ "This Recordly build is missing its bundled caption runtime. Reinstall or update Recordly, or select a whisper-cli executable in Caption settings.",
+ );
+}
+
+export async function resolveCaptionAudioCandidates(videoPath: string) {
+ const candidates: Array<{ path: string; label: string }> = [];
+ const seenPaths = new Set();
+
+ const pushCandidate = (candidatePath: string | null | undefined, label: string) => {
+ const normalizedCandidatePath = normalizeVideoSourcePath(candidatePath);
+ if (!normalizedCandidatePath || seenPaths.has(normalizedCandidatePath)) {
+ return;
+ }
+
+ seenPaths.add(normalizedCandidatePath);
+ candidates.push({ path: normalizedCandidatePath, label });
+ };
+
+ pushCandidate(videoPath, "recording");
+ const companionAudio = await getUsableCompanionAudioCandidates(videoPath);
+ for (const candidate of getCaptionCompanionAudioCandidates(companionAudio)) {
+ pushCandidate(candidate.path, candidate.label);
+ }
+
+ const requestedRecordingSession = await resolveRecordingSession(videoPath);
+ pushCandidate(requestedRecordingSession?.webcamPath, "linked webcam recording");
+
+ return candidates;
+}
+
+export async function extractCaptionAudioSource(options: {
+ videoPath: string;
+ ffmpegPath: string;
+ wavPath: string;
+}) {
+ const candidates = await resolveCaptionAudioCandidates(options.videoPath);
+ const attemptedCandidates: Array<{
+ path: string;
+ label: string;
+ readable: boolean;
+ extractedAudio: boolean;
+ error?: string;
+ }> = [];
+
+ for (const candidate of candidates) {
+ try {
+ await ensureReadableFile(candidate.path);
+ await execFileAsync(
+ options.ffmpegPath,
+ [
+ "-y",
+ "-i",
+ candidate.path,
+ "-map",
+ "0:a:0",
+ "-vn",
+ "-ac",
+ "1",
+ "-ar",
+ "16000",
+ "-c:a",
+ "pcm_s16le",
+ options.wavPath,
+ ],
+ { timeout: 5 * 60 * 1000, maxBuffer: 20 * 1024 * 1024 },
+ );
+ attemptedCandidates.push({ ...candidate, readable: true, extractedAudio: true });
+ return candidate;
+ } catch (error) {
+ attemptedCandidates.push({
+ ...candidate,
+ readable: true,
+ extractedAudio: false,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ }
+ }
+
+ console.warn(
+ "[auto-captions] No audio source candidate could be extracted:",
+ attemptedCandidates,
+ );
+
+ throw new Error(
+ "No audio was found to transcribe in the saved recording file. Captions need an audio track. If this recording should have contained sound, the recording was saved without an audio stream.",
+ );
+}
+
+export async function detectSilenceIntervals(options: {
+ ffmpegPath: string;
+ wavPath: string;
+}): Promise {
+ // ffmpeg writes silencedetect results to stderr; the null muxer just runs the filter.
+ const { stderr } = await execFileAsync(
+ options.ffmpegPath,
+ [
+ "-hide_banner",
+ "-nostats",
+ "-i",
+ options.wavPath,
+ "-af",
+ `silencedetect=noise=${SILENCE_NOISE_DB}dB:d=${SILENCE_DETECT_MIN_S}`,
+ "-f",
+ "null",
+ "-",
+ ],
+ { timeout: 5 * 60 * 1000, maxBuffer: 20 * 1024 * 1024 },
+ );
+
+ return parseSilenceIntervals(stderr ?? "");
+}
+
+export async function generateAutoCaptionsFromVideo(options: {
+ videoPath: string;
+ whisperExecutablePath?: string;
+ whisperModelPath: string;
+ language?: string;
+}) {
+ const ffmpegPath = getFfmpegBinaryPath();
+ const normalizedVideoPath = normalizeVideoSourcePath(options.videoPath);
+ if (!normalizedVideoPath) {
+ throw new Error("Missing source video path.");
+ }
+
+ const whisperExecutablePath = await resolveWhisperExecutablePath(options.whisperExecutablePath);
+ const whisperModelPath = path.resolve(options.whisperModelPath);
+ await ensureReadableFile(whisperExecutablePath, { executable: true });
+ await ensureReadableFile(whisperModelPath);
+
+ const tempBase = path.join(
+ app.getPath("temp"),
+ `recordly-captions-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+ );
+ const wavPath = `${tempBase}.wav`;
+ const outputBase = `${tempBase}-whisper`;
+ const srtPath = `${outputBase}.srt`;
+ const jsonPath = `${outputBase}.json`;
+
+ try {
+ const audioSource = await extractCaptionAudioSource({
+ videoPath: normalizedVideoPath,
+ ffmpegPath,
+ wavPath,
+ });
+
+ const language =
+ options.language && options.language.trim() ? options.language.trim() : "auto";
+ const whisperBaseArgs = [
+ "-m",
+ whisperModelPath,
+ "-f",
+ wavPath,
+ "-osrt",
+ "-of",
+ outputBase,
+ "-l",
+ language,
+ "-np",
+ ];
+
+ let jsonEnabled = true;
+ try {
+ await executeWhisper(whisperExecutablePath, [...whisperBaseArgs, "-ojf"]);
+ } catch (error) {
+ if (!shouldRetryWhisperWithoutJson(error)) {
+ throw error;
+ }
+
+ jsonEnabled = false;
+ console.warn(
+ "[auto-captions] Whisper runtime does not support JSON full output, retrying with SRT only:",
+ error,
+ );
+ await executeWhisper(whisperExecutablePath, whisperBaseArgs);
+ }
+
+ const timedCues = jsonEnabled
+ ? parseWhisperJsonCues(await fs.readFile(jsonPath, "utf-8"))
+ : [];
+ if (jsonEnabled && timedCues.length === 0) {
+ // JSON ran but yielded no word-timed cues (empty/malformed output). We fall back
+ // to SRT, which has no word timings — captions are then split by sentence text and
+ // silence rather than precise word timing. Surface it for diagnosis.
+ console.warn(
+ "[auto-captions] Whisper JSON produced no word-timed cues; falling back to SRT (no word timings).",
+ );
+ }
+ const cues =
+ timedCues.length > 0 ? timedCues : parseSrtCues(await fs.readFile(srtPath, "utf-8"));
+ if (cues.length === 0) {
+ throw new Error("Whisper completed, but no caption cues were produced.");
+ }
+
+ // Whisper cues run sentences together and don't break on pauses. Re-segment them
+ // into one caption per sentence/phrase using Whisper's own word stream (punctuation
+ // + pauses), backed by ground-truth acoustic silence (ffmpeg `silencedetect`).
+ // Failure here must not block caption generation — fall back to raw.
+ let cuesToReturn = cues;
+ try {
+ const silences = await detectSilenceIntervals({ ffmpegPath, wavPath });
+ // An empty result is a valid resegmentation (e.g. every transcribed word fell
+ // inside a long detected silence and was dropped as a hallucination), so take it
+ // as-is. Only a thrown exception should fall back to the raw cues.
+ cuesToReturn = segmentCuesIntoPhrases(cues, silences);
+ } catch (error) {
+ console.warn(
+ "[auto-captions] Silence-aware re-segmentation failed, using raw cues:",
+ error,
+ );
+ }
+
+ return {
+ cues: cuesToReturn,
+ audioSourceLabel: audioSource.label,
+ };
+ } finally {
+ await Promise.allSettled([
+ fs.rm(wavPath, { force: true }),
+ fs.rm(srtPath, { force: true }),
+ fs.rm(jsonPath, { force: true }),
+ ]);
+ }
+}
diff --git a/electron/ipc/captions/parser.ts b/electron/ipc/captions/parser.ts
new file mode 100644
index 000000000..ff4c62ce6
--- /dev/null
+++ b/electron/ipc/captions/parser.ts
@@ -0,0 +1,183 @@
+import type {
+ CaptionCuePayload,
+ CaptionWordPayload,
+ WhisperJsonSegment,
+ WhisperJsonToken,
+} from "../types";
+
+function isFiniteNumber(value: unknown): value is number {
+ return typeof value === "number" && Number.isFinite(value);
+}
+
+export function buildCaptionTextFromWords(words: CaptionWordPayload[]): string {
+ return words
+ .map((word, index) => `${index > 0 && word.leadingSpace ? " " : ""}${word.text}`)
+ .join("")
+ .trim();
+}
+
+export function parseWhisperJsonWords(tokens: unknown): CaptionWordPayload[] {
+ if (!Array.isArray(tokens)) {
+ return [];
+ }
+
+ const words: CaptionWordPayload[] = [];
+ let nextLeadingSpace = false;
+
+ for (const token of tokens) {
+ if (!token || typeof token !== "object") {
+ continue;
+ }
+
+ const tokenData = token as WhisperJsonToken;
+ const tokenText = typeof tokenData.text === "string" ? tokenData.text : "";
+ if (!tokenText) {
+ continue;
+ }
+
+ const tokenStartMs = isFiniteNumber(tokenData.offsets?.from)
+ ? Math.round(tokenData.offsets.from)
+ : null;
+ const tokenEndMs = isFiniteNumber(tokenData.offsets?.to)
+ ? Math.round(tokenData.offsets.to)
+ : null;
+ const parts = tokenText.match(/\s+|[^\s]+/g) ?? [];
+
+ for (const part of parts) {
+ if (/^\s+$/.test(part)) {
+ nextLeadingSpace = words.length > 0;
+ continue;
+ }
+
+ if (tokenStartMs == null || tokenEndMs == null || tokenEndMs <= tokenStartMs) {
+ return [];
+ }
+
+ const previousWord = words.length > 0 ? words[words.length - 1] : null;
+ if (!previousWord || nextLeadingSpace) {
+ words.push({
+ text: part,
+ startMs: tokenStartMs,
+ endMs: tokenEndMs,
+ ...(words.length > 0 && nextLeadingSpace ? { leadingSpace: true } : {}),
+ });
+ } else {
+ previousWord.text += part;
+ previousWord.endMs = Math.max(previousWord.endMs, tokenEndMs);
+ }
+
+ nextLeadingSpace = false;
+ }
+ }
+
+ return words.filter((word) => word.text.trim().length > 0);
+}
+
+export function parseWhisperJsonCues(content: string): CaptionCuePayload[] {
+ try {
+ const parsed = JSON.parse(content) as {
+ transcription?: unknown;
+ };
+
+ if (!Array.isArray(parsed.transcription)) {
+ return [];
+ }
+
+ return parsed.transcription
+ .map((segment, index) => {
+ if (!segment || typeof segment !== "object") {
+ return null;
+ }
+
+ const segmentData = segment as WhisperJsonSegment;
+ const startMs = isFiniteNumber(segmentData.offsets?.from)
+ ? Math.round(segmentData.offsets.from)
+ : null;
+ const endMs = isFiniteNumber(segmentData.offsets?.to)
+ ? Math.round(segmentData.offsets.to)
+ : null;
+ const segmentText =
+ typeof segmentData.text === "string" ? segmentData.text.trim() : "";
+
+ if (startMs == null || endMs == null || endMs <= startMs) {
+ return null;
+ }
+
+ const words = parseWhisperJsonWords(segmentData.tokens);
+ const text = words.length > 0 ? buildCaptionTextFromWords(words) : segmentText;
+
+ if (!text) {
+ return null;
+ }
+
+ return {
+ id: `caption-${index + 1}`,
+ startMs,
+ endMs,
+ text,
+ ...(words.length > 0 ? { words } : {}),
+ };
+ })
+ .filter((cue): cue is CaptionCuePayload => cue != null);
+ } catch (error) {
+ console.warn("[auto-captions] Failed to parse Whisper JSON output:", error);
+ return [];
+ }
+}
+
+export function parseSrtTimestamp(value: string): number | null {
+ const match = value.trim().match(/^(\d{2}):(\d{2}):(\d{2}),(\d{3})$/);
+ if (!match) {
+ return null;
+ }
+
+ const [, hours, minutes, seconds, milliseconds] = match;
+ return (
+ Number(hours) * 60 * 60 * 1000 +
+ Number(minutes) * 60 * 1000 +
+ Number(seconds) * 1000 +
+ Number(milliseconds)
+ );
+}
+
+export function parseSrtCues(content: string): CaptionCuePayload[] {
+ return content
+ .split(/\r?\n\r?\n/)
+ .map((block, index) => {
+ const lines = block.split(/\r?\n/).map((line) => line.trim());
+ const timingLine = lines.find((line) => line.includes("-->"));
+ if (!timingLine) {
+ return null;
+ }
+
+ const [rawStart, rawEnd] = timingLine.split("-->").map((part) => part.trim());
+ const startMs = parseSrtTimestamp(rawStart);
+ const endMs = parseSrtTimestamp(rawEnd);
+ if (startMs == null || endMs == null || endMs <= startMs) {
+ return null;
+ }
+
+ const text = lines
+ .slice(lines.indexOf(timingLine) + 1)
+ .filter((line) => line.length > 0)
+ .join("\n")
+ .trim();
+
+ if (!text) {
+ return null;
+ }
+
+ return {
+ id: `caption-${index + 1}`,
+ startMs,
+ endMs,
+ text,
+ };
+ })
+ .filter((cue): cue is CaptionCuePayload => cue != null);
+}
+
+export function shouldRetryWhisperWithoutJson(error: unknown): boolean {
+ const message = error instanceof Error ? error.message : String(error);
+ return /unknown argument|output-json-full|output-json|ojf|\boj\b/i.test(message);
+}
diff --git a/electron/ipc/captions/runtimeErrors.ts b/electron/ipc/captions/runtimeErrors.ts
new file mode 100644
index 000000000..707848dd6
--- /dev/null
+++ b/electron/ipc/captions/runtimeErrors.ts
@@ -0,0 +1,10 @@
+const WINDOWS_MISSING_RUNTIME_EXIT_CODES = new Set([-1073741515, 3221225781]);
+
+export function isMissingWindowsWhisperRuntimeDependency(error: unknown) {
+ if (process.platform !== "win32" || !error || typeof error !== "object") {
+ return false;
+ }
+
+ const code = (error as { code?: unknown }).code;
+ return typeof code === "number" && WINDOWS_MISSING_RUNTIME_EXIT_CODES.has(code);
+}
diff --git a/electron/ipc/captions/segment.test.ts b/electron/ipc/captions/segment.test.ts
new file mode 100644
index 000000000..e6ebaf006
--- /dev/null
+++ b/electron/ipc/captions/segment.test.ts
@@ -0,0 +1,371 @@
+import { describe, expect, it } from "vitest";
+import type { CaptionCuePayload } from "../types";
+import { endsSentence, segmentCuesIntoPhrases } from "./segment";
+
+describe("endsSentence", () => {
+ it("detects terminal punctuation, ignoring trailing closers", () => {
+ expect(endsSentence("world.")).toBe(true);
+ expect(endsSentence("you?")).toBe(true);
+ expect(endsSentence("stop!")).toBe(true);
+ expect(endsSentence("wait…")).toBe(true);
+ expect(endsSentence('said."')).toBe(true);
+ expect(endsSentence("done,")).toBe(false);
+ expect(endsSentence("hello")).toBe(false);
+ });
+
+ it("does not treat common abbreviations or initialisms as a sentence end", () => {
+ expect(endsSentence("Mr.")).toBe(false);
+ expect(endsSentence("Dr.")).toBe(false);
+ expect(endsSentence("etc.")).toBe(false);
+ expect(endsSentence("e.g.")).toBe(false);
+ expect(endsSentence("U.S.")).toBe(false);
+ expect(endsSentence("J.")).toBe(false);
+ // real sentence ends are unaffected
+ expect(endsSentence("Smith.")).toBe(true);
+ expect(endsSentence("5.")).toBe(true);
+ // `?`/`!` after an abbreviation-like token still end the sentence
+ expect(endsSentence("really?")).toBe(true);
+ });
+});
+
+describe("segmentCuesIntoPhrases", () => {
+ it("splits back-to-back sentences with no pause into separate captions", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 1_800,
+ text: "Hello world. How are you?",
+ words: [
+ { text: "Hello", startMs: 0, endMs: 400 },
+ { text: "world.", startMs: 400, endMs: 800, leadingSpace: true },
+ { text: "How", startMs: 800, endMs: 1_100, leadingSpace: true },
+ { text: "are", startMs: 1_100, endMs: 1_400, leadingSpace: true },
+ { text: "you?", startMs: 1_400, endMs: 1_800, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("Hello world.");
+ expect(result[1].text).toBe("How are you?");
+ expect(result[0].endMs).toBeLessThanOrEqual(result[1].startMs);
+ });
+
+ it("does not leak the first word of the next sentence into the previous caption", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 1_800,
+ text: "Hello world. How are you?",
+ words: [
+ { text: "Hello", startMs: 0, endMs: 400 },
+ { text: "world.", startMs: 400, endMs: 800, leadingSpace: true },
+ { text: "How", startMs: 800, endMs: 1_100, leadingSpace: true },
+ { text: "are", startMs: 1_100, endMs: 1_400, leadingSpace: true },
+ { text: "you?", startMs: 1_400, endMs: 1_800, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result[1].words?.[0].text).toBe("How");
+ expect(result[1].words?.[0].startMs).toBe(800);
+ // the first word of a phrase has no leading space
+ expect(result[1].words?.[0].leadingSpace).toBeUndefined();
+ });
+
+ it("merges rapid-fire short sentences into one caption (word-timed)", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 800,
+ text: "Okay. Great.",
+ words: [
+ { text: "Okay.", startMs: 0, endMs: 400 },
+ { text: "Great.", startMs: 400, endMs: 800, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("Okay. Great.");
+ expect(result[0].words?.map((word) => word.text)).toEqual(["Okay.", "Great."]);
+ });
+
+ it("merges rapid-fire short sentences into one caption (word-less)", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 400, text: "Okay." },
+ { id: "caption-2", startMs: 400, endMs: 800, text: "Great." },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("Okay. Great.");
+ });
+
+ it("does not merge two short captions across a real pause just above the merge gap", () => {
+ // Two short, sentence-ended phrases separated by a 450ms gap (just above the 400ms
+ // mergeGapMs). Edge padding shrinks the apparent gap, so if merge eligibility ran on
+ // padded timings it would wrongly fuse them. Merge must run on the true speech gap.
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 1_250,
+ text: "Okay. Great.",
+ words: [
+ { text: "Okay.", startMs: 0, endMs: 400 },
+ { text: "Great.", startMs: 850, endMs: 1_250, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("Okay.");
+ expect(result[1].text).toBe("Great.");
+ // Padding still applies, but cues stay separate and non-overlapping.
+ expect(result[0].endMs).toBeLessThanOrEqual(result[1].startMs);
+ });
+
+ it("does not merge a short sentence into a full-length one", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 2_400,
+ text: "Okay. This is a full length sentence that should stand alone.",
+ words: [
+ { text: "Okay.", startMs: 0, endMs: 400 },
+ { text: "This", startMs: 400, endMs: 700, leadingSpace: true },
+ { text: "is", startMs: 700, endMs: 900, leadingSpace: true },
+ { text: "a", startMs: 900, endMs: 1_050, leadingSpace: true },
+ { text: "full", startMs: 1_050, endMs: 1_350, leadingSpace: true },
+ { text: "length", startMs: 1_350, endMs: 1_650, leadingSpace: true },
+ { text: "sentence", startMs: 1_650, endMs: 1_950, leadingSpace: true },
+ { text: "that", startMs: 1_950, endMs: 2_100, leadingSpace: true },
+ { text: "should", startMs: 2_100, endMs: 2_250, leadingSpace: true },
+ { text: "stand", startMs: 2_250, endMs: 2_350, leadingSpace: true },
+ { text: "alone.", startMs: 2_350, endMs: 2_400, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("Okay.");
+ expect(result[1].text).toBe("This is a full length sentence that should stand alone.");
+ });
+
+ it("keeps a comma/clause inside one caption", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 1_500,
+ text: "When I'm done, I start.",
+ words: [
+ { text: "When", startMs: 0, endMs: 300 },
+ { text: "I'm", startMs: 300, endMs: 600, leadingSpace: true },
+ { text: "done,", startMs: 600, endMs: 900, leadingSpace: true },
+ { text: "I", startMs: 900, endMs: 1_100, leadingSpace: true },
+ { text: "start.", startMs: 1_100, endMs: 1_500, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("When I'm done, I start.");
+ });
+
+ it("does not split on an abbreviation, only on the real sentence end", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 1_800,
+ text: "Hello Mr. Smith. How are you?",
+ words: [
+ { text: "Hello", startMs: 0, endMs: 300 },
+ { text: "Mr.", startMs: 300, endMs: 600, leadingSpace: true },
+ { text: "Smith.", startMs: 600, endMs: 900, leadingSpace: true },
+ { text: "How", startMs: 900, endMs: 1_200, leadingSpace: true },
+ { text: "are", startMs: 1_200, endMs: 1_500, leadingSpace: true },
+ { text: "you?", startMs: 1_500, endMs: 1_800, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("Hello Mr. Smith.");
+ expect(result[1].text).toBe("How are you?");
+ });
+
+ it("splits on a real pause even without punctuation", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 2_000,
+ text: "one two three four",
+ words: [
+ { text: "one", startMs: 0, endMs: 300 },
+ { text: "two", startMs: 300, endMs: 600, leadingSpace: true },
+ // 800ms gap (>= 700ms pause) -> phrase boundary
+ { text: "three", startMs: 1_400, endMs: 1_700, leadingSpace: true },
+ { text: "four", startMs: 1_700, endMs: 2_000, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("one two");
+ expect(result[1].text).toBe("three four");
+ });
+
+ it("splits on a long acoustic silence in a word gap even when the word gap is short", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 2_600,
+ text: "alpha beta",
+ words: [
+ { text: "alpha", startMs: 0, endMs: 600 },
+ { text: "beta", startMs: 2_200, endMs: 2_600, leadingSpace: true },
+ ],
+ },
+ ];
+ // pauseMs high so the word gap (1600ms) wouldn't split on its own; the 1500ms
+ // silence sitting in the gap is what forces the break. beta starts after the
+ // silence ends, so it is not dropped as a hallucination.
+ const result = segmentCuesIntoPhrases(cues, [{ startMs: 600, endMs: 2_100 }], {
+ pauseMs: 5_000,
+ });
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("alpha");
+ expect(result[1].text).toBe("beta");
+ });
+
+ it("does not split that same input when there is no silence and the gap is below the pause", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 2_600,
+ text: "alpha beta",
+ words: [
+ { text: "alpha", startMs: 0, endMs: 600 },
+ { text: "beta", startMs: 2_200, endMs: 2_600, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, [], { pauseMs: 5_000 });
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("alpha beta");
+ });
+
+ it("splits a runaway phrase with no punctuation and no pause via the safety cap", () => {
+ const words = Array.from({ length: 12 }, (_, index) => ({
+ text: `w${index}`,
+ startMs: index * 300,
+ endMs: index * 300 + 300,
+ ...(index > 0 ? { leadingSpace: true } : {}),
+ }));
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 3_600,
+ text: words.map((w) => w.text).join(" "),
+ words,
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, [], { maxPhraseMs: 2_000 });
+ expect(result.length).toBeGreaterThan(1);
+ expect(result.map((cue) => cue.text).join(" ")).toBe(words.map((w) => w.text).join(" "));
+ });
+
+ it("drops words that fall entirely inside a long silence (hallucination)", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 5_000,
+ endMs: 6_000,
+ text: "Thank you.",
+ words: [
+ { text: "Thank", startMs: 5_000, endMs: 5_500 },
+ { text: "you.", startMs: 5_500, endMs: 6_000, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, [{ startMs: 4_000, endMs: 9_000 }]);
+ expect(result).toHaveLength(0);
+ });
+
+ it("produces sorted, non-overlapping cues with sequential ids", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 2_400,
+ text: "First phrase here. Second phrase here. Third one.",
+ words: [
+ { text: "First", startMs: 0, endMs: 300 },
+ { text: "phrase", startMs: 300, endMs: 600, leadingSpace: true },
+ { text: "here.", startMs: 600, endMs: 900, leadingSpace: true },
+ { text: "Second", startMs: 900, endMs: 1_200, leadingSpace: true },
+ { text: "phrase", startMs: 1_200, endMs: 1_500, leadingSpace: true },
+ { text: "here.", startMs: 1_500, endMs: 1_800, leadingSpace: true },
+ { text: "Third", startMs: 1_800, endMs: 2_100, leadingSpace: true },
+ { text: "one.", startMs: 2_100, endMs: 2_400, leadingSpace: true },
+ ],
+ },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(3);
+ for (let index = 0; index < result.length - 1; index += 1) {
+ expect(result[index].startMs).toBeLessThanOrEqual(result[index + 1].startMs);
+ expect(result[index].endMs).toBeLessThanOrEqual(result[index + 1].startMs);
+ }
+ expect(result.map((cue) => cue.id)).toEqual(
+ result.map((_, index) => `caption-${index + 1}`),
+ );
+ });
+
+ it("keeps a single-sentence word-less cue intact (legacy silence trim preserved)", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 13_920, text: "Hello, this is a test" },
+ ];
+ // One sentence -> unchanged: trim leading silence, keep text (legacy behavior).
+ const result = segmentCuesIntoPhrases(cues, [{ startMs: 0, endMs: 3_000 }]);
+ expect(result).toHaveLength(1);
+ expect(result[0].startMs).toBe(3_000 - 80);
+ expect(result[0].endMs).toBe(13_920 + 80);
+ expect(result[0].text).toBe("Hello, this is a test");
+ });
+
+ it("splits a continuous word-less paragraph into one caption per sentence", () => {
+ // The reported bug: no word timings (SRT path) + continuous speech collapsed into one
+ // caption. It must now split on sentence punctuation even without word timings.
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 3_000, text: "This is one." },
+ { id: "caption-2", startMs: 3_000, endMs: 6_000, text: "This is two." },
+ { id: "caption-3", startMs: 6_000, endMs: 9_000, text: "This is three." },
+ ];
+ const result = segmentCuesIntoPhrases(cues, []);
+ expect(result).toHaveLength(3);
+ expect(result.map((cue) => cue.text)).toEqual([
+ "This is one.",
+ "This is two.",
+ "This is three.",
+ ]);
+ for (let index = 0; index < result.length - 1; index += 1) {
+ expect(result[index].endMs).toBeLessThanOrEqual(result[index + 1].startMs);
+ }
+ expect(result.map((cue) => cue.id)).toEqual(["caption-1", "caption-2", "caption-3"]);
+ });
+
+ it("returns an empty array for empty input", () => {
+ expect(segmentCuesIntoPhrases([], [])).toEqual([]);
+ });
+});
diff --git a/electron/ipc/captions/segment.ts b/electron/ipc/captions/segment.ts
new file mode 100644
index 000000000..60407a00a
--- /dev/null
+++ b/electron/ipc/captions/segment.ts
@@ -0,0 +1,459 @@
+import type { CaptionCuePayload, CaptionWordPayload } from "../types";
+import { buildCaptionTextFromWords } from "./parser";
+import { padSpans, resegmentCuesBySilence, type SilenceInterval } from "./silence";
+
+/**
+ * Phrase-aware caption segmentation.
+ *
+ * Whisper breaks speech on its own internal boundaries — not on sentences — so a single
+ * cue can run two phrases together, and re-segmenting purely on acoustic silence merges
+ * back-to-back sentences and misassigns boundary words. We instead walk Whisper's own
+ * word stream (which carries punctuation) and start a new caption at a real boundary:
+ * - the end of a sentence (`.`, `?`, `!`, `…`), or
+ * - a real pause — a large gap between two consecutive words, or a long ffmpeg
+ * `silencedetect` interval sitting in that gap.
+ *
+ * Because every break happens *between two consecutive words*, a word can never leak into
+ * the wrong caption (the failure mode of center-time region assignment). Commas/clauses
+ * stay inside a caption and a whole sentence is allowed to be one caption; only a high
+ * safety cap splits a runaway phrase with no punctuation and no pause.
+ *
+ * When the transcript has no word timings (SRT fallback) we first re-segment by acoustic
+ * silence (`resegmentCuesBySilence`) and then split each cue on its sentence punctuation, so
+ * a continuous paragraph still becomes one caption per sentence (timing is proportional).
+ */
+
+/** A gap (ms) between two consecutive words this long or longer starts a new phrase. */
+const DEFAULT_PHRASE_PAUSE_MS = 700;
+/** An ffmpeg `silencedetect` interval this long inside a word gap also starts a new phrase. */
+const DEFAULT_SPLIT_SILENCE_MS = 1_500;
+/** Padding (ms) kept around each phrase so captions don't feel clipped. */
+const DEFAULT_EDGE_PAD_MS = 80;
+/** Safety cap: a phrase with no sentence end and no pause is split once it gets this long. */
+const DEFAULT_MAX_PHRASE_MS = 12_000;
+
+/**
+ * A caption shorter than this (ms) is "too quick" and may be merged with an adjacent short
+ * caption so rapid-fire one-word sentences ("Okay." "Great.") don't each flash by alone.
+ */
+const DEFAULT_MIN_CAPTION_MS = 800;
+/** Only merge short captions separated by at most this gap (ms) — never across a real pause. */
+const DEFAULT_MERGE_GAP_MS = 400;
+/** A merged short-caption run never grows past this duration (ms) or character count. */
+const DEFAULT_MAX_MERGED_MS = 2_500;
+const DEFAULT_MAX_MERGED_CHARS = 80;
+
+export interface SegmentOptions {
+ /** Word gap (ms) that splits one phrase into two. Lower = more, shorter captions. */
+ pauseMs?: number;
+ /** Minimum acoustic silence (ms) inside a word gap that also splits a phrase. */
+ splitSilenceMs?: number;
+ /** Padding (ms) kept around each phrase. */
+ edgePadMs?: number;
+ /** Safety cap (ms) that splits a punctuation-less, pause-less runaway phrase. */
+ maxPhraseMs?: number;
+ /** A caption shorter than this (ms) may be merged with an adjacent short caption. */
+ minCaptionMs?: number;
+ /** Only merge short captions separated by at most this gap (ms). */
+ mergeGapMs?: number;
+ /** A merged short-caption run never grows past this duration (ms). */
+ maxMergedMs?: number;
+ /** A merged short-caption run never grows past this character count. */
+ maxMergedChars?: number;
+}
+
+interface CaptionPiece {
+ startMs: number;
+ endMs: number;
+ text: string;
+ words: CaptionWordPayload[];
+}
+
+const SENTENCE_END = /[.?!…。！？]$/;
+/** Closing quotes/brackets that can trail terminal punctuation, e.g. `said."` */
+const TRAILING_CLOSERS = /[)\]}"'”’»」』）】］｝>]+$/u;
+
+/**
+ * Unambiguous English titles that take a trailing period mid-sentence. Kept deliberately
+ * short: only words that are never themselves a sentence (so we don't suppress a real
+ * break — e.g. "no" is excluded because "No." is a valid sentence). Dotted initialisms
+ * like "e.g."/"U.S."/"a.m." are handled by the regex below, not this list. `?`/`!`/`…`
+ * always end a sentence. For non-English audio this simply never matches.
+ */
+const ABBREVIATIONS = new Set(["mr", "mrs", "ms", "dr", "prof", "sr", "jr", "st", "vs", "etc"]);
+
+/** A trailing period belongs to an abbreviation/initialism rather than ending a sentence. */
+function isAbbreviation(text: string): boolean {
+ const trimmed = text.trim().replace(TRAILING_CLOSERS, "").trim();
+ if (!trimmed.endsWith(".")) {
+ return false; // only a plain period can be an abbreviation marker
+ }
+ const core = trimmed.slice(0, -1).toLowerCase();
+ if (core.length === 0) {
+ return false;
+ }
+ // Single-letter initial ("J.", "U.") or dotted initialism ("U.S.", "e.g.", "a.m.").
+ if (/^[a-z]$/.test(core) || /^[a-z](\.[a-z])+$/.test(core)) {
+ return true;
+ }
+ return ABBREVIATIONS.has(core);
+}
+
+/**
+ * True when a word's text ends a sentence, ignoring trailing closing quotes/brackets and
+ * common abbreviations (so "Mr. Smith" or "e.g." don't start a new caption).
+ */
+export function endsSentence(text: string): boolean {
+ const trimmed = text.trim().replace(TRAILING_CLOSERS, "").trim();
+ if (!SENTENCE_END.test(trimmed)) {
+ return false;
+ }
+ return !isAbbreviation(text);
+}
+
+/** Every cue carries usable word timing, so we can segment on the word stream. */
+function hasWordTimings(cues: CaptionCuePayload[]): boolean {
+ return cues.length > 0 && cues.every((cue) => Array.isArray(cue.words) && cue.words.length > 0);
+}
+
+/** Flatten all cues' words into one time-ordered stream, spacing across cue joins. */
+function flattenWords(cues: CaptionCuePayload[]): CaptionWordPayload[] {
+ const stream: CaptionWordPayload[] = [];
+ for (const cue of cues) {
+ const words = (cue.words ?? []) as CaptionWordPayload[];
+ words.forEach((word, index) => {
+ // A new cue continues the speech, so its first word leads with a space.
+ const leadingSpace =
+ stream.length > 0 && (index === 0 ? true : word.leadingSpace !== false);
+ stream.push({
+ text: word.text,
+ startMs: word.startMs,
+ endMs: word.endMs,
+ ...(leadingSpace ? { leadingSpace: true } : {}),
+ });
+ });
+ }
+ return stream.sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
+}
+
+/** Drop words that sit entirely inside a long detected silence (Whisper hallucinations). */
+function dropHallucinations(
+ words: CaptionWordPayload[],
+ silences: SilenceInterval[],
+ splitSilenceMs: number,
+): CaptionWordPayload[] {
+ const longSilences = silences.filter(
+ (silence) => silence.endMs - silence.startMs >= splitSilenceMs,
+ );
+ if (longSilences.length === 0) {
+ return words;
+ }
+ return words.filter(
+ (word) =>
+ !longSilences.some(
+ (silence) => silence.startMs <= word.startMs && word.endMs <= silence.endMs,
+ ),
+ );
+}
+
+/** A long silence interval overlaps the gap between two consecutive words. */
+function silenceInGap(
+ gapStartMs: number,
+ gapEndMs: number,
+ silences: SilenceInterval[],
+ splitSilenceMs: number,
+): boolean {
+ return silences.some(
+ (silence) =>
+ silence.endMs - silence.startMs >= splitSilenceMs &&
+ silence.startMs < gapEndMs &&
+ silence.endMs > gapStartMs,
+ );
+}
+
+/** Reset the first word's leading space so a phrase reads as its own line. */
+function normalizePhraseWords(words: CaptionWordPayload[]): CaptionWordPayload[] {
+ return words.map((word, index) => {
+ if (index === 0 && word.leadingSpace) {
+ const { leadingSpace: _leadingSpace, ...rest } = word;
+ return rest;
+ }
+ return word;
+ });
+}
+
+/** Group a cue's words into runs that each end on a sentence boundary. */
+function groupWordsBySentence(words: CaptionWordPayload[]): CaptionWordPayload[][] {
+ const groups: CaptionWordPayload[][] = [];
+ let current: CaptionWordPayload[] = [];
+ words.forEach((word, index) => {
+ current.push(word);
+ if (endsSentence(word.text) && index < words.length - 1) {
+ groups.push(current);
+ current = [];
+ }
+ });
+ if (current.length > 0) {
+ groups.push(current);
+ }
+ return groups;
+}
+
+/**
+ * Split a word-less cue's text into one cue per sentence, distributing the cue's time span
+ * across sentences by character length. Used on the fallback (no word timing) path so a
+ * continuous paragraph still becomes one caption per sentence.
+ */
+function splitTextBySentence(cue: CaptionCuePayload): CaptionCuePayload[] {
+ const tokens = cue.text.trim().split(/\s+/).filter(Boolean);
+ if (tokens.length <= 1) {
+ return [cue];
+ }
+
+ const groups: string[][] = [];
+ let current: string[] = [];
+ tokens.forEach((token, index) => {
+ current.push(token);
+ if (endsSentence(token) && index < tokens.length - 1) {
+ groups.push(current);
+ current = [];
+ }
+ });
+ if (current.length > 0) {
+ groups.push(current);
+ }
+ if (groups.length <= 1) {
+ return [cue];
+ }
+
+ const texts = groups.map((group) => group.join(" "));
+ const totalChars = texts.reduce((sum, text) => sum + text.length, 0) || 1;
+ const spanMs = Math.max(1, cue.endMs - cue.startMs);
+ let cursorMs = cue.startMs;
+ return texts.map((text, index) => {
+ const startMs = cursorMs;
+ const endMs =
+ index === texts.length - 1
+ ? cue.endMs
+ : Math.min(
+ cue.endMs - 1,
+ Math.round(startMs + (spanMs * text.length) / totalChars),
+ );
+ cursorMs = Math.max(startMs + 1, endMs);
+ return { id: cue.id, startMs, endMs: Math.max(startMs + 1, endMs), text };
+ });
+}
+
+/** Split one re-segmented cue into one cue per sentence (by words if present, else text). */
+function splitCueBySentences(cue: CaptionCuePayload): CaptionCuePayload[] {
+ const words = Array.isArray(cue.words) ? (cue.words as CaptionWordPayload[]) : [];
+ if (words.length === 0) {
+ return splitTextBySentence(cue);
+ }
+
+ const groups = groupWordsBySentence(words);
+ if (groups.length <= 1) {
+ return [cue];
+ }
+ return groups.map((group) => {
+ const phraseWords = normalizePhraseWords(group);
+ return {
+ id: cue.id,
+ startMs: phraseWords[0].startMs,
+ endMs: phraseWords[phraseWords.length - 1].endMs,
+ text: buildCaptionTextFromWords(phraseWords),
+ words: phraseWords,
+ };
+ });
+}
+
+/** Concatenate two adjacent cues into one, joining words (with a space) when both have them. */
+function mergeTwoCues(left: CaptionCuePayload, right: CaptionCuePayload): CaptionCuePayload {
+ const leftWords = Array.isArray(left.words) ? (left.words as CaptionWordPayload[]) : [];
+ const rightWords = Array.isArray(right.words) ? (right.words as CaptionWordPayload[]) : [];
+ if (leftWords.length > 0 && rightWords.length > 0) {
+ // The right cue's first word started its own phrase (no leading space) — restore it.
+ const joined = normalizePhraseWords([
+ ...leftWords,
+ ...rightWords.map((word, index) =>
+ index === 0 ? { ...word, leadingSpace: true } : word,
+ ),
+ ]);
+ return {
+ id: left.id,
+ startMs: left.startMs,
+ endMs: right.endMs,
+ text: buildCaptionTextFromWords(joined),
+ words: joined,
+ };
+ }
+ return {
+ id: left.id,
+ startMs: left.startMs,
+ endMs: right.endMs,
+ text: `${left.text} ${right.text}`.trim(),
+ };
+}
+
+interface MergeOptions {
+ minCaptionMs: number;
+ mergeGapMs: number;
+ maxMergedMs: number;
+ maxMergedChars: number;
+}
+
+/**
+ * Merge adjacent captions that are BOTH short and rapid-fire (tiny gap), so quick one-word
+ * sentences like "Okay." "Great." read as one caption instead of flashing by individually.
+ * Only merges when both sides are short, so a short caption never absorbs a full-length one,
+ * and never across a real pause or past the size caps.
+ */
+function mergeShortAdjacentCaptions(
+ cues: CaptionCuePayload[],
+ options: MergeOptions,
+): CaptionCuePayload[] {
+ if (cues.length <= 1) {
+ return cues;
+ }
+
+ const merged: CaptionCuePayload[] = [];
+ let group = cues[0];
+ for (let index = 1; index < cues.length; index += 1) {
+ const next = cues[index];
+ const groupDurationMs = group.endMs - group.startMs;
+ const nextDurationMs = next.endMs - next.startMs;
+ const gapMs = next.startMs - group.endMs;
+ const combinedDurationMs = next.endMs - group.startMs;
+ const combinedChars = group.text.length + next.text.length + 1;
+
+ const canMerge =
+ groupDurationMs < options.minCaptionMs &&
+ nextDurationMs < options.minCaptionMs &&
+ gapMs <= options.mergeGapMs &&
+ combinedDurationMs <= options.maxMergedMs &&
+ combinedChars <= options.maxMergedChars;
+
+ if (canMerge) {
+ group = mergeTwoCues(group, next);
+ } else {
+ merged.push(group);
+ group = next;
+ }
+ }
+ merged.push(group);
+ return merged;
+}
+
+/** Assign sequential, stable ids to the final cue list. */
+function renumberCues(cues: CaptionCuePayload[]): CaptionCuePayload[] {
+ return cues.map((cue, index) => ({ ...cue, id: `caption-${index + 1}` }));
+}
+
+/**
+ * Re-segment Whisper cues into one caption per sentence/phrase, then merge rapid-fire short
+ * sentences back together. Returns sorted, non-overlapping cues with fresh ids. Falls back to
+ * silence-only re-segmentation (plus sentence splitting) when the transcript has no word timings.
+ */
+export function segmentCuesIntoPhrases(
+ cues: CaptionCuePayload[],
+ silences: SilenceInterval[],
+ options: SegmentOptions = {},
+): CaptionCuePayload[] {
+ const pauseMs = options.pauseMs ?? DEFAULT_PHRASE_PAUSE_MS;
+ const splitSilenceMs = options.splitSilenceMs ?? DEFAULT_SPLIT_SILENCE_MS;
+ const edgePadMs = options.edgePadMs ?? DEFAULT_EDGE_PAD_MS;
+ const maxPhraseMs = options.maxPhraseMs ?? DEFAULT_MAX_PHRASE_MS;
+ const mergeOptions: MergeOptions = {
+ minCaptionMs: options.minCaptionMs ?? DEFAULT_MIN_CAPTION_MS,
+ mergeGapMs: options.mergeGapMs ?? DEFAULT_MERGE_GAP_MS,
+ maxMergedMs: options.maxMergedMs ?? DEFAULT_MAX_MERGED_MS,
+ maxMergedChars: options.maxMergedChars ?? DEFAULT_MAX_MERGED_CHARS,
+ };
+
+ if (cues.length === 0) {
+ return [];
+ }
+
+ // No word timings (SRT path): the silence-only segmenter trims/merges by acoustic
+ // silence but can't see sentence boundaries, so a continuous paragraph would collapse
+ // into one caption. Re-segment by silence first, then split each cue on its sentence
+ // punctuation so we still get one caption per sentence.
+ if (!hasWordTimings(cues)) {
+ const base = resegmentCuesBySilence(cues, silences, { splitSilenceMs, edgePadMs });
+ const sentences = base.flatMap(splitCueBySentences);
+ return renumberCues(mergeShortAdjacentCaptions(sentences, mergeOptions));
+ }
+
+ const sortedCues = [...cues].sort(
+ (left, right) => left.startMs - right.startMs || left.endMs - right.endMs,
+ );
+ const stream = dropHallucinations(flattenWords(sortedCues), silences, splitSilenceMs);
+ if (stream.length === 0) {
+ return [];
+ }
+
+ const phrases: CaptionWordPayload[][] = [];
+ let current: CaptionWordPayload[] = [];
+
+ for (let index = 0; index < stream.length; index += 1) {
+ const word = stream[index];
+ current.push(word);
+
+ const next = stream[index + 1];
+ if (!next) {
+ break;
+ }
+
+ const gapMs = next.startMs - word.endMs;
+ const phraseDurationMs = word.endMs - current[0].startMs;
+ const shouldBreak =
+ endsSentence(word.text) ||
+ gapMs >= pauseMs ||
+ // Only consult acoustic silence when there's a real gap between the words. When
+ // consecutive words overlap or abut (gapMs <= 0) a silence interval spanning that
+ // region must not manufacture a bogus split.
+ (gapMs > 0 && silenceInGap(word.endMs, next.startMs, silences, splitSilenceMs)) ||
+ phraseDurationMs >= maxPhraseMs;
+
+ if (shouldBreak) {
+ phrases.push(current);
+ current = [];
+ }
+ }
+ if (current.length > 0) {
+ phrases.push(current);
+ }
+
+ const pieces: CaptionPiece[] = phrases
+ .map((words) => {
+ const phraseWords = normalizePhraseWords(words);
+ return {
+ startMs: phraseWords[0].startMs,
+ endMs: phraseWords[phraseWords.length - 1].endMs,
+ text: buildCaptionTextFromWords(phraseWords),
+ words: phraseWords,
+ };
+ })
+ .filter((piece) => piece.text.trim().length > 0);
+
+ if (pieces.length === 0) {
+ return [];
+ }
+
+ pieces.sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
+
+ const sentenceCues: CaptionCuePayload[] = pieces.map((piece) => ({
+ id: "",
+ startMs: piece.startMs,
+ endMs: piece.endMs,
+ text: piece.text,
+ ...(piece.words.length > 0 ? { words: piece.words } : {}),
+ }));
+ // Merge rapid-fire short captions BEFORE padding so merge eligibility sees the true
+ // speech gaps. Padding pulls cue edges toward each other, which would shrink the
+ // apparent gap and could merge two captions across a real pause sitting just above
+ // mergeGapMs. Pad the survivors afterward so envelopes still get their edge padding.
+ const merged = mergeShortAdjacentCaptions(sentenceCues, mergeOptions);
+ padSpans(merged, edgePadMs);
+ return renumberCues(merged);
+}
diff --git a/electron/ipc/captions/silence.test.ts b/electron/ipc/captions/silence.test.ts
new file mode 100644
index 000000000..941d1076f
--- /dev/null
+++ b/electron/ipc/captions/silence.test.ts
@@ -0,0 +1,141 @@
+import { describe, expect, it } from "vitest";
+import type { CaptionCuePayload } from "../types";
+import { parseSilenceIntervals, resegmentCuesBySilence } from "./silence";
+
+describe("parseSilenceIntervals", () => {
+ it("pairs silence_start / silence_end lines into ms intervals", () => {
+ const stderr = [
+ "[silencedetect @ 0x1] silence_start: 0",
+ "[silencedetect @ 0x1] silence_end: 3.2 | silence_duration: 3.2",
+ "[silencedetect @ 0x1] silence_start: 8.5",
+ "[silencedetect @ 0x1] silence_end: 9.3 | silence_duration: 0.8",
+ ].join("\n");
+ expect(parseSilenceIntervals(stderr)).toEqual([
+ { startMs: 0, endMs: 3_200 },
+ { startMs: 8_500, endMs: 9_300 },
+ ]);
+ });
+
+ it("treats a trailing silence_start with no end as running to end-of-audio", () => {
+ const stderr = "[silencedetect] silence_start: 12.0";
+ expect(parseSilenceIntervals(stderr)).toEqual([
+ { startMs: 12_000, endMs: Number.POSITIVE_INFINITY },
+ ]);
+ });
+
+ it("returns an empty array when there is no silence output", () => {
+ expect(parseSilenceIntervals("some unrelated ffmpeg log\n")).toEqual([]);
+ });
+});
+
+describe("resegmentCuesBySilence", () => {
+ it("trims leading silence off a word-less cue", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 13_920, text: "Hello, this is a test" },
+ ];
+ const result = resegmentCuesBySilence(cues, [{ startMs: 0, endMs: 3_000 }]);
+ expect(result).toHaveLength(1);
+ // speech span [3000, 13920]; only an 80ms pad re-enters the silence
+ expect(result[0].startMs).toBe(3_000 - 80);
+ expect(result[0].endMs).toBe(13_920 + 80);
+ expect(result[0].text).toBe("Hello, this is a test");
+ });
+
+ it("does NOT split on a short pause (slowing down stays one phrase)", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 8_000, text: "one two three four" },
+ ];
+ // 800ms pause is below the 1500ms split threshold -> absorbed, stays one phrase
+ const result = resegmentCuesBySilence(cues, [{ startMs: 3_000, endMs: 3_800 }]);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("one two three four");
+ });
+
+ it("merges adjacent cues that are not separated by a long pause", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "a", startMs: 0, endMs: 3_000, text: "hello world" },
+ { id: "b", startMs: 3_000, endMs: 6_000, text: "how are you" },
+ ];
+ // continuous speech, no silence -> one merged phrase
+ const result = resegmentCuesBySilence(cues, []);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("hello world how are you");
+ });
+
+ it("splits only at a long pause (>= 1500ms)", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 10_000, text: "one two three four" },
+ ];
+ // 2000ms pause -> a real boundary
+ const result = resegmentCuesBySilence(cues, [{ startMs: 4_000, endMs: 6_000 }]);
+ expect(result).toHaveLength(2);
+ expect(result[0].endMs).toBeLessThanOrEqual(result[1].startMs);
+ expect(`${result[0].text} ${result[1].text}`).toBe("one two three four");
+ });
+
+ it("does not over-split: two short pauses inside a sentence stay one phrase", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 0, endMs: 9_000, text: "so this is a slow sentence" },
+ ];
+ const result = resegmentCuesBySilence(cues, [
+ { startMs: 2_000, endMs: 2_700 }, // 700ms
+ { startMs: 5_000, endMs: 5_900 }, // 900ms
+ ]);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("so this is a slow sentence");
+ });
+
+ it("drops a cue that falls entirely inside silence (hallucination)", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 5_000, endMs: 7_000, text: "Thank you." },
+ ];
+ const result = resegmentCuesBySilence(cues, [{ startMs: 4_000, endMs: 9_000 }]);
+ expect(result).toHaveLength(0);
+ });
+
+ it("keeps a continuous cue (no silence) as a single phrase", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "caption-1", startMs: 1_000, endMs: 4_000, text: "continuous speech" },
+ ];
+ const result = resegmentCuesBySilence(cues, []);
+ expect(result).toHaveLength(1);
+ expect(result[0].text).toBe("continuous speech");
+ });
+
+ it("splits a word-timed cue by assigning each word to its speech region", () => {
+ const cues: CaptionCuePayload[] = [
+ {
+ id: "caption-1",
+ startMs: 0,
+ endMs: 10_000,
+ text: "alpha beta gamma",
+ words: [
+ { text: "alpha", startMs: 500, endMs: 1_000 },
+ { text: "beta", startMs: 1_000, endMs: 1_500, leadingSpace: true },
+ { text: "gamma", startMs: 7_000, endMs: 7_500, leadingSpace: true },
+ ],
+ },
+ ];
+ // 4000ms pause puts alpha+beta in region 1, gamma in region 2
+ const result = resegmentCuesBySilence(cues, [{ startMs: 2_000, endMs: 6_000 }]);
+ expect(result).toHaveLength(2);
+ expect(result[0].text).toBe("alpha beta");
+ expect(result[1].text).toBe("gamma");
+ expect(result[0].endMs).toBeLessThanOrEqual(result[1].startMs);
+ });
+
+ it("produces sorted, non-overlapping cues with sequential ids", () => {
+ const cues: CaptionCuePayload[] = [
+ { id: "x", startMs: 0, endMs: 6_000, text: "first phrase here" },
+ { id: "y", startMs: 6_000, endMs: 14_000, text: "second phrase here" },
+ ];
+ const result = resegmentCuesBySilence(cues, [{ startMs: 6_000, endMs: 8_000 }]);
+ for (let index = 0; index < result.length - 1; index += 1) {
+ expect(result[index].startMs).toBeLessThanOrEqual(result[index + 1].startMs);
+ expect(result[index].endMs).toBeLessThanOrEqual(result[index + 1].startMs);
+ }
+ expect(result.map((cue) => cue.id)).toEqual(
+ result.map((_, index) => `caption-${index + 1}`),
+ );
+ });
+});
diff --git a/electron/ipc/captions/silence.ts b/electron/ipc/captions/silence.ts
new file mode 100644
index 000000000..c8750ca1c
--- /dev/null
+++ b/electron/ipc/captions/silence.ts
@@ -0,0 +1,323 @@
+import type { CaptionCuePayload, CaptionWordPayload } from "../types";
+import { buildCaptionTextFromWords } from "./parser";
+
+/**
+ * Silence-aware caption re-segmentation.
+ *
+ * Whisper breaks speech on its own internal boundaries, not on real pauses, so cues can
+ * cover silence and continuous speech gets chopped arbitrarily. We re-segment against
+ * ground-truth silence from ffmpeg `silencedetect` instead:
+ * ffmpeg silencedetect (stderr) -> parseSilenceIntervals -> resegmentCuesBySilence
+ *
+ * A phrase only breaks at a long pause (>= splitSilenceMs) or at silence touching the
+ * transcript edges (leading/trailing trim). Short pauses are absorbed; speech not separated
+ * by a long pause is merged; a region with no speech is dropped (drops hallucinations).
+ */
+
+/** ffmpeg `silencedetect` noise floor. Quieter than this counts as silence. */
+export const SILENCE_NOISE_DB = -30;
+/** ffmpeg `silencedetect` minimum silence duration (seconds) it should report at all. */
+export const SILENCE_DETECT_MIN_S = 0.5;
+
+/** A pause must be at least this long (ms) to break one phrase into two. The "sensitivity" knob. */
+const DEFAULT_SPLIT_SILENCE_MS = 1_500;
+/** Padding (ms) kept around each phrase so captions don't feel clipped. */
+const DEFAULT_EDGE_PAD_MS = 80;
+/** Speech regions shorter than this (ms) are dropped as artifacts. */
+const DEFAULT_MIN_SPEECH_MS = 150;
+
+export interface SilenceInterval {
+ startMs: number;
+ /** `Number.POSITIVE_INFINITY` for a trailing silence that runs to end-of-audio. */
+ endMs: number;
+}
+
+export interface ResegmentOptions {
+ /** Minimum pause (ms) that splits a phrase. Higher = fewer splits. */
+ splitSilenceMs?: number;
+ /** Padding (ms) kept around each phrase. */
+ edgePadMs?: number;
+ /** Speech regions shorter than this (ms) are dropped. */
+ minSpeechMs?: number;
+}
+
+interface Span {
+ startMs: number;
+ endMs: number;
+}
+
+interface CaptionPiece extends Span {
+ text: string;
+ words?: CaptionWordPayload[];
+}
+
+/**
+ * Parse ffmpeg `silencedetect` stderr into ordered, non-overlapping silence intervals.
+ * Lines look like:
+ * [silencedetect @ 0x..] silence_start: 12.34
+ * [silencedetect @ 0x..] silence_end: 15.67 | silence_duration: 3.33
+ */
+export function parseSilenceIntervals(stderr: string): SilenceInterval[] {
+ const intervals: SilenceInterval[] = [];
+ let pendingStartMs: number | null = null;
+
+ for (const line of stderr.split(/\r?\n/)) {
+ const startMatch = line.match(/silence_start:\s*(-?[\d.]+)/);
+ if (startMatch) {
+ pendingStartMs = Math.max(0, Math.round(Number.parseFloat(startMatch[1]) * 1000));
+ continue;
+ }
+
+ const endMatch = line.match(/silence_end:\s*(-?[\d.]+)/);
+ if (endMatch && pendingStartMs !== null) {
+ const endMs = Math.round(Number.parseFloat(endMatch[1]) * 1000);
+ if (endMs > pendingStartMs) {
+ intervals.push({ startMs: pendingStartMs, endMs });
+ }
+ pendingStartMs = null;
+ }
+ }
+
+ // A trailing silence_start with no matching end runs to the end of the audio.
+ if (pendingStartMs !== null) {
+ intervals.push({ startMs: pendingStartMs, endMs: Number.POSITIVE_INFINITY });
+ }
+
+ return intervals.sort((left, right) => left.startMs - right.startMs);
+}
+
+/** Subtract a set of (sorted, non-overlapping) intervals from [startMs, endMs]. */
+function subtractIntervals(startMs: number, endMs: number, intervals: Span[]): Span[] {
+ const spans: Span[] = [];
+ let cursor = startMs;
+
+ for (const interval of intervals) {
+ if (interval.endMs <= startMs || interval.startMs >= endMs) {
+ continue;
+ }
+ const clippedStart = Math.max(interval.startMs, startMs);
+ if (clippedStart > cursor) {
+ spans.push({ startMs: cursor, endMs: clippedStart });
+ }
+ cursor = Math.max(cursor, Math.min(interval.endMs, endMs));
+ }
+
+ if (cursor < endMs) {
+ spans.push({ startMs: cursor, endMs });
+ }
+
+ return spans;
+}
+
+function nearestRegionIndex(regions: Span[], timeMs: number): number {
+ let bestIndex = 0;
+ let bestDistance = Number.POSITIVE_INFINITY;
+ regions.forEach((region, index) => {
+ const distance =
+ timeMs < region.startMs
+ ? region.startMs - timeMs
+ : timeMs > region.endMs
+ ? timeMs - region.endMs
+ : 0;
+ if (distance < bestDistance) {
+ bestDistance = distance;
+ bestIndex = index;
+ }
+ });
+ return bestIndex;
+}
+
+function joinText(existing: string, addition: string): string {
+ return [existing, addition]
+ .map((part) => part.trim())
+ .filter(Boolean)
+ .join(" ");
+}
+
+/**
+ * Distribute a cue's plain text across the regions it overlaps, proportionally to how much
+ * of the cue's duration falls in each region. Used only when a single Whisper cue straddles
+ * a long pause (rare) and has no word timing.
+ */
+function splitTextProportionally(text: string, overlaps: Span[]): string[] {
+ const tokens = text.trim().split(/\s+/).filter(Boolean);
+ if (tokens.length === 0) {
+ return overlaps.map(() => "");
+ }
+
+ const totalDurationMs =
+ overlaps.reduce((sum, span) => sum + (span.endMs - span.startMs), 0) || 1;
+ const result: string[] = [];
+ let cursor = 0;
+
+ overlaps.forEach((span, index) => {
+ const isLast = index === overlaps.length - 1;
+ const share = (span.endMs - span.startMs) / totalDurationMs;
+ const count = isLast
+ ? tokens.length - cursor
+ : Math.min(tokens.length - cursor, Math.round(tokens.length * share));
+ result.push(tokens.slice(cursor, cursor + count).join(" "));
+ cursor += count;
+ });
+
+ if (cursor < tokens.length) {
+ result[result.length - 1] = joinText(
+ result[result.length - 1],
+ tokens.slice(cursor).join(" "),
+ );
+ }
+
+ return result;
+}
+
+/** Pad spans toward neighbors by at most half the silent gap, so cues never overlap. */
+export function padSpans(spans: Span[], edgePadMs: number): void {
+ for (let index = 0; index < spans.length; index += 1) {
+ const prevEndMs = index > 0 ? spans[index - 1].endMs : null;
+ const nextStartMs = index < spans.length - 1 ? spans[index + 1].startMs : null;
+ const rawStart = spans[index].startMs;
+ const rawEnd = spans[index].endMs;
+
+ const leftPad =
+ prevEndMs === null
+ ? Math.min(edgePadMs, rawStart)
+ : Math.min(edgePadMs, Math.floor(Math.max(0, rawStart - prevEndMs) / 2));
+ const rightPad =
+ nextStartMs === null
+ ? edgePadMs
+ : Math.min(edgePadMs, Math.floor(Math.max(0, nextStartMs - rawEnd) / 2));
+
+ spans[index].startMs = Math.max(0, Math.round(rawStart - leftPad));
+ spans[index].endMs = Math.max(spans[index].startMs + 1, Math.round(rawEnd + rightPad));
+ }
+}
+
+/**
+ * Re-segment Whisper cues against detected silence into phrases that only break on long
+ * pauses. Returns sorted, non-overlapping cues with fresh ids. If no silence is detected
+ * the cues are merged into a single trimmed phrase (continuous speech).
+ */
+export function resegmentCuesBySilence(
+ cues: CaptionCuePayload[],
+ silences: SilenceInterval[],
+ options: ResegmentOptions = {},
+): CaptionCuePayload[] {
+ const splitSilenceMs = options.splitSilenceMs ?? DEFAULT_SPLIT_SILENCE_MS;
+ const edgePadMs = options.edgePadMs ?? DEFAULT_EDGE_PAD_MS;
+ const minSpeechMs = options.minSpeechMs ?? DEFAULT_MIN_SPEECH_MS;
+
+ if (cues.length === 0) {
+ return [];
+ }
+
+ const sortedCues = [...cues].sort(
+ (left, right) => left.startMs - right.startMs || left.endMs - right.endMs,
+ );
+ const transcriptStartMs = sortedCues[0].startMs;
+ const transcriptEndMs = sortedCues.reduce(
+ (max, cue) => Math.max(max, cue.endMs),
+ transcriptStartMs,
+ );
+
+ // Boundaries = long pauses, plus any silence touching the transcript edges (so leading
+ // and trailing silence is always trimmed even if short).
+ const boundaries: Span[] = silences
+ .map((silence) => ({
+ startMs: Math.max(silence.startMs, transcriptStartMs),
+ endMs: Math.min(silence.endMs, transcriptEndMs),
+ }))
+ .filter((span) => span.endMs > span.startMs)
+ .filter(
+ (span) =>
+ span.endMs - span.startMs >= splitSilenceMs ||
+ span.startMs <= transcriptStartMs ||
+ span.endMs >= transcriptEndMs,
+ )
+ .sort((left, right) => left.startMs - right.startMs);
+
+ const regions = subtractIntervals(transcriptStartMs, transcriptEndMs, boundaries).filter(
+ (region) => region.endMs - region.startMs >= minSpeechMs,
+ );
+ if (regions.length === 0) {
+ return [];
+ }
+
+ const regionTexts = regions.map(() => "");
+ const regionWords: CaptionWordPayload[][] = regions.map(() => []);
+
+ for (const cue of sortedCues) {
+ const overlapping = regions
+ .map((region, index) => ({ region, index }))
+ .filter(({ region }) => cue.startMs < region.endMs && cue.endMs > region.startMs);
+ if (overlapping.length === 0) {
+ continue;
+ }
+
+ const words = Array.isArray(cue.words) ? (cue.words as CaptionWordPayload[]) : [];
+ if (words.length > 0) {
+ for (const word of words) {
+ const center = (word.startMs + word.endMs) / 2;
+ const match = overlapping.find(
+ ({ region }) => center >= region.startMs && center <= region.endMs,
+ );
+ const targetIndex =
+ match?.index ??
+ overlapping[
+ nearestRegionIndex(
+ overlapping.map((entry) => entry.region),
+ center,
+ )
+ ].index;
+ regionWords[targetIndex].push(word);
+ }
+ continue;
+ }
+
+ if (overlapping.length === 1) {
+ const { index } = overlapping[0];
+ regionTexts[index] = joinText(regionTexts[index], cue.text);
+ continue;
+ }
+
+ const overlaps = overlapping.map(({ region }) => ({
+ startMs: Math.max(cue.startMs, region.startMs),
+ endMs: Math.min(cue.endMs, region.endMs),
+ }));
+ const texts = splitTextProportionally(cue.text, overlaps);
+ overlapping.forEach(({ index }, position) => {
+ regionTexts[index] = joinText(regionTexts[index], texts[position]);
+ });
+ }
+
+ const pieces = regions
+ .map((region, index): CaptionPiece => {
+ const words = regionWords[index]
+ .slice()
+ .sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
+ if (words.length > 0) {
+ return {
+ startMs: words[0].startMs,
+ endMs: words[words.length - 1].endMs,
+ text: buildCaptionTextFromWords(words),
+ words,
+ };
+ }
+ return {
+ startMs: region.startMs,
+ endMs: region.endMs,
+ text: regionTexts[index].trim(),
+ };
+ })
+ .filter((piece) => piece.text.trim().length > 0);
+
+ pieces.sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
+ padSpans(pieces, edgePadMs);
+
+ return pieces.map((piece, index) => ({
+ id: `caption-${index + 1}`,
+ startMs: piece.startMs,
+ endMs: piece.endMs,
+ text: piece.text,
+ ...(piece.words && piece.words.length > 0 ? { words: piece.words } : {}),
+ }));
+}
diff --git a/electron/ipc/captions/whisper.ts b/electron/ipc/captions/whisper.ts
new file mode 100644
index 000000000..67b04cd58
--- /dev/null
+++ b/electron/ipc/captions/whisper.ts
@@ -0,0 +1,155 @@
+import { createWriteStream } from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import { get as httpsGet } from "node:https";
+import type Electron from "electron";
+import {
+ WHISPER_MODEL_DIR,
+ WHISPER_MODEL_DOWNLOAD_URL,
+ WHISPER_SMALL_MODEL_PATH,
+} from "../constants";
+
+export function sendWhisperModelDownloadProgress(
+ webContents: Electron.WebContents,
+ payload: {
+ status: "idle" | "downloading" | "downloaded" | "error";
+ progress: number;
+ path?: string | null;
+ error?: string;
+ },
+) {
+ webContents.send("whisper-small-model-download-progress", payload);
+}
+
+export async function getWhisperSmallModelStatus() {
+ try {
+ await fs.access(WHISPER_SMALL_MODEL_PATH, fsConstants.R_OK);
+ return {
+ success: true,
+ exists: true,
+ path: WHISPER_SMALL_MODEL_PATH,
+ };
+ } catch {
+ return {
+ success: true,
+ exists: false,
+ path: null,
+ };
+ }
+}
+
+export function downloadFileWithProgress(
+ url: string,
+ destinationPath: string,
+ onProgress: (progress: number) => void,
+): Promise {
+ const request = (currentUrl: string, redirectCount = 0): Promise => {
+ return new Promise((resolve, reject) => {
+ const req = httpsGet(currentUrl, { timeout: 30_000 }, (response) => {
+ const statusCode = response.statusCode ?? 0;
+ const location = response.headers.location;
+
+ if (statusCode >= 300 && statusCode < 400 && location) {
+ response.resume();
+ if (redirectCount >= 5) {
+ reject(new Error("Too many redirects while downloading Whisper model."));
+ return;
+ }
+
+ const nextUrl = new URL(location, currentUrl).toString();
+ void request(nextUrl, redirectCount + 1)
+ .then(resolve)
+ .catch(reject);
+ return;
+ }
+
+ if (statusCode < 200 || statusCode >= 300) {
+ response.resume();
+ reject(new Error(`Whisper model download failed with status ${statusCode}.`));
+ return;
+ }
+
+ const totalBytes = Number.parseInt(
+ String(response.headers["content-length"] ?? "0"),
+ 10,
+ );
+ let downloadedBytes = 0;
+ const fileStream = createWriteStream(destinationPath);
+
+ response.on("data", (chunk: Buffer) => {
+ downloadedBytes += chunk.length;
+ if (Number.isFinite(totalBytes) && totalBytes > 0) {
+ onProgress(Math.min(100, Math.round((downloadedBytes / totalBytes) * 100)));
+ }
+ });
+
+ response.on("error", (error) => {
+ fileStream.destroy(error);
+ });
+
+ fileStream.on("error", (error) => {
+ response.destroy(error);
+ reject(error);
+ });
+
+ fileStream.on("finish", () => {
+ onProgress(100);
+ resolve();
+ });
+
+ response.pipe(fileStream);
+ });
+
+ req.on("error", reject);
+ req.on("timeout", () => {
+ req.destroy(new Error("Whisper model download timed out."));
+ });
+ });
+ };
+
+ return request(url);
+}
+
+export async function downloadWhisperSmallModel(
+ webContents: Electron.WebContents,
+): Promise {
+ await fs.mkdir(WHISPER_MODEL_DIR, { recursive: true });
+ const tempPath = `${WHISPER_SMALL_MODEL_PATH}.download`;
+
+ sendWhisperModelDownloadProgress(webContents, {
+ status: "downloading",
+ progress: 0,
+ path: null,
+ });
+
+ try {
+ await fs.rm(tempPath, { force: true });
+ await downloadFileWithProgress(WHISPER_MODEL_DOWNLOAD_URL, tempPath, (progress) => {
+ sendWhisperModelDownloadProgress(webContents, {
+ status: "downloading",
+ progress,
+ path: null,
+ });
+ });
+ await fs.rename(tempPath, WHISPER_SMALL_MODEL_PATH);
+ sendWhisperModelDownloadProgress(webContents, {
+ status: "downloaded",
+ progress: 100,
+ path: WHISPER_SMALL_MODEL_PATH,
+ });
+ return WHISPER_SMALL_MODEL_PATH;
+ } catch (error) {
+ await fs.rm(tempPath, { force: true }).catch(() => undefined);
+ sendWhisperModelDownloadProgress(webContents, {
+ status: "error",
+ progress: 0,
+ path: null,
+ error: String(error),
+ });
+ throw error;
+ }
+}
+
+export async function deleteWhisperSmallModel(): Promise {
+ await fs.rm(WHISPER_SMALL_MODEL_PATH, { force: true });
+}
diff --git a/electron/ipc/constants.ts b/electron/ipc/constants.ts
new file mode 100644
index 000000000..2c5cf8f17
--- /dev/null
+++ b/electron/ipc/constants.ts
@@ -0,0 +1,31 @@
+import path from "node:path";
+import { USER_DATA_PATH } from "../appPaths";
+
+export const PROJECT_FILE_EXTENSION = "recordly";
+export const LEGACY_PROJECT_FILE_EXTENSIONS = ["openscreen"];
+export const PROJECTS_DIRECTORY_NAME = "Projects";
+export const PROJECT_THUMBNAIL_SUFFIX = ".preview.png";
+export const RECENT_PROJECTS_FILE = path.join(USER_DATA_PATH, "recent-projects.json");
+export const MAX_RECENT_PROJECTS = 16;
+export const SHORTCUTS_FILE = path.join(USER_DATA_PATH, "shortcuts.json");
+export const RECORDINGS_SETTINGS_FILE = path.join(USER_DATA_PATH, "recordings-settings.json");
+export const COUNTDOWN_SETTINGS_FILE = path.join(USER_DATA_PATH, "countdown-settings.json");
+export const APP_SETTINGS_FILE = path.join(USER_DATA_PATH, "app-settings.json");
+export const AUTO_RECORDING_PREFIX = "recording-";
+export const AUTO_RECORDING_RETENTION_COUNT = 20;
+export const AUTO_RECORDING_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+export const ALLOW_RECORDLY_WINDOW_CAPTURE = Boolean(process.env["VITE_DEV_SERVER_URL"]);
+export const RECORDING_SESSION_MANIFEST_SUFFIX = ".recordly-session.json";
+export const WHISPER_MODEL_DOWNLOAD_URL =
+ "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin";
+export const WHISPER_MODEL_DIR = path.join(USER_DATA_PATH, "whisper");
+export const WHISPER_SMALL_MODEL_PATH = path.join(WHISPER_MODEL_DIR, "ggml-small.bin");
+export const COMPANION_AUDIO_LAYOUTS = [
+ { platform: "mac" as const, systemSuffix: ".system.m4a", micSuffix: ".mic.m4a" },
+ { platform: "win" as const, systemSuffix: ".system.wav", micSuffix: ".mic.wav" },
+ { platform: "mac" as const, systemSuffix: ".system.webm", micSuffix: ".mic.webm" },
+];
+
+export const CURSOR_TELEMETRY_VERSION = 2;
+export const CURSOR_SAMPLE_INTERVAL_MS = 33;
+export const MAX_CURSOR_SAMPLES = 60 * 60 * 30; // 1 hour @ 30Hz
diff --git a/electron/ipc/cursor/bounds.ts b/electron/ipc/cursor/bounds.ts
new file mode 100644
index 000000000..fbc7d2d50
--- /dev/null
+++ b/electron/ipc/cursor/bounds.ts
@@ -0,0 +1,271 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { NativeMacWindowSource, WindowBounds, SelectedSource } from "../types";
+import {
+ selectedSource,
+ setSelectedWindowBounds,
+ interactionCaptureCleanup,
+ setInteractionCaptureCleanup,
+ windowBoundsCaptureInterval,
+ setWindowBoundsCaptureInterval,
+ cachedNativeMacWindowSources,
+ setCachedNativeMacWindowSources,
+ cachedNativeMacWindowSourcesAtMs,
+ setCachedNativeMacWindowSourcesAtMs,
+} from "../state";
+import { parseWindowId } from "../utils";
+import { ensureNativeWindowListBinary } from "../paths/binaries";
+
+const execFileAsync = promisify(execFile);
+
+export async function getNativeMacWindowSources(options?: { maxAgeMs?: number }) {
+ if (process.platform !== "darwin") {
+ return [] as NativeMacWindowSource[];
+ }
+
+ const maxAgeMs = options?.maxAgeMs ?? 5000;
+ const now = Date.now();
+ if (cachedNativeMacWindowSources && now - cachedNativeMacWindowSourcesAtMs < maxAgeMs) {
+ return cachedNativeMacWindowSources;
+ }
+
+ try {
+ const binaryPath = await ensureNativeWindowListBinary();
+ const { stdout } = await execFileAsync(binaryPath, [], {
+ timeout: 30000,
+ maxBuffer: 10 * 1024 * 1024,
+ });
+
+ const parsed = JSON.parse(stdout);
+ if (!Array.isArray(parsed)) {
+ return [] as NativeMacWindowSource[];
+ }
+
+ const entries = parsed.filter((entry: unknown): entry is NativeMacWindowSource => {
+ if (!entry || typeof entry !== "object") {
+ return false;
+ }
+
+ const candidate = entry as Partial;
+ return typeof candidate.id === "string" && typeof candidate.name === "string";
+ });
+
+ setCachedNativeMacWindowSources(entries);
+ setCachedNativeMacWindowSourcesAtMs(now);
+ return entries;
+ } catch {
+ return cachedNativeMacWindowSources ?? ([] as NativeMacWindowSource[]);
+ }
+}
+
+export function getWindowBoundsFromNativeSource(
+ source?: NativeMacWindowSource | null,
+): WindowBounds | null {
+ if (!source) {
+ return null;
+ }
+
+ const { x, y, width, height } = source;
+ if (
+ typeof x !== "number" ||
+ !Number.isFinite(x) ||
+ typeof y !== "number" ||
+ !Number.isFinite(y) ||
+ typeof width !== "number" ||
+ !Number.isFinite(width) ||
+ typeof height !== "number" ||
+ !Number.isFinite(height)
+ ) {
+ return null;
+ }
+
+ if (width <= 0 || height <= 0) {
+ return null;
+ }
+
+ return { x, y, width, height };
+}
+
+export async function resolveMacWindowBounds(source: SelectedSource): Promise {
+ const windowId = parseWindowId(source.id);
+ if (!windowId) {
+ return null;
+ }
+
+ try {
+ const nativeSources = await getNativeMacWindowSources({ maxAgeMs: 250 });
+ const matchedSource = nativeSources.find((entry) => parseWindowId(entry.id) === windowId);
+ return getWindowBoundsFromNativeSource(matchedSource);
+ } catch {
+ return null;
+ }
+}
+
+export function parseXwininfoBounds(stdout: string): WindowBounds | null {
+ const absX = stdout.match(/Absolute upper-left X:\s+(-?\d+)/);
+ const absY = stdout.match(/Absolute upper-left Y:\s+(-?\d+)/);
+ const width = stdout.match(/Width:\s+(\d+)/);
+ const height = stdout.match(/Height:\s+(\d+)/);
+
+ if (!absX || !absY || !width || !height) {
+ return null;
+ }
+
+ return {
+ x: Number.parseInt(absX[1], 10),
+ y: Number.parseInt(absY[1], 10),
+ width: Number.parseInt(width[1], 10),
+ height: Number.parseInt(height[1], 10),
+ };
+}
+
+export async function resolveLinuxWindowBounds(
+ source: SelectedSource,
+): Promise {
+ const windowId = parseWindowId(source?.id);
+
+ if (windowId) {
+ try {
+ const { stdout } = await execFileAsync("xwininfo", ["-id", String(windowId)], {
+ timeout: 1500,
+ });
+ const bounds = parseXwininfoBounds(stdout);
+ if (bounds && bounds.width > 0 && bounds.height > 0) {
+ return bounds;
+ }
+ } catch {
+ // fall back to title lookup below
+ }
+ }
+
+ const windowTitle =
+ typeof source.windowTitle === "string" ? source.windowTitle.trim() : source.name.trim();
+ if (!windowTitle) {
+ return null;
+ }
+
+ try {
+ const { stdout } = await execFileAsync("xwininfo", ["-name", windowTitle], {
+ timeout: 1500,
+ });
+ const bounds = parseXwininfoBounds(stdout);
+ return bounds && bounds.width > 0 && bounds.height > 0 ? bounds : null;
+ } catch {
+ return null;
+ }
+}
+
+export async function resolveWindowsWindowBounds(
+ source: SelectedSource,
+): Promise {
+ const windowId = parseWindowId(source?.id);
+ const windowTitle =
+ typeof source.windowTitle === "string" ? source.windowTitle.trim() : source.name.trim();
+
+ if (!windowId && !windowTitle) {
+ return null;
+ }
+
+ const script = [
+ "param([string]$windowId, [string]$windowTitle)",
+ 'Add-Type -TypeDefinition @"',
+ "using System;",
+ "using System.Runtime.InteropServices;",
+ "public static class RecordlyWindowBounds {",
+ " [StructLayout(LayoutKind.Sequential)]",
+ " public struct RECT {",
+ " public int Left;",
+ " public int Top;",
+ " public int Right;",
+ " public int Bottom;",
+ " }",
+ ' [DllImport("user32.dll")]',
+ " [return: MarshalAs(UnmanagedType.Bool)]",
+ " public static extern bool GetWindowRect(IntPtr hWnd, out RECT rect);",
+ "}",
+ '"@',
+ "$handle = [Int64]0",
+ "if ($windowId) {",
+ " $handle = [Int64]$windowId",
+ "}",
+ "$escapedWindowTitle = if ($windowTitle) { [WildcardPattern]::Escape($windowTitle) } else { $null }",
+ "if ($handle -le 0 -and $windowTitle) {",
+ ' $matchingProcess = Get-Process | Where-Object { $_.MainWindowTitle -eq $windowTitle -or ($escapedWindowTitle -and $_.MainWindowTitle -like "*$escapedWindowTitle*") } | Select-Object -First 1',
+ " if ($matchingProcess) {",
+ " $handle = $matchingProcess.MainWindowHandle.ToInt64()",
+ " }",
+ "}",
+ "if ($handle -le 0) {",
+ " exit 1",
+ "}",
+ "$rect = New-Object RecordlyWindowBounds+RECT",
+ "if (-not [RecordlyWindowBounds]::GetWindowRect([IntPtr]$handle, [ref]$rect)) {",
+ " exit 1",
+ "}",
+ "@{ x = $rect.Left; y = $rect.Top; width = $rect.Right - $rect.Left; height = $rect.Bottom - $rect.Top } | ConvertTo-Json -Compress",
+ ].join("\n");
+
+ try {
+ const { stdout } = await execFileAsync(
+ "powershell.exe",
+ ["-NoProfile", "-Command", script, String(windowId ?? ""), windowTitle],
+ { timeout: 1500 },
+ );
+ const bounds = JSON.parse(stdout) as WindowBounds;
+ return bounds && bounds.width > 0 && bounds.height > 0 ? bounds : null;
+ } catch {
+ return null;
+ }
+}
+
+export function stopInteractionCapture() {
+ if (interactionCaptureCleanup) {
+ interactionCaptureCleanup();
+ setInteractionCaptureCleanup(null);
+ }
+}
+
+export function stopWindowBoundsCapture() {
+ if (windowBoundsCaptureInterval) {
+ clearInterval(windowBoundsCaptureInterval);
+ setWindowBoundsCaptureInterval(null);
+ }
+ setSelectedWindowBounds(null);
+}
+
+async function refreshSelectedWindowBounds() {
+ if (!selectedSource?.id?.startsWith("window:")) {
+ setSelectedWindowBounds(null);
+ return;
+ }
+
+ let bounds: WindowBounds | null = null;
+
+ if (process.platform === "darwin") {
+ bounds = await resolveMacWindowBounds(selectedSource);
+ } else if (process.platform === "win32") {
+ bounds = await resolveWindowsWindowBounds(selectedSource);
+ } else if (process.platform === "linux") {
+ bounds = await resolveLinuxWindowBounds(selectedSource);
+ }
+
+ setSelectedWindowBounds(bounds);
+}
+
+export function startWindowBoundsCapture() {
+ stopWindowBoundsCapture();
+
+ if (
+ !["darwin", "win32", "linux"].includes(process.platform) ||
+ !selectedSource?.id?.startsWith("window:")
+ ) {
+ return;
+ }
+
+ void refreshSelectedWindowBounds();
+ setWindowBoundsCaptureInterval(
+ setInterval(() => {
+ void refreshSelectedWindowBounds();
+ }, 250),
+ );
+}
diff --git a/electron/ipc/cursor/interaction.test.ts b/electron/ipc/cursor/interaction.test.ts
new file mode 100644
index 000000000..4ea662414
--- /dev/null
+++ b/electron/ipc/cursor/interaction.test.ts
@@ -0,0 +1,92 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("electron", () => ({
+ app: {
+ getPath: vi.fn(() => "/tmp"),
+ setPath: vi.fn(),
+ isReady: vi.fn(() => true),
+ },
+}));
+
+import {
+ repairBundledUiohookBinaryForCurrentArch,
+ shouldStartGlobalInteractionHook,
+} from "./interaction";
+
+describe("shouldStartGlobalInteractionHook", () => {
+ it("does not start the synchronous uiohook event tap on macOS", () => {
+ expect(shouldStartGlobalInteractionHook("darwin")).toBe(false);
+ });
+
+ it("keeps global interaction capture enabled on Windows and Linux", () => {
+ expect(shouldStartGlobalInteractionHook("win32")).toBe(true);
+ expect(shouldStartGlobalInteractionHook("linux")).toBe(true);
+ });
+});
+
+describe("repairBundledUiohookBinaryForCurrentArch", () => {
+ const tempRoots: string[] = [];
+
+ afterEach(async () => {
+ await Promise.all(
+ tempRoots
+ .splice(0)
+ .map((tempRoot) => fs.rm(tempRoot, { recursive: true, force: true })),
+ );
+ });
+
+ it("promotes the bundled darwin-arm64 prebuild over a stale incompatible build", async () => {
+ const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-uiohook-"));
+ tempRoots.push(tempRoot);
+
+ const packageRoot = path.join(tempRoot, "uiohook-napi");
+ const prebuildPath = path.join(packageRoot, "prebuilds", "darwin-arm64", "node.napi.node");
+ const buildPath = path.join(packageRoot, "build", "Release", "uiohook_napi.node");
+ await fs.mkdir(path.dirname(prebuildPath), { recursive: true });
+ await fs.mkdir(path.dirname(buildPath), { recursive: true });
+ await fs.writeFile(prebuildPath, "arm64-prebuild");
+ await fs.writeFile(buildPath, "x64-build");
+
+ const log = vi.fn();
+ const repaired = repairBundledUiohookBinaryForCurrentArch(
+ Object.assign(
+ new Error(
+ "mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64')",
+ ),
+ {
+ code: "ERR_DLOPEN_FAILED",
+ },
+ ),
+ { packageRoot, platform: "darwin", arch: "arm64", log },
+ );
+
+ expect(repaired).toBe(true);
+ expect(await fs.readFile(buildPath, "utf8")).toBe("arm64-prebuild");
+ expect(log).toHaveBeenCalledWith(
+ "[CursorTelemetry] Repaired stale uiohook-napi binary using bundled darwin-arm64 prebuild.",
+ );
+ });
+
+ it("does not rewrite binaries for unrelated load failures", async () => {
+ const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-uiohook-"));
+ tempRoots.push(tempRoot);
+
+ const packageRoot = path.join(tempRoot, "uiohook-napi");
+ const buildPath = path.join(packageRoot, "build", "Release", "uiohook_napi.node");
+ await fs.mkdir(path.dirname(buildPath), { recursive: true });
+ await fs.writeFile(buildPath, "existing-build");
+
+ const repaired = repairBundledUiohookBinaryForCurrentArch(
+ Object.assign(new Error("some other dlopen failure"), {
+ code: "ERR_DLOPEN_FAILED",
+ }),
+ { packageRoot, platform: "darwin", arch: "arm64" },
+ );
+
+ expect(repaired).toBe(false);
+ expect(await fs.readFile(buildPath, "utf8")).toBe("existing-build");
+ });
+});
diff --git a/electron/ipc/cursor/interaction.ts b/electron/ipc/cursor/interaction.ts
new file mode 100644
index 000000000..47c42437f
--- /dev/null
+++ b/electron/ipc/cursor/interaction.ts
@@ -0,0 +1,333 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import {
+ hasLoggedInteractionHookFailure,
+ interactionCaptureCleanup,
+ isCursorCaptureActive,
+ lastLeftClick,
+ setHasLoggedInteractionHookFailure,
+ setInteractionCaptureCleanup,
+ setLastLeftClick,
+ setLinuxCursorScreenPoint,
+} from "../state";
+import type {
+ CursorInteractionType,
+ HookMouseEvent,
+ UiohookLike,
+ UiohookModuleNamespace,
+} from "../types";
+import {
+ getCursorCaptureElapsedMs,
+ getHookCursorScreenPoint,
+ getNormalizedCursorPoint,
+ isCursorCapturePaused,
+ pushCursorSample,
+} from "./telemetry";
+
+const nodeRequire = createRequire(import.meta.url);
+
+export function normalizeHookMouseButton(rawButton: unknown): 1 | 2 | 3 {
+ if (typeof rawButton !== "number" || !Number.isFinite(rawButton)) {
+ return 1;
+ }
+
+ if (rawButton === 2 || rawButton === 39) {
+ return 2;
+ }
+
+ if (rawButton === 3 || rawButton === 38) {
+ return 3;
+ }
+
+ return 1;
+}
+
+export function getHookMouseButton(event: HookMouseEvent | null | undefined): 1 | 2 | 3 {
+ return normalizeHookMouseButton(
+ event?.button ?? event?.mouseButton ?? event?.data?.button ?? event?.data?.mouseButton,
+ );
+}
+
+export function stopInteractionCapture() {
+ if (interactionCaptureCleanup) {
+ interactionCaptureCleanup();
+ setInteractionCaptureCleanup(null);
+ }
+}
+
+function isUiohookLike(value: unknown): value is UiohookLike {
+ const candidate = value as Partial | null;
+ return typeof candidate?.on === "function" && typeof candidate?.start === "function";
+}
+
+function resolveUiohookModule(moduleExports: UiohookModuleNamespace) {
+ const defaultExport = moduleExports.default;
+
+ if (moduleExports.uIOhook) {
+ return moduleExports.uIOhook;
+ }
+
+ if (moduleExports.uiohook) {
+ return moduleExports.uiohook;
+ }
+
+ if (moduleExports.Uiohook) {
+ return moduleExports.Uiohook;
+ }
+
+ if (isUiohookLike(defaultExport)) {
+ return defaultExport;
+ }
+
+ if (defaultExport?.uIOhook) {
+ return defaultExport.uIOhook;
+ }
+
+ if (defaultExport?.uiohook) {
+ return defaultExport.uiohook;
+ }
+
+ if (defaultExport?.Uiohook) {
+ return defaultExport.Uiohook;
+ }
+
+ return null;
+}
+
+function shouldRepairBundledUiohookBinary(error: unknown): error is NodeJS.ErrnoException {
+ if (process.platform !== "darwin") {
+ return false;
+ }
+
+ if (process.arch !== "arm64") {
+ return false;
+ }
+
+ const candidate = error as NodeJS.ErrnoException | null;
+ return (
+ candidate?.code === "ERR_DLOPEN_FAILED" &&
+ typeof candidate.message === "string" &&
+ candidate.message.includes("incompatible architecture")
+ );
+}
+
+export function repairBundledUiohookBinaryForCurrentArch(
+ error: unknown,
+ options?: {
+ packageRoot?: string;
+ platform?: NodeJS.Platform;
+ arch?: string;
+ log?: (message: string) => void;
+ },
+) {
+ const platform = options?.platform ?? process.platform;
+ const arch = options?.arch ?? process.arch;
+
+ if (platform !== "darwin" || arch !== "arm64") {
+ return false;
+ }
+
+ const candidate = error as NodeJS.ErrnoException | null;
+ if (
+ candidate?.code !== "ERR_DLOPEN_FAILED" ||
+ typeof candidate.message !== "string" ||
+ !candidate.message.includes("incompatible architecture")
+ ) {
+ return false;
+ }
+
+ const packageRoot =
+ options?.packageRoot ?? path.dirname(nodeRequire.resolve("uiohook-napi/package.json"));
+ const prebuildPath = path.join(packageRoot, "prebuilds", `darwin-${arch}`, "node.napi.node");
+ const buildPath = path.join(packageRoot, "build", "Release", "uiohook_napi.node");
+
+ if (!fs.existsSync(prebuildPath)) {
+ return false;
+ }
+
+ try {
+ fs.mkdirSync(path.dirname(buildPath), { recursive: true });
+ fs.copyFileSync(prebuildPath, buildPath);
+ (options?.log ?? console.warn)(
+ "[CursorTelemetry] Repaired stale uiohook-napi binary using bundled darwin-arm64 prebuild.",
+ );
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function loadUiohookModule() {
+ try {
+ const moduleExports = nodeRequire("uiohook-napi") as UiohookModuleNamespace;
+ return resolveUiohookModule(moduleExports);
+ } catch (error) {
+ if (!shouldRepairBundledUiohookBinary(error)) {
+ throw error;
+ }
+
+ if (!repairBundledUiohookBinaryForCurrentArch(error)) {
+ throw error;
+ }
+
+ delete nodeRequire.cache[nodeRequire.resolve("uiohook-napi")];
+ const moduleExports = nodeRequire("uiohook-napi") as UiohookModuleNamespace;
+ return resolveUiohookModule(moduleExports);
+ }
+}
+
+export function shouldStartGlobalInteractionHook(platform: NodeJS.Platform = process.platform) {
+ // On macOS, uiohook can block forever while its native event tap starts
+ // (notably when Accessibility permission is unavailable or stale). Because
+ // start() executes synchronously, that freezes Electron's main thread and
+ // makes every window, including the recording HUD, unresponsive. Cursor
+ // position and visual-state telemetry still come from the existing native
+ // macOS monitor and Electron sampler.
+ return platform !== "darwin";
+}
+
+export function recordCursorMouseDown(button: 1 | 2 | 3) {
+ if (!isCursorCaptureActive || isCursorCapturePaused()) {
+ return;
+ }
+
+ const point = getNormalizedCursorPoint();
+ if (!point) {
+ return;
+ }
+
+ const timeMs = getCursorCaptureElapsedMs();
+ let interactionType: CursorInteractionType = "click";
+
+ if (button === 2) {
+ interactionType = "right-click";
+ } else if (button === 3) {
+ interactionType = "middle-click";
+ } else {
+ const thresholdMs = 350;
+ const distance = lastLeftClick
+ ? Math.hypot(point.cx - lastLeftClick.cx, point.cy - lastLeftClick.cy)
+ : Number.POSITIVE_INFINITY;
+
+ if (lastLeftClick && timeMs - lastLeftClick.timeMs <= thresholdMs && distance <= 0.04) {
+ interactionType = "double-click";
+ }
+
+ setLastLeftClick({ timeMs, cx: point.cx, cy: point.cy });
+ }
+
+ pushCursorSample(point.cx, point.cy, timeMs, interactionType);
+}
+
+export function recordCursorMouseUp() {
+ if (!isCursorCaptureActive || isCursorCapturePaused()) {
+ return;
+ }
+
+ const point = getNormalizedCursorPoint();
+ if (!point) {
+ return;
+ }
+
+ pushCursorSample(point.cx, point.cy, getCursorCaptureElapsedMs(), "mouseup");
+}
+
+export async function startInteractionCapture() {
+ if (!isCursorCaptureActive) {
+ return;
+ }
+
+ if (!["darwin", "win32", "linux"].includes(process.platform)) {
+ return;
+ }
+
+ if (!shouldStartGlobalInteractionHook()) {
+ console.warn("[CursorTelemetry] Skipping the blocking global interaction hook on macOS.");
+ return;
+ }
+
+ stopInteractionCapture();
+
+ try {
+ const hook = loadUiohookModule();
+ console.log(
+ "[CursorTelemetry] hook loaded:",
+ !!hook,
+ "has.on:",
+ typeof hook?.on,
+ "has.start:",
+ typeof hook?.start,
+ );
+ if (!isCursorCaptureActive) {
+ return;
+ }
+
+ if (!hook || typeof hook.on !== "function" || typeof hook.start !== "function") {
+ console.log("[CursorTelemetry] hook unusable — aborting interaction capture");
+ return;
+ }
+
+ const onMouseDown = (event: HookMouseEvent) => {
+ recordCursorMouseDown(getHookMouseButton(event));
+ };
+
+ const onMouseUp = () => {
+ recordCursorMouseUp();
+ };
+
+ const onMouseMove = (event: HookMouseEvent) => {
+ if (process.platform !== "linux" || !isCursorCaptureActive || isCursorCapturePaused()) {
+ return;
+ }
+
+ const point = getHookCursorScreenPoint(event);
+ if (!point) {
+ return;
+ }
+
+ setLinuxCursorScreenPoint({ x: point.x, y: point.y, updatedAt: Date.now() });
+ };
+
+ hook.on("mousedown", onMouseDown);
+ hook.on("mouseup", onMouseUp);
+ if (process.platform === "linux") {
+ hook.on("mousemove", onMouseMove);
+ }
+
+ setInteractionCaptureCleanup(() => {
+ try {
+ if (typeof hook.off === "function") {
+ hook.off("mousedown", onMouseDown);
+ hook.off("mouseup", onMouseUp);
+ if (process.platform === "linux") {
+ hook.off("mousemove", onMouseMove);
+ }
+ } else if (typeof hook.removeListener === "function") {
+ hook.removeListener("mousedown", onMouseDown);
+ hook.removeListener("mouseup", onMouseUp);
+ if (process.platform === "linux") {
+ hook.removeListener("mousemove", onMouseMove);
+ }
+ }
+ } catch {
+ // ignore listener cleanup errors
+ }
+
+ try {
+ if (typeof hook.stop === "function") {
+ hook.stop();
+ }
+ } catch {
+ // ignore hook shutdown errors
+ }
+ });
+
+ hook.start();
+ } catch (error) {
+ if (!hasLoggedInteractionHookFailure) {
+ setHasLoggedInteractionHookFailure(true);
+ console.warn("[CursorTelemetry] Global interaction capture unavailable:", error);
+ }
+ }
+}
diff --git a/electron/ipc/cursor/monitor.ts b/electron/ipc/cursor/monitor.ts
new file mode 100644
index 000000000..8a507d56d
--- /dev/null
+++ b/electron/ipc/cursor/monitor.ts
@@ -0,0 +1,163 @@
+import { spawn } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import { BrowserWindow } from "electron";
+import { ensureNativeCursorMonitorBinary, getCursorMonitorExePath } from "../paths/binaries";
+import {
+ currentCursorVisualType,
+ nativeCursorMonitorOutputBuffer,
+ nativeCursorMonitorProcess,
+ setCurrentCursorVisualType,
+ setNativeCursorMonitorOutputBuffer,
+ setNativeCursorMonitorProcess,
+} from "../state";
+import type { CursorVisualType } from "../types";
+import { recordCursorMouseDown, recordCursorMouseUp } from "./interaction";
+
+export function emitCursorStateChanged(cursorType: CursorVisualType) {
+ BrowserWindow.getAllWindows().forEach((window) => {
+ if (!window.isDestroyed()) {
+ window.webContents.send("cursor-state-changed", { cursorType });
+ }
+ });
+}
+
+export function handleCursorMonitorStdout(chunk: Buffer) {
+ setNativeCursorMonitorOutputBuffer(nativeCursorMonitorOutputBuffer + chunk.toString());
+ const lines = nativeCursorMonitorOutputBuffer.split(/\r?\n/);
+ setNativeCursorMonitorOutputBuffer(lines.pop() ?? "");
+
+ for (const line of lines) {
+ const interactionMatch = line.match(/^INTERACTION:(mousedown|mouseup)(?::([123]))?$/);
+ if (interactionMatch) {
+ if (interactionMatch[1] === "mouseup") {
+ recordCursorMouseUp();
+ } else {
+ const button = Number(interactionMatch[2]);
+ recordCursorMouseDown(button === 2 || button === 3 ? button : 1);
+ }
+ continue;
+ }
+
+ const match = line.match(/^STATE:(.+)$/);
+ if (!match) continue;
+ const next = match[1].trim() as CursorVisualType;
+ if (
+ next === "arrow" ||
+ next === "text" ||
+ next === "pointer" ||
+ next === "crosshair" ||
+ next === "open-hand" ||
+ next === "closed-hand" ||
+ next === "resize-ew" ||
+ next === "resize-ns" ||
+ next === "not-allowed"
+ ) {
+ if (currentCursorVisualType !== next) {
+ setCurrentCursorVisualType(next);
+ // sampleCursorStateChange is called from cursor/telemetry.ts via the handler
+ emitCursorStateChanged(next);
+ }
+ }
+ }
+}
+
+export function stopNativeCursorMonitor() {
+ setCurrentCursorVisualType("arrow");
+
+ if (!nativeCursorMonitorProcess) {
+ return;
+ }
+
+ try {
+ nativeCursorMonitorProcess.stdin.write("stop\n");
+ } catch {
+ // ignore stop signal issues
+ }
+ try {
+ nativeCursorMonitorProcess.kill();
+ } catch {
+ // ignore kill issues
+ }
+
+ setNativeCursorMonitorProcess(null);
+ setNativeCursorMonitorOutputBuffer("");
+}
+
+export async function startNativeCursorMonitor() {
+ stopNativeCursorMonitor();
+
+ if (process.platform !== "darwin" && process.platform !== "win32") {
+ setCurrentCursorVisualType("arrow");
+ return;
+ }
+
+ try {
+ let helperPath: string;
+ if (process.platform === "win32") {
+ helperPath = getCursorMonitorExePath();
+ try {
+ // Use F_OK on Windows — X_OK is meaningless and can give false positives
+ await fs.access(helperPath, fsConstants.F_OK);
+ } catch {
+ console.warn("Windows cursor monitor helper missing:", helperPath);
+ setCurrentCursorVisualType("arrow");
+ return;
+ }
+ } else {
+ helperPath = await ensureNativeCursorMonitorBinary();
+ }
+
+ setNativeCursorMonitorOutputBuffer("");
+ setCurrentCursorVisualType("arrow");
+
+ let proc: ReturnType | null;
+ try {
+ proc = spawn(helperPath, [], {
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ } catch (spawnError) {
+ console.warn("Failed to spawn cursor monitor:", spawnError);
+ setNativeCursorMonitorProcess(null);
+ setCurrentCursorVisualType("arrow");
+ return;
+ }
+
+ setNativeCursorMonitorProcess(proc as Parameters[0]);
+ const spawned = proc;
+ if (!spawned) {
+ setNativeCursorMonitorProcess(null);
+ setCurrentCursorVisualType("arrow");
+ return;
+ }
+
+ spawned.once("error", (error) => {
+ console.warn("Native cursor monitor process error:", error);
+ if (nativeCursorMonitorProcess === spawned) {
+ setNativeCursorMonitorProcess(null);
+ setNativeCursorMonitorOutputBuffer("");
+ setCurrentCursorVisualType("arrow");
+ }
+ });
+
+ if (spawned.stdout) spawned.stdout.on("data", handleCursorMonitorStdout);
+ if (spawned.stderr) {
+ spawned.stderr.on("data", () => {
+ // Drain stderr so helper logging cannot block the process.
+ });
+ }
+
+ spawned.once("close", () => {
+ if (nativeCursorMonitorProcess === spawned) {
+ setNativeCursorMonitorProcess(null);
+ setNativeCursorMonitorOutputBuffer("");
+ setCurrentCursorVisualType("arrow");
+ }
+ });
+ } catch (error) {
+ console.warn("Failed to start native cursor monitor:", error);
+ setNativeCursorMonitorProcess(null);
+ setNativeCursorMonitorOutputBuffer("");
+ setCurrentCursorVisualType("arrow");
+ }
+}
diff --git a/electron/ipc/cursor/telemetry.test.ts b/electron/ipc/cursor/telemetry.test.ts
new file mode 100644
index 000000000..03613859b
--- /dev/null
+++ b/electron/ipc/cursor/telemetry.test.ts
@@ -0,0 +1,122 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { CURSOR_TELEMETRY_VERSION } from "../constants";
+
+const { writeFile, rm } = vi.hoisted(() => ({
+ writeFile: vi.fn(),
+ rm: vi.fn(),
+}));
+
+vi.mock("node:fs/promises", () => ({
+ default: {
+ writeFile,
+ rm,
+ },
+}));
+
+vi.mock("electron", () => ({
+ app: {
+ getPath: vi.fn(() => "/tmp"),
+ },
+}));
+
+vi.mock("../utils", () => ({
+ getTelemetryPathForVideo: vi.fn(() => "/tmp/recording.cursor.json"),
+ getScreen: vi.fn(() => ({
+ getCursorScreenPoint: () => ({ x: 0, y: 0 }),
+ getPrimaryDisplay: () => ({ scaleFactor: 1 }),
+ getDisplayNearestPoint: () => ({ bounds: { x: 0, y: 0, width: 1, height: 1 } }),
+ getAllDisplays: () => [],
+ })),
+}));
+
+import { activeCursorSamples, setActiveCursorSamples, setCursorCaptureStartTimeMs } from "../state";
+import {
+ getCursorCaptureElapsedMs,
+ normalizeCursorTelemetrySamples,
+ pauseCursorCapture,
+ pauseCursorCaptureAtBoundary,
+ pushCursorSample,
+ resetCursorCaptureClock,
+ resumeCursorCapture,
+ writeCursorTelemetry,
+} from "./telemetry";
+
+describe("cursor telemetry pause clock", () => {
+ beforeEach(() => {
+ writeFile.mockReset();
+ rm.mockReset();
+ setCursorCaptureStartTimeMs(1_000);
+ setActiveCursorSamples([]);
+ resetCursorCaptureClock();
+ });
+
+ it("subtracts paused time from elapsed cursor timestamps", () => {
+ expect(getCursorCaptureElapsedMs(1_120)).toBe(120);
+
+ pauseCursorCapture(1_200);
+ expect(getCursorCaptureElapsedMs(1_450)).toBe(200);
+
+ resumeCursorCapture(1_700);
+ expect(getCursorCaptureElapsedMs(1_900)).toBe(400);
+ });
+
+ it("ignores duplicate pause or resume transitions", () => {
+ pauseCursorCapture(1_150);
+ pauseCursorCapture(1_250);
+ resumeCursorCapture(1_500);
+ resumeCursorCapture(1_650);
+
+ expect(getCursorCaptureElapsedMs(1_900)).toBe(550);
+ });
+
+ it("drops cursor samples captured after the renderer pause boundary", () => {
+ pushCursorSample(0.1, 0.1, 120, "move");
+ pushCursorSample(0.2, 0.2, 205, "move");
+ pushCursorSample(0.3, 0.3, 260, "move");
+
+ pauseCursorCaptureAtBoundary(1_200);
+
+ expect(getCursorCaptureElapsedMs(1_500)).toBe(200);
+ expect(activeCursorSamples.map((sample) => sample.timeMs)).toEqual([120]);
+
+ resumeCursorCapture(1_700);
+ expect(getCursorCaptureElapsedMs(1_900)).toBe(400);
+ });
+
+ it("normalizes cursor telemetry samples before persisting them", async () => {
+ const samples = normalizeCursorTelemetrySamples([
+ { timeMs: 30, cx: 2, cy: -1, interactionType: "click", cursorType: "pointer" },
+ { timeMs: -10, cx: Number.NaN, cy: 0.2, interactionType: "drag", cursorType: "ibeam" },
+ { timeMs: 10, cx: 0.25, cy: 0.75, interactionType: "move", cursorType: "text" },
+ ]);
+
+ expect(samples).toEqual([
+ { timeMs: 0, cx: 0.5, cy: 0.2, interactionType: undefined, cursorType: undefined },
+ { timeMs: 10, cx: 0.25, cy: 0.75, interactionType: "move", cursorType: "text" },
+ { timeMs: 30, cx: 1, cy: 0, interactionType: "click", cursorType: "pointer" },
+ ]);
+
+ await writeCursorTelemetry("/tmp/recording.mp4", samples);
+
+ expect(writeFile).toHaveBeenCalledWith(
+ "/tmp/recording.cursor.json",
+ JSON.stringify(
+ {
+ version: CURSOR_TELEMETRY_VERSION,
+ samples,
+ },
+ null,
+ 2,
+ ),
+ "utf-8",
+ );
+ expect(rm).not.toHaveBeenCalled();
+ });
+
+ it("removes the sidecar when saving an empty cursor telemetry payload", async () => {
+ await writeCursorTelemetry("/tmp/recording.mp4", []);
+
+ expect(rm).toHaveBeenCalledWith("/tmp/recording.cursor.json", { force: true });
+ expect(writeFile).not.toHaveBeenCalled();
+ });
+});
diff --git a/electron/ipc/cursor/telemetry.ts b/electron/ipc/cursor/telemetry.ts
new file mode 100644
index 000000000..fd598b102
--- /dev/null
+++ b/electron/ipc/cursor/telemetry.ts
@@ -0,0 +1,331 @@
+import fs from "node:fs/promises";
+import {
+ CURSOR_SAMPLE_INTERVAL_MS,
+ CURSOR_TELEMETRY_VERSION,
+ MAX_CURSOR_SAMPLES,
+} from "../constants";
+import {
+ activeCursorSamples,
+ currentCursorVisualType,
+ cursorCaptureAccumulatedPausedMs,
+ cursorCaptureInterval,
+ cursorCapturePauseStartedAtMs,
+ cursorCaptureStartTimeMs,
+ isCursorCaptureActive,
+ linuxCursorScreenPoint,
+ pendingCursorSamples,
+ selectedSource,
+ selectedWindowBounds,
+ setActiveCursorSamples,
+ setCursorCaptureAccumulatedPausedMs,
+ setCursorCaptureInterval,
+ setCursorCapturePauseStartedAtMs,
+ setPendingCursorSamples,
+} from "../state";
+import type { CursorInteractionType, CursorTelemetryPoint, CursorVisualType } from "../types";
+import { getScreen, getTelemetryPathForVideo } from "../utils";
+
+export function clamp(value: number, min: number, max: number) {
+ return Math.min(max, Math.max(min, value));
+}
+
+export function normalizeCursorTelemetrySamples(rawSamples: unknown): CursorTelemetryPoint[] {
+ const samples = Array.isArray(rawSamples)
+ ? rawSamples
+ : Array.isArray((rawSamples as { samples?: unknown[] } | null | undefined)?.samples)
+ ? ((rawSamples as { samples: unknown[] }).samples ?? [])
+ : [];
+ const boundedSamples = samples.slice(0, MAX_CURSOR_SAMPLES);
+
+ return boundedSamples
+ .filter((sample: unknown) => Boolean(sample && typeof sample === "object"))
+ .map((sample: unknown) => {
+ const point = sample as Partial;
+ return {
+ timeMs:
+ typeof point.timeMs === "number" && Number.isFinite(point.timeMs)
+ ? Math.max(0, point.timeMs)
+ : 0,
+ cx:
+ typeof point.cx === "number" && Number.isFinite(point.cx)
+ ? clamp(point.cx, 0, 1)
+ : 0.5,
+ cy:
+ typeof point.cy === "number" && Number.isFinite(point.cy)
+ ? clamp(point.cy, 0, 1)
+ : 0.5,
+ interactionType:
+ point.interactionType === "click" ||
+ point.interactionType === "double-click" ||
+ point.interactionType === "right-click" ||
+ point.interactionType === "middle-click" ||
+ point.interactionType === "move" ||
+ point.interactionType === "mouseup"
+ ? point.interactionType
+ : undefined,
+ cursorType:
+ point.cursorType === "arrow" ||
+ point.cursorType === "text" ||
+ point.cursorType === "pointer" ||
+ point.cursorType === "crosshair" ||
+ point.cursorType === "open-hand" ||
+ point.cursorType === "closed-hand" ||
+ point.cursorType === "resize-ew" ||
+ point.cursorType === "resize-ns" ||
+ point.cursorType === "not-allowed"
+ ? point.cursorType
+ : undefined,
+ };
+ })
+ .sort((a, b) => a.timeMs - b.timeMs);
+}
+
+export async function writeCursorTelemetry(videoPath: string, samples: unknown) {
+ const telemetryPath = getTelemetryPathForVideo(videoPath);
+ const normalizedSamples = normalizeCursorTelemetrySamples(samples);
+
+ if (normalizedSamples.length === 0) {
+ await fs.rm(telemetryPath, { force: true });
+ return normalizedSamples;
+ }
+
+ await fs.writeFile(
+ telemetryPath,
+ JSON.stringify({ version: CURSOR_TELEMETRY_VERSION, samples: normalizedSamples }, null, 2),
+ "utf-8",
+ );
+
+ return normalizedSamples;
+}
+
+export function stopCursorCapture() {
+ if (cursorCaptureInterval) {
+ clearTimeout(cursorCaptureInterval);
+ setCursorCaptureInterval(null);
+ }
+}
+
+export function resetCursorCaptureClock() {
+ setCursorCaptureAccumulatedPausedMs(0);
+ setCursorCapturePauseStartedAtMs(null);
+}
+
+export function isCursorCapturePaused() {
+ return cursorCapturePauseStartedAtMs !== null;
+}
+
+export function pauseCursorCapture(pausedAtMs: number) {
+ if (cursorCapturePauseStartedAtMs !== null) {
+ return;
+ }
+
+ setCursorCapturePauseStartedAtMs(pausedAtMs);
+}
+
+export function pauseCursorCaptureAtBoundary(pausedAtMs: number) {
+ if (cursorCapturePauseStartedAtMs !== null) {
+ return;
+ }
+
+ const pausedElapsedMs = getCursorCaptureElapsedMs(pausedAtMs);
+ setActiveCursorSamples(
+ activeCursorSamples.filter((sample) => sample.timeMs <= pausedElapsedMs),
+ );
+ setCursorCapturePauseStartedAtMs(pausedAtMs);
+}
+
+export function resumeCursorCapture(resumedAtMs: number) {
+ if (cursorCapturePauseStartedAtMs === null) {
+ return;
+ }
+
+ const pauseDurationMs = Math.max(0, resumedAtMs - cursorCapturePauseStartedAtMs);
+ setCursorCaptureAccumulatedPausedMs(cursorCaptureAccumulatedPausedMs + pauseDurationMs);
+ setCursorCapturePauseStartedAtMs(null);
+}
+
+export function getCursorCaptureElapsedMs(nowMs = Date.now()) {
+ if (!Number.isFinite(cursorCaptureStartTimeMs) || cursorCaptureStartTimeMs <= 0) {
+ return 0;
+ }
+
+ const safeNowMs = Math.max(cursorCaptureStartTimeMs, nowMs);
+ const activePauseDurationMs =
+ cursorCapturePauseStartedAtMs === null
+ ? 0
+ : Math.max(0, safeNowMs - cursorCapturePauseStartedAtMs);
+
+ return Math.max(
+ 0,
+ safeNowMs -
+ cursorCaptureStartTimeMs -
+ Math.max(0, cursorCaptureAccumulatedPausedMs) -
+ activePauseDurationMs,
+ );
+}
+
+export function getNormalizedCursorPoint() {
+ const fallbackCursor = getScreen().getCursorScreenPoint();
+ const linuxCursorCache = process.platform === "linux" ? linuxCursorScreenPoint : null;
+ const isLinuxCacheFresh = !!linuxCursorCache && Date.now() - linuxCursorCache.updatedAt <= 1000;
+
+ const primarySf =
+ process.platform !== "darwin" ? getScreen().getPrimaryDisplay().scaleFactor || 1 : 1;
+
+ const cursor = isLinuxCacheFresh
+ ? { x: linuxCursorCache.x / primarySf, y: linuxCursorCache.y / primarySf }
+ : fallbackCursor;
+
+ const windowBounds = selectedSource?.id?.startsWith("window:") ? selectedWindowBounds : null;
+ if (windowBounds) {
+ const sf =
+ process.platform !== "darwin"
+ ? getScreen().getDisplayNearestPoint({
+ x: windowBounds.x / primarySf,
+ y: windowBounds.y / primarySf,
+ }).scaleFactor || 1
+ : 1;
+ const width = Math.max(1, windowBounds.width / sf);
+ const height = Math.max(1, windowBounds.height / sf);
+
+ return {
+ cx: clamp((cursor.x - windowBounds.x / sf) / width, 0, 1),
+ cy: clamp((cursor.y - windowBounds.y / sf) / height, 0, 1),
+ };
+ }
+
+ const sourceDisplayId = Number(selectedSource?.display_id);
+ const sourceDisplay = Number.isFinite(sourceDisplayId)
+ ? (getScreen()
+ .getAllDisplays()
+ .find((display) => display.id === sourceDisplayId) ?? null)
+ : null;
+ const display = sourceDisplay ?? getScreen().getDisplayNearestPoint(cursor);
+ const bounds = display.bounds;
+ const width = Math.max(1, bounds.width);
+ const height = Math.max(1, bounds.height);
+
+ const cx = clamp((cursor.x - bounds.x) / width, 0, 1);
+ const cy = clamp((cursor.y - bounds.y) / height, 0, 1);
+ return { cx, cy };
+}
+
+export function getHookCursorScreenPoint(
+ event:
+ | {
+ x?: number;
+ y?: number;
+ data?: { x?: number; y?: number; screenX?: number; screenY?: number };
+ screenX?: number;
+ screenY?: number;
+ }
+ | null
+ | undefined,
+): { x: number; y: number } | null {
+ const rawX = event?.x ?? event?.data?.x ?? event?.screenX ?? event?.data?.screenX;
+ const rawY = event?.y ?? event?.data?.y ?? event?.screenY ?? event?.data?.screenY;
+
+ if (
+ typeof rawX !== "number" ||
+ !Number.isFinite(rawX) ||
+ typeof rawY !== "number" ||
+ !Number.isFinite(rawY)
+ ) {
+ return null;
+ }
+
+ return { x: rawX, y: rawY };
+}
+
+export function pushCursorSample(
+ cx: number,
+ cy: number,
+ timeMs: number,
+ interactionType: CursorInteractionType = "move",
+ cursorType?: CursorVisualType,
+) {
+ activeCursorSamples.push({
+ timeMs: Math.max(0, timeMs),
+ cx,
+ cy,
+ interactionType,
+ cursorType: cursorType ?? currentCursorVisualType,
+ } as CursorTelemetryPoint);
+
+ if (activeCursorSamples.length > MAX_CURSOR_SAMPLES) {
+ activeCursorSamples.shift();
+ }
+}
+
+export function sampleCursorPoint() {
+ const point = getNormalizedCursorPoint();
+ pushCursorSample(point.cx, point.cy, getCursorCaptureElapsedMs(), "move");
+}
+
+export async function persistPendingCursorTelemetry(videoPath: string) {
+ const telemetryPath = getTelemetryPathForVideo(videoPath);
+ if (pendingCursorSamples.length > 0) {
+ await fs.writeFile(
+ telemetryPath,
+ JSON.stringify(
+ { version: CURSOR_TELEMETRY_VERSION, samples: pendingCursorSamples },
+ null,
+ 2,
+ ),
+ "utf-8",
+ );
+ }
+ setPendingCursorSamples([]);
+}
+
+export function snapshotCursorTelemetryForPersistence() {
+ if (activeCursorSamples.length === 0) {
+ return;
+ }
+
+ if (pendingCursorSamples.length === 0) {
+ setPendingCursorSamples([...activeCursorSamples]);
+ return;
+ }
+
+ const lastPendingTimeMs = pendingCursorSamples[pendingCursorSamples.length - 1]?.timeMs ?? -1;
+ setPendingCursorSamples([
+ ...pendingCursorSamples,
+ ...activeCursorSamples.filter((sample) => sample.timeMs > lastPendingTimeMs),
+ ]);
+}
+
+export function startCursorSampling() {
+ stopCursorCapture();
+
+ // Use recursive setTimeout with drift compensation instead of setInterval.
+ // Under CPU load setInterval bunches or skips callbacks, creating large gaps
+ // in telemetry data. This approach measures wall-clock drift each tick and
+ // adjusts the next delay so samples stay close to the target interval.
+ let nextExpectedMs = Date.now() + CURSOR_SAMPLE_INTERVAL_MS;
+
+ const tick = () => {
+ if (isCursorCaptureActive && !isCursorCapturePaused()) {
+ sampleCursorPoint();
+ }
+
+ const now = Date.now();
+ const drift = now - nextExpectedMs;
+ nextExpectedMs += CURSOR_SAMPLE_INTERVAL_MS;
+
+ // If we fell behind by more than one full interval, reset the baseline
+ // so we don't try to "catch up" with a burst of rapid samples.
+ if (drift > CURSOR_SAMPLE_INTERVAL_MS) {
+ nextExpectedMs = now + CURSOR_SAMPLE_INTERVAL_MS;
+ }
+
+ const delay = Math.max(1, nextExpectedMs - now);
+ setCursorCaptureInterval(setTimeout(tick, delay));
+ };
+
+ setCursorCaptureInterval(setTimeout(tick, CURSOR_SAMPLE_INTERVAL_MS));
+}
+
+export { CURSOR_SAMPLE_INTERVAL_MS } from "../constants";
+// Re-export for consumers that use it from this module
+export { getTelemetryPathForVideo } from "../utils";
diff --git a/electron/ipc/export/exportStream.test.ts b/electron/ipc/export/exportStream.test.ts
new file mode 100644
index 000000000..d8889437d
--- /dev/null
+++ b/electron/ipc/export/exportStream.test.ts
@@ -0,0 +1,139 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+const TMP_ROOT = path.join(os.tmpdir(), `recordly-export-stream-test-${Date.now()}`);
+
+vi.mock("electron", () => ({
+ app: {
+ getPath: (key: string) => {
+ if (key === "temp") {
+ return TMP_ROOT;
+ }
+ throw new Error(`Unexpected app.getPath key: ${key}`);
+ },
+ },
+}));
+
+import {
+ cleanupAllExportStreams,
+ closeExportStream,
+ hasExportStream,
+ isOwnedExportPath,
+ openExportStream,
+ writeToExportStream,
+} from "./exportStream";
+
+async function readBytes(filePath: string): Promise {
+ return new Uint8Array(await fs.readFile(filePath));
+}
+
+describe("exportStream", () => {
+ const openedTempPaths: string[] = [];
+
+ beforeAll(async () => {
+ await fs.mkdir(TMP_ROOT, { recursive: true });
+ });
+
+ afterAll(async () => {
+ await fs.rm(TMP_ROOT, { recursive: true, force: true });
+ });
+
+ beforeEach(() => {
+ openedTempPaths.length = 0;
+ });
+
+ afterEach(async () => {
+ await cleanupAllExportStreams();
+ await Promise.allSettled(
+ openedTempPaths.map((tempPath) => fs.rm(tempPath, { force: true })),
+ );
+ });
+
+ it("persists multiple chunks in order and reports the highest watermark on close", async () => {
+ const { streamId, tempPath } = await openExportStream();
+ openedTempPaths.push(tempPath);
+ expect(hasExportStream(streamId)).toBe(true);
+
+ await writeToExportStream(streamId, 0, new Uint8Array([1, 2, 3, 4]));
+ await writeToExportStream(streamId, 4, new Uint8Array([5, 6, 7, 8]));
+
+ const result = await closeExportStream(streamId);
+ expect(result.tempPath).toBe(tempPath);
+ expect(result.bytesWritten).toBe(8);
+
+ const bytes = await readBytes(tempPath);
+ expect(Array.from(bytes)).toEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+ expect(hasExportStream(streamId)).toBe(false);
+ });
+
+ it("supports out-of-order writes and keeps the watermark at the highest offset", async () => {
+ const { streamId, tempPath } = await openExportStream();
+ openedTempPaths.push(tempPath);
+
+ await writeToExportStream(streamId, 16, new Uint8Array([0xff, 0xee]));
+ await writeToExportStream(streamId, 0, new Uint8Array([0x01, 0x02]));
+
+ const result = await closeExportStream(streamId);
+ expect(result.bytesWritten).toBe(18);
+
+ const bytes = await readBytes(tempPath);
+ expect(bytes.byteLength).toBe(18);
+ expect(bytes[0]).toBe(0x01);
+ expect(bytes[1]).toBe(0x02);
+ expect(bytes[16]).toBe(0xff);
+ expect(bytes[17]).toBe(0xee);
+ });
+
+ it("removes the temp file when closed with abort and returns a null tempPath", async () => {
+ const { streamId, tempPath } = await openExportStream();
+ openedTempPaths.push(tempPath);
+ await writeToExportStream(streamId, 0, new Uint8Array([9, 9, 9]));
+
+ const result = await closeExportStream(streamId, { abort: true });
+
+ await expect(fs.access(tempPath)).rejects.toThrow();
+ expect(hasExportStream(streamId)).toBe(false);
+ expect(result.tempPath).toBeNull();
+ expect(result.bytesWritten).toBe(0);
+ expect(isOwnedExportPath(tempPath)).toBe(false);
+ });
+
+ it("tracks open temp paths in the owned-path registry until close", async () => {
+ const { streamId, tempPath } = await openExportStream();
+ openedTempPaths.push(tempPath);
+
+ expect(isOwnedExportPath(tempPath)).toBe(true);
+ // Spoofed paths must not satisfy the registry check.
+ expect(isOwnedExportPath("/tmp/not-ours.mp4")).toBe(false);
+
+ // A successful close keeps ownership so callers can still move or discard
+ // the file via the subsequent IPC call.
+ const result = await closeExportStream(streamId);
+ expect(result.tempPath).toBe(tempPath);
+ expect(isOwnedExportPath(tempPath)).toBe(true);
+ });
+
+ it("rejects writes after the stream has been aborted", async () => {
+ const { streamId, tempPath } = await openExportStream();
+ openedTempPaths.push(tempPath);
+ await closeExportStream(streamId, { abort: true });
+
+ await expect(writeToExportStream(streamId, 0, new Uint8Array([1]))).rejects.toThrow(
+ /Export stream not found/,
+ );
+ });
+
+ it("rejects an extension that would escape the temp directory", async () => {
+ await expect(openExportStream({ extension: "mp4/../etc/passwd" })).rejects.toThrow(
+ /Invalid export stream extension/,
+ );
+ await expect(openExportStream({ extension: ".." })).rejects.toThrow(
+ /Invalid export stream extension/,
+ );
+ await expect(openExportStream({ extension: "MP4" })).rejects.toThrow(
+ /Invalid export stream extension/,
+ );
+ });
+});
diff --git a/electron/ipc/export/exportStream.ts b/electron/ipc/export/exportStream.ts
new file mode 100644
index 000000000..d0aac4067
--- /dev/null
+++ b/electron/ipc/export/exportStream.ts
@@ -0,0 +1,204 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { app } from "electron";
+
+type ExportStreamSession = {
+ streamId: string;
+ sessionDir: string;
+ tempPath: string;
+ fileHandle: fs.promises.FileHandle;
+ bytesWritten: number;
+ highestWatermark: number;
+ writeQueue: Promise;
+ aborted: boolean;
+};
+
+const exportStreamSessions = new Map();
+
+const EXTENSION_ALLOWLIST = /^[a-z0-9]{1,8}$/;
+const SESSION_DIR_PREFIX = "recordly-export-";
+
+// Paths that the export pipeline itself produced (stream temp files plus any
+// successor temp files returned by main-process helpers such as
+// muxNativeVideoExportAudio). Every renderer-facing handler that moves or
+// deletes a path must assert membership here before touching disk, so a
+// compromised renderer can never route arbitrary file paths into the IPC.
+const ownedExportPaths = new Set();
+
+function normalizeOwnedPath(candidate: string): string {
+ return path.resolve(candidate);
+}
+
+export function registerOwnedExportPath(candidate: string): void {
+ ownedExportPaths.add(normalizeOwnedPath(candidate));
+}
+
+export function releaseOwnedExportPath(candidate: string): void {
+ ownedExportPaths.delete(normalizeOwnedPath(candidate));
+}
+
+export function isOwnedExportPath(candidate: string): boolean {
+ return ownedExportPaths.has(normalizeOwnedPath(candidate));
+}
+
+function generateStreamId() {
+ return `recordly-export-stream-${randomUUID()}`;
+}
+
+export async function openExportStream(options?: { extension?: string }): Promise<{
+ streamId: string;
+ tempPath: string;
+}> {
+ const extension = options?.extension ?? "mp4";
+ if (!EXTENSION_ALLOWLIST.test(extension)) {
+ throw new Error(`Invalid export stream extension: ${extension}`);
+ }
+ const streamId = generateStreamId();
+
+ // Per-session 0700 directory defeats TOCTOU/symlink races on shared
+ // tempdirs (e.g. /tmp on Linux): only the current user can enter the dir,
+ // so an adversary cannot pre-plant a symlink at the file path.
+ const sessionDir = await fsp.mkdtemp(path.join(app.getPath("temp"), SESSION_DIR_PREFIX));
+ try {
+ await fsp.chmod(sessionDir, 0o700);
+ } catch {
+ // chmod is a defense-in-depth on platforms where mkdtemp already sets
+ // a safe mode. Non-Linux filesystems may ignore mode bits entirely.
+ }
+ const tempPath = path.join(sessionDir, `${streamId}.${extension}`);
+ const fileHandle = await fsp.open(
+ tempPath,
+ fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL,
+ 0o600,
+ );
+
+ exportStreamSessions.set(streamId, {
+ streamId,
+ sessionDir,
+ tempPath,
+ fileHandle,
+ bytesWritten: 0,
+ highestWatermark: 0,
+ writeQueue: Promise.resolve(),
+ aborted: false,
+ });
+ registerOwnedExportPath(tempPath);
+
+ return { streamId, tempPath };
+}
+
+export async function writeToExportStream(
+ streamId: string,
+ position: number,
+ chunk: Uint8Array,
+): Promise {
+ const session = exportStreamSessions.get(streamId);
+ if (!session) {
+ throw new Error(`Export stream not found: ${streamId}`);
+ }
+
+ if (session.aborted) {
+ throw new Error("Export stream was aborted");
+ }
+
+ // Serialize writes against the session to keep byte counters consistent when
+ // the renderer issues concurrent chunks.
+ const previous = session.writeQueue;
+ const next = previous.then(async () => {
+ if (session.aborted) {
+ return;
+ }
+ const buffer = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+ await session.fileHandle.write(buffer, 0, buffer.byteLength, position);
+ session.bytesWritten += buffer.byteLength;
+ const end = position + buffer.byteLength;
+ if (end > session.highestWatermark) {
+ session.highestWatermark = end;
+ }
+ });
+ session.writeQueue = next.catch(() => undefined);
+ await next;
+}
+
+export async function closeExportStream(
+ streamId: string,
+ options?: { abort?: boolean },
+): Promise<{ tempPath: string | null; bytesWritten: number }> {
+ const session = exportStreamSessions.get(streamId);
+ if (!session) {
+ throw new Error(`Export stream not found: ${streamId}`);
+ }
+
+ const abort = options?.abort === true;
+ if (abort) {
+ session.aborted = true;
+ }
+
+ try {
+ await session.writeQueue;
+ } catch {
+ // Propagated to the in-flight write promise; closure proceeds regardless.
+ }
+
+ try {
+ await session.fileHandle.close();
+ } catch {
+ // File handle may already be closed; ignore so abort paths stay best-effort.
+ }
+
+ exportStreamSessions.delete(streamId);
+
+ if (abort) {
+ releaseOwnedExportPath(session.tempPath);
+ try {
+ await fsp.rm(session.tempPath, { force: true });
+ } catch {
+ // Temp file may be gone already.
+ }
+ try {
+ await fsp.rm(session.sessionDir, { recursive: true, force: true });
+ } catch {
+ // ignore
+ }
+ // Aborted streams return `tempPath: null` so callers cannot accidentally
+ // reuse a path that no longer references a file on disk (or, worse, a
+ // path a later session may recycle).
+ return { tempPath: null, bytesWritten: 0 };
+ }
+
+ return {
+ tempPath: session.tempPath,
+ bytesWritten: session.highestWatermark,
+ };
+}
+
+export function hasExportStream(streamId: string): boolean {
+ return exportStreamSessions.has(streamId);
+}
+
+export async function cleanupAllExportStreams(): Promise {
+ const sessions = Array.from(exportStreamSessions.values());
+ exportStreamSessions.clear();
+ ownedExportPaths.clear();
+ await Promise.allSettled(
+ sessions.map(async (session) => {
+ try {
+ await session.fileHandle.close();
+ } catch {
+ // ignore
+ }
+ try {
+ await fsp.rm(session.tempPath, { force: true });
+ } catch {
+ // ignore
+ }
+ try {
+ await fsp.rm(session.sessionDir, { recursive: true, force: true });
+ } catch {
+ // ignore
+ }
+ }),
+ );
+}
diff --git a/electron/ipc/export/native-video.test.ts b/electron/ipc/export/native-video.test.ts
new file mode 100644
index 000000000..ee31dcdd7
--- /dev/null
+++ b/electron/ipc/export/native-video.test.ts
@@ -0,0 +1,1453 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("electron", () => ({
+ app: {
+ getAppPath: vi.fn(() => process.cwd()),
+ getGPUInfo: vi.fn(async () => ({ gpuDevice: [] })),
+ getPath: vi.fn(() => process.env.TEMP ?? process.cwd()),
+ isPackaged: false,
+ },
+}));
+
+vi.mock("../ffmpeg/binary", () => ({
+ getFfmpegBinaryPath: vi.fn(() => "ffmpeg"),
+ getFfprobeBinaryPath: vi.fn(() => "ffprobe"),
+}));
+
+vi.mock("../state", () => ({
+ cachedNativeVideoEncoder: null,
+ setCachedNativeVideoEncoder: vi.fn(),
+}));
+
+const fsMocks = vi.hoisted(() => ({
+ access: vi.fn(async () => {
+ throw new Error("missing");
+ }),
+ writeFile: vi.fn(async () => undefined),
+ readFile: vi.fn(),
+ stat: vi.fn(async () => ({ size: 5_000_000_000 })),
+ unlink: vi.fn(async () => undefined),
+}));
+
+vi.mock("node:fs/promises", () => ({
+ default: fsMocks,
+ ...fsMocks,
+}));
+
+const execFileMock = vi.hoisted(() =>
+ vi.fn((_cmd: string, _args: string[], _opts: unknown, cb: (err: Error | null) => void) => {
+ cb(null);
+ return { stdout: "", stderr: "" } as unknown;
+ }),
+);
+
+vi.mock("node:child_process", () => ({
+ execFile: execFileMock,
+ spawn: vi.fn(),
+}));
+
+import { app } from "electron";
+import {
+ buildExperimentalNvidiaCudaStaticLayoutArgs,
+ buildExperimentalWindowsGpuStaticLayoutArgs,
+ buildNativeStaticLayoutSourceProxyArgs,
+ buildNativeStaticLayoutTimelineSegments,
+ buildNativeVideoAudioMuxArgs,
+ canCopyAudioCodecIntoMp4,
+ getExperimentalNvidiaCudaExportSkipReason,
+ getNativeExportCapabilities,
+ getNativeGpuCompositorStallTimeoutMs,
+ getNativeStaticLayoutSourceProxyBitrate,
+ getNvidiaCudaAudioExportSkipReason,
+ getNvidiaCudaAutoStallTimeoutMs,
+ hasNativeStaticLayoutProgressAdvanced,
+ hasNvidiaGpuDeviceInGpuInfo,
+ mapNvidiaCudaWrapperProgressPercentage,
+ muxExportedVideoAudioBuffer,
+ type NativeStaticLayoutExportOptions,
+ normalizeNativeStaticLayoutBackground,
+ parseFfmpegDurationSeconds,
+ parseFfmpegFrameRate,
+ parseFfmpegProgressLineSeconds,
+ parseNativeVideoMetadataProbeOutput,
+ parseNativeVideoStreamStatsProbeOutput,
+ parseNvidiaCudaExportSummary,
+ parseWindowsGpuExportProgressLine,
+ parseWindowsGpuExportSummary,
+ resolveExperimentalNvidiaCudaExportScriptPath,
+ shouldCreateNativeStaticLayoutSourceProxy,
+ validateNativeStaticLayoutSourceProxyMetadata,
+ validateNativeVideoStreamStats,
+ validateNvidiaCudaExportSummary,
+ validateWindowsGpuExportSummary,
+} from "./native-video";
+
+const electronAppMock = app as unknown as {
+ getAppPath: ReturnType;
+ getGPUInfo: ReturnType;
+ isPackaged: boolean;
+};
+
+function withNvidiaCudaAudioOverride(value: string | undefined, callback: () => T) {
+ const envName = "RECORDLY_NVIDIA_CUDA_ALLOW_AUDIO_EXPORT";
+ const originalValue = process.env[envName];
+ if (value === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = value;
+ }
+
+ try {
+ return callback();
+ } finally {
+ if (originalValue === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = originalValue;
+ }
+ }
+}
+
+function resetFsAccessMock() {
+ fsMocks.access.mockImplementation(async () => {
+ throw new Error("missing");
+ });
+}
+
+function createNvidiaCudaSkipOptions(
+ overrides: Partial = {},
+): NativeStaticLayoutExportOptions {
+ return {
+ inputPath: "input.mp4",
+ width: 1920,
+ height: 1080,
+ frameRate: 30,
+ bitrate: 8_000_000,
+ encodingMode: "quality",
+ durationSec: 10,
+ contentWidth: 1600,
+ contentHeight: 900,
+ offsetX: 160,
+ offsetY: 90,
+ backgroundColor: "#101010",
+ experimentalWindowsGpuCompositor: true,
+ ...overrides,
+ };
+}
+
+async function withPackagedCudaCandidate(gpuInfo: unknown, callback: () => Promise) {
+ const envName = "RECORDLY_EXPERIMENTAL_NVIDIA_CUDA_EXPORT";
+ const originalEnv = process.env[envName];
+ const originalIsPackaged = electronAppMock.isPackaged;
+ electronAppMock.isPackaged = true;
+ electronAppMock.getGPUInfo.mockResolvedValue(gpuInfo);
+ fsMocks.access.mockResolvedValue(undefined);
+ delete process.env[envName];
+
+ try {
+ return await callback();
+ } finally {
+ if (originalEnv === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = originalEnv;
+ }
+ electronAppMock.isPackaged = originalIsPackaged;
+ electronAppMock.getGPUInfo.mockReset();
+ electronAppMock.getGPUInfo.mockResolvedValue({ gpuDevice: [] });
+ resetFsAccessMock();
+ }
+}
+
+describe("normalizeNativeStaticLayoutBackground", () => {
+ it("falls back to a solid background when the configured image file is missing", async () => {
+ const normalized = await normalizeNativeStaticLayoutBackground({
+ inputPath: "input.mp4",
+ width: 1920,
+ height: 1080,
+ frameRate: 30,
+ bitrate: 8_000_000,
+ encodingMode: "quality",
+ durationSec: 10,
+ contentWidth: 1600,
+ contentHeight: 900,
+ offsetX: 160,
+ offsetY: 90,
+ backgroundColor: "#101010",
+ backgroundImagePath: "Z:\\recordly-missing-wallpaper\\midnight-8.jpg",
+ });
+
+ expect(normalized.backgroundImagePath).toBeNull();
+ expect(normalized.backgroundColor).toBe("#ffffff");
+ });
+});
+
+describe("native static-layout source proxy", () => {
+ const h264Metadata = {
+ width: 1920,
+ height: 1080,
+ duration: 45,
+ frameRate: 30,
+ codec: "h264 (High)",
+ hasAudio: true,
+ audioCodec: "aac",
+ };
+
+ it("proxies non-H.264 codecs and non-MP4-like containers", () => {
+ expect(shouldCreateNativeStaticLayoutSourceProxy(h264Metadata, "recording.mp4")).toBe(
+ false,
+ );
+ expect(shouldCreateNativeStaticLayoutSourceProxy(h264Metadata, "recording.webm")).toBe(
+ true,
+ );
+ expect(
+ shouldCreateNativeStaticLayoutSourceProxy(
+ { ...h264Metadata, codec: "vp9 (Profile 0)" },
+ "recording.webm",
+ ),
+ ).toBe(true);
+ });
+
+ it("builds a CFR H.264 MP4 proxy at visually safe bitrate", () => {
+ const options = createNvidiaCudaSkipOptions({
+ inputPath: "recording.webm",
+ bitrate: 22_000_000,
+ durationSec: 30,
+ });
+ const metadata = {
+ ...h264Metadata,
+ codec: "vp9 (Profile 0)",
+ audioCodec: "opus",
+ duration: 45.036,
+ streamDuration: 45.036,
+ };
+ const args = buildNativeStaticLayoutSourceProxyArgs(options, "source-proxy.mp4", metadata);
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "-i",
+ "recording.webm",
+ "-an",
+ "-t",
+ "45.036",
+ "-c:v",
+ "libx264",
+ "-preset",
+ "veryfast",
+ "-pix_fmt",
+ "yuv420p",
+ "-movflags",
+ "+faststart",
+ "source-proxy.mp4",
+ ]),
+ );
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "-vf",
+ "fps=fps=30:start_time=0,scale=trunc(iw/2)*2:trunc(ih/2)*2,setsar=1,format=yuv420p,setpts=PTS-STARTPTS",
+ ]),
+ );
+ expect(getNativeStaticLayoutSourceProxyBitrate(options, metadata)).toBeGreaterThan(
+ options.bitrate,
+ );
+ });
+
+ it("validates proxy codec and duration before native composition", () => {
+ expect(
+ validateNativeStaticLayoutSourceProxyMetadata(
+ { ...h264Metadata, codec: "vp9", duration: 45 },
+ { sourceDurationSec: 45 },
+ ),
+ ).toEqual(["proxy codec is not H.264/AVC: vp9"]);
+ expect(
+ validateNativeStaticLayoutSourceProxyMetadata(
+ { ...h264Metadata, duration: 10 },
+ { sourceDurationSec: 45 },
+ ),
+ ).toEqual(["proxy duration 10.000s shorter than expected 45.000s"]);
+ });
+});
+
+describe("getNvidiaCudaAudioExportSkipReason", () => {
+ it("allows video-only CUDA exports by default", () => {
+ withNvidiaCudaAudioOverride(undefined, () => {
+ expect(getNvidiaCudaAudioExportSkipReason(undefined)).toBeNull();
+ expect(getNvidiaCudaAudioExportSkipReason("none")).toBeNull();
+ });
+ });
+
+ it("guards CUDA for audio exports unless explicitly overridden", () => {
+ withNvidiaCudaAudioOverride(undefined, () => {
+ expect(getNvidiaCudaAudioExportSkipReason("copy-source")).toBe(
+ "audio-mode:copy-source",
+ );
+ expect(getNvidiaCudaAudioExportSkipReason("trim-source")).toBe(
+ "audio-mode:trim-source",
+ );
+ expect(getNvidiaCudaAudioExportSkipReason("edited-track")).toBe(
+ "audio-mode:edited-track",
+ );
+ });
+ });
+
+ it("allows CUDA audio exports only for explicit lab overrides", () => {
+ withNvidiaCudaAudioOverride("1", () => {
+ expect(getNvidiaCudaAudioExportSkipReason("copy-source")).toBeNull();
+ });
+ });
+
+ it("allows validated fallback candidates to try CUDA audio exports", () => {
+ withNvidiaCudaAudioOverride(undefined, () => {
+ expect(
+ getNvidiaCudaAudioExportSkipReason("copy-source", {
+ allowValidatedFallbackCandidate: true,
+ }),
+ ).toBeNull();
+ });
+ });
+});
+
+describe("getNvidiaCudaAutoStallTimeoutMs", () => {
+ it("only applies the stall guard to active validated CUDA candidates by default", () => {
+ expect(getNvidiaCudaAutoStallTimeoutMs(false)).toBeNull();
+ expect(getNvidiaCudaAutoStallTimeoutMs(true)).toBe(120_000);
+ });
+
+ it("allows the CUDA auto stall guard to be disabled or tuned", () => {
+ const envName = "RECORDLY_NVIDIA_CUDA_AUTO_STALL_TIMEOUT_MS";
+ const originalValue = process.env[envName];
+
+ try {
+ process.env[envName] = "0";
+ expect(getNvidiaCudaAutoStallTimeoutMs(true)).toBeNull();
+
+ process.env[envName] = "5000";
+ expect(getNvidiaCudaAutoStallTimeoutMs(true)).toBe(10_000);
+
+ process.env[envName] = "45000";
+ expect(getNvidiaCudaAutoStallTimeoutMs(true)).toBe(45_000);
+ } finally {
+ if (originalValue === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = originalValue;
+ }
+ }
+ });
+});
+
+describe("getNativeGpuCompositorStallTimeoutMs", () => {
+ it("guards Windows GPU compositor stalls by default", () => {
+ expect(getNativeGpuCompositorStallTimeoutMs()).toBe(120_000);
+ });
+
+ it("allows the Windows GPU stall guard to be disabled or tuned", () => {
+ const envName = "RECORDLY_NATIVE_GPU_STALL_TIMEOUT_MS";
+ const originalValue = process.env[envName];
+
+ try {
+ process.env[envName] = "0";
+ expect(getNativeGpuCompositorStallTimeoutMs()).toBeNull();
+
+ process.env[envName] = "5000";
+ expect(getNativeGpuCompositorStallTimeoutMs()).toBe(10_000);
+
+ process.env[envName] = "45000";
+ expect(getNativeGpuCompositorStallTimeoutMs()).toBe(45_000);
+ } finally {
+ if (originalValue === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = originalValue;
+ }
+ }
+ });
+});
+
+describe("hasNvidiaGpuDeviceInGpuInfo", () => {
+ it("detects NVIDIA GPUs by vendor id or device strings", () => {
+ expect(
+ hasNvidiaGpuDeviceInGpuInfo({
+ gpuDevice: [{ active: false, vendorId: 0x10de, deviceId: 0x1f91 }],
+ }),
+ ).toBe(true);
+ expect(
+ hasNvidiaGpuDeviceInGpuInfo({
+ gpuDevice: [{ vendorString: "NVIDIA Corporation" }],
+ }),
+ ).toBe(true);
+ expect(
+ hasNvidiaGpuDeviceInGpuInfo({
+ gpuDevice: [{ deviceString: "NVIDIA GeForce GTX 1650" }],
+ }),
+ ).toBe(true);
+ });
+
+ it("rejects non-NVIDIA and malformed GPU info", () => {
+ expect(
+ hasNvidiaGpuDeviceInGpuInfo({
+ gpuDevice: [
+ { vendorId: 0x1002, deviceString: "AMD Radeon" },
+ { vendorId: 0x8086, deviceString: "Intel UHD Graphics" },
+ ],
+ }),
+ ).toBe(false);
+ expect(hasNvidiaGpuDeviceInGpuInfo({})).toBe(false);
+ expect(hasNvidiaGpuDeviceInGpuInfo(null)).toBe(false);
+ });
+});
+
+describe("getNativeExportCapabilities", () => {
+ it("reports NVIDIA CUDA availability when the wrapper and an NVIDIA GPU are present", async () => {
+ const capabilities = await withPackagedCudaCandidate(
+ { gpuDevice: [{ vendorId: 0x10de, deviceString: "NVIDIA GeForce GTX 1650" }] },
+ () => getNativeExportCapabilities(),
+ );
+
+ expect(capabilities.nvidiaCuda.available).toBe(process.platform === "win32");
+ expect(capabilities.nvidiaCuda.hasWrapper).toBe(process.platform === "win32");
+ expect(capabilities.nvidiaCuda.hasNvidiaGpu).toBe(
+ process.platform === "win32" ? true : null,
+ );
+ });
+});
+
+describe("getExperimentalNvidiaCudaExportSkipReason", () => {
+ it("requires user opt-in before packaged CUDA candidates run", async () => {
+ const reason = await withPackagedCudaCandidate(
+ { gpuDevice: [{ vendorId: 0x10de, deviceString: "NVIDIA GeForce GTX 1650" }] },
+ () =>
+ getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ }),
+ ),
+ );
+
+ expect(reason).toBe(process.platform === "win32" ? "env-disabled" : "not-windows");
+ });
+
+ it("allows user opt-in CUDA candidates when the helper and an NVIDIA GPU are present", async () => {
+ const reason = await withPackagedCudaCandidate(
+ { gpuDevice: [{ vendorId: 0x10de, deviceString: "NVIDIA GeForce GTX 1650" }] },
+ () =>
+ getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({
+ experimentalNvidiaCudaExport: true,
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ }),
+ ),
+ );
+
+ expect(reason).toBe(process.platform === "win32" ? null : "not-windows");
+ });
+
+ it("allows explicit lab CUDA audio exports when forced onto the shared mux path", async () => {
+ const exportEnvName = "RECORDLY_EXPERIMENTAL_NVIDIA_CUDA_EXPORT";
+ const forceEnvName = "RECORDLY_NVIDIA_CUDA_FORCE_VIDEO_ONLY";
+ const allowAudioEnvName = "RECORDLY_NVIDIA_CUDA_ALLOW_AUDIO_EXPORT";
+ const originalExportEnv = process.env[exportEnvName];
+ const originalForceEnv = process.env[forceEnvName];
+ const originalAllowAudioEnv = process.env[allowAudioEnvName];
+ process.env[exportEnvName] = "1";
+ process.env[forceEnvName] = "1";
+ delete process.env[allowAudioEnvName];
+
+ try {
+ const reason = await getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ }),
+ );
+
+ expect(reason).toBe(process.platform === "win32" ? null : "not-windows");
+ } finally {
+ if (originalExportEnv === undefined) {
+ delete process.env[exportEnvName];
+ } else {
+ process.env[exportEnvName] = originalExportEnv;
+ }
+ if (originalForceEnv === undefined) {
+ delete process.env[forceEnvName];
+ } else {
+ process.env[forceEnvName] = originalForceEnv;
+ }
+ if (originalAllowAudioEnv === undefined) {
+ delete process.env[allowAudioEnvName];
+ } else {
+ process.env[allowAudioEnvName] = originalAllowAudioEnv;
+ }
+ }
+ });
+
+ it("does not use packaged auto-candidate audio bypass when CUDA is explicitly enabled", async () => {
+ const exportEnvName = "RECORDLY_EXPERIMENTAL_NVIDIA_CUDA_EXPORT";
+ const forceEnvName = "RECORDLY_NVIDIA_CUDA_FORCE_VIDEO_ONLY";
+ const allowAudioEnvName = "RECORDLY_NVIDIA_CUDA_ALLOW_AUDIO_EXPORT";
+ const originalExportEnv = process.env[exportEnvName];
+ const originalForceEnv = process.env[forceEnvName];
+ const originalAllowAudioEnv = process.env[allowAudioEnvName];
+ const originalIsPackaged = electronAppMock.isPackaged;
+ electronAppMock.isPackaged = true;
+ process.env[exportEnvName] = "1";
+ delete process.env[forceEnvName];
+ delete process.env[allowAudioEnvName];
+
+ try {
+ const reason = await getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ }),
+ );
+
+ expect(reason).toBe(
+ process.platform === "win32" ? "audio-mode:copy-source" : "not-windows",
+ );
+ } finally {
+ if (originalExportEnv === undefined) {
+ delete process.env[exportEnvName];
+ } else {
+ process.env[exportEnvName] = originalExportEnv;
+ }
+ if (originalForceEnv === undefined) {
+ delete process.env[forceEnvName];
+ } else {
+ process.env[forceEnvName] = originalForceEnv;
+ }
+ if (originalAllowAudioEnv === undefined) {
+ delete process.env[allowAudioEnvName];
+ } else {
+ process.env[allowAudioEnvName] = originalAllowAudioEnv;
+ }
+ electronAppMock.isPackaged = originalIsPackaged;
+ }
+ });
+
+ it("skips user opt-in CUDA candidates when Electron reports no NVIDIA GPU", async () => {
+ const reason = await withPackagedCudaCandidate(
+ { gpuDevice: [{ vendorId: 0x8086, deviceString: "Intel UHD Graphics" }] },
+ () =>
+ getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({ experimentalNvidiaCudaExport: true }),
+ ),
+ );
+
+ expect(reason).toBe(
+ process.platform === "win32" ? "nvidia-gpu-unavailable" : "not-windows",
+ );
+ });
+
+ it("lets the user opt-in candidate be explicitly disabled", async () => {
+ const reason = await withPackagedCudaCandidate(
+ { gpuDevice: [{ vendorId: 0x10de, deviceString: "NVIDIA GeForce GTX 1650" }] },
+ async () => {
+ process.env.RECORDLY_EXPERIMENTAL_NVIDIA_CUDA_EXPORT = "0";
+ return getExperimentalNvidiaCudaExportSkipReason(
+ createNvidiaCudaSkipOptions({ experimentalNvidiaCudaExport: true }),
+ );
+ },
+ );
+
+ expect(reason).toBe(process.platform === "win32" ? "env-disabled" : "not-windows");
+ });
+});
+
+describe("resolveExperimentalNvidiaCudaExportScriptPath", () => {
+ it("prefers the packaged app.asar.unpacked CUDA wrapper over the virtual app.asar copy", async () => {
+ const envName = "RECORDLY_NVIDIA_CUDA_EXPORT_SCRIPT";
+ const originalEnv = process.env[envName];
+ const originalResourcesPath = Object.getOwnPropertyDescriptor(process, "resourcesPath");
+ delete process.env[envName];
+
+ try {
+ if (process.platform !== "win32") {
+ expect(await resolveExperimentalNvidiaCudaExportScriptPath()).toBeNull();
+ return;
+ }
+
+ const resourcesPath = "C:\\Recordly\\resources";
+ const unpackedScriptPath =
+ "C:\\Recordly\\resources\\app.asar.unpacked\\electron\\native\\nvidia-cuda-compositor\\run-mp4-pipeline.mjs";
+ const asarScriptPath =
+ "C:\\Recordly\\resources\\app.asar\\electron\\native\\nvidia-cuda-compositor\\run-mp4-pipeline.mjs";
+ Object.defineProperty(process, "resourcesPath", {
+ configurable: true,
+ value: resourcesPath,
+ });
+ electronAppMock.getAppPath.mockReturnValue("C:\\Recordly\\resources\\app.asar");
+ fsMocks.access.mockImplementation(async (candidate: string) => {
+ if (candidate === unpackedScriptPath || candidate === asarScriptPath) {
+ return;
+ }
+ throw new Error(`missing ${candidate}`);
+ });
+
+ expect(await resolveExperimentalNvidiaCudaExportScriptPath()).toBe(unpackedScriptPath);
+ } finally {
+ if (originalEnv === undefined) {
+ delete process.env[envName];
+ } else {
+ process.env[envName] = originalEnv;
+ }
+ if (originalResourcesPath) {
+ Object.defineProperty(process, "resourcesPath", originalResourcesPath);
+ } else {
+ delete (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;
+ }
+ electronAppMock.getAppPath.mockReset();
+ electronAppMock.getAppPath.mockReturnValue(process.cwd());
+ resetFsAccessMock();
+ }
+ });
+});
+
+describe("buildExperimentalNvidiaCudaStaticLayoutArgs", () => {
+ it("passes output canvas dimensions to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({ width: 1020, height: 572 }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(expect.arrayContaining(["--width", "1020", "--height", "572"]));
+ });
+
+ it("keeps explicit copy-source CUDA audio inline by default", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).not.toContain("--video-only");
+ });
+
+ it("forces packaged auto CUDA candidates onto the shared audio mux path", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ audioOptions: { audioMode: "copy-source", audioSourcePath: "input.mp4" },
+ nvidiaCudaForceVideoOnly: true,
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toContain("--video-only");
+ });
+
+ it("passes native timeline maps to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ timelineMapPath: "timeline-map.csv",
+ timelineSegments: [
+ {
+ sourceStartMs: 0,
+ sourceEndMs: 6_000,
+ outputStartMs: 0,
+ outputEndMs: 4_000,
+ speed: 1.5,
+ },
+ ],
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(expect.arrayContaining(["--timeline-map", "timeline-map.csv"]));
+ });
+
+ it("passes background blur to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ backgroundImagePath: "wallpaper.jpg",
+ backgroundBlurPx: 36,
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(expect.arrayContaining(["--background-blur", "36"]));
+ });
+
+ it("passes the export encoding mode to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ encodingMode: "quality",
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(expect.arrayContaining(["--encoding-mode", "quality"]));
+ });
+
+ it("passes webcam source-time controls to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ webcamInputPath: "webcam.mp4",
+ webcamLeft: 32,
+ webcamTop: 48,
+ webcamSize: 240,
+ webcamRadius: 18,
+ webcamTimeOffsetMs: -125.5,
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "--webcam-input",
+ "webcam.mp4",
+ "--webcam-time-offset-ms",
+ "-125.5",
+ "--webcam-stream",
+ ]),
+ );
+ });
+
+ it("passes cursor telemetry and atlas assets to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ cursorTelemetryPath: "cursor-telemetry.json",
+ cursorSize: 96,
+ cursorAtlasPath: "cursor-atlas.png",
+ cursorAtlasMetadataPath: "cursor-atlas.tsv",
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "--cursor-json",
+ "cursor-telemetry.json",
+ "--cursor-height",
+ "96",
+ "--cursor-style",
+ "external",
+ "--cursor-atlas-png",
+ "cursor-atlas.png",
+ "--cursor-atlas-metadata",
+ "cursor-atlas.tsv",
+ ]),
+ );
+ });
+
+ it("passes source crop coordinates to the CUDA wrapper", () => {
+ const args = buildExperimentalNvidiaCudaStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ sourceCropX: 192,
+ sourceCropY: 108,
+ sourceCropWidth: 1536,
+ sourceCropHeight: 864,
+ }),
+ "output.mp4",
+ "work",
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "--source-crop-x",
+ "192",
+ "--source-crop-y",
+ "108",
+ "--source-crop-width",
+ "1536",
+ "--source-crop-height",
+ "864",
+ ]),
+ );
+ });
+});
+
+describe("buildExperimentalWindowsGpuStaticLayoutArgs", () => {
+ it("passes background blur to the D3D11 compositor", () => {
+ const args = buildExperimentalWindowsGpuStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ backgroundImagePath: "wallpaper.jpg",
+ backgroundBlurPx: 36,
+ }),
+ "output.mp4",
+ );
+
+ expect(args).toEqual(expect.arrayContaining(["--background-blur", "36"]));
+ });
+
+ it("passes source crop coordinates to the D3D11 compositor", () => {
+ const args = buildExperimentalWindowsGpuStaticLayoutArgs(
+ createNvidiaCudaSkipOptions({
+ sourceCropX: 192,
+ sourceCropY: 108,
+ sourceCropWidth: 1536,
+ sourceCropHeight: 864,
+ }),
+ "output.mp4",
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "--source-crop-x",
+ "192",
+ "--source-crop-y",
+ "108",
+ "--source-crop-width",
+ "1536",
+ "--source-crop-height",
+ "864",
+ ]),
+ );
+ });
+});
+
+describe("buildNativeStaticLayoutTimelineSegments", () => {
+ it("derives contiguous output timeline ranges from edited-track source segments", () => {
+ expect(
+ buildNativeStaticLayoutTimelineSegments([
+ { startMs: 0, endMs: 2_000, speed: 1 },
+ { startMs: 2_000, endMs: 8_000, speed: 1.5 },
+ { startMs: 8_000, endMs: 10_000, speed: 0.5 },
+ ]),
+ ).toEqual([
+ {
+ sourceStartMs: 0,
+ sourceEndMs: 2_000,
+ outputStartMs: 0,
+ outputEndMs: 2_000,
+ speed: 1,
+ },
+ {
+ sourceStartMs: 2_000,
+ sourceEndMs: 8_000,
+ outputStartMs: 2_000,
+ outputEndMs: 6_000,
+ speed: 1.5,
+ },
+ {
+ sourceStartMs: 8_000,
+ sourceEndMs: 10_000,
+ outputStartMs: 6_000,
+ outputEndMs: 10_000,
+ speed: 0.5,
+ },
+ ]);
+ });
+});
+
+describe("muxExportedVideoAudioBuffer", () => {
+ it("returns the muxed output path without reading the muxed file into memory", async () => {
+ const videoData = new ArrayBuffer(64);
+ const result = await muxExportedVideoAudioBuffer(videoData, { audioMode: "none" });
+
+ expect(typeof result.outputPath).toBe("string");
+ expect(result.outputPath.length).toBeGreaterThan(0);
+ // The >2 GiB fix relies on stat-only metric collection; readFile must stay unused.
+ expect(fsMocks.readFile).not.toHaveBeenCalled();
+ expect(result.metrics.muxedVideoBytes).toBe(5_000_000_000);
+ });
+
+ it("preserves the input temp path when audioMode='none' (no re-mux)", async () => {
+ const videoData = new ArrayBuffer(32);
+ const result = await muxExportedVideoAudioBuffer(videoData, { audioMode: "none" });
+
+ expect(result.outputPath).toMatch(/recordly-export-video-/);
+ });
+});
+
+describe("buildNativeVideoAudioMuxArgs", () => {
+ it("stream-copies source audio and preserves the requested video duration", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.mp4", "out.mp4", {
+ audioMode: "copy-source",
+ audioSourceCodec: "aac (LC) (mp4a / 0x6134706D)",
+ outputDurationSec: 60,
+ });
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "-map",
+ "0:v:0",
+ "-map",
+ "1:a:0",
+ "-c:v",
+ "copy",
+ "-c:a",
+ "copy",
+ "-t",
+ "60.000",
+ ]),
+ );
+ expect(args).not.toContain("-shortest");
+ });
+
+ it("does not shorten copy-source muxes when no explicit duration is available", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.mp4", "out.mp4", {
+ audioMode: "copy-source",
+ audioSourceCodec: "aac",
+ });
+
+ expect(args).toEqual(expect.arrayContaining(["-c:a", "copy"]));
+ expect(args).not.toContain("-shortest");
+ });
+
+ it("transcodes WebM/Opus source audio when muxing into MP4", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.webm", "out.mp4", {
+ audioMode: "copy-source",
+ audioSourceCodec: "opus",
+ outputDurationSec: 60,
+ });
+
+ expect(args).toEqual(expect.arrayContaining(["-c:a", "aac", "-b:a", "192k"]));
+ expect(args.join(";")).not.toContain("-c:a;copy");
+ });
+
+ it("transcodes unknown source audio instead of copying unsafe codecs into MP4", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.wav", "out.mp4", {
+ audioMode: "copy-source",
+ outputDurationSec: 60,
+ });
+
+ expect(args).toEqual(expect.arrayContaining(["-c:a", "aac", "-b:a", "192k"]));
+ expect(args.join(";")).not.toContain("-c:a;copy");
+ });
+
+ it("keeps filtered audio on the AAC encode path", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.mp4", "out.mp4", {
+ audioMode: "trim-source",
+ trimSegments: [{ startMs: 0, endMs: 1_000 }],
+ outputDurationSec: 1,
+ });
+
+ expect(args).toEqual(expect.arrayContaining(["-filter_complex"]));
+ expect(args).toEqual(expect.arrayContaining(["-c:a", "aac", "-b:a", "192k"]));
+ });
+
+ it("pads and trims edited-track filtergraph audio to the expected duration", () => {
+ const args = buildNativeVideoAudioMuxArgs("video.mp4", "source.mp4", "out.mp4", {
+ audioMode: "edited-track",
+ editedTrackStrategy: "filtergraph-fast-path",
+ audioSourceSampleRate: 48_000,
+ editedTrackSegments: [{ startMs: 0, endMs: 4_000, speed: 0.5 }],
+ outputDurationSec: 8,
+ });
+
+ expect(args).toEqual(expect.arrayContaining(["-map", "[aout_sync]"]));
+ expect(args.join(";")).toContain(
+ "[aout]apad,atrim=duration=8.000,asetpts=PTS-STARTPTS[aout_sync]",
+ );
+ });
+
+ it("can enable machine-readable FFmpeg mux progress", () => {
+ const args = buildNativeVideoAudioMuxArgs(
+ "video.mp4",
+ "source.mp4",
+ "out.mp4",
+ { audioMode: "copy-source", audioSourceCodec: "aac", outputDurationSec: 60 },
+ { progressPipe: 2 },
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining(["-stats_period", "0.5", "-progress", "pipe:2", "-nostats"]),
+ );
+ });
+});
+
+describe("canCopyAudioCodecIntoMp4", () => {
+ it("allows common MP4-compatible audio codecs", () => {
+ expect(canCopyAudioCodecIntoMp4("aac (LC) (mp4a / 0x6134706D)")).toBe(true);
+ expect(canCopyAudioCodecIntoMp4("mp3")).toBe(true);
+ });
+
+ it("blocks Opus so native exports transcode it to AAC for MP4", () => {
+ expect(canCopyAudioCodecIntoMp4("opus")).toBe(false);
+ });
+
+ it("blocks unknown codecs so sidecar WAV/PCM audio is encoded for MP4", () => {
+ expect(canCopyAudioCodecIntoMp4(undefined)).toBe(false);
+ expect(canCopyAudioCodecIntoMp4("")).toBe(false);
+ });
+});
+
+describe("validateNativeVideoStreamStats", () => {
+ it("accepts a complete video stream", () => {
+ expect(
+ validateNativeVideoStreamStats(
+ { durationSec: 45, frameCount: 1350, frameRate: 30 },
+ { durationSec: 45, targetFrames: 1350 },
+ ),
+ ).toEqual([]);
+ });
+
+ it("rejects files with container duration but too few video frames", () => {
+ expect(
+ validateNativeVideoStreamStats(
+ { durationSec: 0.067, frameCount: 2, frameRate: 30 },
+ { durationSec: 45, targetFrames: 1350 },
+ ),
+ ).toEqual([
+ "video frames 2 below expected minimum 1282",
+ "video stream duration 0.067s differs from expected 45.000s",
+ ]);
+ });
+});
+
+describe("parseNativeVideoStreamStatsProbeOutput", () => {
+ it("parses FFprobe count-frame JSON output", () => {
+ expect(
+ parseNativeVideoStreamStatsProbeOutput(
+ JSON.stringify({
+ streams: [
+ {
+ duration: "44.999000",
+ nb_read_frames: "1349",
+ avg_frame_rate: "30000/1001",
+ },
+ ],
+ }),
+ ),
+ ).toEqual({
+ durationSec: 44.999,
+ frameCount: 1349,
+ frameRate: 30000 / 1001,
+ });
+ });
+});
+
+describe("parseFfmpegProgressLineSeconds", () => {
+ it("parses FFmpeg progress timestamps into seconds", () => {
+ expect(parseFfmpegProgressLineSeconds("out_time_us=1500000")).toBe(1.5);
+ expect(parseFfmpegProgressLineSeconds("out_time_ms=2500000")).toBe(2.5);
+ expect(parseFfmpegProgressLineSeconds("out_time=00:01:02.500000")).toBe(62.5);
+ expect(parseFfmpegProgressLineSeconds("progress=continue")).toBeNull();
+ });
+});
+
+describe("parseWindowsGpuExportSummary", () => {
+ it("returns the last JSON summary from helper stdout", () => {
+ const summary = parseWindowsGpuExportSummary(
+ [
+ "initializing",
+ '{"success":true,"frames":30,"totalMs":1000,"realtimeMultiplier":2}',
+ "cleanup",
+ '{"success":true,"frames":60,"surfacePoolSize":12,"readMs":12.5,"videoProcessMs":30,"writeSampleMs":40,"finalizeMs":5,"realtimeMultiplier":4}',
+ ].join("\n"),
+ );
+
+ expect(summary).toEqual({
+ success: true,
+ frames: 60,
+ surfacePoolSize: 12,
+ readMs: 12.5,
+ videoProcessMs: 30,
+ writeSampleMs: 40,
+ finalizeMs: 5,
+ realtimeMultiplier: 4,
+ });
+ });
+
+ it("returns null when helper stdout has no valid JSON summary", () => {
+ expect(parseWindowsGpuExportSummary("initializing\nnot-json")).toBeNull();
+ expect(parseWindowsGpuExportSummary("")).toBeNull();
+ });
+});
+
+describe("validateWindowsGpuExportSummary", () => {
+ it("rejects short Windows GPU outputs before muxing audio", () => {
+ expect(
+ validateWindowsGpuExportSummary(
+ { success: true, frames: 2, seconds: 0.067 },
+ { durationSec: 45, targetFrames: 1350 },
+ ),
+ ).toEqual([
+ "Windows GPU frames 2 below expected minimum 1282",
+ "Windows GPU duration 0.067s differs from expected 45.000s",
+ ]);
+ });
+
+ it("accepts complete Windows GPU outputs within tolerance", () => {
+ expect(
+ validateWindowsGpuExportSummary(
+ { success: true, frames: 1345, seconds: 44.9 },
+ { durationSec: 45, targetFrames: 1350 },
+ ),
+ ).toEqual([]);
+ });
+});
+
+describe("parseNvidiaCudaExportSummary", () => {
+ it("parses the pretty JSON summary emitted by the CUDA wrapper", () => {
+ const summary = parseNvidiaCudaExportSummary(
+ [
+ "preflight",
+ JSON.stringify(
+ {
+ success: true,
+ fps: 30,
+ durationSec: 10,
+ targetFrames: 300,
+ timingsMs: { nativeEncode: 920, mux: 45, endToEnd: 1400 },
+ nativeSummary: { success: true, frames: 300, fps: 326.1 },
+ },
+ null,
+ 2,
+ ),
+ ].join("\n"),
+ );
+
+ expect(summary?.success).toBe(true);
+ expect(summary?.targetFrames).toBe(300);
+ expect(summary?.timingsMs?.nativeEncode).toBe(920);
+ expect(summary?.nativeSummary?.fps).toBe(326.1);
+ });
+
+ it("returns null when the wrapper output has no JSON object", () => {
+ expect(parseNvidiaCudaExportSummary("native helper failed before summary")).toBeNull();
+ });
+});
+
+describe("validateNvidiaCudaExportSummary", () => {
+ it("accepts CUDA output when frames and stream durations match the export target", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: { success: true, frames: 300 },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ outputAudio: { duration: "10.005000" },
+ },
+ { durationSec: 10, targetFrames: 300 },
+ );
+
+ expect(issues).toEqual([]);
+ });
+
+ it("rejects CUDA output that reports too few frames or a short video stream", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: { success: true, frames: 144 },
+ outputVideo: { duration: "4.799952", nb_frames: "144" },
+ outputAudio: { duration: "10.005000" },
+ },
+ { durationSec: 10, targetFrames: 300 },
+ );
+
+ expect(issues).toEqual([
+ "native frames 144 below expected minimum 285",
+ "output video frames 144 below expected minimum 285",
+ "output video duration 4.800s differs from expected 10.000s",
+ ]);
+ });
+
+ it("rejects audio CUDA output unless the helper reports timestamp-aligned frame selection", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ selectionStage: "decoder-policy-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ outputAudio: { duration: "10.005000" },
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: true },
+ );
+
+ expect(issues).toEqual(["CUDA timeline mode is not timestamp-aligned for audio export"]);
+ });
+
+ it("accepts video-only CUDA output when audio is muxed by the shared export path", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ selectionStage: "decoder-policy-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: false },
+ );
+
+ expect(issues).toEqual([]);
+ });
+
+ it("rejects inline-audio CUDA output when the helper does not produce audio", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ sourceTimestampMode: "pts",
+ selectionStage: "timestamp-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: true },
+ );
+
+ expect(issues).toEqual(["missing output audio stream"]);
+ });
+
+ it("rejects inline-audio CUDA output when the probed audio stream is empty", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ sourceTimestampMode: "pts",
+ selectionStage: "timestamp-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ outputAudio: { duration: "0.000000" },
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: true },
+ );
+
+ expect(issues).toEqual(["output audio duration is not positive"]);
+ });
+
+ it("rejects inline-audio CUDA output when the audio duration is missing", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ sourceTimestampMode: "pts",
+ selectionStage: "timestamp-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ outputAudio: {},
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: true },
+ );
+
+ expect(issues).toEqual(["missing output audio duration"]);
+ });
+
+ it("accepts audio CUDA output when the helper reports PTS-aligned selection", () => {
+ const issues = validateNvidiaCudaExportSummary(
+ {
+ success: true,
+ targetFrames: 300,
+ durationSec: 10,
+ nativeSummary: {
+ success: true,
+ frames: 300,
+ sourceTimestampMode: "pts",
+ selectionStage: "timestamp-mapped-callback",
+ },
+ outputVideo: { duration: "9.999900", nb_frames: "300" },
+ outputAudio: { duration: "10.005000" },
+ },
+ { durationSec: 10, targetFrames: 300, requiresTimelineSync: true },
+ );
+
+ expect(issues).toEqual([]);
+ });
+});
+
+describe("parseWindowsGpuExportProgressLine", () => {
+ it("parses bounded helper progress lines", () => {
+ expect(
+ parseWindowsGpuExportProgressLine(
+ 'PROGRESS {"currentFrame":30,"totalFrames":60,"percentage":50,"averageFps":240.5,"instantFps":180.25,"intervalMs":166.4,"intervalFrames":30,"intervalEncodeMs":120.2,"intervalPipelineWaitMs":46.2,"intervalMonolithicCompositeFrames":0,"stage":"finalizing"}',
+ ),
+ ).toEqual({
+ currentFrame: 30,
+ totalFrames: 60,
+ percentage: 50,
+ stage: "finalizing",
+ averageFps: 240.5,
+ instantFps: 180.25,
+ intervalMs: 166.4,
+ intervalFrames: 30,
+ intervalEncodeMs: 120.2,
+ intervalPipelineWaitMs: 46.2,
+ intervalMonolithicCompositeFrames: 0,
+ });
+ });
+
+ it("preserves CUDA preparation progress as a non-rendering stage", () => {
+ expect(
+ parseWindowsGpuExportProgressLine(
+ 'PROGRESS {"currentFrame":0,"totalFrames":100,"percentage":2.5,"stage":"preparing"}',
+ ),
+ ).toEqual({
+ currentFrame: 0,
+ totalFrames: 100,
+ percentage: 2.5,
+ stage: "preparing",
+ });
+ });
+
+ it("ignores non-progress or malformed helper stderr", () => {
+ expect(parseWindowsGpuExportProgressLine("warning: encoder selected")).toBeNull();
+ expect(parseWindowsGpuExportProgressLine("PROGRESS not-json")).toBeNull();
+ expect(
+ parseWindowsGpuExportProgressLine(
+ 'PROGRESS {"currentFrame":1,"totalFrames":0,"percentage":999}',
+ ),
+ ).toBeNull();
+ });
+});
+
+describe("mapNvidiaCudaWrapperProgressPercentage", () => {
+ it("keeps preflight progress and maps native encode into the main export span", () => {
+ expect(
+ mapNvidiaCudaWrapperProgressPercentage({
+ currentFrame: 0,
+ totalFrames: 100,
+ percentage: 2.5,
+ }),
+ ).toBe(2.5);
+ expect(
+ mapNvidiaCudaWrapperProgressPercentage({
+ currentFrame: 0,
+ totalFrames: 100,
+ percentage: 0,
+ }),
+ ).toBe(3);
+ expect(
+ mapNvidiaCudaWrapperProgressPercentage({
+ currentFrame: 50,
+ totalFrames: 100,
+ percentage: 50,
+ }),
+ ).toBe(50.5);
+ expect(
+ mapNvidiaCudaWrapperProgressPercentage({
+ currentFrame: 100,
+ totalFrames: 100,
+ percentage: 100,
+ }),
+ ).toBe(98);
+ expect(
+ mapNvidiaCudaWrapperProgressPercentage({
+ currentFrame: 100,
+ totalFrames: 100,
+ percentage: 97.25,
+ stage: "finalizing",
+ }),
+ ).toBe(97.25);
+ });
+});
+
+describe("hasNativeStaticLayoutProgressAdvanced", () => {
+ it("treats repeated preparation heartbeats as stalled until real progress arrives", () => {
+ const previous = { currentFrame: 0, percentage: 2.5 };
+
+ expect(
+ hasNativeStaticLayoutProgressAdvanced(
+ { currentFrame: 0, totalFrames: 100, percentage: 2.5, stage: "preparing" },
+ previous,
+ ),
+ ).toBe(false);
+ expect(
+ hasNativeStaticLayoutProgressAdvanced(
+ { currentFrame: 0, totalFrames: 100, percentage: 2.7, stage: "preparing" },
+ previous,
+ ),
+ ).toBe(true);
+ expect(
+ hasNativeStaticLayoutProgressAdvanced(
+ { currentFrame: 1, totalFrames: 100, percentage: 2.5 },
+ previous,
+ ),
+ ).toBe(true);
+ expect(
+ hasNativeStaticLayoutProgressAdvanced(
+ { currentFrame: 100, totalFrames: 100, percentage: 97.25, stage: "finalizing" },
+ { currentFrame: 100, percentage: 97.25 },
+ ),
+ ).toBe(true);
+ });
+});
+
+describe("parseNativeVideoMetadataProbeOutput", () => {
+ it("parses FFmpeg input metadata with video and audio streams", () => {
+ const metadata = parseNativeVideoMetadataProbeOutput(`
+Input #0, mov,mp4,m4a,3gp,3g2,mj2, from 'recording.mp4':
+ Metadata:
+ major_brand : isom
+ Duration: 00:06:04.25, start: 0.000000, bitrate: 3938 kb/s
+ Stream #0:0[0x1](und): Video: h264 (High) (avc1 / 0x31637661), yuv420p(progressive), 1920x1080, 3720 kb/s, 46.05 fps, 60 tbr, 90k tbn (default)
+ Stream #0:1[0x2](und): Audio: aac (LC) (mp4a / 0x6134706D), 48000 Hz, stereo, fltp, 192 kb/s (default)
+`);
+
+ expect(metadata).toEqual({
+ width: 1920,
+ height: 1080,
+ duration: 364.25,
+ mediaStartTime: 0,
+ streamStartTime: 0,
+ streamDuration: 364.25,
+ frameRate: 46.05,
+ codec: "h264 (High) (avc1 / 0x31637661)",
+ hasAudio: true,
+ audioCodec: "aac (LC) (mp4a / 0x6134706D)",
+ audioSampleRate: 48000,
+ });
+ });
+
+ it("parses video-only metadata and falls back to tbr when fps is absent", () => {
+ const metadata = parseNativeVideoMetadataProbeOutput(`
+Input #0, matroska,webm, from 'recording.webm':
+ Duration: 00:00:10.50, start: 0.023000, bitrate: 1000 kb/s
+ Stream #0:0: Video: vp9, yuv420p, 1280x720, 30 tbr, 1k tbn
+`);
+
+ expect(metadata).toEqual({
+ width: 1280,
+ height: 720,
+ duration: 10.5,
+ mediaStartTime: 0.023,
+ streamStartTime: 0.023,
+ streamDuration: 10.5,
+ frameRate: 30,
+ codec: "vp9",
+ hasAudio: false,
+ audioCodec: undefined,
+ audioSampleRate: undefined,
+ });
+ });
+
+ it("rejects output without usable video metadata", () => {
+ expect(parseNativeVideoMetadataProbeOutput("Duration: N/A")).toBeNull();
+ expect(parseNativeVideoMetadataProbeOutput("not a media file")).toBeNull();
+ });
+});
+
+describe("parseFfmpegDurationSeconds", () => {
+ it("parses HH:MM:SS timestamps", () => {
+ expect(parseFfmpegDurationSeconds("01:02:03.5")).toBe(3723.5);
+ expect(parseFfmpegDurationSeconds("bad")).toBeNull();
+ });
+});
+
+describe("parseFfmpegFrameRate", () => {
+ it("prefers fps and falls back to tbr", () => {
+ expect(parseFfmpegFrameRate("Video: h264, 1920x1080, 59.94 fps, 60 tbr")).toBe(59.94);
+ expect(parseFfmpegFrameRate("Video: h264, 1920x1080, 30 tbr")).toBe(30);
+ expect(parseFfmpegFrameRate("Video: h264")).toBeNull();
+ });
+});
diff --git a/electron/ipc/export/native-video.ts b/electron/ipc/export/native-video.ts
new file mode 100644
index 000000000..16b2993e8
--- /dev/null
+++ b/electron/ipc/export/native-video.ts
@@ -0,0 +1,4198 @@
+import type { ChildProcessByStdio } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import type { Readable, Writable } from "node:stream";
+import { promisify } from "node:util";
+import type { WebContents } from "electron";
+import { app, powerSaveBlocker } from "electron";
+import { getFfmpegBinaryPath, getFfprobeBinaryPath } from "../ffmpeg/binary";
+import type {
+ NativeExportEncodingMode,
+ NativeStaticLayoutBackend,
+ NativeStaticLayoutExportArgsConfig,
+ NativeVideoAudioMuxMetrics,
+ NativeVideoExportAudioMode,
+ NativeVideoExportEditedTrackSegment,
+ NativeVideoExportFinishOptions,
+} from "../nativeVideoExport";
+import {
+ buildEditedTrackSourceAudioFilter,
+ buildNativeConcatArgs,
+ buildNativeCudaOverlayStaticLayoutArgs,
+ buildNativeCudaScaleCpuPadStaticLayoutArgs,
+ buildNativePrecompositedStaticLayoutArgs,
+ buildNativeStaticBackgroundRenderArgs,
+ buildNativeStaticLayoutChunks,
+ buildNativeVideoExportArgs,
+ buildTrimmedSourceAudioFilter,
+ createNativeSquircleMaskPgmBuffer,
+ getEditedAudioExtension,
+ getNativeVideoInputByteSize,
+ getPreferredNativeVideoEncoders,
+ isNativeCudaOutOfMemory,
+ parseAvailableFfmpegEncoders,
+} from "../nativeVideoExport";
+import { cachedNativeVideoEncoder, setCachedNativeVideoEncoder } from "../state";
+
+const execFileAsync = promisify(execFile);
+const getNowMs = () => performance.now();
+const formatFfmpegSeconds = (milliseconds: number) => (milliseconds / 1000).toFixed(3);
+const MISSING_NATIVE_STATIC_BACKGROUND_COLOR = "#ffffff";
+const NATIVE_EXPORT_HIGH_PRIORITY = os.constants.priority.PRIORITY_HIGH;
+const NVIDIA_PCI_VENDOR_ID = 0x10de;
+const NVIDIA_CUDA_EXPORT_ENV = "RECORDLY_EXPERIMENTAL_NVIDIA_CUDA_EXPORT";
+const NVIDIA_CUDA_ALLOW_AUDIO_EXPORT_ENV = "RECORDLY_NVIDIA_CUDA_ALLOW_AUDIO_EXPORT";
+const NVIDIA_CUDA_FORCE_VIDEO_ONLY_ENV = "RECORDLY_NVIDIA_CUDA_FORCE_VIDEO_ONLY";
+const NVIDIA_CUDA_AUTO_STALL_TIMEOUT_ENV = "RECORDLY_NVIDIA_CUDA_AUTO_STALL_TIMEOUT_MS";
+const DEFAULT_NVIDIA_CUDA_AUTO_STALL_TIMEOUT_MS = 120_000;
+const NATIVE_GPU_STALL_TIMEOUT_ENV = "RECORDLY_NATIVE_GPU_STALL_TIMEOUT_MS";
+const DEFAULT_NATIVE_GPU_STALL_TIMEOUT_MS = 120_000;
+const NATIVE_STATIC_LAYOUT_SOURCE_PROXY_REFERENCE_PIXEL_RATE = 1920 * 1080 * 30;
+const NATIVE_STATIC_LAYOUT_SOURCE_PROXY_1080P30_BITRATE = 24_000_000;
+const NATIVE_STATIC_LAYOUT_SOURCE_PROXY_MAX_BITRATE = 80_000_000;
+const NATIVE_STATIC_LAYOUT_SOURCE_PROXY_CONTAINERS = new Set([".mp4", ".m4v", ".mov"]);
+
+type ElectronGpuDeviceLike = {
+ vendorId?: number | string;
+ vendorString?: string;
+ deviceString?: string;
+};
+
+type ElectronGpuInfoLike = {
+ gpuDevice?: ElectronGpuDeviceLike[];
+};
+
+export type NativeVideoExportSession = {
+ ffmpegProcess: ChildProcessByStdio;
+ outputPath: string;
+ inputByteSize: number;
+ inputMode: "rawvideo" | "h264-stream";
+ maxQueuedWriteBytes: number;
+ stderrOutput: string;
+ encoderName: string;
+ processError: Error | null;
+ stdinError: Error | null;
+ terminating: boolean;
+ writeSequence: Promise;
+ completionPromise: Promise;
+ sender: WebContents | null;
+ pendingWriteRequestIds: Set;
+};
+
+export const nativeVideoExportSessions = new Map();
+
+export interface NativeStaticLayoutTimelineSegment {
+ sourceStartMs: number;
+ sourceEndMs: number;
+ outputStartMs: number;
+ outputEndMs: number;
+ speed: number;
+}
+
+export interface NativeStaticLayoutExportOptions {
+ sessionId?: string;
+ inputPath: string;
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: NativeExportEncodingMode;
+ durationSec: number;
+ contentWidth: number;
+ contentHeight: number;
+ offsetX: number;
+ offsetY: number;
+ sourceCropX?: number;
+ sourceCropY?: number;
+ sourceCropWidth?: number;
+ sourceCropHeight?: number;
+ backgroundColor: string;
+ backgroundImagePath?: string | null;
+ backgroundBlurPx?: number;
+ borderRadius?: number;
+ shadowIntensity?: number;
+ webcamInputPath?: string | null;
+ webcamLeft?: number;
+ webcamTop?: number;
+ webcamSize?: number;
+ webcamRadius?: number;
+ webcamShadowIntensity?: number;
+ webcamMirror?: boolean;
+ webcamTimeOffsetMs?: number;
+ cursorTelemetry?: Array<{
+ timeMs: number;
+ cx: number;
+ cy: number;
+ cursorTypeIndex?: number;
+ bounceScale?: number;
+ visible?: boolean;
+ }>;
+ cursorTelemetryPath?: string | null;
+ cursorSize?: number;
+ cursorAtlasPngDataUrl?: string | null;
+ cursorAtlasPath?: string | null;
+ cursorAtlasEntries?: Array<{
+ index: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+ anchorX: number;
+ anchorY: number;
+ aspectRatio: number;
+ }>;
+ cursorAtlasMetadataPath?: string | null;
+ zoomTelemetry?: Array<{ timeMs: number; scale: number; x: number; y: number }>;
+ zoomTelemetryPath?: string | null;
+ timelineSegments?: NativeStaticLayoutTimelineSegment[];
+ timelineMapPath?: string | null;
+ chunkDurationSec?: number;
+ experimentalWindowsGpuCompositor?: boolean;
+ experimentalNvidiaCudaExport?: boolean;
+ audioOptions?: NativeVideoExportFinishOptions;
+ nvidiaCudaForceVideoOnly?: boolean;
+}
+
+export interface NativeStaticLayoutExportProgress {
+ sessionId?: string;
+ backend?: NativeStaticLayoutBackend;
+ stage?: "preparing" | "finalizing";
+ elapsedMs?: number;
+ averageFps?: number;
+ instantFps?: number;
+ intervalMs?: number;
+ intervalFrames?: number;
+ intervalDecodeWallMs?: number;
+ intervalEncodeMs?: number;
+ intervalPipelineWaitMs?: number;
+ intervalCompositeMs?: number;
+ intervalNvencMs?: number;
+ intervalPacketWriteMs?: number;
+ intervalWebcamDecodeMs?: number;
+ intervalWebcamCopyMs?: number;
+ intervalRoiCompositeFrames?: number;
+ intervalMonolithicCompositeFrames?: number;
+ intervalCopyCompositeFrames?: number;
+ currentFrame: number;
+ totalFrames: number;
+ percentage: number;
+}
+
+type NativeVideoAudioMuxProgress = {
+ ratio: number;
+ processedSec?: number;
+ totalSec?: number;
+};
+
+type NativeVideoAudioMuxArgsOptions = {
+ progressPipe?: 1 | 2;
+};
+
+export interface WindowsGpuExportSummary {
+ success?: boolean;
+ width?: number;
+ height?: number;
+ fps?: number;
+ seconds?: number;
+ mediaMs?: number;
+ frames?: number;
+ gpuDecodeSurface?: boolean;
+ webcamOverlay?: boolean;
+ cursorOverlay?: boolean;
+ cursorAtlas?: boolean;
+ zoomOverlay?: boolean;
+ surfacePoolSize?: number;
+ adapterIndex?: number;
+ adapterVendorId?: number;
+ adapterDeviceId?: number;
+ adapterDedicatedVideoMemoryMB?: number;
+ encoderBackend?: string;
+ encoderTuningApplied?: boolean;
+ nvencOutputBytes?: number;
+ initializeMs?: number;
+ initCoInitializeMs?: number;
+ initMfStartupMs?: number;
+ initD3DDeviceMs?: number;
+ initSourceReaderMs?: number;
+ initWebcamReaderMs?: number;
+ initVideoProcessorMs?: number;
+ initTexturesMs?: number;
+ initShaderPipelineMs?: number;
+ initSinkWriterMs?: number;
+ totalMs?: number;
+ readMs?: number;
+ clearMs?: number;
+ videoProcessMs?: number;
+ writeSampleMs?: number;
+ finalizeMs?: number;
+ realtimeMultiplier?: number;
+}
+
+export interface NvidiaCudaExportSummary {
+ success?: boolean;
+ inputPath?: string;
+ outputPath?: string;
+ fps?: number;
+ bitrateMbps?: number;
+ durationSec?: number;
+ targetFrames?: number;
+ sourcePtsFrames?: number;
+ sourcePtsSource?: string;
+ timingsMs?: {
+ demux?: number;
+ backgroundConvert?: number;
+ cursorAtlas?: number;
+ webcamConvert?: number;
+ webcamDemux?: number;
+ sourcePtsProbe?: number;
+ nativeEncode?: number;
+ mux?: number;
+ endToEnd?: number;
+ };
+ nativeSummary?: {
+ success?: boolean;
+ selectionStage?: string;
+ sourceTimestampMode?: string;
+ timelineMode?: string;
+ frames?: number;
+ totalMs?: number;
+ fps?: number;
+ measuredFps?: number;
+ mappedDisplayFrames?: number;
+ selectedDisplayFrames?: number;
+ skippedDisplayFrames?: number;
+ roiCompositeFrames?: number;
+ monolithicCompositeFrames?: number;
+ copyCompositeFrames?: number;
+ cursorAtlas?: boolean;
+ webcamOverlay?: boolean;
+ zoomOverlay?: boolean;
+ zoomSamples?: number;
+ };
+ nativeProcessPriorityBoosted?: boolean;
+ appRuntimeGuard?: {
+ powerGuardStarted?: boolean;
+ wrapperProcessPriorityBoosted?: boolean;
+ nativeProcessPriorityBoosted?: boolean;
+ };
+ gpuSamples?: unknown[];
+ gpuSummary?: unknown;
+ outputVideo?: unknown;
+ outputAudio?: unknown;
+}
+
+export interface NativeVideoMetadataProbe {
+ width: number;
+ height: number;
+ duration: number;
+ mediaStartTime?: number;
+ streamStartTime?: number;
+ streamDuration?: number;
+ frameRate: number;
+ codec: string;
+ hasAudio: boolean;
+ audioCodec?: string;
+ audioSampleRate?: number;
+}
+
+export interface NativeVideoStreamStatsProbe {
+ durationSec: number | null;
+ frameCount: number | null;
+ frameRate: number | null;
+}
+
+export interface NativeStaticLayoutChunkMetric {
+ index: number;
+ startSec: number;
+ durationSec: number;
+ backend: NativeStaticLayoutBackend;
+ elapsedMs: number;
+ outputBytes: number;
+ fallbackReason?: string;
+ windowsGpuSummary?: WindowsGpuExportSummary;
+ nvidiaCudaSummary?: NvidiaCudaExportSummary;
+}
+
+export interface NativeStaticLayoutExportMetrics extends NativeVideoAudioMuxMetrics {
+ chunkCount: number;
+ chunkDurationSec: number;
+ chunkExecMs: number;
+ concatExecMs?: number;
+ staticAssetExecMs?: number;
+ fallbackChunkCount: number;
+ videoOnlyBytes?: number;
+ chunks: NativeStaticLayoutChunkMetric[];
+}
+
+export interface NativeStaticLayoutExportSession {
+ terminating: boolean;
+ currentProcess: ReturnType | null;
+}
+
+export function cleanupNativeVideoExportSessions() {
+ for (const [sessionId, session] of nativeVideoExportSessions) {
+ session.terminating = true;
+ try {
+ if (!session.ffmpegProcess.stdin.destroyed) {
+ session.ffmpegProcess.stdin.destroy();
+ }
+ } catch {
+ /* stream may already be closed */
+ }
+ try {
+ session.ffmpegProcess.kill("SIGKILL");
+ } catch {
+ /* process may already be exited */
+ }
+ nativeVideoExportSessions.delete(sessionId);
+ }
+
+ for (const [sessionId, session] of nativeStaticLayoutExportSessions) {
+ session.terminating = true;
+ try {
+ session.currentProcess?.kill("SIGKILL");
+ } catch {
+ /* process may already be exited */
+ }
+ nativeStaticLayoutExportSessions.delete(sessionId);
+ }
+}
+
+export function parseWindowsGpuExportSummary(stdout: string): WindowsGpuExportSummary | null {
+ const summaryLine = stdout
+ .trim()
+ .split(/\r?\n/)
+ .reverse()
+ .find((line) => line.trim().startsWith("{"));
+ if (!summaryLine) {
+ return null;
+ }
+
+ try {
+ const parsed = JSON.parse(summaryLine) as WindowsGpuExportSummary;
+ return parsed && typeof parsed === "object" ? parsed : null;
+ } catch {
+ return null;
+ }
+}
+
+export function parseNvidiaCudaExportSummary(stdout: string): NvidiaCudaExportSummary | null {
+ const trimmed = stdout.trim();
+ const startIndex = trimmed.indexOf("{");
+ const endIndex = trimmed.lastIndexOf("}");
+ if (startIndex === -1 || endIndex <= startIndex) {
+ return null;
+ }
+
+ try {
+ const parsed = JSON.parse(
+ trimmed.slice(startIndex, endIndex + 1),
+ ) as NvidiaCudaExportSummary;
+ return parsed && typeof parsed === "object" ? parsed : null;
+ } catch {
+ return null;
+ }
+}
+
+function getFiniteNumber(value: unknown) {
+ const numberValue = typeof value === "string" ? Number(value) : value;
+ return typeof numberValue === "number" && Number.isFinite(numberValue) ? numberValue : null;
+}
+
+function getNvidiaCudaOutputStreamNumber(stream: unknown, property: string) {
+ if (!stream || typeof stream !== "object") {
+ return null;
+ }
+
+ return getFiniteNumber((stream as Record)[property]);
+}
+
+export function validateNvidiaCudaExportSummary(
+ summary: NvidiaCudaExportSummary,
+ expected: {
+ durationSec: number;
+ targetFrames: number;
+ requiresTimelineSync?: boolean;
+ },
+) {
+ const issues: string[] = [];
+ const expectedFrames = Math.max(1, Math.round(expected.targetFrames));
+ const minimumFrames = Math.max(1, Math.floor(expectedFrames * 0.95));
+ const expectedDurationSec = Math.max(0, expected.durationSec);
+ const durationToleranceSec = Math.min(2, Math.max(0.5, expectedDurationSec * 0.02));
+ const nativeFrames = getFiniteNumber(summary.nativeSummary?.frames);
+ const outputVideoFrames = getNvidiaCudaOutputStreamNumber(summary.outputVideo, "nb_frames");
+ const outputVideoDurationSec = getNvidiaCudaOutputStreamNumber(summary.outputVideo, "duration");
+ const outputAudioDurationSec = getNvidiaCudaOutputStreamNumber(summary.outputAudio, "duration");
+
+ if (!summary.outputVideo) {
+ issues.push("missing output video probe");
+ }
+ if (expected.requiresTimelineSync && !isNvidiaCudaTimestampAlignedSummary(summary)) {
+ issues.push("CUDA timeline mode is not timestamp-aligned for audio export");
+ }
+ if (expected.requiresTimelineSync) {
+ if (!summary.outputAudio) {
+ issues.push("missing output audio stream");
+ } else if (outputAudioDurationSec === null) {
+ issues.push("missing output audio duration");
+ } else if (outputAudioDurationSec <= 0) {
+ issues.push("output audio duration is not positive");
+ }
+ }
+ if (nativeFrames === null) {
+ issues.push("missing native frame count");
+ } else if (nativeFrames < minimumFrames) {
+ issues.push(`native frames ${nativeFrames} below expected minimum ${minimumFrames}`);
+ }
+ if (outputVideoFrames !== null && outputVideoFrames < minimumFrames) {
+ issues.push(
+ `output video frames ${outputVideoFrames} below expected minimum ${minimumFrames}`,
+ );
+ }
+ if (
+ outputVideoDurationSec !== null &&
+ Math.abs(outputVideoDurationSec - expectedDurationSec) > durationToleranceSec
+ ) {
+ issues.push(
+ `output video duration ${outputVideoDurationSec.toFixed(
+ 3,
+ )}s differs from expected ${expectedDurationSec.toFixed(3)}s`,
+ );
+ }
+ if (
+ outputAudioDurationSec !== null &&
+ outputAudioDurationSec > 0 &&
+ Math.abs(outputAudioDurationSec - expectedDurationSec) > durationToleranceSec
+ ) {
+ issues.push(
+ `output audio duration ${outputAudioDurationSec.toFixed(
+ 3,
+ )}s differs from expected ${expectedDurationSec.toFixed(3)}s`,
+ );
+ }
+
+ return issues;
+}
+
+export function validateWindowsGpuExportSummary(
+ summary: WindowsGpuExportSummary,
+ expected: {
+ durationSec: number;
+ targetFrames: number;
+ },
+) {
+ const issues: string[] = [];
+ const expectedFrames = Math.max(1, Math.round(expected.targetFrames));
+ const minimumFrames = Math.max(1, Math.floor(expectedFrames * 0.95));
+ const expectedDurationSec = Math.max(0, expected.durationSec);
+ const durationToleranceSec = Math.min(2, Math.max(0.5, expectedDurationSec * 0.02));
+ const frames = getFiniteNumber(summary.frames);
+ const mediaMs = getFiniteNumber(summary.mediaMs);
+ const seconds = getFiniteNumber(summary.seconds) ?? (mediaMs !== null ? mediaMs / 1000 : null);
+
+ if (frames === null) {
+ issues.push("missing Windows GPU frame count");
+ } else if (frames < minimumFrames) {
+ issues.push(`Windows GPU frames ${frames} below expected minimum ${minimumFrames}`);
+ }
+ if (
+ seconds !== null &&
+ Number.isFinite(seconds) &&
+ Math.abs(seconds - expectedDurationSec) > durationToleranceSec
+ ) {
+ issues.push(
+ `Windows GPU duration ${seconds.toFixed(3)}s differs from expected ${expectedDurationSec.toFixed(3)}s`,
+ );
+ }
+
+ return issues;
+}
+
+function parseRationalFrameRate(value: unknown) {
+ if (typeof value !== "string") {
+ return null;
+ }
+ const [numeratorRaw, denominatorRaw] = value.split("/");
+ const numerator = Number(numeratorRaw);
+ const denominator = Number(denominatorRaw);
+ if (
+ !Number.isFinite(numerator) ||
+ !Number.isFinite(denominator) ||
+ numerator <= 0 ||
+ denominator <= 0
+ ) {
+ return null;
+ }
+
+ return numerator / denominator;
+}
+
+function parseOptionalPositiveNumber(value: unknown) {
+ const parsed =
+ typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parseOptionalPositiveInteger(value: unknown) {
+ const parsed = parseOptionalPositiveNumber(value);
+ return parsed === null ? null : Math.max(0, Math.round(parsed));
+}
+
+export function parseNativeVideoStreamStatsProbeOutput(
+ output: string,
+): NativeVideoStreamStatsProbe | null {
+ const parsed = JSON.parse(output) as {
+ streams?: Array<{
+ duration?: unknown;
+ nb_frames?: unknown;
+ nb_read_frames?: unknown;
+ avg_frame_rate?: unknown;
+ r_frame_rate?: unknown;
+ }>;
+ };
+ const stream = parsed.streams?.[0];
+ if (!stream) {
+ return null;
+ }
+
+ return {
+ durationSec: parseOptionalPositiveNumber(stream.duration),
+ frameCount:
+ parseOptionalPositiveInteger(stream.nb_read_frames) ??
+ parseOptionalPositiveInteger(stream.nb_frames),
+ frameRate:
+ parseRationalFrameRate(stream.avg_frame_rate) ??
+ parseRationalFrameRate(stream.r_frame_rate),
+ };
+}
+
+export function validateNativeVideoStreamStats(
+ stats: NativeVideoStreamStatsProbe,
+ expected: {
+ durationSec: number;
+ targetFrames: number;
+ },
+) {
+ const issues: string[] = [];
+ const expectedFrames = Math.max(1, Math.round(expected.targetFrames));
+ const minimumFrames = Math.max(1, Math.floor(expectedFrames * 0.95));
+ const expectedDurationSec = Math.max(0, expected.durationSec);
+ const durationToleranceSec = Math.min(2, Math.max(0.5, expectedDurationSec * 0.02));
+
+ if (stats.frameCount === null) {
+ issues.push("missing video frame count");
+ } else if (stats.frameCount < minimumFrames) {
+ issues.push(`video frames ${stats.frameCount} below expected minimum ${minimumFrames}`);
+ }
+
+ if (stats.durationSec === null) {
+ issues.push("missing video stream duration");
+ } else if (Math.abs(stats.durationSec - expectedDurationSec) > durationToleranceSec) {
+ issues.push(
+ `video stream duration ${stats.durationSec.toFixed(
+ 3,
+ )}s differs from expected ${expectedDurationSec.toFixed(3)}s`,
+ );
+ }
+
+ return issues;
+}
+
+function isNvidiaCudaTimestampAlignedSummary(summary: NvidiaCudaExportSummary) {
+ const nativeSummary = summary.nativeSummary;
+ const timelineFields = [
+ nativeSummary?.sourceTimestampMode,
+ nativeSummary?.timelineMode,
+ nativeSummary?.selectionStage,
+ ];
+ return timelineFields.some((value) => {
+ const normalized = String(value ?? "").toLowerCase();
+ return normalized.includes("pts") || normalized.includes("timestamp");
+ });
+}
+
+function shouldPersistNativeExportDiagnostics() {
+ const rawValue = process.env.RECORDLY_NATIVE_EXPORT_DIAGNOSTICS?.trim().toLowerCase();
+ return rawValue !== "0" && rawValue !== "off" && rawValue !== "false";
+}
+
+function shouldPersistNvidiaCudaExportDiagnostics() {
+ return (
+ shouldPersistNativeExportDiagnostics() ||
+ process.env.RECORDLY_NVIDIA_CUDA_EXPORT_DIAGNOSTICS === "1"
+ );
+}
+
+function getSafeDiagnosticsFileSegment(value: string | undefined) {
+ const safe = (value || "session").replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 96);
+ return safe || "session";
+}
+
+function getCliArgValue(args: string[], name: string) {
+ const index = args.indexOf(name);
+ if (index === -1 || index + 1 >= args.length) {
+ return null;
+ }
+ return args[index + 1] || null;
+}
+
+async function persistNvidiaCudaExportDiagnostics(params: {
+ args: string[];
+ code: number | null;
+ elapsedMs: number;
+ outputPath: string;
+ sessionId?: string;
+ signal: NodeJS.Signals | null;
+ startedAtIso: string;
+ stderr: string;
+ stdout: string;
+ summary: NvidiaCudaExportSummary | null;
+ timedOut: boolean;
+}) {
+ if (!shouldPersistNvidiaCudaExportDiagnostics()) {
+ return;
+ }
+
+ const diagnosticsDirectory = path.join(app.getPath("userData"), "native-export-diagnostics");
+ const filePrefix = `${Date.now()}-${getSafeDiagnosticsFileSegment(params.sessionId)}`;
+ const manifest = {
+ backend: "nvidia-cuda-compositor",
+ startedAt: params.startedAtIso,
+ completedAt: new Date().toISOString(),
+ elapsedMs: Number(params.elapsedMs.toFixed(2)),
+ sessionId: params.sessionId ?? null,
+ outputPath: params.outputPath,
+ exitCode: params.code,
+ signal: params.signal,
+ timedOut: params.timedOut,
+ args: params.args,
+ summary: params.summary,
+ };
+
+ try {
+ await fs.mkdir(diagnosticsDirectory, { recursive: true });
+ const artifactsDirectory = path.join(diagnosticsDirectory, `${filePrefix}.artifacts`);
+ const artifactArgs = [
+ "--cursor-json",
+ "--cursor-atlas-png",
+ "--cursor-atlas-metadata",
+ "--zoom-telemetry",
+ ];
+ const artifactCopies = artifactArgs
+ .map((argName) => {
+ const sourcePath = getCliArgValue(params.args, argName);
+ return sourcePath
+ ? {
+ argName,
+ sourcePath,
+ outputPath: path.join(
+ artifactsDirectory,
+ `${getSafeDiagnosticsFileSegment(argName.replace(/^--/, ""))}-${path.basename(sourcePath)}`,
+ ),
+ }
+ : null;
+ })
+ .filter((artifact): artifact is NonNullable => Boolean(artifact));
+ await fs.mkdir(artifactsDirectory, { recursive: true }).catch(() => undefined);
+ await Promise.allSettled([
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.manifest.json`),
+ `${JSON.stringify(manifest, null, 2)}\n`,
+ ),
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.stdout.json`),
+ params.stdout,
+ ),
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.stderr.log`),
+ params.stderr,
+ ),
+ ...artifactCopies.map((artifact) =>
+ fs.copyFile(artifact.sourcePath, artifact.outputPath).catch(() => undefined),
+ ),
+ ]);
+ } catch (error) {
+ console.warn(
+ "[native-static-layout-export] Failed to persist NVIDIA CUDA diagnostics",
+ error,
+ );
+ }
+}
+
+async function persistWindowsGpuExportDiagnostics(params: {
+ args: string[];
+ code: number | null;
+ elapsedMs: number;
+ outputPath: string;
+ signal: NodeJS.Signals | null;
+ startedAtIso: string;
+ stderr: string;
+ stdout: string;
+ summary: WindowsGpuExportSummary | null;
+ timedOut: boolean;
+}) {
+ if (!shouldPersistNativeExportDiagnostics()) {
+ return;
+ }
+
+ const diagnosticsDirectory = path.join(app.getPath("userData"), "native-export-diagnostics");
+ const filePrefix = `${Date.now()}-windows-d3d11-compositor`;
+ const manifest = {
+ backend: "windows-d3d11-compositor",
+ startedAt: params.startedAtIso,
+ completedAt: new Date().toISOString(),
+ elapsedMs: Number(params.elapsedMs.toFixed(2)),
+ outputPath: params.outputPath,
+ exitCode: params.code,
+ signal: params.signal,
+ timedOut: params.timedOut,
+ args: params.args,
+ summary: params.summary,
+ };
+
+ try {
+ await fs.mkdir(diagnosticsDirectory, { recursive: true });
+ await Promise.allSettled([
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.manifest.json`),
+ `${JSON.stringify(manifest, null, 2)}\n`,
+ ),
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.stdout.log`),
+ params.stdout,
+ ),
+ fs.writeFile(
+ path.join(diagnosticsDirectory, `${filePrefix}.stderr.log`),
+ params.stderr,
+ ),
+ ]);
+ } catch (error) {
+ console.warn(
+ "[native-static-layout-export] Failed to persist Windows GPU diagnostics",
+ error,
+ );
+ }
+}
+
+export function parseWindowsGpuExportProgressLine(
+ line: string,
+): NativeStaticLayoutExportProgress | null {
+ const trimmed = line.trim();
+ const prefix = "PROGRESS ";
+ if (!trimmed.startsWith(prefix)) {
+ return null;
+ }
+
+ try {
+ const parsed = JSON.parse(trimmed.slice(prefix.length)) as {
+ currentFrame?: unknown;
+ totalFrames?: unknown;
+ percentage?: unknown;
+ averageFps?: unknown;
+ instantFps?: unknown;
+ intervalMs?: unknown;
+ intervalFrames?: unknown;
+ intervalDecodeWallMs?: unknown;
+ intervalEncodeMs?: unknown;
+ intervalPipelineWaitMs?: unknown;
+ intervalCompositeMs?: unknown;
+ intervalNvencMs?: unknown;
+ intervalPacketWriteMs?: unknown;
+ intervalWebcamDecodeMs?: unknown;
+ intervalWebcamCopyMs?: unknown;
+ intervalRoiCompositeFrames?: unknown;
+ intervalMonolithicCompositeFrames?: unknown;
+ intervalCopyCompositeFrames?: unknown;
+ stage?: unknown;
+ };
+ const currentFrame = Number(parsed.currentFrame);
+ const totalFrames = Number(parsed.totalFrames);
+ const percentage = Number(parsed.percentage);
+ if (
+ !Number.isFinite(currentFrame) ||
+ !Number.isFinite(totalFrames) ||
+ !Number.isFinite(percentage) ||
+ totalFrames <= 0
+ ) {
+ return null;
+ }
+
+ const progress: NativeStaticLayoutExportProgress = {
+ currentFrame: Math.max(0, Math.floor(currentFrame)),
+ totalFrames: Math.max(1, Math.floor(totalFrames)),
+ percentage: Math.min(100, Math.max(0, percentage)),
+ };
+ if (parsed.stage === "preparing" || parsed.stage === "finalizing") {
+ progress.stage = parsed.stage;
+ }
+ const optionalNumberFields = [
+ "averageFps",
+ "instantFps",
+ "intervalMs",
+ "intervalFrames",
+ "intervalDecodeWallMs",
+ "intervalEncodeMs",
+ "intervalPipelineWaitMs",
+ "intervalCompositeMs",
+ "intervalNvencMs",
+ "intervalPacketWriteMs",
+ "intervalWebcamDecodeMs",
+ "intervalWebcamCopyMs",
+ "intervalRoiCompositeFrames",
+ "intervalMonolithicCompositeFrames",
+ "intervalCopyCompositeFrames",
+ ] as const;
+ for (const field of optionalNumberFields) {
+ const value = Number(parsed[field]);
+ if (Number.isFinite(value) && value >= 0) {
+ progress[field] = value;
+ }
+ }
+ return progress;
+ } catch {
+ return null;
+ }
+}
+
+export function mapNvidiaCudaWrapperProgressPercentage(progress: NativeStaticLayoutExportProgress) {
+ if (progress.stage === "finalizing") {
+ return progress.percentage;
+ }
+
+ if (progress.currentFrame > 0 || progress.percentage === 0) {
+ return Math.min(98, 3 + progress.percentage * 0.95);
+ }
+
+ return progress.percentage;
+}
+
+export function hasNativeStaticLayoutProgressAdvanced(
+ progress: { currentFrame: number; percentage: number; stage?: string },
+ previous: { currentFrame: number; percentage: number; stage?: string },
+) {
+ const currentFrame = Math.max(0, Math.floor(progress.currentFrame));
+ const percentage =
+ typeof progress.percentage === "number" && Number.isFinite(progress.percentage)
+ ? progress.percentage
+ : 0;
+ if (currentFrame > previous.currentFrame) {
+ return true;
+ }
+ if (percentage > previous.percentage + 0.1) {
+ return true;
+ }
+ return progress.stage === "finalizing" && previous.stage !== "finalizing";
+}
+
+function startNativeStaticLayoutExportPowerGuard() {
+ try {
+ const blockerId = powerSaveBlocker.start("prevent-app-suspension");
+ return {
+ started: true,
+ release: () => {
+ if (powerSaveBlocker.isStarted(blockerId)) {
+ powerSaveBlocker.stop(blockerId);
+ }
+ },
+ };
+ } catch (error) {
+ console.warn("[native-static-layout-export] Failed to start power guard", error);
+ return {
+ started: false,
+ release: () => undefined,
+ };
+ }
+}
+
+function setNativeStaticLayoutExportProcessPriority(pid: number | undefined, label: string) {
+ if (!pid) {
+ return false;
+ }
+
+ try {
+ os.setPriority(pid, NATIVE_EXPORT_HIGH_PRIORITY);
+ return true;
+ } catch (error) {
+ console.warn(`[native-static-layout-export] Failed to raise ${label} priority`, error);
+ return false;
+ }
+}
+
+export const nativeStaticLayoutExportSessions = new Map();
+
+export interface NativeExportCapabilities {
+ platform: NodeJS.Platform;
+ nvidiaCuda: {
+ available: boolean;
+ skipReason: string | null;
+ hasNvidiaGpu: boolean | null;
+ hasWrapper: boolean;
+ explicitEnabled: boolean;
+ explicitDisabled: boolean;
+ userOptInRequired: boolean;
+ };
+}
+
+export function parseFfmpegDurationSeconds(value: string): number | null {
+ const parts = value.trim().split(":");
+ if (parts.length !== 3) {
+ return null;
+ }
+
+ const [hours, minutes, seconds] = parts.map(Number);
+ if (![hours, minutes, seconds].every(Number.isFinite)) {
+ return null;
+ }
+
+ return hours * 3600 + minutes * 60 + seconds;
+}
+
+export function parseFfmpegFrameRate(line: string): number | null {
+ const fpsMatch = line.match(/,\s*([0-9]+(?:\.[0-9]+)?)\s*fps\b/i);
+ if (fpsMatch) {
+ const frameRate = Number(fpsMatch[1]);
+ return Number.isFinite(frameRate) && frameRate > 0 ? frameRate : null;
+ }
+
+ const tbrMatch = line.match(/,\s*([0-9]+(?:\.[0-9]+)?)\s*tbr\b/i);
+ if (tbrMatch) {
+ const frameRate = Number(tbrMatch[1]);
+ return Number.isFinite(frameRate) && frameRate > 0 ? frameRate : null;
+ }
+
+ return null;
+}
+
+export function parseNativeVideoMetadataProbeOutput(
+ output: string,
+): NativeVideoMetadataProbe | null {
+ const durationMatch = output.match(
+ /Duration:\s*([0-9:.]+),\s*start:\s*(-?[0-9]+(?:\.[0-9]+)?)/i,
+ );
+ const duration = durationMatch ? parseFfmpegDurationSeconds(durationMatch[1]) : null;
+ if (!duration || duration <= 0) {
+ return null;
+ }
+
+ const mediaStartTime = durationMatch ? Number(durationMatch[2]) : 0;
+ const lines = output.split(/\r?\n/);
+ const videoLine = lines.find((line) => /\bVideo:\s*/i.test(line));
+ if (!videoLine) {
+ return null;
+ }
+
+ const dimensionsMatch = videoLine.match(/,\s*([0-9]{2,5})x([0-9]{2,5})(?:[,\s]|$)/);
+ if (!dimensionsMatch) {
+ return null;
+ }
+
+ const width = Number(dimensionsMatch[1]);
+ const height = Number(dimensionsMatch[2]);
+ if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+ return null;
+ }
+
+ const videoCodecMatch = videoLine.match(/Video:\s*([^,\r\n]+)/i);
+ const videoStartMatch = videoLine.match(/\bstart:\s*(-?[0-9]+(?:\.[0-9]+)?)/i);
+ const frameRate = parseFfmpegFrameRate(videoLine) ?? 60;
+ const audioLine = lines.find((line) => /\bAudio:\s*/i.test(line));
+ const audioCodecMatch = audioLine?.match(/Audio:\s*([^,\r\n]+)/i);
+ const audioSampleRateMatch = audioLine?.match(/,\s*([0-9]+)\s*Hz\b/i);
+
+ return {
+ width,
+ height,
+ duration,
+ mediaStartTime: Number.isFinite(mediaStartTime) ? mediaStartTime : 0,
+ streamStartTime: videoStartMatch ? Number(videoStartMatch[1]) : mediaStartTime,
+ streamDuration: duration,
+ frameRate,
+ codec: videoCodecMatch?.[1]?.trim() || "unknown",
+ hasAudio: Boolean(audioLine),
+ audioCodec: audioCodecMatch?.[1]?.trim(),
+ audioSampleRate: audioSampleRateMatch ? Number(audioSampleRateMatch[1]) : undefined,
+ };
+}
+
+export async function probeNativeVideoMetadata(
+ ffmpegPath: string,
+ inputPath: string,
+): Promise {
+ let output = "";
+ try {
+ const result = await execFileAsync(ffmpegPath, ["-hide_banner", "-i", inputPath], {
+ timeout: 30_000,
+ maxBuffer: 4 * 1024 * 1024,
+ });
+ output = `${result.stdout}\n${result.stderr}`;
+ } catch (error) {
+ const processOutput = error as { stdout?: unknown; stderr?: unknown };
+ output = [processOutput.stdout, processOutput.stderr]
+ .filter((value): value is string => typeof value === "string")
+ .join("\n");
+ if (!output) {
+ throw error;
+ }
+ }
+
+ const metadata = parseNativeVideoMetadataProbeOutput(output);
+ if (!metadata) {
+ throw new Error("Unable to parse native video metadata from FFmpeg output");
+ }
+
+ return metadata;
+}
+
+export async function probeNativeVideoStreamStats(
+ ffprobePath: string,
+ inputPath: string,
+): Promise {
+ const result = await execFileAsync(
+ ffprobePath,
+ [
+ "-v",
+ "error",
+ "-select_streams",
+ "v:0",
+ "-count_frames",
+ "-show_entries",
+ "stream=duration,nb_frames,nb_read_frames,avg_frame_rate,r_frame_rate",
+ "-of",
+ "json",
+ inputPath,
+ ],
+ { timeout: 120_000, maxBuffer: 2 * 1024 * 1024 },
+ );
+ const stats = parseNativeVideoStreamStatsProbeOutput(result.stdout);
+ if (!stats) {
+ throw new Error("Unable to parse native video stream stats from FFprobe output");
+ }
+
+ return stats;
+}
+
+async function validateNativeVideoOutputFile(
+ ffprobePath: string,
+ videoPath: string,
+ expected: {
+ durationSec: number;
+ targetFrames: number;
+ },
+) {
+ const stats = await probeNativeVideoStreamStats(ffprobePath, videoPath);
+ const issues = validateNativeVideoStreamStats(stats, expected);
+ if (issues.length > 0) {
+ throw new Error(`Native video output is invalid: ${issues.join("; ")}`);
+ }
+}
+
+export function isNativeStaticLayoutH264SourceCodec(codec: string | undefined) {
+ const normalized = (codec ?? "").trim().toLowerCase();
+ return (
+ /\bh\.?264\b/.test(normalized) ||
+ normalized.includes("avc1") ||
+ normalized.includes("avc3") ||
+ normalized.includes("mpeg-4 avc")
+ );
+}
+
+export function shouldCreateNativeStaticLayoutSourceProxy(
+ metadata: Pick,
+ inputPath: string,
+) {
+ const extension = path.extname(inputPath).toLowerCase();
+ return (
+ !isNativeStaticLayoutH264SourceCodec(metadata.codec) ||
+ !NATIVE_STATIC_LAYOUT_SOURCE_PROXY_CONTAINERS.has(extension)
+ );
+}
+
+export function getNativeStaticLayoutSourceProxyBitrate(
+ options: Pick,
+ metadata?: Pick,
+) {
+ const frameRate = Math.max(1, Math.round(options.frameRate));
+ const width = Math.max(1, Math.round(metadata?.width ?? options.width));
+ const height = Math.max(1, Math.round(metadata?.height ?? options.height));
+ const pixelRateScale = Math.sqrt(
+ (width * height * frameRate) / NATIVE_STATIC_LAYOUT_SOURCE_PROXY_REFERENCE_PIXEL_RATE,
+ );
+ const qualityFloor = Math.round(
+ NATIVE_STATIC_LAYOUT_SOURCE_PROXY_1080P30_BITRATE * pixelRateScale,
+ );
+ return Math.min(
+ NATIVE_STATIC_LAYOUT_SOURCE_PROXY_MAX_BITRATE,
+ Math.max(Math.round(options.bitrate * 1.2), qualityFloor),
+ );
+}
+
+export function buildNativeStaticLayoutSourceProxyArgs(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ metadata: NativeVideoMetadataProbe,
+) {
+ const frameRate = Math.max(1, Math.round(options.frameRate));
+ const sourceDurationSec = Math.max(
+ 0.001,
+ metadata.streamDuration ?? metadata.duration ?? options.durationSec,
+ );
+ const proxyBitrate = getNativeStaticLayoutSourceProxyBitrate(options, metadata);
+ return [
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-i",
+ options.inputPath,
+ "-map",
+ "0:v:0",
+ "-an",
+ "-t",
+ formatCliNumber(sourceDurationSec),
+ "-vf",
+ `fps=fps=${frameRate}:start_time=0,scale=trunc(iw/2)*2:trunc(ih/2)*2,setsar=1,format=yuv420p,setpts=PTS-STARTPTS`,
+ "-c:v",
+ "libx264",
+ "-preset",
+ "veryfast",
+ "-tune",
+ "zerolatency",
+ "-g",
+ String(Math.max(1, Math.round(frameRate * 2))),
+ "-b:v",
+ String(proxyBitrate),
+ "-maxrate",
+ String(Math.round(proxyBitrate * 1.25)),
+ "-bufsize",
+ String(proxyBitrate * 2),
+ "-pix_fmt",
+ "yuv420p",
+ "-movflags",
+ "+faststart",
+ outputPath,
+ ];
+}
+
+export function validateNativeStaticLayoutSourceProxyMetadata(
+ metadata: NativeVideoMetadataProbe,
+ expected: { sourceDurationSec: number },
+) {
+ const issues: string[] = [];
+ const expectedDurationSec = Math.max(0, expected.sourceDurationSec);
+ const durationToleranceSec = Math.min(2, Math.max(0.5, expectedDurationSec * 0.03));
+ if (!isNativeStaticLayoutH264SourceCodec(metadata.codec)) {
+ issues.push(`proxy codec is not H.264/AVC: ${metadata.codec || "unknown"}`);
+ }
+ if (!Number.isFinite(metadata.duration) || metadata.duration <= 0) {
+ issues.push("proxy duration is unavailable");
+ } else if (metadata.duration + durationToleranceSec < expectedDurationSec) {
+ issues.push(
+ `proxy duration ${metadata.duration.toFixed(
+ 3,
+ )}s shorter than expected ${expectedDurationSec.toFixed(3)}s`,
+ );
+ }
+ return issues;
+}
+
+export function getNativeVideoExportMaxQueuedWriteBytes(inputByteSize: number) {
+ if (inputByteSize === 0) return 8 * 1024 * 1024;
+ return Math.min(64 * 1024 * 1024, Math.max(16 * 1024 * 1024, inputByteSize * 4));
+}
+
+async function runFfmpegWithMetrics(
+ ffmpegPath: string,
+ args: string[],
+ timeoutMs: number,
+ session?: NativeStaticLayoutExportSession,
+): Promise<{
+ success: boolean;
+ elapsedMs: number;
+ stderr: string;
+ code: number | null;
+ signal: NodeJS.Signals | null;
+}> {
+ const startedAt = getNowMs();
+ return await new Promise((resolve) => {
+ const child = spawn(ffmpegPath, args, {
+ stdio: ["ignore", "ignore", "pipe"],
+ });
+ if (session) {
+ session.currentProcess = child;
+ if (session.terminating) {
+ child.kill("SIGKILL");
+ }
+ }
+ let stderr = "";
+ let settled = false;
+ const timeout = setTimeout(() => {
+ if (settled) return;
+ try {
+ child.kill("SIGKILL");
+ } catch {
+ // ignore
+ }
+ }, timeoutMs);
+
+ child.stderr.on("data", (chunk: Buffer) => {
+ stderr += chunk.toString();
+ });
+ child.once("error", (error) => {
+ if (settled) return;
+ settled = true;
+ if (session?.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ resolve({
+ success: false,
+ elapsedMs: getNowMs() - startedAt,
+ stderr: error instanceof Error ? error.message : String(error),
+ code: null,
+ signal: null,
+ });
+ });
+ child.once("close", (code, signal) => {
+ if (settled) return;
+ settled = true;
+ if (session?.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ resolve({
+ success: code === 0,
+ elapsedMs: getNowMs() - startedAt,
+ stderr,
+ code,
+ signal,
+ });
+ });
+ });
+}
+
+function parseFfmpegProgressClockSeconds(value: string) {
+ const match = value.match(/^(\d+):(\d+):(\d+(?:\.\d+)?)$/);
+ if (!match) {
+ return null;
+ }
+
+ const hours = Number(match[1]);
+ const minutes = Number(match[2]);
+ const seconds = Number(match[3]);
+ if (![hours, minutes, seconds].every(Number.isFinite)) {
+ return null;
+ }
+
+ return hours * 3600 + minutes * 60 + seconds;
+}
+
+export function parseFfmpegProgressLineSeconds(line: string) {
+ const separatorIndex = line.indexOf("=");
+ if (separatorIndex <= 0) {
+ return null;
+ }
+
+ const key = line.slice(0, separatorIndex).trim();
+ const value = line.slice(separatorIndex + 1).trim();
+ if (key === "out_time_us" || key === "out_time_ms") {
+ const microseconds = Number(value);
+ return Number.isFinite(microseconds) && microseconds >= 0 ? microseconds / 1_000_000 : null;
+ }
+ if (key === "out_time") {
+ return parseFfmpegProgressClockSeconds(value);
+ }
+
+ return null;
+}
+
+function createFfmpegMuxProgressHandler(
+ totalSec: number | undefined,
+ onProgress?: (progress: NativeVideoAudioMuxProgress) => void,
+) {
+ if (!onProgress || !Number.isFinite(totalSec) || !totalSec || totalSec <= 0) {
+ return () => undefined;
+ }
+
+ let lineBuffer = "";
+ let lastRatio = 0;
+ return (chunk: Buffer | string) => {
+ lineBuffer += chunk.toString();
+ const lines = lineBuffer.split(/\r?\n/);
+ lineBuffer = lines.pop() ?? "";
+ for (const line of lines) {
+ const processedSec = parseFfmpegProgressLineSeconds(line);
+ if (processedSec === null) {
+ continue;
+ }
+ const ratio = Math.max(0, Math.min(1, processedSec / totalSec));
+ if (ratio < lastRatio + 0.0025 && ratio < 1) {
+ continue;
+ }
+ lastRatio = Math.max(lastRatio, ratio);
+ onProgress({
+ ratio: lastRatio,
+ processedSec,
+ totalSec,
+ });
+ }
+ };
+}
+
+async function runFfmpegAudioMux(
+ ffmpegPath: string,
+ args: string[],
+ timeoutMs: number,
+ options: NativeVideoExportFinishOptions,
+ onProgress?: (progress: NativeVideoAudioMuxProgress) => void,
+ session?: NativeStaticLayoutExportSession,
+) {
+ if (!onProgress && !session) {
+ await execFileAsync(ffmpegPath, args, {
+ timeout: timeoutMs,
+ maxBuffer: 20 * 1024 * 1024,
+ });
+ return;
+ }
+
+ const handleProgressChunk = createFfmpegMuxProgressHandler(
+ options.outputDurationSec,
+ onProgress,
+ );
+ await new Promise((resolve, reject) => {
+ const child = spawn(ffmpegPath, args, {
+ stdio: ["ignore", "ignore", "pipe"],
+ });
+ if (session) {
+ session.currentProcess = child;
+ if (session.terminating) {
+ child.kill("SIGKILL");
+ }
+ }
+
+ let stderr = "";
+ let settled = false;
+ const timeout = setTimeout(() => {
+ if (settled) return;
+ child.kill("SIGKILL");
+ }, timeoutMs);
+
+ child.stderr.on("data", (chunk: Buffer) => {
+ const text = chunk.toString();
+ stderr += text;
+ handleProgressChunk(text);
+ });
+ child.once("error", (error) => {
+ if (settled) return;
+ settled = true;
+ if (session?.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ reject(error);
+ });
+ child.once("close", (code, signal) => {
+ if (settled) return;
+ settled = true;
+ if (session?.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ if (session?.terminating) {
+ reject(new Error("Native static layout export was cancelled"));
+ return;
+ }
+ if (code !== 0) {
+ const suffix = signal ? ` (signal ${signal})` : "";
+ reject(
+ new Error(
+ `FFmpeg audio mux exited with code ${code ?? "unknown"}${suffix}` +
+ (stderr.trim() ? `\nSTDERR:\n${stderr.trim()}` : ""),
+ ),
+ );
+ return;
+ }
+ if (onProgress) {
+ const completeProgress: NativeVideoAudioMuxProgress = { ratio: 1 };
+ if (
+ typeof options.outputDurationSec === "number" &&
+ Number.isFinite(options.outputDurationSec)
+ ) {
+ completeProgress.processedSec = options.outputDurationSec;
+ completeProgress.totalSec = options.outputDurationSec;
+ }
+ onProgress(completeProgress);
+ }
+ resolve();
+ });
+ });
+}
+
+export function isHardwareAcceleratedVideoEncoder(encoderName: string) {
+ return /(videotoolbox|nvenc|qsv|amf|mf)/i.test(encoderName);
+}
+
+export async function removeTemporaryExportFile(filePath: string | null | undefined) {
+ if (!filePath) {
+ return;
+ }
+
+ try {
+ await fs.rm(filePath, { force: true });
+ } catch {
+ // Ignore cleanup failures for temp export artifacts.
+ }
+}
+
+export function getNativeVideoExportSessionError(
+ session: NativeVideoExportSession,
+ fallback: string,
+) {
+ return (
+ session.stdinError?.message ||
+ session.processError?.message ||
+ session.stderrOutput.trim() ||
+ fallback
+ );
+}
+
+export function sendNativeVideoExportWriteFrameResult(
+ sender: WebContents | null | undefined,
+ sessionId: string,
+ requestId: number,
+ result: { success: boolean; error?: string },
+) {
+ if (!sender || sender.isDestroyed()) {
+ return;
+ }
+
+ sender.send("native-video-export-write-frame-result", {
+ sessionId,
+ requestId,
+ ...result,
+ });
+}
+
+export function settleNativeVideoExportWriteFrameRequest(
+ sessionId: string,
+ session: NativeVideoExportSession,
+ requestId: number,
+ result: { success: boolean; error?: string },
+) {
+ session.pendingWriteRequestIds.delete(requestId);
+ sendNativeVideoExportWriteFrameResult(session.sender, sessionId, requestId, result);
+}
+
+export function flushNativeVideoExportPendingWriteRequests(
+ sessionId: string,
+ session: NativeVideoExportSession,
+ error: string,
+) {
+ for (const requestId of session.pendingWriteRequestIds) {
+ sendNativeVideoExportWriteFrameResult(session.sender, sessionId, requestId, {
+ success: false,
+ error,
+ });
+ }
+
+ session.pendingWriteRequestIds.clear();
+}
+
+export function isIgnorableNativeVideoExportStreamError(error: Error | null | undefined): boolean {
+ if (!error) {
+ return false;
+ }
+
+ const errno = error as NodeJS.ErrnoException;
+ return (
+ errno.code === "EPIPE" ||
+ errno.code === "ERR_STREAM_DESTROYED" ||
+ /broken pipe|stream destroyed|eof/i.test(error.message)
+ );
+}
+
+export async function waitForNativeVideoExportDrain(session: NativeVideoExportSession) {
+ if (
+ session.stdinError ||
+ session.processError ||
+ session.ffmpegProcess.stdin.destroyed ||
+ session.ffmpegProcess.stdin.writableEnded ||
+ !session.ffmpegProcess.stdin.writable ||
+ session.ffmpegProcess.stdin.writableLength <= 0
+ ) {
+ return;
+ }
+
+ await new Promise((resolve, reject) => {
+ const timeout = setTimeout(() => {
+ cleanup();
+ reject(
+ new Error("Timed out while waiting for native export writer backpressure to clear"),
+ );
+ }, 15000);
+
+ const cleanup = () => {
+ clearTimeout(timeout);
+ session.ffmpegProcess.stdin.off("drain", handleDrain);
+ session.ffmpegProcess.stdin.off("error", handleError);
+ session.ffmpegProcess.off("close", handleClose);
+ };
+
+ const handleDrain = () => {
+ cleanup();
+ resolve();
+ };
+
+ const handleError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const handleClose = () => {
+ cleanup();
+ reject(
+ new Error(
+ getNativeVideoExportSessionError(
+ session,
+ "Native video export writer closed before draining",
+ ),
+ ),
+ );
+ };
+
+ session.ffmpegProcess.stdin.once("drain", handleDrain);
+ session.ffmpegProcess.stdin.once("error", handleError);
+ session.ffmpegProcess.once("close", handleClose);
+ });
+}
+
+export function getNativeVideoExportFrameLength(frameData: Uint8Array | ArrayBuffer) {
+ return frameData.byteLength;
+}
+
+export async function writeNativeVideoExportFrame(
+ session: NativeVideoExportSession,
+ frameData: Uint8Array | ArrayBuffer,
+) {
+ if (
+ session.inputMode !== "h264-stream" &&
+ getNativeVideoExportFrameLength(frameData) !== session.inputByteSize
+ ) {
+ throw new Error(
+ `Native video export expected ${session.inputByteSize} bytes per frame but received ${getNativeVideoExportFrameLength(frameData)}`,
+ );
+ }
+
+ if (
+ session.stdinError ||
+ session.processError ||
+ session.ffmpegProcess.stdin.destroyed ||
+ session.ffmpegProcess.stdin.writableEnded ||
+ !session.ffmpegProcess.stdin.writable
+ ) {
+ throw new Error(
+ getNativeVideoExportSessionError(
+ session,
+ "Native video export encoder is not accepting frames",
+ ),
+ );
+ }
+
+ const frameBuffer =
+ frameData instanceof ArrayBuffer
+ ? Buffer.from(frameData)
+ : Buffer.from(frameData.buffer, frameData.byteOffset, frameData.byteLength);
+
+ try {
+ session.ffmpegProcess.stdin.write(frameBuffer);
+ } catch (error) {
+ session.stdinError = error instanceof Error ? error : new Error(String(error));
+ throw session.stdinError;
+ }
+
+ if (session.ffmpegProcess.stdin.writableLength >= session.maxQueuedWriteBytes) {
+ try {
+ await waitForNativeVideoExportDrain(session);
+ } catch (error) {
+ session.stdinError = error instanceof Error ? error : new Error(String(error));
+ throw session.stdinError;
+ }
+ }
+}
+
+function toConcatFileLine(filePath: string) {
+ const normalized = filePath.replace(/\\/g, "/").replace(/'/g, "'\\''");
+ return `file '${normalized}'`;
+}
+
+function getStaticLayoutChunkOutputPath(directory: string, index: number) {
+ return path.join(directory, `chunk-${String(index).padStart(4, "0")}.mp4`);
+}
+
+function shouldUsePrecompositedStaticLayout(options: NativeStaticLayoutExportOptions) {
+ return Boolean(
+ options.backgroundImagePath ||
+ (options.borderRadius ?? 0) > 0.5 ||
+ (options.shadowIntensity ?? 0) > 0,
+ );
+}
+
+export async function normalizeNativeStaticLayoutBackground(
+ options: NativeStaticLayoutExportOptions,
+): Promise {
+ if (!options.backgroundImagePath || (await pathExists(options.backgroundImagePath))) {
+ return options;
+ }
+
+ console.warn(
+ "[native-static-layout-export] Background image is missing; using solid fallback",
+ {
+ backgroundImagePath: options.backgroundImagePath,
+ },
+ );
+ return {
+ ...options,
+ backgroundColor: MISSING_NATIVE_STATIC_BACKGROUND_COLOR,
+ backgroundImagePath: null,
+ };
+}
+
+function getFfmpegFailureMessage(result: Awaited>) {
+ const suffix = result.signal ? ` (signal ${result.signal})` : "";
+ const status = result.code === null ? "unknown" : String(result.code);
+ return result.stderr.trim() || `FFmpeg exited with code ${status}${suffix}`;
+}
+
+function clampUnit(value: number) {
+ if (!Number.isFinite(value)) {
+ return 0;
+ }
+
+ return Math.min(1, Math.max(0, value));
+}
+
+function formatCliNumber(value: number) {
+ return Number.isInteger(value)
+ ? String(value)
+ : value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function hasNativeStaticLayoutTimeline(options: NativeStaticLayoutExportOptions) {
+ return (options.timelineSegments?.length ?? 0) > 0;
+}
+
+function hasNativeStaticLayoutSourceCrop(options: NativeStaticLayoutExportOptions) {
+ return Boolean(
+ Number.isFinite(options.sourceCropWidth) &&
+ Number.isFinite(options.sourceCropHeight) &&
+ (options.sourceCropWidth ?? 0) >= 2 &&
+ (options.sourceCropHeight ?? 0) >= 2,
+ );
+}
+
+export function buildNativeStaticLayoutTimelineSegments(
+ segments: NativeVideoExportEditedTrackSegment[],
+): NativeStaticLayoutTimelineSegment[] {
+ const timelineSegments: NativeStaticLayoutTimelineSegment[] = [];
+ let outputCursorMs = 0;
+
+ for (const segment of segments) {
+ const sourceStartMs = Math.max(0, segment.startMs);
+ const sourceEndMs = Math.max(sourceStartMs, segment.endMs);
+ const speed = segment.speed;
+ if (
+ !Number.isFinite(sourceStartMs) ||
+ !Number.isFinite(sourceEndMs) ||
+ !Number.isFinite(speed) ||
+ sourceEndMs - sourceStartMs <= 0.5 ||
+ speed <= 0
+ ) {
+ return [];
+ }
+
+ const outputDurationMs = (sourceEndMs - sourceStartMs) / speed;
+ if (!Number.isFinite(outputDurationMs) || outputDurationMs <= 0.5) {
+ return [];
+ }
+
+ const outputStartMs = outputCursorMs;
+ const outputEndMs = outputStartMs + outputDurationMs;
+ timelineSegments.push({
+ sourceStartMs,
+ sourceEndMs,
+ outputStartMs,
+ outputEndMs,
+ speed,
+ });
+ outputCursorMs = outputEndMs;
+ }
+
+ return timelineSegments;
+}
+
+function validateNativeStaticLayoutTimelineSegments(
+ segments: NativeStaticLayoutTimelineSegment[] | undefined,
+ durationSec: number,
+) {
+ if (!segments?.length) {
+ return [];
+ }
+
+ const normalized: NativeStaticLayoutTimelineSegment[] = [];
+ let expectedOutputStartMs = 0;
+ for (const segment of segments) {
+ const sourceStartMs = Math.max(0, segment.sourceStartMs);
+ const sourceEndMs = Math.max(sourceStartMs, segment.sourceEndMs);
+ const outputStartMs = Math.max(0, segment.outputStartMs);
+ const outputEndMs = Math.max(outputStartMs, segment.outputEndMs);
+ const speed = segment.speed;
+ if (
+ !Number.isFinite(sourceStartMs) ||
+ !Number.isFinite(sourceEndMs) ||
+ !Number.isFinite(outputStartMs) ||
+ !Number.isFinite(outputEndMs) ||
+ !Number.isFinite(speed) ||
+ sourceEndMs - sourceStartMs <= 0.5 ||
+ outputEndMs - outputStartMs <= 0.5 ||
+ speed <= 0
+ ) {
+ throw new Error("Native timeline map contains an invalid segment");
+ }
+
+ if (Math.abs(outputStartMs - expectedOutputStartMs) > 2) {
+ throw new Error("Native timeline map output ranges must be contiguous");
+ }
+
+ const expectedOutputDurationMs = (sourceEndMs - sourceStartMs) / speed;
+ if (Math.abs(expectedOutputDurationMs - (outputEndMs - outputStartMs)) > 2) {
+ throw new Error("Native timeline map segment speed does not match its output duration");
+ }
+
+ normalized.push({
+ sourceStartMs,
+ sourceEndMs,
+ outputStartMs,
+ outputEndMs,
+ speed,
+ });
+ expectedOutputStartMs = outputEndMs;
+ }
+
+ if (Math.abs(expectedOutputStartMs / 1000 - durationSec) > 0.05) {
+ throw new Error("Native timeline map duration does not match the export duration");
+ }
+
+ return normalized;
+}
+
+async function prepareNativeStaticLayoutTimelineMap(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ const segments = validateNativeStaticLayoutTimelineSegments(
+ options.timelineSegments,
+ options.durationSec,
+ );
+ if (segments.length === 0) {
+ return null;
+ }
+
+ const lines = segments.map((segment) =>
+ [
+ segment.sourceStartMs,
+ segment.sourceEndMs,
+ segment.outputStartMs,
+ segment.outputEndMs,
+ segment.speed,
+ ]
+ .map(formatCliNumber)
+ .join(","),
+ );
+ await fs.writeFile(outputPath, `${lines.join("\n")}\n`, "utf8");
+ return outputPath;
+}
+
+async function pathExists(filePath: string) {
+ try {
+ await fs.access(filePath);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function isNvidiaVendorId(value: unknown) {
+ if (typeof value === "number") {
+ return value === NVIDIA_PCI_VENDOR_ID;
+ }
+ if (typeof value !== "string") {
+ return false;
+ }
+
+ const normalized = value.trim().toLowerCase();
+ if (normalized.length === 0) {
+ return false;
+ }
+ const parsed = normalized.startsWith("0x")
+ ? Number.parseInt(normalized.slice(2), 16)
+ : Number.parseInt(normalized, 10);
+
+ return Number.isFinite(parsed) && parsed === NVIDIA_PCI_VENDOR_ID;
+}
+
+function includesNvidiaGpuName(value: unknown) {
+ return typeof value === "string" && /\bnvidia\b/i.test(value);
+}
+
+function isNvidiaGpuDevice(device: unknown) {
+ if (!device || typeof device !== "object") {
+ return false;
+ }
+
+ const gpuDevice = device as ElectronGpuDeviceLike;
+ return (
+ isNvidiaVendorId(gpuDevice.vendorId) ||
+ includesNvidiaGpuName(gpuDevice.vendorString) ||
+ includesNvidiaGpuName(gpuDevice.deviceString)
+ );
+}
+
+export function hasNvidiaGpuDeviceInGpuInfo(gpuInfo: unknown) {
+ if (!gpuInfo || typeof gpuInfo !== "object") {
+ return false;
+ }
+
+ const devices = (gpuInfo as ElectronGpuInfoLike).gpuDevice;
+ return Array.isArray(devices) && devices.some(isNvidiaGpuDevice);
+}
+
+async function hasNvidiaGpuForCudaExportCandidate() {
+ const hasNvidiaGpu = await probeNvidiaGpuForCudaExportCandidate();
+ return hasNvidiaGpu ?? true;
+}
+
+async function probeNvidiaGpuForCudaExportCandidate(): Promise {
+ const getGPUInfo = (
+ app as typeof app & {
+ getGPUInfo?: (infoType: "basic") => Promise;
+ }
+ ).getGPUInfo;
+ if (typeof getGPUInfo !== "function") {
+ return null;
+ }
+
+ try {
+ return hasNvidiaGpuDeviceInGpuInfo(await getGPUInfo.call(app, "basic"));
+ } catch (error) {
+ console.warn(
+ "[native-static-layout-export] Unable to inspect GPU info before NVIDIA CUDA export; letting the helper decide",
+ error,
+ );
+ return null;
+ }
+}
+
+function getNativeBinPlatformArch() {
+ return process.arch === "arm64" ? "win32-arm64" : "win32-x64";
+}
+
+async function resolveExperimentalWindowsGpuExporterPath() {
+ if (process.platform !== "win32") {
+ return null;
+ }
+
+ const executableNames = ["recordly-gpu-export.exe", "gpu-export-probe.exe"];
+ const candidates: string[] = [];
+ const configuredPath = process.env.RECORDLY_WINDOWS_GPU_EXPORT_EXE;
+ if (configuredPath) {
+ candidates.push(configuredPath);
+ }
+
+ const nativeBinDir = path.join("electron", "native", "bin", getNativeBinPlatformArch());
+ const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;
+ if (resourcesPath) {
+ for (const executableName of executableNames) {
+ candidates.push(
+ path.join(resourcesPath, "app.asar.unpacked", nativeBinDir, executableName),
+ path.join(resourcesPath, nativeBinDir, executableName),
+ );
+ }
+ }
+
+ for (const executableName of executableNames) {
+ candidates.push(
+ path.join(process.cwd(), nativeBinDir, executableName),
+ path.join(
+ app.getAppPath().replace(/app\.asar$/, "app.asar.unpacked"),
+ nativeBinDir,
+ executableName,
+ ),
+ path.join(process.cwd(), ".tmp", "gpu-export-probe-build", "Release", executableName),
+ path.join(
+ process.cwd(),
+ "electron",
+ "native",
+ "gpu-export-probe",
+ "build",
+ "Release",
+ executableName,
+ ),
+ );
+ }
+
+ for (const candidate of candidates) {
+ if (await pathExists(candidate)) {
+ return candidate;
+ }
+ }
+
+ return null;
+}
+
+export function getNvidiaCudaAudioExportSkipReason(
+ audioMode: NativeVideoExportAudioMode | undefined,
+ options: { allowValidatedFallbackCandidate?: boolean } = {},
+) {
+ const resolvedAudioMode = audioMode ?? "none";
+ if (resolvedAudioMode === "none") {
+ return null;
+ }
+ if (process.env[NVIDIA_CUDA_ALLOW_AUDIO_EXPORT_ENV] === "1") {
+ return null;
+ }
+ if (options.allowValidatedFallbackCandidate) {
+ return null;
+ }
+
+ return `audio-mode:${resolvedAudioMode}`;
+}
+
+function isExplicitNvidiaCudaExportEnabled() {
+ return process.env[NVIDIA_CUDA_EXPORT_ENV] === "1";
+}
+
+function isExplicitNvidiaCudaExportDisabled() {
+ return process.env[NVIDIA_CUDA_EXPORT_ENV] === "0";
+}
+
+function isUserOptedInNvidiaCudaExport(options: NativeStaticLayoutExportOptions) {
+ return options.experimentalNvidiaCudaExport === true && !isExplicitNvidiaCudaExportDisabled();
+}
+
+function isValidatedNvidiaCudaFallbackCandidate(options: NativeStaticLayoutExportOptions) {
+ return isUserOptedInNvidiaCudaExport(options) && !isExplicitNvidiaCudaExportEnabled();
+}
+
+function isNvidiaCudaForceVideoOnlyEnabled() {
+ return process.env[NVIDIA_CUDA_FORCE_VIDEO_ONLY_ENV] === "1";
+}
+
+export function getNvidiaCudaAutoStallTimeoutMs(autoCandidateActive = false) {
+ if (!autoCandidateActive && !isExplicitNvidiaCudaExportEnabled()) {
+ return null;
+ }
+
+ const rawValue = process.env[NVIDIA_CUDA_AUTO_STALL_TIMEOUT_ENV]?.trim();
+ if (rawValue === "0" || rawValue?.toLowerCase() === "off") {
+ return null;
+ }
+
+ const parsed = Number(rawValue);
+ if (Number.isFinite(parsed) && parsed > 0) {
+ return Math.max(10_000, Math.round(parsed));
+ }
+
+ return DEFAULT_NVIDIA_CUDA_AUTO_STALL_TIMEOUT_MS;
+}
+
+export function getNativeGpuCompositorStallTimeoutMs() {
+ const rawValue = process.env[NATIVE_GPU_STALL_TIMEOUT_ENV]?.trim();
+ if (rawValue === "0" || rawValue?.toLowerCase() === "off") {
+ return null;
+ }
+
+ const parsed = Number(rawValue);
+ if (Number.isFinite(parsed) && parsed > 0) {
+ return Math.max(10_000, Math.round(parsed));
+ }
+
+ return DEFAULT_NATIVE_GPU_STALL_TIMEOUT_MS;
+}
+
+export async function getExperimentalNvidiaCudaExportSkipReason(
+ options: NativeStaticLayoutExportOptions,
+) {
+ if (process.platform !== "win32") {
+ return "not-windows";
+ }
+ if (isExplicitNvidiaCudaExportDisabled()) {
+ return "env-disabled";
+ }
+ const explicitCuda = isExplicitNvidiaCudaExportEnabled();
+ const userOptIn = isUserOptedInNvidiaCudaExport(options);
+ if (!explicitCuda && !userOptIn) {
+ return "env-disabled";
+ }
+ if (!options.experimentalWindowsGpuCompositor) {
+ return "windows-gpu-compositor-disabled";
+ }
+
+ if (userOptIn) {
+ if (!(await resolveExperimentalNvidiaCudaExportScriptPath())) {
+ return "cuda-wrapper-unavailable";
+ }
+ if (!(await hasNvidiaGpuForCudaExportCandidate())) {
+ return "nvidia-gpu-unavailable";
+ }
+ }
+
+ return getNvidiaCudaAudioExportSkipReason(options.audioOptions?.audioMode, {
+ allowValidatedFallbackCandidate:
+ isValidatedNvidiaCudaFallbackCandidate(options) || isNvidiaCudaForceVideoOnlyEnabled(),
+ });
+}
+
+export async function getNativeExportCapabilities(): Promise {
+ if (process.platform !== "win32") {
+ return {
+ platform: process.platform,
+ nvidiaCuda: {
+ available: false,
+ skipReason: "not-windows",
+ hasNvidiaGpu: null,
+ hasWrapper: false,
+ explicitEnabled: isExplicitNvidiaCudaExportEnabled(),
+ explicitDisabled: isExplicitNvidiaCudaExportDisabled(),
+ userOptInRequired: true,
+ },
+ };
+ }
+
+ const explicitEnabled = isExplicitNvidiaCudaExportEnabled();
+ const explicitDisabled = isExplicitNvidiaCudaExportDisabled();
+ const wrapperPath = await resolveExperimentalNvidiaCudaExportScriptPath();
+ const hasNvidiaGpu = await probeNvidiaGpuForCudaExportCandidate();
+ const skipReason = explicitDisabled
+ ? "env-disabled"
+ : !wrapperPath
+ ? "cuda-wrapper-unavailable"
+ : hasNvidiaGpu === false
+ ? "nvidia-gpu-unavailable"
+ : hasNvidiaGpu === null
+ ? "nvidia-gpu-probe-unavailable"
+ : null;
+
+ return {
+ platform: process.platform,
+ nvidiaCuda: {
+ available: skipReason === null,
+ skipReason,
+ hasNvidiaGpu,
+ hasWrapper: Boolean(wrapperPath),
+ explicitEnabled,
+ explicitDisabled,
+ userOptInRequired: !explicitEnabled,
+ },
+ };
+}
+
+export async function resolveExperimentalNvidiaCudaExportScriptPath() {
+ if (process.platform !== "win32") {
+ return null;
+ }
+
+ const candidates: string[] = [];
+ const configuredPath = process.env.RECORDLY_NVIDIA_CUDA_EXPORT_SCRIPT;
+ if (configuredPath) {
+ candidates.push(configuredPath);
+ }
+ const resourcesPath = (process as NodeJS.Process & { resourcesPath?: string }).resourcesPath;
+ if (resourcesPath) {
+ candidates.push(
+ path.join(
+ resourcesPath,
+ "app.asar.unpacked",
+ "electron",
+ "native",
+ "nvidia-cuda-compositor",
+ "run-mp4-pipeline.mjs",
+ ),
+ );
+ }
+ candidates.push(
+ path.join(
+ process.cwd(),
+ "electron",
+ "native",
+ "nvidia-cuda-compositor",
+ "run-mp4-pipeline.mjs",
+ ),
+ path.join(
+ app.getAppPath().replace(/app\.asar$/, "app.asar.unpacked"),
+ "electron",
+ "native",
+ "nvidia-cuda-compositor",
+ "run-mp4-pipeline.mjs",
+ ),
+ path.join(
+ app.getAppPath(),
+ "electron",
+ "native",
+ "nvidia-cuda-compositor",
+ "run-mp4-pipeline.mjs",
+ ),
+ path.join(process.cwd(), ".tmp", "nvdec-nvenc-probe", "run-mp4-pipeline.mjs"),
+ path.join(app.getAppPath(), ".tmp", "nvdec-nvenc-probe", "run-mp4-pipeline.mjs"),
+ );
+
+ for (const candidate of candidates) {
+ if (await pathExists(candidate)) {
+ return candidate;
+ }
+ }
+
+ return null;
+}
+
+function resolveExperimentalNvidiaCudaNodeCommand() {
+ const configuredNodePath = process.env.RECORDLY_NVIDIA_CUDA_NODE_EXE;
+ if (configuredNodePath) {
+ return {
+ command: configuredNodePath,
+ env: {},
+ };
+ }
+
+ return {
+ command: process.execPath,
+ env: {
+ ELECTRON_RUN_AS_NODE: "1",
+ },
+ };
+}
+
+function convertHexColorToNv12(color: string) {
+ const hex = color.trim().match(/^#?([0-9a-f]{6})$/i)?.[1] ?? "101010";
+ const r = Number.parseInt(hex.slice(0, 2), 16);
+ const g = Number.parseInt(hex.slice(2, 4), 16);
+ const b = Number.parseInt(hex.slice(4, 6), 16);
+ const clampByte = (value: number) => Math.max(0, Math.min(255, Math.round(value)));
+
+ return {
+ y: clampByte(((66 * r + 129 * g + 25 * b + 128) >> 8) + 16),
+ u: clampByte(((-38 * r - 74 * g + 112 * b + 128) >> 8) + 128),
+ v: clampByte(((112 * r - 94 * g - 18 * b + 128) >> 8) + 128),
+ };
+}
+
+function getNvidiaCudaBitrateMbps(options: NativeStaticLayoutExportOptions) {
+ return Math.max(1, Math.round(options.bitrate / 1_000_000));
+}
+
+export function buildExperimentalWindowsGpuStaticLayoutArgs(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ const shadowPixels = Math.round(clampUnit(options.shadowIntensity ?? 0) * 64);
+ const backgroundBlurPx = Math.max(0, options.backgroundBlurPx ?? 0);
+ const pixelCount = options.width * options.height;
+ const surfacePoolSize = pixelCount <= 1920 * 1080 ? 12 : 8;
+ const args = [
+ "--input",
+ options.inputPath,
+ "--output",
+ outputPath,
+ "--width",
+ String(options.width),
+ "--height",
+ String(options.height),
+ "--fps",
+ String(options.frameRate),
+ "--seconds",
+ formatCliNumber(options.durationSec),
+ "--bitrate",
+ String(options.bitrate),
+ "--shader-composite",
+ "--radius",
+ formatCliNumber(Math.max(0, options.borderRadius ?? 0)),
+ "--shadow",
+ formatCliNumber(shadowPixels),
+ "--content-left",
+ String(Math.round(options.offsetX)),
+ "--content-top",
+ String(Math.round(options.offsetY)),
+ "--content-width",
+ String(Math.round(options.contentWidth)),
+ "--content-height",
+ String(Math.round(options.contentHeight)),
+ "--background-color",
+ options.backgroundColor,
+ "--surface-pool-size",
+ String(surfacePoolSize),
+ ];
+
+ if (options.backgroundImagePath) {
+ args.push("--background-image", options.backgroundImagePath);
+ }
+ if (
+ Number.isFinite(options.sourceCropX) &&
+ Number.isFinite(options.sourceCropY) &&
+ Number.isFinite(options.sourceCropWidth) &&
+ Number.isFinite(options.sourceCropHeight) &&
+ (options.sourceCropWidth ?? 0) >= 2 &&
+ (options.sourceCropHeight ?? 0) >= 2
+ ) {
+ args.push(
+ "--source-crop-x",
+ String(Math.round(options.sourceCropX ?? 0)),
+ "--source-crop-y",
+ String(Math.round(options.sourceCropY ?? 0)),
+ "--source-crop-width",
+ String(Math.round(options.sourceCropWidth ?? 0)),
+ "--source-crop-height",
+ String(Math.round(options.sourceCropHeight ?? 0)),
+ );
+ }
+ if (backgroundBlurPx > 0) {
+ args.push("--background-blur", formatCliNumber(backgroundBlurPx));
+ }
+ if (options.webcamInputPath) {
+ const webcamShadowPixels = Math.round(clampUnit(options.webcamShadowIntensity ?? 0) * 64);
+ args.push(
+ "--webcam-input",
+ options.webcamInputPath,
+ "--webcam-left",
+ String(Math.round(options.webcamLeft ?? 0)),
+ "--webcam-top",
+ String(Math.round(options.webcamTop ?? 0)),
+ "--webcam-size",
+ String(Math.round(options.webcamSize ?? 0)),
+ "--webcam-radius",
+ formatCliNumber(Math.max(0, options.webcamRadius ?? 0)),
+ "--webcam-shadow",
+ formatCliNumber(webcamShadowPixels),
+ "--webcam-time-offset-ms",
+ formatCliNumber(options.webcamTimeOffsetMs ?? 0),
+ );
+ if (options.webcamMirror !== false) {
+ args.push("--webcam-mirror");
+ }
+ }
+ if (options.cursorTelemetryPath) {
+ args.push(
+ "--cursor-telemetry",
+ options.cursorTelemetryPath,
+ "--cursor-size",
+ formatCliNumber(Math.max(1, options.cursorSize ?? 84)),
+ );
+ if (options.cursorAtlasPath && options.cursorAtlasMetadataPath) {
+ args.push(
+ "--cursor-atlas",
+ options.cursorAtlasPath,
+ "--cursor-atlas-metadata",
+ options.cursorAtlasMetadataPath,
+ );
+ }
+ }
+ if (options.zoomTelemetryPath) {
+ args.push("--zoom-telemetry", options.zoomTelemetryPath);
+ }
+ if (options.timelineMapPath) {
+ args.push("--timeline-map", options.timelineMapPath);
+ }
+
+ return args;
+}
+
+async function prepareWindowsGpuCursorTelemetry(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ const telemetry = options.cursorTelemetry;
+ if (!telemetry || telemetry.length === 0) {
+ return null;
+ }
+
+ const lines = telemetry
+ .filter((sample) => {
+ return (
+ Number.isFinite(sample.timeMs) &&
+ Number.isFinite(sample.cx) &&
+ Number.isFinite(sample.cy)
+ );
+ })
+ .map((sample) => {
+ const timeMs = Math.max(0, sample.timeMs);
+ const cx = Math.min(1, Math.max(0, sample.cx));
+ const cy = Math.min(1, Math.max(0, sample.cy));
+ const cursorTypeIndex = Math.max(
+ 0,
+ Math.min(8, Math.round(sample.cursorTypeIndex ?? 0)),
+ );
+ const bounceScale = Math.min(2, Math.max(0.1, sample.bounceScale ?? 1));
+ const visible = sample.visible !== false ? 1 : 0;
+ return [
+ formatCliNumber(timeMs),
+ formatCliNumber(cx),
+ formatCliNumber(cy),
+ String(cursorTypeIndex),
+ formatCliNumber(bounceScale),
+ String(visible),
+ ].join(",");
+ });
+
+ if (lines.length === 0) {
+ return null;
+ }
+
+ await fs.writeFile(outputPath, lines.join("\n"), "utf8");
+ return outputPath;
+}
+
+async function prepareWindowsGpuCursorAtlas(
+ options: NativeStaticLayoutExportOptions,
+ atlasPath: string,
+ metadataPath: string,
+) {
+ const dataUrl = options.cursorAtlasPngDataUrl;
+ const entries = options.cursorAtlasEntries;
+ if (!dataUrl || !entries?.length) {
+ return null;
+ }
+
+ const match = /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl);
+ if (!match) {
+ return null;
+ }
+
+ const metadataLines = entries
+ .filter((entry) => {
+ return (
+ Number.isInteger(entry.index) &&
+ Number.isFinite(entry.x) &&
+ Number.isFinite(entry.y) &&
+ Number.isFinite(entry.width) &&
+ Number.isFinite(entry.height) &&
+ Number.isFinite(entry.anchorX) &&
+ Number.isFinite(entry.anchorY) &&
+ Number.isFinite(entry.aspectRatio) &&
+ entry.width > 0 &&
+ entry.height > 0
+ );
+ })
+ .map((entry) =>
+ [
+ String(Math.max(0, Math.min(8, entry.index))),
+ formatCliNumber(Math.max(0, entry.x)),
+ formatCliNumber(Math.max(0, entry.y)),
+ formatCliNumber(Math.max(1, entry.width)),
+ formatCliNumber(Math.max(1, entry.height)),
+ formatCliNumber(Math.min(1, Math.max(0, entry.anchorX))),
+ formatCliNumber(Math.min(1, Math.max(0, entry.anchorY))),
+ formatCliNumber(Math.max(0.01, entry.aspectRatio)),
+ ].join(","),
+ );
+ if (metadataLines.length === 0) {
+ return null;
+ }
+
+ await fs.writeFile(atlasPath, Buffer.from(match[1], "base64"));
+ await fs.writeFile(metadataPath, metadataLines.join("\n"), "utf8");
+ return { atlasPath, metadataPath };
+}
+
+async function prepareNvidiaCudaCursorTelemetry(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ const telemetry = options.cursorTelemetry;
+ if (!telemetry || telemetry.length === 0) {
+ return null;
+ }
+
+ const samples = telemetry
+ .filter((sample) => {
+ return (
+ Number.isFinite(sample.timeMs) &&
+ Number.isFinite(sample.cx) &&
+ Number.isFinite(sample.cy)
+ );
+ })
+ .map((sample) => ({
+ timeMs: Math.max(0, sample.timeMs),
+ cx: Math.min(1, Math.max(0, sample.cx)),
+ cy: Math.min(1, Math.max(0, sample.cy)),
+ cursorTypeIndex: Math.max(0, Math.min(8, Math.round(sample.cursorTypeIndex ?? 0))),
+ bounceScale: Math.min(2, Math.max(0.1, sample.bounceScale ?? 1)),
+ visible: sample.visible !== false,
+ }));
+ if (samples.length === 0) {
+ return null;
+ }
+
+ await fs.writeFile(outputPath, JSON.stringify({ samples }), "utf8");
+ return outputPath;
+}
+
+async function prepareNvidiaCudaCursorAtlas(
+ options: NativeStaticLayoutExportOptions,
+ atlasPath: string,
+ metadataPath: string,
+) {
+ const dataUrl = options.cursorAtlasPngDataUrl;
+ const entries = options.cursorAtlasEntries;
+ if (!dataUrl || !entries?.length) {
+ return null;
+ }
+
+ const match = /^data:image\/png;base64,([A-Za-z0-9+/=]+)$/.exec(dataUrl);
+ if (!match) {
+ return null;
+ }
+
+ const metadataLines = entries
+ .filter((entry) => {
+ return (
+ Number.isInteger(entry.index) &&
+ Number.isFinite(entry.x) &&
+ Number.isFinite(entry.y) &&
+ Number.isFinite(entry.width) &&
+ Number.isFinite(entry.height) &&
+ Number.isFinite(entry.anchorX) &&
+ Number.isFinite(entry.anchorY) &&
+ Number.isFinite(entry.aspectRatio) &&
+ entry.width > 0 &&
+ entry.height > 0
+ );
+ })
+ .map((entry) =>
+ [
+ String(Math.max(0, Math.min(8, entry.index))),
+ formatCliNumber(Math.max(0, entry.x)),
+ formatCliNumber(Math.max(0, entry.y)),
+ formatCliNumber(Math.max(1, entry.width)),
+ formatCliNumber(Math.max(1, entry.height)),
+ formatCliNumber(Math.min(1, Math.max(0, entry.anchorX))),
+ formatCliNumber(Math.min(1, Math.max(0, entry.anchorY))),
+ formatCliNumber(Math.max(0.01, entry.aspectRatio)),
+ ].join("\t"),
+ );
+ if (metadataLines.length === 0) {
+ return null;
+ }
+
+ await fs.writeFile(atlasPath, Buffer.from(match[1], "base64"));
+ await fs.writeFile(metadataPath, `${metadataLines.join("\n")}\n`, "utf8");
+ return { atlasPath, metadataPath };
+}
+
+async function prepareWindowsGpuZoomTelemetry(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ const telemetry = options.zoomTelemetry;
+ if (!telemetry || telemetry.length === 0) {
+ return null;
+ }
+
+ const lines = telemetry
+ .filter((sample) => {
+ return (
+ Number.isFinite(sample.timeMs) &&
+ Number.isFinite(sample.scale) &&
+ Number.isFinite(sample.x) &&
+ Number.isFinite(sample.y)
+ );
+ })
+ .map((sample) => {
+ const timeMs = Math.max(0, sample.timeMs);
+ const scale = Math.max(0.01, sample.scale);
+ return [
+ formatCliNumber(timeMs),
+ formatCliNumber(scale),
+ formatCliNumber(sample.x),
+ formatCliNumber(sample.y),
+ ].join(",");
+ });
+
+ if (lines.length === 0) {
+ return null;
+ }
+
+ await fs.writeFile(outputPath, lines.join("\n"), "utf8");
+ return outputPath;
+}
+
+function shouldCreateWindowsGpuWebcamProxy(filePath: string) {
+ const extension = path.extname(filePath).toLowerCase();
+ return extension !== ".mp4" && extension !== ".m4v" && extension !== ".mov";
+}
+
+function buildWindowsGpuWebcamProxyArgs(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+) {
+ if (!options.webcamInputPath) {
+ throw new Error("Windows GPU webcam proxy requires an input path");
+ }
+
+ const frameRate = Math.max(1, Math.round(options.frameRate));
+ const proxyBitrate = Math.max(2_000_000, Math.min(6_000_000, Math.round(options.bitrate / 3)));
+ return [
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-i",
+ options.webcamInputPath,
+ "-map",
+ "0:v:0",
+ "-an",
+ "-t",
+ formatCliNumber(options.durationSec),
+ "-vf",
+ `scale=trunc(iw/2)*2:trunc(ih/2)*2,setsar=1,fps=${frameRate}`,
+ "-c:v",
+ "libx264",
+ "-preset",
+ "ultrafast",
+ "-tune",
+ "zerolatency",
+ "-b:v",
+ String(proxyBitrate),
+ "-maxrate",
+ String(Math.round(proxyBitrate * 1.2)),
+ "-bufsize",
+ String(proxyBitrate * 2),
+ "-pix_fmt",
+ "yuv420p",
+ "-movflags",
+ "+faststart",
+ outputPath,
+ ];
+}
+
+async function prepareWindowsGpuWebcamInput(
+ ffmpegPath: string,
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ session: NativeStaticLayoutExportSession,
+) {
+ if (!options.webcamInputPath || !shouldCreateWindowsGpuWebcamProxy(options.webcamInputPath)) {
+ return { inputPath: options.webcamInputPath ?? null, elapsedMs: 0 };
+ }
+
+ const result = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildWindowsGpuWebcamProxyArgs(options, outputPath),
+ Math.max(5 * 60 * 1000, options.durationSec * 1000),
+ session,
+ );
+ if (!result.success) {
+ throw new Error(getFfmpegFailureMessage(result));
+ }
+
+ return { inputPath: outputPath, elapsedMs: result.elapsedMs };
+}
+
+async function prepareNativeStaticLayoutSourceInput(
+ ffmpegPath: string,
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ session: NativeStaticLayoutExportSession,
+) {
+ const metadata = await probeNativeVideoMetadata(ffmpegPath, options.inputPath);
+ if (!shouldCreateNativeStaticLayoutSourceProxy(metadata, options.inputPath)) {
+ return {
+ inputPath: options.inputPath,
+ elapsedMs: 0,
+ sourceCodec: metadata.codec,
+ proxyCreated: false,
+ };
+ }
+
+ const sourceDurationSec = Math.max(
+ 0.001,
+ metadata.streamDuration ?? metadata.duration ?? options.durationSec,
+ );
+ const result = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeStaticLayoutSourceProxyArgs(options, outputPath, metadata),
+ Math.max(5 * 60 * 1000, sourceDurationSec * 2000),
+ session,
+ );
+ if (!result.success) {
+ throw new Error(getFfmpegFailureMessage(result));
+ }
+
+ const proxyMetadata = await probeNativeVideoMetadata(ffmpegPath, outputPath);
+ const validationIssues = validateNativeStaticLayoutSourceProxyMetadata(proxyMetadata, {
+ sourceDurationSec,
+ });
+ if (validationIssues.length > 0) {
+ throw new Error(`Native source proxy is invalid: ${validationIssues.join("; ")}`);
+ }
+
+ return {
+ inputPath: outputPath,
+ elapsedMs: result.elapsedMs,
+ sourceCodec: metadata.codec,
+ proxyCodec: proxyMetadata.codec,
+ proxyCreated: true,
+ };
+}
+
+export function buildExperimentalNvidiaCudaStaticLayoutArgs(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ workDir: string,
+) {
+ const background = convertHexColorToNv12(options.backgroundColor);
+ const backgroundBlurPx = Math.max(0, options.backgroundBlurPx ?? 0);
+ const shadowIntensityPct = Math.round(clampUnit(options.shadowIntensity ?? 0) * 100);
+ const shadowOffsetY =
+ shadowIntensityPct > 0 ? Math.max(1, Math.round(options.height * 0.012)) : 0;
+ const args = [
+ "--input",
+ options.inputPath,
+ "--output",
+ outputPath,
+ "--work-dir",
+ workDir,
+ "--width",
+ String(options.width),
+ "--height",
+ String(options.height),
+ "--fps",
+ String(Math.max(1, Math.round(options.frameRate))),
+ "--bitrate-mbps",
+ String(getNvidiaCudaBitrateMbps(options)),
+ "--encoding-mode",
+ options.encodingMode,
+ "--duration-sec",
+ formatCliNumber(options.durationSec),
+ "--stream-sync",
+ "--prewarm-ms",
+ process.env.RECORDLY_NVIDIA_CUDA_PREWARM_MS || "500",
+ "--content-x",
+ String(Math.round(options.offsetX)),
+ "--content-y",
+ String(Math.round(options.offsetY)),
+ "--content-width",
+ String(Math.round(options.contentWidth)),
+ "--content-height",
+ String(Math.round(options.contentHeight)),
+ "--radius",
+ String(Math.round(Math.max(0, options.borderRadius ?? 0))),
+ "--background-y",
+ String(background.y),
+ "--background-u",
+ String(background.u),
+ "--background-v",
+ String(background.v),
+ ];
+ if (!canMuxNvidiaCudaSourceAudioInline(options)) {
+ args.push("--video-only");
+ }
+
+ if (options.backgroundImagePath) {
+ args.push("--background-image", options.backgroundImagePath);
+ }
+ if (
+ Number.isFinite(options.sourceCropX) &&
+ Number.isFinite(options.sourceCropY) &&
+ Number.isFinite(options.sourceCropWidth) &&
+ Number.isFinite(options.sourceCropHeight) &&
+ (options.sourceCropWidth ?? 0) >= 2 &&
+ (options.sourceCropHeight ?? 0) >= 2
+ ) {
+ args.push(
+ "--source-crop-x",
+ String(Math.round(options.sourceCropX ?? 0)),
+ "--source-crop-y",
+ String(Math.round(options.sourceCropY ?? 0)),
+ "--source-crop-width",
+ String(Math.round(options.sourceCropWidth ?? 0)),
+ "--source-crop-height",
+ String(Math.round(options.sourceCropHeight ?? 0)),
+ );
+ }
+ if (backgroundBlurPx > 0) {
+ args.push("--background-blur", formatCliNumber(backgroundBlurPx));
+ }
+ if (shadowOffsetY > 0 && shadowIntensityPct > 0) {
+ args.push(
+ "--shadow-offset-y",
+ String(shadowOffsetY),
+ "--shadow-intensity-pct",
+ String(shadowIntensityPct),
+ );
+ }
+ if (options.webcamInputPath && (options.webcamSize ?? 0) > 0) {
+ args.push(
+ "--webcam-input",
+ options.webcamInputPath,
+ "--webcam-x",
+ String(Math.round(options.webcamLeft ?? 0)),
+ "--webcam-y",
+ String(Math.round(options.webcamTop ?? 0)),
+ "--webcam-size",
+ String(Math.round(options.webcamSize ?? 0)),
+ "--webcam-radius",
+ String(Math.round(Math.max(0, options.webcamRadius ?? 0))),
+ "--webcam-time-offset-ms",
+ formatCliNumber(options.webcamTimeOffsetMs ?? 0),
+ "--webcam-stream",
+ );
+ if (options.webcamMirror !== false) {
+ args.push("--webcam-mirror");
+ }
+ }
+ if (options.cursorTelemetryPath) {
+ args.push(
+ "--cursor-json",
+ options.cursorTelemetryPath,
+ "--cursor-height",
+ String(Math.round(Math.max(1, options.cursorSize ?? 84))),
+ "--cursor-style",
+ "external",
+ );
+ if (options.cursorAtlasPath && options.cursorAtlasMetadataPath) {
+ args.push(
+ "--cursor-atlas-png",
+ options.cursorAtlasPath,
+ "--cursor-atlas-metadata",
+ options.cursorAtlasMetadataPath,
+ );
+ }
+ }
+ if (options.zoomTelemetryPath) {
+ args.push("--zoom-telemetry", options.zoomTelemetryPath);
+ }
+ if (options.timelineMapPath) {
+ args.push("--timeline-map", options.timelineMapPath);
+ }
+ if (process.env.RECORDLY_NVIDIA_CUDA_SAMPLE_GPU === "1") {
+ args.push("--sample-gpu");
+ }
+
+ return args;
+}
+
+function canMuxNvidiaCudaSourceAudioInline(options: NativeStaticLayoutExportOptions) {
+ if (options.nvidiaCudaForceVideoOnly) {
+ return false;
+ }
+
+ const audioOptions = options.audioOptions;
+ if (audioOptions?.audioMode !== "copy-source" || !audioOptions.audioSourcePath) {
+ return false;
+ }
+
+ return path.resolve(audioOptions.audioSourcePath) === path.resolve(options.inputPath);
+}
+
+async function runExperimentalNvidiaCudaStaticLayoutExport(
+ ffmpegPath: string,
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ chunkDirectory: string,
+ session: NativeStaticLayoutExportSession,
+ onProgress?: (progress: NativeStaticLayoutExportProgress) => void,
+) {
+ const scriptPath = await resolveExperimentalNvidiaCudaExportScriptPath();
+ if (!scriptPath) {
+ throw new Error("Experimental NVIDIA CUDA export script is not available");
+ }
+
+ const nodeCommand = resolveExperimentalNvidiaCudaNodeCommand();
+ const workDir = path.join(chunkDirectory, "nvidia-cuda-work");
+ const args = [
+ scriptPath,
+ ...buildExperimentalNvidiaCudaStaticLayoutArgs(options, outputPath, workDir),
+ ];
+ const startedAt = getNowMs();
+ const startedAtIso = new Date().toISOString();
+ const timeoutMs = Math.max(20 * 60 * 1000, options.durationSec * 2000);
+ const stallTimeoutMs = getNvidiaCudaAutoStallTimeoutMs(
+ isValidatedNvidiaCudaFallbackCandidate(options),
+ );
+ const ffmpegDirectory = path.dirname(ffmpegPath);
+ const pathKey = process.platform === "win32" ? "Path" : "PATH";
+ const env = {
+ ...process.env,
+ ...nodeCommand.env,
+ RECORDLY_NVIDIA_CUDA_EXPORT_HIGH_PRIORITY:
+ process.env.RECORDLY_NVIDIA_CUDA_EXPORT_HIGH_PRIORITY ?? "1",
+ RECORDLY_FFMPEG_EXE: ffmpegPath,
+ RECORDLY_FFPROBE_EXE: process.env.RECORDLY_FFPROBE_EXE ?? getFfprobeBinaryPath(),
+ [pathKey]: `${ffmpegDirectory}${path.delimiter}${process.env[pathKey] ?? ""}`,
+ };
+ const powerGuard = startNativeStaticLayoutExportPowerGuard();
+
+ return await new Promise<{
+ elapsedMs: number;
+ stdout: string;
+ stderr: string;
+ summary: NvidiaCudaExportSummary;
+ }>((resolve, reject) => {
+ const child = spawn(nodeCommand.command, args, {
+ env,
+ stdio: ["ignore", "pipe", "pipe"],
+ windowsHide: true,
+ });
+ const childPriorityApplied = setNativeStaticLayoutExportProcessPriority(
+ child.pid,
+ "NVIDIA CUDA export wrapper",
+ );
+ console.info("[native-static-layout-export] NVIDIA CUDA runtime guard started", {
+ childPriorityApplied,
+ powerGuardStarted: powerGuard.started,
+ });
+ session.currentProcess = child;
+ if (session.terminating) {
+ child.kill("SIGKILL");
+ }
+
+ let stdout = "";
+ let stderr = "";
+ let stderrLineBuffer = "";
+ let lastProgressPercentage = 0;
+ let lastProgressForStallGuard: {
+ currentFrame: number;
+ percentage: number;
+ stage?: string;
+ } = { currentFrame: -1, percentage: -1 };
+ let stallTimedOut = false;
+ let settled = false;
+ const timeout = setTimeout(() => {
+ if (settled) return;
+ child.kill("SIGKILL");
+ }, timeoutMs);
+ let stallTimeout: ReturnType | null = null;
+ const clearStallTimeout = () => {
+ if (stallTimeout) {
+ clearTimeout(stallTimeout);
+ stallTimeout = null;
+ }
+ };
+ const armStallTimeout = () => {
+ if (!stallTimeoutMs) {
+ return;
+ }
+ clearStallTimeout();
+ stallTimeout = setTimeout(() => {
+ if (settled) return;
+ stallTimedOut = true;
+ child.kill("SIGKILL");
+ }, stallTimeoutMs);
+ };
+ armStallTimeout();
+
+ child.stdout.on("data", (chunk: Buffer) => {
+ stdout += chunk.toString();
+ });
+ child.stderr.on("data", (chunk: Buffer) => {
+ const text = chunk.toString();
+ stderr += text;
+ stderrLineBuffer += text;
+ const lines = stderrLineBuffer.split(/\r?\n/);
+ stderrLineBuffer = lines.pop() ?? "";
+ for (const line of lines) {
+ const progress = parseWindowsGpuExportProgressLine(line);
+ if (!progress) {
+ continue;
+ }
+ const elapsedMs = Math.max(0, getNowMs() - startedAt);
+ const averageFps =
+ typeof progress.averageFps === "number" &&
+ Number.isFinite(progress.averageFps) &&
+ progress.averageFps > 0
+ ? progress.averageFps
+ : elapsedMs > 0 && progress.currentFrame > 0
+ ? (progress.currentFrame * 1000) / elapsedMs
+ : undefined;
+ const mappedPercentage = mapNvidiaCudaWrapperProgressPercentage(progress);
+ lastProgressPercentage = Math.max(lastProgressPercentage, mappedPercentage);
+ const progressForStallGuard = {
+ currentFrame: progress.currentFrame,
+ percentage: mappedPercentage,
+ stage: progress.stage,
+ };
+ if (
+ hasNativeStaticLayoutProgressAdvanced(
+ progressForStallGuard,
+ lastProgressForStallGuard,
+ )
+ ) {
+ lastProgressForStallGuard = progressForStallGuard;
+ armStallTimeout();
+ }
+ onProgress?.({
+ ...progress,
+ percentage: lastProgressPercentage,
+ sessionId: options.sessionId,
+ backend: "nvidia-cuda-compositor",
+ elapsedMs,
+ averageFps,
+ });
+ }
+ });
+ child.once("error", (error) => {
+ if (settled) return;
+ settled = true;
+ if (session.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ clearStallTimeout();
+ powerGuard.release();
+ reject(error);
+ });
+ child.once("close", async (code, signal) => {
+ if (settled) return;
+ settled = true;
+ if (session.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ clearStallTimeout();
+ powerGuard.release();
+
+ if (session.terminating) {
+ reject(new Error("Native static layout export was cancelled"));
+ return;
+ }
+
+ const elapsedMs = getNowMs() - startedAt;
+ const summary = parseNvidiaCudaExportSummary(stdout);
+ if (summary) {
+ summary.appRuntimeGuard = {
+ powerGuardStarted: powerGuard.started,
+ wrapperProcessPriorityBoosted: childPriorityApplied,
+ nativeProcessPriorityBoosted: summary.nativeProcessPriorityBoosted,
+ };
+ }
+ await Promise.allSettled([
+ fs.writeFile(path.join(chunkDirectory, "nvidia-cuda-export.stdout.json"), stdout),
+ fs.writeFile(path.join(chunkDirectory, "nvidia-cuda-export.stderr.log"), stderr),
+ summary
+ ? fs.writeFile(
+ path.join(chunkDirectory, "nvidia-cuda-export.summary.json"),
+ `${JSON.stringify(summary, null, 2)}\n`,
+ )
+ : Promise.resolve(),
+ ]);
+ await persistNvidiaCudaExportDiagnostics({
+ args,
+ code,
+ elapsedMs,
+ outputPath,
+ sessionId: options.sessionId,
+ signal,
+ startedAtIso,
+ stderr,
+ stdout,
+ summary,
+ timedOut: stallTimedOut,
+ });
+ if (code !== 0 || !summary?.success) {
+ const suffix = signal ? ` (signal ${signal})` : "";
+ reject(
+ new Error(
+ (stallTimedOut && stallTimeoutMs
+ ? `Experimental NVIDIA CUDA exporter stalled for ${stallTimeoutMs}ms without progress`
+ : stderr.trim()) ||
+ stdout.trim() ||
+ `Experimental NVIDIA CUDA exporter exited with code ${code ?? "unknown"}${suffix}`,
+ ),
+ );
+ return;
+ }
+
+ resolve({
+ elapsedMs,
+ stdout,
+ stderr,
+ summary,
+ });
+ });
+ });
+}
+
+async function runExperimentalWindowsGpuStaticLayoutExport(
+ options: NativeStaticLayoutExportOptions,
+ outputPath: string,
+ session: NativeStaticLayoutExportSession,
+ onProgress?: (progress: NativeStaticLayoutExportProgress) => void,
+) {
+ const executablePath = await resolveExperimentalWindowsGpuExporterPath();
+ if (!executablePath) {
+ throw new Error("Experimental Windows GPU exporter is not built");
+ }
+
+ const args = buildExperimentalWindowsGpuStaticLayoutArgs(options, outputPath);
+ const startedAt = getNowMs();
+ const startedAtIso = new Date().toISOString();
+ const timeoutMs = Math.max(15 * 60 * 1000, options.durationSec * 1000);
+ const stallTimeoutMs = getNativeGpuCompositorStallTimeoutMs();
+
+ return await new Promise<{
+ elapsedMs: number;
+ stdout: string;
+ stderr: string;
+ summary: WindowsGpuExportSummary;
+ }>((resolve, reject) => {
+ const child = spawn(executablePath, args, {
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ session.currentProcess = child;
+ if (session.terminating) {
+ child.kill("SIGKILL");
+ }
+
+ let stdout = "";
+ let stderr = "";
+ let stderrLineBuffer = "";
+ let lastProgressForStallGuard: {
+ currentFrame: number;
+ percentage: number;
+ stage?: string;
+ } = { currentFrame: -1, percentage: -1 };
+ let stallTimedOut = false;
+ let settled = false;
+ const timeout = setTimeout(() => {
+ if (settled) return;
+ child.kill("SIGKILL");
+ }, timeoutMs);
+ let stallTimeout: ReturnType | null = null;
+ const clearStallTimeout = () => {
+ if (stallTimeout) {
+ clearTimeout(stallTimeout);
+ stallTimeout = null;
+ }
+ };
+ const armStallTimeout = () => {
+ if (!stallTimeoutMs) {
+ return;
+ }
+ clearStallTimeout();
+ stallTimeout = setTimeout(() => {
+ if (settled) return;
+ stallTimedOut = true;
+ child.kill("SIGKILL");
+ }, stallTimeoutMs);
+ };
+ armStallTimeout();
+
+ child.stdout.on("data", (chunk: Buffer) => {
+ stdout += chunk.toString();
+ });
+ child.stderr.on("data", (chunk: Buffer) => {
+ const text = chunk.toString();
+ stderr += text;
+ stderrLineBuffer += text;
+ const lines = stderrLineBuffer.split(/\r?\n/);
+ stderrLineBuffer = lines.pop() ?? "";
+ for (const line of lines) {
+ const progress = parseWindowsGpuExportProgressLine(line);
+ if (!progress) {
+ continue;
+ }
+ if (hasNativeStaticLayoutProgressAdvanced(progress, lastProgressForStallGuard)) {
+ lastProgressForStallGuard = {
+ currentFrame: progress.currentFrame,
+ percentage: progress.percentage,
+ stage: progress.stage,
+ };
+ armStallTimeout();
+ }
+ const elapsedMs = Math.max(0, getNowMs() - startedAt);
+ onProgress?.({
+ ...progress,
+ sessionId: options.sessionId,
+ backend: "windows-d3d11-compositor",
+ elapsedMs,
+ averageFps:
+ elapsedMs > 0 && progress.currentFrame > 0
+ ? (progress.currentFrame * 1000) / elapsedMs
+ : undefined,
+ });
+ }
+ });
+ child.once("error", (error) => {
+ if (settled) return;
+ settled = true;
+ if (session.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ clearStallTimeout();
+ reject(error);
+ });
+ child.once("close", async (code, signal) => {
+ if (settled) return;
+ settled = true;
+ if (session.currentProcess === child) {
+ session.currentProcess = null;
+ }
+ clearTimeout(timeout);
+ clearStallTimeout();
+
+ if (session.terminating) {
+ reject(new Error("Native static layout export was cancelled"));
+ return;
+ }
+
+ const elapsedMs = getNowMs() - startedAt;
+ const summary = parseWindowsGpuExportSummary(stdout);
+ await persistWindowsGpuExportDiagnostics({
+ args,
+ code,
+ elapsedMs,
+ outputPath,
+ signal,
+ startedAtIso,
+ stderr,
+ stdout,
+ summary,
+ timedOut: stallTimedOut,
+ });
+
+ if (code !== 0 || !summary?.success) {
+ const suffix = signal ? ` (signal ${signal})` : "";
+ reject(
+ new Error(
+ (stallTimedOut && stallTimeoutMs
+ ? `Experimental Windows GPU exporter stalled for ${stallTimeoutMs}ms without progress`
+ : stderr.trim()) ||
+ stdout.trim() ||
+ `Experimental Windows GPU exporter exited with code ${code ?? "unknown"}${suffix}`,
+ ),
+ );
+ return;
+ }
+
+ resolve({
+ elapsedMs,
+ stdout,
+ stderr,
+ summary,
+ });
+ });
+ });
+}
+
+export async function exportNativeStaticLayoutVideo(
+ ffmpegPath: string,
+ options: NativeStaticLayoutExportOptions,
+ onProgress?: (progress: NativeStaticLayoutExportProgress) => void,
+) {
+ if (options.width % 2 !== 0 || options.height % 2 !== 0) {
+ throw new Error("Native static layout export requires even output dimensions");
+ }
+ if (!Number.isFinite(options.durationSec) || options.durationSec <= 0) {
+ throw new Error("Native static layout export requires a positive duration");
+ }
+ options = await normalizeNativeStaticLayoutBackground(options);
+ if (
+ options.webcamInputPath &&
+ !(options.experimentalWindowsGpuCompositor && process.platform === "win32")
+ ) {
+ throw new Error("Native webcam overlay requires the Windows GPU compositor");
+ }
+ if (
+ options.zoomTelemetry?.length &&
+ !(options.experimentalWindowsGpuCompositor && process.platform === "win32")
+ ) {
+ throw new Error("Native zoom telemetry requires the Windows GPU compositor");
+ }
+
+ const chunkDurationSec = Math.max(1, Math.min(300, options.chunkDurationSec ?? 120));
+ const chunks = buildNativeStaticLayoutChunks(options.durationSec, chunkDurationSec);
+ if (chunks.length === 0) {
+ throw new Error("Native static layout export produced no chunks");
+ }
+
+ const sessionId =
+ options.sessionId ??
+ `recordly-static-layout-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+ const session: NativeStaticLayoutExportSession = {
+ terminating: false,
+ currentProcess: null,
+ };
+ const chunkDirectory = path.join(app.getPath("temp"), sessionId);
+ const concatListPath = path.join(chunkDirectory, "chunks.txt");
+ const videoOnlyPath = path.join(app.getPath("temp"), `${sessionId}.mp4`);
+ const ffprobePath = getFfprobeBinaryPath();
+ let outputPathToKeep: string | null = null;
+ let videoOutputValidated = false;
+ const metrics: NativeStaticLayoutExportMetrics = {
+ chunkCount: chunks.length,
+ chunkDurationSec,
+ chunkExecMs: 0,
+ fallbackChunkCount: 0,
+ chunks: [],
+ };
+ const validateRenderedVideoOutput = async () => {
+ await validateNativeVideoOutputFile(ffprobePath, videoOnlyPath, {
+ durationSec: options.durationSec,
+ targetFrames: Math.ceil(options.durationSec * options.frameRate),
+ });
+ videoOutputValidated = true;
+ };
+
+ try {
+ nativeStaticLayoutExportSessions.set(sessionId, session);
+ await fs.mkdir(chunkDirectory, { recursive: true });
+ const sourceInput = await prepareNativeStaticLayoutSourceInput(
+ ffmpegPath,
+ options,
+ path.join(chunkDirectory, "source-proxy.mp4"),
+ session,
+ );
+ if (sourceInput.elapsedMs > 0) {
+ metrics.staticAssetExecMs = (metrics.staticAssetExecMs ?? 0) + sourceInput.elapsedMs;
+ }
+ if (sourceInput.inputPath !== options.inputPath) {
+ console.info("[native-static-layout-export] Prepared H.264 source proxy", {
+ sourceCodec: sourceInput.sourceCodec,
+ proxyCodec: sourceInput.proxyCodec,
+ elapsedMs: sourceInput.elapsedMs,
+ });
+ options = {
+ ...options,
+ inputPath: sourceInput.inputPath,
+ };
+ }
+ const timelineMapPath = await prepareNativeStaticLayoutTimelineMap(
+ options,
+ path.join(chunkDirectory, "timeline-map.csv"),
+ );
+ if (timelineMapPath) {
+ if (!(options.experimentalWindowsGpuCompositor && process.platform === "win32")) {
+ throw new Error("Native timeline-map export requires the Windows GPU compositor");
+ }
+ options = {
+ ...options,
+ timelineMapPath,
+ };
+ }
+ const fullConfig: NativeStaticLayoutExportArgsConfig = {
+ inputPath: options.inputPath,
+ outputPath: videoOnlyPath,
+ width: options.width,
+ height: options.height,
+ frameRate: options.frameRate,
+ bitrate: options.bitrate,
+ encodingMode: options.encodingMode,
+ contentWidth: options.contentWidth,
+ contentHeight: options.contentHeight,
+ offsetX: options.offsetX,
+ offsetY: options.offsetY,
+ sourceCropX: options.sourceCropX,
+ sourceCropY: options.sourceCropY,
+ sourceCropWidth: options.sourceCropWidth,
+ sourceCropHeight: options.sourceCropHeight,
+ backgroundColor: options.backgroundColor,
+ backgroundImagePath: options.backgroundImagePath,
+ backgroundBlurPx: options.backgroundBlurPx,
+ borderRadius: options.borderRadius,
+ shadowIntensity: options.shadowIntensity,
+ durationSec: options.durationSec,
+ };
+ const usePrecompositedLayout = shouldUsePrecompositedStaticLayout(options);
+ let didRenderVideo = false;
+ let didMuxAudioInline = false;
+
+ if (options.experimentalWindowsGpuCompositor && process.platform === "win32") {
+ try {
+ if (session.terminating) {
+ throw new Error("Native static layout export was cancelled");
+ }
+ let experimentalGpuOptions = options;
+ if (options.webcamInputPath) {
+ const webcamProxyPath = path.join(chunkDirectory, "webcam-proxy.mp4");
+ const webcamInput = await prepareWindowsGpuWebcamInput(
+ ffmpegPath,
+ options,
+ webcamProxyPath,
+ session,
+ );
+ if (webcamInput.elapsedMs > 0) {
+ metrics.staticAssetExecMs =
+ (metrics.staticAssetExecMs ?? 0) + webcamInput.elapsedMs;
+ }
+ if (
+ webcamInput.inputPath &&
+ webcamInput.inputPath !== options.webcamInputPath
+ ) {
+ experimentalGpuOptions = {
+ ...options,
+ webcamInputPath: webcamInput.inputPath,
+ };
+ }
+ }
+ if (options.cursorTelemetry?.length) {
+ const cursorTelemetryPath = await prepareWindowsGpuCursorTelemetry(
+ options,
+ path.join(chunkDirectory, "cursor-telemetry.csv"),
+ );
+ if (cursorTelemetryPath) {
+ experimentalGpuOptions = {
+ ...experimentalGpuOptions,
+ cursorTelemetryPath,
+ };
+ }
+ const cursorAtlas = await prepareWindowsGpuCursorAtlas(
+ options,
+ path.join(chunkDirectory, "cursor-atlas.png"),
+ path.join(chunkDirectory, "cursor-atlas.csv"),
+ );
+ if (cursorAtlas) {
+ experimentalGpuOptions = {
+ ...experimentalGpuOptions,
+ cursorAtlasPath: cursorAtlas.atlasPath,
+ cursorAtlasMetadataPath: cursorAtlas.metadataPath,
+ };
+ }
+ }
+ if (options.zoomTelemetry?.length) {
+ const zoomTelemetryPath = await prepareWindowsGpuZoomTelemetry(
+ options,
+ path.join(chunkDirectory, "zoom-telemetry.csv"),
+ );
+ if (zoomTelemetryPath) {
+ experimentalGpuOptions = {
+ ...experimentalGpuOptions,
+ zoomTelemetryPath,
+ };
+ }
+ }
+ let experimentalNvidiaCudaOptions = experimentalGpuOptions;
+ const nvidiaCudaSkipReason =
+ await getExperimentalNvidiaCudaExportSkipReason(options);
+ let shouldTryNvidiaCuda = nvidiaCudaSkipReason === null;
+ const validatedCudaFallbackCandidate =
+ isValidatedNvidiaCudaFallbackCandidate(options);
+ if (
+ shouldTryNvidiaCuda &&
+ (validatedCudaFallbackCandidate || isNvidiaCudaForceVideoOnlyEnabled()) &&
+ (experimentalNvidiaCudaOptions.audioOptions?.audioMode ?? "none") !== "none"
+ ) {
+ experimentalNvidiaCudaOptions = {
+ ...experimentalNvidiaCudaOptions,
+ nvidiaCudaForceVideoOnly: true,
+ };
+ console.info(
+ "[native-static-layout-export] NVIDIA CUDA candidate will use shared audio mux validation",
+ {
+ audioMode:
+ experimentalNvidiaCudaOptions.audioOptions?.audioMode ?? "none",
+ forcedByEnv: isNvidiaCudaForceVideoOnlyEnabled(),
+ userOptIn: options.experimentalNvidiaCudaExport === true,
+ },
+ );
+ }
+ const shouldLogNvidiaCudaSkip =
+ isExplicitNvidiaCudaExportEnabled() ||
+ (options.experimentalNvidiaCudaExport === true &&
+ nvidiaCudaSkipReason !== "env-disabled");
+ if (
+ !shouldTryNvidiaCuda &&
+ shouldLogNvidiaCudaSkip &&
+ nvidiaCudaSkipReason !== "env-disabled"
+ ) {
+ console.warn(
+ "[native-static-layout-export] Skipping NVIDIA CUDA compositor; falling back to Windows GPU compositor",
+ {
+ reason: nvidiaCudaSkipReason,
+ audioMode: options.audioOptions?.audioMode ?? "none",
+ overrideEnv: NVIDIA_CUDA_ALLOW_AUDIO_EXPORT_ENV,
+ userOptIn: options.experimentalNvidiaCudaExport === true,
+ },
+ );
+ }
+ if (shouldTryNvidiaCuda && options.cursorTelemetry?.length) {
+ const cursorTelemetryPath = await prepareNvidiaCudaCursorTelemetry(
+ options,
+ path.join(chunkDirectory, "cursor-telemetry.json"),
+ );
+ const cursorAtlas = await prepareNvidiaCudaCursorAtlas(
+ options,
+ path.join(chunkDirectory, "cursor-atlas-nvidia.png"),
+ path.join(chunkDirectory, "cursor-atlas-nvidia.tsv"),
+ );
+ shouldTryNvidiaCuda = Boolean(cursorTelemetryPath && cursorAtlas);
+ if (cursorTelemetryPath && cursorAtlas) {
+ experimentalNvidiaCudaOptions = {
+ ...experimentalNvidiaCudaOptions,
+ cursorTelemetryPath,
+ cursorAtlasPath: cursorAtlas.atlasPath,
+ cursorAtlasMetadataPath: cursorAtlas.metadataPath,
+ };
+ }
+ }
+
+ if (shouldTryNvidiaCuda) {
+ try {
+ const shouldMuxAudioInline = canMuxNvidiaCudaSourceAudioInline(
+ experimentalNvidiaCudaOptions,
+ );
+ const cudaResult = await runExperimentalNvidiaCudaStaticLayoutExport(
+ ffmpegPath,
+ experimentalNvidiaCudaOptions,
+ videoOnlyPath,
+ chunkDirectory,
+ session,
+ onProgress,
+ );
+ const cudaValidationIssues = validateNvidiaCudaExportSummary(
+ cudaResult.summary,
+ {
+ durationSec: options.durationSec,
+ targetFrames: Math.ceil(options.durationSec * options.frameRate),
+ requiresTimelineSync: shouldMuxAudioInline,
+ },
+ );
+ if (cudaValidationIssues.length > 0) {
+ throw new Error(
+ `Experimental NVIDIA CUDA compositor produced an invalid output: ${cudaValidationIssues.join("; ")}`,
+ );
+ }
+ const outputStat = await fs.stat(videoOnlyPath);
+ if (outputStat.size <= 0) {
+ throw new Error(
+ "Experimental NVIDIA CUDA compositor produced an empty output file",
+ );
+ }
+ await validateRenderedVideoOutput();
+ console.info(
+ "[native-static-layout-export] NVIDIA CUDA compositor completed",
+ {
+ elapsedMs: cudaResult.elapsedMs,
+ fps: cudaResult.summary.fps,
+ targetFrames: cudaResult.summary.targetFrames,
+ durationSec: cudaResult.summary.durationSec,
+ nativeEncodeMs: cudaResult.summary.timingsMs?.nativeEncode,
+ muxMs: cudaResult.summary.timingsMs?.mux,
+ endToEndMs: cudaResult.summary.timingsMs?.endToEnd,
+ nativeFps:
+ cudaResult.summary.nativeSummary?.measuredFps ??
+ cudaResult.summary.nativeSummary?.fps,
+ mappedDisplayFrames:
+ cudaResult.summary.nativeSummary?.mappedDisplayFrames,
+ selectedDisplayFrames:
+ cudaResult.summary.nativeSummary?.selectedDisplayFrames,
+ skippedDisplayFrames:
+ cudaResult.summary.nativeSummary?.skippedDisplayFrames,
+ roiCompositeFrames:
+ cudaResult.summary.nativeSummary?.roiCompositeFrames,
+ monolithicCompositeFrames:
+ cudaResult.summary.nativeSummary?.monolithicCompositeFrames,
+ copyCompositeFrames:
+ cudaResult.summary.nativeSummary?.copyCompositeFrames,
+ webcamOverlay: cudaResult.summary.nativeSummary?.webcamOverlay,
+ cursorAtlas: cudaResult.summary.nativeSummary?.cursorAtlas,
+ zoomOverlay: cudaResult.summary.nativeSummary?.zoomOverlay,
+ zoomSamples: cudaResult.summary.nativeSummary?.zoomSamples,
+ },
+ );
+ metrics.chunkCount = 1;
+ metrics.chunkDurationSec = options.durationSec;
+ metrics.chunkExecMs += cudaResult.elapsedMs;
+ metrics.chunks.push({
+ index: 0,
+ startSec: 0,
+ durationSec: options.durationSec,
+ backend: "nvidia-cuda-compositor",
+ elapsedMs: cudaResult.elapsedMs,
+ outputBytes: outputStat.size,
+ nvidiaCudaSummary: cudaResult.summary,
+ });
+ didRenderVideo = true;
+ didMuxAudioInline = shouldMuxAudioInline;
+ } catch (error) {
+ if (session.terminating) {
+ throw error;
+ }
+ metrics.fallbackChunkCount++;
+ console.warn(
+ "[native-static-layout-export] Experimental NVIDIA CUDA compositor failed or produced invalid output; falling back to Windows GPU compositor:",
+ error,
+ );
+ await removeTemporaryExportFile(videoOnlyPath);
+ }
+ }
+
+ if (!didRenderVideo) {
+ const gpuResult = await runExperimentalWindowsGpuStaticLayoutExport(
+ experimentalGpuOptions,
+ videoOnlyPath,
+ session,
+ onProgress,
+ );
+ const gpuValidationIssues = validateWindowsGpuExportSummary(gpuResult.summary, {
+ durationSec: options.durationSec,
+ targetFrames: Math.ceil(options.durationSec * options.frameRate),
+ });
+ if (gpuValidationIssues.length > 0) {
+ throw new Error(
+ `Experimental Windows GPU compositor produced an invalid output: ${gpuValidationIssues.join("; ")}`,
+ );
+ }
+ await validateRenderedVideoOutput();
+ console.info("[native-static-layout-export] Windows GPU compositor completed", {
+ elapsedMs: gpuResult.elapsedMs,
+ width: gpuResult.summary.width,
+ height: gpuResult.summary.height,
+ fps: gpuResult.summary.fps,
+ frames: gpuResult.summary.frames,
+ realtimeMultiplier: gpuResult.summary.realtimeMultiplier,
+ surfacePoolSize: gpuResult.summary.surfacePoolSize,
+ gpuDecodeSurface: gpuResult.summary.gpuDecodeSurface,
+ adapterIndex: gpuResult.summary.adapterIndex,
+ encoderBackend: gpuResult.summary.encoderBackend,
+ encoderTuningApplied: gpuResult.summary.encoderTuningApplied,
+ readMs: gpuResult.summary.readMs,
+ videoProcessMs: gpuResult.summary.videoProcessMs,
+ writeSampleMs: gpuResult.summary.writeSampleMs,
+ finalizeMs: gpuResult.summary.finalizeMs,
+ webcamOverlay: gpuResult.summary.webcamOverlay,
+ cursorOverlay: gpuResult.summary.cursorOverlay,
+ cursorAtlas: gpuResult.summary.cursorAtlas,
+ zoomOverlay: gpuResult.summary.zoomOverlay,
+ });
+ const outputStat = await fs.stat(videoOnlyPath);
+ metrics.chunkCount = 1;
+ metrics.chunkDurationSec = options.durationSec;
+ metrics.chunkExecMs += gpuResult.elapsedMs;
+ metrics.chunks.push({
+ index: 0,
+ startSec: 0,
+ durationSec: options.durationSec,
+ backend: "windows-d3d11-compositor",
+ elapsedMs: gpuResult.elapsedMs,
+ outputBytes: outputStat.size,
+ windowsGpuSummary: gpuResult.summary,
+ });
+ didRenderVideo = true;
+ }
+ } catch (error) {
+ if (session.terminating) {
+ throw error;
+ }
+ if (hasNativeStaticLayoutTimeline(options)) {
+ throw error;
+ }
+ metrics.fallbackChunkCount++;
+ console.warn(
+ "[native-static-layout-export] Experimental Windows GPU compositor unavailable; falling back to FFmpeg static layout:",
+ error,
+ );
+ await removeTemporaryExportFile(videoOnlyPath);
+ if (options.webcamInputPath || options.zoomTelemetry?.length) {
+ throw error;
+ }
+ }
+ }
+
+ if (!didRenderVideo && hasNativeStaticLayoutTimeline(options)) {
+ throw new Error("Native timeline-map export requires a GPU compositor backend");
+ }
+ if (!didRenderVideo && hasNativeStaticLayoutSourceCrop(options)) {
+ throw new Error("Native crop export requires a GPU compositor backend");
+ }
+
+ if (!didRenderVideo && usePrecompositedLayout) {
+ const maskPath = path.join(chunkDirectory, "layout-mask.pgm");
+ const staticBackgroundPath = path.join(chunkDirectory, "layout-background.png");
+ await fs.writeFile(
+ maskPath,
+ createNativeSquircleMaskPgmBuffer(
+ options.contentWidth,
+ options.contentHeight,
+ options.borderRadius ?? 0,
+ ),
+ );
+
+ const backgroundResult = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeStaticBackgroundRenderArgs({
+ ...fullConfig,
+ inputPath: options.inputPath,
+ outputPath: staticBackgroundPath,
+ maskPath,
+ }),
+ 2 * 60 * 1000,
+ session,
+ );
+ metrics.staticAssetExecMs = backgroundResult.elapsedMs;
+ if (!backgroundResult.success) {
+ throw new Error(getFfmpegFailureMessage(backgroundResult));
+ }
+
+ const fullResult = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativePrecompositedStaticLayoutArgs({
+ ...fullConfig,
+ staticBackgroundPath,
+ maskPath,
+ }),
+ 15 * 60 * 1000,
+ session,
+ );
+ metrics.chunkExecMs += fullResult.elapsedMs;
+ if (!fullResult.success) {
+ throw new Error(getFfmpegFailureMessage(fullResult));
+ }
+
+ const outputStat = await fs.stat(videoOnlyPath);
+ metrics.chunkCount = 1;
+ metrics.chunkDurationSec = options.durationSec;
+ metrics.chunks.push({
+ index: 0,
+ startSec: 0,
+ durationSec: options.durationSec,
+ backend: "cuda-static-composite",
+ elapsedMs: fullResult.elapsedMs,
+ outputBytes: outputStat.size,
+ });
+ } else if (!didRenderVideo) {
+ const primaryResult = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeCudaOverlayStaticLayoutArgs(fullConfig),
+ 15 * 60 * 1000,
+ session,
+ );
+ let fullResult = primaryResult;
+ let fullBackend: NativeStaticLayoutBackend = "cuda-overlay";
+ let fallbackReason: string | undefined;
+ if (!primaryResult.success) {
+ fullBackend = "cuda-scale-cpu-pad";
+ fallbackReason = isNativeCudaOutOfMemory(primaryResult.stderr)
+ ? "cuda-oom"
+ : "cuda-overlay-failed";
+ metrics.fallbackChunkCount++;
+ fullResult = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeCudaScaleCpuPadStaticLayoutArgs(fullConfig),
+ 15 * 60 * 1000,
+ session,
+ );
+ }
+ metrics.chunkExecMs += fullResult.elapsedMs;
+ if (fullResult !== primaryResult) {
+ metrics.chunkExecMs += primaryResult.elapsedMs;
+ }
+
+ if (fullResult.success) {
+ const outputStat = await fs.stat(videoOnlyPath);
+ metrics.chunkCount = 1;
+ metrics.chunkDurationSec = options.durationSec;
+ metrics.chunks.push({
+ index: 0,
+ startSec: 0,
+ durationSec: options.durationSec,
+ backend: fullBackend,
+ elapsedMs: fullResult.elapsedMs,
+ outputBytes: outputStat.size,
+ fallbackReason,
+ });
+ } else if (isNativeCudaOutOfMemory(fullResult.stderr)) {
+ const concatLines: string[] = [];
+
+ for (const chunk of chunks) {
+ if (session.terminating) {
+ throw new Error("Native static layout export was cancelled");
+ }
+
+ const outputPath = getStaticLayoutChunkOutputPath(chunkDirectory, chunk.index);
+ const baseConfig: NativeStaticLayoutExportArgsConfig = {
+ inputPath: options.inputPath,
+ outputPath,
+ width: options.width,
+ height: options.height,
+ frameRate: options.frameRate,
+ bitrate: options.bitrate,
+ encodingMode: options.encodingMode,
+ contentWidth: options.contentWidth,
+ contentHeight: options.contentHeight,
+ offsetX: options.offsetX,
+ offsetY: options.offsetY,
+ backgroundColor: options.backgroundColor,
+ startSec: chunk.startSec,
+ durationSec: chunk.durationSec,
+ };
+ const primary = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeCudaOverlayStaticLayoutArgs(baseConfig),
+ 15 * 60 * 1000,
+ session,
+ );
+ let backend: NativeStaticLayoutBackend = "cuda-overlay";
+ let result = primary;
+ let fallbackReason: string | undefined;
+
+ if (!primary.success && isNativeCudaOutOfMemory(primary.stderr)) {
+ backend = "cuda-scale-cpu-pad";
+ fallbackReason = "cuda-oom";
+ metrics.fallbackChunkCount++;
+ result = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeCudaScaleCpuPadStaticLayoutArgs(baseConfig),
+ 15 * 60 * 1000,
+ session,
+ );
+ }
+
+ metrics.chunkExecMs += result.elapsedMs;
+ if (!result.success) {
+ throw new Error(getFfmpegFailureMessage(result));
+ }
+
+ const outputStat = await fs.stat(outputPath);
+ metrics.chunks.push({
+ index: chunk.index,
+ startSec: chunk.startSec,
+ durationSec: chunk.durationSec,
+ backend,
+ elapsedMs: result.elapsedMs,
+ outputBytes: outputStat.size,
+ fallbackReason,
+ });
+ concatLines.push(toConcatFileLine(outputPath));
+ }
+
+ metrics.chunkCount = chunks.length;
+ await fs.writeFile(concatListPath, `${concatLines.join("\n")}\n`, "utf8");
+ if (session.terminating) {
+ throw new Error("Native static layout export was cancelled");
+ }
+ const concatStartedAt = getNowMs();
+ const concatResult = await runFfmpegWithMetrics(
+ ffmpegPath,
+ buildNativeConcatArgs({ listPath: concatListPath, outputPath: videoOnlyPath }),
+ 15 * 60 * 1000,
+ session,
+ );
+ metrics.concatExecMs = getNowMs() - concatStartedAt;
+ if (!concatResult.success) {
+ throw new Error(getFfmpegFailureMessage(concatResult));
+ }
+ } else {
+ throw new Error(getFfmpegFailureMessage(fullResult));
+ }
+ }
+
+ const videoOnlyStat = await fs.stat(videoOnlyPath);
+ metrics.videoOnlyBytes = videoOnlyStat.size;
+ if (!videoOutputValidated) {
+ await validateRenderedVideoOutput();
+ }
+ if (didMuxAudioInline) {
+ outputPathToKeep = videoOnlyPath;
+ return {
+ outputPath: videoOnlyPath,
+ metrics,
+ };
+ }
+ const audioMuxProgressStart = 97.25;
+ const audioMuxProgressEnd = 99;
+ const progressTotalFrames = Math.max(1, Math.ceil(options.durationSec * options.frameRate));
+ const finalized = await muxNativeVideoExportAudio(
+ videoOnlyPath,
+ options.audioOptions ?? {},
+ (progress) => {
+ const ratio = Math.max(0, Math.min(1, progress.ratio));
+ const percentage =
+ audioMuxProgressStart + (audioMuxProgressEnd - audioMuxProgressStart) * ratio;
+ const progressPayload: NativeStaticLayoutExportProgress = {
+ sessionId,
+ stage: "finalizing",
+ currentFrame: progressTotalFrames,
+ totalFrames: progressTotalFrames,
+ percentage,
+ };
+ const backend = metrics.chunks[0]?.backend;
+ if (backend) {
+ progressPayload.backend = backend;
+ }
+ onProgress?.(progressPayload);
+ },
+ session,
+ );
+ Object.assign(metrics, finalized.metrics);
+ outputPathToKeep = finalized.outputPath;
+ return {
+ outputPath: finalized.outputPath,
+ metrics,
+ };
+ } catch (error) {
+ await removeTemporaryExportFile(videoOnlyPath);
+ await removeTemporaryExportFile(videoOnlyPath.replace(/\.mp4$/, "-final.mp4"));
+ throw error;
+ } finally {
+ nativeStaticLayoutExportSessions.delete(sessionId);
+ await fs.rm(chunkDirectory, { force: true, recursive: true }).catch(() => undefined);
+ if (outputPathToKeep !== videoOnlyPath) {
+ await removeTemporaryExportFile(videoOnlyPath);
+ }
+ }
+}
+
+export async function enqueueNativeVideoExportFrameWrite(
+ session: NativeVideoExportSession,
+ frameData: Uint8Array | ArrayBuffer,
+) {
+ const writePromise = session.writeSequence.then(async () => {
+ if (session.terminating) {
+ throw new Error("Native video export session was cancelled");
+ }
+
+ await writeNativeVideoExportFrame(session, frameData);
+ });
+
+ session.writeSequence = writePromise.catch(() => undefined);
+ await writePromise;
+}
+
+export async function enqueueNativeVideoExportFrameWrites(
+ session: NativeVideoExportSession,
+ frameDataList: Array,
+) {
+ const writePromise = session.writeSequence.then(async () => {
+ if (session.terminating) {
+ throw new Error("Native video export session was cancelled");
+ }
+
+ for (const frameData of frameDataList) {
+ await writeNativeVideoExportFrame(session, frameData);
+ }
+ });
+
+ session.writeSequence = writePromise.catch(() => undefined);
+ await writePromise;
+}
+
+export async function getAvailableNativeVideoEncoders(ffmpegPath: string) {
+ const { stdout } = await execFileAsync(ffmpegPath, ["-hide_banner", "-encoders"], {
+ timeout: 15000,
+ maxBuffer: 20 * 1024 * 1024,
+ });
+
+ return parseAvailableFfmpegEncoders(stdout);
+}
+
+export async function probeNativeVideoEncoder(
+ ffmpegPath: string,
+ encoderName: string,
+ encodingMode: NativeExportEncodingMode,
+) {
+ const outputPath = path.join(
+ app.getPath("temp"),
+ `recordly-export-probe-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mp4`,
+ );
+ const args = buildNativeVideoExportArgs(
+ encoderName,
+ {
+ width: 64,
+ height: 64,
+ frameRate: 1,
+ bitrate: 1_500_000,
+ encodingMode,
+ },
+ outputPath,
+ );
+
+ return new Promise((resolve) => {
+ const process = spawn(ffmpegPath, args, {
+ stdio: ["pipe", "ignore", "pipe"],
+ });
+ let stderrOutput = "";
+ const timeout = setTimeout(() => {
+ try {
+ process.kill("SIGKILL");
+ } catch {
+ // ignore
+ }
+ resolve(false);
+ }, 15000);
+
+ process.stderr.on("data", (chunk: Buffer) => {
+ stderrOutput += chunk.toString();
+ });
+
+ process.on("close", (code) => {
+ clearTimeout(timeout);
+ void removeTemporaryExportFile(outputPath);
+ if (code !== 0 && stderrOutput.trim().length > 0) {
+ console.warn(
+ `[native-export] Encoder probe failed for ${encoderName}:`,
+ stderrOutput.trim(),
+ );
+ }
+ resolve(code === 0);
+ });
+
+ process.stdin.end(Buffer.alloc(getNativeVideoInputByteSize(64, 64), 0));
+ });
+}
+
+export async function resolveNativeVideoEncoder(
+ ffmpegPath: string,
+ encodingMode: NativeExportEncodingMode,
+) {
+ if (
+ cachedNativeVideoEncoder?.ffmpegPath === ffmpegPath &&
+ cachedNativeVideoEncoder?.encodingMode === encodingMode
+ ) {
+ return cachedNativeVideoEncoder.encoderName;
+ }
+
+ const availableEncoders = await getAvailableNativeVideoEncoders(ffmpegPath);
+ const candidates = [
+ ...new Set([...getPreferredNativeVideoEncoders(process.platform), "libx264"]),
+ ];
+
+ for (const encoderName of candidates) {
+ if (!availableEncoders.has(encoderName)) {
+ continue;
+ }
+
+ if (await probeNativeVideoEncoder(ffmpegPath, encoderName, encodingMode)) {
+ setCachedNativeVideoEncoder({ ffmpegPath, encodingMode, encoderName });
+ return encoderName;
+ }
+ }
+
+ throw new Error("No usable FFmpeg encoder was available for native export");
+}
+
+export function canCopyAudioCodecIntoMp4(codec?: string | null) {
+ const normalized = (codec ?? "").trim().toLowerCase();
+ if (!normalized) {
+ return false;
+ }
+
+ return (
+ normalized.includes("aac") ||
+ normalized.includes("mp4a") ||
+ normalized.includes("mpeg-4 audio") ||
+ normalized.includes("mp3") ||
+ normalized.includes("alac")
+ );
+}
+
+export function buildNativeVideoAudioMuxArgs(
+ videoPath: string,
+ audioInputPath: string,
+ outputPath: string,
+ options: NativeVideoExportFinishOptions,
+ argsOptions: NativeVideoAudioMuxArgsOptions = {},
+) {
+ const audioMode = options.audioMode ?? "none";
+ const useEditedTrackFiltergraph =
+ audioMode === "edited-track" && options.editedTrackStrategy === "filtergraph-fast-path";
+ const args = ["-y", "-hide_banner", "-loglevel", "error"];
+ if (argsOptions.progressPipe) {
+ args.push(
+ "-stats_period",
+ "0.5",
+ "-progress",
+ `pipe:${argsOptions.progressPipe}`,
+ "-nostats",
+ );
+ }
+ args.push("-i", videoPath, "-i", audioInputPath);
+
+ if (audioMode === "trim-source") {
+ const filter = buildTrimmedSourceAudioFilter(options.trimSegments ?? []);
+ if (filter) {
+ args.push("-filter_complex", filter, "-map", "0:v:0", "-map", "[aout]");
+ } else {
+ args.push("-map", "0:v:0", "-map", "1:a:0");
+ }
+ } else if (useEditedTrackFiltergraph) {
+ const filter = buildEditedTrackSourceAudioFilter(
+ options.editedTrackSegments ?? [],
+ options.audioSourceSampleRate ?? 0,
+ );
+ if (!filter) {
+ throw new Error("Edited-track filtergraph inputs are incomplete for native export");
+ }
+ if (
+ typeof options.outputDurationSec === "number" &&
+ Number.isFinite(options.outputDurationSec) &&
+ options.outputDurationSec > 0
+ ) {
+ const duration = formatFfmpegSeconds(options.outputDurationSec * 1000);
+ args.push(
+ "-filter_complex",
+ `${filter};[aout]apad,atrim=duration=${duration},asetpts=PTS-STARTPTS[aout_sync]`,
+ "-map",
+ "0:v:0",
+ "-map",
+ "[aout_sync]",
+ );
+ } else {
+ args.push("-filter_complex", filter, "-map", "0:v:0", "-map", "[aout]");
+ }
+ } else {
+ args.push("-map", "0:v:0", "-map", "1:a:0");
+ }
+
+ args.push("-c:v", "copy");
+ if (audioMode === "copy-source" && canCopyAudioCodecIntoMp4(options.audioSourceCodec)) {
+ args.push("-c:a", "copy");
+ } else {
+ args.push("-c:a", "aac", "-b:a", "192k");
+ }
+ if (
+ typeof options.outputDurationSec === "number" &&
+ Number.isFinite(options.outputDurationSec) &&
+ options.outputDurationSec > 0
+ ) {
+ args.push("-t", formatFfmpegSeconds(options.outputDurationSec * 1000));
+ } else if (audioMode !== "copy-source") {
+ args.push("-shortest");
+ }
+ args.push("-movflags", "+faststart", outputPath);
+
+ return args;
+}
+
+export async function muxNativeVideoExportAudio(
+ videoPath: string,
+ options: NativeVideoExportFinishOptions,
+ onProgress?: (progress: NativeVideoAudioMuxProgress) => void,
+ session?: NativeStaticLayoutExportSession,
+) {
+ const audioMode = options.audioMode ?? "none";
+ if (audioMode === "none") {
+ return {
+ outputPath: videoPath,
+ metrics: {} as NativeVideoAudioMuxMetrics,
+ };
+ }
+
+ const ffmpegPath = getFfmpegBinaryPath();
+ const metrics: NativeVideoAudioMuxMetrics = {};
+ const tempArtifacts: string[] = [];
+ let audioInputPath = options.audioSourcePath ?? null;
+ const useEditedTrackFiltergraph =
+ audioMode === "edited-track" && options.editedTrackStrategy === "filtergraph-fast-path";
+
+ if (audioMode === "edited-track" && !useEditedTrackFiltergraph) {
+ if (!options.editedAudioData) {
+ throw new Error("Edited audio data is missing for native export");
+ }
+
+ const extension = getEditedAudioExtension(options.editedAudioMimeType);
+ audioInputPath = path.join(
+ app.getPath("temp"),
+ `recordly-export-audio-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${extension}`,
+ );
+ const tempAudioWriteStartedAt = getNowMs();
+ await fs.writeFile(audioInputPath, Buffer.from(options.editedAudioData));
+ metrics.tempEditedAudioWriteMs = getNowMs() - tempAudioWriteStartedAt;
+ metrics.tempEditedAudioBytes = options.editedAudioData.byteLength;
+ tempArtifacts.push(audioInputPath);
+ }
+
+ if (!audioInputPath) {
+ return {
+ outputPath: videoPath,
+ metrics,
+ };
+ }
+
+ const outputPath = path.join(
+ path.dirname(videoPath),
+ `${path.basename(videoPath, path.extname(videoPath))}-final.mp4`,
+ );
+
+ const args = buildNativeVideoAudioMuxArgs(
+ videoPath,
+ audioInputPath,
+ outputPath,
+ options,
+ onProgress ? { progressPipe: 2 } : {},
+ );
+
+ try {
+ const ffmpegExecStartedAt = getNowMs();
+ await runFfmpegAudioMux(ffmpegPath, args, 15 * 60 * 1000, options, onProgress, session);
+ metrics.ffmpegExecMs = getNowMs() - ffmpegExecStartedAt;
+ console.info("[native-video-export] Audio mux completed", {
+ ffmpegExecMs: metrics.ffmpegExecMs,
+ audioMode: options.audioMode,
+ tempVideoBytes: metrics.tempVideoBytes,
+ muxedVideoBytes: metrics.muxedVideoBytes,
+ });
+ await removeTemporaryExportFile(videoPath);
+ return {
+ outputPath,
+ metrics,
+ };
+ } finally {
+ await Promise.allSettled(
+ tempArtifacts.map((artifactPath) => removeTemporaryExportFile(artifactPath)),
+ );
+ }
+}
+
+export async function muxExportedVideoAudioBuffer(
+ videoData: ArrayBuffer,
+ options: NativeVideoExportFinishOptions,
+) {
+ const tempVideoPath = path.join(
+ app.getPath("temp"),
+ `recordly-export-video-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.mp4`,
+ );
+ const metrics: NativeVideoAudioMuxMetrics = {};
+ let succeeded = false;
+ let outputPath = tempVideoPath;
+
+ try {
+ const tempVideoWriteStartedAt = getNowMs();
+ await fs.writeFile(tempVideoPath, Buffer.from(videoData));
+ metrics.tempVideoWriteMs = getNowMs() - tempVideoWriteStartedAt;
+ metrics.tempVideoBytes = videoData.byteLength;
+ const finalized = await muxNativeVideoExportAudio(tempVideoPath, options);
+ Object.assign(metrics, finalized.metrics);
+ outputPath = finalized.outputPath;
+ // Record byte size via stat instead of reading the whole file into a
+ // Buffer — fs.readFile throws ERR_FS_FILE_TOO_LARGE on >2 GiB outputs.
+ try {
+ const stat = await fs.stat(outputPath);
+ metrics.muxedVideoBytes = stat.size;
+ } catch {
+ // Stat failures are non-fatal; size is purely metric data.
+ }
+ succeeded = true;
+ return {
+ outputPath,
+ metrics,
+ };
+ } finally {
+ // Always remove the unmuxed intermediate when the muxer wrote a separate
+ // file. Only remove the muxed output on failure — on success the caller
+ // owns it and is responsible for moving/deleting it.
+ const cleanupTargets: string[] = [];
+ if (outputPath !== tempVideoPath) {
+ cleanupTargets.push(tempVideoPath);
+ }
+ if (!succeeded) {
+ cleanupTargets.push(outputPath);
+ }
+ if (cleanupTargets.length > 0) {
+ await Promise.allSettled(
+ cleanupTargets.map((target) => removeTemporaryExportFile(target)),
+ );
+ }
+ }
+}
diff --git a/electron/ipc/export/nativeStaticLayoutRoutePlan.test.ts b/electron/ipc/export/nativeStaticLayoutRoutePlan.test.ts
new file mode 100644
index 000000000..36bcaf064
--- /dev/null
+++ b/electron/ipc/export/nativeStaticLayoutRoutePlan.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+import {
+ type NativeStaticLayoutRouteSource,
+ type NvidiaCudaExportCapabilityProbe,
+ planNativeStaticLayoutRoutes,
+ type WindowsD3D11ExportCapabilityProbe,
+} from "./nativeStaticLayoutRoutePlan";
+
+const source: NativeStaticLayoutRouteSource = {
+ inputCodec: "h264",
+ proxyCodec: "h264",
+ proxyCreated: false,
+};
+
+const cudaProbe: NvidiaCudaExportCapabilityProbe = {
+ platform: "win32",
+ appPackaged: true,
+ explicitEnabled: false,
+ explicitDisabled: false,
+ packagedAutoCandidateEnabled: true,
+ packagedAutoCandidateActive: true,
+ windowsGpuCompositorEnabled: true,
+ wrapperPath: "C:\\Recordly\\run-mp4-pipeline.mjs",
+ hasNvidiaGpu: true,
+ audioMode: "copy-source",
+ audioSkipReason: null,
+ stallTimeoutMs: 120_000,
+ skipReason: null,
+};
+
+const d3d11Probe: WindowsD3D11ExportCapabilityProbe = {
+ platform: "win32",
+ windowsGpuCompositorEnabled: true,
+ helperPath: "C:\\Recordly\\recordly-gpu-export.exe",
+ adapterIndexOverride: null,
+ preferHighPerformanceAdapter: true,
+ nvencSdkRequested: false,
+ skipReason: null,
+};
+
+describe("planNativeStaticLayoutRoutes", () => {
+ it("selects CUDA first and records D3D11 plus FFmpeg fallbacks", () => {
+ expect(
+ planNativeStaticLayoutRoutes({
+ cuda: cudaProbe,
+ d3d11: d3d11Probe,
+ source,
+ }),
+ ).toEqual({
+ selectedRoute: "nvidia-cuda-compositor",
+ decisions: [
+ {
+ route: "nvidia-cuda-compositor",
+ status: "selected",
+ reasons: ["cuda-wrapper-and-nvidia-gpu-available"],
+ },
+ {
+ route: "windows-d3d11-compositor",
+ status: "fallback",
+ reasons: ["documented-fallback-if-cuda-runtime-fails"],
+ },
+ {
+ route: "ffmpeg-static-layout",
+ status: "fallback",
+ reasons: ["native-gpu-runtime-fallback"],
+ },
+ ],
+ cuda: cudaProbe,
+ d3d11: d3d11Probe,
+ source,
+ });
+ });
+
+ it("selects D3D11 when CUDA is unavailable", () => {
+ const cuda = {
+ ...cudaProbe,
+ hasNvidiaGpu: false,
+ skipReason: "nvidia-gpu-unavailable",
+ } satisfies NvidiaCudaExportCapabilityProbe;
+
+ expect(
+ planNativeStaticLayoutRoutes({
+ cuda,
+ d3d11: d3d11Probe,
+ source,
+ }),
+ ).toMatchObject({
+ selectedRoute: "windows-d3d11-compositor",
+ decisions: [
+ {
+ route: "nvidia-cuda-compositor",
+ status: "rejected",
+ reasons: ["nvidia-gpu-unavailable"],
+ },
+ {
+ route: "windows-d3d11-compositor",
+ status: "selected",
+ reasons: ["documented-fallback-after-cuda-skip:nvidia-gpu-unavailable"],
+ },
+ {
+ route: "ffmpeg-static-layout",
+ status: "fallback",
+ reasons: ["windows-d3d11-runtime-fallback"],
+ },
+ ],
+ });
+ });
+
+ it("selects FFmpeg when both native GPU routes are unavailable", () => {
+ const cuda = {
+ ...cudaProbe,
+ wrapperPath: null,
+ skipReason: "cuda-wrapper-unavailable",
+ } satisfies NvidiaCudaExportCapabilityProbe;
+ const d3d11 = {
+ ...d3d11Probe,
+ helperPath: null,
+ skipReason: "windows-gpu-helper-unavailable",
+ } satisfies WindowsD3D11ExportCapabilityProbe;
+
+ expect(
+ planNativeStaticLayoutRoutes({
+ cuda,
+ d3d11,
+ source,
+ }),
+ ).toEqual({
+ selectedRoute: "ffmpeg-static-layout",
+ decisions: [
+ {
+ route: "nvidia-cuda-compositor",
+ status: "rejected",
+ reasons: ["cuda-wrapper-unavailable"],
+ },
+ {
+ route: "windows-d3d11-compositor",
+ status: "rejected",
+ reasons: ["windows-gpu-helper-unavailable"],
+ },
+ {
+ route: "ffmpeg-static-layout",
+ status: "selected",
+ reasons: ["native-gpu-routes-unavailable"],
+ },
+ ],
+ cuda,
+ d3d11,
+ source,
+ });
+ });
+
+ it("preserves proxy source metadata for route diagnostics", () => {
+ const proxiedSource = {
+ inputCodec: "vp9",
+ proxyCodec: "h264",
+ proxyCreated: true,
+ };
+
+ expect(
+ planNativeStaticLayoutRoutes({
+ cuda: cudaProbe,
+ d3d11: d3d11Probe,
+ source: proxiedSource,
+ }).source,
+ ).toEqual(proxiedSource);
+ });
+});
diff --git a/electron/ipc/export/nativeStaticLayoutRoutePlan.ts b/electron/ipc/export/nativeStaticLayoutRoutePlan.ts
new file mode 100644
index 000000000..3ee6c4e73
--- /dev/null
+++ b/electron/ipc/export/nativeStaticLayoutRoutePlan.ts
@@ -0,0 +1,132 @@
+import type { NativeVideoExportAudioMode } from "../nativeVideoExport";
+
+export type NativeStaticLayoutRoute =
+ | "nvidia-cuda-compositor"
+ | "windows-d3d11-compositor"
+ | "ffmpeg-static-layout";
+
+export interface NativeStaticLayoutRouteDecision {
+ route: NativeStaticLayoutRoute;
+ status: "selected" | "fallback" | "rejected";
+ reasons: string[];
+}
+
+export interface NvidiaCudaExportCapabilityProbe {
+ platform: NodeJS.Platform;
+ appPackaged: boolean;
+ explicitEnabled: boolean;
+ explicitDisabled: boolean;
+ packagedAutoCandidateEnabled: boolean;
+ packagedAutoCandidateActive: boolean;
+ windowsGpuCompositorEnabled: boolean;
+ wrapperPath: string | null;
+ hasNvidiaGpu: boolean | null;
+ audioMode: NativeVideoExportAudioMode;
+ audioSkipReason: string | null;
+ stallTimeoutMs: number | null;
+ skipReason: string | null;
+}
+
+export interface WindowsD3D11ExportCapabilityProbe {
+ platform: NodeJS.Platform;
+ windowsGpuCompositorEnabled: boolean;
+ helperPath: string | null;
+ adapterIndexOverride: number | null;
+ preferHighPerformanceAdapter: boolean;
+ nvencSdkRequested: boolean;
+ skipReason: string | null;
+}
+
+export interface NativeStaticLayoutRouteSource {
+ inputCodec: string;
+ proxyCodec?: string;
+ proxyCreated: boolean;
+}
+
+export interface NativeStaticLayoutRoutePlan {
+ selectedRoute: NativeStaticLayoutRoute;
+ decisions: NativeStaticLayoutRouteDecision[];
+ cuda: NvidiaCudaExportCapabilityProbe;
+ d3d11: WindowsD3D11ExportCapabilityProbe;
+ source: NativeStaticLayoutRouteSource;
+}
+
+export function planNativeStaticLayoutRoutes(options: {
+ cuda: NvidiaCudaExportCapabilityProbe;
+ d3d11: WindowsD3D11ExportCapabilityProbe;
+ source: NativeStaticLayoutRouteSource;
+}): NativeStaticLayoutRoutePlan {
+ const { cuda, d3d11, source } = options;
+ const decisions: NativeStaticLayoutRouteDecision[] = [];
+
+ if (!cuda.skipReason) {
+ decisions.push({
+ route: "nvidia-cuda-compositor",
+ status: "selected",
+ reasons: ["cuda-wrapper-and-nvidia-gpu-available"],
+ });
+ decisions.push({
+ route: "windows-d3d11-compositor",
+ status: d3d11.skipReason ? "rejected" : "fallback",
+ reasons: d3d11.skipReason
+ ? [d3d11.skipReason]
+ : ["documented-fallback-if-cuda-runtime-fails"],
+ });
+ decisions.push({
+ route: "ffmpeg-static-layout",
+ status: "fallback",
+ reasons: ["native-gpu-runtime-fallback"],
+ });
+ return {
+ selectedRoute: "nvidia-cuda-compositor",
+ decisions,
+ cuda,
+ d3d11,
+ source,
+ };
+ }
+
+ decisions.push({
+ route: "nvidia-cuda-compositor",
+ status: "rejected",
+ reasons: [cuda.skipReason],
+ });
+
+ if (!d3d11.skipReason) {
+ decisions.push({
+ route: "windows-d3d11-compositor",
+ status: "selected",
+ reasons: [`documented-fallback-after-cuda-skip:${cuda.skipReason}`],
+ });
+ decisions.push({
+ route: "ffmpeg-static-layout",
+ status: "fallback",
+ reasons: ["windows-d3d11-runtime-fallback"],
+ });
+ return {
+ selectedRoute: "windows-d3d11-compositor",
+ decisions,
+ cuda,
+ d3d11,
+ source,
+ };
+ }
+
+ decisions.push({
+ route: "windows-d3d11-compositor",
+ status: "rejected",
+ reasons: [d3d11.skipReason],
+ });
+ decisions.push({
+ route: "ffmpeg-static-layout",
+ status: "selected",
+ reasons: ["native-gpu-routes-unavailable"],
+ });
+ return {
+ selectedRoute: "ffmpeg-static-layout",
+ decisions,
+ cuda,
+ d3d11,
+ source,
+ };
+}
diff --git a/electron/ipc/ffmpeg/binary.ts b/electron/ipc/ffmpeg/binary.ts
new file mode 100644
index 000000000..a0cf8468c
--- /dev/null
+++ b/electron/ipc/ffmpeg/binary.ts
@@ -0,0 +1,161 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { app } from "electron";
+
+const nodeRequire = createRequire(import.meta.url);
+
+export function loadFfmpegStatic(): string | null {
+ try {
+ const moduleExports = nodeRequire("ffmpeg-static");
+ if (typeof moduleExports === "string") {
+ return moduleExports;
+ }
+
+ if (typeof moduleExports?.default === "string") {
+ return moduleExports.default as string;
+ }
+ } catch {
+ // ffmpeg-static not available; fall through to system FFmpeg
+ }
+
+ return null;
+}
+
+export function loadFfprobeStatic(): string | null {
+ try {
+ const moduleExports = nodeRequire("ffprobe-static");
+ if (typeof moduleExports === "string") {
+ return moduleExports;
+ }
+
+ if (typeof moduleExports?.path === "string") {
+ return moduleExports.path as string;
+ }
+
+ if (typeof moduleExports?.default === "string") {
+ return moduleExports.default as string;
+ }
+
+ if (typeof moduleExports?.default?.path === "string") {
+ return moduleExports.default.path as string;
+ }
+ } catch {
+ // ffprobe-static not available; fall through to system FFprobe
+ }
+
+ return null;
+}
+
+export function resolveSystemFfmpegBinaryPath(): string | null {
+ const locator = process.platform === "win32" ? "where" : "which";
+ const result = spawnSync(locator, ["ffmpeg"], {
+ encoding: "utf-8",
+ windowsHide: true,
+ });
+
+ if (result.status === 0) {
+ const candidate = result.stdout
+ .split(/\r?\n/)
+ .map((line: string) => line.trim())
+ .find((line: string) => line.length > 0);
+
+ if (candidate) {
+ return candidate;
+ }
+ }
+
+ // Fallback: check common install paths directly (Electron's shell may lack full PATH)
+ if (process.platform !== "win32") {
+ const commonPaths = [
+ "/opt/homebrew/bin/ffmpeg",
+ "/usr/local/bin/ffmpeg",
+ "/usr/bin/ffmpeg",
+ ];
+ for (const p of commonPaths) {
+ if (existsSync(p)) {
+ return p;
+ }
+ }
+ }
+
+ return null;
+}
+
+export function resolveSystemFfprobeBinaryPath(): string | null {
+ const locator = process.platform === "win32" ? "where" : "which";
+ const result = spawnSync(locator, ["ffprobe"], {
+ encoding: "utf-8",
+ windowsHide: true,
+ });
+
+ if (result.status === 0) {
+ const candidate = result.stdout
+ .split(/\r?\n/)
+ .map((line: string) => line.trim())
+ .find((line: string) => line.length > 0);
+
+ if (candidate) {
+ return candidate;
+ }
+ }
+
+ if (process.platform !== "win32") {
+ const commonPaths = [
+ "/opt/homebrew/bin/ffprobe",
+ "/usr/local/bin/ffprobe",
+ "/usr/bin/ffprobe",
+ ];
+ for (const p of commonPaths) {
+ if (existsSync(p)) {
+ return p;
+ }
+ }
+ }
+
+ return null;
+}
+
+export function getFfmpegBinaryPath(): string {
+ const ffmpegStatic = loadFfmpegStatic();
+ if (ffmpegStatic && typeof ffmpegStatic === "string") {
+ const bundledPath = app.isPackaged
+ ? ffmpegStatic.replace(/\.asar([/\\])/, ".asar.unpacked$1")
+ : ffmpegStatic;
+
+ if (existsSync(bundledPath)) {
+ return bundledPath;
+ }
+ }
+
+ const systemFfmpeg = resolveSystemFfmpegBinaryPath();
+ if (systemFfmpeg) {
+ return systemFfmpeg;
+ }
+
+ throw new Error(
+ "FFmpeg binary is unavailable. Install ffmpeg-static for this platform or make ffmpeg available on PATH.",
+ );
+}
+
+export function getFfprobeBinaryPath(): string {
+ const ffprobeStatic = loadFfprobeStatic();
+ if (ffprobeStatic && typeof ffprobeStatic === "string") {
+ const bundledPath = app.isPackaged
+ ? ffprobeStatic.replace(/\.asar([/\\])/, ".asar.unpacked$1")
+ : ffprobeStatic;
+
+ if (existsSync(bundledPath)) {
+ return bundledPath;
+ }
+ }
+
+ const systemFfprobe = resolveSystemFfprobeBinaryPath();
+ if (systemFfprobe) {
+ return systemFfprobe;
+ }
+
+ throw new Error(
+ "FFprobe binary is unavailable. Install ffprobe-static for this platform or make ffprobe available on PATH.",
+ );
+}
diff --git a/electron/ipc/ffmpeg/filters.test.ts b/electron/ipc/ffmpeg/filters.test.ts
new file mode 100644
index 000000000..8b8ecfdb5
--- /dev/null
+++ b/electron/ipc/ffmpeg/filters.test.ts
@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ appendSyncedAudioFilter,
+ applyRecordedAudioStartDelay,
+ getAudioSyncAdjustment,
+} from "./filters";
+
+describe("getAudioSyncAdjustment", () => {
+ it("does not speed up longer audio tracks that would advance speech", () => {
+ expect(getAudioSyncAdjustment(120, 122.5)).toEqual({
+ mode: "none",
+ delayMs: 0,
+ tempoRatio: 1,
+ durationDeltaMs: -2500,
+ });
+ });
+
+ it("still stretches slightly shorter audio tracks to match the video", () => {
+ expect(getAudioSyncAdjustment(120, 117)).toEqual({
+ mode: "tempo",
+ delayMs: 0,
+ tempoRatio: 0.975,
+ durationDeltaMs: 3000,
+ });
+ });
+
+ it("still delays much shorter audio tracks instead of extreme tempo correction", () => {
+ expect(getAudioSyncAdjustment(120, 110)).toEqual({
+ mode: "delay",
+ delayMs: 10000,
+ tempoRatio: 1,
+ durationDeltaMs: 10000,
+ });
+ });
+
+ it("pads trailing silence instead of prepending extreme delay for very short audio tracks", () => {
+ expect(getAudioSyncAdjustment(600, 480)).toEqual({
+ mode: "pad",
+ delayMs: 0,
+ tempoRatio: 1,
+ durationDeltaMs: 120000,
+ });
+ });
+
+ it("does not inject atempo when longer audio stays on the anchored path", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", getAudioSyncAdjustment(120, 122.5));
+
+ expect(filterParts).toEqual([
+ "[1:a]aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("still injects atempo for slightly shorter audio tracks", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", getAudioSyncAdjustment(120, 117));
+
+ expect(filterParts).toEqual([
+ "[1:a]atempo=0.975000,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("pads the tail for very short audio tracks", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", getAudioSyncAdjustment(600, 480));
+
+ expect(filterParts).toEqual([
+ "[1:a]apad=pad_dur=120.000,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("pads the remaining tail after a measured late start delay", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", {
+ mode: "delay",
+ delayMs: 18051,
+ tempoRatio: 1,
+ durationDeltaMs: 1631070,
+ });
+
+ expect(filterParts).toEqual([
+ "[1:a]adelay=18051|18051,apad=pad_dur=1613.019,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("does not pad when a measured late start already explains the duration gap", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", {
+ mode: "delay",
+ delayMs: 10000,
+ tempoRatio: 1,
+ durationDeltaMs: 10000,
+ });
+
+ expect(filterParts).toEqual([
+ "[1:a]adelay=10000|10000,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("can add a small gain boost before resampling", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(
+ filterParts,
+ "[1:a]",
+ "aout",
+ getAudioSyncAdjustment(120, 120),
+ 1.4,
+ );
+
+ expect(filterParts).toEqual([
+ "[1:a]volume=1.400,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+
+ it("can prepend mic normalization filters before sync handling", () => {
+ const filterParts: string[] = [];
+ appendSyncedAudioFilter(filterParts, "[1:a]", "aout", getAudioSyncAdjustment(120, 120), {
+ preFilters: ["adeclip=threshold=1", "loudnorm=I=-16:TP=-1.5:LRA=11"],
+ });
+
+ expect(filterParts).toEqual([
+ "[1:a]adeclip=threshold=1,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=async=1:first_pts=0,asetpts=PTS-STARTPTS[aout]",
+ ]);
+ });
+});
+
+describe("applyRecordedAudioStartDelay", () => {
+ it("pads the tail when recorded metadata says audio started on time", () => {
+ expect(applyRecordedAudioStartDelay(getAudioSyncAdjustment(120, 110), 0)).toEqual({
+ mode: "pad",
+ delayMs: 0,
+ tempoRatio: 1,
+ durationDeltaMs: 10000,
+ });
+ });
+
+ it("prefers a measured start delay over a tempo-only heuristic", () => {
+ expect(applyRecordedAudioStartDelay(getAudioSyncAdjustment(120, 119.8), 275)).toEqual({
+ mode: "delay",
+ delayMs: 275,
+ tempoRatio: 1,
+ durationDeltaMs: 200,
+ });
+ });
+
+ it("applies a measured start delay even when durations already match", () => {
+ expect(applyRecordedAudioStartDelay(getAudioSyncAdjustment(120, 120), 275)).toEqual({
+ mode: "delay",
+ delayMs: 275,
+ tempoRatio: 1,
+ durationDeltaMs: 0,
+ });
+ });
+
+ it("leaves tempo correction alone when recorded metadata says there was no late start", () => {
+ expect(applyRecordedAudioStartDelay(getAudioSyncAdjustment(120, 117), 0)).toEqual({
+ mode: "tempo",
+ delayMs: 0,
+ tempoRatio: 0.975,
+ durationDeltaMs: 3000,
+ });
+ });
+});
diff --git a/electron/ipc/ffmpeg/filters.ts b/electron/ipc/ffmpeg/filters.ts
new file mode 100644
index 000000000..2d3370c7f
--- /dev/null
+++ b/electron/ipc/ffmpeg/filters.ts
@@ -0,0 +1,258 @@
+import type { AudioSyncAdjustment, PauseSegment } from "../types";
+
+const MAX_AUDIO_SYNC_DELAY_MS = 15000;
+export const ATEMPO_FILTER_EPSILON = 0.0005;
+
+export function buildAtempoFilters(tempoRatio: number): string[] {
+ if (!Number.isFinite(tempoRatio) || tempoRatio <= 0) {
+ return [];
+ }
+
+ const filters: string[] = [];
+ let remaining = tempoRatio;
+
+ while (remaining < 0.5) {
+ filters.push("atempo=0.5");
+ remaining /= 0.5;
+ }
+
+ while (remaining > 2) {
+ filters.push("atempo=2.0");
+ remaining /= 2.0;
+ }
+
+ if (Math.abs(remaining - 1) > ATEMPO_FILTER_EPSILON) {
+ filters.push(`atempo=${remaining.toFixed(6)}`);
+ }
+
+ return filters;
+}
+
+export function getAudioSyncAdjustment(
+ videoDuration: number,
+ audioDuration: number,
+): AudioSyncAdjustment {
+ if (
+ !Number.isFinite(videoDuration) ||
+ !Number.isFinite(audioDuration) ||
+ videoDuration <= 0 ||
+ audioDuration <= 0
+ ) {
+ return { mode: "none", delayMs: 0, tempoRatio: 1, durationDeltaMs: 0 };
+ }
+
+ const durationDeltaMs = Math.round((videoDuration - audioDuration) * 1000);
+ const absDeltaMs = Math.abs(durationDeltaMs);
+ if (absDeltaMs <= 20) {
+ return { mode: "none", delayMs: 0, tempoRatio: 1, durationDeltaMs };
+ }
+
+ // When the recorded audio runs longer than the video, globally speeding it
+ // up can pull speech ahead of the picture. Keep the track anchored at the
+ // start instead and let the downstream mux path trim any trailing overrun.
+ if (durationDeltaMs < 0) {
+ return { mode: "none", delayMs: 0, tempoRatio: 1, durationDeltaMs };
+ }
+
+ const tempoRatio = Math.max(0.5, Math.min(2, audioDuration / videoDuration));
+ const relativeDelta = absDeltaMs / Math.max(videoDuration * 1000, 1);
+
+ if (relativeDelta <= 0.03 || absDeltaMs <= 1500) {
+ return { mode: "tempo", delayMs: 0, tempoRatio, durationDeltaMs };
+ }
+
+ if (durationDeltaMs > MAX_AUDIO_SYNC_DELAY_MS) {
+ return { mode: "pad", delayMs: 0, tempoRatio: 1, durationDeltaMs };
+ }
+
+ return { mode: "delay", delayMs: durationDeltaMs, tempoRatio: 1, durationDeltaMs };
+}
+
+export function applyRecordedAudioStartDelay(
+ adjustment: AudioSyncAdjustment,
+ recordedStartDelayMs?: number | null,
+): AudioSyncAdjustment {
+ if (!Number.isFinite(recordedStartDelayMs) || (recordedStartDelayMs ?? 0) < 0) {
+ return adjustment;
+ }
+
+ const delayMs = Math.max(0, Math.round(recordedStartDelayMs ?? 0));
+ if (delayMs > 20) {
+ return {
+ mode: "delay",
+ delayMs,
+ tempoRatio: 1,
+ durationDeltaMs: adjustment.durationDeltaMs,
+ };
+ }
+
+ if (adjustment.mode !== "delay" && adjustment.mode !== "pad") {
+ return adjustment;
+ }
+
+ return {
+ mode: "pad",
+ delayMs: 0,
+ tempoRatio: 1,
+ durationDeltaMs: adjustment.durationDeltaMs,
+ };
+}
+
+export function appendSyncedAudioFilter(
+ filterParts: string[],
+ inputLabel: string,
+ outputLabel: string,
+ adjustment: AudioSyncAdjustment,
+ options: number | { volumeMultiplier?: number; preFilters?: string[] } = 1,
+) {
+ const volumeMultiplier =
+ typeof options === "number" ? options : (options.volumeMultiplier ?? 1);
+ const preFilters = typeof options === "number" ? [] : (options.preFilters ?? []);
+ const filters: string[] = [...preFilters];
+
+ if (adjustment.mode === "delay" && adjustment.delayMs > 0) {
+ filters.push(`adelay=${adjustment.delayMs}|${adjustment.delayMs}`);
+ }
+
+ if (adjustment.mode === "delay" && adjustment.durationDeltaMs > adjustment.delayMs + 20) {
+ filters.push(
+ `apad=pad_dur=${formatFfmpegSeconds(adjustment.durationDeltaMs - adjustment.delayMs)}`,
+ );
+ }
+
+ if (adjustment.mode === "tempo") {
+ filters.push(...buildAtempoFilters(adjustment.tempoRatio));
+ }
+
+ if (adjustment.mode === "pad" && adjustment.durationDeltaMs > 0) {
+ filters.push(`apad=pad_dur=${formatFfmpegSeconds(adjustment.durationDeltaMs)}`);
+ }
+
+ if (
+ Number.isFinite(volumeMultiplier) &&
+ volumeMultiplier > 0 &&
+ Math.abs(volumeMultiplier - 1) > 0.0005
+ ) {
+ filters.push(`volume=${volumeMultiplier.toFixed(3)}`);
+ }
+
+ filters.push("aresample=async=1:first_pts=0", "asetpts=PTS-STARTPTS");
+ filterParts.push(`${inputLabel}${filters.join(",")}[${outputLabel}]`);
+}
+
+export function formatFfmpegSeconds(milliseconds: number): string {
+ return (milliseconds / 1000).toFixed(3);
+}
+
+export function normalizePauseSegments(pauseSegments: PauseSegment[] | undefined): PauseSegment[] {
+ if (!Array.isArray(pauseSegments) || pauseSegments.length === 0) {
+ return [];
+ }
+
+ const normalized = pauseSegments
+ .map((segment) => {
+ const startMs = Number(segment?.startMs);
+ const endMs = Number(segment?.endMs);
+
+ if (!Number.isFinite(startMs) || !Number.isFinite(endMs)) {
+ return null;
+ }
+
+ const clampedStart = Math.max(0, Math.round(startMs));
+ const clampedEnd = Math.max(0, Math.round(endMs));
+ if (clampedEnd <= clampedStart) {
+ return null;
+ }
+
+ return { startMs: clampedStart, endMs: clampedEnd };
+ })
+ .filter((segment): segment is PauseSegment => !!segment)
+ .sort((left, right) => left.startMs - right.startMs);
+
+ if (normalized.length <= 1) {
+ return normalized;
+ }
+
+ const merged: PauseSegment[] = [{ ...normalized[0] }];
+
+ for (const segment of normalized.slice(1)) {
+ const previous = merged[merged.length - 1];
+ if (segment.startMs <= previous.endMs) {
+ previous.endMs = Math.max(previous.endMs, segment.endMs);
+ } else {
+ merged.push({ ...segment });
+ }
+ }
+
+ return merged;
+}
+
+export function buildPausedAudioFilter(
+ inputLabel: string,
+ outputLabel: string,
+ pauseSegments: PauseSegment[],
+): string | null {
+ if (pauseSegments.length === 0) {
+ return null;
+ }
+
+ const activeSegments: Array<{ startMs: number; endMs?: number }> = [];
+ let cursorMs = 0;
+
+ for (const pauseSegment of pauseSegments) {
+ if (pauseSegment.startMs > cursorMs) {
+ activeSegments.push({ startMs: cursorMs, endMs: pauseSegment.startMs });
+ }
+ cursorMs = Math.max(cursorMs, pauseSegment.endMs);
+ }
+
+ activeSegments.push({ startMs: cursorMs });
+
+ const filterParts: string[] = [];
+ const segmentLabels: string[] = [];
+
+ activeSegments.forEach((segment, index) => {
+ if (typeof segment.endMs === "number" && segment.endMs <= segment.startMs) {
+ return;
+ }
+
+ const segmentLabel = `${outputLabel}_part${index}`;
+ const trimArgs =
+ typeof segment.endMs === "number"
+ ? `start=${formatFfmpegSeconds(segment.startMs)}:end=${formatFfmpegSeconds(segment.endMs)}`
+ : `start=${formatFfmpegSeconds(segment.startMs)}`;
+
+ filterParts.push(`[${inputLabel}]atrim=${trimArgs},asetpts=PTS-STARTPTS[${segmentLabel}]`);
+ segmentLabels.push(`[${segmentLabel}]`);
+ });
+
+ if (segmentLabels.length === 0) {
+ return null;
+ }
+
+ if (segmentLabels.length === 1) {
+ filterParts.push(`${segmentLabels[0]}anull[${outputLabel}]`);
+ } else {
+ filterParts.push(
+ `${segmentLabels.join("")}concat=n=${segmentLabels.length}:v=0:a=1[${outputLabel}]`,
+ );
+ }
+
+ return filterParts.join(";");
+}
+
+export function parseFfmpegDurationSeconds(stderr: string): number | null {
+ const match = stderr.match(/Duration:\s+(\d+):(\d+):(\d+(?:\.\d+)?)/i);
+ if (!match) {
+ return null;
+ }
+
+ const hours = Number(match[1]);
+ const minutes = Number(match[2]);
+ const seconds = Number(match[3]);
+ if (![hours, minutes, seconds].every(Number.isFinite)) {
+ return null;
+ }
+
+ return hours * 3600 + minutes * 60 + seconds;
+}
diff --git a/electron/ipc/handlers.ts b/electron/ipc/handlers.ts
index 81e8af5ae..2a0f998eb 100644
--- a/electron/ipc/handlers.ts
+++ b/electron/ipc/handlers.ts
@@ -1,181 +1,74 @@
-import { ipcMain, desktopCapturer, BrowserWindow, shell, app } from 'electron'
-import { startMouseTracking, stopMouseTracking, getTrackingData } from './mouseTracking'
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import { RECORDINGS_DIR } from '../main'
+import { BrowserWindow } from "electron";
+import { registerAnnouncementHandlers } from "./register/announcements";
+import { registerAssetHandlers } from "./register/assets";
+import { registerCaptionHandlers } from "./register/captions";
+import { registerExportHandlers } from "./register/export";
+import { registerPermissionHandlers } from "./register/permissions";
+import { registerProjectHandlers } from "./register/project";
+import { registerRecordingHandlers } from "./register/recording";
+import { registerSettingsHandlers } from "./register/settings";
+import { registerSourceHandlers } from "./register/sources";
+import {
+ selectedSource,
+ setNativeScreenRecordingActive,
+ setWindowsCapturePaused,
+ setWindowsCaptureProcess,
+ setWindowsCaptureStopRequested,
+ setWindowsCaptureTargetPath,
+ setWindowsMicAudioPath,
+ setWindowsNativeCaptureActive,
+ setWindowsOrphanedMicAudioPath,
+ setWindowsPendingVideoPath,
+ setWindowsSystemAudioPath,
+ windowsCaptureProcess,
+} from "./state";
+
+export { cleanupAllExportStreams } from "./export/exportStream";
+export { cleanupNativeVideoExportSessions } from "./export/native-video";
+
+/** Returns the currently selected source ID for setDisplayMediaRequestHandler */
+export function getSelectedSourceId(): string | null {
+ return (selectedSource?.id as string | null) ?? null;
+}
-let selectedSource: any = null
+export function killWindowsCaptureProcess() {
+ if (windowsCaptureProcess) {
+ try {
+ windowsCaptureProcess.kill();
+ } catch {
+ /* ignore */
+ }
+ setWindowsCaptureProcess(null);
+ setWindowsCaptureTargetPath(null);
+ setWindowsNativeCaptureActive(false);
+ setNativeScreenRecordingActive(false);
+ setWindowsCaptureStopRequested(false);
+ setWindowsCapturePaused(false);
+ setWindowsSystemAudioPath(null);
+ setWindowsMicAudioPath(null);
+ setWindowsOrphanedMicAudioPath(null);
+ setWindowsPendingVideoPath(null);
+ }
+}
export function registerIpcHandlers(
- createEditorWindow: () => void,
- createSourceSelectorWindow: () => BrowserWindow,
- getMainWindow: () => BrowserWindow | null,
- getSourceSelectorWindow: () => BrowserWindow | null,
- onRecordingStateChange?: (recording: boolean, sourceName: string) => void
+ createEditorWindow: () => void,
+ createSourceSelectorWindow: () => BrowserWindow,
+ _getMainWindow: () => BrowserWindow | null,
+ getSourceSelectorWindow: () => BrowserWindow | null,
+ onRecordingStateChange?: (recording: boolean, sourceName: string) => void,
) {
- ipcMain.handle('get-sources', async (_, opts) => {
- const sources = await desktopCapturer.getSources(opts)
- return sources.map(source => ({
- id: source.id,
- name: source.name,
- display_id: source.display_id,
- thumbnail: source.thumbnail ? source.thumbnail.toDataURL() : null,
- appIcon: source.appIcon ? source.appIcon.toDataURL() : null
- }))
- })
-
- ipcMain.handle('select-source', (_, source) => {
- selectedSource = source
- const sourceSelectorWin = getSourceSelectorWindow()
- if (sourceSelectorWin) {
- sourceSelectorWin.close()
- }
- return selectedSource
- })
-
- ipcMain.handle('get-selected-source', () => {
- return selectedSource
- })
-
- ipcMain.handle('open-source-selector', () => {
- const sourceSelectorWin = getSourceSelectorWindow()
- if (sourceSelectorWin) {
- sourceSelectorWin.focus()
- return
- }
- createSourceSelectorWindow()
- })
-
- ipcMain.handle('switch-to-editor', () => {
- const mainWin = getMainWindow()
- if (mainWin) {
- mainWin.close()
- }
- createEditorWindow()
- })
-
- ipcMain.handle('start-mouse-tracking', () => {
- return startMouseTracking()
- })
-
- ipcMain.handle('stop-mouse-tracking', () => {
- return stopMouseTracking()
- })
-
- ipcMain.handle('store-recorded-video', async (_, videoData: ArrayBuffer, fileName: string) => {
- try {
- const videoPath = path.join(RECORDINGS_DIR, fileName)
- await fs.writeFile(videoPath, Buffer.from(videoData))
-
- return {
- success: true,
- path: videoPath,
- message: 'Video stored successfully'
- }
- } catch (error) {
- console.error('Failed to store video:', error)
- return {
- success: false,
- message: 'Failed to store video',
- error: String(error)
- }
- }
- })
-
- ipcMain.handle('store-mouse-tracking-data', async (_, fileName: string) => {
- try {
- const data = getTrackingData()
-
- if (data.length === 0) {
- return { success: false, message: 'No tracking data to save' }
- }
-
- const trackingPath = path.join(RECORDINGS_DIR, fileName)
- await fs.writeFile(trackingPath, JSON.stringify(data, null, 2), 'utf-8')
-
- return {
- success: true,
- path: trackingPath,
- eventCount: data.length,
- message: 'Mouse tracking data stored successfully'
- }
- } catch (error) {
- console.error('Failed to store mouse tracking data:', error)
- return {
- success: false,
- message: 'Failed to store mouse tracking data',
- error: String(error)
- }
- }
- })
-
- ipcMain.handle('get-recorded-video-path', async () => {
- try {
- const files = await fs.readdir(RECORDINGS_DIR)
- const videoFiles = files.filter(file => file.endsWith('.webm'))
-
- if (videoFiles.length === 0) {
- return { success: false, message: 'No recorded video found' }
- }
-
- const latestVideo = videoFiles.sort().reverse()[0]
- const videoPath = path.join(RECORDINGS_DIR, latestVideo)
-
- return { success: true, path: videoPath }
- } catch (error) {
- console.error('Failed to get video path:', error)
- return { success: false, message: 'Failed to get video path', error: String(error) }
- }
- })
-
- ipcMain.handle('set-recording-state', (_, recording: boolean) => {
- const source = selectedSource || { name: 'Screen' }
- if (onRecordingStateChange) {
- onRecordingStateChange(recording, source.name)
- }
- })
-
- ipcMain.handle('open-external-url', async (_, url: string) => {
- try {
- await shell.openExternal(url)
- return { success: true }
- } catch (error) {
- console.error('Failed to open URL:', error)
- return { success: false, error: String(error) }
- }
- })
-
- // Return base path for assets so renderer can resolve file:// paths in production
- ipcMain.handle('get-asset-base-path', () => {
- try {
- if (app.isPackaged) {
- return path.join(process.resourcesPath, 'assets')
- }
- return path.join(app.getAppPath(), 'public', 'assets')
- } catch (err) {
- console.error('Failed to resolve asset base path:', err)
- return null
- }
- })
-
- ipcMain.handle('save-exported-video', async (_, videoData: ArrayBuffer, fileName: string) => {
- try {
- const downloadsPath = app.getPath('downloads')
- const videoPath = path.join(downloadsPath, fileName)
- await fs.writeFile(videoPath, Buffer.from(videoData))
-
- return {
- success: true,
- path: videoPath,
- message: 'Video exported successfully'
- }
- } catch (error) {
- console.error('Failed to save exported video:', error)
- return {
- success: false,
- message: 'Failed to save exported video',
- error: String(error)
- }
- }
- })
+ registerSourceHandlers({
+ createEditorWindow,
+ createSourceSelectorWindow,
+ getSourceSelectorWindow,
+ });
+ registerRecordingHandlers(onRecordingStateChange);
+ registerPermissionHandlers();
+ registerAnnouncementHandlers();
+ registerAssetHandlers();
+ registerExportHandlers();
+ registerCaptionHandlers();
+ registerProjectHandlers();
+ registerSettingsHandlers();
}
diff --git a/electron/ipc/monitorResolver.ts b/electron/ipc/monitorResolver.ts
new file mode 100644
index 000000000..f14bbd38c
--- /dev/null
+++ b/electron/ipc/monitorResolver.ts
@@ -0,0 +1,78 @@
+import { spawnSync } from "node:child_process";
+
+/**
+ * Represents a Windows monitor handle and its physical desktop coordinates.
+ */
+export interface WinMonitorHandle {
+ handle: number;
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+}
+
+/**
+ * Retrieves raw HMONITOR handles from the Windows OS using a PowerShell bridge.
+ * This is necessary because Electron's display IDs are often internal hashes that
+ * cannot be used directly with native Windows APIs like Graphics Capture (WGC).
+ */
+export function getMonitorHandles(): WinMonitorHandle[] {
+ if (process.platform !== "win32") return [];
+
+ // PowerShell snippet that uses P/Invoke to call EnumDisplayMonitors and return raw handles + bounds.
+ const psScript = `
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+using System.Collections.Generic;
+
+public class MonitorHelper {
+ [DllImport("user32.dll")]
+ public static extern bool EnumDisplayMonitors(IntPtr hdc, IntPtr lprcClip, MonitorEnumProc lpfnEnum, IntPtr dwData);
+
+ public delegate bool MonitorEnumProc(IntPtr hMonitor, IntPtr hdcMonitor, ref Rect lprcMonitor, IntPtr dwData);
+
+ [StructLayout(LayoutKind.Sequential)]
+ public struct Rect {
+ public int left;
+ public int top;
+ public int right;
+ public int bottom;
+ }
+
+ public static List GetMonitors() {
+ List result = new List();
+ EnumDisplayMonitors(IntPtr.Zero, IntPtr.Zero, (IntPtr hMonitor, IntPtr hdcMonitor, ref Rect lprcMonitor, IntPtr dwData) => {
+ result.Add(string.Format("{0}|{1}|{2}|{3}|{4}", hMonitor.ToInt64(), lprcMonitor.left, lprcMonitor.top, lprcMonitor.right - lprcMonitor.left, lprcMonitor.bottom - lprcMonitor.top));
+ return true;
+ }, IntPtr.Zero);
+ return result;
+ }
+}
+"@
+[MonitorHelper]::GetMonitors()
+`.trim();
+
+ const result = spawnSync(
+ "powershell.exe",
+ ["-NoProfile", "-NonInteractive", "-Command", psScript],
+ {
+ encoding: "utf-8",
+ timeout: 5000,
+ },
+ );
+
+ if (result.error || result.status !== 0) {
+ // Silent failure is preferred; the caller will fall back to coordinate-based matching.
+ return [];
+ }
+
+ return result.stdout
+ .split("\n")
+ .map((line) => line.trim())
+ .filter((line) => line.length > 0)
+ .map((line) => {
+ const [handle, x, y, width, height] = line.split("|").map(Number);
+ return { handle, x, y, width, height };
+ });
+}
diff --git a/electron/ipc/mouseTracking.ts b/electron/ipc/mouseTracking.ts
deleted file mode 100644
index 47d317174..000000000
--- a/electron/ipc/mouseTracking.ts
+++ /dev/null
@@ -1,155 +0,0 @@
-// uiohook-napi [WIP: scoping out mouse tracking with cross platform support for potential auto zoom/ post processing cursor effects]
-// not currently being used.
-
-import { uIOhook } from 'uiohook-napi'
-
-let isMouseTrackingActive = false
-let isHookStarted = false
-let recordingStartTime: number = 0
-let mouseEventData: MouseEvent[] = []
-
-export interface MouseEvent {
- type: 'move' | 'down' | 'up' | 'click'
- timestamp: number // milliseconds since recording started
- x: number
- y: number
- button?: unknown
- clicks?: number
-}
-
-export interface MouseTrackingSession {
- startTime: number
- events: MouseEvent[]
- duration: number
-}
-
-export function startMouseTracking() {
- if (isMouseTrackingActive) {
- return { success: false, message: 'Already tracking' }
- }
-
- isMouseTrackingActive = true
-
- // Reset data for new recording session
- recordingStartTime = performance.now()
- mouseEventData = []
-
- // Only start the hook once
- if (!isHookStarted) {
- setupMouseEventListeners()
-
- try {
- uIOhook.start()
- isHookStarted = true
- return { success: true, message: 'Mouse tracking started', startTime: recordingStartTime }
- } catch (error) {
- console.error('Failed to start mouse tracking:', error)
- isMouseTrackingActive = false
- return { success: false, message: 'Failed to start hook', error }
- }
- } else {
- return { success: true, message: 'Mouse tracking resumed', startTime: recordingStartTime }
- }
-}
-
-export function stopMouseTracking(): { success: boolean; message: string; data?: MouseTrackingSession } {
- if (!isMouseTrackingActive) {
- return { success: false, message: 'Not currently tracking' }
- }
-
- isMouseTrackingActive = false
-
- const duration = performance.now() - recordingStartTime
-
- const session: MouseTrackingSession = {
- startTime: recordingStartTime,
- events: mouseEventData,
- duration: duration
- }
-
- return {
- success: true,
- message: 'Mouse tracking stopped',
- data: session
- }
-}
-
-function setupMouseEventListeners() {
- // Track mouse movement
- uIOhook.on('mousemove', (e) => {
- if (isMouseTrackingActive) {
- const timestamp = performance.now() - recordingStartTime
- const event: MouseEvent = {
- type: 'move',
- timestamp,
- x: e.x,
- y: e.y
- }
- mouseEventData.push(event)
- }
- })
-
- // Track mouse button press
- uIOhook.on('mousedown', (e) => {
- if (isMouseTrackingActive) {
- const timestamp = performance.now() - recordingStartTime
- const event: MouseEvent = {
- type: 'down',
- timestamp,
- x: e.x,
- y: e.y,
- button: e.button,
- clicks: e.clicks
- }
- mouseEventData.push(event)
- }
- })
-
- // Track mouse button release
- uIOhook.on('mouseup', (e) => {
- if (isMouseTrackingActive) {
- const timestamp = performance.now() - recordingStartTime
- const event: MouseEvent = {
- type: 'up',
- timestamp,
- x: e.x,
- y: e.y,
- button: e.button
- }
- mouseEventData.push(event)
- }
- })
-
- // Track complete click events
- uIOhook.on('click', (e) => {
- if (isMouseTrackingActive) {
- const timestamp = performance.now() - recordingStartTime
- const event: MouseEvent = {
- type: 'click',
- timestamp,
- x: e.x,
- y: e.y,
- button: e.button,
- clicks: e.clicks
- }
- mouseEventData.push(event)
- }
- })
-}
-
-export function getTrackingData(): MouseEvent[] {
- return [...mouseEventData]
-}
-
-export function cleanupMouseTracking() {
- if (isHookStarted) {
- try {
- uIOhook.stop()
- isHookStarted = false
- isMouseTrackingActive = false
- mouseEventData = []
- } catch (error) {
- console.error('Error cleaning up mouse tracking:', error)
- }
- }
-}
diff --git a/electron/ipc/nativeVideoExport.test.ts b/electron/ipc/nativeVideoExport.test.ts
new file mode 100644
index 000000000..47a9a273e
--- /dev/null
+++ b/electron/ipc/nativeVideoExport.test.ts
@@ -0,0 +1,325 @@
+import { describe, expect, it } from "vitest";
+import { ATEMPO_FILTER_EPSILON } from "./ffmpeg/filters";
+import {
+ buildEditedTrackSourceAudioFilter,
+ buildNativeConcatArgs,
+ buildNativeCudaOverlayStaticLayoutArgs,
+ buildNativeCudaScaleCpuPadStaticLayoutArgs,
+ buildNativePrecompositedStaticLayoutArgs,
+ buildNativeStaticBackgroundRenderArgs,
+ buildNativeStaticLayoutChunks,
+ buildNativeVideoExportArgs,
+ buildTrimmedSourceAudioFilter,
+ createNativeSquircleMaskPgmBuffer,
+ FFMPEG_BT709_VIDEO_COLOR_ARGS,
+ isNativeCudaOutOfMemory,
+} from "./nativeVideoExport";
+
+describe("buildTrimmedSourceAudioFilter", () => {
+ it("concatenates trimmed source segments into a single output label", () => {
+ expect(
+ buildTrimmedSourceAudioFilter([
+ { startMs: 0, endMs: 2_000 },
+ { startMs: 4_000, endMs: 6_000 },
+ ]),
+ ).toBe(
+ "[1:a]atrim=start=0.000:end=2.000,asetpts=PTS-STARTPTS[trimmed_audio_0];" +
+ "[1:a]atrim=start=4.000:end=6.000,asetpts=PTS-STARTPTS[trimmed_audio_1];" +
+ "[trimmed_audio_0][trimmed_audio_1]concat=n=2:v=0:a=1[aout]",
+ );
+ });
+});
+
+describe("buildEditedTrackSourceAudioFilter", () => {
+ it("builds a concat filtergraph that applies tempo filters for speed changes", () => {
+ const filter = buildEditedTrackSourceAudioFilter(
+ [
+ { startMs: 0, endMs: 2_000, speed: 1 },
+ { startMs: 2_000, endMs: 6_000, speed: 1.5 },
+ ],
+ 44_100,
+ );
+
+ expect(filter).toBe(
+ "[1:a]atrim=start=0.000:end=2.000,asetpts=PTS-STARTPTS[edited_audio_0];" +
+ "[1:a]atrim=start=2.000:end=6.000,asetpts=PTS-STARTPTS,atempo=1.500000[edited_audio_1];" +
+ "[edited_audio_0][edited_audio_1]concat=n=2:v=0:a=1[aout]",
+ );
+ });
+
+ it("builds a filtergraph for slowdown segments with a tempo filter", () => {
+ const filter = buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed: 0.5 }],
+ 44_100,
+ );
+
+ expect(filter).toBe(
+ "[1:a]atrim=start=0.000:end=2.000,asetpts=PTS-STARTPTS,atempo=0.500000[edited_audio_0];" +
+ "[edited_audio_0]anull[aout]",
+ );
+ });
+
+ it("treats near-unity speed changes as unchanged audio", () => {
+ const filter = buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed: 1.0002 }],
+ 44_100,
+ );
+
+ expect(filter).toBe(
+ "[1:a]atrim=start=0.000:end=2.000,asetpts=PTS-STARTPTS[edited_audio_0];" +
+ "[edited_audio_0]anull[aout]",
+ );
+ });
+
+ it("treats exact epsilon speed changes as unchanged audio", () => {
+ for (const speed of [1 - ATEMPO_FILTER_EPSILON, 1 + ATEMPO_FILTER_EPSILON]) {
+ const filter = buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed }],
+ 44_100,
+ );
+
+ expect(filter).toBe(
+ "[1:a]atrim=start=0.000:end=2.000,asetpts=PTS-STARTPTS[edited_audio_0];" +
+ "[edited_audio_0]anull[aout]",
+ );
+ }
+ });
+
+ it("returns null when the edited-track filtergraph inputs are incomplete", () => {
+ expect(buildEditedTrackSourceAudioFilter([], 44_100)).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed: 1.5 }],
+ Number.NaN,
+ ),
+ ).toBeNull();
+ });
+
+ it("returns null when the edited-track segments are malformed", () => {
+ expect(
+ buildEditedTrackSourceAudioFilter(
+ [{ startMs: Number.NaN, endMs: 2_000, speed: 1.5 }],
+ 44_100,
+ ),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter([{ startMs: 0, endMs: 2_000, speed: 0 }], 44_100),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter([{ startMs: 0, endMs: 2_000, speed: -1 }], 44_100),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed: Number.NaN }],
+ 44_100,
+ ),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter([{ startMs: 0, endMs: 2_000, speed: 1 }], 0.4),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter([{ startMs: -100, endMs: 2_000, speed: 1 }], 44_100),
+ ).toBeNull();
+ expect(
+ buildEditedTrackSourceAudioFilter(
+ [{ startMs: 0, endMs: 2_000, speed: Number.MAX_SAFE_INTEGER }],
+ 44_100,
+ ),
+ ).toBeNull();
+ });
+});
+
+describe("native static layout command builders", () => {
+ const baseConfig = {
+ inputPath: "input.mp4",
+ outputPath: "chunk.mp4",
+ width: 1920,
+ height: 1080,
+ frameRate: 60,
+ bitrate: 8_000_000,
+ encodingMode: "fast" as const,
+ contentWidth: 1536,
+ contentHeight: 864,
+ offsetX: 192,
+ offsetY: 108,
+ backgroundColor: "#101010",
+ startSec: 120,
+ durationSec: 60,
+ };
+
+ it("builds the primary CUDA overlay layout command", () => {
+ const args = buildNativeCudaOverlayStaticLayoutArgs(baseConfig);
+
+ expect(args).toContain("-filter_complex");
+ expect(args).toContain(
+ "color=c=0x101010:s=1920x1080:r=60:d=60.000,format=nv12,setrange=limited,hwupload_cuda[bg];" +
+ "[0:v]scale_cuda=w=1536:h=864:format=nv12:passthrough=0,hwdownload,format=nv12,scale=in_range=auto:out_range=tv:sws_dither=bayer,fps=60,hwupload_cuda[fg];" +
+ "[bg][fg]overlay_cuda=192:108:shortest=0:repeatlast=1:eof_action=repeat,trim=duration=60.000,setpts=PTS-STARTPTS[out]",
+ );
+ expect(args).toContain("h264_nvenc");
+ expect(args).toContain("p1");
+ expect(args).not.toContain("yuv420p");
+ expect(args).toEqual(expect.arrayContaining(["-ss", "120.000", "-t", "60.000"]));
+ expect(args).toEqual(expect.arrayContaining([...FFMPEG_BT709_VIDEO_COLOR_ARGS]));
+ });
+
+ it("converts full-range canvas pixels and tags native H.264 as BT.709 video range", () => {
+ const args = buildNativeVideoExportArgs(
+ "h264_videotoolbox",
+ {
+ width: 1920,
+ height: 1080,
+ frameRate: 30,
+ bitrate: 30_000_000,
+ encodingMode: "quality",
+ },
+ "out.mp4",
+ );
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "-vf",
+ "vflip,scale=in_range=full:out_range=tv:sws_dither=bayer",
+ "-colorspace",
+ "bt709",
+ "-color_primaries",
+ "bt709",
+ "-color_trc",
+ "bt709",
+ "-color_range",
+ "tv",
+ ]),
+ );
+ });
+
+ it("builds the stable CUDA scale plus CPU pad fallback command", () => {
+ const args = buildNativeCudaScaleCpuPadStaticLayoutArgs(baseConfig);
+
+ expect(args).toEqual(
+ expect.arrayContaining([
+ "-vf",
+ "scale_cuda=w=1536:h=864:format=nv12:passthrough=0,hwdownload,format=nv12,scale=in_range=auto:out_range=tv:sws_dither=bayer,fps=60,pad=w=1920:h=1080:x=192:y=108:color=0x101010",
+ "-map",
+ "0:v:0",
+ "-an",
+ ]),
+ );
+ expect(args).toEqual(expect.arrayContaining([...FFMPEG_BT709_VIDEO_COLOR_ARGS]));
+ });
+
+ it("sanitizes unsupported background colors to the safe dark fallback", () => {
+ const args = buildNativeCudaScaleCpuPadStaticLayoutArgs({
+ ...baseConfig,
+ backgroundColor: "linear-gradient(red, blue)",
+ });
+
+ expect(args).toContain(
+ "scale_cuda=w=1536:h=864:format=nv12:passthrough=0,hwdownload,format=nv12,scale=in_range=auto:out_range=tv:sws_dither=bayer,fps=60,pad=w=1920:h=1080:x=192:y=108:color=0x101010",
+ );
+ });
+
+ it("builds a precomposited background command for image wallpaper and shadow", () => {
+ const args = buildNativeStaticBackgroundRenderArgs({
+ ...baseConfig,
+ outputPath: "background.png",
+ backgroundImagePath: "wallpaper.jpg",
+ maskPath: "mask.pgm",
+ shadowIntensity: 0.67,
+ });
+ const filterComplex = args[args.indexOf("-filter_complex") + 1];
+
+ expect(args).toEqual(expect.arrayContaining(["-i", "wallpaper.jpg", "-i", "mask.pgm"]));
+ expect(filterComplex).toContain(
+ "scale=w=1920:h=1080:force_original_aspect_ratio=increase,crop=w=1920:h=1080",
+ );
+ expect(filterComplex).toContain("split=3");
+ expect(filterComplex).toContain("gblur=sigma=32.16:steps=2");
+ expect(filterComplex).toContain("overlay=x=119:y=35:format=auto");
+ expect(args).toEqual(expect.arrayContaining(["-frames:v", "1", "background.png"]));
+ });
+
+ it("pre-blurs image wallpapers for native fallback static backgrounds", () => {
+ const args = buildNativeStaticBackgroundRenderArgs({
+ ...baseConfig,
+ outputPath: "background.png",
+ backgroundImagePath: "wallpaper.jpg",
+ backgroundBlurPx: 36,
+ });
+ const filterComplex = args[args.indexOf("-filter_complex") + 1];
+
+ expect(filterComplex).toContain("[bg0]gblur=sigma=36:steps=2[bg_blur]");
+ expect(filterComplex).toContain("[bg_blur]format=rgba[out]");
+ });
+
+ it("builds a precomposited static layout command with a squircle alpha mask", () => {
+ const args = buildNativePrecompositedStaticLayoutArgs({
+ ...baseConfig,
+ staticBackgroundPath: "background.png",
+ maskPath: "mask.pgm",
+ borderRadius: 12.5,
+ });
+ const filterComplex = args[args.indexOf("-filter_complex") + 1];
+
+ expect(args).toEqual(expect.arrayContaining(["-i", "background.png", "-i", "mask.pgm"]));
+ expect(filterComplex).toContain(
+ "scale_cuda=w=1536:h=864:format=nv12:passthrough=0,hwdownload,format=nv12,scale=in_range=auto:out_range=full,fps=60,format=rgba",
+ );
+ expect(filterComplex).toContain("[fgbase][mask]alphamerge[fg]");
+ expect(filterComplex).toContain("overlay=x=192:y=108:format=auto");
+ expect(filterComplex).toContain(
+ "scale=in_range=full:out_range=tv:sws_dither=bayer,format=yuv420p[out]",
+ );
+ expect(args).toContain("h264_nvenc");
+ expect(args).toEqual(expect.arrayContaining(["-pix_fmt", "yuv420p"]));
+ expect(args).toEqual(expect.arrayContaining([...FFMPEG_BT709_VIDEO_COLOR_ARGS]));
+ });
+
+ it("creates an opaque PGM mask for square video corners and a partial mask for radius", () => {
+ const squareMask = createNativeSquircleMaskPgmBuffer(4, 4, 0);
+ expect(squareMask.subarray(squareMask.length - 16)).toEqual(Buffer.alloc(16, 255));
+
+ const roundedMask = createNativeSquircleMaskPgmBuffer(8, 8, 4);
+ const header = Buffer.from("P5\n8 8\n255\n", "ascii");
+ const pixels = roundedMask.subarray(header.length);
+ expect(pixels[0]).toBeLessThan(255);
+ expect(pixels[4 * 8 + 4]).toBe(255);
+ });
+
+ it("splits long exports into bounded chunks", () => {
+ expect(buildNativeStaticLayoutChunks(367.5, 120)).toEqual([
+ { index: 0, startSec: 0, durationSec: 120 },
+ { index: 1, startSec: 120, durationSec: 120 },
+ { index: 2, startSec: 240, durationSec: 120 },
+ { index: 3, startSec: 360, durationSec: 7.5 },
+ ]);
+ });
+
+ it("builds concat args for already encoded chunks", () => {
+ expect(buildNativeConcatArgs({ listPath: "chunks.txt", outputPath: "out.mp4" })).toEqual([
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-f",
+ "concat",
+ "-safe",
+ "0",
+ "-i",
+ "chunks.txt",
+ "-c",
+ "copy",
+ "-movflags",
+ "+faststart",
+ "out.mp4",
+ ]);
+ });
+
+ it("detects CUDA OOM as a retryable fast-path failure", () => {
+ expect(
+ isNativeCudaOutOfMemory(
+ "cu->cuMemAlloc(&data, size) failed -> CUDA_ERROR_OUT_OF_MEMORY: out of memory",
+ ),
+ ).toBe(true);
+ expect(isNativeCudaOutOfMemory("FFmpeg exited with code 1")).toBe(false);
+ });
+});
diff --git a/electron/ipc/nativeVideoExport.ts b/electron/ipc/nativeVideoExport.ts
new file mode 100644
index 000000000..8b9a0fa32
--- /dev/null
+++ b/electron/ipc/nativeVideoExport.ts
@@ -0,0 +1,771 @@
+import {
+ getShadowFilterPadding,
+ VIDEO_SHADOW_LAYER_PROFILES,
+} from "../../src/lib/exporter/shadowProfile";
+import { getSquirclePathPoints } from "../../src/lib/geometry/squircle";
+import { ATEMPO_FILTER_EPSILON, buildAtempoFilters } from "./ffmpeg/filters";
+
+const NATIVE_EXPORT_INPUT_BYTES_PER_PIXEL = 4;
+const MIN_EDITED_TRACK_TEMPO_SPEED = 0.5;
+const MAX_EDITED_TRACK_TEMPO_SPEED = 2;
+
+export const FFMPEG_BT709_VIDEO_COLOR_ARGS = [
+ "-colorspace",
+ "bt709",
+ "-color_primaries",
+ "bt709",
+ "-color_trc",
+ "bt709",
+ "-color_range",
+ "tv",
+] as const;
+
+const FFMPEG_AUTO_TO_VIDEO_RANGE_FILTER = "scale=in_range=auto:out_range=tv:sws_dither=bayer";
+const FFMPEG_AUTO_TO_FULL_RANGE_FILTER = "scale=in_range=auto:out_range=full";
+const FFMPEG_FULL_TO_VIDEO_RANGE_FILTER = "scale=in_range=full:out_range=tv:sws_dither=bayer";
+
+export type NativeExportEncodingMode = "fast" | "balanced" | "quality";
+
+export type NativeVideoExportAudioMode = "none" | "copy-source" | "trim-source" | "edited-track";
+export type NativeVideoExportEditedTrackStrategy =
+ | "filtergraph-fast-path"
+ | "offline-render-fallback";
+
+export interface NativeVideoExportStartOptions {
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: NativeExportEncodingMode;
+ inputMode?: "rawvideo" | "h264-stream";
+}
+
+export interface NativeVideoExportAudioSegment {
+ startMs: number;
+ endMs: number;
+}
+
+export interface NativeVideoExportEditedTrackSegment extends NativeVideoExportAudioSegment {
+ speed: number;
+}
+
+export interface NativeVideoExportFinishOptions {
+ audioMode?: NativeVideoExportAudioMode;
+ audioSourcePath?: string | null;
+ audioSourceCodec?: string | null;
+ audioSourceSampleRate?: number;
+ outputDurationSec?: number;
+ trimSegments?: NativeVideoExportAudioSegment[];
+ editedTrackStrategy?: NativeVideoExportEditedTrackStrategy;
+ editedTrackSegments?: NativeVideoExportEditedTrackSegment[];
+ editedAudioData?: ArrayBuffer;
+ editedAudioMimeType?: string | null;
+}
+
+export interface NativeVideoAudioMuxMetrics {
+ tempVideoWriteMs?: number;
+ tempEditedAudioWriteMs?: number;
+ ffmpegExecMs?: number;
+ muxedVideoReadMs?: number;
+ tempVideoBytes?: number;
+ tempEditedAudioBytes?: number;
+ muxedVideoBytes?: number;
+}
+
+export type NativeStaticLayoutBackend =
+ | "cuda-overlay"
+ | "cuda-scale-cpu-pad"
+ | "cuda-static-composite"
+ | "nvidia-cuda-compositor"
+ | "windows-d3d11-compositor";
+
+export interface NativeStaticLayoutExportArgsConfig {
+ inputPath: string;
+ outputPath: string;
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: NativeExportEncodingMode;
+ contentWidth: number;
+ contentHeight: number;
+ offsetX: number;
+ offsetY: number;
+ sourceCropX?: number;
+ sourceCropY?: number;
+ sourceCropWidth?: number;
+ sourceCropHeight?: number;
+ backgroundColor: string;
+ backgroundImagePath?: string | null;
+ backgroundBlurPx?: number;
+ staticBackgroundPath?: string | null;
+ maskPath?: string | null;
+ borderRadius?: number;
+ shadowIntensity?: number;
+ startSec?: number;
+ durationSec?: number;
+}
+
+export interface NativeStaticLayoutChunk {
+ index: number;
+ startSec: number;
+ durationSec: number;
+}
+
+export function getNativeVideoInputByteSize(width: number, height: number): number {
+ return width * height * NATIVE_EXPORT_INPUT_BYTES_PER_PIXEL;
+}
+
+export function parseAvailableFfmpegEncoders(stdout: string): Set {
+ const encoders = new Set();
+
+ for (const line of stdout.split(/\r?\n/)) {
+ const match = line.match(/^\s*[A-Z.]{6}\s+([a-z0-9_]+)/i);
+ if (match?.[1]) {
+ encoders.add(match[1]);
+ }
+ }
+
+ return encoders;
+}
+
+export function getPreferredNativeVideoEncoders(platform: NodeJS.Platform): string[] {
+ switch (platform) {
+ case "darwin":
+ return ["h264_videotoolbox", "libx264"];
+ case "win32":
+ return ["h264_nvenc", "h264_qsv", "h264_amf", "h264_mf", "libx264"];
+ case "linux":
+ return ["h264_nvenc", "h264_qsv", "libx264"];
+ default:
+ return ["libx264"];
+ }
+}
+
+function getLibx264ModeArgs(encodingMode: NativeExportEncodingMode): string[] {
+ switch (encodingMode) {
+ case "fast":
+ return ["-preset", "ultrafast", "-tune", "zerolatency"];
+ case "quality":
+ return ["-preset", "slow"];
+ case "balanced":
+ default:
+ return ["-preset", "medium"];
+ }
+}
+
+function getBitrateArgs(bitrate: number): string[] {
+ const effectiveBitrate = Math.max(1_500_000, Math.round(bitrate));
+ const maxRate = Math.max(effectiveBitrate, Math.round(effectiveBitrate * 1.2));
+ const bufferSize = Math.max(maxRate * 2, effectiveBitrate * 2);
+
+ return [
+ "-b:v",
+ String(effectiveBitrate),
+ "-maxrate",
+ String(maxRate),
+ "-bufsize",
+ String(bufferSize),
+ ];
+}
+
+function getNvencStaticLayoutModeArgs(encodingMode: NativeExportEncodingMode): string[] {
+ const lowLatencyRateControlArgs = [
+ "-rc",
+ "vbr",
+ "-multipass",
+ "disabled",
+ "-rc-lookahead",
+ "0",
+ "-surfaces",
+ "32",
+ ];
+ switch (encodingMode) {
+ case "quality":
+ return ["-preset", "p1", "-tune", "hq", ...lowLatencyRateControlArgs];
+ case "balanced":
+ return ["-preset", "p1", "-tune", "ll", ...lowLatencyRateControlArgs];
+ case "fast":
+ default:
+ return ["-preset", "p1", "-tune", "ull", ...lowLatencyRateControlArgs];
+ }
+}
+
+function formatFfmpegColor(value: string): string {
+ const trimmed = value.trim();
+ const hex = trimmed.match(/^#?([0-9a-f]{6})$/i)?.[1];
+ return hex ? `0x${hex.toLowerCase()}` : "0x101010";
+}
+
+function clampUnitInterval(value: number): number {
+ if (!Number.isFinite(value)) {
+ return 0;
+ }
+
+ return Math.min(1, Math.max(0, value));
+}
+
+function formatFfmpegNumber(value: number): string {
+ return Number.isInteger(value)
+ ? String(value)
+ : value.toFixed(6).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function isPointInsidePolygon(x: number, y: number, points: Array<{ x: number; y: number }>) {
+ let inside = false;
+ for (
+ let index = 0, previousIndex = points.length - 1;
+ index < points.length;
+ previousIndex = index++
+ ) {
+ const current = points[index];
+ const previous = points[previousIndex];
+ const intersects =
+ current.y > y !== previous.y > y &&
+ x < ((previous.x - current.x) * (y - current.y)) / (previous.y - current.y) + current.x;
+
+ if (intersects) {
+ inside = !inside;
+ }
+ }
+
+ return inside;
+}
+
+export function createNativeSquircleMaskPgmBuffer(
+ width: number,
+ height: number,
+ radius: number,
+): Buffer {
+ const safeWidth = Math.max(1, Math.round(width));
+ const safeHeight = Math.max(1, Math.round(height));
+ const clampedRadius = Math.min(Math.max(0, radius), Math.min(safeWidth, safeHeight) / 2);
+ const header = Buffer.from(`P5\n${safeWidth} ${safeHeight}\n255\n`, "ascii");
+ const pixels = Buffer.alloc(safeWidth * safeHeight, 255);
+
+ if (clampedRadius <= 0.5) {
+ return Buffer.concat([header, pixels]);
+ }
+
+ const points = getSquirclePathPoints({
+ x: 0,
+ y: 0,
+ width: safeWidth,
+ height: safeHeight,
+ radius: clampedRadius,
+ });
+ const samples = [
+ [0.25, 0.25],
+ [0.75, 0.25],
+ [0.25, 0.75],
+ [0.75, 0.75],
+ ] as const;
+
+ for (let y = 0; y < safeHeight; y += 1) {
+ for (let x = 0; x < safeWidth; x += 1) {
+ let coveredSamples = 0;
+ for (const [sampleX, sampleY] of samples) {
+ if (isPointInsidePolygon(x + sampleX, y + sampleY, points)) {
+ coveredSamples += 1;
+ }
+ }
+ pixels[y * safeWidth + x] = Math.round((coveredSamples / samples.length) * 255);
+ }
+ }
+
+ return Buffer.concat([header, pixels]);
+}
+
+function pushFfmpegTimeSliceArgs(
+ args: string[],
+ startSec: number | undefined,
+ durationSec: number | undefined,
+) {
+ if (Number.isFinite(startSec) && (startSec ?? 0) > 0) {
+ args.push("-ss", formatFfmpegSeconds((startSec ?? 0) * 1000));
+ }
+
+ if (Number.isFinite(durationSec) && (durationSec ?? 0) > 0) {
+ args.push("-t", formatFfmpegSeconds((durationSec ?? 0) * 1000));
+ }
+}
+
+export function buildNativeVideoExportArgs(
+ encoder: string,
+ options: NativeVideoExportStartOptions,
+ outputPath: string,
+): string[] {
+ const args = [
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-f",
+ "rawvideo",
+ "-pix_fmt",
+ "rgba",
+ "-s:v",
+ `${options.width}x${options.height}`,
+ "-framerate",
+ String(options.frameRate),
+ "-i",
+ "pipe:0",
+ "-vf",
+ `vflip,${FFMPEG_FULL_TO_VIDEO_RANGE_FILTER}`,
+ "-an",
+ "-c:v",
+ encoder,
+ "-g",
+ String(Math.max(1, Math.round(options.frameRate * 5))),
+ ...getBitrateArgs(options.bitrate),
+ ];
+
+ if (encoder === "libx264") {
+ args.push(...getLibx264ModeArgs(options.encodingMode));
+ }
+
+ args.push(
+ "-pix_fmt",
+ "yuv420p",
+ ...FFMPEG_BT709_VIDEO_COLOR_ARGS,
+ "-movflags",
+ "+faststart",
+ outputPath,
+ );
+ return args;
+}
+
+export function buildNativeCudaOverlayStaticLayoutArgs(
+ config: NativeStaticLayoutExportArgsConfig,
+): string[] {
+ const backgroundColor = formatFfmpegColor(config.backgroundColor);
+ const durationSec = formatFfmpegSeconds(Math.max(0.001, config.durationSec ?? 1) * 1000);
+ const args = ["-y", "-hide_banner", "-loglevel", "error"];
+ pushFfmpegTimeSliceArgs(args, config.startSec, config.durationSec);
+ args.push(
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ config.inputPath,
+ "-filter_complex",
+ `color=c=${backgroundColor}:s=${config.width}x${config.height}:r=${config.frameRate}:d=${durationSec},format=nv12,setrange=limited,hwupload_cuda[bg];[0:v]scale_cuda=w=${config.contentWidth}:h=${config.contentHeight}:format=nv12:passthrough=0,hwdownload,format=nv12,${FFMPEG_AUTO_TO_VIDEO_RANGE_FILTER},fps=${config.frameRate},hwupload_cuda[fg];[bg][fg]overlay_cuda=${config.offsetX}:${config.offsetY}:shortest=0:repeatlast=1:eof_action=repeat,trim=duration=${durationSec},setpts=PTS-STARTPTS[out]`,
+ "-map",
+ "[out]",
+ "-an",
+ "-r",
+ String(config.frameRate),
+ "-c:v",
+ "h264_nvenc",
+ ...getNvencStaticLayoutModeArgs(config.encodingMode),
+ ...getBitrateArgs(config.bitrate),
+ ...FFMPEG_BT709_VIDEO_COLOR_ARGS,
+ "-movflags",
+ "+faststart",
+ config.outputPath,
+ );
+ return args;
+}
+
+export function buildNativeCudaScaleCpuPadStaticLayoutArgs(
+ config: NativeStaticLayoutExportArgsConfig,
+): string[] {
+ const backgroundColor = formatFfmpegColor(config.backgroundColor);
+ const args = ["-y", "-hide_banner", "-loglevel", "error"];
+ pushFfmpegTimeSliceArgs(args, config.startSec, config.durationSec);
+ args.push(
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ config.inputPath,
+ "-vf",
+ `scale_cuda=w=${config.contentWidth}:h=${config.contentHeight}:format=nv12:passthrough=0,hwdownload,format=nv12,${FFMPEG_AUTO_TO_VIDEO_RANGE_FILTER},fps=${config.frameRate},pad=w=${config.width}:h=${config.height}:x=${config.offsetX}:y=${config.offsetY}:color=${backgroundColor}`,
+ "-map",
+ "0:v:0",
+ "-an",
+ "-r",
+ String(config.frameRate),
+ "-c:v",
+ "h264_nvenc",
+ ...getNvencStaticLayoutModeArgs(config.encodingMode),
+ ...getBitrateArgs(config.bitrate),
+ "-pix_fmt",
+ "yuv420p",
+ ...FFMPEG_BT709_VIDEO_COLOR_ARGS,
+ "-movflags",
+ "+faststart",
+ config.outputPath,
+ );
+ return args;
+}
+
+export function buildNativeStaticBackgroundRenderArgs(
+ config: NativeStaticLayoutExportArgsConfig,
+): string[] {
+ const backgroundColor = formatFfmpegColor(config.backgroundColor);
+ const backgroundBlurPx = Math.max(0, config.backgroundBlurPx ?? 0);
+ const args = ["-y", "-hide_banner", "-loglevel", "error"];
+ if (config.backgroundImagePath) {
+ args.push("-i", config.backgroundImagePath);
+ } else {
+ args.push(
+ "-f",
+ "lavfi",
+ "-i",
+ `color=c=${backgroundColor}:s=${config.width}x${config.height}:d=1`,
+ );
+ }
+
+ const shadowStrength = clampUnitInterval(config.shadowIntensity ?? 0);
+ const shadowLayers =
+ shadowStrength > 0 && config.maskPath
+ ? VIDEO_SHADOW_LAYER_PROFILES.map((layer) => ({
+ offsetY: layer.offsetScale * shadowStrength,
+ alpha: clampUnitInterval(layer.alphaScale * shadowStrength),
+ blur: Math.max(0, layer.blurScale * shadowStrength),
+ })).filter((layer) => layer.alpha > 0)
+ : [];
+
+ if (shadowLayers.length > 0 && config.maskPath) {
+ args.push("-i", config.maskPath);
+ }
+
+ const filterParts = [
+ config.backgroundImagePath
+ ? `[0:v]scale=w=${config.width}:h=${config.height}:force_original_aspect_ratio=increase,crop=w=${config.width}:h=${config.height},setsar=1,format=rgba[bg0]`
+ : "[0:v]format=rgba[bg0]",
+ ];
+ let currentBackgroundLabel = "bg0";
+ if (backgroundBlurPx > 0 && config.backgroundImagePath) {
+ filterParts.push(
+ `[${currentBackgroundLabel}]gblur=sigma=${formatFfmpegNumber(
+ Math.min(96, backgroundBlurPx),
+ )}:steps=2[bg_blur]`,
+ );
+ currentBackgroundLabel = "bg_blur";
+ }
+
+ if (shadowLayers.length > 0) {
+ filterParts.push(
+ `[1:v]format=gray,split=${shadowLayers.length}${shadowLayers
+ .map((_, index) => `[shadow_mask_source_${index}]`)
+ .join("")}`,
+ );
+ }
+
+ shadowLayers.forEach((layer, index) => {
+ const padding = getShadowFilterPadding(layer.blur, layer.offsetY);
+ const paddedWidth = config.contentWidth + padding * 2;
+ const paddedHeight = config.contentHeight + padding * 2;
+ const positionedMaskLabel = `shadow_mask_positioned_${index}`;
+ const shadowMaskLabel = `shadow_mask_${index}`;
+ const shadowColorLabel = `shadow_color_${index}`;
+ const shadowLabel = `shadow_${index}`;
+ const nextBackgroundLabel = `bg${index + 1}`;
+ const blurFilter =
+ layer.blur > 0 ? `,gblur=sigma=${formatFfmpegNumber(layer.blur)}:steps=2` : "";
+
+ filterParts.push(
+ `[shadow_mask_source_${index}]lut=y=val*${formatFfmpegNumber(
+ layer.alpha,
+ )},pad=w=${paddedWidth}:h=${paddedHeight}:x=${padding}:y=${Math.round(
+ padding + layer.offsetY,
+ )}:color=black${blurFilter}[${positionedMaskLabel}]`,
+ `[${positionedMaskLabel}]format=gray[${shadowMaskLabel}]`,
+ `color=c=black:s=${paddedWidth}x${paddedHeight}:d=1,format=rgba[${shadowColorLabel}]`,
+ `[${shadowColorLabel}][${shadowMaskLabel}]alphamerge[${shadowLabel}]`,
+ `[${currentBackgroundLabel}][${shadowLabel}]overlay=x=${
+ config.offsetX - padding
+ }:y=${config.offsetY - padding}:format=auto[${nextBackgroundLabel}]`,
+ );
+ currentBackgroundLabel = nextBackgroundLabel;
+ });
+
+ filterParts.push(`[${currentBackgroundLabel}]format=rgba[out]`);
+ args.push(
+ "-filter_complex",
+ filterParts.join(";"),
+ "-map",
+ "[out]",
+ "-frames:v",
+ "1",
+ config.outputPath,
+ );
+ return args;
+}
+
+export function buildNativePrecompositedStaticLayoutArgs(
+ config: NativeStaticLayoutExportArgsConfig,
+): string[] {
+ if (!config.staticBackgroundPath) {
+ throw new Error("Native precomposited static layout requires a static background path");
+ }
+
+ const durationSec = formatFfmpegSeconds(Math.max(0.001, config.durationSec ?? 1) * 1000);
+ const useMask = Boolean(config.maskPath && (config.borderRadius ?? 0) > 0.5);
+ const args = ["-y", "-hide_banner", "-loglevel", "error"];
+ pushFfmpegTimeSliceArgs(args, config.startSec, config.durationSec);
+ args.push(
+ "-hwaccel",
+ "cuda",
+ "-hwaccel_output_format",
+ "cuda",
+ "-i",
+ config.inputPath,
+ "-loop",
+ "1",
+ "-framerate",
+ String(config.frameRate),
+ "-t",
+ durationSec,
+ "-i",
+ config.staticBackgroundPath,
+ );
+
+ if (useMask && config.maskPath) {
+ args.push(
+ "-loop",
+ "1",
+ "-framerate",
+ String(config.frameRate),
+ "-t",
+ durationSec,
+ "-i",
+ config.maskPath,
+ );
+ }
+
+ const foregroundFilter = `[0:v]scale_cuda=w=${config.contentWidth}:h=${config.contentHeight}:format=nv12:passthrough=0,hwdownload,format=nv12,${FFMPEG_AUTO_TO_FULL_RANGE_FILTER},fps=${config.frameRate},format=rgba[fgbase]`;
+ const maskFilter = useMask ? ";[2:v]format=gray[mask];[fgbase][mask]alphamerge[fg]" : "";
+ const foregroundLabel = useMask ? "fg" : "fgbase";
+ const filterComplex = `${foregroundFilter}${maskFilter};[1:v]format=rgba[bg];[bg][${foregroundLabel}]overlay=x=${config.offsetX}:y=${config.offsetY}:format=auto,trim=duration=${durationSec},setpts=PTS-STARTPTS,${FFMPEG_FULL_TO_VIDEO_RANGE_FILTER},format=yuv420p[out]`;
+
+ args.push(
+ "-filter_complex",
+ filterComplex,
+ "-map",
+ "[out]",
+ "-an",
+ "-r",
+ String(config.frameRate),
+ "-c:v",
+ "h264_nvenc",
+ ...getNvencStaticLayoutModeArgs(config.encodingMode),
+ ...getBitrateArgs(config.bitrate),
+ "-pix_fmt",
+ "yuv420p",
+ ...FFMPEG_BT709_VIDEO_COLOR_ARGS,
+ "-movflags",
+ "+faststart",
+ config.outputPath,
+ );
+ return args;
+}
+
+export function buildNativeConcatArgs(config: { listPath: string; outputPath: string }): string[] {
+ return [
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ "-f",
+ "concat",
+ "-safe",
+ "0",
+ "-i",
+ config.listPath,
+ "-c",
+ "copy",
+ "-movflags",
+ "+faststart",
+ config.outputPath,
+ ];
+}
+
+export function buildNativeStaticLayoutChunks(
+ durationSec: number,
+ chunkDurationSec: number,
+): NativeStaticLayoutChunk[] {
+ if (!Number.isFinite(durationSec) || durationSec <= 0) {
+ return [];
+ }
+
+ const safeChunkDuration = Math.max(1, Math.min(300, Math.floor(chunkDurationSec)));
+ const chunks: NativeStaticLayoutChunk[] = [];
+ for (
+ let startSec = 0, index = 0;
+ startSec < durationSec;
+ startSec += safeChunkDuration, index++
+ ) {
+ chunks.push({
+ index,
+ startSec,
+ durationSec: Math.min(safeChunkDuration, durationSec - startSec),
+ });
+ }
+
+ return chunks;
+}
+
+export function isNativeCudaOutOfMemory(stderr: string): boolean {
+ return /CUDA_ERROR_OUT_OF_MEMORY|cuMemAlloc.+out of memory/i.test(stderr);
+}
+
+function formatFfmpegSeconds(milliseconds: number): string {
+ return (milliseconds / 1000).toFixed(3);
+}
+
+export function buildTrimmedSourceAudioFilter(
+ segments: NativeVideoExportAudioSegment[],
+): string | null {
+ if (segments.length === 0) {
+ return null;
+ }
+
+ const filterParts: string[] = [];
+ const segmentLabels: string[] = [];
+
+ segments.forEach((segment, index) => {
+ const label = `trimmed_audio_${index}`;
+ filterParts.push(
+ `[1:a]atrim=start=${formatFfmpegSeconds(segment.startMs)}:end=${formatFfmpegSeconds(segment.endMs)},asetpts=PTS-STARTPTS[${label}]`,
+ );
+ segmentLabels.push(`[${label}]`);
+ });
+
+ if (segmentLabels.length === 1) {
+ filterParts.push(`${segmentLabels[0]}anull[aout]`);
+ } else {
+ filterParts.push(`${segmentLabels.join("")}concat=n=${segmentLabels.length}:v=0:a=1[aout]`);
+ }
+
+ return filterParts.join(";");
+}
+
+export function buildEditedTrackSourceAudioFilter(
+ segments: NativeVideoExportEditedTrackSegment[],
+ sourceSampleRate: number,
+): string | null {
+ if (segments.length === 0 || !Number.isFinite(sourceSampleRate) || sourceSampleRate <= 0) {
+ return null;
+ }
+
+ const normalizedSourceSampleRate = Math.round(sourceSampleRate);
+ if (normalizedSourceSampleRate < 1) {
+ return null;
+ }
+
+ const filterParts: string[] = [];
+ const segmentLabels: string[] = [];
+ let hasInvalidSegment = false;
+
+ segments.forEach((segment, index) => {
+ if (
+ !Number.isFinite(segment.startMs) ||
+ !Number.isFinite(segment.endMs) ||
+ segment.startMs < 0 ||
+ segment.endMs < 0
+ ) {
+ hasInvalidSegment = true;
+ return;
+ }
+
+ if (segment.endMs - segment.startMs <= 0.5) {
+ hasInvalidSegment = true;
+ return;
+ }
+
+ const label = `edited_audio_${index}`;
+ const speed = segment.speed;
+ if (
+ !Number.isFinite(speed) ||
+ speed < MIN_EDITED_TRACK_TEMPO_SPEED ||
+ speed > MAX_EDITED_TRACK_TEMPO_SPEED
+ ) {
+ hasInvalidSegment = true;
+ return;
+ }
+
+ const segmentFilter = [
+ `[1:a]atrim=start=${formatFfmpegSeconds(segment.startMs)}:end=${formatFfmpegSeconds(segment.endMs)}`,
+ "asetpts=PTS-STARTPTS",
+ ];
+
+ const tempoFilters = buildAtempoFilters(speed);
+ if (tempoFilters.length > 0) {
+ segmentFilter.push(...tempoFilters);
+ } else if (Math.abs(speed - 1) > ATEMPO_FILTER_EPSILON) {
+ hasInvalidSegment = true;
+ return;
+ }
+
+ filterParts.push(`${segmentFilter.join(",")}[${label}]`);
+ segmentLabels.push(`[${label}]`);
+ });
+
+ if (hasInvalidSegment || segmentLabels.length === 0) {
+ return null;
+ }
+
+ if (segmentLabels.length === 1) {
+ filterParts.push(`${segmentLabels[0]}anull[aout]`);
+ } else {
+ filterParts.push(`${segmentLabels.join("")}concat=n=${segmentLabels.length}:v=0:a=1[aout]`);
+ }
+
+ return filterParts.join(";");
+}
+
+/**
+ * Builds FFmpeg arguments for a zero-copy H.264 stream export.
+ * FFmpeg receives a pre-encoded Annex B H.264 stream on stdin (produced by the
+ * browser's hardware VideoEncoder) and copies it straight into an MP4 container
+ * — no re-encoding step, no raw pixel IPC traffic.
+ */
+export function buildNativeH264StreamExportArgs(config: {
+ frameRate: number;
+ outputPath: string;
+}): string[] {
+ return [
+ "-y",
+ "-hide_banner",
+ "-loglevel",
+ "error",
+ // Input 0: pre-encoded H.264 Annex B stream from browser VideoEncoder via stdin
+ "-f",
+ "h264",
+ "-r",
+ String(config.frameRate),
+ "-i",
+ "pipe:0",
+ "-an", // audio handled separately by muxNativeVideoExportAudio
+ "-c:v",
+ "copy",
+ "-movflags",
+ "+faststart",
+ config.outputPath,
+ ];
+}
+
+export function getEditedAudioExtension(mimeType?: string | null): string {
+ if (!mimeType) {
+ return ".webm";
+ }
+
+ if (mimeType.includes("wav")) {
+ return ".wav";
+ }
+
+ if (mimeType.includes("mp4") || mimeType.includes("m4a")) {
+ return ".m4a";
+ }
+
+ if (mimeType.includes("ogg")) {
+ return ".ogg";
+ }
+
+ return ".webm";
+}
diff --git a/electron/ipc/paths/binaries.test.ts b/electron/ipc/paths/binaries.test.ts
new file mode 100644
index 000000000..361861739
--- /dev/null
+++ b/electron/ipc/paths/binaries.test.ts
@@ -0,0 +1,83 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("Windows native helper path resolution", () => {
+ let tempRoot: string;
+ let appPath: string;
+
+ beforeEach(async () => {
+ tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-helper-paths-"));
+ appPath = path.join(tempRoot, "App");
+ await fs.mkdir(appPath, { recursive: true });
+
+ vi.resetModules();
+ vi.doMock("electron", () => ({
+ app: {
+ isPackaged: false,
+ getAppPath: () => appPath,
+ },
+ }));
+ });
+
+ afterEach(async () => {
+ vi.resetModules();
+ vi.doUnmock("electron");
+ await fs.rm(tempRoot, { recursive: true, force: true });
+ });
+
+ it("resolves a requested platform tag independently of the host platform", async () => {
+ const { getNativeArchTag } = await import("./binaries");
+
+ expect(getNativeArchTag("win32")).toBe(
+ process.arch === "arm64" ? "win32-arm64" : "win32-x64",
+ );
+ });
+
+ it("prefers the branch-staged helper over a stale local CMake build in dev", async () => {
+ const buildOutputPath = path.join(
+ appPath,
+ "electron",
+ "native",
+ "wgc-capture",
+ "build",
+ "Release",
+ "wgc-capture.exe",
+ );
+ const prebundledPath = path.join(
+ appPath,
+ "electron",
+ "native",
+ "bin",
+ process.arch === "arm64" ? "win32-arm64" : "win32-x64",
+ "wgc-capture.exe",
+ );
+ await fs.mkdir(path.dirname(buildOutputPath), { recursive: true });
+ await fs.mkdir(path.dirname(prebundledPath), { recursive: true });
+ await fs.writeFile(buildOutputPath, "old-local-build");
+ await fs.writeFile(prebundledPath, "branch-staged-helper");
+
+ const { getWindowsCaptureExePath } = await import("./binaries");
+
+ expect(getWindowsCaptureExePath()).toBe(prebundledPath);
+ });
+
+ it("falls back to the local CMake build when no staged helper exists", async () => {
+ const buildOutputPath = path.join(
+ appPath,
+ "electron",
+ "native",
+ "wgc-capture",
+ "build",
+ "Release",
+ "wgc-capture.exe",
+ );
+ await fs.mkdir(path.dirname(buildOutputPath), { recursive: true });
+ await fs.writeFile(buildOutputPath, "local-build");
+
+ const { getWindowsCaptureExePath } = await import("./binaries");
+
+ expect(getWindowsCaptureExePath()).toBe(buildOutputPath);
+ });
+});
diff --git a/electron/ipc/paths/binaries.ts b/electron/ipc/paths/binaries.ts
new file mode 100644
index 000000000..04bc577c5
--- /dev/null
+++ b/electron/ipc/paths/binaries.ts
@@ -0,0 +1,263 @@
+import { execFile } from "node:child_process";
+import { existsSync, constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { app } from "electron";
+import { nativeHelperMigrationPromise, setNativeHelperMigrationPromise } from "../state";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve a path within the app bundle, handling asar unpacking in production.
+ * Files listed in asarUnpack are extracted to app.asar.unpacked/ and must be
+ * accessed via that path instead of the asar virtual filesystem.
+ */
+export function resolveUnpackedAppPath(...segments: string[]): string {
+ const base = app.getAppPath();
+ const resolved = path.join(base, ...segments);
+ if (app.isPackaged) {
+ return resolved.replace(/\.asar([/\\])/, ".asar.unpacked$1");
+ }
+ return resolved;
+}
+
+export function getNativeCaptureHelperSourcePath(): string {
+ return resolveUnpackedAppPath("electron", "native", "ScreenCaptureKitRecorder.swift");
+}
+
+export function getNativeArchTag(platform: NodeJS.Platform = process.platform): string {
+ if (platform === "darwin") {
+ return process.arch === "arm64" ? "darwin-arm64" : "darwin-x64";
+ }
+
+ if (platform === "win32") {
+ return process.arch === "arm64" ? "win32-arm64" : "win32-x64";
+ }
+
+ if (platform === "linux") {
+ return process.arch === "arm64" ? "linux-arm64" : "linux-x64";
+ }
+
+ return `${platform}-${process.arch}`;
+}
+
+export function getPrebundledNativeHelperPath(
+ binaryName: string,
+ archTag = getNativeArchTag(),
+): string {
+ return resolveUnpackedAppPath("electron", "native", "bin", archTag, binaryName);
+}
+
+export function resolvePreferredWindowsNativeHelperPath(
+ helperDirectory: string,
+ binaryName: string,
+): string {
+ const buildOutputPath = resolveUnpackedAppPath(
+ "electron",
+ "native",
+ helperDirectory,
+ "build",
+ "Release",
+ binaryName,
+ );
+ const prebundledPath = getPrebundledNativeHelperPath(binaryName, getNativeArchTag("win32"));
+
+ if (app.isPackaged && existsSync(prebundledPath)) {
+ return prebundledPath;
+ }
+
+ // Source checkouts should run the helper staged in the branch instead of a
+ // stale local CMake build left over from an earlier test run.
+ if (existsSync(prebundledPath)) {
+ return prebundledPath;
+ }
+
+ if (existsSync(buildOutputPath)) {
+ return buildOutputPath;
+ }
+
+ return buildOutputPath;
+}
+
+export function getBundledWhisperExecutableCandidates(): string[] {
+ const binaryNames =
+ process.platform === "win32"
+ ? ["whisper-cli.exe", "whisper-cpp.exe", "whisper.exe", "main.exe"]
+ : ["whisper-cli", "whisper-cpp", "whisper", "main"];
+
+ return binaryNames.map((binaryName) => getPrebundledNativeHelperPath(binaryName));
+}
+
+export function getNativeCaptureHelperBinaryPath(): string {
+ return path.join(app.getPath("userData"), "native-tools", "recordly-screencapturekit-helper");
+}
+
+export function getSystemCursorHelperSourcePath(): string {
+ return resolveUnpackedAppPath("electron", "native", "SystemCursorAssets.swift");
+}
+
+export function getSystemCursorHelperBinaryPath(): string {
+ return path.join(app.getPath("userData"), "native-tools", "recordly-system-cursors");
+}
+
+export function getNativeCursorMonitorSourcePath(): string {
+ return resolveUnpackedAppPath("electron", "native", "NativeCursorMonitor.swift");
+}
+
+export function getNativeCursorMonitorBinaryPath(): string {
+ return path.join(app.getPath("userData"), "native-tools", "recordly-native-cursor-monitor");
+}
+
+export function getNativeWindowListSourcePath(): string {
+ return resolveUnpackedAppPath("electron", "native", "ScreenCaptureKitWindowList.swift");
+}
+
+export function getNativeWindowListBinaryPath(): string {
+ return path.join(app.getPath("userData"), "native-tools", "recordly-window-list");
+}
+
+export function getWindowsCaptureExePath(): string {
+ return resolvePreferredWindowsNativeHelperPath("wgc-capture", "wgc-capture.exe");
+}
+
+export function getCursorMonitorExePath(): string {
+ return resolvePreferredWindowsNativeHelperPath("cursor-monitor", "cursor-monitor.exe");
+}
+
+async function migrateLegacyNativeHelperBinaries(): Promise {
+ const legacyToCurrentPaths: Array<[string, string]> = [
+ [
+ path.join(
+ app.getPath("userData"),
+ "native-tools",
+ "openscreen-screencapturekit-helper",
+ ),
+ getNativeCaptureHelperBinaryPath(),
+ ],
+ [
+ path.join(app.getPath("userData"), "native-tools", "openscreen-window-list"),
+ getNativeWindowListBinaryPath(),
+ ],
+ [
+ path.join(app.getPath("userData"), "native-tools", "openscreen-system-cursors"),
+ getSystemCursorHelperBinaryPath(),
+ ],
+ [
+ path.join(app.getPath("userData"), "native-tools", "openscreen-native-cursor-monitor"),
+ getNativeCursorMonitorBinaryPath(),
+ ],
+ ];
+
+ for (const [legacyPath, currentPath] of legacyToCurrentPaths) {
+ if (legacyPath === currentPath || existsSync(currentPath) || !existsSync(legacyPath)) {
+ continue;
+ }
+
+ try {
+ await fs.mkdir(path.dirname(currentPath), { recursive: true });
+ await fs.rename(legacyPath, currentPath);
+ } catch (error) {
+ console.warn("[native-tools] Failed to migrate helper binary", {
+ legacyPath,
+ currentPath,
+ error,
+ });
+ }
+ }
+}
+
+export async function ensureNativeHelperMigration(): Promise {
+ if (!nativeHelperMigrationPromise) {
+ setNativeHelperMigrationPromise(
+ migrateLegacyNativeHelperBinaries().catch((error) => {
+ setNativeHelperMigrationPromise(null);
+ throw error;
+ }),
+ );
+ }
+
+ return nativeHelperMigrationPromise!;
+}
+
+export async function ensureSwiftHelperBinary(
+ sourcePath: string,
+ binaryPath: string,
+ label: string,
+ prebundledBinaryName?: string,
+): Promise {
+ if (prebundledBinaryName) {
+ const prebundledPath = getPrebundledNativeHelperPath(prebundledBinaryName);
+ try {
+ await fs.access(prebundledPath, fsConstants.X_OK);
+ return prebundledPath;
+ } catch {
+ if (app.isPackaged) {
+ throw new Error(
+ `${label} is missing from this app build (${prebundledPath}). Reinstall or update the app.`,
+ );
+ }
+ }
+ }
+
+ const helperDir = path.dirname(binaryPath);
+ await fs.mkdir(helperDir, { recursive: true });
+
+ let shouldCompile = false;
+ try {
+ const [sourceStat, binaryStat] = await Promise.all([
+ fs.stat(sourcePath),
+ fs.stat(binaryPath).catch(() => null),
+ ]);
+ shouldCompile = !binaryStat || sourceStat.mtimeMs > binaryStat.mtimeMs;
+ } catch (error) {
+ throw new Error(`${label} source is unavailable: ${String(error)}`);
+ }
+
+ if (!shouldCompile) {
+ return binaryPath;
+ }
+
+ try {
+ await execFileAsync("swiftc", ["-O", sourcePath, "-o", binaryPath], {
+ encoding: "utf8",
+ timeout: 120000,
+ });
+ } catch (error) {
+ const err = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
+ const details = [err.stderr, err.stdout].filter(Boolean).join("\n").trim();
+ throw new Error(details || `Failed to compile ${label}`);
+ }
+
+ return binaryPath;
+}
+
+export async function ensureNativeCaptureHelperBinary(): Promise {
+ await ensureNativeHelperMigration();
+ return ensureSwiftHelperBinary(
+ getNativeCaptureHelperSourcePath(),
+ getNativeCaptureHelperBinaryPath(),
+ "native ScreenCaptureKit helper",
+ "recordly-screencapturekit-helper",
+ );
+}
+
+export async function ensureNativeWindowListBinary(): Promise {
+ await ensureNativeHelperMigration();
+ return ensureSwiftHelperBinary(
+ getNativeWindowListSourcePath(),
+ getNativeWindowListBinaryPath(),
+ "native ScreenCaptureKit window list helper",
+ "recordly-window-list",
+ );
+}
+
+export async function ensureNativeCursorMonitorBinary(): Promise {
+ await ensureNativeHelperMigration();
+ return ensureSwiftHelperBinary(
+ getNativeCursorMonitorSourcePath(),
+ getNativeCursorMonitorBinaryPath(),
+ "native cursor monitor helper",
+ "recordly-native-cursor-monitor",
+ );
+}
diff --git a/electron/ipc/project/atomicSave.test.ts b/electron/ipc/project/atomicSave.test.ts
new file mode 100644
index 000000000..34646af34
--- /dev/null
+++ b/electron/ipc/project/atomicSave.test.ts
@@ -0,0 +1,112 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { getProjectBackupPath, writeProjectFileAtomically } from "./atomicSave";
+
+describe("writeProjectFileAtomically", () => {
+ let tempDir: string;
+ let projectPath: string;
+
+ beforeEach(async () => {
+ tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-atomic-project-"));
+ projectPath = path.join(tempDir, "demo.recordly");
+ });
+
+ afterEach(async () => {
+ await fs.rm(tempDir, { recursive: true, force: true });
+ });
+
+ async function expectNoTemporaryArtifacts() {
+ const entries = await fs.readdir(tempDir);
+ expect(entries.filter((entry) => entry.endsWith(".tmp"))).toEqual([]);
+ }
+
+ it("commits a complete new project without creating a backup", async () => {
+ await writeProjectFileAtomically(projectPath, '{"version":1}');
+
+ await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1}');
+ await expect(fs.access(getProjectBackupPath(projectPath))).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ await expectNoTemporaryArtifacts();
+ await expectNoTemporaryArtifacts();
+ });
+
+ it("removes a stale backup when the target has no previous generation", async () => {
+ await fs.writeFile(getProjectBackupPath(projectPath), "stale-project");
+
+ await writeProjectFileAtomically(projectPath, '{"version":1}');
+
+ await expect(fs.access(getProjectBackupPath(projectPath))).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ });
+
+ it("preserves the previous complete generation before replacement", async () => {
+ await writeProjectFileAtomically(projectPath, '{"version":1,"name":"old"}');
+ await writeProjectFileAtomically(projectPath, '{"version":1,"name":"new"}');
+
+ await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1,"name":"new"}');
+ await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+ '{"version":1,"name":"old"}',
+ );
+ await expectNoTemporaryArtifacts();
+ });
+
+ it("keeps the active generation unchanged when backup commit fails", async () => {
+ await writeProjectFileAtomically(projectPath, '{"version":1,"name":"old"}');
+ await fs.mkdir(getProjectBackupPath(projectPath));
+
+ await expect(
+ writeProjectFileAtomically(projectPath, '{"version":1,"name":"new"}'),
+ ).rejects.toBeDefined();
+
+ await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"version":1,"name":"old"}');
+ await expectNoTemporaryArtifacts();
+
+ await fs.rm(getProjectBackupPath(projectPath), { recursive: true });
+ await writeProjectFileAtomically(projectPath, '{"version":1,"name":"retry"}');
+ await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe(
+ '{"version":1,"name":"retry"}',
+ );
+ await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+ '{"version":1,"name":"old"}',
+ );
+ await expectNoTemporaryArtifacts();
+ });
+
+ it("serializes overlapping writes to the same project", async () => {
+ await writeProjectFileAtomically(projectPath, '{"revision":1}');
+
+ // Each call enters the queue synchronously before its first await, preserving invocation order.
+ await Promise.all([
+ writeProjectFileAtomically(projectPath, '{"revision":2}'),
+ writeProjectFileAtomically(projectPath, '{"revision":3}'),
+ ]);
+
+ await expect(fs.readFile(projectPath, "utf-8")).resolves.toBe('{"revision":3}');
+ await expect(fs.readFile(getProjectBackupPath(projectPath), "utf-8")).resolves.toBe(
+ '{"revision":2}',
+ );
+ await expectNoTemporaryArtifacts();
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "preserves exact project permission bits despite the process umask",
+ async () => {
+ await fs.writeFile(projectPath, '{"revision":1}', { mode: 0o666 });
+ await fs.chmod(projectPath, 0o666);
+ const previousUmask = process.umask(0o077);
+
+ try {
+ await writeProjectFileAtomically(projectPath, '{"revision":2}');
+ } finally {
+ process.umask(previousUmask);
+ }
+
+ expect((await fs.stat(projectPath)).mode & 0o777).toBe(0o666);
+ },
+ );
+});
diff --git a/electron/ipc/project/atomicSave.ts b/electron/ipc/project/atomicSave.ts
new file mode 100644
index 000000000..d2440ffe5
--- /dev/null
+++ b/electron/ipc/project/atomicSave.ts
@@ -0,0 +1,146 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const pendingWrites = new Map>();
+
+const unsupportedDirectorySyncErrors = new Set([
+ "EACCES",
+ "EINVAL",
+ "EISDIR",
+ "ENOSYS",
+ "ENOTSUP",
+ "EOPNOTSUPP",
+ "EPERM",
+]);
+
+export function getProjectBackupPath(projectPath: string): string {
+ return `${projectPath}.bak`;
+}
+
+function getQueueKey(projectPath: string): string {
+ const resolvedPath = path.resolve(projectPath);
+ return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+}
+
+function createTemporaryPath(parentDir: string, label: string): string {
+ return path.join(parentDir, `.recordly-${label}-${process.pid}-${randomUUID()}.tmp`);
+}
+
+async function getExistingFileMode(filePath: string): Promise {
+ try {
+ return (await fs.stat(filePath)).mode & 0o777;
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ return undefined;
+ }
+ throw error;
+ }
+}
+
+async function writeSyncedTemporaryFile(
+ filePath: string,
+ contents: string,
+ mode?: number,
+): Promise {
+ const handle = await fs.open(filePath, "wx", mode);
+ try {
+ await handle.writeFile(contents, "utf-8");
+ if (mode !== undefined) {
+ await handle.chmod(mode);
+ }
+ await handle.sync();
+ } finally {
+ await handle.close();
+ }
+}
+
+async function syncExistingFile(filePath: string): Promise {
+ const handle = await fs.open(filePath, "r+");
+ try {
+ await handle.sync();
+ } finally {
+ await handle.close();
+ }
+}
+
+async function syncParentDirectory(parentDir: string): Promise {
+ if (process.platform === "win32") {
+ return;
+ }
+
+ try {
+ const handle = await fs.open(parentDir, "r");
+ try {
+ await handle.sync();
+ } finally {
+ await handle.close();
+ }
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (!code || !unsupportedDirectorySyncErrors.has(code)) {
+ throw error;
+ }
+ }
+}
+
+async function preservePreviousGeneration(
+ targetPath: string,
+ backupPath: string,
+ backupTemporaryPath: string,
+): Promise {
+ try {
+ await fs.copyFile(targetPath, backupTemporaryPath, fsConstants.COPYFILE_EXCL);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+ await fs.rm(backupPath, { force: true });
+ return;
+ }
+ throw error;
+ }
+
+ await syncExistingFile(backupTemporaryPath);
+ await fs.rename(backupTemporaryPath, backupPath);
+}
+
+async function commitProjectFile(projectPath: string, contents: string): Promise {
+ const targetPath = path.resolve(projectPath);
+ const parentDir = path.dirname(targetPath);
+ const backupPath = getProjectBackupPath(targetPath);
+ const temporaryPath = createTemporaryPath(parentDir, "project");
+ const backupTemporaryPath = createTemporaryPath(parentDir, "backup");
+ const existingMode = await getExistingFileMode(targetPath);
+
+ try {
+ await writeSyncedTemporaryFile(temporaryPath, contents, existingMode);
+ await preservePreviousGeneration(targetPath, backupPath, backupTemporaryPath);
+ await fs.rename(temporaryPath, targetPath);
+ await syncParentDirectory(parentDir);
+ } finally {
+ await Promise.all([
+ fs.rm(temporaryPath, { force: true }).catch(() => undefined),
+ fs.rm(backupTemporaryPath, { force: true }).catch(() => undefined),
+ ]);
+ }
+}
+
+export async function writeProjectFileAtomically(
+ projectPath: string,
+ contents: string,
+): Promise {
+ const queueKey = getQueueKey(projectPath);
+ const previousWrite = pendingWrites.get(queueKey) ?? Promise.resolve();
+ const currentWrite = previousWrite
+ .catch(() => undefined)
+ .then(() => commitProjectFile(projectPath, contents));
+ pendingWrites.set(queueKey, currentWrite);
+
+ try {
+ await currentWrite;
+ } finally {
+ if (pendingWrites.get(queueKey) === currentWrite) {
+ pendingWrites.delete(queueKey);
+ }
+ }
+}
diff --git a/electron/ipc/project/manager.test.ts b/electron/ipc/project/manager.test.ts
new file mode 100644
index 000000000..508730924
--- /dev/null
+++ b/electron/ipc/project/manager.test.ts
@@ -0,0 +1,232 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("local media path policy", () => {
+ let tempRoot: string;
+ let appDataPath: string;
+ let userDataPath: string;
+ let tempPath: string;
+ let appPath: string;
+
+ beforeEach(async () => {
+ tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-media-policy-"));
+ appDataPath = path.join(tempRoot, "AppData");
+ userDataPath = path.join(tempRoot, "UserData");
+ tempPath = path.join(tempRoot, "Temp");
+ appPath = path.join(tempRoot, "App");
+
+ await Promise.all(
+ [appDataPath, userDataPath, tempPath, appPath].map((dirPath) =>
+ fs.mkdir(dirPath, { recursive: true }),
+ ),
+ );
+
+ vi.resetModules();
+ vi.doMock("electron", () => ({
+ app: {
+ isPackaged: false,
+ getAppPath: () => appPath,
+ getPath: (name: string) => {
+ if (name === "appData") return appDataPath;
+ if (name === "userData") return userDataPath;
+ if (name === "temp") return tempPath;
+ return tempRoot;
+ },
+ setPath: () => undefined,
+ },
+ }));
+ });
+
+ afterEach(async () => {
+ vi.resetModules();
+ vi.doUnmock("electron");
+ if (tempRoot) {
+ await fs.rm(tempRoot, { recursive: true, force: true });
+ }
+ });
+
+ it("rejects existing media files outside allowed directories until they are approved", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const exportPath = path.join(downloadsPath, "export-test.mp4");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(exportPath, "test-video");
+
+ const { isAllowedLocalMediaPath, rememberApprovedLocalReadPath } = await import(
+ "./manager"
+ );
+
+ await expect(isAllowedLocalMediaPath(exportPath)).resolves.toBe(false);
+
+ await rememberApprovedLocalReadPath(exportPath);
+
+ await expect(isAllowedLocalMediaPath(exportPath)).resolves.toBe(true);
+ });
+
+ it("rejects missing media files outside the allowed directories", async () => {
+ const missingPath = path.join(tempRoot, "Downloads", "missing.mp4");
+ const { isAllowedLocalMediaPath } = await import("./manager");
+
+ await expect(isAllowedLocalMediaPath(missingPath)).resolves.toBe(false);
+ });
+
+ it("allows approved media paths before the file exists", async () => {
+ const pendingExportPath = path.join(tempRoot, "Downloads", "pending-export.mp4");
+ const { isAllowedLocalMediaPath, rememberApprovedLocalReadPath } = await import(
+ "./manager"
+ );
+
+ await rememberApprovedLocalReadPath(pendingExportPath);
+
+ await expect(isAllowedLocalMediaPath(pendingExportPath)).resolves.toBe(true);
+ });
+
+ it("approves media-server access for approved external files resolved through the URL policy", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const videoPath = path.join(downloadsPath, "external-video.mp4");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(videoPath, "test-video");
+ const resolvedVideoPath = await fs.realpath(videoPath);
+
+ const { resolveApprovedLocalMediaPath, rememberApprovedLocalReadPath } = await import(
+ "./manager"
+ );
+ const { isAllowedMediaPath } = await import("../../mediaServer");
+
+ // Unapproved external paths are rejected before they ever reach the media server.
+ expect(isAllowedMediaPath(videoPath)).toBe(false);
+ await expect(resolveApprovedLocalMediaPath(videoPath)).resolves.toBeNull();
+
+ // Once the user opts in (via dialog/export/etc.) the path is approved.
+ await rememberApprovedLocalReadPath(videoPath);
+
+ await expect(resolveApprovedLocalMediaPath(videoPath)).resolves.toBe(resolvedVideoPath);
+ expect(isAllowedMediaPath(videoPath)).toBe(true);
+ });
+
+ it("rejects existing non-media files when resolving local media URLs", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const textPath = path.join(downloadsPath, "notes.txt");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(textPath, "not media");
+
+ const { resolveApprovedLocalMediaPath } = await import("./manager");
+ const { isAllowedMediaPath } = await import("../../mediaServer");
+
+ await expect(resolveApprovedLocalMediaPath(textPath)).resolves.toBeNull();
+ expect(isAllowedMediaPath(textPath)).toBe(false);
+ });
+
+ it("rejects symlinks under allowed prefixes that point outside the allowlist", async () => {
+ const outsideTarget = path.join(tempRoot, "outside-secret.mp4");
+ const symlinkInsideUserData = path.join(userDataPath, "shortcut-to-secret.mp4");
+ await fs.writeFile(outsideTarget, "secret-bytes");
+
+ try {
+ await fs.symlink(outsideTarget, symlinkInsideUserData);
+ } catch (error) {
+ // Windows requires Developer Mode or admin to create file symlinks. If
+ // we can't create one, the bypass we're guarding against also can't be
+ // crafted on this machine, so skipping is safe.
+ if ((error as NodeJS.ErrnoException).code === "EPERM") {
+ return;
+ }
+ throw error;
+ }
+
+ const { isAllowedLocalMediaPath, resolveApprovedLocalMediaPath } = await import(
+ "./manager"
+ );
+
+ await expect(isAllowedLocalMediaPath(symlinkInsideUserData)).resolves.toBe(false);
+ await expect(resolveApprovedLocalMediaPath(symlinkInsideUserData)).resolves.toBeNull();
+ });
+
+ it("preserves an existing project thumbnail when no replacement is provided", async () => {
+ const projectPath = path.join(tempRoot, "Projects", "demo.recordly");
+ const thumbnailDataUrl = `data:image/png;base64,${Buffer.from("png-thumbnail").toString("base64")}`;
+ await fs.mkdir(path.dirname(projectPath), { recursive: true });
+
+ const { getProjectThumbnailPath, saveProjectThumbnail } = await import("./manager");
+ const thumbnailPath = getProjectThumbnailPath(projectPath);
+
+ await saveProjectThumbnail(projectPath, thumbnailDataUrl);
+ await saveProjectThumbnail(projectPath, undefined);
+
+ await expect(fs.readFile(thumbnailPath, "utf8")).resolves.toBe("png-thumbnail");
+ });
+
+ it("loads project files that start with a UTF-8 byte order mark", async () => {
+ const videoPath = path.join(tempPath, "recording.mp4");
+ const projectPath = path.join(tempPath, "recording.recordly");
+ await fs.writeFile(videoPath, "test-video");
+ await fs.writeFile(
+ projectPath,
+ `\uFEFF${JSON.stringify({
+ version: 1,
+ videoPath,
+ editor: {},
+ })}`,
+ "utf-8",
+ );
+
+ const { loadProjectFromPath } = await import("./manager");
+
+ const result = await loadProjectFromPath(projectPath);
+ expect(result.success).toBe(true);
+ expect(result.path).toBe(projectPath);
+ expect(result.project).toMatchObject({ videoPath });
+ });
+
+ it("rejects invalid project payloads before approving media paths", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const videoPath = path.join(downloadsPath, "recording.mp4");
+ const projectPath = path.join(tempPath, "invalid.recordly");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(videoPath, "test-video");
+ await fs.writeFile(
+ projectPath,
+ JSON.stringify({
+ videoPath,
+ editor: {},
+ }),
+ "utf-8",
+ );
+
+ const { loadProjectFromPath, resolveApprovedLocalMediaPath } = await import("./manager");
+
+ const result = await loadProjectFromPath(projectPath);
+ expect(result.success).toBe(false);
+ expect(result.message).toBe("Invalid project file format");
+ await expect(resolveApprovedLocalMediaPath(videoPath)).resolves.toBeNull();
+ });
+
+ it("approves editor audioRegions audioPath entries when loading a project", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const videoPath = path.join(tempPath, "recording.mp4");
+ const audioPath = path.join(downloadsPath, "music.ogg");
+ const projectPath = path.join(tempPath, "recording.recordly");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(videoPath, "test-video");
+ await fs.writeFile(audioPath, "test-audio");
+ await fs.writeFile(
+ projectPath,
+ JSON.stringify({
+ version: 1,
+ videoPath,
+ editor: {
+ audioRegions: [{ id: "a1", startMs: 0, endMs: 1000, audioPath, volume: 1 }],
+ },
+ }),
+ "utf-8",
+ );
+
+ const { loadProjectFromPath, resolveApprovedLocalMediaPath } = await import("./manager");
+ const resolvedAudioPath = await fs.realpath(audioPath);
+
+ const result = await loadProjectFromPath(projectPath);
+ expect(result.success).toBe(true);
+ await expect(resolveApprovedLocalMediaPath(audioPath)).resolves.toBe(resolvedAudioPath);
+ });
+});
diff --git a/electron/ipc/project/manager.ts b/electron/ipc/project/manager.ts
new file mode 100644
index 000000000..7828fa8b6
--- /dev/null
+++ b/electron/ipc/project/manager.ts
@@ -0,0 +1,501 @@
+import { existsSync, constants as fsConstants, realpathSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { app } from "electron";
+import { RECORDINGS_DIR, USER_DATA_PATH } from "../../appPaths";
+import { isSupportedLocalMediaPath } from "../../mediaTypes";
+import {
+ LEGACY_PROJECT_FILE_EXTENSIONS,
+ MAX_RECENT_PROJECTS,
+ PROJECT_FILE_EXTENSION,
+ PROJECT_THUMBNAIL_SUFFIX,
+ PROJECTS_DIRECTORY_NAME,
+ RECENT_PROJECTS_FILE,
+ RECORDINGS_SETTINGS_FILE,
+} from "../constants";
+import {
+ approvedLocalReadPaths,
+ currentProjectPath,
+ setCurrentProjectPath,
+ setCurrentRecordingSession,
+ setCurrentVideoPath,
+ setCustomRecordingsDir,
+ setRecordingsDirLoaded,
+} from "../state";
+import type { ProjectLibraryEntry, RecordingSessionData } from "../types";
+import {
+ getRecordingsDir,
+ normalizePath,
+ normalizeVideoSourcePath,
+ parseJsonWithByteOrderMark,
+} from "../utils";
+
+export { normalizePath, normalizeVideoSourcePath };
+
+export function getAssetRootPath() {
+ if (app.isPackaged) {
+ return path.join(process.resourcesPath, "assets");
+ }
+
+ return path.join(app.getAppPath(), "public");
+}
+
+export function isPathInsideDirectory(candidatePath: string, directoryPath: string) {
+ const normalizedCandidatePath = normalizePath(candidatePath);
+ const normalizedDirectoryPath = normalizePath(directoryPath);
+ return (
+ normalizedCandidatePath === normalizedDirectoryPath ||
+ normalizedCandidatePath.startsWith(`${normalizedDirectoryPath}${path.sep}`)
+ );
+}
+
+export function isAllowedLocalReadPath(candidatePath: string) {
+ const allowedPrefixes = [
+ RECORDINGS_DIR,
+ USER_DATA_PATH,
+ getAssetRootPath(),
+ app.getPath("temp"),
+ ];
+ const normalizedCandidatePath = normalizePath(candidatePath);
+
+ // Canonicalize so a symlink placed under an allowed prefix can't smuggle in a
+ // target that lives outside it. realpathSync throws when the path doesn't
+ // exist yet (e.g. a pending export approved before the file is written) — in
+ // that case fall back to the lexical path, which can only succeed via the
+ // approvedLocalReadPaths check below since no symlink target exists yet.
+ let canonicalCandidatePath = normalizedCandidatePath;
+ try {
+ canonicalCandidatePath = normalizePath(realpathSync(normalizedCandidatePath));
+ } catch {
+ // File may not exist yet; keep the lexical path.
+ }
+
+ // Security: only allow paths under app-managed directories or paths the user
+ // has explicitly opted into (recording session sources, files chosen via
+ // dialog, app-produced exports). The lexical path must satisfy the policy
+ // AND the canonical (real) path must satisfy it too, so a symlink under an
+ // allowed prefix that points outside the allowlist is rejected. Previously
+ // this returned true for any existing file, which made the allowlist a no-op
+ // for read-local-file and the local media URL handler.
+ const lexicalAllowed =
+ allowedPrefixes.some((prefix) => isPathInsideDirectory(normalizedCandidatePath, prefix)) ||
+ approvedLocalReadPaths.has(normalizedCandidatePath);
+ if (!lexicalAllowed) {
+ return false;
+ }
+
+ if (canonicalCandidatePath === normalizedCandidatePath) {
+ return true;
+ }
+
+ return (
+ allowedPrefixes.some((prefix) => isPathInsideDirectory(canonicalCandidatePath, prefix)) ||
+ approvedLocalReadPaths.has(canonicalCandidatePath)
+ );
+}
+
+// Keep loopback media-server access restricted to allowlisted or explicitly
+// approved files. Direct renderer-side read-local-file calls can be more
+// permissive, but URL-based serving must stay scoped so arbitrary paths do not
+// become fetchable inside the app.
+export async function isAllowedLocalMediaPath(candidatePath: string) {
+ const normalizedCandidatePath = normalizePath(candidatePath);
+ return isAllowedLocalReadPath(normalizedCandidatePath);
+}
+
+async function collectApprovedLocalReadPaths(filePath?: string | null): Promise {
+ const normalizedPath = normalizeVideoSourcePath(filePath);
+ if (!normalizedPath) {
+ return [];
+ }
+
+ const approvedPaths = [normalizePath(normalizedPath)];
+
+ try {
+ const realPath = await fs.realpath(approvedPaths[0]);
+ const normalizedRealPath = normalizePath(realPath);
+ if (!approvedPaths.includes(normalizedRealPath)) {
+ approvedPaths.push(normalizedRealPath);
+ }
+ } catch {
+ // Ignore missing files; the eventual read will surface the real error.
+ }
+
+ return approvedPaths;
+}
+
+export async function rememberApprovedLocalReadPath(filePath?: string | null) {
+ const normalizedPath = normalizeVideoSourcePath(filePath);
+ if (!normalizedPath) {
+ return;
+ }
+
+ const approvedPaths = await collectApprovedLocalReadPaths(normalizedPath);
+ for (const approvedPath of approvedPaths) {
+ approvedLocalReadPaths.add(approvedPath);
+ }
+}
+
+export async function resolveApprovedLocalMediaPath(candidatePath: string): Promise {
+ const normalizedCandidatePath = normalizePath(candidatePath);
+ const realPath = await fs.realpath(normalizedCandidatePath).catch(() => null);
+
+ if (!realPath) {
+ return null;
+ }
+
+ const stat = await fs.stat(realPath).catch(() => null);
+ if (!stat?.isFile() || !isSupportedLocalMediaPath(realPath)) {
+ return null;
+ }
+
+ if (!(await isAllowedLocalMediaPath(realPath))) {
+ return null;
+ }
+
+ await rememberApprovedLocalReadPath(candidatePath);
+ return realPath;
+}
+
+export async function replaceApprovedSessionLocalReadPaths(
+ filePaths: Array,
+) {
+ const nextApprovedPaths = new Set();
+ const approvedPathLists = await Promise.all(
+ filePaths.map((filePath) => collectApprovedLocalReadPaths(filePath)),
+ );
+
+ for (const approvedPathList of approvedPathLists) {
+ for (const approvedPath of approvedPathList) {
+ nextApprovedPaths.add(approvedPath);
+ }
+ }
+
+ approvedLocalReadPaths.clear();
+ for (const approvedPath of nextApprovedPaths) {
+ approvedLocalReadPaths.add(approvedPath);
+ }
+}
+
+export async function resolveProjectMediaSources(
+ project: unknown,
+): Promise<
+ | { success: true; videoPath: string; webcamPath: string | null }
+ | { success: false; message: string }
+> {
+ if (!project || typeof project !== "object") {
+ return { success: false, message: "Invalid project file format" };
+ }
+
+ const rawVideoPath = (project as { videoPath?: unknown }).videoPath;
+ if (typeof rawVideoPath !== "string") {
+ return { success: false, message: "Project file is missing a video path" };
+ }
+
+ const normalizedVideoPath = normalizeVideoSourcePath(rawVideoPath);
+ if (!normalizedVideoPath) {
+ return { success: false, message: "Project file is missing a valid video path" };
+ }
+
+ try {
+ await fs.access(normalizedVideoPath, fsConstants.F_OK);
+ } catch {
+ return {
+ success: false,
+ message: `Project video file not found: ${normalizedVideoPath}`,
+ };
+ }
+
+ const rawWebcamPath =
+ typeof (project as { editor?: { webcam?: { sourcePath?: unknown } } }).editor?.webcam
+ ?.sourcePath === "string"
+ ? ((project as { editor?: { webcam?: { sourcePath?: string } } }).editor?.webcam
+ ?.sourcePath ?? null)
+ : null;
+ const normalizedWebcamPath = normalizeVideoSourcePath(rawWebcamPath);
+
+ if (!normalizedWebcamPath) {
+ return {
+ success: true,
+ videoPath: normalizedVideoPath,
+ webcamPath: null,
+ };
+ }
+
+ try {
+ await fs.access(normalizedWebcamPath, fsConstants.F_OK);
+ return {
+ success: true,
+ videoPath: normalizedVideoPath,
+ webcamPath: normalizedWebcamPath,
+ };
+ } catch {
+ return {
+ success: true,
+ videoPath: normalizedVideoPath,
+ webcamPath: null,
+ };
+ }
+}
+
+export async function getProjectsDir() {
+ const projectsDir = path.join(await getRecordingsDir(), PROJECTS_DIRECTORY_NAME);
+ await fs.mkdir(projectsDir, { recursive: true });
+ return projectsDir;
+}
+
+export async function persistRecordingsDirectorySetting(nextDir: string) {
+ setCustomRecordingsDir(path.resolve(nextDir));
+ setRecordingsDirLoaded(true);
+ await fs.writeFile(
+ RECORDINGS_SETTINGS_FILE,
+ JSON.stringify({ recordingsDir: path.resolve(nextDir) }, null, 2),
+ "utf-8",
+ );
+}
+
+export function hasProjectFileExtension(filePath: string) {
+ const extension = path.extname(filePath).replace(/^\./, "").toLowerCase();
+ return [PROJECT_FILE_EXTENSION, ...LEGACY_PROJECT_FILE_EXTENSIONS].includes(extension);
+}
+
+export function getProjectThumbnailPath(projectPath: string) {
+ return `${projectPath}${PROJECT_THUMBNAIL_SUFFIX}`;
+}
+
+export async function saveProjectThumbnail(projectPath: string, thumbnailDataUrl?: string | null) {
+ const thumbnailPath = getProjectThumbnailPath(projectPath);
+ if (thumbnailDataUrl === undefined) {
+ return existsSync(thumbnailPath) ? thumbnailPath : null;
+ }
+
+ if (!thumbnailDataUrl) {
+ await fs.rm(thumbnailPath, { force: true }).catch(() => undefined);
+ return null;
+ }
+
+ const match = thumbnailDataUrl.match(/^data:image\/png;base64,(.+)$/);
+ if (!match) {
+ throw new Error("Project thumbnail must be a PNG data URL.");
+ }
+
+ await fs.writeFile(thumbnailPath, Buffer.from(match[1], "base64"));
+ return thumbnailPath;
+}
+
+export async function loadRecentProjectPaths() {
+ try {
+ const content = await fs.readFile(RECENT_PROJECTS_FILE, "utf-8");
+ const parsed = parseJsonWithByteOrderMark<{ paths?: unknown }>(content);
+ return Array.isArray(parsed.paths)
+ ? parsed.paths.filter(
+ (value): value is string =>
+ typeof value === "string" && value.trim().length > 0,
+ )
+ : [];
+ } catch {
+ return [];
+ }
+}
+
+export async function saveRecentProjectPaths(paths: string[]) {
+ const normalizedPaths = Array.from(new Set(paths.map((value) => normalizePath(value)))).slice(
+ 0,
+ MAX_RECENT_PROJECTS,
+ );
+ await fs.writeFile(
+ RECENT_PROJECTS_FILE,
+ JSON.stringify({ paths: normalizedPaths }, null, 2),
+ "utf-8",
+ );
+}
+
+export async function rememberRecentProject(projectPath: string) {
+ if (!hasProjectFileExtension(projectPath)) {
+ return;
+ }
+
+ const existingPaths = await loadRecentProjectPaths();
+ await saveRecentProjectPaths([projectPath, ...existingPaths]);
+}
+
+export async function buildProjectLibraryEntry(
+ projectPath: string,
+ projectsDir: string,
+): Promise {
+ try {
+ const normalizedPath = normalizePath(projectPath);
+ if (!hasProjectFileExtension(normalizedPath)) {
+ return null;
+ }
+
+ const stats = await fs.stat(normalizedPath);
+ if (!stats.isFile()) {
+ return null;
+ }
+
+ const thumbnailPath = getProjectThumbnailPath(normalizedPath);
+ const thumbnailExists = await fs
+ .access(thumbnailPath, fsConstants.R_OK)
+ .then(() => true)
+ .catch(() => false);
+
+ return {
+ path: normalizedPath,
+ name: path
+ .basename(normalizedPath)
+ .replace(
+ new RegExp(
+ `\\.(${[PROJECT_FILE_EXTENSION, ...LEGACY_PROJECT_FILE_EXTENSIONS].join("|")})$`,
+ "i",
+ ),
+ "",
+ ),
+ updatedAt: stats.mtimeMs,
+ thumbnailPath: thumbnailExists ? thumbnailPath : null,
+ isCurrent: Boolean(
+ currentProjectPath && normalizePath(currentProjectPath) === normalizedPath,
+ ),
+ isInProjectsDirectory: path.dirname(normalizedPath) === normalizePath(projectsDir),
+ };
+ } catch {
+ return null;
+ }
+}
+
+export async function listProjectLibraryEntries() {
+ const projectsDir = await getProjectsDir();
+ const projectPaths: string[] = [];
+
+ try {
+ const entries = await fs.readdir(projectsDir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isFile()) {
+ continue;
+ }
+
+ const entryPath = path.join(projectsDir, entry.name);
+ if (hasProjectFileExtension(entryPath)) {
+ projectPaths.push(entryPath);
+ }
+ }
+ } catch {
+ // Ignore directory read failures and fall back to recent files.
+ }
+
+ const recentProjectPaths = await loadRecentProjectPaths();
+ const candidatePaths = Array.from(new Set([...projectPaths, ...recentProjectPaths]));
+ const entries = (
+ await Promise.all(
+ candidatePaths.map((candidatePath) =>
+ buildProjectLibraryEntry(candidatePath, projectsDir),
+ ),
+ )
+ )
+ .filter((entry): entry is ProjectLibraryEntry => entry != null)
+ .sort((left, right) => right.updatedAt - left.updatedAt);
+
+ await saveRecentProjectPaths(entries.map((entry) => entry.path));
+
+ return {
+ projectsDir,
+ entries,
+ };
+}
+
+function isLoadableProjectData(projectData: unknown) {
+ if (!projectData || typeof projectData !== "object" || Array.isArray(projectData)) {
+ return false;
+ }
+
+ const candidate = projectData as {
+ version?: unknown;
+ projectId?: unknown;
+ videoPath?: unknown;
+ editor?: unknown;
+ };
+
+ return (
+ typeof candidate.version === "number" &&
+ (candidate.projectId === undefined || typeof candidate.projectId === "string") &&
+ typeof candidate.videoPath === "string" &&
+ candidate.videoPath.trim().length > 0 &&
+ candidate.editor != null &&
+ typeof candidate.editor === "object" &&
+ !Array.isArray(candidate.editor)
+ );
+}
+
+export async function loadProjectFromPath(projectPath: string) {
+ const normalizedPath = normalizePath(projectPath);
+ let project: unknown;
+ try {
+ const content = await fs.readFile(normalizedPath, "utf-8");
+ project = parseJsonWithByteOrderMark(content);
+ } catch (error) {
+ return {
+ success: false,
+ canceled: false,
+ message: `Failed to read project file: ${error instanceof Error ? error.message : String(error)}`,
+ };
+ }
+ if (!isLoadableProjectData(project)) {
+ return {
+ success: false,
+ canceled: false,
+ message: "Invalid project file format",
+ };
+ }
+ const mediaSources = await resolveProjectMediaSources(project);
+
+ if (!mediaSources.success) {
+ return {
+ success: false,
+ canceled: false,
+ message: mediaSources.message,
+ };
+ }
+ const projectObj = project as Record;
+ const editorObj = projectObj?.editor as Record | undefined;
+ const audioTracks = editorObj?.audioTracks as { sourcePath?: unknown }[] | undefined;
+ const audioRegions = editorObj?.audioRegions as { audioPath?: unknown }[] | undefined;
+ const approvedProjectPaths: Array = [
+ mediaSources.videoPath,
+ mediaSources.webcamPath,
+ ];
+ if (Array.isArray(audioTracks)) {
+ for (const track of audioTracks) {
+ if (typeof track?.sourcePath === "string") {
+ approvedProjectPaths.push(track.sourcePath);
+ }
+ }
+ }
+ if (Array.isArray(audioRegions)) {
+ for (const region of audioRegions) {
+ if (typeof region?.audioPath === "string") {
+ approvedProjectPaths.push(region.audioPath);
+ }
+ }
+ }
+ await replaceApprovedSessionLocalReadPaths(approvedProjectPaths);
+ await rememberRecentProject(normalizedPath);
+
+ setCurrentProjectPath(normalizedPath);
+ setCurrentVideoPath(mediaSources.videoPath);
+ setCurrentRecordingSession({
+ videoPath: mediaSources.videoPath,
+ webcamPath: mediaSources.webcamPath,
+ timeOffsetMs: 0,
+ } as RecordingSessionData);
+
+ return {
+ success: true,
+ path: normalizedPath,
+ project,
+ };
+}
+
+export function isTrustedProjectPath(filePath?: string | null): boolean {
+ if (!filePath || !currentProjectPath) return false;
+ return normalizePath(filePath) === normalizePath(currentProjectPath);
+}
diff --git a/electron/ipc/project/session.ts b/electron/ipc/project/session.ts
new file mode 100644
index 000000000..d5f83a839
--- /dev/null
+++ b/electron/ipc/project/session.ts
@@ -0,0 +1,141 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RECORDING_SESSION_MANIFEST_SUFFIX } from "../constants";
+import type { RecordingSessionData, RecordingSessionManifest } from "../types";
+import { normalizeVideoSourcePath, parseJsonWithByteOrderMark } from "../utils";
+
+function normalizeRecordingTimeOffsetMs(value: unknown): number {
+ return typeof value === "number" && Number.isFinite(value) ? Math.round(value) : 0;
+}
+
+export function getRecordingSessionManifestPath(videoPath: string) {
+ const extension = path.extname(videoPath);
+ const baseName = path.basename(videoPath, extension);
+ return path.join(path.dirname(videoPath), `${baseName}${RECORDING_SESSION_MANIFEST_SUFFIX}`);
+}
+
+export async function persistRecordingSessionManifest(
+ session: RecordingSessionData,
+): Promise {
+ const normalizedVideoPath = normalizeVideoSourcePath(session.videoPath);
+ if (!normalizedVideoPath) {
+ return;
+ }
+
+ const normalizedWebcamPath = normalizeVideoSourcePath(session.webcamPath ?? null);
+ const manifestPath = getRecordingSessionManifestPath(normalizedVideoPath);
+
+ if (!normalizedWebcamPath) {
+ await fs.rm(manifestPath, { force: true });
+ return;
+ }
+
+ const manifest: RecordingSessionManifest = {
+ version: 2,
+ videoFileName: path.basename(normalizedVideoPath),
+ webcamFileName: path.basename(normalizedWebcamPath),
+ timeOffsetMs: normalizeRecordingTimeOffsetMs(session.timeOffsetMs),
+ };
+
+ await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+}
+
+export async function resolveRecordingSessionManifest(
+ videoPath?: string | null,
+): Promise {
+ const normalizedVideoPath = normalizeVideoSourcePath(videoPath);
+ if (!normalizedVideoPath) {
+ return null;
+ }
+
+ const manifestPath = getRecordingSessionManifestPath(normalizedVideoPath);
+
+ try {
+ const content = await fs.readFile(manifestPath, "utf-8");
+ const parsed = parseJsonWithByteOrderMark>(content);
+ if (parsed.version !== 1 && parsed.version !== 2) {
+ return null;
+ }
+
+ const webcamFileName =
+ typeof parsed.webcamFileName === "string" && parsed.webcamFileName.trim()
+ ? parsed.webcamFileName.trim()
+ : null;
+
+ if (!webcamFileName) {
+ return {
+ videoPath: normalizedVideoPath,
+ webcamPath: null,
+ timeOffsetMs: normalizeRecordingTimeOffsetMs(parsed.timeOffsetMs),
+ };
+ }
+
+ const webcamPath = path.join(path.dirname(normalizedVideoPath), webcamFileName);
+ const webcamExists = await fs
+ .access(webcamPath, fsConstants.F_OK)
+ .then(() => true)
+ .catch(() => false);
+
+ return {
+ videoPath: normalizedVideoPath,
+ webcamPath: webcamExists ? webcamPath : null,
+ timeOffsetMs: normalizeRecordingTimeOffsetMs(parsed.timeOffsetMs),
+ };
+ } catch {
+ return null;
+ }
+}
+
+export async function resolveLinkedWebcamPath(videoPath?: string | null): Promise {
+ const normalizedVideoPath = normalizeVideoSourcePath(videoPath);
+ if (!normalizedVideoPath) {
+ return null;
+ }
+
+ const extension = path.extname(normalizedVideoPath);
+ const baseName = path.basename(normalizedVideoPath, extension);
+ if (!baseName || baseName.endsWith("-webcam")) {
+ return null;
+ }
+
+ const candidateExtensions = Array.from(
+ new Set([extension, ".webm", ".mp4", ".mov", ".mkv", ".avi"].filter(Boolean)),
+ );
+
+ for (const candidateExtension of candidateExtensions) {
+ const candidatePath = path.join(
+ path.dirname(normalizedVideoPath),
+ `${baseName}-webcam${candidateExtension}`,
+ );
+
+ try {
+ await fs.access(candidatePath, fsConstants.F_OK);
+ return candidatePath;
+ } catch {
+ continue;
+ }
+ }
+
+ return null;
+}
+
+export async function resolveRecordingSession(
+ videoPath?: string | null,
+): Promise {
+ const manifestSession = await resolveRecordingSessionManifest(videoPath);
+ if (manifestSession) {
+ return manifestSession;
+ }
+
+ const normalizedVideoPath = normalizeVideoSourcePath(videoPath);
+ if (!normalizedVideoPath) {
+ return null;
+ }
+
+ const linkedWebcamPath = await resolveLinkedWebcamPath(normalizedVideoPath);
+ return {
+ videoPath: normalizedVideoPath,
+ webcamPath: linkedWebcamPath,
+ };
+}
diff --git a/electron/ipc/recording/audioFilters.test.ts b/electron/ipc/recording/audioFilters.test.ts
new file mode 100644
index 000000000..1e80e2665
--- /dev/null
+++ b/electron/ipc/recording/audioFilters.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ BROWSER_MIC_SIDECAR_FILTERS,
+ BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS,
+ getBrowserMicSidecarFilters,
+ RECORDING_AUDIO_SIDECAR_DEBUG_ENV,
+ shouldKeepRecordingAudioSidecars,
+ WINDOWS_NATIVE_MIC_PRE_FILTERS,
+} from "./audioFilters";
+
+describe("Windows native mic pre-filter policy", () => {
+ it("keeps repair filters without automatic gain or loudness normalization", () => {
+ expect(WINDOWS_NATIVE_MIC_PRE_FILTERS).toContain("adeclip=threshold=1");
+ expect(
+ WINDOWS_NATIVE_MIC_PRE_FILTERS.some((filter) =>
+ /(^|,)(loudnorm|dynaudnorm|volume)=/i.test(filter),
+ ),
+ ).toBe(false);
+ });
+
+ it("keeps native audio sidecars only when explicitly requested", () => {
+ expect(shouldKeepRecordingAudioSidecars({})).toBe(false);
+ expect(
+ shouldKeepRecordingAudioSidecars({
+ [RECORDING_AUDIO_SIDECAR_DEBUG_ENV]: "1",
+ }),
+ ).toBe(true);
+ expect(
+ shouldKeepRecordingAudioSidecars({
+ [RECORDING_AUDIO_SIDECAR_DEBUG_ENV]: "true",
+ }),
+ ).toBe(true);
+ expect(
+ shouldKeepRecordingAudioSidecars({
+ [RECORDING_AUDIO_SIDECAR_DEBUG_ENV]: "off",
+ }),
+ ).toBe(false);
+ });
+});
+
+describe("browser microphone sidecar post-processing", () => {
+ it("keeps the browser fallback chain conservative and speech-oriented", () => {
+ expect(BROWSER_MIC_SIDECAR_FILTERS).toEqual([
+ "adeclip=threshold=1",
+ "adeclick=w=40:o=75:t=3:b=2",
+ "highpass=f=85",
+ "lowpass=f=9500",
+ "afftdn=nr=10:nf=-45:tn=1",
+ "alimiter=limit=0.92:level=0",
+ ]);
+ expect(
+ BROWSER_MIC_SIDECAR_FILTERS.some((filter) =>
+ /(^|,)(loudnorm|dynaudnorm|volume)=/i.test(filter),
+ ),
+ ).toBe(false);
+ });
+
+ it("adds bounded speech gain only for the no-AGC browser mic profile", () => {
+ expect(getBrowserMicSidecarFilters("processed")).toEqual(BROWSER_MIC_SIDECAR_FILTERS);
+ expect(getBrowserMicSidecarFilters("no-agc")).toEqual([
+ "adeclip=threshold=1",
+ "adeclick=w=40:o=75:t=3:b=2",
+ "highpass=f=85",
+ "lowpass=f=9500",
+ "afftdn=nr=10:nf=-45:tn=1",
+ ...BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS,
+ ]);
+ expect(BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS).toContain(
+ "speechnorm=p=0.92:e=12:c=2:r=0.0005:f=0.001",
+ );
+ expect(BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS).toContain("alimiter=limit=0.92:level=0");
+ });
+});
diff --git a/electron/ipc/recording/audioFilters.ts b/electron/ipc/recording/audioFilters.ts
new file mode 100644
index 000000000..b465f5f20
--- /dev/null
+++ b/electron/ipc/recording/audioFilters.ts
@@ -0,0 +1,40 @@
+// Keep native mic capture dry by default. Automatic loudness normalization
+// amplified wireless-headset noise and WASAPI discontinuities during beta tests.
+export const WINDOWS_NATIVE_MIC_PRE_FILTERS = ["adeclip=threshold=1"];
+
+// Browser mic fallback uses Chromium/WebRTC voice processing, but beta tests
+// showed its realtime AGC can introduce short crackle bursts on some Realtek
+// and headset paths. Default to no AGC, then restore usable level offline with
+// bounded speech expansion and a limiter.
+export const BROWSER_MIC_SIDECAR_BASE_FILTERS = [
+ "adeclip=threshold=1",
+ "adeclick=w=40:o=75:t=3:b=2",
+ "highpass=f=85",
+ "lowpass=f=9500",
+ "afftdn=nr=10:nf=-45:tn=1",
+];
+
+export const BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS = [
+ "speechnorm=p=0.92:e=12:c=2:r=0.0005:f=0.001",
+ "alimiter=limit=0.92:level=0",
+];
+
+export const BROWSER_MIC_SIDECAR_FILTERS = [
+ ...BROWSER_MIC_SIDECAR_BASE_FILTERS,
+ "alimiter=limit=0.92:level=0",
+];
+
+export function getBrowserMicSidecarFilters(profile?: string | null) {
+ if (profile === "no-agc") {
+ return [...BROWSER_MIC_SIDECAR_BASE_FILTERS, ...BROWSER_MIC_SIDECAR_NO_AGC_GAIN_FILTERS];
+ }
+
+ return BROWSER_MIC_SIDECAR_FILTERS;
+}
+
+export const RECORDING_AUDIO_SIDECAR_DEBUG_ENV = "RECORDLY_KEEP_RECORDING_AUDIO_SIDECARS"; // not used yet, because we need to have seperate audio files for system and mic for each recording
+
+export function shouldKeepRecordingAudioSidecars(env: NodeJS.ProcessEnv = process.env) {
+ const value = env[RECORDING_AUDIO_SIDECAR_DEBUG_ENV]?.trim().toLowerCase();
+ return value === "1" || value === "true" || value === "yes" || value === "on";
+}
diff --git a/electron/ipc/recording/diagnostics.test.ts b/electron/ipc/recording/diagnostics.test.ts
new file mode 100644
index 000000000..9f7ddeb08
--- /dev/null
+++ b/electron/ipc/recording/diagnostics.test.ts
@@ -0,0 +1,410 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type ExecFileCallback = (error: Error | null, stdout?: string, stderr?: string) => void;
+
+describe("getCompanionAudioFallbackPaths", () => {
+ let tempRoot: string;
+ let appDataPath: string;
+ let userDataPath: string;
+ let tempPath: string;
+ let appPath: string;
+ let execFileMock: ReturnType;
+
+ beforeEach(async () => {
+ tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-companion-audio-"));
+ appDataPath = path.join(tempRoot, "AppData");
+ userDataPath = path.join(tempRoot, "UserData");
+ tempPath = path.join(tempRoot, "Temp");
+ appPath = path.join(tempRoot, "App");
+ await Promise.all(
+ [appDataPath, userDataPath, tempPath, appPath].map((dirPath) =>
+ fs.mkdir(dirPath, { recursive: true }),
+ ),
+ );
+ execFileMock = vi.fn(
+ (
+ _file: string,
+ _args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ callback(null, "", "");
+ },
+ );
+
+ vi.resetModules();
+ vi.doMock("electron", () => ({
+ app: {
+ isPackaged: false,
+ getAppPath: () => appPath,
+ getPath: (name: string) => {
+ if (name === "appData") return appDataPath;
+ if (name === "userData") return userDataPath;
+ if (name === "temp") return tempPath;
+ return tempRoot;
+ },
+ setPath: () => undefined,
+ },
+ }));
+ vi.doMock("node:child_process", () => ({
+ execFile: execFileMock,
+ }));
+ vi.doMock("../ffmpeg/binary", () => ({
+ getFfmpegBinaryPath: () => "ffmpeg",
+ getFfprobeBinaryPath: () => "ffprobe",
+ }));
+ });
+
+ afterEach(async () => {
+ vi.resetModules();
+ vi.doUnmock("electron");
+ vi.doUnmock("node:child_process");
+ vi.doUnmock("../ffmpeg/binary");
+ if (tempRoot) {
+ await fs.rm(tempRoot, { recursive: true, force: true });
+ }
+ });
+
+ it("returns companion audio files directly when the video has no embedded audio", async () => {
+ const videoPath = path.join(tempRoot, "recording.mp4");
+ const systemPath = path.join(tempRoot, "recording.system.wav");
+ const micPath = path.join(tempRoot, "recording.mic.wav");
+
+ await Promise.all([
+ fs.writeFile(videoPath, "video"),
+ fs.writeFile(systemPath, "system"),
+ fs.writeFile(micPath, "mic"),
+ ]);
+
+ execFileMock.mockImplementation(
+ (
+ _file: string,
+ _args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ const error = new Error("ffmpeg probe failed") as Error & { stderr?: string };
+ error.stderr = "Stream #0:0: Video: h264";
+ callback(error, "", error.stderr);
+ },
+ );
+
+ const { getCompanionAudioFallbackPaths } = await import("./diagnostics");
+
+ await expect(getCompanionAudioFallbackPaths(videoPath)).resolves.toEqual([
+ systemPath,
+ micPath,
+ ]);
+ });
+
+ it("keeps the embedded source audio and adds the mic companion when both are present", async () => {
+ const videoPath = path.join(tempRoot, "recording.mp4");
+ const systemPath = path.join(tempRoot, "recording.system.wav");
+ const micPath = path.join(tempRoot, "recording.mic.wav");
+
+ await Promise.all([
+ fs.writeFile(videoPath, "video"),
+ fs.writeFile(systemPath, "system"),
+ fs.writeFile(micPath, "mic"),
+ ]);
+
+ execFileMock.mockImplementation(
+ (
+ _file: string,
+ _args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ const error = new Error("ffmpeg probe found embedded audio") as Error & {
+ stderr?: string;
+ };
+ error.stderr = "Stream #0:1: Audio: aac";
+ callback(error, "", error.stderr);
+ },
+ );
+
+ const { getCompanionAudioFallbackPaths } = await import("./diagnostics");
+
+ await expect(getCompanionAudioFallbackPaths(videoPath)).resolves.toEqual([
+ videoPath,
+ micPath,
+ ]);
+ });
+
+ it("prefers the mac mic companion alone when embedded audio already exists and no system sidecar is present", async () => {
+ const videoPath = path.join(tempRoot, "recording.mp4");
+ const micPath = path.join(tempRoot, "recording.mic.m4a");
+
+ await Promise.all([fs.writeFile(videoPath, "video"), fs.writeFile(micPath, "mic")]);
+
+ execFileMock.mockImplementation(
+ (
+ _file: string,
+ _args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ const error = new Error("ffmpeg probe found embedded audio") as Error & {
+ stderr?: string;
+ };
+ error.stderr = "Stream #0:1: Audio: aac";
+ callback(error, "", error.stderr);
+ },
+ );
+
+ const { getCompanionAudioFallbackPaths } = await import("./diagnostics");
+
+ await expect(getCompanionAudioFallbackPaths(videoPath)).resolves.toEqual([micPath]);
+ });
+
+ it("loads saved sidecar timing metadata alongside companion audio paths", async () => {
+ const videoPath = path.join(tempRoot, "recording.mp4");
+ const micPath = path.join(tempRoot, "recording.mic.webm");
+
+ await Promise.all([
+ fs.writeFile(videoPath, "video"),
+ fs.writeFile(micPath, "mic"),
+ fs.writeFile(`${micPath}.json`, `\ufeff${JSON.stringify({ startDelayMs: 2750 })}`),
+ ]);
+
+ execFileMock.mockImplementation(
+ (
+ _file: string,
+ _args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ const error = new Error("ffmpeg probe failed") as Error & { stderr?: string };
+ error.stderr = "Stream #0:0: Video: h264";
+ callback(error, "", error.stderr);
+ },
+ );
+
+ const { getCompanionAudioFallbackInfo } = await import("./diagnostics");
+
+ await expect(getCompanionAudioFallbackInfo(videoPath)).resolves.toEqual({
+ paths: [micPath],
+ startDelayMsByPath: {
+ [micPath]: 2750,
+ },
+ });
+ });
+
+ it("scales audio mux timeout for long recordings", async () => {
+ const { getRecordingAudioMuxTimeoutMs } = await import("./diagnostics");
+
+ expect(getRecordingAudioMuxTimeoutMs(0)).toBe(5 * 60 * 1000);
+ expect(getRecordingAudioMuxTimeoutMs(29 * 60 + 29.41)).toBeGreaterThan(120000);
+ expect(getRecordingAudioMuxTimeoutMs(29 * 60 + 29.41)).toBeCloseTo(
+ (29 * 60 + 29.41) * 1000 + 60 * 1000,
+ 0,
+ );
+ });
+
+ it("uses video stream frames when container duration is misleading", async () => {
+ const { parseFfprobeVideoStreamDuration } = await import("./diagnostics");
+
+ expect(
+ parseFfprobeVideoStreamDuration(
+ JSON.stringify({
+ streams: [
+ {
+ duration: "18.000000",
+ nb_read_frames: "540",
+ avg_frame_rate: "30/1",
+ },
+ ],
+ }),
+ ),
+ ).toEqual({
+ durationSeconds: 18,
+ frameCount: 540,
+ frameRate: 30,
+ });
+ });
+
+ it("derives video stream duration from frame count when stream duration is absent", async () => {
+ const { parseFfprobeVideoStreamDuration } = await import("./diagnostics");
+
+ expect(
+ parseFfprobeVideoStreamDuration(
+ JSON.stringify({
+ streams: [
+ {
+ nb_read_frames: "540",
+ avg_frame_rate: "30/1",
+ },
+ ],
+ }),
+ ),
+ ).toEqual({
+ durationSeconds: 18,
+ frameCount: 540,
+ frameRate: 30,
+ });
+ });
+
+ it("writes a recording diagnostics sidecar with stream and audio probes", async () => {
+ const videoPath = path.join(tempRoot, "recording-123.mp4");
+ const micPath = path.join(tempRoot, "recording-123.mic.wav");
+ await Promise.all([
+ fs.writeFile(videoPath, "video"),
+ fs.writeFile(micPath, "mic"),
+ fs.writeFile(`${micPath}.json`, JSON.stringify({ startDelayMs: 125 })),
+ ]);
+
+ execFileMock.mockImplementation(
+ (
+ file: string,
+ args: string[],
+ _options: Record,
+ callback: ExecFileCallback,
+ ) => {
+ if (file === "ffprobe" || args.includes("-of")) {
+ callback(
+ null,
+ JSON.stringify({
+ streams: [
+ {
+ duration: "18.000000",
+ nb_read_frames: "540",
+ avg_frame_rate: "30/1",
+ },
+ ],
+ }),
+ "",
+ );
+ return;
+ }
+
+ const error = new Error("ffmpeg probe") as Error & { stderr?: string };
+ error.stderr = "Duration: 00:00:18.00, start: 0.000000";
+ callback(error, "", error.stderr);
+ },
+ );
+
+ const { getRecordingDiagnosticsPath, writeRecordingDiagnosticsSnapshot } = await import(
+ "./diagnostics"
+ );
+
+ const diagnosticsPath = await writeRecordingDiagnosticsSnapshot(videoPath, {
+ backend: "windows-wgc",
+ phase: "mux-start",
+ expectedDurationMs: 60_000,
+ outputPath: videoPath,
+ microphonePath: micPath,
+ details: {
+ hasMicrophone: true,
+ },
+ });
+ const diagnostics = JSON.parse(await fs.readFile(diagnosticsPath, "utf8"));
+
+ expect(diagnosticsPath).toBe(getRecordingDiagnosticsPath(videoPath));
+ expect(diagnostics.events).toHaveLength(1);
+ expect(diagnostics.latest.expectedDurationMs).toBe(60_000);
+ expect(diagnostics.latest.media.video.stream).toEqual({
+ durationSeconds: 18,
+ frameCount: 540,
+ frameRate: 30,
+ });
+ expect(diagnostics.latest.media.microphone).toMatchObject({
+ path: micPath,
+ exists: true,
+ containerDurationSeconds: 18,
+ startDelayMs: 125,
+ });
+ });
+
+ it("ignores invalid sidecar timing metadata values", async () => {
+ const micPath = path.join(tempRoot, "recording.mic.wav");
+ await Promise.all([
+ fs.writeFile(micPath, "mic"),
+ fs.writeFile(`${micPath}.json`, JSON.stringify({ startDelayMs: -250 })),
+ ]);
+
+ const { getCompanionAudioStartDelayMs } = await import("./diagnostics");
+
+ await expect(getCompanionAudioStartDelayMs(micPath)).resolves.toBeNull();
+ });
+
+ it("classifies wall-clock mic chunk gaps covered by pause intervals", async () => {
+ const { summarizeMicrophoneChunkTiming } = await import("./diagnostics");
+
+ expect(
+ summarizeMicrophoneChunkTiming(
+ [
+ {
+ index: 0,
+ size: 1024,
+ elapsedMs: 250,
+ deltaMs: null,
+ recordedElapsedMs: 250,
+ recordedDeltaMs: null,
+ },
+ {
+ index: 1,
+ size: 1024,
+ elapsedMs: 8250,
+ deltaMs: 8000,
+ recordedElapsedMs: 500,
+ recordedDeltaMs: 250,
+ },
+ ],
+ [{ startElapsedMs: 250, endElapsedMs: 8250, durationMs: 7750 }],
+ 250,
+ ),
+ ).toMatchObject({
+ status: "pause-accounted",
+ wallClockGapCount: 1,
+ recordedGapCount: 0,
+ pausedDurationMs: 7750,
+ });
+ });
+
+ it("flags recorded mic chunk gaps that remain after pause accounting", async () => {
+ const { summarizeMicrophoneChunkTiming } = await import("./diagnostics");
+
+ expect(
+ summarizeMicrophoneChunkTiming(
+ [
+ {
+ index: 0,
+ size: 1024,
+ elapsedMs: 250,
+ deltaMs: null,
+ recordedElapsedMs: 250,
+ recordedDeltaMs: null,
+ },
+ {
+ index: 1,
+ size: 1024,
+ elapsedMs: 2500,
+ deltaMs: 2250,
+ recordedElapsedMs: 2500,
+ recordedDeltaMs: 2250,
+ },
+ ],
+ [],
+ 250,
+ ),
+ ).toMatchObject({
+ status: "needs-review",
+ wallClockGapCount: 1,
+ recordedGapCount: 1,
+ });
+ });
+
+ it("rejects tiny MP4 container-only outputs before they reach the editor", async () => {
+ const videoPath = path.join(tempRoot, "recording-123.mp4");
+ await fs.writeFile(videoPath, Buffer.alloc(261));
+
+ const { validateRecordedVideo } = await import("./diagnostics");
+
+ await expect(validateRecordedVideo(videoPath)).rejects.toThrow(
+ "Recorded output is too small to contain playable video",
+ );
+ });
+});
diff --git a/electron/ipc/recording/diagnostics.ts b/electron/ipc/recording/diagnostics.ts
new file mode 100644
index 000000000..985209f22
--- /dev/null
+++ b/electron/ipc/recording/diagnostics.ts
@@ -0,0 +1,614 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import { promisify } from "node:util";
+import { COMPANION_AUDIO_LAYOUTS } from "../constants";
+import { getFfmpegBinaryPath, getFfprobeBinaryPath } from "../ffmpeg/binary";
+import { lastNativeCaptureDiagnostics, setLastNativeCaptureDiagnostics } from "../state";
+import type { CompanionAudioCandidate, NativeCaptureDiagnostics } from "../types";
+import { parseJsonWithByteOrderMark } from "../utils";
+
+const execFileAsync = promisify(execFile);
+export const MIN_VALID_RECORDED_VIDEO_BYTES = 1024;
+export const RECORDING_AUDIO_MUX_MIN_TIMEOUT_MS = 5 * 60 * 1000;
+export const RECORDING_AUDIO_MUX_MAX_TIMEOUT_MS = 2 * 60 * 60 * 1000;
+
+type CompanionAudioTimingMetadata = {
+ startDelayMs?: number;
+};
+
+export type MicrophoneChunkTimingEvent = {
+ index: number;
+ size: number;
+ elapsedMs: number;
+ deltaMs: number | null;
+ recordedElapsedMs?: number;
+ recordedDeltaMs?: number | null;
+};
+
+export type MicrophonePauseInterval = {
+ startElapsedMs: number;
+ endElapsedMs?: number;
+ durationMs?: number;
+};
+
+export type VideoStreamDurationProbe = {
+ durationSeconds: number | null;
+ frameCount: number | null;
+ frameRate: number | null;
+};
+
+export type RecordingDiagnosticsSnapshot = {
+ backend: NativeCaptureDiagnostics["backend"];
+ phase:
+ | `${NativeCaptureDiagnostics["phase"]}`
+ | "pad"
+ | "mic-sidecar"
+ | "mux-start"
+ | "mux-complete"
+ | "mux-error";
+ expectedDurationMs?: number | null;
+ outputPath?: string | null;
+ systemAudioPath?: string | null;
+ microphonePath?: string | null;
+ processOutput?: string;
+ error?: string;
+ details?: Record;
+};
+
+type RecordingDiagnosticsLog = {
+ version: 1;
+ createdAt: string;
+ updatedAt: string;
+ videoPath: string;
+ diagnosticsPath: string;
+ events: unknown[];
+ latest?: unknown;
+};
+
+export function recordNativeCaptureDiagnostics(
+ diagnostics: Omit,
+) {
+ setLastNativeCaptureDiagnostics({
+ timestamp: new Date().toISOString(),
+ ...diagnostics,
+ });
+
+ return lastNativeCaptureDiagnostics;
+}
+
+export async function getFileSizeIfPresent(filePath: string | null | undefined) {
+ if (!filePath) {
+ return null;
+ }
+
+ try {
+ const stat = await fs.stat(filePath);
+ return stat.size;
+ } catch {
+ return null;
+ }
+}
+
+export function parseFfmpegDurationSeconds(stderr: string) {
+ const match = stderr.match(/Duration:\s+(\d+):(\d+):(\d+(?:\.\d+)?)/i);
+ if (!match) {
+ return null;
+ }
+
+ const hours = Number(match[1]);
+ const minutes = Number(match[2]);
+ const seconds = Number(match[3]);
+ if (![hours, minutes, seconds].every(Number.isFinite)) {
+ return null;
+ }
+
+ return hours * 3600 + minutes * 60 + seconds;
+}
+
+export function getRecordingAudioMuxTimeoutMs(durationSeconds: number) {
+ if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+ return RECORDING_AUDIO_MUX_MIN_TIMEOUT_MS;
+ }
+
+ const realtimeMuxBudgetMs = Math.ceil(durationSeconds * 1000) + 60 * 1000;
+ return Math.min(
+ RECORDING_AUDIO_MUX_MAX_TIMEOUT_MS,
+ Math.max(RECORDING_AUDIO_MUX_MIN_TIMEOUT_MS, realtimeMuxBudgetMs),
+ );
+}
+
+function getFiniteNonNegativeNumber(value: unknown) {
+ return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+export function summarizeMicrophoneChunkTiming(
+ chunkEvents: MicrophoneChunkTimingEvent[] | null | undefined,
+ pauseIntervals: MicrophonePauseInterval[] | null | undefined = [],
+ timesliceMs = 250,
+) {
+ const normalizedTimesliceMs =
+ Number.isFinite(timesliceMs) && timesliceMs > 0 ? Math.round(timesliceMs) : 250;
+ const thresholdMs = Math.max(600, Math.round(normalizedTimesliceMs * 2.5));
+ const events = Array.isArray(chunkEvents) ? chunkEvents : [];
+ const pauses = Array.isArray(pauseIntervals) ? pauseIntervals : [];
+ const pausedDurationMs = pauses.reduce((total, interval) => {
+ const durationMs = getFiniteNonNegativeNumber(interval.durationMs);
+ return durationMs === null ? total : total + Math.round(durationMs);
+ }, 0);
+
+ const wallClockGaps = events
+ .filter((event) => (event.deltaMs ?? 0) > thresholdMs)
+ .map((event) => ({
+ index: event.index,
+ deltaMs: Math.round(event.deltaMs ?? 0),
+ elapsedMs: Math.round(event.elapsedMs),
+ }));
+ const recordedGaps = events
+ .filter((event) => {
+ const recordedDeltaMs =
+ getFiniteNonNegativeNumber(event.recordedDeltaMs) ?? event.deltaMs ?? 0;
+ return recordedDeltaMs > thresholdMs;
+ })
+ .map((event) => ({
+ index: event.index,
+ deltaMs: Math.round(
+ getFiniteNonNegativeNumber(event.recordedDeltaMs) ?? event.deltaMs ?? 0,
+ ),
+ recordedElapsedMs: Math.round(event.recordedElapsedMs ?? event.elapsedMs),
+ }));
+ const maxWallClockDeltaMs = events.reduce(
+ (maxDeltaMs, event) => Math.max(maxDeltaMs, event.deltaMs ?? 0),
+ 0,
+ );
+ const maxRecordedDeltaMs = events.reduce((maxDeltaMs, event) => {
+ const recordedDeltaMs =
+ getFiniteNonNegativeNumber(event.recordedDeltaMs) ?? event.deltaMs ?? 0;
+ return Math.max(maxDeltaMs, recordedDeltaMs);
+ }, 0);
+ const status =
+ recordedGaps.length > 0
+ ? "needs-review"
+ : wallClockGaps.length > 0 && pausedDurationMs > 0
+ ? "pause-accounted"
+ : "ok";
+
+ return {
+ status,
+ timesliceMs: normalizedTimesliceMs,
+ thresholdMs,
+ eventCount: events.length,
+ pauseIntervalCount: pauses.length,
+ pausedDurationMs,
+ maxWallClockDeltaMs: Math.round(maxWallClockDeltaMs),
+ maxRecordedDeltaMs: Math.round(maxRecordedDeltaMs),
+ wallClockGapCount: wallClockGaps.length,
+ recordedGapCount: recordedGaps.length,
+ wallClockGaps: wallClockGaps.slice(0, 10),
+ recordedGaps: recordedGaps.slice(0, 10),
+ };
+}
+
+/** Probe the duration of a media file (in seconds) using the container header. */
+export async function probeMediaDurationSeconds(filePath: string): Promise {
+ const start = Date.now();
+ const ffmpegPath = getFfmpegBinaryPath();
+ try {
+ await execFileAsync(ffmpegPath, ["-i", filePath, "-hide_banner"], { timeout: 5000 });
+ } catch (error) {
+ const stderr = (error as NodeJS.ErrnoException & { stderr?: string })?.stderr ?? "";
+ const duration = parseFfmpegDurationSeconds(stderr);
+ if (duration !== null) {
+ return duration;
+ }
+ } finally {
+ console.log(`[PERF:MAIN] probeMediaDurationSeconds: COMPLETED in ${Date.now() - start}ms`);
+ }
+ return 0;
+}
+
+function parsePositiveNumber(value: unknown) {
+ const parsed =
+ typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function parsePositiveInteger(value: unknown) {
+ const parsed = parsePositiveNumber(value);
+ return parsed === null ? null : Math.max(0, Math.round(parsed));
+}
+
+function parseFrameRate(value: unknown) {
+ if (typeof value !== "string") {
+ return null;
+ }
+ const [numeratorRaw, denominatorRaw] = value.split("/");
+ const numerator = Number(numeratorRaw);
+ const denominator = Number(denominatorRaw);
+ if (
+ !Number.isFinite(numerator) ||
+ !Number.isFinite(denominator) ||
+ numerator <= 0 ||
+ denominator <= 0
+ ) {
+ return null;
+ }
+
+ return numerator / denominator;
+}
+
+export function parseFfprobeVideoStreamDuration(output: string): VideoStreamDurationProbe | null {
+ const parsed = JSON.parse(output) as {
+ streams?: Array<{
+ duration?: unknown;
+ nb_frames?: unknown;
+ nb_read_frames?: unknown;
+ avg_frame_rate?: unknown;
+ r_frame_rate?: unknown;
+ }>;
+ };
+ const stream = parsed.streams?.[0];
+ if (!stream) {
+ return null;
+ }
+
+ const frameRate = parseFrameRate(stream.avg_frame_rate) ?? parseFrameRate(stream.r_frame_rate);
+ const frameCount =
+ parsePositiveInteger(stream.nb_read_frames) ?? parsePositiveInteger(stream.nb_frames);
+ const streamDuration = parsePositiveNumber(stream.duration);
+ const frameDerivedDuration =
+ frameCount !== null && frameRate !== null && frameRate > 0 ? frameCount / frameRate : null;
+
+ return {
+ durationSeconds: streamDuration ?? frameDerivedDuration,
+ frameCount,
+ frameRate,
+ };
+}
+
+export async function probeVideoStreamDuration(
+ filePath: string,
+): Promise {
+ const start = Date.now();
+ try {
+ const result = await execFileAsync(
+ getFfprobeBinaryPath(),
+ [
+ "-v",
+ "error",
+ "-select_streams",
+ "v:0",
+ "-show_entries",
+ "stream=duration,nb_frames,nb_read_frames,avg_frame_rate,r_frame_rate",
+ "-of",
+ "json",
+ filePath,
+ ],
+ { timeout: 30000, maxBuffer: 2 * 1024 * 1024 },
+ );
+ const stdout = typeof result === "string" ? result : result.stdout;
+ return parseFfprobeVideoStreamDuration(stdout);
+ } catch {
+ return null;
+ } finally {
+ console.log(`[PERF:MAIN] probeVideoStreamDuration: COMPLETED in ${Date.now() - start}ms`);
+ }
+}
+
+export async function probeVideoStreamDurationSeconds(filePath: string): Promise {
+ const probe = await probeVideoStreamDuration(filePath);
+ return probe?.durationSeconds && probe.durationSeconds > 0
+ ? probe.durationSeconds
+ : probeMediaDurationSeconds(filePath);
+}
+
+export function getRecordingDiagnosticsPath(videoPath: string) {
+ return `${videoPath.replace(/\.[^.]+$/u, "")}.recording-diagnostics.json`;
+}
+
+function truncateDiagnosticsText(value: string | undefined, maxLength = 12000) {
+ if (!value || value.length <= maxLength) {
+ return value;
+ }
+
+ return `${value.slice(-maxLength)}\n[recordly: truncated to last ${maxLength} chars]`;
+}
+
+async function describeMediaFile(filePath: string | null | undefined) {
+ if (!filePath) {
+ return null;
+ }
+
+ try {
+ const stat = await fs.stat(filePath);
+ if (!stat.isFile()) {
+ return {
+ path: filePath,
+ exists: false,
+ };
+ }
+
+ return {
+ path: filePath,
+ exists: true,
+ sizeBytes: stat.size,
+ containerDurationSeconds: await probeMediaDurationSeconds(filePath),
+ };
+ } catch {
+ return {
+ path: filePath,
+ exists: false,
+ };
+ }
+}
+
+async function describeVideoFile(filePath: string | null | undefined) {
+ const media = await describeMediaFile(filePath);
+ if (!media?.exists || !filePath) {
+ return media;
+ }
+
+ return {
+ ...media,
+ stream: await probeVideoStreamDuration(filePath),
+ };
+}
+
+async function describeAudioFile(filePath: string | null | undefined) {
+ const media = await describeMediaFile(filePath);
+ if (!media?.exists || !filePath) {
+ return media;
+ }
+
+ const startDelayMs = await getCompanionAudioStartDelayMs(filePath);
+ return {
+ ...media,
+ startDelayMs,
+ };
+}
+
+export async function writeRecordingDiagnosticsSnapshot(
+ videoPath: string,
+ snapshot: RecordingDiagnosticsSnapshot,
+) {
+ const diagnosticsPath = getRecordingDiagnosticsPath(videoPath);
+ const now = new Date().toISOString();
+ let existing: RecordingDiagnosticsLog | null = null;
+
+ try {
+ const raw = await fs.readFile(diagnosticsPath, "utf8");
+ const parsed = parseJsonWithByteOrderMark(raw);
+ if (parsed?.version === 1 && Array.isArray(parsed.events)) {
+ existing = parsed;
+ }
+ } catch {
+ // First diagnostics event for this recording.
+ }
+
+ const event = {
+ timestamp: now,
+ ...snapshot,
+ processOutput: truncateDiagnosticsText(snapshot.processOutput),
+ media: {
+ video: await describeVideoFile(videoPath),
+ systemAudio: await describeAudioFile(snapshot.systemAudioPath),
+ microphone: await describeAudioFile(snapshot.microphonePath),
+ },
+ };
+ const log: RecordingDiagnosticsLog = existing ?? {
+ version: 1,
+ createdAt: now,
+ updatedAt: now,
+ videoPath,
+ diagnosticsPath,
+ events: [],
+ };
+ log.updatedAt = now;
+ log.videoPath = videoPath;
+ log.diagnosticsPath = diagnosticsPath;
+ log.events.push(event);
+ log.latest = event;
+
+ await fs.writeFile(diagnosticsPath, JSON.stringify(log, null, 2), "utf8");
+ return diagnosticsPath;
+}
+
+export async function getUsableCompanionAudioCandidates(
+ videoPath: string,
+): Promise {
+ const basePath = videoPath.replace(/\.[^.]+$/u, "");
+ const candidates: CompanionAudioCandidate[] = [];
+
+ for (const layout of COMPANION_AUDIO_LAYOUTS) {
+ const systemPath = `${basePath}${layout.systemSuffix}`;
+ const micPath = `${basePath}${layout.micSuffix}`;
+ const usablePaths: string[] = [];
+
+ for (const companionPath of [systemPath, micPath]) {
+ try {
+ const stat = await fs.stat(companionPath);
+ if (stat.size > 0) {
+ usablePaths.push(companionPath);
+ }
+ } catch {
+ // Missing companion audio is expected for many recordings.
+ }
+ }
+
+ if (usablePaths.length > 0) {
+ candidates.push({
+ platform: layout.platform,
+ systemPath,
+ micPath,
+ usablePaths,
+ });
+ }
+ }
+
+ return candidates;
+}
+
+async function readCompanionAudioTimingMetadata(
+ companionPath: string,
+): Promise {
+ try {
+ const raw = await fs.readFile(`${companionPath}.json`, "utf8");
+ const parsed = parseJsonWithByteOrderMark(raw);
+ if (!parsed || typeof parsed !== "object") {
+ return null;
+ }
+
+ return parsed;
+ } catch {
+ return null;
+ }
+}
+
+export async function getCompanionAudioStartDelayMs(companionPath: string) {
+ const metadata = await readCompanionAudioTimingMetadata(companionPath);
+ const startDelayMs = metadata?.startDelayMs;
+ if (!Number.isFinite(startDelayMs) || (startDelayMs ?? 0) < 0) {
+ return null;
+ }
+
+ return Math.round(startDelayMs ?? 0);
+}
+
+export async function hasEmbeddedAudioStream(videoPath: string) {
+ const ffmpegPath = getFfmpegBinaryPath();
+ let stderr = "";
+
+ try {
+ const result = await execFileAsync(
+ ffmpegPath,
+ ["-hide_banner", "-i", videoPath, "-map", "0:a:0", "-frames:a", "1", "-f", "null", "-"],
+ { timeout: 20000, maxBuffer: 10 * 1024 * 1024 },
+ );
+ stderr = result.stderr;
+ } catch (error) {
+ stderr = (error as NodeJS.ErrnoException & { stderr?: string }).stderr ?? "";
+ }
+
+ return /Stream #.*Audio:/i.test(stderr);
+}
+
+export async function getCompanionAudioFallbackPaths(videoPath: string) {
+ const { paths } = await getCompanionAudioFallbackInfo(videoPath);
+ return paths;
+}
+
+export async function getCompanionAudioFallbackInfo(videoPath: string) {
+ const companionCandidates = await getUsableCompanionAudioCandidates(videoPath);
+ if (companionCandidates.length === 0) {
+ return { paths: [], startDelayMsByPath: {} };
+ }
+
+ let paths: string[];
+ if (await hasEmbeddedAudioStream(videoPath)) {
+ const hasUsableMacSystemCompanion = companionCandidates.some(
+ (candidate) =>
+ candidate.platform === "mac" &&
+ candidate.usablePaths.includes(candidate.systemPath),
+ );
+ const usableMacMicOnlyCompanions = Array.from(
+ new Set(
+ companionCandidates.flatMap((candidate) =>
+ candidate.platform === "mac" &&
+ !candidate.usablePaths.includes(candidate.systemPath) &&
+ candidate.usablePaths.includes(candidate.micPath)
+ ? [candidate.micPath]
+ : [],
+ ),
+ ),
+ );
+
+ if (!hasUsableMacSystemCompanion && usableMacMicOnlyCompanions.length > 0) {
+ paths = usableMacMicOnlyCompanions;
+ } else if (hasUsableMacSystemCompanion) {
+ paths = [videoPath];
+ } else {
+ const companionPaths = Array.from(
+ new Set(
+ companionCandidates.flatMap((candidate) =>
+ candidate.usablePaths.filter(
+ (companionPath) => companionPath === candidate.micPath,
+ ),
+ ),
+ ),
+ );
+ if (companionPaths.length === 0) {
+ return { paths: [], startDelayMsByPath: {} };
+ }
+
+ paths = [videoPath, ...companionPaths];
+ }
+ } else {
+ paths = Array.from(
+ new Set(companionCandidates.flatMap((candidate) => candidate.usablePaths)),
+ );
+ }
+
+ const metadataEntries = await Promise.all(
+ paths.map(async (audioPath) => {
+ const startDelayMs = await getCompanionAudioStartDelayMs(audioPath);
+ if (!Number.isFinite(startDelayMs)) {
+ return null;
+ }
+
+ return [audioPath, startDelayMs] as const;
+ }),
+ );
+
+ return {
+ paths,
+ startDelayMsByPath: Object.fromEntries(
+ metadataEntries.filter((entry): entry is readonly [string, number] => entry !== null),
+ ),
+ };
+}
+
+export async function validateRecordedVideo(videoPath: string) {
+ const stat = await fs.stat(videoPath);
+ if (!stat.isFile()) {
+ throw new Error(`Recorded output is not a file: ${videoPath}`);
+ }
+
+ if (stat.size <= 0) {
+ throw new Error(`Recorded output is empty: ${videoPath}`);
+ }
+
+ if (stat.size < MIN_VALID_RECORDED_VIDEO_BYTES) {
+ throw new Error(
+ `Recorded output is too small to contain playable video (${stat.size} bytes): ${videoPath}`,
+ );
+ }
+
+ const ffmpegPath = getFfmpegBinaryPath();
+ let stderr = "";
+
+ try {
+ const result = await execFileAsync(
+ ffmpegPath,
+ ["-hide_banner", "-i", videoPath, "-map", "0:v:0", "-frames:v", "1", "-f", "null", "-"],
+ { timeout: 20000, maxBuffer: 10 * 1024 * 1024 },
+ );
+ stderr = result.stderr;
+ } catch (error) {
+ const execError = error as NodeJS.ErrnoException & { stderr?: string };
+ const output = execError.stderr?.trim();
+ throw new Error(output || `Recorded output could not be decoded: ${videoPath}`);
+ }
+
+ if (!/Stream #.*Video:/i.test(stderr)) {
+ throw new Error(`Recorded output does not contain a readable video stream: ${videoPath}`);
+ }
+
+ const durationSeconds = parseFfmpegDurationSeconds(stderr);
+ if (durationSeconds === null || durationSeconds <= 0) {
+ throw new Error(`Recorded output has an invalid duration: ${videoPath}`);
+ }
+
+ return {
+ fileSizeBytes: stat.size,
+ durationSeconds,
+ };
+}
diff --git a/electron/ipc/recording/events.ts b/electron/ipc/recording/events.ts
new file mode 100644
index 000000000..5a2653c3b
--- /dev/null
+++ b/electron/ipc/recording/events.ts
@@ -0,0 +1,9 @@
+import { BrowserWindow } from "electron";
+
+export function emitRecordingInterrupted(reason: string, message: string) {
+ BrowserWindow.getAllWindows().forEach((window) => {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-interrupted", { reason, message });
+ }
+ });
+}
diff --git a/electron/ipc/recording/ffmpeg.ts b/electron/ipc/recording/ffmpeg.ts
new file mode 100644
index 000000000..50281a39f
--- /dev/null
+++ b/electron/ipc/recording/ffmpeg.ts
@@ -0,0 +1,225 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import fs from "node:fs/promises";
+import { resolveLinuxWindowBounds } from "../cursor/bounds";
+import { ffmpegCaptureOutputBuffer } from "../state";
+import type { SelectedSource } from "../types";
+import { getScreen, parseWindowId } from "../utils";
+import { resolveWindowsCaptureDisplay } from "../windowsCaptureSelection";
+
+export function getDisplayBoundsForSource(source: SelectedSource) {
+ return resolveWindowsCaptureDisplay(
+ source,
+ getScreen().getAllDisplays(),
+ getScreen().getPrimaryDisplay(),
+ ).bounds;
+}
+
+export function getDisplayWorkAreaForSource(source: SelectedSource) {
+ const allDisplays = getScreen().getAllDisplays();
+ const primaryDisplay = getScreen().getPrimaryDisplay();
+ const { displayId } = resolveWindowsCaptureDisplay(source, allDisplays, primaryDisplay);
+ const matched = allDisplays.find((d) => d.id === displayId) ?? primaryDisplay;
+ return matched.workArea;
+}
+
+export async function buildFfmpegCaptureArgs(source: SelectedSource, outputPath: string) {
+ const buildOutputArgs = (inputRange: "auto" | "full") => [
+ "-an",
+ "-vf",
+ `scale=in_range=${inputRange}:out_range=tv:out_color_matrix=bt709:sws_dither=bayer`,
+ "-c:v",
+ "libx264",
+ "-preset",
+ "veryfast",
+ "-pix_fmt",
+ "yuv420p",
+ "-colorspace",
+ "bt709",
+ "-color_primaries",
+ "bt709",
+ "-color_trc",
+ "bt709",
+ "-color_range",
+ "tv",
+ "-movflags",
+ "+faststart",
+ outputPath,
+ ];
+ const fullRangeOutputArgs = buildOutputArgs("full");
+
+ if (process.platform === "win32") {
+ if (source?.id?.startsWith("window:")) {
+ const windowId = parseWindowId(source.id);
+ const windowTitle =
+ typeof source.windowTitle === "string"
+ ? source.windowTitle.trim()
+ : source.name.trim();
+ if (!windowId && !windowTitle) {
+ throw new Error("Missing window identifier for FFmpeg window capture");
+ }
+
+ return [
+ "-y",
+ "-f",
+ "gdigrab",
+ "-framerate",
+ "60",
+ "-draw_mouse",
+ "0",
+ "-i",
+ windowId ? `hwnd=${windowId}` : `title=${windowTitle}`,
+ ...fullRangeOutputArgs,
+ ];
+ }
+
+ return [
+ "-y",
+ "-f",
+ "gdigrab",
+ "-framerate",
+ "60",
+ "-draw_mouse",
+ "0",
+ "-i",
+ "desktop",
+ ...fullRangeOutputArgs,
+ ];
+ }
+
+ if (process.platform === "linux") {
+ const displayEnv = process.env.DISPLAY || ":0.0";
+ if (source?.id?.startsWith("window:")) {
+ const bounds = await resolveLinuxWindowBounds(source);
+ if (!bounds) {
+ throw new Error("Unable to resolve Linux window bounds for FFmpeg capture");
+ }
+
+ return [
+ "-y",
+ "-f",
+ "x11grab",
+ "-framerate",
+ "60",
+ "-draw_mouse",
+ "0",
+ "-video_size",
+ `${Math.max(2, bounds.width)}x${Math.max(2, bounds.height)}`,
+ "-i",
+ `${displayEnv}+${Math.round(bounds.x)},${Math.round(bounds.y)}`,
+ ...fullRangeOutputArgs,
+ ];
+ }
+
+ const bounds = getDisplayBoundsForSource(source);
+ return [
+ "-y",
+ "-f",
+ "x11grab",
+ "-framerate",
+ "60",
+ "-draw_mouse",
+ "0",
+ "-video_size",
+ `${Math.max(2, bounds.width)}x${Math.max(2, bounds.height)}`,
+ "-i",
+ `${displayEnv}+${Math.round(bounds.x)},${Math.round(bounds.y)}`,
+ ...fullRangeOutputArgs,
+ ];
+ }
+
+ if (process.platform === "darwin") {
+ return [
+ "-y",
+ "-f",
+ "avfoundation",
+ "-capture_cursor",
+ "0",
+ "-framerate",
+ "60",
+ "-i",
+ "1:none",
+ ...buildOutputArgs("auto"),
+ ];
+ }
+
+ throw new Error(`FFmpeg capture is not supported on ${process.platform}`);
+}
+
+export function waitForFfmpegCaptureStart(process: ChildProcessWithoutNullStreams) {
+ return new Promise((resolve, reject) => {
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const onExit = (code: number | null) => {
+ cleanup();
+ reject(
+ new Error(
+ ffmpegCaptureOutputBuffer.trim() ||
+ `FFmpeg exited before recording started (code ${code ?? "unknown"})`,
+ ),
+ );
+ };
+
+ const timer = setTimeout(() => {
+ cleanup();
+ resolve();
+ }, 900);
+
+ const cleanup = () => {
+ clearTimeout(timer);
+ process.off("error", onError);
+ process.off("exit", onExit);
+ };
+
+ process.once("error", onError);
+ process.once("exit", onExit);
+ });
+}
+
+export function waitForFfmpegCaptureStop(
+ process: ChildProcessWithoutNullStreams,
+ outputPath: string,
+) {
+ return new Promise((resolve, reject) => {
+ const onClose = async (code: number | null) => {
+ cleanup();
+
+ try {
+ await fs.access(outputPath);
+ if (code === 0 || code === null) {
+ resolve(outputPath);
+ return;
+ }
+
+ if (ffmpegCaptureOutputBuffer.includes("Exiting normally")) {
+ resolve(outputPath);
+ return;
+ }
+ } catch {
+ // handled below
+ }
+
+ reject(
+ new Error(
+ ffmpegCaptureOutputBuffer.trim() ||
+ `FFmpeg exited with code ${code ?? "unknown"}`,
+ ),
+ );
+ };
+
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const cleanup = () => {
+ process.off("close", onClose);
+ process.off("error", onError);
+ };
+
+ process.once("close", onClose);
+ process.once("error", onError);
+ });
+}
diff --git a/electron/ipc/recording/mac.ts b/electron/ipc/recording/mac.ts
new file mode 100644
index 000000000..57a9e6881
--- /dev/null
+++ b/electron/ipc/recording/mac.ts
@@ -0,0 +1,352 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import fs from "node:fs/promises";
+import { BrowserWindow } from "electron";
+import {
+ persistPendingCursorTelemetry,
+ snapshotCursorTelemetryForPersistence,
+} from "../cursor/telemetry";
+import {
+ lastNativeCaptureDiagnostics,
+ nativeCaptureMicrophonePath,
+ nativeCaptureOutputBuffer,
+ nativeCaptureStopRequested,
+ nativeCaptureSystemAudioPath,
+ nativeCaptureTargetPath,
+ nativeScreenRecordingActive,
+ selectedSource,
+ setCurrentProjectPath,
+ setCurrentVideoPath,
+ setNativeCaptureMicrophonePath,
+ setNativeCaptureProcess,
+ setNativeCaptureStopRequested,
+ setNativeCaptureSystemAudioPath,
+ setNativeCaptureTargetPath,
+ setNativeScreenRecordingActive,
+} from "../state";
+import { isAutoRecordingPath, moveFileWithOverwrite } from "../utils";
+import {
+ getFileSizeIfPresent,
+ recordNativeCaptureDiagnostics,
+ validateRecordedVideo,
+} from "./diagnostics";
+import { emitRecordingInterrupted } from "./events";
+import { getFinalMacCompanionAudioPath } from "./macCompanionAudio";
+import { pruneAutoRecordings } from "./prune";
+
+export function waitForNativeCaptureStart(process: ChildProcessWithoutNullStreams) {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ cleanup();
+ reject(new Error("Timed out waiting for ScreenCaptureKit recorder to start"));
+ }, 12000);
+
+ let stdoutBuffer = "";
+ const onStdout = (chunk: Buffer) => {
+ stdoutBuffer += chunk.toString();
+ if (stdoutBuffer.includes("Recording started")) {
+ cleanup();
+ resolve();
+ }
+ };
+
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const onExit = (code: number | null) => {
+ cleanup();
+ reject(
+ new Error(
+ nativeCaptureOutputBuffer.trim() ||
+ `Native capture helper exited before recording started (code ${code ?? "unknown"})`,
+ ),
+ );
+ };
+
+ const cleanup = () => {
+ clearTimeout(timer);
+ process.stdout.off("data", onStdout);
+ process.off("error", onError);
+ process.off("exit", onExit);
+ };
+
+ process.stdout.on("data", onStdout);
+ process.once("error", onError);
+ process.once("exit", onExit);
+ });
+}
+
+export function waitForNativeCaptureCommand(
+ process: ChildProcessWithoutNullStreams,
+ marker: "Recording paused" | "Recording resumed",
+) {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ cleanup();
+ reject(new Error(`Timed out waiting for ScreenCaptureKit helper: ${marker}`));
+ }, 5000);
+
+ let stdoutBuffer = "";
+ const onStdout = (chunk: Buffer) => {
+ stdoutBuffer += chunk.toString();
+ if (stdoutBuffer.includes(marker)) {
+ cleanup();
+ resolve();
+ }
+ };
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+ const onExit = (code: number | null) => {
+ cleanup();
+ reject(
+ new Error(
+ `Native capture helper exited before ${marker.toLowerCase()} (code ${code ?? "unknown"})`,
+ ),
+ );
+ };
+ const cleanup = () => {
+ clearTimeout(timer);
+ process.stdout.off("data", onStdout);
+ process.off("error", onError);
+ process.off("exit", onExit);
+ };
+
+ process.stdout.on("data", onStdout);
+ process.once("error", onError);
+ process.once("exit", onExit);
+ });
+}
+
+export function waitForNativeCaptureStop(process: ChildProcessWithoutNullStreams) {
+ return new Promise((resolve, reject) => {
+ const onClose = (code: number | null) => {
+ cleanup();
+ const match = nativeCaptureOutputBuffer.match(/Recording stopped\. Output path: (.+)/);
+ if (match?.[1]) {
+ resolve(match[1].trim());
+ return;
+ }
+ if (code === 0 && nativeCaptureTargetPath) {
+ resolve(nativeCaptureTargetPath);
+ return;
+ }
+ reject(
+ new Error(
+ nativeCaptureOutputBuffer.trim() ||
+ `Native capture helper exited with code ${code ?? "unknown"}`,
+ ),
+ );
+ };
+
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const cleanup = () => {
+ process.off("close", onClose);
+ process.off("error", onError);
+ };
+
+ process.once("close", onClose);
+ process.once("error", onError);
+ });
+}
+
+export async function muxNativeMacRecordingWithAudio(
+ videoPath: string,
+ systemAudioPath?: string | null,
+ microphonePath?: string | null,
+) {
+ console.log("[mac-mux] Optimization active: keeping tracks separate.");
+
+ // Optimization: instead of heavy FFmpeg muxing, we ensure audio sidecars
+ // are available alongside the video for the editor.
+ if (systemAudioPath) {
+ const finalSystemPath = getFinalMacCompanionAudioPath(videoPath, systemAudioPath, "system");
+ try {
+ const stat = await fs.stat(systemAudioPath);
+ if (stat.size > 0 && systemAudioPath !== finalSystemPath) {
+ await moveFileWithOverwrite(systemAudioPath, finalSystemPath);
+ }
+ } catch (err) {
+ console.error(`[mac-mux] Failed to handle system audio:`, err);
+ }
+ }
+
+ if (microphonePath) {
+ const finalMicPath = getFinalMacCompanionAudioPath(videoPath, microphonePath, "mic");
+ try {
+ const stat = await fs.stat(microphonePath);
+ if (stat.size > 0 && microphonePath !== finalMicPath) {
+ await moveFileWithOverwrite(microphonePath, finalMicPath);
+ }
+ } catch (err) {
+ console.error(`[mac-mux] Failed to handle mic audio:`, err);
+ }
+ }
+}
+
+export function attachNativeCaptureLifecycle(process: ChildProcessWithoutNullStreams) {
+ process.once("close", () => {
+ const wasActive = nativeScreenRecordingActive;
+ setNativeCaptureProcess(null);
+
+ if (!wasActive || nativeCaptureStopRequested) {
+ return;
+ }
+
+ setNativeScreenRecordingActive(false);
+ console.log("[mac-finalize] Optimization active: skipping safety-net muxing.");
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+
+ const sourceName = selectedSource?.name ?? "Screen";
+ BrowserWindow.getAllWindows().forEach((window) => {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-state-changed", {
+ recording: false,
+ sourceName,
+ });
+ }
+ });
+
+ const reason = nativeCaptureOutputBuffer.includes("WINDOW_UNAVAILABLE")
+ ? "window-unavailable"
+ : "capture-stopped";
+ const message =
+ reason === "window-unavailable"
+ ? "The selected window is no longer capturable. Please reselect a window."
+ : "Recording stopped unexpectedly.";
+
+ emitRecordingInterrupted(reason, message);
+ });
+}
+
+export async function finalizeStoredVideo(videoPath: string) {
+ console.log("[finalize] Optimization active: skipping safety-net muxing.");
+
+ let validation: { fileSizeBytes: number; durationSeconds: number | null };
+ try {
+ validation = await validateRecordedVideo(videoPath);
+ } catch (error) {
+ if (
+ lastNativeCaptureDiagnostics?.backend === "mac-screencapturekit" ||
+ lastNativeCaptureDiagnostics?.backend === "windows-wgc"
+ ) {
+ recordNativeCaptureDiagnostics({
+ backend: lastNativeCaptureDiagnostics.backend,
+ phase: lastNativeCaptureDiagnostics.phase === "mux" ? "mux" : "stop",
+ sourceId: lastNativeCaptureDiagnostics.sourceId ?? null,
+ sourceType: lastNativeCaptureDiagnostics.sourceType ?? "unknown",
+ displayId: lastNativeCaptureDiagnostics.displayId ?? null,
+ displayBounds: lastNativeCaptureDiagnostics.displayBounds ?? null,
+ windowHandle: lastNativeCaptureDiagnostics.windowHandle ?? null,
+ helperPath: lastNativeCaptureDiagnostics.helperPath ?? null,
+ outputPath: videoPath,
+ systemAudioPath: lastNativeCaptureDiagnostics.systemAudioPath ?? null,
+ microphonePath: lastNativeCaptureDiagnostics.microphonePath ?? null,
+ osRelease: lastNativeCaptureDiagnostics.osRelease,
+ supported: lastNativeCaptureDiagnostics.supported,
+ helperExists: lastNativeCaptureDiagnostics.helperExists,
+ processOutput: lastNativeCaptureDiagnostics.processOutput,
+ fileSizeBytes: await getFileSizeIfPresent(videoPath),
+ error: error instanceof Error ? error.message : String(error),
+ });
+ }
+ throw error;
+ }
+
+ snapshotCursorTelemetryForPersistence();
+ setCurrentVideoPath(videoPath);
+ setCurrentProjectPath(null);
+ try {
+ await persistPendingCursorTelemetry(videoPath);
+ } catch (error) {
+ console.warn("[mac-stop] Failed to persist cursor telemetry:", error);
+ }
+ if (isAutoRecordingPath(videoPath)) {
+ await pruneAutoRecordings([videoPath]);
+ }
+
+ if (
+ lastNativeCaptureDiagnostics?.backend === "mac-screencapturekit" ||
+ lastNativeCaptureDiagnostics?.backend === "windows-wgc"
+ ) {
+ recordNativeCaptureDiagnostics({
+ backend: lastNativeCaptureDiagnostics.backend,
+ phase: lastNativeCaptureDiagnostics.phase === "mux" ? "mux" : "stop",
+ sourceId: lastNativeCaptureDiagnostics.sourceId ?? null,
+ sourceType: lastNativeCaptureDiagnostics.sourceType ?? "unknown",
+ displayId: lastNativeCaptureDiagnostics.displayId ?? null,
+ displayBounds: lastNativeCaptureDiagnostics.displayBounds ?? null,
+ windowHandle: lastNativeCaptureDiagnostics.windowHandle ?? null,
+ helperPath: lastNativeCaptureDiagnostics.helperPath ?? null,
+ outputPath: videoPath,
+ systemAudioPath: lastNativeCaptureDiagnostics.systemAudioPath ?? null,
+ microphonePath: lastNativeCaptureDiagnostics.microphonePath ?? null,
+ osRelease: lastNativeCaptureDiagnostics.osRelease,
+ supported: lastNativeCaptureDiagnostics.supported,
+ helperExists: lastNativeCaptureDiagnostics.helperExists,
+ processOutput: lastNativeCaptureDiagnostics.processOutput,
+ fileSizeBytes: validation.fileSizeBytes,
+ });
+ }
+
+ return {
+ success: true,
+ path: videoPath,
+ message:
+ validation.durationSeconds !== null
+ ? `Video stored successfully (${validation.fileSizeBytes} bytes, ${validation.durationSeconds.toFixed(2)}s)`
+ : `Video stored successfully`,
+ };
+}
+
+export async function recoverNativeMacCaptureOutput() {
+ const macDiagnostics =
+ lastNativeCaptureDiagnostics?.backend === "mac-screencapturekit"
+ ? lastNativeCaptureDiagnostics
+ : null;
+ const diagnosticsPath = macDiagnostics?.outputPath ?? null;
+ const candidatePath = nativeCaptureTargetPath ?? diagnosticsPath;
+ const systemAudioPath = nativeCaptureSystemAudioPath ?? macDiagnostics?.systemAudioPath ?? null;
+ const microphonePath = nativeCaptureMicrophonePath ?? macDiagnostics?.microphonePath ?? null;
+
+ if (!candidatePath) {
+ return null;
+ }
+
+ try {
+ if (systemAudioPath || microphonePath) {
+ try {
+ await muxNativeMacRecordingWithAudio(
+ candidatePath,
+ systemAudioPath,
+ microphonePath,
+ );
+ } catch (muxError) {
+ console.warn("Failed to mux audio during recovery:", muxError);
+ }
+ }
+
+ return await finalizeStoredVideo(candidatePath);
+ } catch (error) {
+ recordNativeCaptureDiagnostics({
+ backend: "mac-screencapturekit",
+ phase: "stop",
+ outputPath: candidatePath,
+ systemAudioPath,
+ microphonePath,
+ processOutput: nativeCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: await getFileSizeIfPresent(candidatePath),
+ error: String(error),
+ });
+ return null;
+ }
+}
diff --git a/electron/ipc/recording/macCompanionAudio.test.ts b/electron/ipc/recording/macCompanionAudio.test.ts
new file mode 100644
index 000000000..269a76623
--- /dev/null
+++ b/electron/ipc/recording/macCompanionAudio.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import { getFinalMacCompanionAudioPath } from "./macCompanionAudio";
+
+describe("mac companion audio paths", () => {
+ it("preserves the helper's AAC container extension", () => {
+ expect(
+ getFinalMacCompanionAudioPath(
+ "/Users/egg/Recordly/recording-1.mp4",
+ "/Users/egg/Recordly/recording-1.mic.m4a",
+ "mic",
+ ),
+ ).toBe("/Users/egg/Recordly/recording-1.mic.m4a");
+ });
+
+ it("preserves legacy sidecar extensions instead of renaming bytes", () => {
+ expect(
+ getFinalMacCompanionAudioPath(
+ "/Users/egg/Recordly/recording-1.mp4",
+ "/tmp/recordly-native.system.webm",
+ "system",
+ ),
+ ).toBe("/Users/egg/Recordly/recording-1.system.webm");
+ });
+
+ it("keeps dotted directories when the video path has no extension", () => {
+ expect(
+ getFinalMacCompanionAudioPath(
+ "/Users/egg/Recordly.videos/recording-1",
+ "/tmp/recordly-native.mic.m4a",
+ "mic",
+ ),
+ ).toBe("/Users/egg/Recordly.videos/recording-1.mic.m4a");
+ });
+});
diff --git a/electron/ipc/recording/macCompanionAudio.ts b/electron/ipc/recording/macCompanionAudio.ts
new file mode 100644
index 000000000..fdfc9e26b
--- /dev/null
+++ b/electron/ipc/recording/macCompanionAudio.ts
@@ -0,0 +1,16 @@
+import path from "node:path";
+
+export type MacCompanionAudioSuffix = "system" | "mic";
+
+export function getFinalMacCompanionAudioPath(
+ videoPath: string,
+ sourceAudioPath: string,
+ suffix: MacCompanionAudioSuffix,
+) {
+ const separatorIndex = Math.max(videoPath.lastIndexOf("/"), videoPath.lastIndexOf("\\"));
+ const videoDirectory = separatorIndex >= 0 ? videoPath.slice(0, separatorIndex + 1) : "";
+ const videoFileName = separatorIndex >= 0 ? videoPath.slice(separatorIndex + 1) : videoPath;
+ const videoPathWithoutExt = `${videoDirectory}${path.parse(videoFileName).name}`;
+ const sourceExtension = path.extname(sourceAudioPath).toLowerCase() || ".m4a";
+ return `${videoPathWithoutExt}.${suffix}${sourceExtension}`;
+}
diff --git a/electron/ipc/recording/prune.test.ts b/electron/ipc/recording/prune.test.ts
new file mode 100644
index 000000000..8c1c66839
--- /dev/null
+++ b/electron/ipc/recording/prune.test.ts
@@ -0,0 +1,130 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("pruneAutoRecordings", () => {
+ let tempRoot: string;
+ let appDataPath: string;
+ let userDataPath: string;
+ let tempPath: string;
+ let appPath: string;
+
+ beforeEach(async () => {
+ tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-prune-"));
+ appDataPath = path.join(tempRoot, "AppData");
+ userDataPath = path.join(tempRoot, "UserData");
+ tempPath = path.join(tempRoot, "Temp");
+ appPath = path.join(tempRoot, "App");
+
+ await Promise.all(
+ [appDataPath, userDataPath, tempPath, appPath].map((dirPath) =>
+ fs.mkdir(dirPath, { recursive: true }),
+ ),
+ );
+
+ vi.resetModules();
+ vi.doMock("electron", () => ({
+ app: {
+ isPackaged: false,
+ getAppPath: () => appPath,
+ getPath: (name: string) => {
+ if (name === "appData") return appDataPath;
+ if (name === "userData") return userDataPath;
+ if (name === "temp") return tempPath;
+ return tempRoot;
+ },
+ setPath: () => undefined,
+ },
+ }));
+ });
+
+ afterEach(async () => {
+ vi.resetModules();
+ vi.doUnmock("electron");
+ if (tempRoot) {
+ await fs.rm(tempRoot, { recursive: true, force: true });
+ }
+ });
+
+ it("preserves recordings referenced by saved projects in the Projects directory", async () => {
+ const { getRecordingsDir } = await import("../utils");
+ const { PROJECTS_DIRECTORY_NAME, PROJECT_FILE_EXTENSION } = await import("../constants");
+ const { pruneAutoRecordings } = await import("./prune");
+
+ const recordingsDir = await getRecordingsDir();
+ const projectsDir = path.join(recordingsDir, PROJECTS_DIRECTORY_NAME);
+ await fs.mkdir(projectsDir, { recursive: true });
+
+ const recordingPaths: string[] = [];
+ for (let index = 0; index < 23; index += 1) {
+ const recordingPath = path.join(recordingsDir, `recording-${index}.mp4`);
+ recordingPaths.push(recordingPath);
+ await fs.writeFile(recordingPath, `video-${index}`);
+ const timestamp = new Date(Date.now() - index * 60_000);
+ await fs.utimes(recordingPath, timestamp, timestamp);
+ }
+
+ const protectedVideoRecordingPath = recordingPaths.at(-3);
+ const protectedWebcamRecordingPath = recordingPaths.at(-2);
+ const prunableRecordingPath = recordingPaths.at(-1);
+
+ await fs.writeFile(
+ path.join(projectsDir, `saved-project-video.${PROJECT_FILE_EXTENSION}`),
+ JSON.stringify(
+ {
+ videoPath: protectedVideoRecordingPath,
+ },
+ null,
+ 2,
+ ),
+ "utf-8",
+ );
+
+ await fs.writeFile(
+ path.join(projectsDir, `saved-project-webcam.${PROJECT_FILE_EXTENSION}`),
+ JSON.stringify(
+ {
+ editor: {
+ webcam: {
+ sourcePath: protectedWebcamRecordingPath,
+ },
+ },
+ },
+ null,
+ 2,
+ ),
+ "utf-8",
+ );
+
+ await pruneAutoRecordings();
+
+ await expect(fs.access(protectedVideoRecordingPath!)).resolves.toBeUndefined();
+ await expect(fs.access(protectedWebcamRecordingPath!)).resolves.toBeUndefined();
+ await expect(fs.access(prunableRecordingPath!)).rejects.toThrow();
+ });
+
+ it("aborts pruning when a saved project cannot be parsed", async () => {
+ const { getRecordingsDir } = await import("../utils");
+ const { PROJECTS_DIRECTORY_NAME, PROJECT_FILE_EXTENSION } = await import("../constants");
+ const { pruneAutoRecordings } = await import("./prune");
+
+ const recordingsDir = await getRecordingsDir();
+ const projectsDir = path.join(recordingsDir, PROJECTS_DIRECTORY_NAME);
+ await fs.mkdir(projectsDir, { recursive: true });
+
+ const recordingPath = path.join(recordingsDir, "recording-stale.mp4");
+ await fs.writeFile(recordingPath, "video");
+ const staleTimestamp = new Date(Date.now() - 48 * 60 * 60 * 1_000);
+ await fs.utimes(recordingPath, staleTimestamp, staleTimestamp);
+
+ await fs.writeFile(
+ path.join(projectsDir, `broken-project.${PROJECT_FILE_EXTENSION}`),
+ "{ invalid json",
+ "utf-8",
+ );
+
+ await expect(pruneAutoRecordings()).rejects.toThrow();
+ await expect(fs.access(recordingPath)).resolves.toBeUndefined();
+ });
+});
diff --git a/electron/ipc/recording/prune.ts b/electron/ipc/recording/prune.ts
new file mode 100644
index 000000000..29787e8e2
--- /dev/null
+++ b/electron/ipc/recording/prune.ts
@@ -0,0 +1,190 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+ AUTO_RECORDING_MAX_AGE_MS,
+ AUTO_RECORDING_RETENTION_COUNT,
+ COMPANION_AUDIO_LAYOUTS,
+ LEGACY_PROJECT_FILE_EXTENSIONS,
+ PROJECT_FILE_EXTENSION,
+ PROJECTS_DIRECTORY_NAME,
+} from "../constants";
+import { currentVideoPath } from "../state";
+import {
+ getRecordingsDir,
+ getTelemetryPathForVideo,
+ isAutoRecordingPath,
+ normalizePath,
+ normalizeVideoSourcePath,
+ parseJsonWithByteOrderMark,
+} from "../utils";
+
+export async function hasSiblingProjectFile(videoPath: string) {
+ const baseName = path.basename(videoPath, path.extname(videoPath));
+ const candidateExtensions = [PROJECT_FILE_EXTENSION, ...LEGACY_PROJECT_FILE_EXTENSIONS];
+
+ for (const extension of candidateExtensions) {
+ const projectPath = path.join(path.dirname(videoPath), `${baseName}.${extension}`);
+
+ try {
+ await fs.access(projectPath);
+ return true;
+ } catch {
+ continue;
+ }
+ }
+
+ return false;
+}
+
+export { isAutoRecordingPath };
+
+async function loadSavedProjectMediaPaths() {
+ const recordingsDir = await getRecordingsDir();
+ const projectsDir = path.join(recordingsDir, PROJECTS_DIRECTORY_NAME);
+ const protectedPaths = new Set();
+ const candidateExtensions = new Set([
+ PROJECT_FILE_EXTENSION,
+ ...LEGACY_PROJECT_FILE_EXTENSIONS,
+ ]);
+
+ let projectEntries: Array<{ isFile(): boolean; name: string }>;
+ try {
+ projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
+ } catch (error) {
+ const code =
+ typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+ if (code === "ENOENT") {
+ return protectedPaths;
+ }
+
+ throw error;
+ }
+
+ await Promise.all(
+ projectEntries
+ .filter((entry) => {
+ if (!entry.isFile()) {
+ return false;
+ }
+
+ const extension = path.extname(entry.name).replace(/^\./, "").toLowerCase();
+ return candidateExtensions.has(extension);
+ })
+ .map(async (entry) => {
+ const projectPath = path.join(projectsDir, entry.name);
+ let rawProject: {
+ videoPath?: unknown;
+ editor?: { webcam?: { sourcePath?: unknown } };
+ };
+ try {
+ rawProject = parseJsonWithByteOrderMark<{
+ videoPath?: unknown;
+ editor?: { webcam?: { sourcePath?: unknown } };
+ }>(await fs.readFile(projectPath, "utf-8"));
+ } catch (error) {
+ console.warn(
+ "[prune] Aborting recording prune because a saved project is unreadable",
+ {
+ projectPath,
+ error,
+ },
+ );
+ throw error;
+ }
+ const candidatePaths = [
+ rawProject.videoPath,
+ rawProject.editor?.webcam?.sourcePath,
+ ];
+
+ for (const candidatePath of candidatePaths) {
+ if (typeof candidatePath !== "string" || candidatePath.trim().length === 0) {
+ continue;
+ }
+
+ const normalizedCandidatePath = normalizePath(
+ normalizeVideoSourcePath(candidatePath) ?? candidatePath,
+ );
+ protectedPaths.add(normalizedCandidatePath);
+ try {
+ protectedPaths.add(await fs.realpath(normalizedCandidatePath));
+ } catch {
+ // Ignore missing project media; project loading already surfaces that error.
+ }
+ }
+ }),
+ );
+
+ return protectedPaths;
+}
+
+export async function pruneAutoRecordings(exemptPaths: string[] = []) {
+ const recordingsDir = await getRecordingsDir();
+ await fs.mkdir(recordingsDir, { recursive: true });
+ const protectedProjectMediaPaths = await loadSavedProjectMediaPaths();
+ const exempt = new Set(
+ [currentVideoPath, ...exemptPaths]
+ .filter((value): value is string => Boolean(value))
+ .map((value) => normalizePath(value)),
+ );
+
+ const entries = await fs.readdir(recordingsDir, { withFileTypes: true });
+ const autoRecordingStats = await Promise.all(
+ entries
+ .filter((entry) => entry.isFile() && /^recording-.*\.(mp4|mov|webm)$/i.test(entry.name))
+ .map(async (entry) => {
+ const filePath = path.join(recordingsDir, entry.name);
+ const stats = await fs.stat(filePath);
+ return { filePath, stats };
+ }),
+ );
+
+ const sorted = autoRecordingStats.sort(
+ (left, right) => right.stats.mtimeMs - left.stats.mtimeMs,
+ );
+ const now = Date.now();
+
+ for (const [index, entry] of sorted.entries()) {
+ const normalizedFilePath = normalizePath(entry.filePath);
+ if (exempt.has(normalizedFilePath)) {
+ continue;
+ }
+
+ if (await hasSiblingProjectFile(entry.filePath)) {
+ continue;
+ }
+
+ const resolvedFilePath = await fs.realpath(entry.filePath).catch(() => normalizedFilePath);
+ if (
+ protectedProjectMediaPaths.has(normalizedFilePath) ||
+ protectedProjectMediaPaths.has(resolvedFilePath)
+ ) {
+ continue;
+ }
+
+ const tooOld = now - entry.stats.mtimeMs > AUTO_RECORDING_MAX_AGE_MS;
+ const overLimit = index >= AUTO_RECORDING_RETENTION_COUNT;
+ if (!tooOld && !overLimit) {
+ continue;
+ }
+
+ try {
+ await fs.rm(entry.filePath, { force: true });
+ await fs.rm(getTelemetryPathForVideo(entry.filePath), { force: true });
+ // Clean up companion audio files left from recording (macOS .m4a, Windows .wav)
+ const base = entry.filePath.replace(/\.(mp4|mov|webm)$/i, "");
+ const companionSuffixes = Array.from(
+ new Set(
+ COMPANION_AUDIO_LAYOUTS.flatMap((layout) => [
+ layout.systemSuffix,
+ layout.micSuffix,
+ ]),
+ ),
+ );
+ for (const suffix of companionSuffixes) {
+ await fs.rm(base + suffix, { force: true }).catch(() => undefined);
+ }
+ } catch (error) {
+ console.warn("Failed to prune old auto recording:", entry.filePath, error);
+ }
+ }
+}
diff --git a/electron/ipc/recording/storagePath.test.ts b/electron/ipc/recording/storagePath.test.ts
new file mode 100644
index 000000000..dced4f52e
--- /dev/null
+++ b/electron/ipc/recording/storagePath.test.ts
@@ -0,0 +1,53 @@
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { resolveRecordedVideoStoragePath } from "./storagePath";
+
+describe("resolveRecordedVideoStoragePath", () => {
+ const recordingsDir = path.resolve("recordings-root");
+
+ it.each([
+ "recording-0.webm",
+ "recording-1720588800000.mp4",
+ "recording-1720588800000-webcam.webm",
+ "recording-1720588800000-webcam.mp4",
+ ])("accepts an app-generated recording name: %s", (fileName) => {
+ expect(resolveRecordedVideoStoragePath(recordingsDir, fileName)).toBe(
+ path.resolve(recordingsDir, fileName),
+ );
+ });
+
+ it.each([
+ "",
+ "../recording-1.webm",
+ "..\\recording-1.webm",
+ "nested/recording-1.webm",
+ "nested\\recording-1.webm",
+ "/tmp/recording-1.webm",
+ "C:\\temp\\recording-1.webm",
+ "\\\\server\\share\\recording-1.webm",
+ "recording-1.webm:payload",
+ "recording-1.webm\n",
+ "recording-1.webm\0",
+ "recording--1.webm",
+ "recording-1.5.webm",
+ "recording-1.mov",
+ "other-1.webm",
+ "recording-1-WEBCAM.webm",
+ ])("rejects an untrusted recording name: %s", (fileName) => {
+ expect(() => resolveRecordedVideoStoragePath(recordingsDir, fileName)).toThrow(
+ "Invalid recording file name",
+ );
+ });
+
+ it.each([
+ { label: "undefined", value: undefined },
+ { label: "null", value: null },
+ { label: "number", value: 1 },
+ { label: "object", value: {} },
+ { label: "array", value: [] },
+ ])("rejects a non-string recording name: $label", ({ value }) => {
+ expect(() => resolveRecordedVideoStoragePath(recordingsDir, value)).toThrow(
+ "Invalid recording file name",
+ );
+ });
+});
diff --git a/electron/ipc/recording/storagePath.ts b/electron/ipc/recording/storagePath.ts
new file mode 100644
index 000000000..12c3484f6
--- /dev/null
+++ b/electron/ipc/recording/storagePath.ts
@@ -0,0 +1,24 @@
+import path from "node:path";
+
+const RECORDED_VIDEO_FILE_NAME = /^recording-[0-9]+(?:-webcam)?\.(?:webm|mp4)$/;
+
+export function resolveRecordedVideoStoragePath(recordingsDir: string, fileName: unknown): string {
+ if (typeof fileName !== "string" || RECORDED_VIDEO_FILE_NAME.exec(fileName)?.[0] !== fileName) {
+ throw new Error("Invalid recording file name");
+ }
+
+ const resolvedRecordingsDir = path.resolve(recordingsDir);
+ const candidatePath = path.resolve(resolvedRecordingsDir, fileName);
+ const relativePath = path.relative(resolvedRecordingsDir, candidatePath);
+
+ if (
+ relativePath.length === 0 ||
+ relativePath === ".." ||
+ relativePath.startsWith(`..${path.sep}`) ||
+ path.isAbsolute(relativePath)
+ ) {
+ throw new Error("Invalid recording file name");
+ }
+
+ return candidatePath;
+}
diff --git a/electron/ipc/recording/windows.test.ts b/electron/ipc/recording/windows.test.ts
new file mode 100644
index 000000000..73a1e0c24
--- /dev/null
+++ b/electron/ipc/recording/windows.test.ts
@@ -0,0 +1,102 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { setWindowsCaptureOutputBuffer, setWindowsCaptureTargetPath } from "../state";
+import { waitForWindowsCaptureStop } from "./windows";
+
+vi.mock("electron", () => ({
+ app: {
+ getPath: () => "C:\\RecordlyTest",
+ },
+ BrowserWindow: {
+ getAllWindows: () => [],
+ },
+}));
+
+class FakeCaptureProcess extends EventEmitter {
+ stdout = new PassThrough();
+ stderr = new PassThrough();
+ stdin = new PassThrough();
+ killed = false;
+
+ kill = vi.fn(() => {
+ this.killed = true;
+ return true;
+ });
+}
+
+describe("waitForWindowsCaptureStop", () => {
+ beforeEach(() => {
+ setWindowsCaptureOutputBuffer("");
+ setWindowsCaptureTargetPath(null);
+ });
+
+ it("resolves the helper output path when the process closes cleanly", async () => {
+ const proc = new FakeCaptureProcess();
+ setWindowsCaptureOutputBuffer("Recording stopped. Output path: C:\\Recordly\\capture.mp4");
+
+ const stopped = waitForWindowsCaptureStop(
+ proc as unknown as Parameters[0],
+ 1000,
+ );
+ proc.emit("close", 0);
+
+ await expect(stopped).resolves.toBe("C:\\Recordly\\capture.mp4");
+ expect(proc.kill).not.toHaveBeenCalled();
+ });
+
+ it("resolves the fallback target path when the helper closes cleanly without output path", async () => {
+ const proc = new FakeCaptureProcess();
+ setWindowsCaptureOutputBuffer("Recording stopped without output path");
+ setWindowsCaptureTargetPath("C:\\Recordly\\fallback.mp4");
+
+ const stopped = waitForWindowsCaptureStop(
+ proc as unknown as Parameters[0],
+ 1000,
+ );
+ proc.emit("close", 0);
+
+ await expect(stopped).resolves.toBe("C:\\Recordly\\fallback.mp4");
+ expect(proc.kill).not.toHaveBeenCalled();
+ });
+
+ it("rejects with helper output when the helper exits with a non-zero code", async () => {
+ const proc = new FakeCaptureProcess();
+ setWindowsCaptureOutputBuffer("Encoder error: insufficient memory");
+
+ const stopped = waitForWindowsCaptureStop(
+ proc as unknown as Parameters[0],
+ 1000,
+ );
+ proc.emit("close", 1);
+
+ await expect(stopped).rejects.toThrow("Encoder error: insufficient memory");
+ expect(proc.kill).not.toHaveBeenCalled();
+ });
+
+ it("rejects when the helper emits an error", async () => {
+ const proc = new FakeCaptureProcess();
+ const error = new Error("spawn failed");
+
+ const stopped = waitForWindowsCaptureStop(
+ proc as unknown as Parameters[0],
+ 1000,
+ );
+ proc.emit("error", error);
+
+ await expect(stopped).rejects.toBe(error);
+ expect(proc.kill).not.toHaveBeenCalled();
+ });
+
+ it("kills the helper and rejects when stop never completes", async () => {
+ const proc = new FakeCaptureProcess();
+
+ await expect(
+ waitForWindowsCaptureStop(
+ proc as unknown as Parameters[0],
+ 5,
+ ),
+ ).rejects.toThrow("Timed out waiting for native Windows capture to stop");
+ expect(proc.kill).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/electron/ipc/recording/windows.ts b/electron/ipc/recording/windows.ts
new file mode 100644
index 000000000..650cdca98
--- /dev/null
+++ b/electron/ipc/recording/windows.ts
@@ -0,0 +1,267 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import { BrowserWindow } from "electron";
+import { getWindowsCaptureExePath } from "../paths/binaries";
+import {
+ selectedSource,
+ setWindowsCaptureProcess,
+ setWindowsCaptureStopRequested,
+ setWindowsNativeCaptureActive,
+ windowsCaptureOutputBuffer,
+ windowsCaptureStopRequested,
+ windowsCaptureTargetPath,
+ windowsNativeCaptureActive,
+} from "../state";
+import { AudioSyncAdjustment } from "../types";
+import { moveFileWithOverwrite } from "../utils";
+import { emitRecordingInterrupted } from "./events";
+
+const WINDOWS_CAPTURE_STOP_TIMEOUT_MS = 45_000;
+
+export type NativeWindowsVideoPaddingResult = {
+ padded: boolean;
+ durationSeconds: number;
+ containerDurationSeconds: number;
+ targetDurationSeconds: number;
+ padDurationSeconds: number;
+};
+
+export type NativeWindowsAudioMuxResult = {
+ muxed: boolean;
+ videoDurationSeconds: number;
+ muxTimeoutMs: number;
+ audioInputs: string[];
+ audio: Record<
+ string,
+ {
+ path: string;
+ sizeBytes: number;
+ durationSeconds: number;
+ startDelayMs: number | null;
+ adjustment: AudioSyncAdjustment;
+ }
+ >;
+ outputPath?: string;
+ keptAudioSidecars?: boolean;
+};
+
+export async function isNativeWindowsCaptureAvailable(): Promise {
+ if (process.platform !== "win32") return false;
+
+ const os = await import("node:os");
+ const [major, , build] = os.release().split(".").map(Number);
+ const supported = major >= 10 && build >= 19041;
+ if (!supported) return false;
+
+ try {
+ await fs.access(getWindowsCaptureExePath(), fsConstants.X_OK);
+ } catch {
+ return false;
+ }
+
+ return true;
+}
+
+export function waitForWindowsCaptureStart(proc: ChildProcessWithoutNullStreams) {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ cleanup();
+ reject(new Error("Timed out waiting for native Windows capture to start"));
+ }, 12000);
+
+ let stdoutBuffer = "";
+ const onStdout = (chunk: Buffer) => {
+ stdoutBuffer += chunk.toString();
+ if (stdoutBuffer.includes("Recording started")) {
+ cleanup();
+ resolve();
+ }
+ };
+
+ const onError = (error: Error) => {
+ cleanup();
+ reject(error);
+ };
+
+ const onExit = (code: number | null) => {
+ cleanup();
+ reject(
+ new Error(
+ windowsCaptureOutputBuffer.trim() ||
+ `Native Windows capture exited before recording started (code ${code ?? "unknown"})`,
+ ),
+ );
+ };
+
+ const cleanup = () => {
+ clearTimeout(timer);
+ proc.stdout.off("data", onStdout);
+ proc.off("error", onError);
+ proc.off("exit", onExit);
+ };
+
+ proc.stdout.on("data", onStdout);
+ proc.once("error", onError);
+ proc.once("exit", onExit);
+ });
+}
+
+export function waitForWindowsCaptureStop(
+ proc: ChildProcessWithoutNullStreams,
+ timeoutMs = WINDOWS_CAPTURE_STOP_TIMEOUT_MS,
+) {
+ return new Promise((resolve, reject) => {
+ let settled = false;
+ const finish = (callback: () => void) => {
+ if (settled) return;
+ settled = true;
+ cleanup();
+ callback();
+ };
+
+ const timer = setTimeout(() => {
+ finish(() => {
+ try {
+ if (!proc.killed) proc.kill();
+ } catch {
+ // The process may already be gone; the caller only needs the timeout error.
+ }
+ reject(new Error("Timed out waiting for native Windows capture to stop"));
+ });
+ }, timeoutMs);
+
+ const onClose = (code: number | null) => {
+ finish(() => {
+ const match = windowsCaptureOutputBuffer.match(
+ /Recording stopped\. Output path: (.+)/,
+ );
+ if (match?.[1]) {
+ resolve(match[1].trim());
+ return;
+ }
+ if (code === 0 && windowsCaptureTargetPath) {
+ resolve(windowsCaptureTargetPath);
+ return;
+ }
+ reject(
+ new Error(
+ windowsCaptureOutputBuffer.trim() ||
+ `Native Windows capture exited with code ${code ?? "unknown"}`,
+ ),
+ );
+ });
+ };
+
+ const onError = (error: Error) => {
+ finish(() => {
+ reject(error);
+ });
+ };
+
+ const cleanup = () => {
+ clearTimeout(timer);
+ proc.off("close", onClose);
+ proc.off("error", onError);
+ };
+
+ proc.once("close", onClose);
+ proc.once("error", onError);
+ });
+}
+
+export function attachWindowsCaptureLifecycle(proc: ChildProcessWithoutNullStreams) {
+ proc.once("close", () => {
+ const wasActive = windowsNativeCaptureActive;
+ setWindowsCaptureProcess(null);
+
+ if (!wasActive || windowsCaptureStopRequested) {
+ return;
+ }
+
+ setWindowsNativeCaptureActive(false);
+ setWindowsCaptureStopRequested(false);
+
+ const sourceName = selectedSource?.name ?? "Screen";
+ BrowserWindow.getAllWindows().forEach((window) => {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-state-changed", {
+ recording: false,
+ sourceName,
+ });
+ }
+ });
+
+ emitRecordingInterrupted("capture-stopped", "Recording stopped unexpectedly.");
+ });
+}
+
+export async function muxNativeWindowsVideoWithAudio(
+ videoPath: string,
+ systemAudioPath: string | null,
+ micAudioPath: string | null,
+): Promise {
+ const start = Date.now();
+ console.log("[PERF:MAIN] muxNativeWindowsVideoWithAudio: STARTED");
+ const audio: NativeWindowsAudioMuxResult["audio"] = {};
+ const audioInputs: string[] = [];
+
+ const videoPathWithoutExt = videoPath.replace(/\.[^.]+$/u, "");
+
+ // Optimization: instead of heavy FFmpeg muxing, we just move the audio sidecars
+ // to their final companion paths so the editor can find them as separate tracks.
+ if (systemAudioPath) {
+ const finalSystemPath = `${videoPathWithoutExt}.system.wav`;
+ try {
+ const stat = await fs.stat(systemAudioPath);
+ if (stat.size > 0) {
+ if (systemAudioPath !== finalSystemPath) {
+ await moveFileWithOverwrite(systemAudioPath, finalSystemPath);
+ }
+ audioInputs.push("system");
+ audio.system = {
+ path: finalSystemPath,
+ sizeBytes: stat.size,
+ durationSeconds: 0,
+ startDelayMs: null,
+ adjustment: { mode: "none", delayMs: 0, tempoRatio: 1, durationDeltaMs: 0 },
+ };
+ }
+ } catch (err) {
+ console.error(`[mux-win] Failed to handle system audio:`, err);
+ }
+ }
+
+ if (micAudioPath) {
+ const finalMicPath = `${videoPathWithoutExt}.mic.wav`;
+ try {
+ const stat = await fs.stat(micAudioPath);
+ if (stat.size > 0) {
+ if (micAudioPath !== finalMicPath) {
+ await moveFileWithOverwrite(micAudioPath, finalMicPath);
+ }
+ audioInputs.push("mic");
+ audio.mic = {
+ path: finalMicPath,
+ sizeBytes: stat.size,
+ durationSeconds: 0,
+ startDelayMs: null,
+ adjustment: { mode: "none", delayMs: 0, tempoRatio: 1, durationDeltaMs: 0 },
+ };
+ }
+ } catch (err) {
+ console.error(`[mux-win] Failed to handle mic audio:`, err);
+ }
+ }
+
+ console.log(`[PERF:MAIN] muxNativeWindowsVideoWithAudio: COMPLETED in ${Date.now() - start}ms`);
+
+ return {
+ muxed: false,
+ videoDurationSeconds: 0, // No longer needed here
+ muxTimeoutMs: 0,
+ audioInputs,
+ audio,
+ keptAudioSidecars: true,
+ };
+}
diff --git a/electron/ipc/recording/windowsFallbacks.test.ts b/electron/ipc/recording/windowsFallbacks.test.ts
new file mode 100644
index 000000000..e1c567522
--- /dev/null
+++ b/electron/ipc/recording/windowsFallbacks.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ shouldStartWindowsBrowserMicrophoneFallback,
+ shouldUseWindowsBrowserMicrophoneFallback,
+ WINDOWS_MIC_CAPTURE_MODE_ENV,
+} from "./windowsFallbacks";
+
+describe("shouldUseWindowsBrowserMicrophoneFallback", () => {
+ it("defaults Windows microphone capture to the browser fallback path", () => {
+ expect(shouldStartWindowsBrowserMicrophoneFallback({ capturesMicrophone: true }, {})).toBe(
+ true,
+ );
+ });
+
+ it("can be forced before native capture starts", () => {
+ expect(
+ shouldStartWindowsBrowserMicrophoneFallback(
+ { capturesMicrophone: true },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "browser" },
+ ),
+ ).toBe(true);
+ });
+
+ it("allows lab runs to force native WASAPI microphone capture", () => {
+ expect(
+ shouldStartWindowsBrowserMicrophoneFallback(
+ { capturesMicrophone: true },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "native" },
+ ),
+ ).toBe(false);
+ expect(
+ shouldStartWindowsBrowserMicrophoneFallback(
+ { capturesMicrophone: true },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "wasapi" },
+ ),
+ ).toBe(false);
+ });
+
+ it("does not force fallback when microphone capture was not requested", () => {
+ expect(
+ shouldStartWindowsBrowserMicrophoneFallback(
+ { capturesMicrophone: false },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "browser" },
+ ),
+ ).toBe(false);
+ });
+
+ it("returns true when native Windows mic initialization fails", () => {
+ expect(
+ shouldUseWindowsBrowserMicrophoneFallback(
+ "WARNING: Failed to initialize WASAPI mic capture\nRecording started",
+ { capturesMicrophone: true },
+ ),
+ ).toBe(true);
+ });
+
+ it("returns false when microphone capture was not requested", () => {
+ expect(
+ shouldUseWindowsBrowserMicrophoneFallback(
+ "WARNING: Failed to initialize WASAPI mic capture\nRecording started",
+ { capturesMicrophone: false },
+ ),
+ ).toBe(false);
+ });
+
+ it("returns false for a healthy native mic when lab mode forces native capture", () => {
+ expect(
+ shouldUseWindowsBrowserMicrophoneFallback(
+ "Recording started",
+ { capturesMicrophone: true },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "native" },
+ ),
+ ).toBe(false);
+ });
+
+ it("returns true when browser fallback is forced", () => {
+ expect(
+ shouldUseWindowsBrowserMicrophoneFallback(
+ "Recording started",
+ { capturesMicrophone: true },
+ { [WINDOWS_MIC_CAPTURE_MODE_ENV]: "fallback" },
+ ),
+ ).toBe(true);
+ });
+});
diff --git a/electron/ipc/recording/windowsFallbacks.ts b/electron/ipc/recording/windowsFallbacks.ts
new file mode 100644
index 000000000..8a3f581c7
--- /dev/null
+++ b/electron/ipc/recording/windowsFallbacks.ts
@@ -0,0 +1,34 @@
+const WINDOWS_MIC_CAPTURE_INIT_WARNING = "WARNING: Failed to initialize WASAPI mic capture";
+export const WINDOWS_MIC_CAPTURE_MODE_ENV = "RECORDLY_WINDOWS_MIC_CAPTURE";
+
+export function shouldStartWindowsBrowserMicrophoneFallback(
+ options?: { capturesMicrophone?: boolean },
+ env: NodeJS.ProcessEnv = process.env,
+) {
+ if (!options?.capturesMicrophone) {
+ return false;
+ }
+
+ const mode = env[WINDOWS_MIC_CAPTURE_MODE_ENV]?.trim().toLowerCase();
+ if (mode === "native" || mode === "wasapi") {
+ return false;
+ }
+
+ if (!mode) {
+ return true;
+ }
+
+ return mode === "browser" || mode === "fallback" || mode === "renderer";
+}
+
+export function shouldUseWindowsBrowserMicrophoneFallback(
+ captureOutput: string,
+ options?: { capturesMicrophone?: boolean },
+ env: NodeJS.ProcessEnv = process.env,
+) {
+ return (
+ Boolean(options?.capturesMicrophone) &&
+ (shouldStartWindowsBrowserMicrophoneFallback(options, env) ||
+ captureOutput.includes(WINDOWS_MIC_CAPTURE_INIT_WARNING))
+ );
+}
diff --git a/electron/ipc/register/announcements.ts b/electron/ipc/register/announcements.ts
new file mode 100644
index 000000000..c5791e99f
--- /dev/null
+++ b/electron/ipc/register/announcements.ts
@@ -0,0 +1,91 @@
+import { ipcMain } from "electron";
+
+const DEFAULT_ANNOUNCEMENT_FEED_URL =
+ "https://raw.githubusercontent.com/webadderallorg/Recordly/main/announcements.json";
+const ANNOUNCEMENT_FETCH_TIMEOUT_MS = 5_000;
+const ANNOUNCEMENT_CACHE_TTL_MS = 6 * 60 * 60 * 1_000;
+const MAX_ANNOUNCEMENT_FEED_BYTES = 1_000_000;
+
+let cachedFeed: unknown = null;
+let cachedAt = 0;
+let hasCachedResult = false;
+let pendingFetch: Promise | null = null;
+
+function getAnnouncementFeedUrl(): string | null {
+ const configuredUrl = process.env.RECORDLY_ANNOUNCEMENTS_URL?.trim();
+ if (configuredUrl?.toLowerCase() === "off") {
+ return null;
+ }
+
+ const candidate = configuredUrl || DEFAULT_ANNOUNCEMENT_FEED_URL;
+ try {
+ const parsed = new URL(candidate);
+ return parsed.protocol === "https:" && !parsed.username && !parsed.password
+ ? parsed.href
+ : null;
+ } catch {
+ return null;
+ }
+}
+
+async function requestAnnouncementFeed(feedUrl: string): Promise {
+ const controller = new AbortController();
+ const timeout = setTimeout(() => controller.abort(), ANNOUNCEMENT_FETCH_TIMEOUT_MS);
+
+ try {
+ const response = await fetch(feedUrl, {
+ signal: controller.signal,
+ headers: { Accept: "application/json" },
+ redirect: "follow",
+ });
+ if (!response.ok) {
+ throw new Error(`Announcement feed returned HTTP ${response.status}`);
+ }
+ if (new URL(response.url).protocol !== "https:") {
+ throw new Error("Announcement feed redirected to an unsafe URL");
+ }
+
+ const declaredLength = Number(response.headers.get("content-length"));
+ if (Number.isFinite(declaredLength) && declaredLength > MAX_ANNOUNCEMENT_FEED_BYTES) {
+ throw new Error("Announcement feed is too large");
+ }
+
+ const text = await response.text();
+ if (Buffer.byteLength(text, "utf8") > MAX_ANNOUNCEMENT_FEED_BYTES) {
+ throw new Error("Announcement feed is too large");
+ }
+
+ cachedFeed = JSON.parse(text) as unknown;
+ cachedAt = Date.now();
+ hasCachedResult = true;
+ return cachedFeed;
+ } catch (error) {
+ console.warn("Failed to load announcement feed:", error);
+ return cachedFeed;
+ } finally {
+ clearTimeout(timeout);
+ }
+}
+
+function fetchAnnouncementFeed(): Promise {
+ const feedUrl = getAnnouncementFeedUrl();
+ if (!feedUrl) {
+ return Promise.resolve(null);
+ }
+
+ if (hasCachedResult && Date.now() - cachedAt < ANNOUNCEMENT_CACHE_TTL_MS) {
+ return Promise.resolve(cachedFeed);
+ }
+
+ if (!pendingFetch) {
+ pendingFetch = requestAnnouncementFeed(feedUrl).finally(() => {
+ pendingFetch = null;
+ });
+ }
+
+ return pendingFetch;
+}
+
+export function registerAnnouncementHandlers() {
+ ipcMain.handle("announcements:get", fetchAnnouncementFeed);
+}
diff --git a/electron/ipc/register/assets.ts b/electron/ipc/register/assets.ts
new file mode 100644
index 000000000..fae8d708d
--- /dev/null
+++ b/electron/ipc/register/assets.ts
@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { ipcMain } from "electron";
+import { USER_DATA_PATH } from "../../appPaths";
+import { normalizePath } from "../utils";
+import { getAssetRootPath } from "../project/manager";
+
+export function registerAssetHandlers() {
+ async function resolveReadableLocalFilePath(filePath: string) {
+ const normalizedPath = normalizePath(filePath);
+ const resolvedPath = await fs.realpath(normalizedPath).catch(() => normalizedPath);
+ const stats = await fs.stat(resolvedPath);
+ if (!stats.isFile()) {
+ throw new Error("Path is not a readable file");
+ }
+ return normalizePath(resolvedPath);
+ }
+
+ // Generate a tiny thumbnail for a wallpaper image and cache it in userData.
+ // Returns the cached thumbnail as raw JPEG bytes for fast grid rendering.
+ // Serialized to prevent concurrent nativeImage operations from eating memory.
+ const THUMB_SIZE = 96;
+ const thumbCacheDir = path.join(USER_DATA_PATH, "wallpaper-thumbs");
+ let thumbGenerationQueue: Promise = Promise.resolve();
+
+ ipcMain.handle("generate-wallpaper-thumbnail", async (_, filePath: string) => {
+ try {
+ const resolved = await resolveReadableLocalFilePath(filePath);
+
+ // Deterministic cache key from file path + mtime
+ const stat = await fs.stat(resolved);
+ const cacheKey = Buffer.from(`${resolved}:${stat.mtimeMs}`).toString("base64url");
+ const thumbPath = path.join(thumbCacheDir, `${cacheKey}.jpg`);
+
+ // Return cached thumbnail if it exists (no queue needed)
+ if (existsSync(thumbPath)) {
+ const data = await fs.readFile(thumbPath);
+ return { success: true, data };
+ }
+
+ // Serialize nativeImage operations to avoid OOM from concurrent full-res decodes
+ let jpegData: Buffer;
+ const generation = thumbGenerationQueue.then(async () => {
+ const { nativeImage } = await import("electron");
+ const img = nativeImage.createFromPath(resolved);
+ if (img.isEmpty()) {
+ throw new Error("Failed to load image");
+ }
+ const { width, height } = img.getSize();
+ const scale = THUMB_SIZE / Math.min(width, height);
+ const resized = img.resize({
+ width: Math.round(width * scale),
+ height: Math.round(height * scale),
+ quality: "good",
+ });
+ jpegData = resized.toJPEG(70);
+
+ // Cache to disk
+ await fs.mkdir(thumbCacheDir, { recursive: true });
+ await fs.writeFile(thumbPath, jpegData);
+ });
+ // Keep the queue moving even if one fails
+ thumbGenerationQueue = generation.catch(() => undefined);
+ await generation;
+
+ return { success: true, data: jpegData! };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ });
+
+ // Return base path for assets so renderer can resolve file:// paths in production
+ ipcMain.handle("get-asset-base-path", () => {
+ try {
+ const assetPath = getAssetRootPath();
+ return pathToFileURL(`${assetPath}${path.sep}`).toString();
+ } catch (err) {
+ console.error("Failed to resolve asset base path:", err);
+ return null;
+ }
+ });
+
+ ipcMain.handle("list-asset-directory", async (_, relativeDir: string) => {
+ try {
+ const normalizedRelativeDir = String(relativeDir ?? "")
+ .replace(/\\/g, "/")
+ .replace(/^\/+/, "");
+
+ const assetRootPath = path.resolve(getAssetRootPath());
+ const targetDirPath = path.resolve(assetRootPath, normalizedRelativeDir);
+ if (
+ targetDirPath !== assetRootPath &&
+ !targetDirPath.startsWith(`${assetRootPath}${path.sep}`)
+ ) {
+ return { success: false, error: "Invalid asset directory" };
+ }
+
+ const entries = await fs.readdir(targetDirPath, { withFileTypes: true });
+ const files = entries
+ .filter((entry) => entry.isFile())
+ .map((entry) => entry.name)
+ .sort(new Intl.Collator(undefined, { numeric: true, sensitivity: "base" }).compare);
+
+ return { success: true, files };
+ } catch (error) {
+ console.error("Failed to list asset directory:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("read-local-file", async (_, filePath: string) => {
+ try {
+ // Intentionally more permissive than the media-server allowlist: this IPC
+ // is used for direct renderer-side local file reads after the app has
+ // already accepted a path, while URL-based media serving must stay scoped
+ // to approved/app-managed locations. We still canonicalize the path and
+ // require a real on-disk file so this cannot be used to read directories.
+ const resolved = await resolveReadableLocalFilePath(filePath);
+
+ const data = await fs.readFile(resolved);
+ return { success: true, data };
+ } catch (error) {
+ console.error("Failed to read local file:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+}
diff --git a/electron/ipc/register/captions.ts b/electron/ipc/register/captions.ts
new file mode 100644
index 000000000..7dfe5d671
--- /dev/null
+++ b/electron/ipc/register/captions.ts
@@ -0,0 +1,256 @@
+import path from "node:path";
+import { dialog, ipcMain } from "electron";
+import { generateAutoCaptionsFromVideo } from "../captions/generate";
+import {
+ deleteWhisperSmallModel,
+ downloadWhisperSmallModel,
+ getWhisperSmallModelStatus,
+ sendWhisperModelDownloadProgress,
+} from "../captions/whisper";
+import { LEGACY_PROJECT_FILE_EXTENSIONS, PROJECT_FILE_EXTENSION } from "../constants";
+import { hasProjectFileExtension, loadProjectFromPath } from "../project/manager";
+import { setCurrentProjectPath } from "../state";
+import { approveUserPath, getRecordingsDir } from "../utils";
+
+const VIDEO_FILE_EXTENSIONS = ["webm", "mp4", "mov", "avi", "mkv"];
+const PROJECT_FILE_EXTENSIONS = [PROJECT_FILE_EXTENSION, ...LEGACY_PROJECT_FILE_EXTENSIONS];
+
+type OpenVideoFilePickerOptions = {
+ includeProjects?: boolean;
+};
+
+export function registerCaptionHandlers() {
+ ipcMain.handle("open-video-file-picker", async (_, options?: OpenVideoFilePickerOptions) => {
+ try {
+ const includeProjects = Boolean(options?.includeProjects);
+ const recordingsDir = await getRecordingsDir();
+ const result = await dialog.showOpenDialog({
+ title: includeProjects ? "Import Media or Recordly Project" : "Select Video File",
+ defaultPath: recordingsDir,
+ filters: [
+ ...(includeProjects
+ ? [
+ {
+ name: "Media or Recordly Projects",
+ extensions: [
+ ...VIDEO_FILE_EXTENSIONS,
+ ...PROJECT_FILE_EXTENSIONS,
+ ],
+ },
+ ]
+ : []),
+ { name: "Video Files", extensions: VIDEO_FILE_EXTENSIONS },
+ ...(includeProjects
+ ? [{ name: "Recordly Projects", extensions: PROJECT_FILE_EXTENSIONS }]
+ : []),
+ { name: "All Files", extensions: ["*"] },
+ ],
+ properties: ["openFile"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true };
+ }
+
+ const selectedPath = result.filePaths[0];
+
+ if (includeProjects && hasProjectFileExtension(selectedPath)) {
+ const projectResult = await loadProjectFromPath(selectedPath);
+ return projectResult.success
+ ? { ...projectResult, kind: "project" }
+ : projectResult;
+ }
+
+ approveUserPath(selectedPath);
+ setCurrentProjectPath(null);
+ return {
+ success: true,
+ kind: "media",
+ path: selectedPath,
+ extension: path.extname(selectedPath).replace(/^\./, "").toLowerCase(),
+ };
+ } catch (error) {
+ console.error("Failed to open file picker:", error);
+ return {
+ success: false,
+ message: "Failed to open file picker",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("open-audio-file-picker", async () => {
+ try {
+ const result = await dialog.showOpenDialog({
+ title: "Select Audio File",
+ filters: [
+ {
+ name: "Audio Files",
+ extensions: ["mp3", "wav", "aac", "m4a", "flac", "ogg"],
+ },
+ { name: "All Files", extensions: ["*"] },
+ ],
+ properties: ["openFile"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true };
+ }
+
+ approveUserPath(result.filePaths[0]);
+ return {
+ success: true,
+ path: result.filePaths[0],
+ };
+ } catch (error) {
+ console.error("Failed to open audio file picker:", error);
+ return {
+ success: false,
+ message: "Failed to open audio file picker",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("open-whisper-executable-picker", async () => {
+ try {
+ const result = await dialog.showOpenDialog({
+ title: "Select Whisper Executable",
+ filters: [
+ {
+ name: "Executables",
+ extensions: process.platform === "win32" ? ["exe", "cmd", "bat"] : ["*"],
+ },
+ { name: "All Files", extensions: ["*"] },
+ ],
+ properties: ["openFile"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true };
+ }
+
+ approveUserPath(result.filePaths[0]);
+ return { success: true, path: result.filePaths[0] };
+ } catch (error) {
+ console.error("Failed to open Whisper executable picker:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("open-whisper-model-picker", async () => {
+ try {
+ const result = await dialog.showOpenDialog({
+ title: "Select Whisper Model",
+ filters: [
+ { name: "Whisper Models", extensions: ["bin"] },
+ { name: "All Files", extensions: ["*"] },
+ ],
+ properties: ["openFile"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true };
+ }
+
+ approveUserPath(result.filePaths[0]);
+ return { success: true, path: result.filePaths[0] };
+ } catch (error) {
+ console.error("Failed to open Whisper model picker:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("get-whisper-small-model-status", async () => {
+ try {
+ return await getWhisperSmallModelStatus();
+ } catch (error) {
+ return { success: false, exists: false, path: null, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("download-whisper-small-model", async (event) => {
+ try {
+ const existing = await getWhisperSmallModelStatus();
+ if (existing.exists) {
+ sendWhisperModelDownloadProgress(event.sender, {
+ status: "downloaded",
+ progress: 100,
+ path: existing.path,
+ });
+ return { success: true, path: existing.path, alreadyDownloaded: true };
+ }
+
+ const modelPath = await downloadWhisperSmallModel(event.sender);
+ return { success: true, path: modelPath };
+ } catch (error) {
+ console.error("Failed to download Whisper small model:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("delete-whisper-small-model", async (event) => {
+ try {
+ await deleteWhisperSmallModel();
+ sendWhisperModelDownloadProgress(event.sender, {
+ status: "idle",
+ progress: 0,
+ path: null,
+ });
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to delete Whisper small model:", error);
+ // Verify whether the file was actually removed despite the error
+ const status = await getWhisperSmallModelStatus();
+ if (!status.exists) {
+ // File is gone — treat as success
+ sendWhisperModelDownloadProgress(event.sender, {
+ status: "idle",
+ progress: 0,
+ path: null,
+ });
+ return { success: true };
+ }
+ sendWhisperModelDownloadProgress(event.sender, {
+ status: "error",
+ progress: 0,
+ path: null,
+ error: String(error),
+ });
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle(
+ "generate-auto-captions",
+ async (
+ _,
+ options: {
+ videoPath: string;
+ whisperExecutablePath: string;
+ whisperModelPath: string;
+ language?: string;
+ },
+ ) => {
+ try {
+ const result = await generateAutoCaptionsFromVideo(options);
+ return {
+ success: true,
+ cues: result.cues,
+ message:
+ result.audioSourceLabel === "recording"
+ ? `Generated ${result.cues.length} caption cues.`
+ : `Generated ${result.cues.length} caption cues from the ${result.audioSourceLabel}.`,
+ };
+ } catch (error) {
+ console.error("Failed to generate auto captions:", error);
+ return {
+ success: false,
+ error: String(error),
+ message:
+ error instanceof Error ? error.message : "Failed to generate auto captions",
+ };
+ }
+ },
+ );
+}
diff --git a/electron/ipc/register/export.test.ts b/electron/ipc/register/export.test.ts
new file mode 100644
index 000000000..df1e9d857
--- /dev/null
+++ b/electron/ipc/register/export.test.ts
@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("electron", () => ({
+ app: {
+ getAppPath: () => process.cwd(),
+ getPath: () => process.env.TEMP ?? process.cwd(),
+ isPackaged: false,
+ },
+ BrowserWindow: {
+ fromWebContents: () => null,
+ },
+ dialog: {
+ showSaveDialog: vi.fn(),
+ },
+ ipcMain: {
+ handle: vi.fn(),
+ },
+ powerSaveBlocker: {
+ isStarted: () => true,
+ start: () => 1,
+ stop: vi.fn(),
+ },
+}));
+
+vi.mock("../ffmpeg/binary", () => ({
+ getFfmpegBinaryPath: () => "ffmpeg",
+}));
+
+import { moveExportedTempFile } from "./export";
+
+const tempDirs: string[] = [];
+
+async function makeTempDir() {
+ const dir = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-export-move-"));
+ tempDirs.push(dir);
+ return dir;
+}
+
+afterEach(async () => {
+ vi.restoreAllMocks();
+ await Promise.allSettled(
+ tempDirs.splice(0).map((dir) => fs.rm(dir, { force: true, recursive: true })),
+ );
+});
+
+describe("moveExportedTempFile", () => {
+ it("moves an app-managed export temp file to the selected destination", async () => {
+ const dir = await makeTempDir();
+ const tempPath = path.join(dir, "export-temp.mp4");
+ const destinationPath = path.join(dir, "export-final.mp4");
+ await fs.writeFile(tempPath, "recordly-export");
+
+ await moveExportedTempFile(tempPath, destinationPath);
+
+ await expect(fs.readFile(destinationPath, "utf8")).resolves.toBe("recordly-export");
+ await expect(fs.access(tempPath)).rejects.toThrow();
+ });
+
+ it("falls back when Windows reports the destination already exists during initial rename", async () => {
+ const dir = await makeTempDir();
+ const tempPath = path.join(dir, "export-temp.mp4");
+ const destinationPath = path.join(dir, "export-final.mp4");
+ await fs.writeFile(tempPath, "new-export");
+ await fs.writeFile(destinationPath, "previous-export");
+
+ const originalRename = fs.rename.bind(fs);
+ const renameSpy = vi.spyOn(fs, "rename");
+ renameSpy.mockImplementation(async (from, to) => {
+ if (from === tempPath && to === destinationPath) {
+ const error = new Error("destination exists") as NodeJS.ErrnoException;
+ error.code = "EEXIST";
+ throw error;
+ }
+
+ return originalRename(from, to);
+ });
+
+ await moveExportedTempFile(tempPath, destinationPath);
+
+ await expect(fs.readFile(destinationPath, "utf8")).resolves.toBe("new-export");
+ await expect(fs.access(tempPath)).rejects.toThrow();
+ });
+});
diff --git a/electron/ipc/register/export.ts b/electron/ipc/register/export.ts
new file mode 100644
index 000000000..2eabb9786
--- /dev/null
+++ b/electron/ipc/register/export.ts
@@ -0,0 +1,1077 @@
+import type { ChildProcessByStdio } from "node:child_process";
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { Readable, Writable } from "node:stream";
+import type { SaveDialogOptions } from "electron";
+import { app, BrowserWindow, dialog, ipcMain } from "electron";
+import {
+ parseCaptionSidecarPayload,
+ type CaptionSidecarPayload,
+ withCaptionSidecarMessage,
+ writeCaptionSidecarsBestEffort,
+} from "./exportCaptionSidecars";
+import {
+ closeExportStream,
+ isOwnedExportPath,
+ openExportStream,
+ registerOwnedExportPath,
+ releaseOwnedExportPath,
+ writeToExportStream,
+} from "../export/exportStream";
+import {
+ enqueueNativeVideoExportFrameWrite,
+ enqueueNativeVideoExportFrameWrites,
+ exportNativeStaticLayoutVideo,
+ flushNativeVideoExportPendingWriteRequests,
+ getNativeExportCapabilities,
+ getNativeVideoExportMaxQueuedWriteBytes,
+ getNativeVideoExportSessionError,
+ isHardwareAcceleratedVideoEncoder,
+ isIgnorableNativeVideoExportStreamError,
+ muxExportedVideoAudioBuffer,
+ muxNativeVideoExportAudio,
+ type NativeStaticLayoutExportOptions,
+ type NativeVideoExportSession,
+ nativeStaticLayoutExportSessions,
+ nativeVideoExportSessions,
+ probeNativeVideoMetadata,
+ removeTemporaryExportFile,
+ resolveNativeVideoEncoder,
+ sendNativeVideoExportWriteFrameResult,
+ settleNativeVideoExportWriteFrameRequest,
+} from "../export/native-video";
+import { getFfmpegBinaryPath } from "../ffmpeg/binary";
+import {
+ buildNativeH264StreamExportArgs,
+ buildNativeVideoExportArgs,
+ getNativeVideoInputByteSize,
+ type NativeExportEncodingMode,
+ type NativeVideoExportFinishOptions,
+} from "../nativeVideoExport";
+import { isAllowedLocalReadPath, resolveApprovedLocalMediaPath } from "../project/manager";
+import { approveUserPath } from "../utils";
+
+function getPartialExportDestinationPath(destinationPath: string) {
+ const parsed = path.parse(destinationPath);
+ const suffix = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+ return path.join(parsed.dir, `.recordly-partial-${parsed.name}-${suffix}${parsed.ext}`);
+}
+
+const MAX_IN_MEMORY_EXPORT_BYTES = 0x7fffffff;
+
+function getInMemoryExportTooLargeMessage(byteLength: number) {
+ if (byteLength <= MAX_IN_MEMORY_EXPORT_BYTES) {
+ return null;
+ }
+
+ return "Export is too large for the legacy in-memory save path. Please retry with temp-file streaming enabled.";
+}
+
+export async function moveExportedTempFile(tempPath: string, destinationPath: string) {
+ await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+ try {
+ await fs.rename(tempPath, destinationPath);
+ return;
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (code !== "EXDEV" && code !== "EPERM" && code !== "ENOTEMPTY" && code !== "EEXIST") {
+ throw error;
+ }
+ // Cross-device or Windows permission quirks — fall back to copy + unlink so
+ // exporting to a different volume still works.
+ }
+
+ const partialDestinationPath = getPartialExportDestinationPath(destinationPath);
+ try {
+ await fs.copyFile(tempPath, partialDestinationPath);
+ try {
+ await fs.rename(partialDestinationPath, destinationPath);
+ } catch (renameError) {
+ const code = (renameError as NodeJS.ErrnoException).code;
+ if (code !== "EEXIST" && code !== "EPERM") {
+ throw renameError;
+ }
+
+ const backupDestinationPath = getPartialExportDestinationPath(destinationPath);
+ let movedExistingDestination = false;
+ try {
+ await fs.rename(destinationPath, backupDestinationPath);
+ movedExistingDestination = true;
+ } catch (backupError) {
+ if ((backupError as NodeJS.ErrnoException).code !== "ENOENT") {
+ throw backupError;
+ }
+ }
+
+ try {
+ await fs.rename(partialDestinationPath, destinationPath);
+ } catch (replaceError) {
+ if (movedExistingDestination) {
+ await fs.rename(backupDestinationPath, destinationPath).catch(() => undefined);
+ }
+ throw replaceError;
+ }
+
+ if (movedExistingDestination) {
+ await fs.rm(backupDestinationPath, { force: true }).catch((cleanupError) => {
+ console.warn(
+ `[export] Failed to remove backup file after replace (${backupDestinationPath}):`,
+ cleanupError,
+ );
+ });
+ }
+ }
+ try {
+ await fs.rm(tempPath, { force: true });
+ } catch (unlinkError) {
+ // Copy succeeded, so the export itself is safe; surface the leaked temp
+ // path instead of silently swallowing the failure so operators can
+ // reclaim disk space manually if the OS temp reaper misses it.
+ console.warn(
+ `[export] Failed to remove temp file after cross-volume copy (${tempPath}):`,
+ unlinkError,
+ );
+ }
+ } catch (error) {
+ await fs.rm(partialDestinationPath, { force: true }).catch(() => undefined);
+ throw error;
+ }
+}
+
+async function resolveAllowedReadableFilePath(
+ filePath: string,
+ label: string,
+ options: { mediaOnly?: boolean } = {},
+) {
+ if (typeof filePath !== "string" || filePath.trim().length === 0) {
+ throw new Error(`${label} requires a file path`);
+ }
+
+ if (options.mediaOnly ?? true) {
+ const resolvedMediaPath = await resolveApprovedLocalMediaPath(filePath);
+ if (!resolvedMediaPath) {
+ throw new Error(`${label} is not an approved readable media file`);
+ }
+
+ return resolvedMediaPath;
+ }
+
+ const resolvedPath = path.resolve(filePath);
+ if (!isAllowedLocalReadPath(resolvedPath)) {
+ throw new Error(`${label} is not approved for local reads`);
+ }
+
+ const realPath = await fs.realpath(resolvedPath).catch(() => null);
+ if (!realPath) {
+ throw new Error(`${label} does not exist`);
+ }
+
+ const stat = await fs.stat(realPath).catch(() => null);
+ if (!stat?.isFile()) {
+ throw new Error(`${label} is not a readable file`);
+ }
+
+ if (!isAllowedLocalReadPath(realPath)) {
+ throw new Error(`${label} is not approved for local reads`);
+ }
+
+ return realPath;
+}
+
+async function sanitizeNativeStaticLayoutExportOptions(
+ options: NativeStaticLayoutExportOptions,
+): Promise {
+ const sanitized: NativeStaticLayoutExportOptions = {
+ ...options,
+ inputPath: await resolveAllowedReadableFilePath(options.inputPath, "Native input"),
+ };
+ const mutableOptions = sanitized as unknown as Record;
+
+ for (const [field, label] of [
+ ["backgroundImagePath", "Native background image"],
+ ["webcamInputPath", "Native webcam input"],
+ ["cursorAtlasPath", "Native cursor atlas"],
+ ] as const) {
+ const value = mutableOptions[field];
+ if (typeof value === "string" && value.trim().length > 0) {
+ mutableOptions[field] = await resolveAllowedReadableFilePath(value, label);
+ } else if (value === "" || value === undefined) {
+ mutableOptions[field] = null;
+ } else if (value !== null) {
+ throw new Error(`${label} must be a file path`);
+ }
+ }
+
+ for (const [field, label] of [
+ ["cursorTelemetryPath", "Native cursor telemetry"],
+ ["cursorAtlasMetadataPath", "Native cursor atlas metadata"],
+ ["zoomTelemetryPath", "Native zoom telemetry"],
+ ["timelineMapPath", "Native timeline map"],
+ ] as const) {
+ const value = mutableOptions[field];
+ if (typeof value === "string" && value.trim().length > 0) {
+ mutableOptions[field] = await resolveAllowedReadableFilePath(value, label, {
+ mediaOnly: false,
+ });
+ } else if (value === "" || value === undefined) {
+ mutableOptions[field] = null;
+ } else if (value !== null) {
+ throw new Error(`${label} must be a file path`);
+ }
+ }
+
+ const audioOptions = sanitized.audioOptions;
+ if (audioOptions?.audioSourcePath) {
+ sanitized.audioOptions = {
+ ...audioOptions,
+ audioSourcePath: await resolveAllowedReadableFilePath(
+ audioOptions.audioSourcePath,
+ "Native audio source",
+ ),
+ };
+ }
+
+ return sanitized;
+}
+
+function isTempPathSafe(tempPath: string): boolean {
+ const tempRoot = path.resolve(app.getPath("temp"));
+ const candidate = path.resolve(tempPath);
+ if (candidate === tempRoot) {
+ return false;
+ }
+ const withSep = tempRoot.endsWith(path.sep) ? tempRoot : tempRoot + path.sep;
+ return candidate.startsWith(withSep);
+}
+
+export function registerExportHandlers() {
+ ipcMain.handle(
+ "native-video-export-start",
+ async (
+ event,
+ options: {
+ width: number;
+ height: number;
+ frameRate: number;
+ bitrate: number;
+ encodingMode: NativeExportEncodingMode;
+ inputMode?: "rawvideo" | "h264-stream";
+ },
+ ) => {
+ try {
+ if (options.width % 2 !== 0 || options.height % 2 !== 0) {
+ throw new Error("Native export requires even output dimensions");
+ }
+
+ const ffmpegPath = getFfmpegBinaryPath();
+ const inputMode = options.inputMode ?? "rawvideo";
+ const sessionId = `recordly-export-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+ const outputPath = path.join(app.getPath("temp"), `${sessionId}.mp4`);
+
+ let encoderName: string;
+ let ffmpegArgs: string[];
+
+ if (inputMode === "h264-stream") {
+ // Pre-encoded H.264 Annex B from browser VideoEncoder — just stream-copy into MP4
+ encoderName = "h264-stream-copy";
+ ffmpegArgs = buildNativeH264StreamExportArgs({
+ frameRate: options.frameRate,
+ outputPath,
+ });
+ } else {
+ encoderName = await resolveNativeVideoEncoder(ffmpegPath, options.encodingMode);
+ ffmpegArgs = buildNativeVideoExportArgs(encoderName, options, outputPath);
+ }
+
+ const ffmpegProcess = spawn(ffmpegPath, ffmpegArgs, {
+ stdio: ["pipe", "ignore", "pipe"],
+ }) as ChildProcessByStdio;
+ // For rawvideo, frames are a fixed RGBA size. For h264-stream, chunks are variable.
+ const inputByteSize =
+ inputMode === "rawvideo"
+ ? getNativeVideoInputByteSize(options.width, options.height)
+ : 0;
+
+ const session: NativeVideoExportSession = {
+ ffmpegProcess,
+ outputPath,
+ inputByteSize,
+ inputMode,
+ maxQueuedWriteBytes:
+ inputMode === "h264-stream"
+ ? 32 * 1024 * 1024
+ : getNativeVideoExportMaxQueuedWriteBytes(inputByteSize),
+ stderrOutput: "",
+ encoderName,
+ processError: null,
+ stdinError: null,
+ terminating: false,
+ writeSequence: Promise.resolve(),
+ sender: event.sender,
+ pendingWriteRequestIds: new Set(),
+ completionPromise: new Promise((resolve, reject) => {
+ ffmpegProcess.once("error", (error) => {
+ const processError =
+ error instanceof Error ? error : new Error(String(error));
+ if (session.terminating) {
+ resolve();
+ return;
+ }
+
+ session.processError = processError;
+ reject(processError);
+ });
+ ffmpegProcess.stdin.once("error", (error) => {
+ const stdinError =
+ error instanceof Error ? error : new Error(String(error));
+ if (
+ session.terminating &&
+ isIgnorableNativeVideoExportStreamError(stdinError)
+ ) {
+ return;
+ }
+
+ session.stdinError = stdinError;
+ });
+ ffmpegProcess.once("close", (code, signal) => {
+ if (session.terminating) {
+ resolve();
+ return;
+ }
+
+ if (code === 0) {
+ resolve();
+ return;
+ }
+
+ reject(
+ new Error(
+ getNativeVideoExportSessionError(
+ session,
+ `FFmpeg exited with code ${code ?? "unknown"}${signal ? ` (signal ${signal})` : ""}`,
+ ),
+ ),
+ );
+ });
+ }),
+ };
+ void session.completionPromise.catch(() => undefined);
+
+ ffmpegProcess.stderr.on("data", (chunk: Buffer) => {
+ session.stderrOutput += chunk.toString();
+ });
+
+ nativeVideoExportSessions.set(sessionId, session);
+
+ console.log(
+ `[native-export] Started ${isHardwareAcceleratedVideoEncoder(encoderName) ? "hardware" : "software"} session ${sessionId} with ${encoderName}`,
+ );
+
+ return {
+ success: true,
+ sessionId,
+ encoderName,
+ };
+ } catch (error) {
+ console.error(
+ "[native-export] Failed to start native video export session:",
+ error,
+ );
+ return {
+ success: false,
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("probe-native-video-metadata", async (_, filePath: string) => {
+ try {
+ if (typeof filePath !== "string" || filePath.trim().length === 0) {
+ throw new Error("Native metadata probe requires a file path");
+ }
+
+ const resolvedFilePath = await resolveAllowedReadableFilePath(
+ filePath,
+ "Native metadata probe",
+ );
+ const metadata = await probeNativeVideoMetadata(
+ getFfmpegBinaryPath(),
+ resolvedFilePath,
+ );
+ return {
+ success: true,
+ metadata,
+ };
+ } catch (error) {
+ console.warn("[probe-native-video-metadata] Failed:", error);
+ return {
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("get-native-export-capabilities", async () => {
+ try {
+ return {
+ success: true,
+ capabilities: await getNativeExportCapabilities(),
+ };
+ } catch (error) {
+ console.warn("[native-export-capabilities] Failed:", error);
+ return {
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ });
+
+ ipcMain.handle(
+ "native-static-layout-export",
+ async (event, options: NativeStaticLayoutExportOptions) => {
+ try {
+ if (!options || typeof options.inputPath !== "string") {
+ throw new Error("Native static layout export requires an input path");
+ }
+ const sanitizedOptions = await sanitizeNativeStaticLayoutExportOptions(options);
+
+ const result = await exportNativeStaticLayoutVideo(
+ getFfmpegBinaryPath(),
+ sanitizedOptions,
+ (progress) => {
+ if (event.sender.isDestroyed()) {
+ return;
+ }
+
+ event.sender.send("native-static-layout-export-progress", progress);
+ },
+ );
+ registerOwnedExportPath(result.outputPath);
+ const primaryBackend = result.metrics.chunks[0]?.backend;
+ return {
+ success: true,
+ tempPath: result.outputPath,
+ encoderName:
+ primaryBackend === "nvidia-cuda-compositor"
+ ? "nvidia-cuda-compositor"
+ : primaryBackend === "windows-d3d11-compositor"
+ ? "windows-d3d11-compositor"
+ : result.metrics.chunkCount > 1
+ ? "chunked-h264-nvenc"
+ : "static-layout-h264-nvenc",
+ metrics: result.metrics,
+ };
+ } catch (error) {
+ console.warn("[native-static-layout-export] Failed:", error);
+ return {
+ success: false,
+ error: error instanceof Error ? error.message : String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("native-static-layout-export-cancel", async (_, sessionId: string) => {
+ const session = nativeStaticLayoutExportSessions.get(sessionId);
+ if (!session) {
+ return { success: true };
+ }
+
+ session.terminating = true;
+ try {
+ session.currentProcess?.kill("SIGKILL");
+ } catch {
+ // Process may already be closed.
+ }
+
+ return { success: true };
+ });
+
+ ipcMain.on(
+ "native-video-export-write-frames-async",
+ (
+ event,
+ payload: {
+ sessionId: string;
+ requestId: number;
+ frameDataList: Uint8Array[];
+ },
+ ) => {
+ const sessionId = payload?.sessionId;
+ const requestId = payload?.requestId;
+ const frameDataList = payload?.frameDataList;
+
+ if (
+ typeof sessionId !== "string" ||
+ typeof requestId !== "number" ||
+ !Array.isArray(frameDataList) ||
+ frameDataList.length === 0
+ ) {
+ return;
+ }
+
+ const session = nativeVideoExportSessions.get(sessionId);
+ if (!session) {
+ sendNativeVideoExportWriteFrameResult(event.sender, sessionId, requestId, {
+ success: false,
+ error: "Invalid native export session",
+ });
+ return;
+ }
+
+ session.sender = event.sender;
+ session.pendingWriteRequestIds.add(requestId);
+
+ if (session.terminating) {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: "Native video export session was cancelled",
+ });
+ return;
+ }
+
+ if (
+ session.inputMode !== "h264-stream" &&
+ frameDataList.some((frameData) => frameData.byteLength !== session.inputByteSize)
+ ) {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: "Native video export batch contained invalid frame sizes",
+ });
+ return;
+ }
+
+ void enqueueNativeVideoExportFrameWrites(session, frameDataList)
+ .then(() => {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: true,
+ });
+ })
+ .catch((error) => {
+ session.stdinError = error instanceof Error ? error : new Error(String(error));
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: getNativeVideoExportSessionError(
+ session,
+ session.stdinError.message,
+ ),
+ });
+ });
+ },
+ );
+
+ ipcMain.on(
+ "native-video-export-write-frame-async",
+ (
+ event,
+ payload: {
+ sessionId: string;
+ requestId: number;
+ frameData: Uint8Array;
+ },
+ ) => {
+ const sessionId = payload?.sessionId;
+ const requestId = payload?.requestId;
+ const frameData = payload?.frameData;
+
+ if (typeof sessionId !== "string" || typeof requestId !== "number" || !frameData) {
+ return;
+ }
+
+ const session = nativeVideoExportSessions.get(sessionId);
+ if (!session) {
+ sendNativeVideoExportWriteFrameResult(event.sender, sessionId, requestId, {
+ success: false,
+ error: "Invalid native export session",
+ });
+ return;
+ }
+
+ session.sender = event.sender;
+ session.pendingWriteRequestIds.add(requestId);
+
+ if (session.terminating) {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: "Native video export session was cancelled",
+ });
+ return;
+ }
+
+ if (
+ session.inputMode !== "h264-stream" &&
+ frameData.byteLength !== session.inputByteSize
+ ) {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: `Native video export expected ${session.inputByteSize} bytes per frame but received ${frameData.byteLength}`,
+ });
+ return;
+ }
+
+ void enqueueNativeVideoExportFrameWrite(session, frameData)
+ .then(() => {
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: true,
+ });
+ })
+ .catch((error) => {
+ session.stdinError = error instanceof Error ? error : new Error(String(error));
+ settleNativeVideoExportWriteFrameRequest(sessionId, session, requestId, {
+ success: false,
+ error: getNativeVideoExportSessionError(
+ session,
+ session.stdinError.message,
+ ),
+ });
+ });
+ },
+ );
+
+ ipcMain.handle(
+ "native-video-export-finish",
+ async (_, sessionId: string, options?: NativeVideoExportFinishOptions) => {
+ const session = nativeVideoExportSessions.get(sessionId);
+ if (!session) {
+ return { success: false, error: "Invalid native export session" };
+ }
+
+ try {
+ await session.writeSequence;
+ if (
+ !session.ffmpegProcess.stdin.destroyed &&
+ !session.ffmpegProcess.stdin.writableEnded
+ ) {
+ session.ffmpegProcess.stdin.end();
+ }
+ await session.completionPromise;
+
+ const finalized = await muxNativeVideoExportAudio(
+ session.outputPath,
+ options ?? {},
+ );
+ nativeVideoExportSessions.delete(sessionId);
+ // Register the finalized path so only app-produced paths can flow back
+ // through finalize-exported-video / discard-exported-temp.
+ registerOwnedExportPath(finalized.outputPath);
+ if (finalized.outputPath !== session.outputPath) {
+ // muxNativeVideoExportAudio removes the intermediate on success, but
+ // clear our registry entry defensively in case a future refactor
+ // changes that contract.
+ releaseOwnedExportPath(session.outputPath);
+ }
+
+ // Return a temp path instead of reading the file back into memory so we
+ // never hit V8's per-ArrayBuffer limit on >2 GiB exports. The renderer
+ // uses finalize-exported-video to move the file to its final path.
+ return {
+ success: true,
+ tempPath: finalized.outputPath,
+ encoderName: session.encoderName,
+ metrics: finalized.metrics,
+ };
+ } catch (error) {
+ flushNativeVideoExportPendingWriteRequests(sessionId, session, String(error));
+ nativeVideoExportSessions.delete(sessionId);
+ await removeTemporaryExportFile(session.outputPath);
+ const finalizedSuffix = session.outputPath.replace(/\.mp4$/, "-final.mp4");
+ await removeTemporaryExportFile(finalizedSuffix);
+ return {
+ success: false,
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "mux-exported-video-audio-from-path",
+ async (_, videoPath: string, options?: NativeVideoExportFinishOptions) => {
+ if (typeof videoPath !== "string" || !isOwnedExportPath(videoPath)) {
+ return {
+ success: false,
+ error: "Video path is not an app-managed export temp",
+ };
+ }
+ try {
+ const finalized = await muxNativeVideoExportAudio(videoPath, options ?? {});
+ if (finalized.outputPath !== videoPath) {
+ registerOwnedExportPath(finalized.outputPath);
+ // muxNativeVideoExportAudio removes the intermediate on success, so
+ // the input is no longer owned by the registry after the call
+ // returns.
+ releaseOwnedExportPath(videoPath);
+ }
+ return {
+ success: true,
+ tempPath: finalized.outputPath,
+ metrics: finalized.metrics,
+ };
+ } catch (error) {
+ // Only clean up the input path if it is still an owned temp (i.e.
+ // muxNativeVideoExportAudio failed before consuming it).
+ if (isOwnedExportPath(videoPath)) {
+ await removeTemporaryExportFile(videoPath);
+ releaseOwnedExportPath(videoPath);
+ }
+ return { success: false, error: String(error) };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "mux-exported-video-audio",
+ async (_, videoData: ArrayBuffer, options?: NativeVideoExportFinishOptions) => {
+ try {
+ const sizeError = getInMemoryExportTooLargeMessage(videoData.byteLength);
+ if (sizeError) {
+ return {
+ success: false,
+ error: sizeError,
+ };
+ }
+
+ const result = await muxExportedVideoAudioBuffer(videoData, options ?? {});
+ // Register the muxed output so finalize-exported-video / discard-
+ // exported-temp accept it. Returning a temp path (instead of the
+ // muxed bytes) keeps us off Node's >2 GiB fs.readFile cap and
+ // avoids a redundant copy through the renderer.
+ registerOwnedExportPath(result.outputPath);
+ return {
+ success: true,
+ tempPath: result.outputPath,
+ metrics: result.metrics,
+ };
+ } catch (error) {
+ return {
+ success: false,
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("export-stream-open", async (_event, options?: { extension?: string }) => {
+ try {
+ const result = await openExportStream(options);
+ return { success: true, streamId: result.streamId, tempPath: result.tempPath };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle(
+ "export-stream-write",
+ async (_event, streamId: string, position: number, chunk: Uint8Array) => {
+ try {
+ await writeToExportStream(streamId, position, chunk);
+ return { success: true };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "export-stream-close",
+ async (_event, streamId: string, options?: { abort?: boolean }) => {
+ try {
+ const result = await closeExportStream(streamId, options);
+ return {
+ success: true,
+ tempPath: result.tempPath,
+ bytesWritten: result.bytesWritten,
+ };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ },
+ );
+
+ ipcMain.handle("native-video-export-cancel", async (_, sessionId: string) => {
+ const session = nativeVideoExportSessions.get(sessionId);
+ if (!session) {
+ return { success: true };
+ }
+
+ session.terminating = true;
+ nativeVideoExportSessions.delete(sessionId);
+ flushNativeVideoExportPendingWriteRequests(
+ sessionId,
+ session,
+ "Native video export session was cancelled",
+ );
+
+ try {
+ if (
+ !session.ffmpegProcess.stdin.destroyed &&
+ !session.ffmpegProcess.stdin.writableEnded
+ ) {
+ session.ffmpegProcess.stdin.destroy();
+ }
+ } catch {
+ // Stream may already be closed.
+ }
+
+ try {
+ session.ffmpegProcess.kill("SIGKILL");
+ } catch {
+ // Process may already be closed.
+ }
+
+ await session.completionPromise.catch(() => undefined);
+ await removeTemporaryExportFile(session.outputPath);
+ return { success: true };
+ });
+
+ ipcMain.handle(
+ "save-exported-video",
+ async (
+ event,
+ videoData: ArrayBuffer,
+ fileName: string,
+ captionSidecar?: CaptionSidecarPayload,
+ ) => {
+ try {
+ const sidecarPayload = parseCaptionSidecarPayload(captionSidecar);
+ const sizeError = getInMemoryExportTooLargeMessage(videoData.byteLength);
+ if (sizeError) {
+ return {
+ success: false,
+ message: sizeError,
+ error: sizeError,
+ };
+ }
+
+ // Determine file type from extension
+ const isGif = fileName.toLowerCase().endsWith(".gif");
+ const filters = isGif
+ ? [{ name: "GIF Image", extensions: ["gif"] }]
+ : [{ name: "MP4 Video", extensions: ["mp4"] }];
+ const parentWindow = BrowserWindow.fromWebContents(event.sender);
+ const saveDialogOptions: SaveDialogOptions = {
+ title: isGif ? "Save Exported GIF" : "Save Exported Video",
+ defaultPath: path.join(app.getPath("downloads"), fileName),
+ filters,
+ properties: ["createDirectory", "showOverwriteConfirmation"],
+ };
+
+ const result = parentWindow
+ ? await dialog.showSaveDialog(parentWindow, saveDialogOptions)
+ : await dialog.showSaveDialog(saveDialogOptions);
+
+ if (result.canceled || !result.filePath) {
+ return {
+ success: false,
+ canceled: true,
+ message: "Export canceled",
+ };
+ }
+
+ await fs.writeFile(result.filePath, Buffer.from(videoData));
+ const captionSidecarResult = await writeCaptionSidecarsBestEffort(
+ result.filePath,
+ sidecarPayload,
+ );
+ approveUserPath(result.filePath);
+
+ return {
+ success: true,
+ path: result.filePath,
+ message: withCaptionSidecarMessage(
+ "Video exported successfully",
+ captionSidecarResult,
+ ),
+ };
+ } catch (error) {
+ console.error("Failed to save exported video:", error);
+ return {
+ success: false,
+ message: "Failed to save exported video",
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "write-exported-video-to-path",
+ async (
+ _event,
+ videoData: ArrayBuffer,
+ outputPath: string,
+ captionSidecar?: CaptionSidecarPayload,
+ ) => {
+ try {
+ const sidecarPayload = parseCaptionSidecarPayload(captionSidecar);
+ const sizeError = getInMemoryExportTooLargeMessage(videoData.byteLength);
+ if (sizeError) {
+ return {
+ success: false,
+ message: sizeError,
+ canceled: false,
+ error: sizeError,
+ };
+ }
+
+ const resolvedPath = path.resolve(outputPath);
+ await fs.mkdir(path.dirname(resolvedPath), { recursive: true });
+ await fs.writeFile(resolvedPath, Buffer.from(videoData));
+ const captionSidecarResult = await writeCaptionSidecarsBestEffort(
+ resolvedPath,
+ sidecarPayload,
+ );
+ approveUserPath(resolvedPath);
+
+ return {
+ success: true,
+ path: resolvedPath,
+ message: withCaptionSidecarMessage(
+ "Video exported successfully",
+ captionSidecarResult,
+ ),
+ canceled: false,
+ };
+ } catch (error) {
+ console.error("Failed to write exported video to path:", error);
+ return {
+ success: false,
+ message: "Failed to write exported video",
+ canceled: false,
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "finalize-exported-video",
+ async (
+ event,
+ payload: {
+ tempPath: string;
+ fileName: string;
+ outputPath?: string | null;
+ captionSidecar?: CaptionSidecarPayload;
+ },
+ ) => {
+ const tempPath = payload?.tempPath;
+ const fileName = payload?.fileName;
+ if (typeof tempPath !== "string" || typeof fileName !== "string") {
+ return { success: false, error: "Invalid finalize-exported-video payload" };
+ }
+
+ if (!isTempPathSafe(tempPath) || !isOwnedExportPath(tempPath)) {
+ return {
+ success: false,
+ error: "Temp path is not an app-managed export temp",
+ };
+ }
+
+ try {
+ await fs.access(tempPath);
+ } catch {
+ return {
+ success: false,
+ error: `Exported video temp file is missing: ${tempPath}`,
+ };
+ }
+
+ try {
+ const sidecarPayload = parseCaptionSidecarPayload(payload.captionSidecar);
+ if (payload.outputPath) {
+ const resolvedPath = path.resolve(payload.outputPath);
+ await moveExportedTempFile(tempPath, resolvedPath);
+ releaseOwnedExportPath(tempPath);
+ const captionSidecarResult = await writeCaptionSidecarsBestEffort(
+ resolvedPath,
+ sidecarPayload,
+ );
+ approveUserPath(resolvedPath);
+ return {
+ success: true,
+ path: resolvedPath,
+ canceled: false,
+ message: withCaptionSidecarMessage(
+ "Video exported successfully",
+ captionSidecarResult,
+ ),
+ };
+ }
+
+ const isGif = fileName.toLowerCase().endsWith(".gif");
+ const filters = isGif
+ ? [{ name: "GIF Image", extensions: ["gif"] }]
+ : [{ name: "MP4 Video", extensions: ["mp4"] }];
+ const parentWindow = BrowserWindow.fromWebContents(event.sender);
+ const saveDialogOptions: SaveDialogOptions = {
+ title: isGif ? "Save Exported GIF" : "Save Exported Video",
+ defaultPath: path.join(app.getPath("downloads"), fileName),
+ filters,
+ properties: ["createDirectory", "showOverwriteConfirmation"],
+ };
+
+ const result = parentWindow
+ ? await dialog.showSaveDialog(parentWindow, saveDialogOptions)
+ : await dialog.showSaveDialog(saveDialogOptions);
+
+ if (result.canceled || !result.filePath) {
+ // Leave the temp file in place so the renderer can offer "Save Again"
+ // without re-rendering. The renderer owns cleanup on discard.
+ return {
+ success: false,
+ canceled: true,
+ message: "Export canceled",
+ };
+ }
+
+ await moveExportedTempFile(tempPath, result.filePath);
+ releaseOwnedExportPath(tempPath);
+ const captionSidecarResult = await writeCaptionSidecarsBestEffort(
+ result.filePath,
+ sidecarPayload,
+ );
+ approveUserPath(result.filePath);
+
+ return {
+ success: true,
+ path: result.filePath,
+ canceled: false,
+ message: withCaptionSidecarMessage(
+ "Video exported successfully",
+ captionSidecarResult,
+ ),
+ };
+ } catch (error) {
+ console.error("Failed to finalize exported video:", error);
+ return {
+ success: false,
+ canceled: false,
+ message: "Failed to save exported video",
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("discard-exported-temp", async (_event, tempPath: string) => {
+ if (typeof tempPath !== "string" || tempPath.length === 0) {
+ return { success: false, error: "Invalid temp path" };
+ }
+ if (!isTempPathSafe(tempPath) || !isOwnedExportPath(tempPath)) {
+ return {
+ success: false,
+ error: "Temp path is not an app-managed export temp",
+ };
+ }
+ try {
+ await removeTemporaryExportFile(tempPath);
+ releaseOwnedExportPath(tempPath);
+ return { success: true };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ });
+}
diff --git a/electron/ipc/register/exportCaptionSidecars.test.ts b/electron/ipc/register/exportCaptionSidecars.test.ts
new file mode 100644
index 000000000..2fc571e13
--- /dev/null
+++ b/electron/ipc/register/exportCaptionSidecars.test.ts
@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ parseCaptionSidecarPayload,
+ serializeSrt,
+ serializeVtt,
+ withCaptionSidecarMessage,
+ writeCaptionSidecarsBestEffort,
+} from "./exportCaptionSidecars";
+
+describe("exportCaptionSidecars", () => {
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ it("serializes SRT cues with stable numbering and timestamps", () => {
+ expect(
+ serializeSrt([
+ {
+ startMs: 1234,
+ endMs: 5678,
+ text: "Hello\nworld",
+ },
+ ]),
+ ).toBe("1\n00:00:01,234 --> 00:00:05,678\nHello\nworld");
+ });
+
+ it("serializes VTT cues with header and dot timestamps", () => {
+ expect(
+ serializeVtt([
+ {
+ startMs: 0,
+ endMs: 2000,
+ text: "Caption",
+ },
+ ]),
+ ).toBe("WEBVTT\n\n00:00:00.000 --> 00:00:02.000\nCaption");
+ });
+
+ it("drops malformed cues when parsing sidecar payloads", () => {
+ expect(
+ parseCaptionSidecarPayload({
+ format: "both",
+ cues: [
+ { startMs: 0, endMs: 1000, text: "ok" },
+ { startMs: 2000, endMs: 1000, text: "bad range" },
+ { startMs: 1000, endMs: 2000, text: " " },
+ ],
+ }),
+ ).toEqual({
+ format: "both",
+ cues: [{ startMs: 0, endMs: 1000, text: "ok" }],
+ });
+ });
+
+ it("returns a warning result instead of throwing when sidecar writes fail", async () => {
+ const writeFileSpy = vi
+ .spyOn(fs, "writeFile")
+ .mockRejectedValueOnce(new Error("disk full"));
+
+ await expect(
+ writeCaptionSidecarsBestEffort("/tmp/export.mp4", {
+ format: "srt",
+ cues: [{ startMs: 0, endMs: 1000, text: "Caption" }],
+ }),
+ ).resolves.toEqual({
+ wroteAny: false,
+ error: "disk full",
+ });
+
+ expect(writeFileSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it("writes requested caption sidecars when the filesystem succeeds", async () => {
+ const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-sidecar-test-"));
+ const videoPath = path.join(tempDir, "clip.mp4");
+
+ try {
+ await expect(
+ writeCaptionSidecarsBestEffort(videoPath, {
+ format: "both",
+ cues: [{ startMs: 0, endMs: 1000, text: "Caption" }],
+ }),
+ ).resolves.toEqual({ wroteAny: true, error: null });
+
+ await expect(fs.readFile(path.join(tempDir, "clip.srt"), "utf8")).resolves.toContain(
+ "00:00:00,000 --> 00:00:01,000",
+ );
+ await expect(fs.readFile(path.join(tempDir, "clip.vtt"), "utf8")).resolves.toContain(
+ "WEBVTT",
+ );
+ } finally {
+ await fs.rm(tempDir, { recursive: true, force: true });
+ }
+ });
+
+ it("appends a non-fatal caption warning only when sidecar writes fail", () => {
+ expect(
+ withCaptionSidecarMessage("Video exported successfully", {
+ wroteAny: false,
+ error: "disk full",
+ }),
+ ).toBe("Video exported successfully Captions could not be saved alongside the video.");
+
+ expect(
+ withCaptionSidecarMessage("Video exported successfully", {
+ wroteAny: true,
+ error: null,
+ }),
+ ).toBe("Video exported successfully");
+ });
+});
diff --git a/electron/ipc/register/exportCaptionSidecars.ts b/electron/ipc/register/exportCaptionSidecars.ts
new file mode 100644
index 000000000..0560a9a96
--- /dev/null
+++ b/electron/ipc/register/exportCaptionSidecars.ts
@@ -0,0 +1,157 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export type CaptionSidecarCue = {
+ startMs: number;
+ endMs: number;
+ text: string;
+};
+
+export type CaptionSidecarPayload = {
+ format: "srt" | "vtt" | "both";
+ cues: CaptionSidecarCue[];
+};
+
+export type CaptionSidecarWriteResult = {
+ wroteAny: boolean;
+ error: string | null;
+};
+
+function toSrtTimestamp(totalMs: number): string {
+ const ms = Math.max(0, Math.round(totalMs));
+ const hours = Math.floor(ms / 3_600_000);
+ const minutes = Math.floor((ms % 3_600_000) / 60_000);
+ const seconds = Math.floor((ms % 60_000) / 1000);
+ const millis = ms % 1000;
+ return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")},${String(millis).padStart(3, "0")}`;
+}
+
+function toVttTimestamp(totalMs: number): string {
+ const ms = Math.max(0, Math.round(totalMs));
+ const hours = Math.floor(ms / 3_600_000);
+ const minutes = Math.floor((ms % 3_600_000) / 60_000);
+ const seconds = Math.floor((ms % 60_000) / 1000);
+ const millis = ms % 1000;
+ return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}.${String(millis).padStart(3, "0")}`;
+}
+
+function normalizeCaptionSidecarCues(cues: unknown): CaptionSidecarCue[] {
+ if (!Array.isArray(cues)) {
+ return [];
+ }
+
+ return cues
+ .filter((cue): cue is CaptionSidecarCue => {
+ return (
+ typeof cue === "object" &&
+ cue !== null &&
+ typeof cue.startMs === "number" &&
+ typeof cue.endMs === "number" &&
+ typeof cue.text === "string" &&
+ Number.isFinite(cue.startMs) &&
+ Number.isFinite(cue.endMs) &&
+ cue.endMs > cue.startMs &&
+ cue.text.trim().length > 0
+ );
+ })
+ .map((cue) => ({
+ startMs: cue.startMs,
+ endMs: cue.endMs,
+ text: cue.text.replace(/\r\n/g, "\n").trim(),
+ }));
+}
+
+export function parseCaptionSidecarPayload(payload: unknown): CaptionSidecarPayload | null {
+ if (typeof payload !== "object" || payload === null) {
+ return null;
+ }
+
+ const candidate = payload as {
+ format?: unknown;
+ cues?: unknown;
+ };
+
+ const format =
+ candidate.format === "srt" || candidate.format === "vtt" || candidate.format === "both"
+ ? candidate.format
+ : null;
+ if (!format) {
+ return null;
+ }
+
+ const cues = normalizeCaptionSidecarCues(candidate.cues);
+ if (cues.length === 0) {
+ return null;
+ }
+
+ return { format, cues };
+}
+
+export function serializeSrt(cues: CaptionSidecarCue[]): string {
+ return cues
+ .map((cue, index) => {
+ return `${index + 1}\n${toSrtTimestamp(cue.startMs)} --> ${toSrtTimestamp(cue.endMs)}\n${cue.text}`;
+ })
+ .join("\n\n");
+}
+
+export function serializeVtt(cues: CaptionSidecarCue[]): string {
+ const body = cues
+ .map((cue) => {
+ return `${toVttTimestamp(cue.startMs)} --> ${toVttTimestamp(cue.endMs)}\n${cue.text}`;
+ })
+ .join("\n\n");
+ return `WEBVTT\n\n${body}`;
+}
+
+export async function writeCaptionSidecars(
+ videoPath: string,
+ payload: CaptionSidecarPayload | null,
+) {
+ if (!payload) {
+ return;
+ }
+
+ const parsed = path.parse(videoPath);
+ const basePath = path.join(parsed.dir, parsed.name);
+
+ if (payload.format === "srt" || payload.format === "both") {
+ await fs.writeFile(`${basePath}.srt`, serializeSrt(payload.cues), "utf8");
+ }
+
+ if (payload.format === "vtt" || payload.format === "both") {
+ await fs.writeFile(`${basePath}.vtt`, serializeVtt(payload.cues), "utf8");
+ }
+}
+
+export async function writeCaptionSidecarsBestEffort(
+ videoPath: string,
+ payload: CaptionSidecarPayload | null,
+): Promise {
+ if (!payload) {
+ return { wroteAny: false, error: null };
+ }
+
+ try {
+ await writeCaptionSidecars(videoPath, payload);
+ return { wroteAny: true, error: null };
+ } catch (error) {
+ const message = error instanceof Error ? error.message : String(error);
+ console.warn("[export] Failed to write caption sidecars:", {
+ videoPath,
+ message,
+ });
+ return { wroteAny: false, error: message };
+ }
+}
+
+export function withCaptionSidecarMessage(
+ baseMessage: string,
+ captionSidecarResult: CaptionSidecarWriteResult,
+) {
+ if (!captionSidecarResult.error) {
+ return baseMessage;
+ }
+
+ return `${baseMessage} Captions could not be saved alongside the video.`;
+}
diff --git a/electron/ipc/register/permissions.ts b/electron/ipc/register/permissions.ts
new file mode 100644
index 000000000..f3b8b86f1
--- /dev/null
+++ b/electron/ipc/register/permissions.ts
@@ -0,0 +1,87 @@
+import { ipcMain, shell, systemPreferences } from "electron";
+import { getMacPrivacySettingsUrl } from "../utils";
+
+export function registerPermissionHandlers() {
+ ipcMain.handle("open-external-url", async (_, url: string) => {
+ try {
+ // Security: only allow http/https URLs to prevent file:// or custom protocol abuse
+ const parsed = new URL(url);
+ if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+ return { success: false, error: `Blocked non-HTTP URL: ${parsed.protocol}` };
+ }
+ await shell.openExternal(url);
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to open URL:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("get-accessibility-permission-status", () => {
+ if (process.platform !== "darwin") {
+ return { success: true, trusted: true, prompted: false };
+ }
+
+ return {
+ success: true,
+ trusted: systemPreferences.isTrustedAccessibilityClient(false),
+ prompted: false,
+ };
+ });
+
+ ipcMain.handle("request-accessibility-permission", () => {
+ if (process.platform !== "darwin") {
+ return { success: true, trusted: true, prompted: false };
+ }
+
+ return {
+ success: true,
+ trusted: systemPreferences.isTrustedAccessibilityClient(true),
+ prompted: true,
+ };
+ });
+
+ ipcMain.handle("get-screen-recording-permission-status", () => {
+ if (process.platform !== "darwin") {
+ return { success: true, status: "granted" };
+ }
+
+ try {
+ return {
+ success: true,
+ status: systemPreferences.getMediaAccessStatus("screen"),
+ };
+ } catch (error) {
+ console.error("Failed to get screen recording permission status:", error);
+ return { success: false, status: "unknown", error: String(error) };
+ }
+ });
+
+ ipcMain.handle("open-screen-recording-preferences", async () => {
+ if (process.platform !== "darwin") {
+ return { success: true };
+ }
+
+ try {
+ await shell.openExternal(getMacPrivacySettingsUrl("screen"));
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to open Screen Recording preferences:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("open-accessibility-preferences", async () => {
+ if (process.platform !== "darwin") {
+ return { success: true };
+ }
+
+ try {
+ await shell.openExternal(getMacPrivacySettingsUrl("accessibility"));
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to open Accessibility preferences:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+}
diff --git a/electron/ipc/register/project.ts b/electron/ipc/register/project.ts
new file mode 100644
index 000000000..a3a0cd078
--- /dev/null
+++ b/electron/ipc/register/project.ts
@@ -0,0 +1,776 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { BrowserWindow, dialog, ipcMain, shell } from "electron";
+import { RECORDINGS_DIR } from "../../appPaths";
+import { buildMediaUrl, getMediaServerBaseUrl } from "../../mediaServer";
+import { LEGACY_PROJECT_FILE_EXTENSIONS, PROJECT_FILE_EXTENSION } from "../constants";
+import { getProjectBackupPath, writeProjectFileAtomically } from "../project/atomicSave";
+import {
+ getProjectsDir,
+ getProjectThumbnailPath,
+ isPathInsideDirectory,
+ isTrustedProjectPath,
+ listProjectLibraryEntries,
+ loadProjectFromPath,
+ loadRecentProjectPaths,
+ persistRecordingsDirectorySetting,
+ rememberRecentProject,
+ replaceApprovedSessionLocalReadPaths,
+ rememberApprovedLocalReadPath,
+ resolveApprovedLocalMediaPath,
+ saveProjectThumbnail,
+ saveRecentProjectPaths,
+} from "../project/manager";
+import { persistRecordingSessionManifest, resolveRecordingSession } from "../project/session";
+import {
+ currentProjectPath,
+ currentRecordingSession,
+ currentVideoPath,
+ setCurrentProjectPath,
+ setCurrentRecordingSession,
+ setCurrentVideoPath,
+} from "../state";
+import {
+ approveUserPath,
+ getRecordingsDir,
+ getTelemetryPathForVideo,
+ isAutoRecordingPath,
+ normalizeVideoSourcePath,
+ parseJsonWithByteOrderMark,
+} from "../utils";
+
+function normalizeRecordingTimeOffsetMs(value: unknown): number {
+ return typeof value === "number" && Number.isFinite(value) ? Math.round(value) : 0;
+}
+
+function normalizeBoolean(value: unknown, fallback = false): boolean {
+ return typeof value === "boolean" ? value : fallback;
+}
+
+/**
+ * Produces a filesystem-safe project base name without the project extension.
+ */
+function normalizeProjectSaveName(projectName?: string | null) {
+ if (typeof projectName !== "string") {
+ return null;
+ }
+
+ const trimmedName = projectName.trim();
+ if (!trimmedName) {
+ return null;
+ }
+
+ const withoutExtension = trimmedName.replace(
+ new RegExp(`\\.${PROJECT_FILE_EXTENSION}$`, "i"),
+ "",
+ );
+ const withoutInvalidFilesystemChars = withoutExtension.replace(/[<>:"/\\|?*]/g, "");
+ const withoutControlChars = Array.from(withoutInvalidFilesystemChars)
+ .filter((character) => character.charCodeAt(0) > 31)
+ .join("");
+ const sanitizedName = withoutControlChars
+ .replace(/\s+/g, " ")
+ .replace(/[. ]+$/g, "")
+ .trim();
+
+ return sanitizedName || null;
+}
+
+type NamedProjectSaveMode = "rename" | "copy";
+
+function normalizeNamedProjectSaveMode(value: unknown): NamedProjectSaveMode {
+ return value === "copy" ? "copy" : "rename";
+}
+
+/**
+ * Extracts the persisted source video path from a saved project payload.
+ */
+function getProjectVideoPath(projectData: unknown) {
+ if (!projectData || typeof projectData !== "object") {
+ return null;
+ }
+
+ const candidate = projectData as { videoPath?: unknown };
+ return typeof candidate.videoPath === "string" ? candidate.videoPath : null;
+}
+
+function getProjectId(projectData: unknown) {
+ if (!projectData || typeof projectData !== "object") {
+ return null;
+ }
+
+ const candidate = projectData as { projectId?: unknown };
+ return typeof candidate.projectId === "string" && candidate.projectId.trim().length > 0
+ ? candidate.projectId
+ : null;
+}
+
+function withProjectId(projectData: unknown, projectId: string) {
+ if (!projectData || typeof projectData !== "object" || Array.isArray(projectData)) {
+ return projectData;
+ }
+
+ return {
+ ...projectData,
+ projectId,
+ };
+}
+
+function ensureProjectDataHasProjectId(projectData: unknown) {
+ const existingProjectId = getProjectId(projectData);
+ if (existingProjectId) {
+ return {
+ projectId: existingProjectId,
+ projectData,
+ };
+ }
+
+ const projectId = randomUUID();
+ return {
+ projectId,
+ projectData: withProjectId(projectData, projectId),
+ };
+}
+
+async function resolveComparablePath(filePath: string) {
+ return fs.realpath(filePath).catch(() => path.resolve(filePath));
+}
+
+/**
+ * Prevents a named save from silently overwriting a different project file.
+ */
+async function ensureNamedProjectSaveDoesNotOverwriteDifferentProject(
+ targetProjectPath: string,
+ projectData: unknown,
+ activeProjectPath?: string | null,
+) {
+ try {
+ await fs.stat(targetProjectPath);
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+ return { success: true };
+ }
+ throw error;
+ }
+
+ const targetResolvedPath = await resolveComparablePath(targetProjectPath);
+ if (activeProjectPath) {
+ const activeResolvedPath = await resolveComparablePath(activeProjectPath);
+ if (activeResolvedPath === targetResolvedPath) {
+ return { success: true };
+ }
+ }
+
+ const incomingProjectId = getProjectId(projectData);
+ const incomingVideoPath = getProjectVideoPath(projectData);
+
+ try {
+ const existingProjectRaw = await fs.readFile(targetProjectPath, "utf-8");
+ const existingProjectData = parseJsonWithByteOrderMark(existingProjectRaw);
+ const existingProjectId = getProjectId(existingProjectData);
+ const existingVideoPath = getProjectVideoPath(existingProjectData);
+
+ if (existingProjectId && incomingProjectId) {
+ if (existingProjectId === incomingProjectId) {
+ return { success: true };
+ }
+
+ return {
+ success: false,
+ message: "A different project already uses this name",
+ };
+ }
+
+ if (existingVideoPath && incomingVideoPath && existingVideoPath !== incomingVideoPath) {
+ return {
+ success: false,
+ message: "A different project already uses this name",
+ };
+ }
+
+ if (!existingProjectId && !incomingProjectId && existingVideoPath && incomingVideoPath) {
+ return {
+ success: false,
+ message: "Unable to verify project identity for the chosen name",
+ };
+ }
+
+ return {
+ success: false,
+ message: "Unable to verify project identity for the chosen name",
+ };
+ } catch (error) {
+ console.error("Failed to verify existing named project before overwrite:", error);
+ return {
+ success: false,
+ message: "Unable to verify project identity for the chosen name",
+ };
+ }
+}
+
+export function registerProjectHandlers() {
+ ipcMain.handle("reveal-in-folder", async (_, filePath: string) => {
+ try {
+ // shell.showItemInFolder doesn't return a value, it throws on error
+ shell.showItemInFolder(filePath);
+ return { success: true };
+ } catch (error) {
+ console.error(`Error revealing item in folder: ${filePath}`, error);
+ // Fallback to open the directory if revealing the item fails
+ // This might happen if the file was moved or deleted after export,
+ // or if the path is somehow invalid for showItemInFolder
+ try {
+ const openPathResult = await shell.openPath(path.dirname(filePath));
+ if (openPathResult) {
+ // openPath returned an error message
+ return { success: false, error: openPathResult };
+ }
+ return { success: true, message: "Could not reveal item, but opened directory." };
+ } catch (openError) {
+ console.error(`Error opening directory: ${path.dirname(filePath)}`, openError);
+ return { success: false, error: String(error) };
+ }
+ }
+ });
+
+ ipcMain.handle("open-recordings-folder", async () => {
+ try {
+ const recordingsDir = await getRecordingsDir();
+ const openPathResult = await shell.openPath(recordingsDir);
+ if (openPathResult) {
+ return {
+ success: false,
+ error: openPathResult,
+ message: "Failed to open recordings folder.",
+ };
+ }
+
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to open recordings folder:", error);
+ return {
+ success: false,
+ error: String(error),
+ message: "Failed to open recordings folder.",
+ };
+ }
+ });
+
+ ipcMain.handle("get-recordings-directory", async () => {
+ try {
+ const recordingsDir = await getRecordingsDir();
+ return {
+ success: true,
+ path: recordingsDir,
+ isDefault: recordingsDir === RECORDINGS_DIR,
+ };
+ } catch (error) {
+ return {
+ success: false,
+ path: RECORDINGS_DIR,
+ isDefault: true,
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("choose-recordings-directory", async () => {
+ try {
+ const current = await getRecordingsDir();
+ const result = await dialog.showOpenDialog({
+ title: "Choose recordings folder",
+ defaultPath: current,
+ properties: ["openDirectory", "createDirectory", "promptToCreate"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true, path: current };
+ }
+
+ const selectedPath = path.resolve(result.filePaths[0]);
+ await fs.mkdir(selectedPath, { recursive: true });
+ await fs.access(selectedPath, fsConstants.W_OK);
+ await persistRecordingsDirectorySetting(selectedPath);
+
+ return {
+ success: true,
+ path: selectedPath,
+ isDefault: selectedPath === RECORDINGS_DIR,
+ };
+ } catch (error) {
+ return {
+ success: false,
+ error: String(error),
+ message: "Failed to set recordings folder",
+ };
+ }
+ });
+
+ ipcMain.handle(
+ "save-project-file",
+ async (
+ _,
+ projectData: unknown,
+ suggestedName?: string,
+ existingProjectPath?: string,
+ thumbnailDataUrl?: string | null,
+ ) => {
+ try {
+ const projectsDir = await getProjectsDir();
+ const preparedProject = ensureProjectDataHasProjectId(projectData);
+ const trustedExistingProjectPath =
+ existingProjectPath &&
+ path.extname(existingProjectPath).toLowerCase() ===
+ `.${PROJECT_FILE_EXTENSION}` &&
+ (isTrustedProjectPath(existingProjectPath) ||
+ isPathInsideDirectory(existingProjectPath, projectsDir))
+ ? path.resolve(existingProjectPath)
+ : null;
+
+ if (trustedExistingProjectPath) {
+ await writeProjectFileAtomically(
+ trustedExistingProjectPath,
+ JSON.stringify(preparedProject.projectData, null, 2),
+ );
+ setCurrentProjectPath(trustedExistingProjectPath);
+ await saveProjectThumbnail(trustedExistingProjectPath, thumbnailDataUrl);
+ await rememberRecentProject(trustedExistingProjectPath);
+ return {
+ success: true,
+ path: trustedExistingProjectPath,
+ projectId: preparedProject.projectId,
+ message: "Project saved successfully",
+ };
+ }
+
+ if (existingProjectPath) {
+ return {
+ success: false,
+ message:
+ "Project path is no longer trusted. Use Save As to choose a project file.",
+ };
+ }
+
+ const safeName = normalizeProjectSaveName(suggestedName) || `project-${Date.now()}`;
+ const defaultName = `${safeName}.${PROJECT_FILE_EXTENSION}`;
+
+ const result = await dialog.showSaveDialog({
+ title: "Save Recordly Project",
+ defaultPath: path.join(projectsDir, defaultName),
+ filters: [
+ { name: "Recordly Project", extensions: [PROJECT_FILE_EXTENSION] },
+ { name: "JSON", extensions: ["json"] },
+ ],
+ properties: ["createDirectory", "showOverwriteConfirmation"],
+ });
+
+ if (result.canceled || !result.filePath) {
+ return {
+ success: false,
+ canceled: true,
+ message: "Save project canceled",
+ };
+ }
+
+ await writeProjectFileAtomically(
+ result.filePath,
+ JSON.stringify(preparedProject.projectData, null, 2),
+ );
+ setCurrentProjectPath(result.filePath);
+ await saveProjectThumbnail(result.filePath, thumbnailDataUrl);
+ await rememberRecentProject(result.filePath);
+
+ return {
+ success: true,
+ path: result.filePath,
+ projectId: preparedProject.projectId,
+ message: "Project saved successfully",
+ };
+ } catch (error) {
+ console.error("Failed to save project file:", error);
+ return {
+ success: false,
+ message: "Failed to save project file",
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle(
+ "save-project-file-named",
+ async (
+ _,
+ projectData: unknown,
+ projectName: string,
+ thumbnailDataUrl?: string | null,
+ mode?: unknown,
+ ) => {
+ try {
+ const normalizedProjectName = normalizeProjectSaveName(projectName);
+ if (!normalizedProjectName) {
+ return {
+ success: false,
+ message: "Project name is required",
+ };
+ }
+
+ const projectsDir = await getProjectsDir();
+ const namedSaveMode = normalizeNamedProjectSaveMode(mode);
+ const activeProjectPath = isTrustedProjectPath(currentProjectPath)
+ ? currentProjectPath
+ : null;
+ const targetProjectPath = path.join(
+ projectsDir,
+ `${normalizedProjectName}.${PROJECT_FILE_EXTENSION}`,
+ );
+ const [activeResolvedPath, targetResolvedPath] = await Promise.all([
+ activeProjectPath
+ ? resolveComparablePath(activeProjectPath)
+ : Promise.resolve(null),
+ resolveComparablePath(targetProjectPath),
+ ]);
+ const isSavingToDifferentPath =
+ !activeResolvedPath || activeResolvedPath !== targetResolvedPath;
+ const preparedProject =
+ namedSaveMode === "copy" && isSavingToDifferentPath
+ ? (() => {
+ const projectId = randomUUID();
+ return {
+ projectId,
+ projectData: withProjectId(projectData, projectId),
+ };
+ })()
+ : ensureProjectDataHasProjectId(projectData);
+
+ const overwriteCheck = await ensureNamedProjectSaveDoesNotOverwriteDifferentProject(
+ targetProjectPath,
+ preparedProject.projectData,
+ activeProjectPath,
+ );
+ if (!overwriteCheck.success) {
+ return overwriteCheck;
+ }
+
+ await writeProjectFileAtomically(
+ targetProjectPath,
+ JSON.stringify(preparedProject.projectData, null, 2),
+ );
+ await saveProjectThumbnail(targetProjectPath, thumbnailDataUrl);
+ await rememberRecentProject(targetProjectPath);
+
+ if (namedSaveMode === "rename" && activeProjectPath && isSavingToDifferentPath) {
+ await fs
+ .unlink(activeProjectPath)
+ .catch((unlinkError: NodeJS.ErrnoException) => {
+ if (unlinkError.code !== "ENOENT") {
+ throw unlinkError;
+ }
+ });
+ await fs
+ .rm(getProjectThumbnailPath(activeProjectPath), { force: true })
+ .catch(() => undefined);
+ await fs
+ .rm(getProjectBackupPath(activeProjectPath), { force: true })
+ .catch(() => undefined);
+
+ const recentProjectPaths = await loadRecentProjectPaths();
+ const filteredRecentProjectPaths: string[] = [];
+ for (const recentProjectPath of recentProjectPaths) {
+ const recentResolvedPath = await resolveComparablePath(recentProjectPath);
+ if (recentResolvedPath !== activeResolvedPath) {
+ filteredRecentProjectPaths.push(recentProjectPath);
+ }
+ }
+ await saveRecentProjectPaths(filteredRecentProjectPaths);
+ }
+
+ setCurrentProjectPath(targetProjectPath);
+
+ return {
+ success: true,
+ path: targetProjectPath,
+ projectId: preparedProject.projectId,
+ message: "Project saved successfully",
+ };
+ } catch (error) {
+ console.error("Failed to save named project file:", error);
+ return {
+ success: false,
+ message: "Failed to save project file",
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("load-project-file", async () => {
+ try {
+ const projectsDir = await getProjectsDir();
+ const result = await dialog.showOpenDialog({
+ title: "Open Recordly Project",
+ defaultPath: projectsDir,
+ filters: [
+ {
+ name: "Recordly Project",
+ extensions: [PROJECT_FILE_EXTENSION, ...LEGACY_PROJECT_FILE_EXTENSIONS],
+ },
+ { name: "JSON", extensions: ["json"] },
+ { name: "All Files", extensions: ["*"] },
+ ],
+ properties: ["openFile"],
+ });
+
+ if (result.canceled || result.filePaths.length === 0) {
+ return { success: false, canceled: true, message: "Open project canceled" };
+ }
+
+ return await loadProjectFromPath(result.filePaths[0]);
+ } catch (error) {
+ console.error("Failed to load project file:", error);
+ return {
+ success: false,
+ message: "Failed to load project file",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("load-current-project-file", async () => {
+ try {
+ if (!currentProjectPath) {
+ return { success: false, message: "No active project" };
+ }
+
+ return await loadProjectFromPath(currentProjectPath);
+ } catch (error) {
+ console.error("Failed to load current project file:", error);
+ return {
+ success: false,
+ message: "Failed to load current project file",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("get-projects-directory", async () => {
+ try {
+ return {
+ success: true,
+ path: await getProjectsDir(),
+ };
+ } catch (error) {
+ return {
+ success: false,
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("list-project-files", async () => {
+ try {
+ const library = await listProjectLibraryEntries();
+ return {
+ success: true,
+ projectsDir: library.projectsDir,
+ entries: library.entries,
+ };
+ } catch (error) {
+ return {
+ success: false,
+ projectsDir: null,
+ entries: [],
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("open-project-file-at-path", async (_, filePath: string) => {
+ try {
+ return await loadProjectFromPath(filePath);
+ } catch (error) {
+ console.error("Failed to open project file at path:", error);
+ return {
+ success: false,
+ message: "Failed to open project file",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("open-projects-directory", async () => {
+ try {
+ const projectsDir = await getProjectsDir();
+ const openPathResult = await shell.openPath(projectsDir);
+ if (openPathResult) {
+ return {
+ success: false,
+ error: openPathResult,
+ message: "Failed to open projects folder.",
+ };
+ }
+
+ return { success: true, path: projectsDir };
+ } catch (error) {
+ console.error("Failed to open projects folder:", error);
+ return {
+ success: false,
+ error: String(error),
+ message: "Failed to open projects folder.",
+ };
+ }
+ });
+ ipcMain.handle(
+ "set-current-video-path",
+ async (
+ _,
+ path: string,
+ options?: { preserveProjectPath?: boolean; hideOverlayCursorByDefault?: boolean },
+ ) => {
+ setCurrentVideoPath(normalizeVideoSourcePath(path) ?? path);
+ approveUserPath(currentVideoPath);
+ const resolvedSession = (await resolveRecordingSession(currentVideoPath)) ?? {
+ videoPath: currentVideoPath!,
+ webcamPath: null,
+ timeOffsetMs: 0,
+ };
+
+ const nextSession = {
+ ...resolvedSession,
+ hideOverlayCursorByDefault:
+ normalizeBoolean(options?.hideOverlayCursorByDefault) ||
+ normalizeBoolean(resolvedSession.hideOverlayCursorByDefault),
+ };
+
+ setCurrentRecordingSession(nextSession);
+ await replaceApprovedSessionLocalReadPaths([
+ resolvedSession.videoPath,
+ resolvedSession.webcamPath,
+ ]);
+
+ if (nextSession.webcamPath) {
+ await persistRecordingSessionManifest(nextSession);
+ }
+
+ if (!options?.preserveProjectPath) {
+ setCurrentProjectPath(null);
+ }
+
+ for (const window of BrowserWindow.getAllWindows()) {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-session-changed", nextSession);
+ }
+ }
+
+ return { success: true, webcamPath: nextSession.webcamPath ?? null };
+ },
+ );
+
+ ipcMain.handle(
+ "set-current-recording-session",
+ async (
+ _,
+ session: {
+ videoPath: string;
+ webcamPath?: string | null;
+ timeOffsetMs?: number;
+ hideOverlayCursorByDefault?: boolean;
+ },
+ options?: { preserveProjectPath?: boolean },
+ ) => {
+ const normalizedVideoPath =
+ normalizeVideoSourcePath(session.videoPath) ?? session.videoPath;
+ setCurrentVideoPath(normalizedVideoPath);
+ setCurrentRecordingSession({
+ videoPath: normalizedVideoPath,
+ webcamPath: normalizeVideoSourcePath(session.webcamPath ?? null),
+ timeOffsetMs: normalizeRecordingTimeOffsetMs(session.timeOffsetMs),
+ hideOverlayCursorByDefault: normalizeBoolean(session.hideOverlayCursorByDefault),
+ });
+ await rememberApprovedLocalReadPath(currentRecordingSession!.videoPath);
+ await rememberApprovedLocalReadPath(currentRecordingSession!.webcamPath);
+ if (!options?.preserveProjectPath) {
+ setCurrentProjectPath(null);
+ }
+ await persistRecordingSessionManifest(currentRecordingSession!);
+
+ for (const window of BrowserWindow.getAllWindows()) {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-session-changed", currentRecordingSession);
+ }
+ }
+
+ return { success: true };
+ },
+ );
+
+ ipcMain.handle("get-current-recording-session", () => {
+ if (!currentRecordingSession) {
+ return { success: false };
+ }
+
+ return {
+ success: true,
+ session: currentRecordingSession,
+ };
+ });
+
+ ipcMain.handle("get-current-video-path", () => {
+ return currentVideoPath ? { success: true, path: currentVideoPath } : { success: false };
+ });
+
+ ipcMain.handle("clear-current-video-path", () => {
+ setCurrentVideoPath(null);
+ setCurrentRecordingSession(null);
+ return { success: true };
+ });
+
+ ipcMain.handle("delete-recording-file", async (_, filePath: string) => {
+ try {
+ if (!filePath) {
+ return { success: false, error: "Only auto-generated recordings can be deleted" };
+ }
+ const resolvedPath = await fs.realpath(filePath).catch(() => path.resolve(filePath));
+ const recordingsDirRaw = await getRecordingsDir();
+ const recordingsDir = await fs
+ .realpath(recordingsDirRaw)
+ .catch(() => path.resolve(recordingsDirRaw));
+ if (
+ !isPathInsideDirectory(resolvedPath, recordingsDir) ||
+ !isAutoRecordingPath(resolvedPath)
+ ) {
+ return { success: false, error: "Only auto-generated recordings can be deleted" };
+ }
+ await fs.unlink(resolvedPath);
+ // Also delete the cursor telemetry sidecar if it exists
+ const telemetryPath = getTelemetryPathForVideo(resolvedPath);
+ await fs.unlink(telemetryPath).catch(() => undefined);
+ const currentResolved = currentVideoPath
+ ? await fs.realpath(currentVideoPath).catch(() => currentVideoPath)
+ : null;
+ if (currentResolved === resolvedPath) {
+ setCurrentVideoPath(null);
+ setCurrentRecordingSession(null);
+ }
+ return { success: true };
+ } catch (error) {
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("get-local-media-url", async (_, filePath: string) => {
+ const baseUrl = getMediaServerBaseUrl();
+ if (!baseUrl || !filePath) {
+ return { success: false as const };
+ }
+ const resolved = await resolveApprovedLocalMediaPath(filePath);
+ if (!resolved) {
+ const normalized = path.resolve(filePath);
+ console.warn(`[get-local-media-url] Blocked disallowed path: ${normalized}`);
+ return { success: false as const };
+ }
+ return { success: true as const, url: buildMediaUrl(baseUrl, resolved) };
+ });
+}
diff --git a/electron/ipc/register/recording.ts b/electron/ipc/register/recording.ts
new file mode 100644
index 000000000..3e03d9709
--- /dev/null
+++ b/electron/ipc/register/recording.ts
@@ -0,0 +1,1945 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import {
+ app,
+ BrowserWindow,
+ desktopCapturer,
+ dialog,
+ ipcMain,
+ shell,
+ systemPreferences,
+} from "electron";
+import { showCursor } from "../../cursorHider";
+import { getMonitorHandles } from "../monitorResolver";
+import { ALLOW_RECORDLY_WINDOW_CAPTURE } from "../constants";
+import { startWindowBoundsCapture, stopWindowBoundsCapture } from "../cursor/bounds";
+import { startInteractionCapture, stopInteractionCapture } from "../cursor/interaction";
+import { startNativeCursorMonitor, stopNativeCursorMonitor } from "../cursor/monitor";
+import {
+ normalizeCursorTelemetrySamples,
+ pauseCursorCaptureAtBoundary,
+ persistPendingCursorTelemetry,
+ resetCursorCaptureClock,
+ resumeCursorCapture,
+ sampleCursorPoint,
+ snapshotCursorTelemetryForPersistence,
+ startCursorSampling,
+ stopCursorCapture,
+ writeCursorTelemetry,
+} from "../cursor/telemetry";
+import { getFfmpegBinaryPath } from "../ffmpeg/binary";
+import {
+ ensureNativeCaptureHelperBinary,
+ ensureSwiftHelperBinary,
+ getNativeCaptureHelperBinaryPath,
+ getSystemCursorHelperBinaryPath,
+ getSystemCursorHelperSourcePath,
+ getWindowsCaptureExePath,
+} from "../paths/binaries";
+import { rememberApprovedLocalReadPath } from "../project/manager";
+import {
+ getBrowserMicSidecarFilters,
+ shouldKeepRecordingAudioSidecars,
+} from "../recording/audioFilters";
+import {
+ getCompanionAudioFallbackInfo,
+ getFileSizeIfPresent,
+ type MicrophoneChunkTimingEvent,
+ type MicrophonePauseInterval,
+ type RecordingDiagnosticsSnapshot,
+ recordNativeCaptureDiagnostics,
+ summarizeMicrophoneChunkTiming,
+ validateRecordedVideo,
+ writeRecordingDiagnosticsSnapshot,
+} from "../recording/diagnostics";
+import {
+ buildFfmpegCaptureArgs,
+ waitForFfmpegCaptureStart,
+ waitForFfmpegCaptureStop,
+} from "../recording/ffmpeg";
+import {
+ attachNativeCaptureLifecycle,
+ finalizeStoredVideo,
+ muxNativeMacRecordingWithAudio,
+ recoverNativeMacCaptureOutput,
+ waitForNativeCaptureCommand,
+ waitForNativeCaptureStart,
+ waitForNativeCaptureStop,
+} from "../recording/mac";
+import { resolveRecordedVideoStoragePath } from "../recording/storagePath";
+import {
+ attachWindowsCaptureLifecycle,
+ isNativeWindowsCaptureAvailable,
+ muxNativeWindowsVideoWithAudio,
+ waitForWindowsCaptureStart,
+ waitForWindowsCaptureStop,
+} from "../recording/windows";
+import {
+ shouldStartWindowsBrowserMicrophoneFallback,
+ shouldUseWindowsBrowserMicrophoneFallback,
+} from "../recording/windowsFallbacks";
+import {
+ cachedSystemCursorAssets,
+ cachedSystemCursorAssetsSourceMtimeMs,
+ currentVideoPath,
+ ffmpegCaptureOutputBuffer,
+ ffmpegCaptureProcess,
+ ffmpegCaptureTargetPath,
+ ffmpegScreenRecordingActive,
+ lastNativeCaptureDiagnostics,
+ nativeCaptureMicrophonePath,
+ nativeCaptureOutputBuffer,
+ nativeCapturePaused,
+ nativeCaptureProcess,
+ nativeCaptureSystemAudioPath,
+ nativeCaptureTargetPath,
+ nativeScreenRecordingActive,
+ selectedSource,
+ setActiveCursorSamples,
+ setCachedSystemCursorAssets,
+ setCachedSystemCursorAssetsSourceMtimeMs,
+ setCursorCaptureStartTimeMs,
+ setFfmpegCaptureOutputBuffer,
+ setFfmpegCaptureProcess,
+ setFfmpegCaptureTargetPath,
+ setFfmpegScreenRecordingActive,
+ setIsCursorCaptureActive,
+ setLastLeftClick,
+ setLinuxCursorScreenPoint,
+ setNativeCaptureMicrophonePath,
+ setNativeCaptureOutputBuffer,
+ setNativeCapturePaused,
+ setNativeCaptureProcess,
+ setNativeCaptureStopRequested,
+ setNativeCaptureSystemAudioPath,
+ setNativeCaptureTargetPath,
+ setNativeScreenRecordingActive,
+ setPendingCursorSamples,
+ setWindowsCaptureOutputBuffer,
+ setWindowsCapturePaused,
+ setWindowsCaptureProcess,
+ setWindowsCaptureStopRequested,
+ setWindowsCaptureTargetPath,
+ setWindowsMicAudioPath,
+ setWindowsNativeCaptureActive,
+ setWindowsOrphanedMicAudioPath,
+ setWindowsPendingVideoPath,
+ setWindowsSystemAudioPath,
+ windowsCaptureOutputBuffer,
+ windowsCapturePaused,
+ windowsCaptureProcess,
+ windowsCaptureTargetPath,
+ windowsMicAudioPath,
+ windowsNativeCaptureActive,
+ windowsOrphanedMicAudioPath,
+ windowsPendingVideoPath,
+ windowsSystemAudioPath,
+} from "../state";
+import type { CursorTelemetryPoint, NativeMacRecordingOptions, SelectedSource } from "../types";
+import {
+ getMacPrivacySettingsUrl,
+ getRecordingsDir,
+ getScreen,
+ getTelemetryPathForVideo,
+ moveFileWithOverwrite,
+ normalizeVideoSourcePath,
+ parseJsonWithByteOrderMark,
+ parseWindowId,
+} from "../utils";
+import { resolveWindowsCaptureTarget } from "../windowsCaptureSelection";
+
+const execFileAsync = promisify(execFile);
+
+async function writeWindowsRecordingDiagnostics(
+ videoPath: string | null | undefined,
+ snapshot: Omit,
+) {
+ if (!videoPath) {
+ return null;
+ }
+
+ try {
+ return await writeRecordingDiagnosticsSnapshot(videoPath, {
+ backend: "windows-wgc",
+ ...snapshot,
+ });
+ } catch (error) {
+ console.warn("Failed to write Windows recording diagnostics:", error);
+ return null;
+ }
+}
+
+function isRecord(value: unknown): value is Record {
+ return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function pickPrimitiveRecord(value: unknown) {
+ if (!isRecord(value)) {
+ return null;
+ }
+
+ const entries = Object.entries(value).filter(
+ (entry): entry is [string, boolean | number | string] => {
+ const primitive = entry[1];
+ return (
+ typeof primitive === "boolean" ||
+ typeof primitive === "number" ||
+ typeof primitive === "string"
+ );
+ },
+ );
+
+ return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+
+function normalizeRendererTimestampMs(value: unknown) {
+ const nowMs = Date.now();
+ if (typeof value !== "number" || !Number.isFinite(value)) {
+ return nowMs;
+ }
+
+ return Math.min(Math.max(0, Math.round(value)), nowMs);
+}
+
+function pickMicrophoneChunkEvents(value: unknown): MicrophoneChunkTimingEvent[] | null {
+ if (!Array.isArray(value)) {
+ return null;
+ }
+
+ const events = value
+ .map((event) => {
+ if (!isRecord(event)) {
+ return null;
+ }
+
+ const { index, size, elapsedMs, deltaMs, recordedElapsedMs, recordedDeltaMs } = event;
+ if (
+ typeof index !== "number" ||
+ !Number.isFinite(index) ||
+ index < 0 ||
+ typeof size !== "number" ||
+ !Number.isFinite(size) ||
+ size < 0 ||
+ typeof elapsedMs !== "number" ||
+ !Number.isFinite(elapsedMs) ||
+ elapsedMs < 0
+ ) {
+ return null;
+ }
+
+ return {
+ index: Math.round(index),
+ size: Math.round(size),
+ elapsedMs: Math.round(elapsedMs),
+ deltaMs:
+ typeof deltaMs === "number" && Number.isFinite(deltaMs)
+ ? Math.max(0, Math.round(deltaMs))
+ : null,
+ ...(typeof recordedElapsedMs === "number" &&
+ Number.isFinite(recordedElapsedMs) &&
+ recordedElapsedMs >= 0
+ ? { recordedElapsedMs: Math.round(recordedElapsedMs) }
+ : {}),
+ recordedDeltaMs:
+ typeof recordedDeltaMs === "number" && Number.isFinite(recordedDeltaMs)
+ ? Math.max(0, Math.round(recordedDeltaMs))
+ : null,
+ };
+ })
+ .filter((event): event is NonNullable => event !== null);
+
+ return events.length > 0 ? events : null;
+}
+
+function pickMicrophonePauseIntervals(value: unknown): MicrophonePauseInterval[] | null {
+ if (!Array.isArray(value)) {
+ return null;
+ }
+
+ const intervals = value
+ .map((interval) => {
+ if (
+ !isRecord(interval) ||
+ typeof interval.startElapsedMs !== "number" ||
+ !Number.isFinite(interval.startElapsedMs) ||
+ interval.startElapsedMs < 0
+ ) {
+ return null;
+ }
+
+ const startElapsedMs = Math.max(0, Math.round(interval.startElapsedMs));
+ return {
+ startElapsedMs,
+ ...(typeof interval.endElapsedMs === "number" &&
+ Number.isFinite(interval.endElapsedMs) &&
+ interval.endElapsedMs >= startElapsedMs
+ ? { endElapsedMs: Math.round(interval.endElapsedMs) }
+ : {}),
+ ...(typeof interval.durationMs === "number" &&
+ Number.isFinite(interval.durationMs) &&
+ interval.durationMs >= 0
+ ? { durationMs: Math.round(interval.durationMs) }
+ : {}),
+ };
+ })
+ .filter((interval): interval is NonNullable => interval !== null);
+
+ return intervals.length > 0 ? intervals : null;
+}
+
+function pickAudioInputDevices(value: unknown) {
+ if (!Array.isArray(value)) {
+ return null;
+ }
+
+ const devices = value
+ .map((device) => {
+ if (!isRecord(device) || typeof device.deviceId !== "string") {
+ return null;
+ }
+
+ return {
+ deviceId: device.deviceId,
+ ...(typeof device.groupId === "string" ? { groupId: device.groupId } : {}),
+ label: typeof device.label === "string" ? device.label : "",
+ };
+ })
+ .filter((device): device is NonNullable => device !== null);
+
+ return devices.length > 0 ? devices : null;
+}
+
+async function getSystemCursorAssets() {
+ if (process.platform !== "darwin") {
+ setCachedSystemCursorAssets({});
+ setCachedSystemCursorAssetsSourceMtimeMs(null);
+ return cachedSystemCursorAssets ?? {};
+ }
+ const sourcePath = getSystemCursorHelperSourcePath();
+ const sourceStat = await fs.stat(sourcePath);
+ if (cachedSystemCursorAssets && cachedSystemCursorAssetsSourceMtimeMs === sourceStat.mtimeMs) {
+ return cachedSystemCursorAssets;
+ }
+ const binaryPath = await ensureSwiftHelperBinary(
+ sourcePath,
+ getSystemCursorHelperBinaryPath(),
+ "system cursor helper",
+ "recordly-system-cursors",
+ );
+ const { stdout } = await execFileAsync(binaryPath, [], {
+ timeout: 15000,
+ maxBuffer: 20 * 1024 * 1024,
+ });
+ const parsed = JSON.parse(stdout) as Record<
+ string,
+ Partial
+ >;
+ const result = Object.fromEntries(
+ Object.entries(parsed).filter(
+ ([, asset]) =>
+ typeof asset?.dataUrl === "string" &&
+ typeof asset?.hotspotX === "number" &&
+ typeof asset?.hotspotY === "number" &&
+ typeof asset?.width === "number" &&
+ typeof asset?.height === "number",
+ ),
+ ) as Record;
+ setCachedSystemCursorAssets(result);
+ setCachedSystemCursorAssetsSourceMtimeMs(sourceStat.mtimeMs);
+ return result;
+}
+
+function normalizeDesktopSourceName(value: string) {
+ return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+async function cleanupWindowsOrphanedMicAudioPath(filePath: string | null) {
+ if (!filePath) {
+ return;
+ }
+
+ if (shouldKeepRecordingAudioSidecars()) {
+ console.log(`[recording] Keeping orphaned native mic sidecar for diagnostics: ${filePath}`);
+ return;
+ }
+
+ await fs.rm(filePath, { force: true }).catch(() => undefined);
+}
+
+async function pathExists(filePath: string | null | undefined) {
+ if (!filePath) {
+ return false;
+ }
+
+ try {
+ await fs.access(filePath);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function resolveExistingPath(...candidates: Array) {
+ for (const candidate of candidates) {
+ if (await pathExists(candidate)) {
+ return candidate ?? null;
+ }
+ }
+
+ return null;
+}
+
+export function registerRecordingHandlers(
+ onRecordingStateChange?: (recording: boolean, sourceName: string) => void,
+) {
+ ipcMain.handle(
+ "start-native-screen-recording",
+ async (_, source: SelectedSource, options?: NativeMacRecordingOptions) => {
+ // Windows native capture path
+ if (process.platform === "win32") {
+ const windowsCaptureAvailable = await isNativeWindowsCaptureAvailable();
+ if (!windowsCaptureAvailable) {
+ return {
+ success: false,
+ message: "Native Windows capture is not available on this system.",
+ };
+ }
+
+ if (windowsCaptureProcess && !windowsNativeCaptureActive) {
+ try {
+ windowsCaptureProcess.kill();
+ } catch {
+ /* ignore */
+ }
+ setWindowsCaptureProcess(null);
+ setWindowsCaptureTargetPath(null);
+ setWindowsCaptureStopRequested(false);
+ }
+
+ if (windowsCaptureProcess) {
+ return {
+ success: false,
+ message: "A native Windows screen recording is already active.",
+ };
+ }
+
+ let wcProc: ChildProcessWithoutNullStreams | null = null;
+ let tempVideoPath: string | null = null;
+ let tempSystemAudioPath: string | null = null;
+ let tempMicPath: string | null = null;
+ try {
+ const exePath = getWindowsCaptureExePath();
+ const recordingsDir = await getRecordingsDir();
+ const timestamp = Date.now();
+ const outputPath = path.join(recordingsDir, `recording-${timestamp}.mp4`);
+ tempVideoPath = path.join(
+ app.getPath("temp"),
+ `recordly-native-${timestamp}.mp4`,
+ );
+
+ let captureOutput = "";
+ let systemAudioPath: string | null = null;
+ let microphonePath: string | null = null;
+ let orphanedMicAudioPath: string | null = null;
+
+ const browserMicFallbackRequested =
+ shouldStartWindowsBrowserMicrophoneFallback(options);
+ const captureTarget = resolveWindowsCaptureTarget(
+ source,
+ getScreen().getAllDisplays(),
+ getScreen().getPrimaryDisplay(),
+ );
+ const displayBounds =
+ captureTarget.kind === "display" ? captureTarget.bounds : null;
+ setWindowsOrphanedMicAudioPath(null);
+
+ const config: Record = {
+ outputPath: tempVideoPath,
+ fps: 60,
+ };
+
+ if (captureTarget.kind === "invalid-window") {
+ return {
+ success: false,
+ message:
+ "Selected window is no longer available. Please choose the window again.",
+ };
+ }
+
+ if (captureTarget.kind === "window") {
+ config.windowHandle = captureTarget.windowHandle;
+ } else {
+ // Windows Graphics Capture (WGC) requires a raw HMONITOR handle.
+ // We attempt to resolve the handle by matching the physical coordinates of the target display.
+ const monitors = getMonitorHandles();
+ const matchedMonitor = monitors.find(
+ (monitor) =>
+ monitor.x === Math.round(captureTarget.bounds.x) &&
+ monitor.y === Math.round(captureTarget.bounds.y),
+ );
+
+ if (matchedMonitor) {
+ config.displayId = matchedMonitor.handle;
+ } else {
+ // Fallback to coordinate-based matching if handle resolution fails
+ config.displayId = captureTarget.displayId;
+ }
+
+ config.displayX = Math.round(captureTarget.bounds.x);
+ config.displayY = Math.round(captureTarget.bounds.y);
+ config.displayW = Math.round(captureTarget.bounds.width);
+ config.displayH = Math.round(captureTarget.bounds.height);
+ }
+
+ if (options?.capturesSystemAudio) {
+ systemAudioPath = path.join(
+ recordingsDir,
+ `recording-${timestamp}.system.wav`,
+ );
+ tempSystemAudioPath = path.join(
+ app.getPath("temp"),
+ `recordly-native-${timestamp}.system.wav`,
+ );
+ config.captureSystemAudio = true;
+ config.audioOutputPath = tempSystemAudioPath;
+ setWindowsSystemAudioPath(systemAudioPath);
+ } else {
+ setWindowsSystemAudioPath(null);
+ }
+
+ if (options?.capturesMicrophone && !browserMicFallbackRequested) {
+ microphonePath = path.join(recordingsDir, `recording-${timestamp}.mic.wav`);
+ tempMicPath = path.join(
+ app.getPath("temp"),
+ `recordly-native-${timestamp}.mic.wav`,
+ );
+ config.captureMic = true;
+ config.micOutputPath = tempMicPath;
+ if (options.microphoneLabel) {
+ config.micDeviceName = options.microphoneLabel;
+ }
+ setWindowsMicAudioPath(microphonePath);
+ } else if (browserMicFallbackRequested) {
+ config.captureMic = false;
+ setWindowsMicAudioPath(null);
+ } else {
+ setWindowsMicAudioPath(null);
+ }
+
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "start",
+ sourceId: source?.id ?? null,
+ sourceType: source?.sourceType ?? "unknown",
+ displayId: typeof config.displayId === "number" ? config.displayId : null,
+ displayBounds,
+ windowHandle:
+ typeof config.windowHandle === "number" ? config.windowHandle : null,
+ helperPath: exePath,
+ outputPath,
+ systemAudioPath,
+ microphonePath,
+ });
+
+ setWindowsCaptureOutputBuffer("");
+ setWindowsCaptureTargetPath(outputPath);
+ setWindowsCaptureStopRequested(false);
+ setWindowsCapturePaused(false);
+
+ // The native helper currently does not declare DPI awareness in its own
+ // manifest or process setup, so we keep the compatibility flag here until
+ // scaled-display capture is verified without it on Windows.
+ wcProc = spawn(exePath, [JSON.stringify(config)], {
+ cwd: recordingsDir,
+ stdio: ["pipe", "pipe", "pipe"],
+ env: { ...process.env, __COMPAT_LAYER: "HighDpiAware" },
+ });
+ setWindowsCaptureProcess(wcProc);
+ attachWindowsCaptureLifecycle(wcProc);
+
+ wcProc.stdout.on("data", (chunk: Buffer) => {
+ const msg = chunk.toString();
+ captureOutput += msg;
+ setWindowsCaptureOutputBuffer(captureOutput);
+ });
+ wcProc.stderr.on("data", (chunk: Buffer) => {
+ const msg = chunk.toString();
+ captureOutput += msg;
+ setWindowsCaptureOutputBuffer(captureOutput);
+ });
+
+ await waitForWindowsCaptureStart(wcProc);
+ const microphoneFallbackRequired =
+ browserMicFallbackRequested ||
+ shouldUseWindowsBrowserMicrophoneFallback(captureOutput, options);
+ if (microphoneFallbackRequired) {
+ orphanedMicAudioPath = tempMicPath ?? microphonePath;
+ setWindowsOrphanedMicAudioPath(orphanedMicAudioPath);
+ microphonePath = null;
+ setWindowsMicAudioPath(null);
+ }
+ setWindowsNativeCaptureActive(true);
+ setNativeScreenRecordingActive(true);
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "start",
+ sourceId: source?.id ?? null,
+ sourceType: source?.sourceType ?? "unknown",
+ displayId: typeof config.displayId === "number" ? config.displayId : null,
+ displayBounds,
+ windowHandle:
+ typeof config.windowHandle === "number" ? config.windowHandle : null,
+ helperPath: exePath,
+ outputPath,
+ systemAudioPath,
+ microphonePath,
+ processOutput: captureOutput.trim() || undefined,
+ });
+ return { success: true, microphoneFallbackRequired };
+ } catch (error) {
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "start",
+ sourceId: source?.id ?? null,
+ sourceType: source?.sourceType ?? "unknown",
+ helperPath: windowsCaptureTargetPath ? getWindowsCaptureExePath() : null,
+ outputPath: windowsCaptureTargetPath,
+ systemAudioPath: windowsSystemAudioPath,
+ microphonePath: windowsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ error: String(error),
+ });
+ console.error("Failed to start native Windows capture:", error);
+ try {
+ if (wcProc) wcProc.kill();
+ } catch {
+ /* ignore */
+ }
+ await Promise.allSettled([
+ tempVideoPath
+ ? fs.rm(tempVideoPath, { force: true }).catch(() => undefined)
+ : Promise.resolve(),
+ tempSystemAudioPath
+ ? fs.rm(tempSystemAudioPath, { force: true }).catch(() => undefined)
+ : Promise.resolve(),
+ tempMicPath
+ ? fs.rm(tempMicPath, { force: true }).catch(() => undefined)
+ : Promise.resolve(),
+ ]);
+ setWindowsNativeCaptureActive(false);
+ setNativeScreenRecordingActive(false);
+ setWindowsCaptureProcess(null);
+ setWindowsCaptureTargetPath(null);
+ setWindowsSystemAudioPath(null);
+ setWindowsMicAudioPath(null);
+ setWindowsOrphanedMicAudioPath(null);
+ setWindowsCaptureStopRequested(false);
+ setWindowsCapturePaused(false);
+ return {
+ success: false,
+ message: "Failed to start native Windows capture",
+ error: String(error),
+ };
+ }
+ }
+
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ message: "Native screen recording is only available on macOS.",
+ };
+ }
+
+ if (nativeCaptureProcess && !nativeScreenRecordingActive) {
+ try {
+ nativeCaptureProcess.kill();
+ } catch {
+ // ignore stale helper cleanup failures
+ }
+ setNativeCaptureProcess(null);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureStopRequested(false);
+ }
+
+ if (nativeCaptureProcess) {
+ return { success: false, message: "A native screen recording is already active." };
+ }
+
+ let captProc: ChildProcessWithoutNullStreams | null = null;
+ try {
+ const recordingsDir = await getRecordingsDir();
+
+ // Warm up TCC: trigger an Electron-level screen capture API call so macOS
+ // activates the screen-recording grant for this process tree before the
+ // native helper binary spawns and calls SCStream.startCapture().
+ try {
+ await desktopCapturer.getSources({
+ types: ["screen"],
+ thumbnailSize: { width: 1, height: 1 },
+ });
+ } catch {
+ // non-fatal – the helper will report its own TCC status
+ }
+
+ // Ensure microphone TCC is granted for this process tree when mic capture
+ // is requested, so the child helper inherits the grant.
+ if (options?.capturesMicrophone) {
+ const micStatus = systemPreferences.getMediaAccessStatus("microphone");
+ if (micStatus !== "granted") {
+ await systemPreferences.askForMediaAccess("microphone");
+ }
+ }
+
+ const appName = normalizeDesktopSourceName(String(source?.appName ?? ""));
+ const ownAppName = normalizeDesktopSourceName(app.getName());
+ if (
+ !ALLOW_RECORDLY_WINDOW_CAPTURE &&
+ source?.id?.startsWith("window:") &&
+ appName &&
+ (appName === ownAppName || appName === "recordly")
+ ) {
+ return {
+ success: false,
+ message:
+ "Cannot record Recordly windows. Please select another app window.",
+ };
+ }
+
+ const helperPath = await ensureNativeCaptureHelperBinary();
+ const timestamp = Date.now();
+ const outputPath = path.join(recordingsDir, `recording-${timestamp}.mp4`);
+ const capturesSystemAudio = Boolean(options?.capturesSystemAudio);
+ const capturesMicrophone = Boolean(options?.capturesMicrophone);
+ const systemAudioOutputPath = capturesSystemAudio
+ ? path.join(recordingsDir, `recording-${timestamp}.system.m4a`)
+ : null;
+ const microphoneOutputPath = capturesMicrophone
+ ? path.join(recordingsDir, `recording-${timestamp}.mic.m4a`)
+ : null;
+ const config: Record = {
+ fps: 60,
+ outputPath,
+ capturesSystemAudio,
+ capturesMicrophone,
+ };
+
+ if (options?.microphoneDeviceId) {
+ config.microphoneDeviceId = options.microphoneDeviceId;
+ }
+
+ if (options?.microphoneLabel) {
+ config.microphoneLabel = options.microphoneLabel;
+ }
+
+ if (systemAudioOutputPath) {
+ config.systemAudioOutputPath = systemAudioOutputPath;
+ }
+
+ if (microphoneOutputPath) {
+ config.microphoneOutputPath = microphoneOutputPath;
+ }
+
+ const windowId = parseWindowId(source?.id);
+ const screenId = Number(source?.display_id);
+
+ if (Number.isFinite(windowId) && windowId && source?.id?.startsWith("window:")) {
+ config.windowId = windowId;
+ } else if (Number.isFinite(screenId) && screenId > 0) {
+ config.displayId = screenId;
+ } else {
+ config.displayId = Number(getScreen().getPrimaryDisplay().id);
+ }
+
+ setNativeCaptureOutputBuffer("");
+ setNativeCaptureTargetPath(outputPath);
+ setNativeCaptureSystemAudioPath(systemAudioOutputPath);
+ setNativeCaptureMicrophonePath(microphoneOutputPath);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+ captProc = spawn(helperPath, [JSON.stringify(config)], {
+ cwd: recordingsDir,
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ setNativeCaptureProcess(captProc);
+ attachNativeCaptureLifecycle(captProc);
+
+ captProc.stdout.on("data", (chunk: Buffer) => {
+ setNativeCaptureOutputBuffer(nativeCaptureOutputBuffer + chunk.toString());
+ });
+ captProc.stderr.on("data", (chunk: Buffer) => {
+ setNativeCaptureOutputBuffer(nativeCaptureOutputBuffer + chunk.toString());
+ });
+
+ await waitForNativeCaptureStart(captProc);
+ setNativeScreenRecordingActive(true);
+
+ // If the native helper reported MICROPHONE_CAPTURE_UNAVAILABLE, it started
+ // capture without microphone. Clear the mic path so the renderer can fall
+ // back to a browser-side sidecar recording for the microphone track.
+ const micUnavailableNatively = nativeCaptureOutputBuffer.includes(
+ "MICROPHONE_CAPTURE_UNAVAILABLE",
+ );
+ if (micUnavailableNatively) {
+ setNativeCaptureMicrophonePath(null);
+ }
+
+ recordNativeCaptureDiagnostics({
+ backend: "mac-screencapturekit",
+ phase: "start",
+ sourceId: source?.id ?? null,
+ sourceType: source?.sourceType ?? "unknown",
+ displayId: typeof config.displayId === "number" ? config.displayId : null,
+ helperPath,
+ outputPath,
+ systemAudioPath: systemAudioOutputPath,
+ microphonePath: nativeCaptureMicrophonePath,
+ processOutput: nativeCaptureOutputBuffer.trim() || undefined,
+ });
+ return { success: true, microphoneFallbackRequired: micUnavailableNatively };
+ } catch (error) {
+ console.error("Failed to start native ScreenCaptureKit recording:", error);
+ const errorStr = String(error);
+
+ // Detect TCC (screen recording permission) errors and show a helpful dialog
+ if (
+ errorStr.includes("declined TCC") ||
+ errorStr.includes("declined TCCs") ||
+ errorStr.includes("SCREEN_RECORDING_PERMISSION_DENIED")
+ ) {
+ const { response } = await dialog.showMessageBox({
+ type: "warning",
+ title: "Screen Recording Permission Required",
+ message:
+ "Recordly needs screen recording permission to capture your screen.",
+ detail: "Please open System Settings > Privacy & Security > Screen Recording, make sure Recordly is toggled ON, then try recording again.",
+ buttons: ["Open System Settings", "Cancel"],
+ defaultId: 0,
+ cancelId: 1,
+ });
+ if (response === 0) {
+ await shell.openExternal(getMacPrivacySettingsUrl("screen"));
+ }
+ try {
+ if (captProc) captProc.kill();
+ } catch {
+ /* ignore */
+ }
+ setNativeScreenRecordingActive(false);
+ setNativeCaptureProcess(null);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+ return {
+ success: false,
+ message:
+ "Screen recording permission not granted. Please allow access in System Settings and restart the app.",
+ userNotified: true,
+ };
+ }
+
+ if (errorStr.includes("MICROPHONE_PERMISSION_DENIED")) {
+ const { response } = await dialog.showMessageBox({
+ type: "warning",
+ title: "Microphone Permission Required",
+ message: "Recordly needs microphone permission to record audio.",
+ detail: "Please open System Settings > Privacy & Security > Microphone, make sure Recordly is toggled ON, then try recording again.",
+ buttons: ["Open System Settings", "Cancel"],
+ defaultId: 0,
+ cancelId: 1,
+ });
+ if (response === 0) {
+ await shell.openExternal(getMacPrivacySettingsUrl("microphone"));
+ }
+ try {
+ if (captProc) captProc.kill();
+ } catch {
+ /* ignore */
+ }
+ setNativeScreenRecordingActive(false);
+ setNativeCaptureProcess(null);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+ return {
+ success: false,
+ message:
+ "Microphone permission not granted. Please allow access in System Settings.",
+ userNotified: true,
+ };
+ }
+
+ recordNativeCaptureDiagnostics({
+ backend: "mac-screencapturekit",
+ phase: "start",
+ sourceId: source?.id ?? null,
+ sourceType: source?.sourceType ?? "unknown",
+ helperPath: getNativeCaptureHelperBinaryPath(),
+ outputPath: nativeCaptureTargetPath,
+ systemAudioPath: nativeCaptureSystemAudioPath,
+ microphonePath: nativeCaptureMicrophonePath,
+ processOutput: nativeCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: await getFileSizeIfPresent(nativeCaptureTargetPath),
+ error: String(error),
+ });
+ try {
+ if (captProc) captProc.kill();
+ } catch {
+ // ignore cleanup failures
+ }
+ setNativeScreenRecordingActive(false);
+ setNativeCaptureProcess(null);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+ return {
+ success: false,
+ message: "Failed to start native ScreenCaptureKit recording",
+ error: String(error),
+ };
+ }
+ },
+ );
+
+ ipcMain.handle("stop-native-screen-recording", async () => {
+ const start = Date.now();
+ console.log("[PERF:MAIN] Handler: stop-native-screen-recording: STARTED");
+ try {
+ // Windows native capture stop path
+ if (process.platform === "win32" && windowsNativeCaptureActive) {
+ let stagedTempVideoPath: string | null = null;
+ let stagedTempSystemAudioPath: string | null = null;
+ let stagedTempMicAudioPath: string | null = null;
+ try {
+ if (!windowsCaptureProcess) {
+ throw new Error("Native Windows capture process is not running");
+ }
+
+ const proc = windowsCaptureProcess;
+ const preferredVideoPath = windowsCaptureTargetPath;
+ const preferredOrphanedMicAudioPath = windowsOrphanedMicAudioPath;
+ const diagnosticsSystemAudioPath = windowsSystemAudioPath;
+ const diagnosticsMicAudioPath = windowsMicAudioPath;
+ setWindowsCaptureStopRequested(true);
+ proc.stdin.write("stop\n");
+ const tempVideoPath = await waitForWindowsCaptureStop(proc);
+ stagedTempVideoPath = tempVideoPath;
+ const finalVideoPath = preferredVideoPath ?? tempVideoPath;
+
+ // Native Windows capture results are initially written to a safe temporary path
+ // (to avoid encoding failures with non-ASCII characters). We move them to the final
+ // destination now using Node.js, which handles Unicode paths correctly.
+ if (tempVideoPath !== finalVideoPath) {
+ await moveFileWithOverwrite(tempVideoPath, finalVideoPath);
+ }
+
+ if (windowsSystemAudioPath && tempVideoPath.endsWith(".mp4")) {
+ const tempAudioPath = tempVideoPath.replace(".mp4", ".system.wav");
+ stagedTempSystemAudioPath = tempAudioPath;
+ const finalAudioPath = windowsSystemAudioPath;
+ if (await pathExists(tempAudioPath)) {
+ await moveFileWithOverwrite(tempAudioPath, finalAudioPath);
+ const tempJson = tempAudioPath + ".json";
+ if (await pathExists(tempJson)) {
+ await moveFileWithOverwrite(tempJson, finalAudioPath + ".json");
+ }
+ }
+ }
+
+ if (windowsMicAudioPath && tempVideoPath.endsWith(".mp4")) {
+ const tempMicPath = tempVideoPath.replace(".mp4", ".mic.wav");
+ stagedTempMicAudioPath = tempMicPath;
+ const finalMicPath = windowsMicAudioPath;
+ if (await pathExists(tempMicPath)) {
+ await moveFileWithOverwrite(tempMicPath, finalMicPath);
+ const tempJson = tempMicPath + ".json";
+ if (await pathExists(tempJson)) {
+ await moveFileWithOverwrite(tempJson, finalMicPath + ".json");
+ }
+ }
+ }
+ const validation = await validateRecordedVideo(finalVideoPath);
+
+ setWindowsCaptureProcess(null);
+ setWindowsNativeCaptureActive(false);
+ setNativeScreenRecordingActive(false);
+ setWindowsCaptureTargetPath(null);
+ setWindowsCaptureStopRequested(false);
+ setWindowsCapturePaused(false);
+ setWindowsOrphanedMicAudioPath(null);
+ await cleanupWindowsOrphanedMicAudioPath(preferredOrphanedMicAudioPath);
+ setWindowsPendingVideoPath(finalVideoPath);
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "stop",
+ outputPath: finalVideoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: validation.fileSizeBytes,
+ });
+ await writeWindowsRecordingDiagnostics(finalVideoPath, {
+ phase: "stop",
+ outputPath: finalVideoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ details: {
+ fileSizeBytes: validation.fileSizeBytes,
+ durationSeconds: validation.durationSeconds,
+ },
+ });
+
+ // Persist cursor telemetry before returning so the editor can find it immediately
+ snapshotCursorTelemetryForPersistence();
+ try {
+ await persistPendingCursorTelemetry(finalVideoPath);
+ } catch (error) {
+ console.warn(
+ "Failed to persist cursor telemetry during native stop:",
+ error,
+ );
+ }
+
+ return { success: true, path: finalVideoPath };
+ } catch (error) {
+ console.error("Failed to stop native Windows capture:", error);
+ const fallbackPath = await resolveExistingPath(
+ windowsCaptureTargetPath,
+ stagedTempVideoPath,
+ );
+ const recoveredSystemAudioPath = await resolveExistingPath(
+ windowsSystemAudioPath,
+ stagedTempSystemAudioPath,
+ );
+ const recoveredMicAudioPath = await resolveExistingPath(
+ windowsMicAudioPath,
+ stagedTempMicAudioPath,
+ );
+ const fallbackOrphanedMicAudioPath = windowsOrphanedMicAudioPath;
+ const diagnosticsSystemAudioPath =
+ recoveredSystemAudioPath ?? windowsSystemAudioPath;
+ const diagnosticsMicAudioPath = recoveredMicAudioPath ?? windowsMicAudioPath;
+ setWindowsNativeCaptureActive(false);
+ setNativeScreenRecordingActive(false);
+ setWindowsCaptureProcess(null);
+ setWindowsCaptureTargetPath(null);
+ setWindowsCaptureStopRequested(false);
+ setWindowsCapturePaused(false);
+ setWindowsOrphanedMicAudioPath(null);
+
+ if (fallbackPath) {
+ try {
+ const validation = await validateRecordedVideo(fallbackPath);
+ setWindowsPendingVideoPath(fallbackPath);
+ setWindowsSystemAudioPath(recoveredSystemAudioPath);
+ setWindowsMicAudioPath(recoveredMicAudioPath);
+ await cleanupWindowsOrphanedMicAudioPath(fallbackOrphanedMicAudioPath);
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "stop",
+ outputPath: fallbackPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: validation.fileSizeBytes,
+ error: String(error),
+ });
+ await writeWindowsRecordingDiagnostics(fallbackPath, {
+ phase: "stop",
+ outputPath: fallbackPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ error: String(error),
+ details: {
+ fileSizeBytes: validation.fileSizeBytes,
+ durationSeconds: validation.durationSeconds,
+ recoveredAfterStopFailure: true,
+ },
+ });
+ return { success: true, path: fallbackPath };
+ } catch {
+ // File is absent or failed validation.
+ }
+ }
+
+ setWindowsSystemAudioPath(null);
+ setWindowsMicAudioPath(null);
+ setWindowsPendingVideoPath(null);
+ await cleanupWindowsOrphanedMicAudioPath(fallbackOrphanedMicAudioPath);
+
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "stop",
+ outputPath: fallbackPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: await getFileSizeIfPresent(fallbackPath),
+ error: String(error),
+ });
+ await writeWindowsRecordingDiagnostics(fallbackPath, {
+ phase: "stop",
+ outputPath: fallbackPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ processOutput: windowsCaptureOutputBuffer.trim() || undefined,
+ error: String(error),
+ details: {
+ fileSizeBytes: await getFileSizeIfPresent(fallbackPath),
+ },
+ });
+
+ return {
+ success: false,
+ message: "Failed to stop native Windows capture",
+ error: String(error),
+ };
+ }
+ }
+
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ message: "Native screen recording is only available on macOS.",
+ };
+ }
+
+ if (!nativeScreenRecordingActive) {
+ const recovered = await recoverNativeMacCaptureOutput();
+ if (recovered) {
+ return recovered;
+ }
+
+ return { success: false, message: "No native screen recording is active." };
+ }
+
+ try {
+ if (!nativeCaptureProcess) {
+ throw new Error("Native capture helper process is not running");
+ }
+
+ const process = nativeCaptureProcess;
+ const preferredVideoPath = nativeCaptureTargetPath;
+ const preferredSystemAudioPath = nativeCaptureSystemAudioPath;
+ const preferredMicrophonePath = nativeCaptureMicrophonePath;
+ console.log(
+ "[stop-native] Audio paths — system:",
+ preferredSystemAudioPath,
+ "mic:",
+ preferredMicrophonePath,
+ );
+ setNativeCaptureStopRequested(true);
+ process.stdin.write("stop\n");
+ const tempVideoPath = await waitForNativeCaptureStop(process);
+ console.log("[stop-native] Helper stopped, tempVideoPath:", tempVideoPath);
+ setNativeCaptureProcess(null);
+ setNativeScreenRecordingActive(false);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+
+ const finalVideoPath = preferredVideoPath ?? tempVideoPath;
+ if (tempVideoPath !== finalVideoPath) {
+ await moveFileWithOverwrite(tempVideoPath, finalVideoPath);
+ }
+
+ if (preferredSystemAudioPath || preferredMicrophonePath) {
+ console.log(
+ "[stop-native] Attempting audio mux (merging separate tracks) into:",
+ finalVideoPath,
+ );
+ try {
+ await muxNativeMacRecordingWithAudio(
+ finalVideoPath,
+ preferredSystemAudioPath,
+ preferredMicrophonePath,
+ );
+ console.log("[stop-native] Audio mux completed successfully");
+ } catch (error) {
+ console.warn(
+ "[stop-native] Audio mux failed (video still has inline audio):",
+ error,
+ );
+ }
+ } else {
+ console.log("[stop-native] No separate audio tracks to mux");
+ }
+
+ return await finalizeStoredVideo(finalVideoPath);
+ } catch (error) {
+ console.error("Failed to stop native ScreenCaptureKit recording:", error);
+ const fallbackPath = nativeCaptureTargetPath;
+ const fallbackSystemAudioPath = nativeCaptureSystemAudioPath;
+ const fallbackMicrophonePath = nativeCaptureMicrophonePath;
+ const fallbackFileSizeBytes = await getFileSizeIfPresent(fallbackPath);
+ setNativeScreenRecordingActive(false);
+ setNativeCaptureProcess(null);
+ setNativeCaptureTargetPath(null);
+ setNativeCaptureSystemAudioPath(null);
+ setNativeCaptureMicrophonePath(null);
+ setNativeCaptureStopRequested(false);
+ setNativeCapturePaused(false);
+
+ recordNativeCaptureDiagnostics({
+ backend: "mac-screencapturekit",
+ phase: "stop",
+ sourceId: lastNativeCaptureDiagnostics?.sourceId ?? null,
+ sourceType: lastNativeCaptureDiagnostics?.sourceType ?? "unknown",
+ displayId: lastNativeCaptureDiagnostics?.displayId ?? null,
+ displayBounds: lastNativeCaptureDiagnostics?.displayBounds ?? null,
+ windowHandle: lastNativeCaptureDiagnostics?.windowHandle ?? null,
+ helperPath: lastNativeCaptureDiagnostics?.helperPath ?? null,
+ outputPath: fallbackPath,
+ systemAudioPath: fallbackSystemAudioPath,
+ microphonePath: fallbackMicrophonePath,
+ osRelease: lastNativeCaptureDiagnostics?.osRelease,
+ supported: lastNativeCaptureDiagnostics?.supported,
+ helperExists: lastNativeCaptureDiagnostics?.helperExists,
+ processOutput: nativeCaptureOutputBuffer.trim() || undefined,
+ fileSizeBytes: fallbackFileSizeBytes,
+ error: String(error),
+ });
+
+ // Try to recover: if the target file exists on disk, finalize with it
+ if (fallbackPath) {
+ try {
+ await fs.access(fallbackPath);
+ console.log(
+ "[stop-native-screen-recording] Recovering with fallback path:",
+ fallbackPath,
+ );
+ if (fallbackSystemAudioPath || fallbackMicrophonePath) {
+ try {
+ await muxNativeMacRecordingWithAudio(
+ fallbackPath,
+ fallbackSystemAudioPath,
+ fallbackMicrophonePath,
+ );
+ } catch (muxError) {
+ console.warn(
+ "Failed to mux recovered native macOS audio into capture:",
+ muxError,
+ );
+ }
+ }
+ return await finalizeStoredVideo(fallbackPath);
+ } catch {
+ // File doesn't exist or isn't accessible
+ }
+ }
+
+ const recovered = await recoverNativeMacCaptureOutput();
+ if (recovered) {
+ return recovered;
+ }
+
+ return {
+ success: false,
+ message: "Failed to stop native ScreenCaptureKit recording",
+ error: String(error),
+ };
+ }
+ } finally {
+ console.log(
+ `[PERF:MAIN] Handler: stop-native-screen-recording: COMPLETED in ${Date.now() - start}ms`,
+ );
+ }
+ });
+
+ ipcMain.handle("recover-native-screen-recording", async () => {
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ message: "Native screen recording recovery is only available on macOS.",
+ };
+ }
+
+ const recovered = await recoverNativeMacCaptureOutput();
+ if (recovered) {
+ return recovered;
+ }
+
+ return {
+ success: false,
+ message: "No recoverable native macOS recording output was found.",
+ };
+ });
+
+ ipcMain.handle("pause-native-screen-recording", async () => {
+ if (process.platform === "win32") {
+ if (!windowsNativeCaptureActive || !windowsCaptureProcess) {
+ return { success: false, message: "No native Windows screen recording is active." };
+ }
+
+ if (windowsCapturePaused) {
+ return { success: true };
+ }
+
+ try {
+ windowsCaptureProcess.stdin.write("pause\n");
+ setWindowsCapturePaused(true);
+ return { success: true };
+ } catch (error) {
+ return {
+ success: false,
+ message: "Failed to pause native Windows capture",
+ error: String(error),
+ };
+ }
+ }
+
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ message: "Native screen recording is only available on macOS.",
+ };
+ }
+
+ if (!nativeScreenRecordingActive || !nativeCaptureProcess) {
+ return { success: false, message: "No native screen recording is active." };
+ }
+
+ if (nativeCapturePaused) {
+ return { success: true };
+ }
+
+ try {
+ const commandApplied = waitForNativeCaptureCommand(
+ nativeCaptureProcess,
+ "Recording paused",
+ );
+ nativeCaptureProcess.stdin.write("pause\n");
+ await commandApplied;
+ setNativeCapturePaused(true);
+ return { success: true };
+ } catch (error) {
+ return {
+ success: false,
+ message: "Failed to pause native screen recording",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("resume-native-screen-recording", async () => {
+ if (process.platform === "win32") {
+ if (!windowsNativeCaptureActive || !windowsCaptureProcess) {
+ return { success: false, message: "No native Windows screen recording is active." };
+ }
+
+ if (!windowsCapturePaused) {
+ return { success: true };
+ }
+
+ try {
+ windowsCaptureProcess.stdin.write("resume\n");
+ setWindowsCapturePaused(false);
+ return { success: true };
+ } catch (error) {
+ return {
+ success: false,
+ message: "Failed to resume native Windows capture",
+ error: String(error),
+ };
+ }
+ }
+
+ if (process.platform !== "darwin") {
+ return {
+ success: false,
+ message: "Native screen recording is only available on macOS.",
+ };
+ }
+
+ if (!nativeScreenRecordingActive || !nativeCaptureProcess) {
+ return { success: false, message: "No native screen recording is active." };
+ }
+
+ if (!nativeCapturePaused) {
+ return { success: true };
+ }
+
+ try {
+ const commandApplied = waitForNativeCaptureCommand(
+ nativeCaptureProcess,
+ "Recording resumed",
+ );
+ nativeCaptureProcess.stdin.write("resume\n");
+ await commandApplied;
+ setNativeCapturePaused(false);
+ return { success: true };
+ } catch (error) {
+ return {
+ success: false,
+ message: "Failed to resume native screen recording",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("get-system-cursor-assets", async () => {
+ try {
+ return { success: true, cursors: await getSystemCursorAssets() };
+ } catch (error) {
+ console.error("Failed to load system cursor assets:", error);
+ return { success: false, cursors: {}, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("is-native-windows-capture-available", async () => {
+ return { available: await isNativeWindowsCaptureAvailable() };
+ });
+
+ ipcMain.handle("get-last-native-capture-diagnostics", async () => {
+ return { success: true, diagnostics: lastNativeCaptureDiagnostics };
+ });
+
+ ipcMain.handle("get-video-audio-fallback-paths", async (_event, videoPath: string) => {
+ if (!videoPath) {
+ return { success: true, paths: [], startDelayMsByPath: {} };
+ }
+
+ try {
+ const { paths, startDelayMsByPath } = await getCompanionAudioFallbackInfo(videoPath);
+ await Promise.all([
+ rememberApprovedLocalReadPath(videoPath),
+ ...paths.map((fallbackPath) => rememberApprovedLocalReadPath(fallbackPath)),
+ ]);
+ return { success: true, paths, startDelayMsByPath };
+ } catch (error) {
+ console.error("Failed to resolve companion audio fallback paths:", error);
+ return { success: false, paths: [], startDelayMsByPath: {}, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("mux-native-windows-recording", async (_event, expectedDurationMs?: number) => {
+ const start = Date.now();
+ console.log("[PERF:MAIN] Handler: mux-native-windows-recording: STARTED");
+ try {
+ const videoPath = windowsPendingVideoPath;
+ const orphanedMicAudioPath = windowsOrphanedMicAudioPath;
+ const diagnosticsSystemAudioPath = windowsSystemAudioPath;
+ const diagnosticsMicAudioPath = windowsMicAudioPath;
+ setWindowsPendingVideoPath(null);
+ setWindowsOrphanedMicAudioPath(null);
+
+ if (!videoPath) {
+ return { success: false, message: "No native Windows video pending for mux" };
+ }
+
+ try {
+ await writeWindowsRecordingDiagnostics(videoPath, {
+ phase: "mux-start",
+ expectedDurationMs,
+ outputPath: videoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ details: {
+ hasSystemAudio: Boolean(diagnosticsSystemAudioPath),
+ hasMicrophone: Boolean(diagnosticsMicAudioPath),
+ hasOrphanedMicrophone: Boolean(orphanedMicAudioPath),
+ },
+ });
+ console.log("[mux-win] Optimization active: skipping video padding.");
+
+ let muxDetails: unknown = null;
+ if (diagnosticsSystemAudioPath || diagnosticsMicAudioPath) {
+ muxDetails = await muxNativeWindowsVideoWithAudio(
+ videoPath,
+ diagnosticsSystemAudioPath,
+ diagnosticsMicAudioPath,
+ );
+ setWindowsSystemAudioPath(null);
+ setWindowsMicAudioPath(null);
+ }
+
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "mux",
+ outputPath: videoPath,
+ fileSizeBytes: await getFileSizeIfPresent(videoPath),
+ });
+ await writeWindowsRecordingDiagnostics(videoPath, {
+ phase: "mux-complete",
+ expectedDurationMs,
+ outputPath: videoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ details: {
+ fileSizeBytes: await getFileSizeIfPresent(videoPath),
+ mux: muxDetails,
+ },
+ });
+ await cleanupWindowsOrphanedMicAudioPath(orphanedMicAudioPath);
+ return await finalizeStoredVideo(videoPath);
+ } catch (error) {
+ console.error("Failed to mux native Windows recording:", error);
+ recordNativeCaptureDiagnostics({
+ backend: "windows-wgc",
+ phase: "mux",
+ outputPath: videoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ fileSizeBytes: await getFileSizeIfPresent(videoPath),
+ error: String(error),
+ });
+ await writeWindowsRecordingDiagnostics(videoPath, {
+ phase: "mux-error",
+ expectedDurationMs,
+ outputPath: videoPath,
+ systemAudioPath: diagnosticsSystemAudioPath,
+ microphonePath: diagnosticsMicAudioPath,
+ error: String(error),
+ details: {
+ fileSizeBytes: await getFileSizeIfPresent(videoPath),
+ },
+ });
+ setWindowsSystemAudioPath(null);
+ setWindowsMicAudioPath(null);
+ await cleanupWindowsOrphanedMicAudioPath(orphanedMicAudioPath);
+ try {
+ return await finalizeStoredVideo(videoPath);
+ } catch {
+ try {
+ await validateRecordedVideo(videoPath);
+ return {
+ success: false,
+ path: videoPath,
+ message: "Failed to mux native Windows recording",
+ error: String(error),
+ };
+ } catch {
+ // The fallback path is not safely playable; surface the original mux error.
+ }
+
+ return {
+ success: false,
+ message: "Failed to mux native Windows recording",
+ error: String(error),
+ };
+ }
+ }
+ } finally {
+ console.log(
+ `[PERF:MAIN] Handler: mux-native-windows-recording: COMPLETED in ${Date.now() - start}ms`,
+ );
+ }
+ });
+
+ ipcMain.handle("start-ffmpeg-recording", async (_, source: SelectedSource) => {
+ if (ffmpegCaptureProcess) {
+ return { success: false, message: "An FFmpeg recording is already active." };
+ }
+
+ try {
+ const recordingsDir = await getRecordingsDir();
+ const ffmpegPath = getFfmpegBinaryPath();
+ const outputPath = path.join(recordingsDir, `recording-${Date.now()}.mp4`);
+ const args = await buildFfmpegCaptureArgs(source, outputPath);
+
+ setFfmpegCaptureOutputBuffer("");
+ setFfmpegCaptureTargetPath(outputPath);
+ const ffProc = spawn(ffmpegPath, args, {
+ cwd: recordingsDir,
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ setFfmpegCaptureProcess(ffProc);
+
+ ffProc.stdout.on("data", (chunk: Buffer) => {
+ setFfmpegCaptureOutputBuffer(ffmpegCaptureOutputBuffer + chunk.toString());
+ });
+ ffProc.stderr.on("data", (chunk: Buffer) => {
+ setFfmpegCaptureOutputBuffer(ffmpegCaptureOutputBuffer + chunk.toString());
+ });
+
+ await waitForFfmpegCaptureStart(ffProc);
+ setFfmpegScreenRecordingActive(true);
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to start FFmpeg recording:", error);
+ setFfmpegScreenRecordingActive(false);
+ setFfmpegCaptureProcess(null);
+ setFfmpegCaptureTargetPath(null);
+ return {
+ success: false,
+ message: "Failed to start FFmpeg recording",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("stop-ffmpeg-recording", async () => {
+ if (!ffmpegScreenRecordingActive) {
+ return { success: false, message: "No FFmpeg recording is active." };
+ }
+
+ try {
+ if (!ffmpegCaptureProcess || !ffmpegCaptureTargetPath) {
+ throw new Error("FFmpeg process is not running");
+ }
+
+ const process = ffmpegCaptureProcess;
+ const outputPath = ffmpegCaptureTargetPath;
+ process.stdin.write("q\n");
+ const finalVideoPath = await waitForFfmpegCaptureStop(process, outputPath);
+
+ setFfmpegCaptureProcess(null);
+ setFfmpegCaptureTargetPath(null);
+ setFfmpegScreenRecordingActive(false);
+
+ return await finalizeStoredVideo(finalVideoPath);
+ } catch (error) {
+ console.error("Failed to stop FFmpeg recording:", error);
+ try {
+ ffmpegCaptureProcess?.kill();
+ } catch {
+ // ignore cleanup failures
+ }
+ setFfmpegCaptureProcess(null);
+ setFfmpegCaptureTargetPath(null);
+ setFfmpegScreenRecordingActive(false);
+ return {
+ success: false,
+ message: "Failed to stop FFmpeg recording",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle(
+ "store-microphone-sidecar",
+ async (
+ _,
+ audioData: ArrayBuffer,
+ videoPath: string,
+ options?: {
+ startDelayMs?: number;
+ browserMicrophoneProfile?: string;
+ requestedBrowserMicrophoneProfile?: string | null;
+ requestedConstraints?: unknown;
+ mediaTrackSettings?: Record;
+ audioInputDevices?: unknown;
+ mediaRecorder?: unknown;
+ chunkEvents?: unknown;
+ pauseIntervals?: unknown;
+ },
+ ) => {
+ const baseName = videoPath.replace(/\.[^.]+$/, "");
+ const sidecarPath = `${baseName}.mic.wav`;
+ const sourceWebmPath = `${baseName}.mic.source.webm`;
+ const tempWebmPath = `${sourceWebmPath}.tmp`;
+
+ try {
+ await fs.writeFile(tempWebmPath, Buffer.from(audioData));
+ await execFileAsync(
+ getFfmpegBinaryPath(),
+ [
+ "-y",
+ "-hide_banner",
+ "-nostdin",
+ "-nostats",
+ "-i",
+ tempWebmPath,
+ "-vn",
+ "-ac",
+ "1",
+ "-ar",
+ "48000",
+ "-af",
+ [
+ ...getBrowserMicSidecarFilters(options?.browserMicrophoneProfile),
+ "aresample=async=1:first_pts=0",
+ ].join(","),
+ "-c:a",
+ "pcm_s16le",
+ sidecarPath,
+ ],
+ { timeout: 120000, maxBuffer: 10 * 1024 * 1024 },
+ );
+ if (shouldKeepRecordingAudioSidecars()) {
+ await fs.rename(tempWebmPath, sourceWebmPath).catch(async () => {
+ await fs.copyFile(tempWebmPath, sourceWebmPath);
+ await fs.rm(tempWebmPath, { force: true });
+ });
+ } else {
+ await fs.rm(tempWebmPath, { force: true });
+ }
+ const startDelayMs = options?.startDelayMs;
+ const mediaTrackSettings = pickPrimitiveRecord(options?.mediaTrackSettings);
+ const audioInputDevices = pickAudioInputDevices(options?.audioInputDevices);
+ const mediaRecorder = isRecord(options?.mediaRecorder)
+ ? {
+ ...(typeof options.mediaRecorder.mimeType === "string"
+ ? { mimeType: options.mediaRecorder.mimeType }
+ : {}),
+ ...(typeof options.mediaRecorder.audioBitsPerSecond === "number"
+ ? {
+ audioBitsPerSecond: Math.round(
+ options.mediaRecorder.audioBitsPerSecond,
+ ),
+ }
+ : {}),
+ ...(typeof options.mediaRecorder.timesliceMs === "number"
+ ? { timesliceMs: Math.round(options.mediaRecorder.timesliceMs) }
+ : {}),
+ }
+ : null;
+ const chunkEvents = pickMicrophoneChunkEvents(options?.chunkEvents);
+ const pauseIntervals = pickMicrophonePauseIntervals(options?.pauseIntervals);
+ const chunkTiming =
+ chunkEvents || pauseIntervals
+ ? summarizeMicrophoneChunkTiming(
+ chunkEvents,
+ pauseIntervals,
+ mediaRecorder?.timesliceMs,
+ )
+ : null;
+ const metadata = {
+ ...(Number.isFinite(startDelayMs) && (startDelayMs ?? 0) >= 0
+ ? { startDelayMs: Math.round(startDelayMs ?? 0) }
+ : {}),
+ ...(typeof options?.browserMicrophoneProfile === "string"
+ ? { browserMicrophoneProfile: options.browserMicrophoneProfile }
+ : {}),
+ ...(typeof options?.requestedBrowserMicrophoneProfile === "string"
+ ? {
+ requestedBrowserMicrophoneProfile:
+ options.requestedBrowserMicrophoneProfile,
+ }
+ : {}),
+ ...(isRecord(options?.requestedConstraints)
+ ? { requestedConstraints: options.requestedConstraints }
+ : {}),
+ ...(mediaTrackSettings ? { mediaTrackSettings } : {}),
+ ...(audioInputDevices ? { audioInputDevices } : {}),
+ ...(mediaRecorder && Object.keys(mediaRecorder).length > 0
+ ? { mediaRecorder }
+ : {}),
+ ...(chunkEvents ? { chunkEvents } : {}),
+ ...(pauseIntervals ? { pauseIntervals } : {}),
+ ...(chunkTiming ? { chunkTiming } : {}),
+ };
+ if (Object.keys(metadata).length > 0) {
+ try {
+ await fs.writeFile(`${sidecarPath}.json`, JSON.stringify(metadata));
+ } catch (metadataError) {
+ console.warn(
+ "Failed to store microphone sidecar timing metadata:",
+ metadataError,
+ );
+ }
+ }
+ await writeRecordingDiagnosticsSnapshot(videoPath, {
+ backend: "browser-store",
+ phase: "mic-sidecar",
+ outputPath: videoPath,
+ microphonePath: sidecarPath,
+ details: {
+ sourceBytes: audioData.byteLength,
+ sourceWebmPath: shouldKeepRecordingAudioSidecars() ? sourceWebmPath : null,
+ metadata,
+ },
+ }).catch((diagnosticsError) => {
+ console.warn(
+ "Failed to write microphone sidecar diagnostics:",
+ diagnosticsError,
+ );
+ });
+ return { success: true, path: sidecarPath };
+ } catch (error) {
+ await Promise.all([
+ fs.rm(tempWebmPath, { force: true }).catch(() => undefined),
+ fs.rm(sidecarPath, { force: true }).catch(() => undefined),
+ ]);
+ console.error("Failed to store microphone sidecar:", error);
+ return { success: false, error: String(error) };
+ }
+ },
+ );
+
+ ipcMain.handle("store-recorded-video", async (_, videoData: ArrayBuffer, fileName: unknown) => {
+ try {
+ const recordingsDir = await getRecordingsDir();
+ const videoPath = resolveRecordedVideoStoragePath(recordingsDir, fileName);
+ await fs.writeFile(videoPath, Buffer.from(videoData));
+ return await finalizeStoredVideo(videoPath);
+ } catch (error) {
+ console.error("Failed to store video:", error);
+ return {
+ success: false,
+ message: "Failed to store video",
+ error: String(error),
+ };
+ }
+ });
+
+ ipcMain.handle("get-recorded-video-path", async () => {
+ try {
+ const recordingsDir = await getRecordingsDir();
+ const entries = await fs.readdir(recordingsDir, { withFileTypes: true });
+ const candidates = await Promise.all(
+ entries
+ .filter(
+ (entry) =>
+ entry.isFile() && /^recording-\d+\.(webm|mov|mp4)$/i.test(entry.name),
+ )
+ .map(async (entry) => {
+ const fullPath = path.join(recordingsDir, entry.name);
+ const stat = await fs.stat(fullPath).catch(() => null);
+ return stat ? { path: fullPath, mtimeMs: stat.mtimeMs } : null;
+ }),
+ );
+ const sortedCandidates = candidates
+ .filter(
+ (candidate): candidate is { path: string; mtimeMs: number } =>
+ candidate !== null,
+ )
+ .sort((left, right) => right.mtimeMs - left.mtimeMs);
+
+ for (const candidate of sortedCandidates) {
+ try {
+ await validateRecordedVideo(candidate.path);
+ return { success: true, path: candidate.path };
+ } catch (error) {
+ console.warn(
+ "Skipping unusable recovered recording candidate:",
+ candidate.path,
+ error,
+ );
+ }
+ }
+
+ if (sortedCandidates.length === 0) {
+ return { success: false, message: "No recorded video found" };
+ }
+
+ return { success: false, message: "No usable recorded video found" };
+ } catch (error) {
+ console.error("Failed to get video path:", error);
+ return { success: false, message: "Failed to get video path", error: String(error) };
+ }
+ });
+
+ ipcMain.handle("set-recording-state", (_, recording: boolean) => {
+ if (recording) {
+ stopCursorCapture();
+ stopInteractionCapture();
+ startWindowBoundsCapture();
+ void startNativeCursorMonitor();
+ setIsCursorCaptureActive(true);
+ setActiveCursorSamples([]);
+ setPendingCursorSamples([]);
+ setCursorCaptureStartTimeMs(Date.now());
+ resetCursorCaptureClock();
+ setLinuxCursorScreenPoint(null);
+ setLastLeftClick(null);
+ sampleCursorPoint();
+ startCursorSampling();
+ void startInteractionCapture();
+ } else {
+ setIsCursorCaptureActive(false);
+ stopCursorCapture();
+ stopInteractionCapture();
+ stopWindowBoundsCapture();
+ stopNativeCursorMonitor();
+ showCursor();
+ setLinuxCursorScreenPoint(null);
+ resetCursorCaptureClock();
+ snapshotCursorTelemetryForPersistence();
+ setActiveCursorSamples([]);
+ }
+
+ const source = selectedSource || { name: "Screen" };
+ BrowserWindow.getAllWindows().forEach((window) => {
+ if (!window.isDestroyed()) {
+ window.webContents.send("recording-state-changed", {
+ recording,
+ sourceName: source.name,
+ });
+ }
+ });
+
+ if (onRecordingStateChange) {
+ onRecordingStateChange(recording, source.name);
+ }
+ });
+
+ ipcMain.handle("pause-cursor-capture", (_, pausedAtMs?: unknown) => {
+ pauseCursorCaptureAtBoundary(normalizeRendererTimestampMs(pausedAtMs));
+ return { success: true };
+ });
+
+ ipcMain.handle("resume-cursor-capture", (_, resumedAtMs?: unknown) => {
+ resumeCursorCapture(normalizeRendererTimestampMs(resumedAtMs));
+ sampleCursorPoint();
+ return { success: true };
+ });
+
+ ipcMain.handle("get-cursor-telemetry", async (_, videoPath?: string) => {
+ const targetVideoPath = normalizeVideoSourcePath(videoPath ?? currentVideoPath);
+ if (!targetVideoPath) {
+ return { success: true, samples: [] };
+ }
+
+ const telemetryPath = getTelemetryPathForVideo(targetVideoPath);
+ try {
+ const content = await fs.readFile(telemetryPath, "utf-8");
+ const parsed = parseJsonWithByteOrderMark(content);
+ const samples = normalizeCursorTelemetrySamples(parsed);
+
+ return { success: true, samples };
+ } catch (error) {
+ const nodeError = error as NodeJS.ErrnoException;
+ if (nodeError.code === "ENOENT") {
+ return { success: true, samples: [] };
+ }
+ console.error("Failed to load cursor telemetry:", error);
+ return {
+ success: false,
+ message: "Failed to load cursor telemetry",
+ error: String(error),
+ samples: [],
+ };
+ }
+ });
+
+ ipcMain.handle(
+ "set-cursor-telemetry",
+ async (_, videoPath: string | undefined, samples: CursorTelemetryPoint[]) => {
+ const targetVideoPath = normalizeVideoSourcePath(videoPath ?? currentVideoPath);
+ if (!targetVideoPath) {
+ return {
+ success: false,
+ samples: [],
+ message: "No video path available for cursor telemetry",
+ error: "Missing video path",
+ };
+ }
+
+ try {
+ const normalizedSamples = await writeCursorTelemetry(targetVideoPath, samples);
+ return { success: true, samples: normalizedSamples };
+ } catch (error) {
+ console.error("Failed to save cursor telemetry:", error);
+ return {
+ success: false,
+ samples: [],
+ message: "Failed to save cursor telemetry",
+ error: String(error),
+ };
+ }
+ },
+ );
+}
diff --git a/electron/ipc/register/settings.ts b/electron/ipc/register/settings.ts
new file mode 100644
index 000000000..93aee8783
--- /dev/null
+++ b/electron/ipc/register/settings.ts
@@ -0,0 +1,268 @@
+import fs from "node:fs/promises";
+import { app, ipcMain } from "electron";
+import { hasAppSetting, readAppSettingsStore, writeAppSettingsStore } from "../../appSettingsStore";
+import { hideCursor } from "../../cursorHider";
+import { closeCountdownWindow, createCountdownWindow, getCountdownWindow } from "../../windows";
+import { COUNTDOWN_SETTINGS_FILE, RECORDINGS_SETTINGS_FILE, SHORTCUTS_FILE } from "../constants";
+import {
+ createRecordingPreferencesStore,
+ type RecordingPreferencesPatch,
+} from "../settings/recordingPreferencesStore";
+import {
+ countdownCancelled,
+ countdownInProgress,
+ countdownRemaining,
+ countdownTimer,
+ setCountdownCancelled,
+ setCountdownInProgress,
+ setCountdownRemaining,
+ setCountdownTimer,
+} from "../state";
+import { parseJsonWithByteOrderMark } from "../utils";
+
+const BROWSER_MICROPHONE_PROFILE_ENV = "RECORDLY_BROWSER_MIC_PROFILE";
+const DEFAULT_BROWSER_MICROPHONE_PROFILE = "processed";
+const recordingPreferencesStore = createRecordingPreferencesStore(RECORDINGS_SETTINGS_FILE);
+const BROWSER_MICROPHONE_PROFILES = new Set([
+ "processed",
+ "no-agc",
+ "no-echo",
+ "no-noise-suppression",
+ "raw",
+]);
+
+function getBrowserMicrophoneProfileFromEnv() {
+ const requested = process.env[BROWSER_MICROPHONE_PROFILE_ENV]?.trim() || null;
+ const normalized = requested?.toLowerCase() ?? DEFAULT_BROWSER_MICROPHONE_PROFILE;
+ return {
+ browserMicrophoneProfile: BROWSER_MICROPHONE_PROFILES.has(normalized)
+ ? normalized
+ : DEFAULT_BROWSER_MICROPHONE_PROFILE,
+ requestedBrowserMicrophoneProfile: requested,
+ };
+}
+
+export function registerSettingsHandlers() {
+ ipcMain.handle("app:getVersion", () => {
+ return app.getVersion();
+ });
+
+ ipcMain.handle("get-platform", () => {
+ return process.platform;
+ });
+
+ ipcMain.on("app-settings:get", (event, key: unknown) => {
+ try {
+ if (typeof key !== "string" || key.length === 0) {
+ event.returnValue = { success: false, value: null };
+ return;
+ }
+
+ const store = readAppSettingsStore();
+ event.returnValue = {
+ success: true,
+ value: hasAppSetting(store, key) ? store[key] : null,
+ };
+ } catch (error) {
+ console.error("Failed to read app setting:", error);
+ event.returnValue = { success: false, value: null };
+ }
+ });
+
+ ipcMain.on("app-settings:set", (event, key: unknown, value: unknown) => {
+ try {
+ if (typeof key !== "string" || key.length === 0) {
+ event.returnValue = { success: false };
+ return;
+ }
+
+ const store = readAppSettingsStore();
+ store[key] = value;
+ writeAppSettingsStore(store);
+ event.returnValue = { success: true };
+ } catch (error) {
+ console.error("Failed to save app setting:", error);
+ event.returnValue = { success: false };
+ }
+ });
+
+ // ---------------------------------------------------------------------------
+ // Cursor hiding for the browser-capture fallback.
+ // The IPC promise resolves only after the cursor hide attempt completes.
+ // ---------------------------------------------------------------------------
+ ipcMain.handle("hide-cursor", () => {
+ if (process.platform !== "win32") {
+ return { success: true };
+ }
+
+ return { success: hideCursor() };
+ });
+
+ ipcMain.handle("get-shortcuts", async () => {
+ try {
+ const data = await fs.readFile(SHORTCUTS_FILE, "utf-8");
+ return parseJsonWithByteOrderMark(data);
+ } catch {
+ return null;
+ }
+ });
+
+ ipcMain.handle("save-shortcuts", async (_, shortcuts: unknown) => {
+ try {
+ await fs.writeFile(SHORTCUTS_FILE, JSON.stringify(shortcuts, null, 2), "utf-8");
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to save shortcuts:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ // ---------------------------------------------------------------------------
+ // Countdown timer before recording
+ // ---------------------------------------------------------------------------
+ ipcMain.handle("get-recording-preferences", async () => {
+ try {
+ const parsed = await recordingPreferencesStore.read();
+ return {
+ success: true,
+ microphoneEnabled: parsed.microphoneEnabled === true,
+ microphoneDeviceId:
+ typeof parsed.microphoneDeviceId === "string"
+ ? parsed.microphoneDeviceId
+ : undefined,
+ systemAudioEnabled: parsed.systemAudioEnabled === true,
+ webcamEnabled: parsed.webcamEnabled === true,
+ webcamDeviceId:
+ typeof parsed.webcamDeviceId === "string" ? parsed.webcamDeviceId : undefined,
+ };
+ } catch {
+ return {
+ success: true,
+ microphoneEnabled: false,
+ microphoneDeviceId: undefined,
+ systemAudioEnabled: false,
+ webcamEnabled: false,
+ webcamDeviceId: undefined,
+ };
+ }
+ });
+
+ ipcMain.handle("get-recording-audio-lab-config", () => {
+ return getBrowserMicrophoneProfileFromEnv();
+ });
+
+ ipcMain.handle("set-recording-preferences", async (_, prefs: RecordingPreferencesPatch) => {
+ try {
+ await recordingPreferencesStore.update(prefs);
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to save recording preferences:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("get-countdown-delay", async () => {
+ try {
+ const content = await fs.readFile(COUNTDOWN_SETTINGS_FILE, "utf-8");
+ const parsed = parseJsonWithByteOrderMark<{ delay?: number }>(content);
+ return { success: true, delay: parsed.delay ?? 3 };
+ } catch {
+ return { success: true, delay: 3 };
+ }
+ });
+
+ ipcMain.handle("set-countdown-delay", async (_, delay: number) => {
+ try {
+ await fs.writeFile(
+ COUNTDOWN_SETTINGS_FILE,
+ JSON.stringify({ delay }, null, 2),
+ "utf-8",
+ );
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to save countdown delay:", error);
+ return { success: false, error: String(error) };
+ }
+ });
+
+ ipcMain.handle("start-countdown", async (_, seconds: number) => {
+ if (countdownInProgress) {
+ return { success: false, error: "Countdown already in progress" };
+ }
+
+ setCountdownInProgress(true);
+ setCountdownCancelled(false);
+ setCountdownRemaining(seconds);
+
+ const countdownWin = createCountdownWindow();
+
+ if (countdownWin.webContents.isLoadingMainFrame()) {
+ await new Promise((resolve) => {
+ countdownWin.webContents.once("did-finish-load", () => {
+ resolve();
+ });
+ });
+ }
+
+ return new Promise<{ success: boolean; cancelled?: boolean }>((resolve) => {
+ let remaining = seconds;
+ setCountdownRemaining(remaining);
+
+ countdownWin.webContents.send("countdown-tick", remaining);
+
+ setCountdownTimer(
+ setInterval(() => {
+ if (countdownCancelled) {
+ if (countdownTimer) {
+ clearInterval(countdownTimer);
+ setCountdownTimer(null);
+ }
+ closeCountdownWindow();
+ setCountdownInProgress(false);
+ setCountdownRemaining(null);
+ resolve({ success: false, cancelled: true });
+ return;
+ }
+
+ remaining--;
+ setCountdownRemaining(remaining);
+
+ if (remaining <= 0) {
+ if (countdownTimer) {
+ clearInterval(countdownTimer);
+ setCountdownTimer(null);
+ }
+ closeCountdownWindow();
+ setCountdownInProgress(false);
+ setCountdownRemaining(null);
+ resolve({ success: true });
+ } else {
+ const win = getCountdownWindow();
+ if (win && !win.isDestroyed()) {
+ win.webContents.send("countdown-tick", remaining);
+ }
+ }
+ }, 1000),
+ );
+ });
+ });
+
+ ipcMain.handle("cancel-countdown", () => {
+ setCountdownCancelled(true);
+ setCountdownInProgress(false);
+ setCountdownRemaining(null);
+ if (countdownTimer) {
+ clearInterval(countdownTimer);
+ setCountdownTimer(null);
+ }
+ closeCountdownWindow();
+ return { success: true };
+ });
+
+ ipcMain.handle("get-active-countdown", () => {
+ return {
+ success: true,
+ seconds: countdownInProgress ? countdownRemaining : null,
+ };
+ });
+}
diff --git a/electron/ipc/register/sourceMapping.test.ts b/electron/ipc/register/sourceMapping.test.ts
new file mode 100644
index 000000000..84351a506
--- /dev/null
+++ b/electron/ipc/register/sourceMapping.test.ts
@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { getScreenSourceIdForDisplay, LINUX_PORTAL_SCREEN_SOURCE_ID } from "./sourceMapping";
+
+describe("getScreenSourceIdForDisplay", () => {
+ it("keeps the live Electron screen source when one is available", () => {
+ expect(
+ getScreenSourceIdForDisplay({
+ displayId: "42",
+ matchedSourceId: "screen:42:0",
+ platform: "linux",
+ }),
+ ).toBe("screen:42:0");
+ });
+
+ it("routes unmatched Linux Wayland screens through the portal sentinel", () => {
+ expect(
+ getScreenSourceIdForDisplay({
+ displayId: "42",
+ env: { XDG_SESSION_TYPE: "wayland", WAYLAND_DISPLAY: "wayland-0" },
+ matchedSourceId: null,
+ platform: "linux",
+ }),
+ ).toBe(LINUX_PORTAL_SCREEN_SOURCE_ID);
+ });
+
+ it("keeps unmatched Linux X11 screens on the explicit fallback id", () => {
+ expect(
+ getScreenSourceIdForDisplay({
+ displayId: "42",
+ env: { XDG_SESSION_TYPE: "x11", DISPLAY: ":0" },
+ matchedSourceId: null,
+ platform: "linux",
+ }),
+ ).toBe("screen:fallback:42");
+ });
+
+ it("keeps non-Linux unmatched screens on the explicit fallback id", () => {
+ expect(
+ getScreenSourceIdForDisplay({
+ displayId: "42",
+ matchedSourceId: undefined,
+ platform: "win32",
+ }),
+ ).toBe("screen:fallback:42");
+ });
+});
diff --git a/electron/ipc/register/sourceMapping.ts b/electron/ipc/register/sourceMapping.ts
new file mode 100644
index 000000000..8b13501a2
--- /dev/null
+++ b/electron/ipc/register/sourceMapping.ts
@@ -0,0 +1,35 @@
+export const LINUX_PORTAL_SCREEN_SOURCE_ID = "screen:linux-portal";
+
+export function isLikelyLinuxWaylandSession(env: NodeJS.ProcessEnv) {
+ const sessionType = env.XDG_SESSION_TYPE?.trim().toLowerCase();
+ if (sessionType === "wayland") {
+ return true;
+ }
+ if (sessionType === "x11") {
+ return false;
+ }
+
+ return Boolean(env.WAYLAND_DISPLAY);
+}
+
+export function getScreenSourceIdForDisplay({
+ displayId,
+ env = process.env,
+ matchedSourceId,
+ platform,
+}: {
+ displayId: string;
+ env?: NodeJS.ProcessEnv;
+ matchedSourceId?: string | null;
+ platform: NodeJS.Platform | string;
+}) {
+ if (matchedSourceId) {
+ return matchedSourceId;
+ }
+
+ if (platform === "linux" && isLikelyLinuxWaylandSession(env)) {
+ return LINUX_PORTAL_SCREEN_SOURCE_ID;
+ }
+
+ return `screen:fallback:${displayId}`;
+}
diff --git a/electron/ipc/register/sources.ts b/electron/ipc/register/sources.ts
new file mode 100644
index 000000000..a92e55808
--- /dev/null
+++ b/electron/ipc/register/sources.ts
@@ -0,0 +1,544 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { app, BrowserWindow, desktopCapturer, ipcMain } from "electron";
+import { ALLOW_RECORDLY_WINDOW_CAPTURE } from "../constants";
+import { selectedSource, setSelectedSource } from "../state";
+import type { SelectedSource } from "../types";
+import { getScreen, parseWindowId } from "../utils";
+import { getDisplayBoundsForSource, getDisplayWorkAreaForSource } from "../recording/ffmpeg";
+import { getScreenSourceIdForDisplay } from "./sourceMapping";
+import {
+ getNativeMacWindowSources,
+ resolveMacWindowBounds,
+ resolveWindowsWindowBounds,
+ resolveLinuxWindowBounds,
+ stopWindowBoundsCapture,
+} from "../cursor/bounds";
+import { reassertHudOverlayMousePassthrough } from "../../windows";
+
+const execFileAsync = promisify(execFile);
+const SOURCE_LIST_CACHE_TTL_MS = 1200;
+let sourceListCache: {
+ key: string;
+ expiresAt: number;
+ value: Array>;
+} | null = null;
+
+function normalizeDesktopSourceName(value: string) {
+ return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+function broadcastSelectedSourceChange() {
+ for (const window of BrowserWindow.getAllWindows()) {
+ if (!window.isDestroyed()) {
+ window.webContents.send("selected-source-changed", selectedSource);
+ }
+ }
+}
+
+export function registerSourceHandlers({
+ createEditorWindow,
+ createSourceSelectorWindow,
+ getSourceSelectorWindow,
+}: {
+ createEditorWindow: () => void;
+ createSourceSelectorWindow: () => BrowserWindow;
+ getSourceSelectorWindow: () => BrowserWindow | null;
+}) {
+ ipcMain.handle("get-sources", async (_, opts) => {
+ const cacheKey = JSON.stringify({
+ types: opts?.types,
+ thumbnailSize: opts?.thumbnailSize,
+ fetchWindowIcons: opts?.fetchWindowIcons,
+ });
+ if (
+ sourceListCache &&
+ sourceListCache.key === cacheKey &&
+ sourceListCache.expiresAt > Date.now()
+ ) {
+ return sourceListCache.value;
+ }
+
+ const includeScreens = Array.isArray(opts?.types) ? opts.types.includes("screen") : true;
+ const includeWindows = Array.isArray(opts?.types) ? opts.types.includes("window") : true;
+ const includeWindowIcons = Boolean(opts?.fetchWindowIcons);
+ const electronTypes = [
+ ...(includeScreens ? ["screen" as const] : []),
+ ...(includeWindows ? ["window" as const] : []),
+ ];
+ const electronSources =
+ electronTypes.length > 0
+ ? await desktopCapturer
+ .getSources({
+ ...opts,
+ types: electronTypes,
+ })
+ .catch((error) => {
+ console.warn(
+ "desktopCapturer.getSources failed (screen recording permission may be missing):",
+ error,
+ );
+ return [];
+ })
+ : [];
+ const ownWindowNames = new Set(
+ [
+ app.getName(),
+ "Recordly",
+ ...BrowserWindow.getAllWindows().flatMap((win) => {
+ const title = win.getTitle().trim();
+ return title ? [title] : [];
+ }),
+ ]
+ .map((name) => normalizeDesktopSourceName(name))
+ .filter(Boolean),
+ );
+ const ownAppName = normalizeDesktopSourceName(app.getName());
+
+ const displays = includeScreens
+ ? [...getScreen().getAllDisplays()].sort(
+ (left, right) =>
+ left.bounds.x - right.bounds.x ||
+ left.bounds.y - right.bounds.y ||
+ left.id - right.id,
+ )
+ : [];
+ const primaryDisplayId = includeScreens ? String(getScreen().getPrimaryDisplay().id) : "";
+ const electronScreenSourcesByDisplayId = new Map(
+ electronSources
+ .filter((source) => source.id.startsWith("screen:"))
+ .map((source) => [String(source.display_id ?? ""), source] as const),
+ );
+ // On Linux, desktopCapturer display_id values may not match screen.getAllDisplays() IDs.
+ // Keep an ordered list so we can fall back to position-based matching.
+ const electronScreenSourcesByIndex = electronSources.filter((source) =>
+ source.id.startsWith("screen:"),
+ );
+
+ const screenSources = displays.map((display, index) => {
+ const displayId = String(display.id);
+ const matchedSource =
+ electronScreenSourcesByDisplayId.get(displayId) ??
+ (electronScreenSourcesByIndex.length === displays.length
+ ? electronScreenSourcesByIndex[index]
+ : undefined);
+ const displayName =
+ displayId === primaryDisplayId
+ ? `Screen ${index + 1} (Primary)`
+ : `Screen ${index + 1}`;
+
+ return {
+ id: getScreenSourceIdForDisplay({
+ displayId,
+ env: process.env,
+ matchedSourceId: matchedSource?.id,
+ platform: process.platform,
+ }),
+ name: displayName,
+ originalName: matchedSource?.name ?? displayName,
+ display_id: displayId,
+ thumbnail: matchedSource?.thumbnail ? matchedSource.thumbnail.toDataURL() : null,
+ appIcon: null,
+ sourceType: "screen" as const,
+ };
+ });
+
+ if (process.platform !== "darwin" || !includeWindows) {
+ const windowSources = electronSources
+ .filter((source) => source.id.startsWith("window:"))
+ .filter((source) => {
+ const normalizedName = normalizeDesktopSourceName(source.name);
+ if (!normalizedName) {
+ return true;
+ }
+
+ if (ALLOW_RECORDLY_WINDOW_CAPTURE && normalizedName.includes("recordly")) {
+ return true;
+ }
+
+ for (const ownName of ownWindowNames) {
+ if (!ownName) continue;
+ if (normalizedName === ownName) {
+ return false;
+ }
+ }
+
+ return true;
+ })
+ .map((source) => ({
+ id: source.id,
+ name: source.name,
+ originalName: source.name,
+ display_id: source.display_id,
+ thumbnail: source.thumbnail ? source.thumbnail.toDataURL() : null,
+ appIcon:
+ includeWindowIcons && source.appIcon ? source.appIcon.toDataURL() : null,
+ sourceType: "window" as const,
+ }));
+ const result = [...screenSources, ...windowSources];
+ sourceListCache = {
+ key: cacheKey,
+ expiresAt: Date.now() + SOURCE_LIST_CACHE_TTL_MS,
+ value: result,
+ };
+ return result;
+ }
+
+ try {
+ const nativeWindowSources = await getNativeMacWindowSources();
+ const electronWindowSourceMap = new Map(
+ electronSources
+ .filter((source) => source.id.startsWith("window:"))
+ .map((source) => [source.id, source] as const),
+ );
+
+ const mergedWindowSources = nativeWindowSources
+ .filter((source) => {
+ const normalizedWindowName = normalizeDesktopSourceName(
+ source.windowTitle ?? source.name,
+ );
+ const normalizedAppName = normalizeDesktopSourceName(source.appName ?? "");
+
+ if (
+ !ALLOW_RECORDLY_WINDOW_CAPTURE &&
+ normalizedAppName &&
+ normalizedAppName === ownAppName
+ ) {
+ return false;
+ }
+
+ if (
+ ALLOW_RECORDLY_WINDOW_CAPTURE &&
+ (normalizedAppName === "recordly" ||
+ normalizedWindowName?.includes("recordly"))
+ ) {
+ return true;
+ }
+
+ if (!normalizedWindowName) {
+ return true;
+ }
+
+ for (const ownName of ownWindowNames) {
+ if (!ownName) continue;
+ if (normalizedWindowName === ownName) {
+ return false;
+ }
+ }
+
+ return true;
+ })
+ .map((source) => {
+ const electronWindowSource = electronWindowSourceMap.get(source.id);
+ return {
+ id: source.id,
+ name: source.name,
+ originalName: source.name,
+ display_id: source.display_id ?? electronWindowSource?.display_id ?? "",
+ thumbnail: electronWindowSource?.thumbnail
+ ? electronWindowSource.thumbnail.toDataURL()
+ : null,
+ appIcon: includeWindowIcons
+ ? (source.appIcon ??
+ (electronWindowSource?.appIcon
+ ? electronWindowSource.appIcon.toDataURL()
+ : null))
+ : null,
+ appName: source.appName,
+ windowTitle: source.windowTitle,
+ sourceType: "window" as const,
+ };
+ });
+
+ const result = [...screenSources, ...mergedWindowSources];
+ sourceListCache = {
+ key: cacheKey,
+ expiresAt: Date.now() + SOURCE_LIST_CACHE_TTL_MS,
+ value: result,
+ };
+ return result;
+ } catch (error) {
+ console.warn("Falling back to Electron window enumeration on macOS:", error);
+
+ const windowSources = electronSources
+ .filter((source) => source.id.startsWith("window:"))
+ .filter((source) => {
+ const normalizedName = normalizeDesktopSourceName(source.name);
+ if (!normalizedName) {
+ return true;
+ }
+
+ if (ALLOW_RECORDLY_WINDOW_CAPTURE && normalizedName.includes("recordly")) {
+ return true;
+ }
+
+ for (const ownName of ownWindowNames) {
+ if (!ownName) continue;
+ if (
+ normalizedName === ownName ||
+ normalizedName.includes(ownName) ||
+ ownName.includes(normalizedName)
+ ) {
+ return false;
+ }
+ }
+
+ return true;
+ })
+ .map((source) => ({
+ id: source.id,
+ name: source.name,
+ originalName: source.name,
+ display_id: source.display_id,
+ thumbnail: source.thumbnail ? source.thumbnail.toDataURL() : null,
+ appIcon:
+ includeWindowIcons && source.appIcon ? source.appIcon.toDataURL() : null,
+ sourceType: "window" as const,
+ }));
+
+ const result = [...screenSources, ...windowSources];
+ sourceListCache = {
+ key: cacheKey,
+ expiresAt: Date.now() + SOURCE_LIST_CACHE_TTL_MS,
+ value: result,
+ };
+ return result;
+ }
+ });
+
+ ipcMain.handle("select-source", (_, source: SelectedSource) => {
+ setSelectedSource(source);
+ broadcastSelectedSourceChange();
+ stopWindowBoundsCapture();
+ const sourceSelectorWin = getSourceSelectorWindow();
+ if (sourceSelectorWin) {
+ sourceSelectorWin.close();
+ }
+ return selectedSource;
+ });
+
+ ipcMain.handle("show-source-highlight", async (_, source: SelectedSource) => {
+ try {
+ const isWindow = source.id?.startsWith("window:");
+ const windowId = isWindow ? parseWindowId(source.id) : null;
+
+ // ── 1. Bring window to front ──
+ if (isWindow && process.platform === "darwin") {
+ const rawAppName = source.appName || source.name?.split(" — ")[0]?.trim();
+ const appName =
+ rawAppName && /^[\w .&()+'-]{1,64}$/.test(rawAppName) ? rawAppName : null;
+ if (appName) {
+ try {
+ await execFileAsync(
+ "osascript",
+ [
+ "-e",
+ "on run argv",
+ "-e",
+ "tell application (item 1 of argv) to activate",
+ "-e",
+ "end run",
+ "--",
+ appName,
+ ],
+ { timeout: 2000 },
+ );
+ await new Promise((resolve) => setTimeout(resolve, 350));
+ } catch {
+ /* ignore */
+ }
+ }
+ } else if (windowId && process.platform === "linux") {
+ try {
+ await execFileAsync("wmctrl", ["-i", "-a", `0x${windowId.toString(16)}`], {
+ timeout: 1500,
+ });
+ } catch {
+ try {
+ await execFileAsync("xdotool", ["windowactivate", String(windowId)], {
+ timeout: 1500,
+ });
+ } catch {
+ /* not available */
+ }
+ }
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ }
+
+ // ── 2. Resolve bounds ──
+ let bounds: { x: number; y: number; width: number; height: number } | null = null;
+
+ if (source.id?.startsWith("screen:")) {
+ bounds =
+ process.platform === "darwin"
+ ? getDisplayWorkAreaForSource(source)
+ : getDisplayBoundsForSource(source);
+ } else if (isWindow) {
+ if (process.platform === "darwin") {
+ bounds = await resolveMacWindowBounds(source);
+ } else if (process.platform === "win32") {
+ bounds = await resolveWindowsWindowBounds(source);
+ } else if (process.platform === "linux") {
+ bounds = await resolveLinuxWindowBounds(source);
+ }
+ }
+
+ if (!bounds || bounds.width <= 0 || bounds.height <= 0) {
+ bounds = getDisplayBoundsForSource(source);
+ }
+
+ if (!bounds || bounds.width <= 0 || bounds.height <= 0) {
+ const primaryBounds = getScreen().getPrimaryDisplay().bounds;
+ if (primaryBounds.width <= 0 || primaryBounds.height <= 0) {
+ return { success: false };
+ }
+ bounds = primaryBounds;
+ }
+
+ const resolvedBounds = bounds;
+
+ // ── 3. Show traveling wave highlight ──
+ // On macOS, screen highlights use workArea and no outward padding —
+ // macOS clamps window positions below the menu bar so outward
+ // padding only works on the left/top while right/bottom run off-screen.
+ const isScreen = source.id?.startsWith("screen:");
+ const isMacScreen = isScreen && process.platform === "darwin";
+ const pad = isMacScreen ? 0 : 6;
+ const highlightWin = new BrowserWindow({
+ x: resolvedBounds.x - pad,
+ y: resolvedBounds.y - pad,
+ width: resolvedBounds.width + pad * 2,
+ height: resolvedBounds.height + pad * 2,
+ frame: false,
+ transparent: true,
+ alwaysOnTop: true,
+ skipTaskbar: true,
+ hasShadow: false,
+ resizable: false,
+ focusable: false,
+ webPreferences: { nodeIntegration: false, contextIsolation: true },
+ });
+
+ highlightWin.setIgnoreMouseEvents(true);
+
+ const borderRadius = isMacScreen ? 0 : 10;
+ const glowInset = isMacScreen ? 0 : -4;
+ const glowRadius = isMacScreen ? 0 : 14;
+ const glowPad = isMacScreen ? 3 : 6;
+
+ const html = `
+
+
+
+`;
+
+ try {
+ await highlightWin.loadURL(
+ `data:text/html;charset=utf-8,${encodeURIComponent(html)}`,
+ );
+ } catch (loadError) {
+ if (!highlightWin.isDestroyed()) {
+ highlightWin.close();
+ }
+ throw loadError;
+ }
+
+ // The highlight window appearing (even with focusable:false) can corrupt
+ // the WS_EX_TRANSPARENT flag on the HUD on Windows 11+, breaking hover
+ // detection until the user moves their mouse over the bar again.
+ // Re-assert passthrough immediately so click-through is restored at once.
+ reassertHudOverlayMousePassthrough();
+
+ const highlightCloseTimer = setTimeout(() => {
+ if (!highlightWin.isDestroyed()) highlightWin.close();
+ }, 1700);
+
+ highlightWin.on("closed", () => {
+ clearTimeout(highlightCloseTimer);
+ // Re-assert once more when the window is actually destroyed so the
+ // native flag is clean regardless of timing.
+ reassertHudOverlayMousePassthrough();
+ });
+
+ return { success: true };
+ } catch (error) {
+ console.error("Failed to show source highlight:", error);
+ return { success: false };
+ }
+ });
+
+ ipcMain.handle("get-selected-source", () => {
+ return selectedSource;
+ });
+
+ ipcMain.handle("open-source-selector", () => {
+ const sourceSelectorWin = getSourceSelectorWindow();
+ if (sourceSelectorWin) {
+ sourceSelectorWin.focus();
+ return;
+ }
+ createSourceSelectorWindow();
+ });
+ ipcMain.handle("switch-to-editor", () => {
+ console.log("[switch-to-editor] Opening editor window");
+ const sourceSelectorWin = getSourceSelectorWindow();
+ if (sourceSelectorWin && !sourceSelectorWin.isDestroyed()) {
+ sourceSelectorWin.close();
+ }
+ createEditorWindow();
+ });
+}
diff --git a/electron/ipc/settings/recordingPreferencesStore.test.ts b/electron/ipc/settings/recordingPreferencesStore.test.ts
new file mode 100644
index 000000000..9caaeaae8
--- /dev/null
+++ b/electron/ipc/settings/recordingPreferencesStore.test.ts
@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createRecordingPreferencesStore } from "./recordingPreferencesStore";
+
+vi.mock("electron", () => ({
+ app: {
+ getPath: () => "",
+ },
+}));
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+ await Promise.all(
+ temporaryDirectories.splice(0).map((directory) =>
+ fs.rm(directory, {
+ recursive: true,
+ force: true,
+ }),
+ ),
+ );
+});
+
+describe("recording preferences store", () => {
+ it("preserves concurrent microphone and webcam preference updates", async () => {
+ const directory = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-preferences-"));
+ temporaryDirectories.push(directory);
+ const store = createRecordingPreferencesStore(path.join(directory, "recording.json"));
+
+ await Promise.all([
+ store.update({ microphoneEnabled: true }),
+ store.update({ microphoneDeviceId: "preferred-mic" }),
+ store.update({ webcamEnabled: true }),
+ store.update({ webcamDeviceId: "preferred-camera" }),
+ ]);
+
+ await expect(store.read()).resolves.toEqual({
+ microphoneEnabled: true,
+ microphoneDeviceId: "preferred-mic",
+ webcamEnabled: true,
+ webcamDeviceId: "preferred-camera",
+ });
+ });
+});
diff --git a/electron/ipc/settings/recordingPreferencesStore.ts b/electron/ipc/settings/recordingPreferencesStore.ts
new file mode 100644
index 000000000..26eced169
--- /dev/null
+++ b/electron/ipc/settings/recordingPreferencesStore.ts
@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import { parseJsonWithByteOrderMark } from "../utils";
+
+export interface RecordingPreferencesPatch {
+ microphoneEnabled?: boolean;
+ microphoneDeviceId?: string;
+ systemAudioEnabled?: boolean;
+ webcamEnabled?: boolean;
+ webcamDeviceId?: string;
+}
+
+export function createRecordingPreferencesStore(filePath: string) {
+ let operationQueue: Promise = Promise.resolve();
+
+ const readFile = async (): Promise> => {
+ try {
+ const content = await fs.readFile(filePath, "utf-8");
+ const parsed = parseJsonWithByteOrderMark(content);
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+ ? (parsed as Record)
+ : {};
+ } catch {
+ return {};
+ }
+ };
+
+ return {
+ async read(): Promise> {
+ await operationQueue;
+ return readFile();
+ },
+ async update(patch: RecordingPreferencesPatch): Promise {
+ const operation = operationQueue.then(async () => {
+ const existing = await readFile();
+ await fs.writeFile(
+ filePath,
+ JSON.stringify({ ...existing, ...patch }, null, 2),
+ "utf-8",
+ );
+ });
+ operationQueue = operation.catch(() => undefined);
+ await operation;
+ },
+ };
+}
diff --git a/electron/ipc/state.ts b/electron/ipc/state.ts
new file mode 100644
index 000000000..a0a41744e
--- /dev/null
+++ b/electron/ipc/state.ts
@@ -0,0 +1,293 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import type {
+ CursorInteractionType,
+ CursorTelemetryPoint,
+ CursorVisualType,
+ NativeCaptureDiagnostics,
+ RecordingSessionData,
+ SelectedSource,
+ SystemCursorAsset,
+ WindowBounds,
+} from "./types";
+
+// ── Source selection ──────────────────────────────────────────────────────────
+export let selectedSource: SelectedSource | null = null;
+
+// ── Project / video state ─────────────────────────────────────────────────────
+export let currentProjectPath: string | null = null;
+export let currentVideoPath: string | null = null;
+export let currentRecordingSession: RecordingSessionData | null = null;
+
+// ── Security: approved read paths ─────────────────────────────────────────────
+export const approvedLocalReadPaths = new Set();
+
+// ── Native macOS capture ──────────────────────────────────────────────────────
+export let nativeScreenRecordingActive = false;
+export let nativeCaptureProcess: ChildProcessWithoutNullStreams | null = null;
+export let nativeCaptureOutputBuffer = "";
+export let nativeCaptureTargetPath: string | null = null;
+export let nativeCaptureStopRequested = false;
+export let nativeCaptureSystemAudioPath: string | null = null;
+export let nativeCaptureMicrophonePath: string | null = null;
+export let nativeCapturePaused = false;
+
+// ── Native cursor monitor ─────────────────────────────────────────────────────
+export let nativeCursorMonitorProcess: ChildProcessWithoutNullStreams | null = null;
+export let nativeCursorMonitorOutputBuffer = "";
+
+// ── Windows native capture ────────────────────────────────────────────────────
+export let windowsCaptureProcess: ChildProcessWithoutNullStreams | null = null;
+export let windowsCaptureOutputBuffer = "";
+export let windowsCaptureTargetPath: string | null = null;
+export let windowsNativeCaptureActive = false;
+export let windowsCaptureStopRequested = false;
+export let windowsCapturePaused = false;
+export let windowsSystemAudioPath: string | null = null;
+export let windowsMicAudioPath: string | null = null;
+export let windowsOrphanedMicAudioPath: string | null = null;
+export let windowsPendingVideoPath: string | null = null;
+
+// ── Diagnostics ───────────────────────────────────────────────────────────────
+export let lastNativeCaptureDiagnostics: NativeCaptureDiagnostics | null = null;
+
+// ── FFmpeg capture ────────────────────────────────────────────────────────────
+export let ffmpegScreenRecordingActive = false;
+export let ffmpegCaptureProcess: ChildProcessWithoutNullStreams | null = null;
+export let ffmpegCaptureOutputBuffer = "";
+export let ffmpegCaptureTargetPath: string | null = null;
+
+// ── Recordings directory ──────────────────────────────────────────────────────
+export let customRecordingsDir: string | null = null;
+export let recordingsDirLoaded = false;
+
+// ── System cursor assets cache ────────────────────────────────────────────────
+export let cachedSystemCursorAssets: Record | null = null;
+export let cachedSystemCursorAssetsSourceMtimeMs: number | null = null;
+
+// ── Countdown ─────────────────────────────────────────────────────────────────
+export let countdownTimer: ReturnType | null = null;
+export let countdownCancelled = false;
+export let countdownInProgress = false;
+export let countdownRemaining: number | null = null;
+
+// ── Cursor visual type ────────────────────────────────────────────────────────
+export let currentCursorVisualType: CursorVisualType | undefined = undefined;
+
+// ── Cursor telemetry ──────────────────────────────────────────────────────────
+export let cursorCaptureInterval: NodeJS.Timeout | null = null;
+export let cursorCaptureStartTimeMs = 0;
+export let cursorCaptureAccumulatedPausedMs = 0;
+export let cursorCapturePauseStartedAtMs: number | null = null;
+export let activeCursorSamples: CursorTelemetryPoint[] = [];
+export let pendingCursorSamples: CursorTelemetryPoint[] = [];
+export let isCursorCaptureActive = false;
+export let interactionCaptureCleanup: (() => void) | null = null;
+export let hasLoggedInteractionHookFailure = false;
+export let lastLeftClick: { timeMs: number; cx: number; cy: number } | null = null;
+export let linuxCursorScreenPoint: { x: number; y: number; updatedAt: number } | null = null;
+export let selectedWindowBounds: WindowBounds | null = null;
+export let windowBoundsCaptureInterval: NodeJS.Timeout | null = null;
+
+// ── Native macOS window source cache ─────────────────────────────────────────
+export let cachedNativeMacWindowSources: import("./types").NativeMacWindowSource[] | null = null;
+export let cachedNativeMacWindowSourcesAtMs = 0;
+
+// ── Native video export ───────────────────────────────────────────────────────
+export let cachedNativeVideoEncoder: {
+ ffmpegPath: string;
+ encodingMode: string;
+ encoderName: string;
+} | null = null;
+
+// ── Native helper migration ───────────────────────────────────────────────────
+export let nativeHelperMigrationPromise: Promise | null = null;
+
+// ── Cursor interaction capture types ─────────────────────────────────────────
+export type { CursorInteractionType, CursorTelemetryPoint };
+
+// ── Setters (for modules that need to reassign exported lets) ─────────────────
+// TypeScript exported `let` can be reassigned by the owning module but importers
+// cannot assign to them directly. Provide simple setters for cross-module writes.
+
+export function setSelectedSource(v: SelectedSource | null) {
+ selectedSource = v;
+}
+export function setCurrentProjectPath(v: string | null) {
+ currentProjectPath = v;
+}
+export function setCurrentVideoPath(v: string | null) {
+ currentVideoPath = v;
+}
+export function setCurrentRecordingSession(v: RecordingSessionData | null) {
+ currentRecordingSession = v;
+}
+
+export function setNativeScreenRecordingActive(v: boolean) {
+ nativeScreenRecordingActive = v;
+}
+export function setNativeCaptureProcess(v: ChildProcessWithoutNullStreams | null) {
+ nativeCaptureProcess = v;
+}
+export function setNativeCaptureOutputBuffer(v: string) {
+ nativeCaptureOutputBuffer = v;
+}
+export function setNativeCaptureTargetPath(v: string | null) {
+ nativeCaptureTargetPath = v;
+}
+export function setNativeCaptureStopRequested(v: boolean) {
+ nativeCaptureStopRequested = v;
+}
+export function setNativeCaptureSystemAudioPath(v: string | null) {
+ nativeCaptureSystemAudioPath = v;
+}
+export function setNativeCaptureMicrophonePath(v: string | null) {
+ nativeCaptureMicrophonePath = v;
+}
+export function setNativeCapturePaused(v: boolean) {
+ nativeCapturePaused = v;
+}
+
+export function setNativeCursorMonitorProcess(v: ChildProcessWithoutNullStreams | null) {
+ nativeCursorMonitorProcess = v;
+}
+export function setNativeCursorMonitorOutputBuffer(v: string) {
+ nativeCursorMonitorOutputBuffer = v;
+}
+
+export function setWindowsCaptureProcess(v: ChildProcessWithoutNullStreams | null) {
+ windowsCaptureProcess = v;
+}
+export function setWindowsCaptureOutputBuffer(v: string) {
+ windowsCaptureOutputBuffer = v;
+}
+export function setWindowsCaptureTargetPath(v: string | null) {
+ windowsCaptureTargetPath = v;
+}
+export function setWindowsNativeCaptureActive(v: boolean) {
+ windowsNativeCaptureActive = v;
+}
+export function setWindowsCaptureStopRequested(v: boolean) {
+ windowsCaptureStopRequested = v;
+}
+export function setWindowsCapturePaused(v: boolean) {
+ windowsCapturePaused = v;
+}
+export function setWindowsSystemAudioPath(v: string | null) {
+ windowsSystemAudioPath = v;
+}
+export function setWindowsMicAudioPath(v: string | null) {
+ windowsMicAudioPath = v;
+}
+export function setWindowsOrphanedMicAudioPath(v: string | null) {
+ windowsOrphanedMicAudioPath = v;
+}
+export function setWindowsPendingVideoPath(v: string | null) {
+ windowsPendingVideoPath = v;
+}
+
+export function setLastNativeCaptureDiagnostics(v: NativeCaptureDiagnostics | null) {
+ lastNativeCaptureDiagnostics = v;
+}
+
+export function setFfmpegScreenRecordingActive(v: boolean) {
+ ffmpegScreenRecordingActive = v;
+}
+export function setFfmpegCaptureProcess(v: ChildProcessWithoutNullStreams | null) {
+ ffmpegCaptureProcess = v;
+}
+export function setFfmpegCaptureOutputBuffer(v: string) {
+ ffmpegCaptureOutputBuffer = v;
+}
+export function setFfmpegCaptureTargetPath(v: string | null) {
+ ffmpegCaptureTargetPath = v;
+}
+
+export function setCustomRecordingsDir(v: string | null) {
+ customRecordingsDir = v;
+}
+export function setRecordingsDirLoaded(v: boolean) {
+ recordingsDirLoaded = v;
+}
+
+export function setCachedSystemCursorAssets(v: Record | null) {
+ cachedSystemCursorAssets = v;
+}
+export function setCachedSystemCursorAssetsSourceMtimeMs(v: number | null) {
+ cachedSystemCursorAssetsSourceMtimeMs = v;
+}
+
+export function setCountdownTimer(v: ReturnType | null) {
+ countdownTimer = v;
+}
+export function setCountdownCancelled(v: boolean) {
+ countdownCancelled = v;
+}
+export function setCountdownInProgress(v: boolean) {
+ countdownInProgress = v;
+}
+export function setCountdownRemaining(v: number | null) {
+ countdownRemaining = v;
+}
+
+export function setCurrentCursorVisualType(v: CursorVisualType | undefined) {
+ currentCursorVisualType = v;
+}
+
+export function setCursorCaptureInterval(v: NodeJS.Timeout | null) {
+ cursorCaptureInterval = v;
+}
+export function setCursorCaptureStartTimeMs(v: number) {
+ cursorCaptureStartTimeMs = v;
+}
+export function setCursorCaptureAccumulatedPausedMs(v: number) {
+ cursorCaptureAccumulatedPausedMs = v;
+}
+export function setCursorCapturePauseStartedAtMs(v: number | null) {
+ cursorCapturePauseStartedAtMs = v;
+}
+export function setActiveCursorSamples(v: CursorTelemetryPoint[]) {
+ activeCursorSamples = v;
+}
+export function setPendingCursorSamples(v: CursorTelemetryPoint[]) {
+ pendingCursorSamples = v;
+}
+export function setIsCursorCaptureActive(v: boolean) {
+ isCursorCaptureActive = v;
+}
+export function setInteractionCaptureCleanup(v: (() => void) | null) {
+ interactionCaptureCleanup = v;
+}
+export function setHasLoggedInteractionHookFailure(v: boolean) {
+ hasLoggedInteractionHookFailure = v;
+}
+export function setLastLeftClick(v: { timeMs: number; cx: number; cy: number } | null) {
+ lastLeftClick = v;
+}
+export function setLinuxCursorScreenPoint(v: { x: number; y: number; updatedAt: number } | null) {
+ linuxCursorScreenPoint = v;
+}
+export function setSelectedWindowBounds(v: WindowBounds | null) {
+ selectedWindowBounds = v;
+}
+export function setWindowBoundsCaptureInterval(v: NodeJS.Timeout | null) {
+ windowBoundsCaptureInterval = v;
+}
+
+export function setCachedNativeMacWindowSources(
+ v: import("./types").NativeMacWindowSource[] | null,
+) {
+ cachedNativeMacWindowSources = v;
+}
+export function setCachedNativeMacWindowSourcesAtMs(v: number) {
+ cachedNativeMacWindowSourcesAtMs = v;
+}
+
+export function setCachedNativeVideoEncoder(
+ v: { ffmpegPath: string; encodingMode: string; encoderName: string } | null,
+) {
+ cachedNativeVideoEncoder = v;
+}
+
+export function setNativeHelperMigrationPromise(v: Promise | null) {
+ nativeHelperMigrationPromise = v;
+}
diff --git a/electron/ipc/types.ts b/electron/ipc/types.ts
new file mode 100644
index 000000000..58f5425bd
--- /dev/null
+++ b/electron/ipc/types.ts
@@ -0,0 +1,203 @@
+export type SelectedSource = {
+ id?: string;
+ name: string;
+ display_id?: string;
+ sourceType?: "screen" | "window";
+ appName?: string;
+ windowTitle?: string;
+ [key: string]: unknown;
+};
+
+export type NativeMacRecordingOptions = {
+ capturesSystemAudio?: boolean;
+ capturesMicrophone?: boolean;
+ microphoneDeviceId?: string;
+ microphoneLabel?: string;
+};
+
+export type WindowBounds = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+};
+
+export type NativeCaptureDiagnostics = {
+ backend: "windows-wgc" | "mac-screencapturekit" | "browser-store" | "ffmpeg";
+ phase: "availability" | "start" | "stop" | "mux";
+ timestamp: string;
+ sourceId?: string | null;
+ sourceType?: SelectedSource["sourceType"] | "unknown";
+ displayId?: number | null;
+ displayBounds?: WindowBounds | null;
+ windowHandle?: number | null;
+ helperPath?: string | null;
+ outputPath?: string | null;
+ systemAudioPath?: string | null;
+ microphonePath?: string | null;
+ osRelease?: string;
+ supported?: boolean;
+ helperExists?: boolean;
+ fileSizeBytes?: number | null;
+ processOutput?: string;
+ error?: string;
+};
+
+export type RecordingSessionData = {
+ videoPath: string;
+ webcamPath?: string | null;
+ timeOffsetMs?: number;
+ hideOverlayCursorByDefault?: boolean;
+};
+
+export type PauseSegment = {
+ startMs: number;
+ endMs: number;
+};
+
+export type RecordingSessionManifest = {
+ version: 1 | 2;
+ videoFileName: string;
+ webcamFileName?: string | null;
+ timeOffsetMs?: number;
+};
+
+export type ProjectLibraryEntry = {
+ path: string;
+ name: string;
+ updatedAt: number;
+ thumbnailPath: string | null;
+ isCurrent: boolean;
+ isInProjectsDirectory: boolean;
+};
+
+export type SystemCursorAsset = {
+ dataUrl: string;
+ hotspotX: number;
+ hotspotY: number;
+ width: number;
+ height: number;
+};
+
+export type CursorVisualType =
+ | "arrow"
+ | "text"
+ | "pointer"
+ | "crosshair"
+ | "open-hand"
+ | "closed-hand"
+ | "resize-ew"
+ | "resize-ns"
+ | "not-allowed";
+
+export type CursorInteractionType =
+ | "move"
+ | "click"
+ | "double-click"
+ | "right-click"
+ | "middle-click"
+ | "mouseup";
+
+export interface CursorTelemetryPoint {
+ timeMs: number;
+ cx: number;
+ cy: number;
+ interactionType?: CursorInteractionType;
+ cursorType?: CursorVisualType;
+}
+
+export type NativeMacWindowSource = {
+ id: string;
+ name: string;
+ display_id?: string;
+ appName?: string;
+ windowTitle?: string;
+ bundleId?: string;
+ appIcon?: string | null;
+ x?: number;
+ y?: number;
+ width?: number;
+ height?: number;
+};
+
+export type HookEventName = "mousedown" | "mouseup" | "mousemove";
+
+export type HookMouseEvent = {
+ button?: number;
+ mouseButton?: number;
+ x?: number;
+ y?: number;
+ screenX?: number;
+ screenY?: number;
+ data?: {
+ button?: number;
+ mouseButton?: number;
+ x?: number;
+ y?: number;
+ screenX?: number;
+ screenY?: number;
+ };
+};
+
+export type HookEventListener = (event: HookMouseEvent) => void;
+
+export type UiohookLike = {
+ on: (eventName: HookEventName, listener: HookEventListener) => void;
+ off?: (eventName: HookEventName, listener: HookEventListener) => void;
+ removeListener?: (eventName: HookEventName, listener: HookEventListener) => void;
+ start: () => void;
+ stop?: () => void;
+};
+
+export type UiohookModuleNamespace = {
+ uIOhook?: UiohookLike;
+ uiohook?: UiohookLike;
+ Uiohook?: UiohookLike;
+ default?: UiohookLike | UiohookModuleNamespace;
+};
+
+export type AudioSyncAdjustment = {
+ mode: "none" | "tempo" | "delay" | "pad";
+ delayMs: number;
+ tempoRatio: number;
+ durationDeltaMs: number;
+};
+
+export type CompanionAudioCandidate = {
+ platform: "mac" | "win";
+ systemPath: string;
+ micPath: string;
+ usablePaths: string[];
+};
+
+export type CaptionWordPayload = {
+ text: string;
+ startMs: number;
+ endMs: number;
+ leadingSpace?: boolean;
+};
+
+export type CaptionCuePayload = {
+ id: string;
+ startMs: number;
+ endMs: number;
+ text: string;
+ words?: CaptionWordPayload[];
+};
+
+export type WhisperJsonToken = {
+ text?: unknown;
+ offsets?: {
+ from?: unknown;
+ to?: unknown;
+ };
+};
+
+export type WhisperJsonSegment = {
+ text?: unknown;
+ offsets?: {
+ from?: unknown;
+ to?: unknown;
+ };
+ tokens?: unknown;
+};
diff --git a/electron/ipc/utils.ts b/electron/ipc/utils.ts
new file mode 100644
index 000000000..23960f209
--- /dev/null
+++ b/electron/ipc/utils.ts
@@ -0,0 +1,131 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { app } from "electron";
+import { RECORDINGS_DIR } from "../appPaths";
+import { AUTO_RECORDING_PREFIX, RECORDINGS_SETTINGS_FILE } from "./constants";
+import {
+ approvedLocalReadPaths,
+ customRecordingsDir,
+ recordingsDirLoaded,
+ setCustomRecordingsDir,
+ setRecordingsDirLoaded,
+} from "./state";
+
+const nodeRequire = createRequire(import.meta.url);
+
+export function getScreen() {
+ if (!app.isReady()) {
+ throw new Error(
+ "getScreen() called before app is ready. Ensure all screen access happens after app.whenReady().",
+ );
+ }
+ return nodeRequire("electron").screen as typeof import("electron").screen;
+}
+
+export function normalizePath(filePath: string) {
+ return path.resolve(filePath);
+}
+
+export function normalizeVideoSourcePath(videoPath?: string | null): string | null {
+ if (typeof videoPath !== "string") {
+ return null;
+ }
+
+ const trimmed = videoPath.trim();
+ if (!trimmed) {
+ return null;
+ }
+
+ if (/^file:\/\//i.test(trimmed)) {
+ try {
+ return fileURLToPath(trimmed);
+ } catch {
+ // Fall through and keep best-effort string path below.
+ }
+ }
+
+ return trimmed;
+}
+
+export function stripJsonByteOrderMark(content: string) {
+ return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+}
+
+export function parseJsonWithByteOrderMark(content: string): T {
+ return JSON.parse(stripJsonByteOrderMark(content)) as T;
+}
+
+export function parseWindowId(sourceId?: string) {
+ if (!sourceId) return null;
+ const match = sourceId.match(/^window:(\d+)/);
+ return match ? Number.parseInt(match[1], 10) : null;
+}
+
+export function getTelemetryPathForVideo(videoPath: string) {
+ return `${videoPath}.cursor.json`;
+}
+
+export function isAutoRecordingPath(filePath: string) {
+ return path.basename(filePath).startsWith(AUTO_RECORDING_PREFIX);
+}
+
+export async function moveFileWithOverwrite(sourcePath: string, destinationPath: string) {
+ await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+ await fs.rm(destinationPath, { force: true });
+
+ try {
+ await fs.rename(sourcePath, destinationPath);
+ } catch (error) {
+ const nodeError = error as NodeJS.ErrnoException;
+ if (nodeError.code !== "EXDEV") {
+ throw error;
+ }
+
+ await fs.copyFile(sourcePath, destinationPath);
+ await fs.unlink(sourcePath);
+ }
+}
+
+async function loadRecordingsDirectorySetting() {
+ if (recordingsDirLoaded) {
+ return;
+ }
+
+ setRecordingsDirLoaded(true);
+
+ try {
+ const content = await fs.readFile(RECORDINGS_SETTINGS_FILE, "utf-8");
+ const parsed = parseJsonWithByteOrderMark<{ recordingsDir?: unknown }>(content);
+ if (typeof parsed.recordingsDir === "string" && parsed.recordingsDir.trim()) {
+ setCustomRecordingsDir(path.resolve(parsed.recordingsDir));
+ }
+ } catch {
+ setCustomRecordingsDir(null);
+ }
+}
+
+export async function getRecordingsDir() {
+ await loadRecordingsDirectorySetting();
+ const targetDir = customRecordingsDir ?? RECORDINGS_DIR;
+ await fs.mkdir(targetDir, { recursive: true });
+ return targetDir;
+}
+
+export function getMacPrivacySettingsUrl(pane: "screen" | "accessibility" | "microphone"): string {
+ if (pane === "screen")
+ return "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture";
+ if (pane === "microphone")
+ return "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone";
+ return "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility";
+}
+
+export function approveUserPath(filePath: string | null | undefined): void {
+ if (!filePath) return;
+ try {
+ approvedLocalReadPaths.add(path.resolve(filePath));
+ } catch {
+ // Ignore invalid paths; later reads will surface the underlying error.
+ }
+}
diff --git a/electron/ipc/windowsCaptureSelection.test.ts b/electron/ipc/windowsCaptureSelection.test.ts
new file mode 100644
index 000000000..17039d4df
--- /dev/null
+++ b/electron/ipc/windowsCaptureSelection.test.ts
@@ -0,0 +1,128 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ resolveWindowsCaptureDisplay,
+ resolveWindowsCaptureTarget,
+} from "./windowsCaptureSelection";
+
+describe("resolveWindowsCaptureDisplay", () => {
+ const primaryDisplay = {
+ id: 101,
+ bounds: {
+ x: 0,
+ y: 0,
+ width: 1920,
+ height: 1080,
+ },
+ };
+
+ const secondaryDisplay = {
+ id: 202,
+ bounds: {
+ x: 1920,
+ y: -40,
+ width: 2560,
+ height: 1440,
+ },
+ };
+
+ it("uses the requested secondary display bounds for WGC fallback metadata", () => {
+ const resolved = resolveWindowsCaptureDisplay(
+ { display_id: String(secondaryDisplay.id) },
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ displayId: secondaryDisplay.id,
+ bounds: secondaryDisplay.bounds,
+ });
+ });
+
+ it("falls back to the primary display when the source has no display id", () => {
+ const resolved = resolveWindowsCaptureDisplay(
+ undefined,
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ displayId: primaryDisplay.id,
+ bounds: primaryDisplay.bounds,
+ });
+ });
+
+ it("keeps the requested display id even if Electron cannot rematch it, while using primary bounds", () => {
+ const resolved = resolveWindowsCaptureDisplay(
+ { display_id: "303" },
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ displayId: 303,
+ bounds: primaryDisplay.bounds,
+ });
+ });
+});
+
+describe("resolveWindowsCaptureTarget", () => {
+ const primaryDisplay = {
+ id: 101,
+ bounds: {
+ x: 0,
+ y: 0,
+ width: 1920,
+ height: 1080,
+ },
+ };
+
+ const secondaryDisplay = {
+ id: 202,
+ bounds: {
+ x: 1920,
+ y: -40,
+ width: 2560,
+ height: 1440,
+ },
+ };
+
+ it("uses a window handle when a Windows window source is selected", () => {
+ const resolved = resolveWindowsCaptureTarget(
+ { id: "window:123456:0", sourceType: "window" },
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ kind: "window",
+ windowHandle: 123456,
+ });
+ });
+
+ it("does not silently turn an invalid window source into display capture", () => {
+ const resolved = resolveWindowsCaptureTarget(
+ { id: "window:0:0", sourceType: "window", display_id: String(secondaryDisplay.id) },
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ kind: "invalid-window",
+ });
+ });
+
+ it("keeps display capture behavior for selected screens", () => {
+ const resolved = resolveWindowsCaptureTarget(
+ { id: "screen:202:0", sourceType: "screen", display_id: String(secondaryDisplay.id) },
+ [primaryDisplay, secondaryDisplay],
+ primaryDisplay,
+ );
+
+ expect(resolved).toEqual({
+ kind: "display",
+ displayId: secondaryDisplay.id,
+ bounds: secondaryDisplay.bounds,
+ });
+ });
+});
diff --git a/electron/ipc/windowsCaptureSelection.ts b/electron/ipc/windowsCaptureSelection.ts
new file mode 100644
index 000000000..3fdf3c008
--- /dev/null
+++ b/electron/ipc/windowsCaptureSelection.ts
@@ -0,0 +1,102 @@
+export type WindowsCaptureSourceLike = {
+ id?: string;
+ display_id?: string;
+ sourceType?: string;
+};
+
+export type WindowsCaptureDisplayBounds = {
+ x: number;
+ y: number;
+ width: number;
+ height: number;
+};
+
+export type WindowsCaptureDisplayLike = {
+ id: number;
+ bounds: WindowsCaptureDisplayBounds;
+};
+
+export type ResolvedWindowsCaptureDisplay = {
+ displayId: number;
+ bounds: WindowsCaptureDisplayBounds;
+};
+
+export type ResolvedWindowsCaptureTarget =
+ | {
+ kind: "window";
+ windowHandle: number;
+ }
+ | {
+ kind: "display";
+ displayId: number;
+ bounds: WindowsCaptureDisplayBounds;
+ }
+ | {
+ kind: "invalid-window";
+ };
+
+function parseDesktopCapturerWindowHandle(sourceId?: string) {
+ if (!sourceId) {
+ return null;
+ }
+
+ const match = sourceId.match(/^window:(\d+)/);
+ if (!match) {
+ return null;
+ }
+
+ const handle = Number.parseInt(match[1], 10);
+ return Number.isFinite(handle) && handle > 0 ? handle : null;
+}
+
+function isWindowCaptureSource(source: WindowsCaptureSourceLike | null | undefined) {
+ return source?.sourceType === "window" || source?.id?.startsWith("window:") === true;
+}
+
+export function resolveWindowsCaptureDisplay(
+ source: WindowsCaptureSourceLike | null | undefined,
+ allDisplays: WindowsCaptureDisplayLike[],
+ primaryDisplay: WindowsCaptureDisplayLike,
+): ResolvedWindowsCaptureDisplay {
+ const requestedDisplayId = Number(source?.display_id);
+ const primaryDisplayId = Number(primaryDisplay.id);
+ const requestedOrPrimaryDisplayId =
+ Number.isFinite(requestedDisplayId) && requestedDisplayId > 0
+ ? requestedDisplayId
+ : primaryDisplayId;
+
+ const matchedDisplay =
+ allDisplays.find((display) => String(display.id) === String(requestedOrPrimaryDisplayId)) ??
+ primaryDisplay;
+
+ return {
+ displayId: requestedOrPrimaryDisplayId,
+ bounds: matchedDisplay.bounds,
+ };
+}
+
+export function resolveWindowsCaptureTarget(
+ source: WindowsCaptureSourceLike | null | undefined,
+ allDisplays: WindowsCaptureDisplayLike[],
+ primaryDisplay: WindowsCaptureDisplayLike,
+): ResolvedWindowsCaptureTarget {
+ if (isWindowCaptureSource(source)) {
+ const windowHandle = parseDesktopCapturerWindowHandle(source?.id);
+ if (windowHandle !== null) {
+ return {
+ kind: "window",
+ windowHandle,
+ };
+ }
+
+ return {
+ kind: "invalid-window",
+ };
+ }
+
+ const resolvedDisplay = resolveWindowsCaptureDisplay(source, allDisplays, primaryDisplay);
+ return {
+ kind: "display",
+ ...resolvedDisplay,
+ };
+}
diff --git a/electron/macosDistributionPolicy.test.mjs b/electron/macosDistributionPolicy.test.mjs
new file mode 100644
index 000000000..bd744802c
--- /dev/null
+++ b/electron/macosDistributionPolicy.test.mjs
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import {
+ assertValidAppleTeamId,
+ collectArchitectureErrors,
+ collectCodeSigningMetadataErrors,
+ collectEntitlementErrors,
+ expectedMachOArchitecture,
+ parseLipoArchitectures,
+} from "../scripts/macos-distribution-policy.mjs";
+
+const validCodeSigningDetails = `
+Identifier=dev.recordly.app
+CodeDirectory v=20500 size=123 flags=0x10000(runtime) hashes=3+7 location=embedded
+Authority=Developer ID Application: Recordly Developer (A1B2C3D4E5)
+Authority=Developer ID Certification Authority
+Authority=Apple Root CA
+Timestamp=Aug 9, 2026 at 10:00:00
+TeamIdentifier=A1B2C3D4E5
+`;
+
+describe("macOS distribution signing policy", () => {
+ it("accepts a valid Developer ID signature", () => {
+ expect(collectCodeSigningMetadataErrors(validCodeSigningDetails, "A1B2C3D4E5")).toEqual([]);
+ });
+
+ it("rejects a wrong identity, team, timestamp, runtime, and bundle identifier", () => {
+ const details = `
+Identifier=dev.example.app
+CodeDirectory v=20400 size=123 flags=0x0(none)
+Authority=Apple Development: Example (Z9Y8X7W6V5)
+Timestamp=none
+TeamIdentifier=Z9Y8X7W6V5
+`;
+
+ expect(collectCodeSigningMetadataErrors(details, "A1B2C3D4E5")).toEqual([
+ "unexpected bundle identifier: dev.example.app",
+ "the leaf signing authority is not Developer ID Application",
+ "unexpected TeamIdentifier: Z9Y8X7W6V5",
+ "secure signing timestamp is missing",
+ "hardened runtime flag is missing",
+ ]);
+ });
+
+ it("validates the expected Apple team ID shape", () => {
+ expect(() => assertValidAppleTeamId("A1B2C3D4E5")).not.toThrow();
+ expect(() => assertValidAppleTeamId("short")).toThrow(/exactly 10/);
+ });
+});
+
+describe("macOS distribution entitlement policy", () => {
+ const validEntitlements = {
+ "com.apple.security.cs.allow-jit": true,
+ "com.apple.security.cs.allow-unsigned-executable-memory": true,
+ "com.apple.security.cs.disable-library-validation": true,
+ "com.apple.security.device.audio-input": true,
+ "com.apple.security.device.camera": true,
+ };
+
+ it("accepts the intended production entitlements", () => {
+ expect(collectEntitlementErrors(validEntitlements)).toEqual([]);
+ });
+
+ it("rejects missing capabilities and debug attachment", () => {
+ expect(
+ collectEntitlementErrors({
+ ...validEntitlements,
+ "com.apple.security.cs.allow-jit": false,
+ "com.apple.security.get-task-allow": true,
+ }),
+ ).toEqual([
+ "required entitlement is missing or disabled: com.apple.security.cs.allow-jit",
+ "distribution build must not enable com.apple.security.get-task-allow",
+ ]);
+ });
+
+ it("rejects unreviewed root runtime exceptions", () => {
+ expect(
+ collectEntitlementErrors({
+ ...validEntitlements,
+ "com.apple.security.cs.allow-dyld-environment-variables": true,
+ }),
+ ).toEqual([
+ "unexpected root application entitlement: com.apple.security.cs.allow-dyld-environment-variables",
+ ]);
+ });
+
+ it("rejects disabled but unreviewed entitlement keys", () => {
+ expect(
+ collectEntitlementErrors({
+ ...validEntitlements,
+ "com.apple.security.get-task-allow": false,
+ }),
+ ).toEqual(["unexpected root application entitlement: com.apple.security.get-task-allow"]);
+ });
+});
+
+describe("macOS distribution architecture policy", () => {
+ it("parses thin and fat lipo output", () => {
+ expect(parseLipoArchitectures("Non-fat file: App is architecture: arm64")).toEqual([
+ "arm64",
+ ]);
+ expect(
+ parseLipoArchitectures("Architectures in the fat file: App are: x86_64 arm64"),
+ ).toEqual(["x86_64", "arm64"]);
+ });
+
+ it("uses path-specific helper architecture before the build architecture", () => {
+ expect(
+ expectedMachOArchitecture("app/electron/native/bin/darwin-arm64/helper", "x64"),
+ ).toBe("arm64");
+ expect(
+ expectedMachOArchitecture("app/electron/native/bin/darwin-x64/helper", "arm64"),
+ ).toBe("x86_64");
+ expect(expectedMachOArchitecture("Recordly.app/Contents/MacOS/Recordly", "x64")).toBe(
+ "x86_64",
+ );
+ });
+
+ it("reports a binary that lacks the required architecture", () => {
+ expect(
+ collectArchitectureErrors("Recordly.app/Contents/MacOS/Recordly", "arm64", "x64"),
+ ).toEqual(["Recordly.app/Contents/MacOS/Recordly does not contain x86_64 (found: arm64)"]);
+ });
+});
diff --git a/electron/main.ts b/electron/main.ts
index 04d15b69e..913ca05df 100644
--- a/electron/main.ts
+++ b/electron/main.ts
@@ -1,43 +1,125 @@
-import { app, BrowserWindow, Tray, Menu, nativeImage } from 'electron'
-import { fileURLToPath } from 'node:url'
-import path from 'node:path'
-import fs from 'node:fs/promises'
-import { createHudOverlayWindow, createEditorWindow, createSourceSelectorWindow } from './windows'
-import { registerIpcHandlers } from './ipc/handlers'
-import { cleanupMouseTracking } from './ipc/mouseTracking'
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
-
-export const RECORDINGS_DIR = path.join(app.getPath('userData'), 'recordings')
-
-// Cleanup old recordings (older than 1 day)
-async function cleanupOldRecordings() {
- try {
- const files = await fs.readdir(RECORDINGS_DIR)
- const now = Date.now()
- const maxAge = 1 * 24 * 60 * 60 * 1000
-
- for (const file of files) {
- const filePath = path.join(RECORDINGS_DIR, file)
- const stats = await fs.stat(filePath)
-
- if (now - stats.mtimeMs > maxAge) {
- await fs.unlink(filePath)
- console.log(`Deleted old recording: ${file}`)
- }
- }
- } catch (error) {
- console.error('Failed to cleanup old recordings:', error)
- }
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+ app,
+ BrowserWindow,
+ desktopCapturer,
+ dialog,
+ webContents as electronWebContents,
+ ipcMain,
+ Menu,
+ nativeImage,
+ session,
+ shell,
+ systemPreferences,
+ Tray,
+} from "electron";
+import { RECORDINGS_DIR } from "./appPaths";
+import { showCursor } from "./cursorHider";
+import { getGpuSwitches } from "./gpuSwitches";
+import {
+ cleanupAllExportStreams,
+ cleanupNativeVideoExportSessions,
+ getSelectedSourceId,
+ killWindowsCaptureProcess,
+ registerIpcHandlers,
+} from "./ipc/handlers";
+import { ensureMediaServer } from "./mediaServer";
+import { hardenWebContentsNavigation, shouldHardenWebContentsType } from "./navigationPolicy";
+import { shouldGrantDisplayCapture, shouldGrantMediaPermission } from "./permissionPolicy";
+import { ensurePackagedRendererServer, getPackagedRendererBaseUrl } from "./rendererServer";
+import {
+ checkForAppUpdates,
+ deferUpdateReminder,
+ dismissUpdateToast,
+ downloadAvailableUpdate,
+ getCurrentUpdateToastPayload,
+ getExperimentalUpdatesEnabled,
+ getUpdaterLogPath,
+ getUpdateStatusSummary,
+ installDownloadedUpdateNow,
+ previewUpdateToast,
+ setExperimentalUpdatesEnabled,
+ setupAutoUpdates,
+ skipAvailableUpdateVersion,
+} from "./updater";
+import {
+ createEditorWindow,
+ createHudOverlayWindow,
+ createSourceSelectorWindow,
+ getHudOverlayWindow,
+ getUpdateToastWindow,
+ hideUpdateToastWindow,
+ isHudOverlayMousePassthroughSupported,
+ reassertHudOverlayMousePassthrough as reassertHudOverlayMouseState,
+ setHudOverlayRecordingActive,
+ showUpdateToastWindow,
+} from "./windows";
+
+const electronMainDir = path.dirname(fileURLToPath(import.meta.url));
+const IS_SMOKE_EXPORT = process.env.RECORDLY_SMOKE_EXPORT === "1";
+
+function ignoreBrokenConsolePipe(stream: NodeJS.WritableStream | undefined) {
+ stream?.on("error", (error: NodeJS.ErrnoException) => {
+ if (error.code === "EPIPE") {
+ return;
+ }
+ throw error;
+ });
+}
+
+ignoreBrokenConsolePipe(process.stdout);
+ignoreBrokenConsolePipe(process.stderr);
+
+app.commandLine.appendSwitch("ignore-gpu-blocklist");
+app.commandLine.appendSwitch("enable-unsafe-webgpu");
+app.commandLine.appendSwitch("enable-gpu-rasterization");
+
+app.on("web-contents-created", (_event, contents) => {
+ if (!shouldHardenWebContentsType(contents.getType())) {
+ return;
+ }
+
+ hardenWebContentsNavigation(contents, (url) => shell.openExternal(url));
+});
+
+function configureGpuAccelerationSwitches() {
+ const { useAngle, useGl, disableFeatures } = getGpuSwitches(process.platform, process.env);
+ if (useAngle) {
+ app.commandLine.appendSwitch("use-angle", useAngle);
+ }
+ if (useGl) {
+ app.commandLine.appendSwitch("use-gl", useGl);
+ }
+ if (disableFeatures && disableFeatures.length > 0) {
+ app.commandLine.appendSwitch("disable-features", disableFeatures.join(","));
+ }
+}
+
+async function logSmokeExportGpuDiagnostics() {
+ if (!IS_SMOKE_EXPORT) {
+ return;
+ }
+
+ try {
+ console.log("[smoke-export] GPU feature status", JSON.stringify(app.getGPUFeatureStatus()));
+ console.log("[smoke-export] GPU info", JSON.stringify(await app.getGPUInfo("basic")));
+ } catch (error) {
+ console.warn("[smoke-export] Failed to read GPU diagnostics:", error);
+ }
}
+configureGpuAccelerationSwitches();
+
async function ensureRecordingsDir() {
- try {
- await fs.mkdir(RECORDINGS_DIR, { recursive: true })
- console.log('Recordings directory ready:', RECORDINGS_DIR)
- } catch (error) {
- console.error('Failed to create recordings directory:', error)
- }
+ try {
+ await fs.mkdir(RECORDINGS_DIR, { recursive: true });
+ console.log("RECORDINGS_DIR:", RECORDINGS_DIR);
+ console.log("User Data Path:", app.getPath("userData"));
+ } catch (error) {
+ console.error("Failed to create recordings directory:", error);
+ }
}
// The built directory structure
@@ -49,117 +131,988 @@ async function ensureRecordingsDir() {
// │ │ ├── main.js
// │ │ └── preload.mjs
// │
-process.env.APP_ROOT = path.join(__dirname, '..')
+process.env.APP_ROOT = path.join(electronMainDir, "..");
// Use ['ENV_NAME'] avoid vite:define plugin - Vite@2.x
-export const VITE_DEV_SERVER_URL = process.env['VITE_DEV_SERVER_URL']
-export const MAIN_DIST = path.join(process.env.APP_ROOT, 'dist-electron')
-export const RENDERER_DIST = path.join(process.env.APP_ROOT, 'dist')
+export const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
+export const MAIN_DIST = path.join(process.env.APP_ROOT, "dist-electron");
+export const RENDERER_DIST = path.join(process.env.APP_ROOT, "dist");
+const IS_DEV = Boolean(VITE_DEV_SERVER_URL);
+
+process.env.VITE_PUBLIC = VITE_DEV_SERVER_URL
+ ? path.join(process.env.APP_ROOT, "public")
+ : RENDERER_DIST;
+
+function getTrustedCaptureDocumentBaseUrls(): string[] {
+ const trustedUrls = [pathToFileURL(path.join(RENDERER_DIST, "index.html")).href];
+
+ if (VITE_DEV_SERVER_URL) {
+ trustedUrls.push(VITE_DEV_SERVER_URL);
+ }
+
+ const packagedRendererBaseUrl = getPackagedRendererBaseUrl();
+ if (packagedRendererBaseUrl) {
+ trustedUrls.push(new URL("/", packagedRendererBaseUrl).href);
+ }
+
+ return trustedUrls;
+}
-process.env.VITE_PUBLIC = VITE_DEV_SERVER_URL ? path.join(process.env.APP_ROOT, 'public') : RENDERER_DIST
+function isHudWebContents(webContents: Electron.WebContents | null): boolean {
+ if (!webContents || webContents.isDestroyed()) {
+ return false;
+ }
+
+ const hudWindow = getHudOverlayWindow();
+ return Boolean(hudWindow && hudWindow.webContents === webContents);
+}
// Window references
-let mainWindow: BrowserWindow | null = null
-let sourceSelectorWindow: BrowserWindow | null = null
-let tray: Tray | null = null
-let selectedSourceName = ''
+let mainWindow: BrowserWindow | null = null;
+let sourceSelectorWindow: BrowserWindow | null = null;
+let tray: Tray | null = null;
+let trayContextMenu: Menu | null = null;
+let selectedSourceName = "";
+let editorHasUnsavedChanges = false;
+let isForceClosing = false;
+let isAppQuitting = false;
+let isCreatingMainWindow = false;
+let isCreatingEditorWindow = false;
+const shouldEnforceSingleInstanceLock = !IS_DEV;
+const hasSingleInstanceLock = shouldEnforceSingleInstanceLock
+ ? app.requestSingleInstanceLock()
+ : true;
+
+if (!hasSingleInstanceLock) {
+ app.quit();
+}
+
+function closeEditorWindowBypassingUnsavedPrompt(window: BrowserWindow | null) {
+ if (!window || window.isDestroyed()) {
+ return;
+ }
+
+ if (isEditorWindow(window)) {
+ isForceClosing = true;
+ editorHasUnsavedChanges = false;
+ }
+ window.close();
+}
+
+function closeEditorWindowToHud(window: BrowserWindow | null) {
+ if (!window || window.isDestroyed()) {
+ return;
+ }
+
+ // The HUD renderer normally remains hidden while the editor is open so
+ // recording finalization can continue. Restore that HUD before destroying
+ // the editor, keeping Recordly in its ready-to-record state on the taskbar.
+ window.hide();
+ if (mainWindow === window) {
+ mainWindow = null;
+ }
+ createWindow();
+ closeEditorWindowBypassingUnsavedPrompt(window);
+}
+
+function restoreWindowSafely(window: BrowserWindow | null) {
+ if (!window || window.isDestroyed()) {
+ return;
+ }
+
+ if (!isEditorWindow(window) && process.platform === "win32") {
+ showHudOverlayFromTray();
+ return;
+ }
+
+ if (window.isMinimized()) {
+ window.restore();
+ }
+
+ if (!window.isVisible()) {
+ window.show();
+ }
+
+ window.moveTop();
+ window.focus();
+}
+
+function getExistingEditorWindow(): BrowserWindow | null {
+ return (
+ BrowserWindow.getAllWindows().find(
+ (window) => !window.isDestroyed() && isEditorWindow(window),
+ ) ?? null
+ );
+}
+
+// Tray Icons (lazily created after app is ready to avoid accessing Electron APIs too early)
+let defaultTrayIcon: ReturnType | null = null;
+let recordingTrayIcon: ReturnType | null = null;
+
+function getPlatformAppIconFilename(size: 32 | 128 | 512) {
+ const baseName = process.platform === "darwin" ? "recordlymac" : "recordly";
+ return `app-icons/${baseName}-${size}.png`;
+}
+
+function getDefaultTrayIcon() {
+ if (!defaultTrayIcon) {
+ defaultTrayIcon = getTrayIcon(getPlatformAppIconFilename(32));
+ }
+ return defaultTrayIcon;
+}
+
+function getRecordingTrayIcon() {
+ if (!recordingTrayIcon) {
+ recordingTrayIcon = getTrayIcon("rec-button.png");
+ }
+ return recordingTrayIcon;
+}
+
+function showHudOverlayFromTray() {
+ const updateToast = getUpdateToastWindow();
+ if (updateToast?.isVisible()) {
+ updateToast.show();
+ updateToast.moveTop();
+ updateToast.focus();
+ return true;
+ }
+
+ const hud = getHudOverlayWindow();
+ if (!hud) {
+ return false;
+ }
+
+ if (hud.isMinimized()) {
+ hud.restore();
+ }
+
+ if (process.platform === "win32" && isHudOverlayMousePassthroughSupported()) {
+ hud.showInactive();
+ hud.moveTop();
+ reassertHudOverlayMouseState();
+ return true;
+ }
+
+ hud.show();
+ hud.moveTop();
+ hud.focus();
+ return true;
+}
+
+ipcMain.on("set-has-unsaved-changes", (_event, hasChanges: boolean) => {
+ editorHasUnsavedChanges = hasChanges;
+});
function createWindow() {
- mainWindow = createHudOverlayWindow()
+ if (!app.isReady()) {
+ void app.whenReady().then(() => {
+ if (!mainWindow || mainWindow.isDestroyed()) {
+ createWindow();
+ }
+ });
+ return;
+ }
+
+ if (isCreatingMainWindow) {
+ return;
+ }
+
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ restoreWindowSafely(mainWindow);
+ return;
+ }
+
+ const existingHudWindow = getHudOverlayWindow();
+ if (existingHudWindow) {
+ mainWindow = existingHudWindow;
+ restoreWindowSafely(existingHudWindow);
+ return;
+ }
+
+ isCreatingMainWindow = true;
+ const createdHudWindow = createHudOverlayWindow();
+ mainWindow = createdHudWindow;
+ createdHudWindow.once("closed", () => {
+ if (mainWindow === createdHudWindow) {
+ mainWindow = null;
+ }
+ });
+ isCreatingMainWindow = false;
+}
+
+function focusOrCreateMainWindow() {
+ if (!app.isReady()) {
+ void app.whenReady().then(() => {
+ focusOrCreateMainWindow();
+ });
+ return;
+ }
+
+ const updateToast = getUpdateToastWindow();
+ if (updateToast?.isVisible()) {
+ updateToast.show();
+ updateToast.moveTop();
+ updateToast.focus();
+ return;
+ }
+
+ if (!mainWindow || mainWindow.isDestroyed()) {
+ const existingHud = getHudOverlayWindow();
+ if (existingHud && !existingHud.isDestroyed()) {
+ mainWindow = existingHud;
+ } else {
+ createWindow();
+ return;
+ }
+ }
+
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ // On Linux/Wayland, focus() often doesn't take effect (compositor ignores it). Apps like Telegram
+ // work because they receive an XDG activation token via StatusNotifierItem.ProvideXdgActivationToken;
+ // Electron's tray doesn't handle that yet. Workaround: destroy and recreate the HUD so the new
+ // window gets focus (creation path works). Only for HUD, not editor.
+ if (
+ process.platform === "linux" &&
+ !mainWindow.isFocused() &&
+ !isEditorWindow(mainWindow)
+ ) {
+ const win = mainWindow;
+ mainWindow = null;
+ win.once("closed", () => createWindow());
+ win.destroy();
+ return;
+ }
+
+ // On Win32 with mouse passthrough enabled (Win11+), calling
+ // show/moveTop/focus on the transparent HUD overlay permanently corrupts
+ // setIgnoreMouseEvents forwarding, making it click-through. Only focus
+ // the editor window; the HUD is alwaysOnTop so it doesn't need explicit
+ // focus. On Win10 (passthrough disabled), the HUD is always interactive
+ // and can be safely shown/restored.
+ if (
+ process.platform === "win32" &&
+ !isEditorWindow(mainWindow) &&
+ isHudOverlayMousePassthroughSupported()
+ ) {
+ showHudOverlayFromTray();
+ return;
+ }
+
+ mainWindow.show();
+ if (mainWindow.isMinimized()) mainWindow.restore();
+ mainWindow.moveTop();
+ mainWindow.focus();
+ }
+}
+
+function isEditorWindow(window: BrowserWindow) {
+ return window.webContents.getURL().includes("windowType=editor");
+}
+
+function sendEditorMenuAction(
+ channel: "menu-load-project" | "menu-save-project" | "menu-save-project-as",
+) {
+ let targetWindow = BrowserWindow.getFocusedWindow() ?? mainWindow;
+
+ if (!targetWindow || targetWindow.isDestroyed() || !isEditorWindow(targetWindow)) {
+ createEditorWindowWrapper();
+ targetWindow = mainWindow;
+ if (!targetWindow || targetWindow.isDestroyed()) return;
+
+ targetWindow.webContents.once("did-finish-load", () => {
+ if (!targetWindow || targetWindow.isDestroyed()) return;
+ targetWindow.webContents.send(channel);
+ });
+ return;
+ }
+
+ targetWindow.webContents.send(channel);
+}
+
+function setupApplicationMenu() {
+ const isMac = process.platform === "darwin";
+ const template: Electron.MenuItemConstructorOptions[] = [];
+ if (isMac) {
+ template.push({
+ label: app.name,
+ submenu: [
+ { role: "about" },
+ { type: "separator" },
+ { role: "services" },
+ { type: "separator" },
+ { role: "hide" },
+ { role: "hideOthers" },
+ { role: "unhide" },
+ { type: "separator" },
+ { role: "quit" },
+ ],
+ });
+ }
+
+ template.push(
+ {
+ label: "File",
+ submenu: [
+ {
+ label: "Open Projects…",
+ accelerator: "CmdOrCtrl+O",
+ click: () => sendEditorMenuAction("menu-load-project"),
+ },
+ {
+ label: "Save Project…",
+ accelerator: "CmdOrCtrl+S",
+ click: () => sendEditorMenuAction("menu-save-project"),
+ },
+ {
+ label: "Save Project As…",
+ accelerator: "CmdOrCtrl+Shift+S",
+ click: () => sendEditorMenuAction("menu-save-project-as"),
+ },
+ ...(isMac
+ ? []
+ : [
+ { type: "separator" as const },
+ { role: "quit" as const, accelerator: "CmdOrCtrl+Q" },
+ ]),
+ ],
+ },
+ {
+ label: "Edit",
+ submenu: [
+ { role: "undo" },
+ { role: "redo" },
+ { type: "separator" },
+ { role: "cut" },
+ { role: "copy" },
+ { role: "paste" },
+ { role: "selectAll" },
+ ],
+ },
+ {
+ label: "View",
+ submenu: [
+ { role: "reload" },
+ { role: "forceReload" },
+ { role: "toggleDevTools" },
+ { type: "separator" },
+ { role: "resetZoom" },
+ { role: "zoomIn" },
+ { role: "zoomOut" },
+ { type: "separator" },
+ { role: "togglefullscreen" },
+ ],
+ },
+ {
+ label: "Window",
+ submenu: isMac
+ ? [{ role: "minimize" }, { role: "zoom" }, { type: "separator" }, { role: "front" }]
+ : [{ role: "minimize" }, { role: "close" }],
+ },
+ {
+ label: "Help",
+ submenu: [
+ {
+ label: "Check for Updates…",
+ click: () => {
+ void checkForAppUpdates(getUpdateDialogWindow, { manual: true });
+ },
+ },
+ ],
+ },
+ );
+
+ const menu = Menu.buildFromTemplate(template);
+ Menu.setApplicationMenu(menu);
+}
+
+function isPrimaryTrayClick(event: unknown) {
+ const button =
+ event && typeof event === "object" && "button" in event
+ ? (event as { button?: number | string }).button
+ : undefined;
+ return button === undefined || button === 0 || button === "left";
}
function createTray() {
- const iconPath = path.join(process.env.VITE_PUBLIC || RENDERER_DIST, 'rec-button.png');
- let icon = nativeImage.createFromPath(iconPath);
- icon = icon.resize({ width: 24, height: 24, quality: 'best' });
- tray = new Tray(icon);
- updateTrayMenu();
-}
-
-function updateTrayMenu() {
- if (!tray) return;
- const menuTemplate = [
- {
- label: 'Stop Recording',
- click: () => {
- if (mainWindow && !mainWindow.isDestroyed()) {
- mainWindow.webContents.send('stop-recording-from-tray');
- }
- }
- }
- ];
- const contextMenu = Menu.buildFromTemplate(menuTemplate);
- tray.setContextMenu(contextMenu);
- tray.setToolTip(`Recording: ${selectedSourceName}`);
+ tray = new Tray(getDefaultTrayIcon());
+ tray.on("click", (event) => {
+ if (process.platform === "win32" && !isPrimaryTrayClick(event)) {
+ return;
+ }
+
+ focusOrCreateMainWindow();
+ });
+
+ if (process.platform === "win32") {
+ tray.on("right-click", () => {
+ if (!tray || !trayContextMenu) {
+ return;
+ }
+
+ tray.popUpContextMenu(trayContextMenu);
+ });
+ return;
+ }
+
+ tray.on("double-click", () => focusOrCreateMainWindow());
+}
+
+function shouldUseTray() {
+ // macOS and Windows expose Recordly through their Dock/taskbar. Keep the
+ // tray entry only on Linux, where it remains the primary app entry point.
+ return process.platform === "linux";
+}
+
+function getPublicAssetPath(filename: string) {
+ return path.join(process.env.VITE_PUBLIC || RENDERER_DIST, filename);
+}
+
+function getAppImage(filename: string) {
+ return nativeImage.createFromPath(getPublicAssetPath(filename));
+}
+
+function getTrayIcon(filename: string) {
+ return getAppImage(filename).resize({
+ width: 24,
+ height: 24,
+ quality: "best",
+ });
+}
+
+function syncDockIcon() {
+ if (process.platform !== "darwin" || !app.dock) {
+ return;
+ }
+
+ const dockIcon = getAppImage(getPlatformAppIconFilename(512));
+ if (!dockIcon.isEmpty()) {
+ app.dock.setIcon(dockIcon);
+ }
+}
+
+function sendUpdateToastToWindows(channel: "update-toast-state", payload: unknown) {
+ if (!payload) {
+ const existingWindow = getUpdateToastWindow();
+ if (existingWindow) {
+ existingWindow.webContents.send(channel, null);
+ }
+ hideUpdateToastWindow();
+ return true;
+ }
+
+ const toastWindow = showUpdateToastWindow();
+ const sendPayload = () => {
+ toastWindow.webContents.send(channel, payload);
+ showUpdateToastWindow();
+ };
+
+ if (toastWindow.webContents.isLoadingMainFrame()) {
+ toastWindow.webContents.once("did-finish-load", sendPayload);
+ } else {
+ sendPayload();
+ }
+
+ return true;
+}
+
+function getUpdateDialogWindow() {
+ const focusedWindow = BrowserWindow.getFocusedWindow();
+ if (focusedWindow && !focusedWindow.isDestroyed()) {
+ return focusedWindow;
+ }
+
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ return mainWindow;
+ }
+
+ return getHudOverlayWindow();
+}
+
+ipcMain.handle("install-downloaded-update", () => {
+ installDownloadedUpdateNow(sendUpdateToastToWindows);
+ return { success: true };
+});
+
+ipcMain.handle("download-available-update", (_event, installAfterDownload?: boolean) => {
+ return downloadAvailableUpdate(sendUpdateToastToWindows, {
+ installAfterDownload: Boolean(installAfterDownload),
+ });
+});
+
+ipcMain.handle("defer-downloaded-update", (_event, delayMs?: number) => {
+ return deferUpdateReminder(getUpdateDialogWindow, sendUpdateToastToWindows, delayMs);
+});
+
+ipcMain.handle("dismiss-update-toast", () => {
+ return dismissUpdateToast(getUpdateDialogWindow, sendUpdateToastToWindows);
+});
+
+ipcMain.handle("skip-update-version", () => {
+ return skipAvailableUpdateVersion(sendUpdateToastToWindows);
+});
+
+ipcMain.handle("get-current-update-toast-payload", () => {
+ return getCurrentUpdateToastPayload();
+});
+
+ipcMain.handle("get-update-status-summary", () => {
+ return getUpdateStatusSummary();
+});
+
+ipcMain.handle("get-experimental-updates-enabled", () => {
+ return getExperimentalUpdatesEnabled();
+});
+
+ipcMain.handle("set-experimental-updates-enabled", async (_event, enabled: unknown) => {
+ if (typeof enabled !== "boolean") {
+ return { success: false, enabled: getExperimentalUpdatesEnabled() };
+ }
+
+ try {
+ const savedValue = setExperimentalUpdatesEnabled(enabled);
+ await checkForAppUpdates(getUpdateDialogWindow);
+ return { success: true, enabled: savedValue };
+ } catch (error) {
+ console.error("Failed to update experimental updates preference:", error);
+ return {
+ success: false,
+ enabled: getExperimentalUpdatesEnabled(),
+ error: String(error),
+ };
+ }
+});
+
+ipcMain.handle("preview-update-toast", () => {
+ return { success: previewUpdateToast(sendUpdateToastToWindows) };
+});
+
+ipcMain.handle("check-for-app-updates", async () => {
+ await checkForAppUpdates(getUpdateDialogWindow, { manual: true });
+ return { success: true, logPath: getUpdaterLogPath() };
+});
+
+function updateTrayMenu(recording: boolean = false) {
+ if (!tray) return;
+ const trayIcon = recording ? getRecordingTrayIcon() : getDefaultTrayIcon();
+ const trayToolTip = recording ? `Recording: ${selectedSourceName}` : "Recordly";
+ const menuTemplate = recording
+ ? [
+ {
+ label: "Show Controls",
+ click: () => {
+ if (!showHudOverlayFromTray()) {
+ focusOrCreateMainWindow();
+ }
+ },
+ },
+ {
+ label: "Stop Recording",
+ click: () => {
+ if (mainWindow && !mainWindow.isDestroyed()) {
+ mainWindow.webContents.send("stop-recording-from-tray");
+ }
+ },
+ },
+ ]
+ : [
+ {
+ label: "Open",
+ click: () => {
+ if (!showHudOverlayFromTray()) {
+ focusOrCreateMainWindow();
+ }
+ },
+ },
+ {
+ label: "Quit",
+ click: () => {
+ app.quit();
+ },
+ },
+ ];
+ const menu = Menu.buildFromTemplate(menuTemplate);
+ trayContextMenu = menu;
+ tray.setImage(trayIcon);
+ tray.setToolTip(trayToolTip);
+ if (process.platform !== "win32") {
+ tray.setContextMenu(menu);
+ }
}
function createEditorWindowWrapper() {
- if (mainWindow) {
- mainWindow.close()
- mainWindow = null
- }
- mainWindow = createEditorWindow()
+ const existingEditorWindow = getExistingEditorWindow();
+ if (existingEditorWindow) {
+ mainWindow = existingEditorWindow;
+ restoreWindowSafely(existingEditorWindow);
+ return existingEditorWindow;
+ }
+
+ if (isCreatingEditorWindow) {
+ const currentWindow = mainWindow;
+ if (currentWindow && !currentWindow.isDestroyed()) {
+ return currentWindow;
+ }
+
+ const currentEditorWindow = getExistingEditorWindow();
+ if (currentEditorWindow) {
+ mainWindow = currentEditorWindow;
+ return currentEditorWindow;
+ }
+ }
+
+ isCreatingEditorWindow = true;
+ const previousWindow = mainWindow;
+ if (previousWindow && !previousWindow.isDestroyed()) {
+ const closingEditorWindow = isEditorWindow(previousWindow);
+
+ if (closingEditorWindow) {
+ closeEditorWindowBypassingUnsavedPrompt(previousWindow);
+ } else {
+ // It's the HUD or another window. Hide it instead of closing so background
+ // tasks (like webcam finalizing) can finish in its renderer process.
+ previousWindow.hide();
+ }
+
+ if (!closingEditorWindow) {
+ isForceClosing = false;
+ }
+ if (mainWindow === previousWindow) {
+ mainWindow = null;
+ }
+ }
+ const editorWindow = createEditorWindow();
+ mainWindow = editorWindow;
+ editorHasUnsavedChanges = false;
+
+ editorWindow.on("closed", () => {
+ if (mainWindow === editorWindow) {
+ mainWindow = null;
+ }
+ isCreatingEditorWindow = false;
+ isForceClosing = false;
+ editorHasUnsavedChanges = false;
+ });
+
+ editorWindow.on("close", (event) => {
+ if (isForceClosing || !editorHasUnsavedChanges) {
+ if (process.platform === "win32" && !isForceClosing && !isAppQuitting) {
+ event.preventDefault();
+ closeEditorWindowToHud(editorWindow);
+ }
+ return;
+ }
+
+ event.preventDefault();
+
+ const choice = dialog.showMessageBoxSync(editorWindow, {
+ type: "warning",
+ buttons: ["Save & Close", "Discard & Close", "Cancel"],
+ defaultId: 0,
+ cancelId: 2,
+ title: "Unsaved Changes",
+ message: "You have unsaved changes.",
+ detail: "Do you want to save your project before closing?",
+ });
+
+ if (choice === 0) {
+ editorWindow.webContents.send("request-save-before-close");
+ ipcMain.once("save-before-close-done", (_event, saved: boolean) => {
+ if (!saved) {
+ isAppQuitting = false;
+ return;
+ }
+
+ if (process.platform === "win32" && !isAppQuitting) {
+ closeEditorWindowToHud(editorWindow);
+ } else {
+ closeEditorWindowBypassingUnsavedPrompt(editorWindow);
+ }
+ });
+ } else if (choice === 1) {
+ if (process.platform === "win32" && !isAppQuitting) {
+ closeEditorWindowToHud(editorWindow);
+ } else {
+ closeEditorWindowBypassingUnsavedPrompt(editorWindow);
+ }
+ } else {
+ isAppQuitting = false;
+ }
+ });
+
+ return editorWindow;
}
function createSourceSelectorWindowWrapper() {
- sourceSelectorWindow = createSourceSelectorWindow()
- sourceSelectorWindow.on('closed', () => {
- sourceSelectorWindow = null
- })
- return sourceSelectorWindow
+ sourceSelectorWindow = createSourceSelectorWindow();
+ sourceSelectorWindow.on("closed", () => {
+ sourceSelectorWindow = null;
+ });
+ return sourceSelectorWindow;
}
-// Quit when all windows are closed, except on macOS. There, it's common
-// for applications and their menu bar to stay active until the user quits
+// On macOS, applications and their menu bar stay active until the user quits
// explicitly with Cmd + Q.
-app.on('window-all-closed', () => {
- if (process.platform !== 'darwin') {
- cleanupMouseTracking()
- app.quit()
- mainWindow = null
- }
-})
-
-app.on('activate', () => {
- // On OS X it's common to re-create a window in the app when the
- // dock icon is clicked and there are no other windows open.
- if (BrowserWindow.getAllWindows().length === 0) {
- createWindow()
- }
-})
-
-// Cleanup old recordings on quit (both macOS and other platforms)
-app.on('before-quit', async (event) => {
- event.preventDefault()
- cleanupMouseTracking()
- await cleanupOldRecordings()
- app.exit(0)
-})
+app.on("before-quit", () => {
+ isAppQuitting = true;
+ killWindowsCaptureProcess();
+ showCursor();
+ cleanupNativeVideoExportSessions();
+ void cleanupAllExportStreams();
+});
+
+app.on("window-all-closed", () => {
+ if (IS_SMOKE_EXPORT || process.platform !== "darwin") {
+ app.quit();
+ }
+});
+
+app.on("activate", () => {
+ // On OS X it's common to re-create a window in the app when the
+ // dock icon is clicked and there are no other windows open.
+ focusOrCreateMainWindow();
+});
+
+app.on("second-instance", () => {
+ focusOrCreateMainWindow();
+});
// Register all IPC handlers when app is ready
app.whenReady().then(async () => {
- // Ensure recordings directory exists
- await ensureRecordingsDir()
-
- registerIpcHandlers(
- createEditorWindowWrapper,
- createSourceSelectorWindowWrapper,
- () => mainWindow,
- () => sourceSelectorWindow,
- (recording: boolean, sourceName: string) => {
- selectedSourceName = sourceName
- if (recording) {
- if (!tray) createTray();
- updateTrayMenu();
- if (mainWindow) mainWindow.minimize();
- } else {
- if (tray) {
- tray.destroy();
- tray = null;
- }
- if (mainWindow) mainWindow.restore();
- }
- }
- )
- createWindow()
-})
+ if (process.platform === "win32") {
+ app.setAppUserModelId("dev.recordly.app");
+ }
+
+ session.defaultSession.setPermissionCheckHandler(
+ (webContents, permission, requestingOrigin, details) => {
+ return shouldGrantMediaPermission(
+ {
+ permission,
+ isTrustedCaptureWindow: isHudWebContents(webContents),
+ isMainFrame: details.isMainFrame,
+ currentDocumentUrl: webContents?.getURL() ?? "",
+ // Electron 39 may supply the last committed document URL, including its
+ // query, in the requestingOrigin argument for media checks.
+ requestingUrl: details.requestingUrl ?? requestingOrigin,
+ securityOrigins:
+ details.securityOrigin === undefined ? [] : [details.securityOrigin],
+ },
+ getTrustedCaptureDocumentBaseUrls(),
+ );
+ },
+ );
+
+ session.defaultSession.setPermissionRequestHandler(
+ (webContents, permission, callback, details) => {
+ const securityOrigin = "securityOrigin" in details ? details.securityOrigin : undefined;
+
+ callback(
+ shouldGrantMediaPermission(
+ {
+ permission,
+ isTrustedCaptureWindow: isHudWebContents(webContents),
+ isMainFrame: details.isMainFrame,
+ currentDocumentUrl: webContents.getURL(),
+ requestingUrl: details.requestingUrl,
+ securityOrigins: securityOrigin === undefined ? [] : [securityOrigin],
+ },
+ getTrustedCaptureDocumentBaseUrls(),
+ ),
+ );
+ },
+ );
+
+ // Recordly does not use WebHID, Web Serial, or WebUSB. Do not grant devices by default.
+ session.defaultSession.setDevicePermissionHandler(() => false);
+
+ if (process.platform === "darwin") {
+ const cameraStatus = systemPreferences.getMediaAccessStatus("camera");
+ if (cameraStatus !== "granted") {
+ await systemPreferences.askForMediaAccess("camera");
+ }
+
+ const micStatus = systemPreferences.getMediaAccessStatus("microphone");
+ if (micStatus !== "granted") {
+ await systemPreferences.askForMediaAccess("microphone");
+ }
+ } else if (process.platform === "win32") {
+ const cameraStatus = systemPreferences.getMediaAccessStatus("camera");
+ const micStatus = systemPreferences.getMediaAccessStatus("microphone");
+ if (cameraStatus !== "granted") {
+ console.warn(
+ `[permissions] Camera access is "${cameraStatus}" — webcam may not work. Check Windows Settings > Privacy > Camera.`,
+ );
+ }
+ if (micStatus !== "granted") {
+ console.warn(
+ `[permissions] Microphone access is "${micStatus}" — mic recording may not work. Check Windows Settings > Privacy > Microphone.`,
+ );
+ }
+ }
+
+ ipcMain.on("hud-overlay-close", () => {
+ const hud = getHudOverlayWindow();
+ if (hud) {
+ console.log("[main] Closing HUD window via hud-overlay-close");
+ hud.close();
+ }
+
+ // If this was the last window (or we are in a state where we should quit), do it.
+ // We use a small delay to allow window.close() to propagate.
+ setTimeout(() => {
+ const windows = BrowserWindow.getAllWindows().filter((w) => !w.isDestroyed());
+ if (windows.length === 0) {
+ console.log("[main] No windows left, quitting app");
+ app.quit();
+ }
+ }, 100);
+ });
+ if (process.platform === "darwin" && app.dock) {
+ await app.dock.show();
+ }
+ syncDockIcon();
+ if (shouldUseTray()) {
+ createTray();
+ updateTrayMenu();
+ }
+ setupApplicationMenu();
+ // Ensure recordings directory exists
+ await ensureRecordingsDir();
+
+ if (!VITE_DEV_SERVER_URL) {
+ try {
+ await ensurePackagedRendererServer(RENDERER_DIST);
+ } catch (error) {
+ console.warn("[renderer-server] Failed to start packaged renderer server:", error);
+ }
+ }
+
+ try {
+ await ensureMediaServer();
+ } catch (error) {
+ console.warn("[media-server] Failed to start media server:", error);
+ }
+
+ registerIpcHandlers(
+ createEditorWindowWrapper,
+ createSourceSelectorWindowWrapper,
+ () => mainWindow,
+ () => sourceSelectorWindow,
+ (recording: boolean, sourceName: string) => {
+ selectedSourceName = sourceName;
+ setHudOverlayRecordingActive(recording);
+ if (shouldUseTray()) {
+ if (!tray) createTray();
+ updateTrayMenu(recording);
+ }
+ if (recording) {
+ reassertHudOverlayMouseState();
+ }
+ if (!recording) {
+ restoreWindowSafely(mainWindow);
+ }
+ },
+ );
+
+ if (IS_SMOKE_EXPORT || process.env.RECORDLY_DEV_OPEN_RECORDING_INPUT) {
+ await logSmokeExportGpuDiagnostics();
+ if (IS_SMOKE_EXPORT) {
+ const smokeSource =
+ process.env.RECORDLY_SMOKE_EXPORT_PROJECT ??
+ process.env.RECORDLY_SMOKE_EXPORT_INPUT ??
+ "";
+ console.log(`[smoke-export] Starting editor smoke export for ${smokeSource}`);
+ } else {
+ console.log(
+ `[dev-open-recording] Starting editor for ${process.env.RECORDLY_DEV_OPEN_RECORDING_INPUT}`,
+ );
+ }
+ createEditorWindowWrapper();
+ return;
+ }
+
+ createWindow();
+ setupAutoUpdates(getUpdateDialogWindow, sendUpdateToastToWindows);
+ if (IS_DEV && process.env.RECORDLY_DEV_PREVIEW_UPDATE === "1") {
+ setTimeout(() => {
+ previewUpdateToast(sendUpdateToastToWindows);
+ }, 750);
+ }
+
+ // Register the display media handler so that renderer's getDisplayMedia()
+ // calls land on the pre-selected source without showing a system picker.
+ //
+ // IMPORTANT: The callback must receive a plain { id, name } Video object.
+ // Passing the full DesktopCapturerSource (with thumbnail, appIcon, etc.)
+ // via an unsafe cast breaks Electron's internal cursor-constraint
+ // propagation and causes cursor: 'never' from the renderer to be silently
+ // ignored by the native capture pipeline.
+ session.defaultSession.setDisplayMediaRequestHandler(async (request, callback) => {
+ try {
+ const frame = request.frame;
+ const isLiveFrame = Boolean(frame && !frame.isDestroyed());
+ const requestingWebContents =
+ isLiveFrame && frame ? electronWebContents.fromFrame(frame) : undefined;
+ const isHudMainFrame = Boolean(
+ isLiveFrame &&
+ requestingWebContents &&
+ isHudWebContents(requestingWebContents) &&
+ frame === requestingWebContents.mainFrame,
+ );
+
+ if (
+ !shouldGrantDisplayCapture(
+ {
+ isTrustedCaptureWindow: isHudMainFrame,
+ isMainFrame: Boolean(isLiveFrame && frame?.parent === null),
+ currentDocumentUrl: isLiveFrame ? (frame?.url ?? "") : "",
+ securityOrigin: request.securityOrigin,
+ videoRequested: request.videoRequested,
+ },
+ getTrustedCaptureDocumentBaseUrls(),
+ )
+ ) {
+ callback({});
+ return;
+ }
+
+ const sourceId = getSelectedSourceId();
+ // On Linux/Wayland, calling desktopCapturer.getSources() itself
+ // invokes the xdg-desktop-portal picker. If we then return one of
+ // those sources, Chromium triggers a SECOND portal because the
+ // pre-enumerated source IDs are stale on Wayland. To collapse this
+ // into a single portal invocation, when the Linux portal sentinel
+ // is set we skip getSources entirely and hand back a synthetic
+ // source id; Chromium then opens the portal once to actually
+ // resolve the capture.
+ // Default to the sentinel on Linux when no source has been
+ // pre-selected (e.g. fresh session where the renderer skipped the
+ // source picker entirely). This avoids calling getSources() which
+ // would itself trigger an extra portal dialog.
+ const isLinuxPortalSentinel =
+ process.platform === "linux" && (sourceId === "screen:linux-portal" || !sourceId);
+ if (isLinuxPortalSentinel) {
+ callback({ video: { id: "screen:0:0", name: "Entire screen" } });
+ return;
+ }
+ const sources = await desktopCapturer.getSources({ types: ["screen", "window"] });
+ const source = sourceId
+ ? (sources.find((s) => s.id === sourceId) ?? sources[0])
+ : sources[0];
+ if (source) {
+ callback({
+ video: { id: source.id, name: source.name },
+ });
+ } else {
+ callback({});
+ }
+ } catch (error) {
+ console.error("setDisplayMediaRequestHandler error:", error);
+ callback({});
+ }
+ });
+
+ const currentToastPayload = getCurrentUpdateToastPayload();
+ if (currentToastPayload) {
+ sendUpdateToastToWindows("update-toast-state", currentToastPayload);
+ }
+});
diff --git a/electron/mainCjsNormalize.test.mjs b/electron/mainCjsNormalize.test.mjs
new file mode 100644
index 000000000..9ccf91da7
--- /dev/null
+++ b/electron/mainCjsNormalize.test.mjs
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+ findElectronMainCjsEsmSyntax,
+ normalizeElectronMainCjsSource,
+} from "../scripts/normalize-electron-main-cjs.mjs";
+
+describe("Electron main CJS normalizer", () => {
+ it("converts Rollup named export blocks to CommonJS assignments", () => {
+ const source = [
+ 'const MAIN_DIST = "dist-electron";',
+ 'const RENDERER_DIST = "dist";',
+ "const VITE_DEV_SERVER_URL = process.env.VITE_DEV_SERVER_URL;",
+ "export {",
+ " MAIN_DIST,",
+ " RENDERER_DIST,",
+ " VITE_DEV_SERVER_URL",
+ "};",
+ ].join("\n");
+
+ const result = normalizeElectronMainCjsSource(source);
+
+ expect(result.changed).toBe(true);
+ expect(result.source).toContain("exports.MAIN_DIST = MAIN_DIST;");
+ expect(result.source).toContain("exports.RENDERER_DIST = RENDERER_DIST;");
+ expect(result.source).toContain("exports.VITE_DEV_SERVER_URL = VITE_DEV_SERVER_URL;");
+ expect(findElectronMainCjsEsmSyntax(result.source)).toEqual([]);
+ });
+
+ it("converts single-line aliased named exports to CommonJS assignments", () => {
+ const source = "export { VITE_DEV_SERVER_URL as devServerUrl };";
+
+ const result = normalizeElectronMainCjsSource(source);
+
+ expect(result.changed).toBe(true);
+ expect(result.source).toBe("exports.devServerUrl = VITE_DEV_SERVER_URL;");
+ expect(findElectronMainCjsEsmSyntax(result.source)).toEqual([]);
+ });
+
+ it("reports unsupported ESM export syntax that cannot be normalized safely", () => {
+ const source = "export default MAIN_DIST;";
+
+ expect(findElectronMainCjsEsmSyntax(source)).toEqual([
+ { line: 1, text: "export default MAIN_DIST;" },
+ ]);
+ });
+
+ it("preserves an unsupported export block exactly while normalizing other syntax", () => {
+ const source = [
+ 'import fs from "node:fs";',
+ "export {",
+ ' MAIN_DIST as "main-dist",',
+ "};",
+ ].join("\n");
+
+ const result = normalizeElectronMainCjsSource(source);
+
+ expect(result.changed).toBe(true);
+ expect(result.source).toBe(
+ [
+ 'const fs = require("node:fs");',
+ "export {",
+ ' MAIN_DIST as "main-dist",',
+ "};",
+ ].join("\n"),
+ );
+ expect(findElectronMainCjsEsmSyntax(result.source)).toEqual([
+ { line: 2, text: "export {" },
+ ]);
+ });
+});
diff --git a/electron/mediaServer.test.ts b/electron/mediaServer.test.ts
new file mode 100644
index 000000000..cf6cd01ba
--- /dev/null
+++ b/electron/mediaServer.test.ts
@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("media server path policy", () => {
+ let tempRoot: string;
+ let appDataPath: string;
+ let userDataPath: string;
+ let tempPath: string;
+ let appPath: string;
+
+ beforeEach(async () => {
+ tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "recordly-media-server-"));
+ appDataPath = path.join(tempRoot, "AppData");
+ userDataPath = path.join(tempRoot, "UserData");
+ tempPath = path.join(tempRoot, "Temp");
+ appPath = path.join(tempRoot, "App");
+
+ await Promise.all(
+ [appDataPath, userDataPath, tempPath, appPath].map((dirPath) =>
+ fs.mkdir(dirPath, { recursive: true }),
+ ),
+ );
+
+ vi.resetModules();
+ vi.doMock("electron", () => ({
+ app: {
+ isPackaged: false,
+ getAppPath: () => appPath,
+ getPath: (name: string) => {
+ if (name === "appData") return appDataPath;
+ if (name === "userData") return userDataPath;
+ if (name === "temp") return tempPath;
+ return tempRoot;
+ },
+ setPath: () => undefined,
+ },
+ }));
+ });
+
+ afterEach(async () => {
+ vi.resetModules();
+ vi.doUnmock("electron");
+ if (tempRoot) {
+ await fs.rm(tempRoot, { recursive: true, force: true });
+ }
+ });
+
+ it("rejects existing media files outside the session directories until they are approved", async () => {
+ const downloadsPath = path.join(tempRoot, "Downloads");
+ const videoPath = path.join(downloadsPath, "personal-video.mp4");
+ await fs.mkdir(downloadsPath, { recursive: true });
+ await fs.writeFile(videoPath, "test-video");
+
+ const { isAllowedMediaPath } = await import("./mediaServer");
+ const { rememberApprovedLocalReadPath } = await import("./ipc/project/manager");
+
+ expect(isAllowedMediaPath(videoPath)).toBe(false);
+
+ await rememberApprovedLocalReadPath(videoPath);
+
+ expect(isAllowedMediaPath(videoPath)).toBe(true);
+ });
+
+ it("rejects missing media files outside the allowed directories", async () => {
+ const missingPath = path.join(tempRoot, "Downloads", "missing.mp4");
+ const { isAllowedMediaPath } = await import("./mediaServer");
+
+ expect(isAllowedMediaPath(missingPath)).toBe(false);
+ });
+});
+
+describe("resolveHttpByteRange", () => {
+ it("rejects malformed and multi-range headers", async () => {
+ const { resolveHttpByteRange } = await import("./mediaServer");
+
+ expect(resolveHttpByteRange("bytes=0-1,2-3", 100)).toBeNull();
+ expect(resolveHttpByteRange("bytes=0-1foo", 100)).toBeNull();
+ });
+
+ it("clamps oversized explicit end offsets to EOF", async () => {
+ const { resolveHttpByteRange } = await import("./mediaServer");
+
+ expect(resolveHttpByteRange("bytes=0-9999999999", 3_221_225_472)).toEqual({
+ start: 0,
+ end: 3_221_225_471,
+ });
+ });
+
+ it("rejects ranges that start beyond EOF", async () => {
+ const { resolveHttpByteRange } = await import("./mediaServer");
+
+ expect(resolveHttpByteRange("bytes=500-999", 500)).toBeNull();
+ });
+
+ it("preserves suffix range semantics", async () => {
+ const { resolveHttpByteRange } = await import("./mediaServer");
+
+ expect(resolveHttpByteRange("bytes=-500", 1_000)).toEqual({
+ start: 500,
+ end: 999,
+ });
+ });
+});
diff --git a/electron/mediaServer.ts b/electron/mediaServer.ts
new file mode 100644
index 000000000..c979a84e8
--- /dev/null
+++ b/electron/mediaServer.ts
@@ -0,0 +1,237 @@
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import path from "node:path";
+import { approvedLocalReadPaths } from "./ipc/state";
+import { getMediaContentType } from "./mediaTypes";
+
+let mediaServerBaseUrl: string | null = null;
+let mediaServerStartPromise: Promise | null = null;
+
+export function resolveHttpByteRange(
+ rangeHeader: string,
+ fileSize: number,
+): { start: number; end: number } | null {
+ const match = rangeHeader.trim().match(/^bytes=(\d*)-(\d*)$/);
+ if (!match || (!match[1] && !match[2])) {
+ return null;
+ }
+
+ if (fileSize === 0) {
+ return null;
+ }
+
+ if (!match[1] && match[2]) {
+ // Suffix range: bytes=-500
+ const suffixLength = Number.parseInt(match[2], 10);
+ if (Number.isNaN(suffixLength) || suffixLength <= 0) {
+ return null;
+ }
+
+ return {
+ start: Math.max(0, fileSize - suffixLength),
+ end: fileSize - 1,
+ };
+ }
+
+ const start = Number.parseInt(match[1], 10);
+ if (Number.isNaN(start) || start < 0 || start >= fileSize) {
+ return null;
+ }
+
+ const requestedEnd = match[2] ? Number.parseInt(match[2], 10) : fileSize - 1;
+ if (Number.isNaN(requestedEnd) || requestedEnd < start) {
+ return null;
+ }
+
+ return {
+ start,
+ end: Math.min(requestedEnd, fileSize - 1),
+ };
+}
+
+async function resolveRealPath(filePath: string): Promise {
+ try {
+ return await fs.realpath(path.resolve(filePath));
+ } catch {
+ return null;
+ }
+}
+
+export function isAllowedMediaPath(realPath: string): boolean {
+ return approvedLocalReadPaths.has(realPath);
+}
+
+async function handleMediaRequest(
+ request: IncomingMessage,
+ response: ServerResponse,
+): Promise {
+ try {
+ const url = new URL(request.url ?? "/", "http://127.0.0.1");
+
+ if (url.pathname !== "/video") {
+ response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Not Found");
+ return;
+ }
+
+ const rawPath = url.searchParams.get("path");
+ if (!rawPath) {
+ response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Missing path parameter");
+ return;
+ }
+
+ const resolvedPath = await resolveRealPath(rawPath);
+ if (!resolvedPath || !isAllowedMediaPath(resolvedPath)) {
+ console.warn(`[media-server] Blocked access to unapproved path: ${rawPath}`);
+ response.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Forbidden");
+ return;
+ }
+
+ const stat = await fs.stat(resolvedPath);
+ if (!stat.isFile()) {
+ response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Not Found");
+ return;
+ }
+
+ const contentType = getMediaContentType(resolvedPath);
+ const fileSize = stat.size;
+ const rangeHeader = request.headers.range;
+
+ const corsHeaders = {
+ "Access-Control-Allow-Origin": "*",
+ "Access-Control-Allow-Credentials": "false",
+ "Access-Control-Expose-Headers": "Content-Range, Content-Length, Accept-Ranges",
+ };
+
+ if (request.method === "OPTIONS") {
+ response.writeHead(204, {
+ ...corsHeaders,
+ "Access-Control-Allow-Methods": "GET, HEAD, OPTIONS",
+ "Access-Control-Allow-Headers": "Range",
+ });
+ response.end();
+ return;
+ }
+
+ if (rangeHeader) {
+ if (fileSize === 0) {
+ response.writeHead(416, { ...corsHeaders, "Content-Range": `bytes */0` });
+ response.end();
+ return;
+ }
+
+ const byteRange = resolveHttpByteRange(rangeHeader, fileSize);
+ if (!byteRange) {
+ response.writeHead(416, { ...corsHeaders, "Content-Range": `bytes */${fileSize}` });
+ response.end();
+ return;
+ }
+
+ const { start, end } = byteRange;
+
+ const chunkSize = end - start + 1;
+ response.writeHead(206, {
+ ...corsHeaders,
+ "Content-Range": `bytes ${start}-${end}/${fileSize}`,
+ "Accept-Ranges": "bytes",
+ "Content-Length": String(chunkSize),
+ "Content-Type": contentType,
+ "Cache-Control": "no-cache",
+ });
+
+ if (request.method === "HEAD") {
+ response.end();
+ return;
+ }
+
+ const stream = createReadStream(resolvedPath, { start, end });
+ stream.pipe(response);
+ stream.on("error", () => {
+ if (!response.headersSent) {
+ response.writeHead(500, { "Content-Type": "text/plain" });
+ }
+ response.end();
+ });
+ } else {
+ response.writeHead(200, {
+ ...corsHeaders,
+ "Accept-Ranges": "bytes",
+ "Content-Length": String(fileSize),
+ "Content-Type": contentType,
+ "Cache-Control": "no-cache",
+ });
+
+ if (request.method === "HEAD") {
+ response.end();
+ return;
+ }
+
+ const stream = createReadStream(resolvedPath);
+ stream.pipe(response);
+ stream.on("error", () => {
+ if (!response.headersSent) {
+ response.writeHead(500, { "Content-Type": "text/plain" });
+ }
+ response.end();
+ });
+ }
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
+ response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Not Found");
+ return;
+ }
+
+ console.error("[media-server] Error handling request:", error);
+ response.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+ response.end("Internal Server Error");
+ }
+}
+
+export function getMediaServerBaseUrl(): string | null {
+ return mediaServerBaseUrl;
+}
+
+export async function ensureMediaServer(): Promise {
+ if (mediaServerBaseUrl) {
+ return mediaServerBaseUrl;
+ }
+
+ if (mediaServerStartPromise) {
+ return mediaServerStartPromise;
+ }
+
+ mediaServerStartPromise = new Promise((resolve, reject) => {
+ const server = createServer((request, response) => {
+ void handleMediaRequest(request, response);
+ });
+
+ server.once("error", (error) => {
+ reject(error);
+ });
+
+ server.listen(0, "127.0.0.1", () => {
+ const address = server.address();
+ if (!address || typeof address === "string") {
+ server.close();
+ reject(new Error("Media server did not expose a TCP address"));
+ return;
+ }
+
+ mediaServerBaseUrl = `http://127.0.0.1:${address.port}`;
+ console.log(`[media-server] Listening at ${mediaServerBaseUrl}`);
+ resolve(mediaServerBaseUrl);
+ });
+ });
+
+ return mediaServerStartPromise;
+}
+
+export function buildMediaUrl(baseUrl: string, filePath: string): string {
+ const resolved = path.resolve(filePath);
+ return `${baseUrl}/video?path=${encodeURIComponent(resolved)}`;
+}
diff --git a/electron/mediaTypes.ts b/electron/mediaTypes.ts
new file mode 100644
index 000000000..5c4307b63
--- /dev/null
+++ b/electron/mediaTypes.ts
@@ -0,0 +1,23 @@
+import path from "node:path";
+
+export const MEDIA_CONTENT_TYPES: Record = {
+ ".mp4": "video/mp4",
+ ".webm": "video/webm",
+ ".mov": "video/quicktime",
+ ".mkv": "video/x-matroska",
+ ".avi": "video/x-msvideo",
+ ".wav": "audio/wav",
+ ".mp3": "audio/mpeg",
+ ".ogg": "audio/ogg",
+ ".png": "image/png",
+ ".jpg": "image/jpeg",
+ ".jpeg": "image/jpeg",
+};
+
+export function getMediaContentType(filePath: string): string {
+ return MEDIA_CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+
+export function isSupportedLocalMediaPath(filePath: string): boolean {
+ return path.extname(filePath).toLowerCase() in MEDIA_CONTENT_TYPES;
+}
diff --git a/electron/native/NativeCursorMonitor.swift b/electron/native/NativeCursorMonitor.swift
new file mode 100644
index 000000000..18c644150
--- /dev/null
+++ b/electron/native/NativeCursorMonitor.swift
@@ -0,0 +1,505 @@
+import Foundation
+import AppKit
+import ApplicationServices
+
+// Force AppKit initialization so cursor images are populated in CLI context
+let _ = NSApplication.shared
+
+func knownCursorCandidates() -> [(String, NSCursor)] {
+ var candidates: [(String, NSCursor)] = [
+ ("arrow", .arrow),
+ ("text", .iBeam),
+ ("pointer", .pointingHand),
+ ("pointer", .dragCopy),
+ ("pointer", .dragLink),
+ ("pointer", .contextualMenu),
+ ("crosshair", .crosshair),
+ ("open-hand", .openHand),
+ ("closed-hand", .closedHand),
+ ("resize-ew", .resizeLeft),
+ ("resize-ew", .resizeRight),
+ ("resize-ew", .resizeLeftRight),
+ ("resize-ns", .resizeUp),
+ ("resize-ns", .resizeDown),
+ ("resize-ns", .resizeUpDown),
+ ("not-allowed", .operationNotAllowed),
+ ]
+
+ if #available(macOS 10.13, *) {
+ candidates.append(("text", .iBeamCursorForVerticalLayout))
+ }
+
+ return candidates
+}
+
+let signatureAcceptanceThreshold = 12000
+let relaxedSignatureAcceptanceThresholds: [String: Int] = [
+ "text": 28000,
+ "crosshair": 32000,
+]
+let strictSignatureAcceptanceThresholds: [String: Int] = [
+ "open-hand": 3200,
+ "closed-hand": 3200,
+]
+
+let systemWideElement = AXUIElementCreateSystemWide()
+let totalScreenHeight = NSScreen.screens.reduce(CGFloat(0)) { max($0, $1.frame.maxY) }
+let axEditableAttribute = "AXEditable"
+let axLinkRole = "AXLink"
+
+struct CursorSignature {
+ let aspectRatio: Double
+ let hotspotXRatio: Double
+ let hotspotYRatio: Double
+ let shapeSamples: [UInt8]
+}
+
+func signature(for cursor: NSCursor, sampleSize: Int = 32) -> CursorSignature? {
+ let image = cursor.image
+ let sourceSize = image.size
+ guard sourceSize.width > 0, sourceSize.height > 0 else {
+ return nil
+ }
+
+ guard let bitmap = NSBitmapImageRep(
+ bitmapDataPlanes: nil,
+ pixelsWide: sampleSize,
+ pixelsHigh: sampleSize,
+ bitsPerSample: 8,
+ samplesPerPixel: 4,
+ hasAlpha: true,
+ isPlanar: false,
+ colorSpaceName: .deviceRGB,
+ bytesPerRow: 0,
+ bitsPerPixel: 0
+ ) else {
+ return nil
+ }
+
+ bitmap.size = NSSize(width: sampleSize, height: sampleSize)
+
+ NSGraphicsContext.saveGraphicsState()
+ guard let context = NSGraphicsContext(bitmapImageRep: bitmap) else {
+ NSGraphicsContext.restoreGraphicsState()
+ return nil
+ }
+
+ NSGraphicsContext.current = context
+ context.imageInterpolation = .high
+
+ let scale = min(CGFloat(sampleSize) / sourceSize.width, CGFloat(sampleSize) / sourceSize.height)
+ let drawWidth = sourceSize.width * scale
+ let drawHeight = sourceSize.height * scale
+ let drawRect = NSRect(
+ x: (CGFloat(sampleSize) - drawWidth) / 2,
+ y: (CGFloat(sampleSize) - drawHeight) / 2,
+ width: drawWidth,
+ height: drawHeight
+ )
+
+ image.draw(in: drawRect, from: .zero, operation: .copy, fraction: 1)
+ context.flushGraphics()
+ NSGraphicsContext.restoreGraphicsState()
+
+ guard let data = bitmap.bitmapData else {
+ return nil
+ }
+
+ var alphaSamples: [UInt8] = []
+ alphaSamples.reserveCapacity(sampleSize * sampleSize)
+ let bytesPerRow = bitmap.bytesPerRow
+
+ for y in 0.. 24 ? 255 : 0)
+ }
+ }
+
+ let hotspot = cursor.hotSpot
+ return CursorSignature(
+ aspectRatio: Double(sourceSize.width / max(1, sourceSize.height)),
+ hotspotXRatio: Double(hotspot.x / max(1, sourceSize.width)),
+ hotspotYRatio: Double(hotspot.y / max(1, sourceSize.height)),
+ shapeSamples: alphaSamples
+ )
+}
+
+func signatureScore(_ lhs: CursorSignature, _ rhs: CursorSignature) -> Int {
+ let count = min(lhs.shapeSamples.count, rhs.shapeSamples.count)
+ var imageDifference = 0
+ for index in 0.. String? {
+ var value: CFTypeRef?
+ let error = AXUIElementCopyAttributeValue(element, attribute as CFString, &value)
+ guard error == .success else {
+ return nil
+ }
+
+ return value as? String
+}
+
+func attributeBool(_ element: AXUIElement, _ attribute: String) -> Bool? {
+ var value: CFTypeRef?
+ let error = AXUIElementCopyAttributeValue(element, attribute as CFString, &value)
+ guard error == .success else {
+ return nil
+ }
+
+ return value as? Bool
+}
+
+func actionNames(_ element: AXUIElement) -> [String] {
+ var names: CFArray?
+ let error = AXUIElementCopyActionNames(element, &names)
+ guard error == .success, let actions = names as? [String] else {
+ return []
+ }
+
+ return actions
+}
+
+func currentElement() -> AXUIElement? {
+ guard let location = CGEvent(source: nil)?.location else {
+ return nil
+ }
+
+ var element: AXUIElement?
+ let y = totalScreenHeight > 0 ? totalScreenHeight - location.y : location.y
+ let error = AXUIElementCopyElementAtPosition(systemWideElement, Float(location.x), Float(y), &element)
+ guard error == .success else {
+ return nil
+ }
+
+ return element
+}
+
+func focusedElement() -> AXUIElement? {
+ var value: CFTypeRef?
+ let error = AXUIElementCopyAttributeValue(systemWideElement, kAXFocusedUIElementAttribute as CFString, &value)
+ guard error == .success, let value else {
+ return nil
+ }
+
+ return unsafeBitCast(value, to: AXUIElement.self)
+}
+
+func parentElement(of element: AXUIElement) -> AXUIElement? {
+ var value: CFTypeRef?
+ let error = AXUIElementCopyAttributeValue(element, kAXParentAttribute as CFString, &value)
+ guard error == .success, let value else {
+ return nil
+ }
+
+ return unsafeBitCast(value, to: AXUIElement.self)
+}
+
+func hasAttribute(_ element: AXUIElement, _ attribute: String) -> Bool {
+ var value: CFTypeRef?
+ return AXUIElementCopyAttributeValue(element, attribute as CFString, &value) == .success
+}
+
+func ancestorChain(startingAt element: AXUIElement?, maxDepth: Int = 4) -> [AXUIElement] {
+ guard let element else {
+ return []
+ }
+
+ var elements: [AXUIElement] = [element]
+ var current = element
+ var depth = 0
+
+ while depth < maxDepth, let parent = parentElement(of: current) {
+ elements.append(parent)
+ current = parent
+ depth += 1
+ }
+
+ return elements
+}
+
+func metadataString(for element: AXUIElement) -> String {
+ return [
+ attributeString(element, kAXRoleAttribute),
+ attributeString(element, kAXSubroleAttribute),
+ attributeString(element, kAXRoleDescriptionAttribute),
+ attributeString(element, kAXDescriptionAttribute),
+ attributeString(element, kAXHelpAttribute),
+ attributeString(element, kAXTitleAttribute),
+ ]
+ .compactMap { $0?.lowercased() }
+ .joined(separator: " ")
+}
+
+func elementLooksTextual(_ element: AXUIElement) -> Bool {
+ let role = attributeString(element, kAXRoleAttribute)
+ let subrole = attributeString(element, kAXSubroleAttribute)
+ let editable = attributeBool(element, axEditableAttribute)
+ let metadata = metadataString(for: element)
+ let actions = actionNames(element)
+
+ let textRoles: Set = [
+ kAXTextFieldRole as String,
+ kAXTextAreaRole as String,
+ kAXComboBoxRole as String,
+ kAXSearchFieldSubrole as String,
+ ]
+
+ if editable == true || textRoles.contains(role ?? "") || textRoles.contains(subrole ?? "") {
+ return true
+ }
+
+ if metadata.contains("text field")
+ || metadata.contains("search field")
+ || metadata.contains("editor")
+ || metadata.contains("insertion point")
+ || metadata.contains("caret")
+ || metadata.contains("source editor") {
+ return true
+ }
+
+ return hasAttribute(element, kAXSelectedTextRangeAttribute as String)
+ || hasAttribute(element, kAXNumberOfCharactersAttribute as String)
+ || (actions.contains(kAXPressAction as String) && metadata.contains("text"))
+}
+
+func accessibilityCursorMatch() -> String? {
+ let hoveredChain = ancestorChain(startingAt: currentElement())
+ let focusedChain = ancestorChain(startingAt: focusedElement())
+
+ for element in hoveredChain + focusedChain {
+ if elementLooksTextual(element) {
+ return "text"
+ }
+ }
+
+ guard let element = hoveredChain.first else {
+ return nil
+ }
+
+ let role = attributeString(element, kAXRoleAttribute)
+ let enabled = attributeBool(element, kAXEnabledAttribute)
+ let actions = actionNames(element)
+ let metadata = hoveredChain
+ .map { metadataString(for: $0) }
+ .filter { !$0.isEmpty }
+ .joined(separator: " ")
+ if metadata.contains("crosshair") || metadata.contains("cross hair") || metadata.contains("precision") || metadata.contains("crop") {
+ return "crosshair"
+ }
+
+ if role == kAXSplitterRole as String {
+ return "resize-ew"
+ }
+
+ let pressableRoles: Set = [
+ kAXButtonRole as String,
+ axLinkRole,
+ kAXMenuItemRole as String,
+ kAXPopUpButtonRole as String,
+ kAXRadioButtonRole as String,
+ kAXCheckBoxRole as String,
+ kAXTabGroupRole as String,
+ ]
+ let hasPressAction = actions.contains(kAXPressAction as String)
+ if enabled == false && (hasPressAction || pressableRoles.contains(role ?? "")) {
+ return "not-allowed"
+ }
+ if hasPressAction || pressableRoles.contains(role ?? "") {
+ return "pointer"
+ }
+
+ return nil
+}
+
+func currentSystemCursorType() -> String {
+ let resolvedCursor: NSCursor? = DispatchQueue.main.sync {
+ if #available(macOS 14.0, *) {
+ return NSCursor.currentSystem ?? NSCursor.current
+ }
+
+ return NSCursor.current
+ }
+
+ guard let resolvedCursor else {
+ return accessibilityCursorMatch() ?? "arrow"
+ }
+
+ guard let currentSignature = signature(for: resolvedCursor) else {
+ return accessibilityCursorMatch() ?? "arrow"
+ }
+
+ guard let bestMatch = knownCursorSignatures.min(by: { lhs, rhs in
+ signatureScore(currentSignature, lhs.1) < signatureScore(currentSignature, rhs.1)
+ }) else {
+ return accessibilityCursorMatch() ?? "arrow"
+ }
+
+ let bestScore = signatureScore(currentSignature, bestMatch.1)
+ let primaryThreshold = strictSignatureAcceptanceThresholds[bestMatch.0] ?? signatureAcceptanceThreshold
+ let matchedCursorType: String
+ if bestScore > primaryThreshold {
+ if let relaxedThreshold = relaxedSignatureAcceptanceThresholds[bestMatch.0], bestScore <= relaxedThreshold {
+ matchedCursorType = bestMatch.0
+ } else {
+ matchedCursorType = "arrow"
+ }
+ } else {
+ matchedCursorType = bestMatch.0
+ }
+
+ return matchedCursorType
+}
+
+func exportCursorImages() {
+ let cursorForType: [(String, NSCursor)] = [
+ ("arrow", .arrow),
+ ("text", .iBeam),
+ ("pointer", .pointingHand),
+ ("crosshair", .crosshair),
+ ("open-hand", .openHand),
+ ("closed-hand", .closedHand),
+ ("resize-ew", .resizeLeftRight),
+ ("resize-ns", .resizeUpDown),
+ ("not-allowed", .operationNotAllowed),
+ ]
+
+ for (name, cursor) in cursorForType {
+ let image = cursor.image
+ let hotspot = cursor.hotSpot
+ let size = image.size
+ guard size.width > 0, size.height > 0 else { continue }
+
+ guard let tiffData = image.tiffRepresentation,
+ let bitmapRep = NSBitmapImageRep(data: tiffData),
+ let pngData = bitmapRep.representation(using: .png, properties: [:]) else {
+ continue
+ }
+
+ let base64 = pngData.base64EncodedString()
+ let hotspotXRatio = hotspot.x / size.width
+ let hotspotYRatio = hotspot.y / size.height
+ let aspectRatio = size.width / size.height
+ print("CURSOR_IMAGE:\(name):\(hotspotXRatio):\(hotspotYRatio):\(aspectRatio):\(base64)")
+ fflush(stdout)
+ }
+}
+
+if CommandLine.arguments.contains("--export-images") {
+ exportCursorImages()
+ exit(0)
+}
+
+func mouseInteractionCallback(
+ proxy: CGEventTapProxy,
+ type: CGEventType,
+ event: CGEvent,
+ refcon: UnsafeMutableRawPointer?
+) -> Unmanaged? {
+ let action: String
+ let button: Int
+ switch type {
+ case .leftMouseDown:
+ action = "mousedown"
+ button = 1
+ case .leftMouseUp:
+ action = "mouseup"
+ button = 1
+ case .rightMouseDown:
+ action = "mousedown"
+ button = 2
+ case .rightMouseUp:
+ action = "mouseup"
+ button = 2
+ case .otherMouseDown:
+ guard event.getIntegerValueField(.mouseEventButtonNumber) == 2 else {
+ return Unmanaged.passUnretained(event)
+ }
+ action = "mousedown"
+ button = 3
+ case .otherMouseUp:
+ guard event.getIntegerValueField(.mouseEventButtonNumber) == 2 else {
+ return Unmanaged.passUnretained(event)
+ }
+ action = "mouseup"
+ button = 3
+ default:
+ return Unmanaged.passUnretained(event)
+ }
+
+ print("INTERACTION:\(action):\(button)")
+ fflush(stdout)
+ return Unmanaged.passUnretained(event)
+}
+
+let mouseEventTypes: [CGEventType] = [
+ .leftMouseDown,
+ .leftMouseUp,
+ .rightMouseDown,
+ .rightMouseUp,
+ .otherMouseDown,
+ .otherMouseUp,
+]
+let mouseEventMask = mouseEventTypes.reduce(CGEventMask(0)) { mask, type in
+ mask | (CGEventMask(1) << type.rawValue)
+}
+let mouseEventTap = CGEvent.tapCreate(
+ tap: .cgSessionEventTap,
+ place: .headInsertEventTap,
+ options: .listenOnly,
+ eventsOfInterest: mouseEventMask,
+ callback: mouseInteractionCallback,
+ userInfo: nil
+)
+if let mouseEventTap,
+ let eventTapSource = CFMachPortCreateRunLoopSource(kCFAllocatorDefault, mouseEventTap, 0) {
+ CFRunLoopAddSource(CFRunLoopGetMain(), eventTapSource, .commonModes)
+ CGEvent.tapEnable(tap: mouseEventTap, enable: true)
+} else {
+ fputs("Mouse interaction event tap unavailable; click telemetry disabled\n", stderr)
+ fflush(stderr)
+}
+
+var lastState = ""
+func emitStateIfNeeded() {
+ let state = currentSystemCursorType()
+ if state != lastState {
+ lastState = state
+ print("STATE:\(state)")
+ fflush(stdout)
+ }
+}
+
+let timer = DispatchSource.makeTimerSource(queue: DispatchQueue.global(qos: .utility))
+timer.schedule(deadline: .now(), repeating: .milliseconds(50))
+timer.setEventHandler {
+ emitStateIfNeeded()
+}
+timer.resume()
+
+DispatchQueue.global(qos: .utility).async {
+ while let line = readLine(strippingNewline: true)?.lowercased() {
+ if line == "stop" {
+ exit(0)
+ }
+ }
+ exit(0)
+}
+
+RunLoop.main.run()
diff --git a/electron/native/ScreenCaptureKitRecorder.swift b/electron/native/ScreenCaptureKitRecorder.swift
new file mode 100644
index 000000000..29253a753
--- /dev/null
+++ b/electron/native/ScreenCaptureKitRecorder.swift
@@ -0,0 +1,934 @@
+import Foundation
+import ScreenCaptureKit
+import AVFoundation
+import CoreGraphics
+
+struct CaptureConfig: Codable {
+ let fps: Int?
+ let displayId: CGDirectDisplayID?
+ let windowId: UInt32?
+ let outputPath: String?
+ let capturesSystemAudio: Bool?
+ let capturesMicrophone: Bool?
+ let systemAudioOutputPath: String?
+ let microphoneDeviceId: String?
+ let microphoneLabel: String?
+ let microphoneOutputPath: String?
+}
+
+let targetCaptureFPS = 60
+let maxInlineAudioTailExtension = CMTime(seconds: 2.0, preferredTimescale: 600)
+/// How long finalization waits for a backed-up encoder queue before giving up on
+/// the optional tail frame: 100 polls x 10 ms = 1 s.
+let writerReadinessPollAttempts = 100
+let writerReadinessPollInterval: UInt64 = 10_000_000
+
+final class ScreenCaptureRecorder: NSObject, SCStreamOutput, SCStreamDelegate {
+ private struct CaptureFinalizationResult {
+ let outputResult: Result
+ let interactiveStopParticipated: Bool
+ }
+
+ private let queue = DispatchQueue(label: "recordly.screencapturekit.video")
+ private var assetWriter: AVAssetWriter?
+ private var videoInput: AVAssetWriterInput?
+ private var systemAudioWriter: AVAssetWriter?
+ private var systemAudioInput: AVAssetWriterInput?
+ private var microphoneOnlyWriter: AVAssetWriter?
+ private var microphoneOnlyInput: AVAssetWriterInput?
+ private var stream: SCStream?
+ private var firstSampleTime: CMTime = .zero
+ private var firstSystemAudioSampleTime: CMTime?
+ private var firstMicrophoneSampleTime: CMTime?
+ private var lastSystemAudioPresentationTime: CMTime = .invalid
+ private var lastMicrophonePresentationTime: CMTime = .invalid
+ private var lastSampleBuffer: CMSampleBuffer?
+ private var lastVideoPresentationTime: CMTime = .zero
+ private var lastVideoDuration: CMTime = .zero
+ private var lastInlineAudioPresentationTime: CMTime = .invalid
+ private var lastInlineAudioDuration: CMTime = .zero
+ private var isRecording = false
+ private var isPaused = false
+ private var pauseStartedHostTime: CMTime?
+ private var pendingResumeAdjustment = false
+ private var accumulatedPausedDuration: CMTime = .zero
+ private var sessionStarted = false
+ private var frameCount = 0
+ private var outputURL: URL?
+ private var microphoneOutputURL: URL?
+ private var trackedWindowId: UInt32?
+ private var windowValidationTask: Task?
+ private var isFinalizing = false
+ private var interactiveStopParticipated = false
+ private var finalizationWaiters: [CheckedContinuation] = []
+ private var inlineAudioInput: AVAssetWriterInput?
+ private var firstInlineAudioSampleTime: CMTime?
+ private var capturesSystemAudio = false
+ private var capturesMicrophone = false
+ private var writesSystemAudioToSeparateTrack = false
+ private var writesMicrophoneToSeparateTrack = false
+
+ private let microphoneOutputTypeRawValue = 2
+
+ func startCapture(configJSON: String) async throws {
+ guard !isRecording else {
+ throw NSError(domain: "RecordlyCapture", code: 1, userInfo: [NSLocalizedDescriptionKey: "Recording is already in progress"])
+ }
+
+ guard let data = configJSON.data(using: .utf8) else {
+ throw NSError(domain: "RecordlyCapture", code: 2, userInfo: [NSLocalizedDescriptionKey: "Invalid JSON input"])
+ }
+
+ let config = try JSONDecoder().decode(CaptureConfig.self, from: data)
+ let availableContent = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+ let streamConfig = SCStreamConfiguration()
+ capturesSystemAudio = config.capturesSystemAudio ?? false
+ capturesMicrophone = config.capturesMicrophone ?? false
+ if capturesMicrophone && !supportsNativeMicrophoneCapture(streamConfig: streamConfig) {
+ fputs("MICROPHONE_CAPTURE_UNAVAILABLE\n", stderr)
+ fflush(stderr)
+ capturesMicrophone = false
+ }
+ writesSystemAudioToSeparateTrack = capturesSystemAudio
+ writesMicrophoneToSeparateTrack = capturesSystemAudio && capturesMicrophone
+ let requestedFPS = max(targetCaptureFPS, config.fps ?? targetCaptureFPS)
+ streamConfig.minimumFrameInterval = CMTime(value: 1, timescale: CMTimeScale(requestedFPS))
+ streamConfig.queueDepth = 6
+ streamConfig.pixelFormat = kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
+ streamConfig.colorSpaceName = CGColorSpace.sRGB
+ streamConfig.colorMatrix = CGDisplayStream.yCbCrMatrix_ITU_R_709_2
+ streamConfig.showsCursor = false
+ streamConfig.capturesAudio = capturesSystemAudio || capturesMicrophone
+ streamConfig.sampleRate = 48000
+ streamConfig.channelCount = 2
+ streamConfig.excludesCurrentProcessAudio = true
+
+ if capturesMicrophone {
+ streamConfig.setValue(true, forKey: "captureMicrophone")
+ if let microphoneDeviceId = Self.resolveMicrophoneCaptureDeviceID(config: config) {
+ streamConfig.setValue(microphoneDeviceId, forKey: "microphoneCaptureDeviceID")
+ }
+ }
+
+ let filter: SCContentFilter
+ let outputWidth: Int
+ let outputHeight: Int
+
+ if let windowId = config.windowId {
+ trackedWindowId = windowId
+ guard let window = availableContent.windows.first(where: { $0.windowID == windowId }) else {
+ throw NSError(domain: "RecordlyCapture", code: 3, userInfo: [NSLocalizedDescriptionKey: "Window not found"])
+ }
+
+ filter = SCContentFilter(desktopIndependentWindow: window)
+
+ let candidateDisplay = availableContent.displays.first(where: {
+ $0.frame.intersects(window.frame) || $0.frame.contains(CGPoint(x: window.frame.midX, y: window.frame.midY))
+ })
+ let scaleFactor = ScreenCaptureRecorder.scaleFactor(for: candidateDisplay?.displayID ?? CGMainDisplayID())
+ outputWidth = max(2, Int(window.frame.width) * scaleFactor)
+ outputHeight = max(2, Int(window.frame.height) * scaleFactor)
+ if #available(macOS 14.0, *) {
+ streamConfig.ignoreShadowsSingleWindow = true
+ }
+ streamConfig.width = outputWidth
+ streamConfig.height = outputHeight
+ } else {
+ trackedWindowId = nil
+ let displayId = config.displayId ?? CGMainDisplayID()
+ guard let display = availableContent.displays.first(where: { $0.displayID == displayId }) else {
+ throw NSError(domain: "RecordlyCapture", code: 4, userInfo: [NSLocalizedDescriptionKey: "Display not found"])
+ }
+
+ filter = SCContentFilter(display: display, excludingApplications: [], exceptingWindows: [])
+ let displayBounds = CGDisplayBounds(display.displayID)
+ let scaleFactor = ScreenCaptureRecorder.scaleFactor(for: display.displayID)
+ outputWidth = max(2, Int(displayBounds.width) * scaleFactor)
+ outputHeight = max(2, Int(displayBounds.height) * scaleFactor)
+ streamConfig.width = outputWidth
+ streamConfig.height = outputHeight
+ }
+
+ let destinationURL: URL
+ if let outputPath = config.outputPath, !outputPath.isEmpty {
+ destinationURL = URL(fileURLWithPath: outputPath)
+ } else {
+ destinationURL = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+ .appendingPathComponent("output_\(Int(Date().timeIntervalSince1970)).mp4")
+ }
+
+ outputURL = destinationURL
+ let outputFileType: AVFileType = destinationURL.pathExtension.lowercased() == "mp4" ? .mp4 : .mov
+ assetWriter = try AVAssetWriter(url: destinationURL, fileType: outputFileType)
+ microphoneOutputURL = nil
+ firstSystemAudioSampleTime = nil
+ firstMicrophoneSampleTime = nil
+ lastSystemAudioPresentationTime = .invalid
+ lastMicrophonePresentationTime = .invalid
+
+ guard let assistant = AVOutputSettingsAssistant(preset: .preset3840x2160) else {
+ throw NSError(domain: "RecordlyCapture", code: 5, userInfo: [NSLocalizedDescriptionKey: "Unable to create output settings assistant"])
+ }
+
+ let sourceVideoFormat = try CMVideoFormatDescription(
+ videoCodecType: CMFormatDescription.MediaSubType(
+ rawValue: kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange
+ ),
+ width: outputWidth,
+ height: outputHeight
+ )
+ assistant.sourceVideoFormat = sourceVideoFormat
+
+ guard var outputSettings = assistant.videoSettings else {
+ throw NSError(domain: "RecordlyCapture", code: 6, userInfo: [NSLocalizedDescriptionKey: "Output settings unavailable"])
+ }
+
+ outputSettings[AVVideoWidthKey] = outputWidth
+ outputSettings[AVVideoHeightKey] = outputHeight
+ outputSettings[AVVideoColorPropertiesKey] = [
+ AVVideoColorPrimariesKey: AVVideoColorPrimaries_ITU_R_709_2,
+ AVVideoTransferFunctionKey: AVVideoTransferFunction_ITU_R_709_2,
+ AVVideoYCbCrMatrixKey: AVVideoYCbCrMatrix_ITU_R_709_2,
+ ]
+
+ let videoInput = AVAssetWriterInput(
+ mediaType: .video,
+ outputSettings: outputSettings,
+ sourceFormatHint: sourceVideoFormat
+ )
+ videoInput.expectsMediaDataInRealTime = true
+
+ guard let assetWriter = assetWriter, assetWriter.canAdd(videoInput) else {
+ throw NSError(domain: "RecordlyCapture", code: 7, userInfo: [NSLocalizedDescriptionKey: "Unable to add video writer input"])
+ }
+
+ assetWriter.add(videoInput)
+ self.videoInput = videoInput
+
+ // Add inline audio track directly to the video so the .mp4 always contains audio.
+ // This eliminates the dependency on the post-recording ffmpeg mux step.
+ if capturesSystemAudio || capturesMicrophone {
+ let inlineAudio = AVAssetWriterInput(mediaType: .audio, outputSettings: Self.audioOutputSettings(bitRate: 192_000))
+ inlineAudio.expectsMediaDataInRealTime = true
+ if assetWriter.canAdd(inlineAudio) {
+ assetWriter.add(inlineAudio)
+ self.inlineAudioInput = inlineAudio
+ }
+ }
+
+ if writesSystemAudioToSeparateTrack {
+ guard let systemAudioOutputPath = config.systemAudioOutputPath, !systemAudioOutputPath.isEmpty else {
+ throw NSError(domain: "RecordlyCapture", code: 11, userInfo: [NSLocalizedDescriptionKey: "Missing system audio output path for audio capture"])
+ }
+
+ let systemAudioURL = URL(fileURLWithPath: systemAudioOutputPath)
+ let systemAudioWriter = try AVAssetWriter(url: systemAudioURL, fileType: .m4a)
+ let systemAudioInput = AVAssetWriterInput(mediaType: .audio, outputSettings: Self.audioOutputSettings(bitRate: 160_000))
+ systemAudioInput.expectsMediaDataInRealTime = true
+
+ guard systemAudioWriter.canAdd(systemAudioInput) else {
+ throw NSError(domain: "RecordlyCapture", code: 12, userInfo: [NSLocalizedDescriptionKey: "Unable to add system audio writer input"])
+ }
+
+ systemAudioWriter.add(systemAudioInput)
+ self.systemAudioWriter = systemAudioWriter
+ self.systemAudioInput = systemAudioInput
+
+ guard systemAudioWriter.startWriting() else {
+ throw NSError(domain: "RecordlyCapture", code: 13, userInfo: [NSLocalizedDescriptionKey: systemAudioWriter.error?.localizedDescription ?? "Unable to start system audio writing"])
+ }
+
+ systemAudioWriter.startSession(atSourceTime: .zero)
+ }
+
+ if writesMicrophoneToSeparateTrack {
+ guard let microphoneOutputPath = config.microphoneOutputPath, !microphoneOutputPath.isEmpty else {
+ throw NSError(domain: "RecordlyCapture", code: 14, userInfo: [NSLocalizedDescriptionKey: "Missing microphone output path for microphone capture"])
+ }
+
+ let microphoneURL = URL(fileURLWithPath: microphoneOutputPath)
+ microphoneOutputURL = microphoneURL
+ let microphoneWriter = try AVAssetWriter(url: microphoneURL, fileType: .m4a)
+ let microphoneInput = AVAssetWriterInput(mediaType: .audio, outputSettings: Self.audioOutputSettings(bitRate: 128_000))
+ microphoneInput.expectsMediaDataInRealTime = true
+
+ guard microphoneWriter.canAdd(microphoneInput) else {
+ throw NSError(domain: "RecordlyCapture", code: 15, userInfo: [NSLocalizedDescriptionKey: "Unable to add microphone writer input"])
+ }
+
+ microphoneWriter.add(microphoneInput)
+ self.microphoneOnlyWriter = microphoneWriter
+ self.microphoneOnlyInput = microphoneInput
+
+ guard microphoneWriter.startWriting() else {
+ throw NSError(domain: "RecordlyCapture", code: 16, userInfo: [NSLocalizedDescriptionKey: microphoneWriter.error?.localizedDescription ?? "Unable to start microphone audio writing"])
+ }
+
+ microphoneWriter.startSession(atSourceTime: .zero)
+ }
+
+ let stream = SCStream(filter: filter, configuration: streamConfig, delegate: self)
+ self.stream = stream
+ try stream.addStreamOutput(self, type: .screen, sampleHandlerQueue: queue)
+ if capturesSystemAudio {
+ try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: queue)
+ }
+ if capturesMicrophone {
+ guard let microphoneOutputType = SCStreamOutputType(rawValue: microphoneOutputTypeRawValue) else {
+ throw NSError(
+ domain: "RecordlyCapture",
+ code: 17,
+ userInfo: [NSLocalizedDescriptionKey: "Microphone stream output type is unavailable"]
+ )
+ }
+ try stream.addStreamOutput(self, type: microphoneOutputType, sampleHandlerQueue: queue)
+ }
+ try await stream.startCapture()
+
+ guard assetWriter.startWriting() else {
+ throw NSError(domain: "RecordlyCapture", code: 8, userInfo: [NSLocalizedDescriptionKey: assetWriter.error?.localizedDescription ?? "Unable to start video writing"])
+ }
+
+ assetWriter.startSession(atSourceTime: .zero)
+ sessionStarted = true
+ isRecording = true
+ isPaused = false
+ pauseStartedHostTime = nil
+ pendingResumeAdjustment = false
+ accumulatedPausedDuration = .zero
+ frameCount = 0
+ firstSampleTime = .zero
+ lastVideoPresentationTime = .zero
+ lastVideoDuration = .zero
+ startWindowValidationIfNeeded()
+ }
+
+ func stopCapture() async throws -> String {
+ let finalization = await finalizeCapture(interactive: true)
+ return try finalization.outputResult.get()
+ }
+
+ func pauseCapture() async -> Bool {
+ await withCheckedContinuation { continuation in
+ queue.async {
+ guard self.isRecording, !self.isPaused else {
+ continuation.resume(returning: self.isRecording && self.isPaused)
+ return
+ }
+ self.isPaused = true
+ self.pauseStartedHostTime = CMClockGetTime(CMClockGetHostTimeClock())
+ self.pendingResumeAdjustment = false
+ continuation.resume(returning: true)
+ }
+ }
+ }
+
+ func resumeCapture() async -> Bool {
+ await withCheckedContinuation { continuation in
+ queue.async {
+ guard self.isRecording, self.isPaused else {
+ continuation.resume(returning: self.isRecording && !self.isPaused)
+ return
+ }
+ self.isPaused = false
+ self.pendingResumeAdjustment = true
+ continuation.resume(returning: true)
+ }
+ }
+ }
+
+ func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of outputType: SCStreamOutputType) {
+ guard sessionStarted, sampleBuffer.isValid, isRecording else { return }
+ guard let presentationTime = adjustedPresentationTime(for: sampleBuffer, outputType: outputType) else { return }
+
+ if outputType == .screen {
+ if frameCount > 0 && CMTimeCompare(presentationTime, lastVideoPresentationTime) <= 0 {
+ return
+ }
+
+ guard let attachments = CMSampleBufferGetSampleAttachmentsArray(sampleBuffer, createIfNecessary: false) as? [[SCStreamFrameInfo: Any]],
+ let attachment = attachments.first,
+ let statusRawValue = attachment[SCStreamFrameInfo.status] as? Int,
+ let status = SCFrameStatus(rawValue: statusRawValue),
+ status == .complete else {
+ return
+ }
+
+ guard let videoInput = videoInput,
+ assetWriter?.status == .writing,
+ videoInput.isReadyForMoreMediaData else { return }
+
+ if firstSampleTime == .zero {
+ firstSampleTime = sampleBuffer.presentationTimeStamp
+ }
+
+ lastSampleBuffer = sampleBuffer
+ let timing = CMSampleTimingInfo(duration: sampleBuffer.duration, presentationTimeStamp: presentationTime, decodeTimeStamp: sampleBuffer.decodeTimeStamp)
+ if let retimedSampleBuffer = try? CMSampleBuffer(copying: sampleBuffer, withNewTiming: [timing]) {
+ if videoInput.append(retimedSampleBuffer) {
+ lastVideoPresentationTime = presentationTime
+ lastVideoDuration = sampleBuffer.duration
+ frameCount += 1
+ if frameCount == 1 {
+ // Signal readiness only after AVAssetWriter has accepted a
+ // real frame, so countdown warm-start cannot pause too early.
+ print("Recording started")
+ fflush(stdout)
+ }
+ }
+ }
+ return
+ }
+
+ if outputType == .audio {
+ guard let systemAudioInput else { return }
+ appendAudioSampleBuffer(sampleBuffer, to: systemAudioInput, of: systemAudioWriter, firstSampleTime: &firstSystemAudioSampleTime, lastPresentationTime: &lastSystemAudioPresentationTime, presentationTime: presentationTime)
+ // Also write system audio to the inline video track
+ if let inlineAudioInput, inlineAudioInput.isReadyForMoreMediaData {
+ appendAudioSampleBuffer(sampleBuffer, to: inlineAudioInput, of: assetWriter, firstSampleTime: &firstInlineAudioSampleTime, lastPresentationTime: &lastInlineAudioPresentationTime, presentationTime: presentationTime)
+ }
+ return
+ }
+
+ if outputType.rawValue == microphoneOutputTypeRawValue {
+ if let microphoneOnlyInput {
+ appendAudioSampleBuffer(sampleBuffer, to: microphoneOnlyInput, of: microphoneOnlyWriter, firstSampleTime: &firstMicrophoneSampleTime, lastPresentationTime: &lastMicrophonePresentationTime, presentationTime: presentationTime)
+ }
+ // Write mic to inline video track only if there's no system audio (avoids double-writing)
+ if !capturesSystemAudio, let inlineAudioInput, inlineAudioInput.isReadyForMoreMediaData {
+ appendAudioSampleBuffer(sampleBuffer, to: inlineAudioInput, of: assetWriter, firstSampleTime: &firstInlineAudioSampleTime, lastPresentationTime: &lastInlineAudioPresentationTime, presentationTime: presentationTime)
+ }
+ return
+ }
+
+ return
+ }
+
+ func stream(_ stream: SCStream, didStopWithError error: Error) {
+ fputs("Error: \(error.localizedDescription)\n", stderr)
+ fflush(stderr)
+ }
+
+ /// Starts one finalization operation after all previously delivered samples on
+ /// the recorder queue have drained. Manual stop and automatic window-close
+ /// detection join the same operation instead of racing the asset writers.
+ private func finalizeCapture(interactive: Bool) async -> CaptureFinalizationResult {
+ await withCheckedContinuation { continuation in
+ queue.async {
+ if self.isFinalizing {
+ self.interactiveStopParticipated = self.interactiveStopParticipated || interactive
+ self.finalizationWaiters.append(continuation)
+ return
+ }
+
+ guard self.isRecording else {
+ continuation.resume(returning: CaptureFinalizationResult(
+ outputResult: .failure(NSError(
+ domain: "RecordlyCapture",
+ code: 9,
+ userInfo: [NSLocalizedDescriptionKey: "No recording in progress"]
+ )),
+ interactiveStopParticipated: interactive
+ ))
+ return
+ }
+
+ self.isFinalizing = true
+ self.interactiveStopParticipated = interactive
+ self.isRecording = false
+ self.windowValidationTask = nil
+ self.trackedWindowId = nil
+ self.finalizationWaiters.append(continuation)
+
+ Task {
+ let outputResult: Result
+ do {
+ outputResult = .success(try await self.finishCapture())
+ } catch {
+ outputResult = .failure(error)
+ }
+
+ self.queue.async {
+ let finalizationResult = CaptureFinalizationResult(
+ outputResult: outputResult,
+ interactiveStopParticipated: self.interactiveStopParticipated
+ )
+ let waiters = self.finalizationWaiters
+ self.finalizationWaiters.removeAll()
+ self.isFinalizing = false
+ self.interactiveStopParticipated = false
+ for waiter in waiters {
+ waiter.resume(returning: finalizationResult)
+ }
+ }
+ }
+ }
+ }
+ }
+
+ private func finishCapture() async throws -> String {
+
+ if let activeStream = stream {
+ do {
+ try await activeStream.stopCapture()
+ } catch {
+ // Stream may have already been stopped by the system — continue with file finalization
+ }
+ }
+ stream = nil
+
+ // The tail frame only gives the last captured frame its full duration, so
+ // it must never put the file at risk. Appending to an input whose encoder
+ // queue is still backed up — routine after a long high-resolution capture —
+ // raises an Objective-C exception that Swift cannot catch, aborting the
+ // helper before `finishWriting()` and leaving an mdat with no moov atom:
+ // an unplayable recording. Wait briefly for the queue to drain, then skip
+ // the frame rather than lose the recording.
+ if let originalBuffer = lastSampleBuffer,
+ let videoInput = videoInput,
+ await waitUntilReady(videoInput, of: assetWriter) {
+ let additionalTime = lastVideoPresentationTime + frameDuration(for: originalBuffer)
+ let timing = CMSampleTimingInfo(duration: originalBuffer.duration, presentationTimeStamp: additionalTime, decodeTimeStamp: originalBuffer.decodeTimeStamp)
+ if let additionalSampleBuffer = try? CMSampleBuffer(copying: originalBuffer, withNewTiming: [timing]) {
+ videoInput.append(additionalSampleBuffer)
+ }
+ }
+
+ // `endSession`, `markAsFinished` and `finishWriting` all raise when the
+ // writer is no longer in the `.writing` state (a mid-capture failure, for
+ // example a full disk), which would abort the helper the same way.
+ let videoEndTime = lastVideoPresentationTime + (lastSampleBuffer.map { frameDuration(for: $0) } ?? .zero)
+ let endTime = resolvedCaptureEndTime(videoEndTime: videoEndTime)
+ if let assetWriter, assetWriter.status == .writing {
+ assetWriter.endSession(atSourceTime: endTime)
+ videoInput?.markAsFinished()
+ inlineAudioInput?.markAsFinished()
+ await assetWriter.finishWriting()
+ }
+
+ if let systemAudioWriter, systemAudioWriter.status == .writing {
+ systemAudioInput?.markAsFinished()
+ await systemAudioWriter.finishWriting()
+ }
+
+ if let microphoneOnlyWriter, microphoneOnlyWriter.status == .writing {
+ microphoneOnlyInput?.markAsFinished()
+ await microphoneOnlyWriter.finishWriting()
+ }
+
+ let finalizeFailure: Error? = [assetWriter, systemAudioWriter, microphoneOnlyWriter]
+ .compactMap { $0 }
+ .compactMap { writer in
+ writer.status == .completed
+ ? nil
+ : (writer.error ?? unfinalizedWriterError(status: writer.status))
+ }
+ .first
+ let path = outputURL?.path ?? ""
+ assetWriter = nil
+ videoInput = nil
+ systemAudioWriter = nil
+ systemAudioInput = nil
+ microphoneOnlyWriter = nil
+ microphoneOnlyInput = nil
+ inlineAudioInput = nil
+ outputURL = nil
+ microphoneOutputURL = nil
+ sessionStarted = false
+ firstSampleTime = .zero
+ firstSystemAudioSampleTime = nil
+ firstMicrophoneSampleTime = nil
+ lastSystemAudioPresentationTime = .invalid
+ lastMicrophonePresentationTime = .invalid
+ firstInlineAudioSampleTime = nil
+ lastSampleBuffer = nil
+ lastVideoPresentationTime = .zero
+ lastVideoDuration = .zero
+ lastInlineAudioPresentationTime = .invalid
+ lastInlineAudioDuration = .zero
+ frameCount = 0
+ isPaused = false
+ pauseStartedHostTime = nil
+ pendingResumeAdjustment = false
+ accumulatedPausedDuration = .zero
+ capturesSystemAudio = false
+ capturesMicrophone = false
+ writesSystemAudioToSeparateTrack = false
+ writesMicrophoneToSeparateTrack = false
+
+ // Report a half-written file as a failure instead of handing the editor a
+ // path it cannot decode.
+ if let finalizeFailure {
+ throw finalizeFailure
+ }
+
+ return path
+ }
+
+ /// Waits briefly for an input's encoder queue to drain. Returns false when the
+ /// input stays backed up or its writer is no longer accepting data, in which
+ /// case the caller must skip the append: `AVAssetWriterInput.append` raises an
+ /// uncatchable Objective-C exception in both cases.
+ private func waitUntilReady(_ input: AVAssetWriterInput, of writer: AVAssetWriter?) async -> Bool {
+ guard let writer else { return false }
+
+ var attemptsRemaining = writerReadinessPollAttempts
+ while writer.status == .writing {
+ if input.isReadyForMoreMediaData {
+ return true
+ }
+ guard attemptsRemaining > 0 else { return false }
+ attemptsRemaining -= 1
+ do {
+ try await Task.sleep(nanoseconds: writerReadinessPollInterval)
+ } catch is CancellationError {
+ return false
+ } catch {
+ return false
+ }
+ }
+
+ return false
+ }
+
+ private func unfinalizedWriterError(status: AVAssetWriter.Status) -> Error {
+ NSError(domain: "RecordlyCapture", code: 10, userInfo: [
+ NSLocalizedDescriptionKey: "Recording could not be finalized (writer status \(status.rawValue))",
+ ])
+ }
+
+ private func adjustedPresentationTime(for sampleBuffer: CMSampleBuffer, outputType: SCStreamOutputType) -> CMTime? {
+ if isPaused {
+ return nil
+ }
+
+ let sampleTime = sampleBuffer.presentationTimeStamp
+ if pendingResumeAdjustment {
+ // Audio and video callbacks share this queue but their timestamps can be
+ // offset slightly. Anchor the post-countdown adjustment to video and drop
+ // audio until that anchor exists; otherwise the first audio callback can
+ // make the following video timestamp move backwards and fail the writer.
+ guard outputType == .screen, let pauseStartedHostTime else {
+ return nil
+ }
+ let pauseGap = sampleTime - pauseStartedHostTime
+ if pauseGap > .zero {
+ accumulatedPausedDuration = accumulatedPausedDuration + pauseGap
+ }
+ self.pauseStartedHostTime = nil
+ pendingResumeAdjustment = false
+ }
+
+ if outputType == .screen {
+ if firstSampleTime == .zero {
+ firstSampleTime = sampleTime
+ }
+ }
+
+ // Use video's first sample time as the common time base for ALL tracks.
+ // This ensures audio files contain leading silence when audio hardware
+ // delivers its first sample after the first video frame (e.g. iPhone mic
+ // over Continuity Camera can lag 1-2 seconds behind).
+ if firstSampleTime == .zero {
+ // Video hasn't started yet — drop this audio sample to avoid
+ // negative timestamps.
+ return nil
+ }
+
+ return max(.zero, sampleTime - firstSampleTime - accumulatedPausedDuration)
+ }
+
+ private func frameDuration(for sampleBuffer: CMSampleBuffer) -> CMTime {
+ if sampleBuffer.duration.isValid && sampleBuffer.duration > .zero {
+ return sampleBuffer.duration
+ }
+
+ if lastVideoDuration.isValid && lastVideoDuration > .zero {
+ return lastVideoDuration
+ }
+
+ return CMTime(value: 1, timescale: CMTimeScale(targetCaptureFPS))
+ }
+
+ private func latestInlineAudioEndTime() -> CMTime {
+ guard lastInlineAudioPresentationTime.isValid else {
+ return .invalid
+ }
+
+ if lastInlineAudioDuration.isValid && lastInlineAudioDuration > .zero {
+ return lastInlineAudioPresentationTime + lastInlineAudioDuration
+ }
+
+ return lastInlineAudioPresentationTime
+ }
+
+ private func resolvedCaptureEndTime(videoEndTime: CMTime) -> CMTime {
+ let inlineAudioEndTime = latestInlineAudioEndTime()
+ guard inlineAudioEndTime.isValid else {
+ return videoEndTime
+ }
+
+ if CMTimeCompare(inlineAudioEndTime, videoEndTime) <= 0 {
+ return videoEndTime
+ }
+
+ // Prevent a stray inline-audio timestamp from forcing finishWriting
+ // to finalize an arbitrarily long tail.
+ let tailExtension = CMTimeSubtract(inlineAudioEndTime, videoEndTime)
+ return videoEndTime + CMTimeMinimum(tailExtension, maxInlineAudioTailExtension)
+ }
+
+ private func appendAudioSampleBuffer(_ sampleBuffer: CMSampleBuffer, to input: AVAssetWriterInput, of writer: AVAssetWriter?, firstSampleTime: inout CMTime?, lastPresentationTime: inout CMTime, presentationTime: CMTime) {
+ // A writer that failed mid-capture (a full disk, say) raises on every
+ // further append, which would abort the helper and lose the whole file.
+ guard writer?.status == .writing, input.isReadyForMoreMediaData else { return }
+ guard !lastPresentationTime.isValid || CMTimeCompare(presentationTime, lastPresentationTime) > 0 else { return }
+
+ if firstSampleTime == nil {
+ firstSampleTime = presentationTime
+ }
+
+ // presentationTime is already relative to the video's first frame
+ // (computed by adjustedPresentationTime), so use it directly.
+ let timing = CMSampleTimingInfo(duration: sampleBuffer.duration, presentationTimeStamp: presentationTime, decodeTimeStamp: sampleBuffer.decodeTimeStamp)
+ if let retimedSampleBuffer = try? CMSampleBuffer(copying: sampleBuffer, withNewTiming: [timing]) {
+ let appended = input.append(retimedSampleBuffer)
+ if appended {
+ lastPresentationTime = presentationTime
+ if input === inlineAudioInput {
+ lastInlineAudioDuration = sampleBuffer.duration
+ }
+ }
+ }
+ }
+
+ private static func audioOutputSettings(bitRate: Int) -> [String: Any] {
+ [
+ AVFormatIDKey: kAudioFormatMPEG4AAC,
+ AVSampleRateKey: 48_000,
+ AVNumberOfChannelsKey: 2,
+ AVEncoderBitRateKey: bitRate,
+ ]
+ }
+
+ private static func resolveMicrophoneCaptureDeviceID(config: CaptureConfig) -> String? {
+ let audioDevices = AVCaptureDevice.devices(for: .audio)
+
+ if let microphoneLabel = config.microphoneLabel?.trimmingCharacters(in: .whitespacesAndNewlines), !microphoneLabel.isEmpty {
+ if let matchedDevice = audioDevices.first(where: { $0.localizedName == microphoneLabel }) {
+ return matchedDevice.uniqueID
+ }
+ }
+
+ if let microphoneDeviceId = config.microphoneDeviceId?.trimmingCharacters(in: .whitespacesAndNewlines), !microphoneDeviceId.isEmpty {
+ if audioDevices.contains(where: { $0.uniqueID == microphoneDeviceId }) {
+ return microphoneDeviceId
+ }
+ }
+
+ return nil
+ }
+
+ private func supportsNativeMicrophoneCapture(streamConfig: SCStreamConfiguration) -> Bool {
+ let supportsConfigSelector = streamConfig.responds(to: Selector(("setCaptureMicrophone:")))
+ let supportsDeviceSelector = streamConfig.responds(to: Selector(("setMicrophoneCaptureDeviceID:")))
+ let supportsOutputType = SCStreamOutputType(rawValue: microphoneOutputTypeRawValue) != nil
+ return supportsConfigSelector && supportsDeviceSelector && supportsOutputType
+ }
+
+ private func startWindowValidationIfNeeded() {
+ guard let trackedWindowId else {
+ windowValidationTask?.cancel()
+ windowValidationTask = nil
+ return
+ }
+
+ windowValidationTask?.cancel()
+ windowValidationTask = Task.detached(priority: .utility) { [weak self] in
+ guard let self else { return }
+ while !Task.isCancelled {
+ try? await Task.sleep(nanoseconds: 500_000_000)
+ if Task.isCancelled { return }
+ guard self.isRecording else { return }
+
+ let availableContent: SCShareableContent
+ do {
+ availableContent = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+ } catch {
+ continue
+ }
+
+ let windowStillAvailable = availableContent.windows.contains(where: { $0.windowID == trackedWindowId })
+ if !windowStillAvailable {
+ print("WINDOW_UNAVAILABLE")
+ fflush(stdout)
+ let finalization = await self.finalizeCapture(interactive: false)
+ if finalization.interactiveStopParticipated {
+ return
+ }
+ do {
+ let outputPath = try finalization.outputResult.get()
+ print("Recording stopped. Output path: \(outputPath)")
+ fflush(stdout)
+ exit(0)
+ } catch {
+ fputs("Error stopping capture: \(error.localizedDescription)\n", stderr)
+ fflush(stderr)
+ exit(1)
+ }
+ }
+ }
+ }
+ }
+
+ private static func scaleFactor(for displayId: CGDirectDisplayID) -> Int {
+ guard let mode = CGDisplayCopyDisplayMode(displayId) else {
+ return 1
+ }
+ return max(1, mode.pixelWidth / max(1, mode.width))
+ }
+}
+
+final class RecorderService {
+ private let recorder = ScreenCaptureRecorder()
+ private let queue = DispatchQueue(label: "recordly.screencapturekit.commands")
+ private let completionGroup = DispatchGroup()
+ private var succeeded = true
+
+ private func enqueue(_ operation: @escaping () async -> Void) {
+ queue.async {
+ let semaphore = DispatchSemaphore(value: 0)
+ Task {
+ await operation()
+ semaphore.signal()
+ }
+ semaphore.wait()
+ }
+ }
+
+ func start(configJSON: String) {
+ completionGroup.enter()
+ enqueue {
+ do {
+ try await self.recorder.startCapture(configJSON: configJSON)
+ } catch {
+ self.succeeded = false
+ fputs("Error starting capture: \(error.localizedDescription)\n", stderr)
+ fflush(stderr)
+ self.completionGroup.leave()
+ }
+ }
+ }
+
+ func stop() {
+ enqueue {
+ do {
+ let outputPath = try await self.recorder.stopCapture()
+ print("Recording stopped. Output path: \(outputPath)")
+ fflush(stdout)
+ self.completionGroup.leave()
+ } catch {
+ self.succeeded = false
+ fputs("Error stopping capture: \(error.localizedDescription)\n", stderr)
+ fflush(stderr)
+ self.completionGroup.leave()
+ }
+ }
+ }
+
+ func pause() {
+ enqueue {
+ if await self.recorder.pauseCapture() {
+ print("Recording paused")
+ fflush(stdout)
+ }
+ }
+ }
+
+ func resume() {
+ enqueue {
+ if await self.recorder.resumeCapture() {
+ print("Recording resumed")
+ fflush(stdout)
+ }
+ }
+ }
+
+ func waitUntilFinished() -> Bool {
+ completionGroup.wait()
+ return succeeded
+ }
+}
+
+guard CommandLine.arguments.count >= 2 else {
+ fputs("Missing config JSON\n", stderr)
+ fflush(stderr)
+ exit(1)
+}
+
+// Force CoreGraphics Services initialization on the main thread.
+// Without this, SCContentFilter(desktopIndependentWindow:) crashes with
+// CGS_REQUIRE_INIT because CGS is never initialised in a CLI tool.
+let _ = CGMainDisplayID()
+
+// Pre-flight check: ensure screen recording permission is granted before
+// attempting capture. On macOS 15+, a one-session grant may expire after the
+// parent app restarts. CGRequestScreenCaptureAccess() will trigger the
+// system-level permission dialog (or open System Settings) when not yet granted.
+if !CGPreflightScreenCaptureAccess() {
+ let granted = CGRequestScreenCaptureAccess()
+ if !granted {
+ fputs("SCREEN_RECORDING_PERMISSION_DENIED\n", stderr)
+ fflush(stderr)
+ exit(1)
+ }
+}
+
+// Pre-flight check for microphone access when mic capture is requested.
+if let configData = CommandLine.arguments[1].data(using: .utf8),
+ let config = try? JSONDecoder().decode(CaptureConfig.self, from: configData),
+ config.capturesMicrophone == true {
+ switch AVCaptureDevice.authorizationStatus(for: .audio) {
+ case .authorized:
+ break
+ case .notDetermined:
+ let sem = DispatchSemaphore(value: 0)
+ AVCaptureDevice.requestAccess(for: .audio) { _ in sem.signal() }
+ sem.wait()
+ if AVCaptureDevice.authorizationStatus(for: .audio) != .authorized {
+ fputs("MICROPHONE_PERMISSION_DENIED\n", stderr)
+ fflush(stderr)
+ exit(1)
+ }
+ default:
+ fputs("MICROPHONE_PERMISSION_DENIED\n", stderr)
+ fflush(stderr)
+ exit(1)
+ }
+}
+
+let service = RecorderService()
+service.start(configJSON: CommandLine.arguments[1])
+
+DispatchQueue.global(qos: .utility).async {
+ while let input = readLine(strippingNewline: true)?.lowercased() {
+ if input == "pause" {
+ service.pause()
+ continue
+ }
+
+ if input == "resume" {
+ service.resume()
+ continue
+ }
+
+ if input == "stop" {
+ service.stop()
+ break
+ }
+ }
+}
+
+if !service.waitUntilFinished() {
+ exit(1)
+}
diff --git a/electron/native/ScreenCaptureKitRecorder.test.ts b/electron/native/ScreenCaptureKitRecorder.test.ts
new file mode 100644
index 000000000..0956bf6fd
--- /dev/null
+++ b/electron/native/ScreenCaptureKitRecorder.test.ts
@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const recorderSource = readFileSync(
+ fileURLToPath(new URL("./ScreenCaptureKitRecorder.swift", import.meta.url)),
+ "utf8",
+);
+
+describe("ScreenCaptureKitRecorder finalization coordination", () => {
+ it("marks manual stops as participants in the shared finalization", () => {
+ expect(recorderSource).toContain("finalizeCapture(interactive: true)");
+ expect(recorderSource).toContain("finalization.outputResult.get()");
+ expect(recorderSource).toContain(
+ "self.interactiveStopParticipated = self.interactiveStopParticipated || interactive",
+ );
+ });
+
+ it("does not let automatic window-close exit preempt a joined manual stop", () => {
+ expect(recorderSource).toContain("self.finalizeCapture(interactive: false)");
+ expect(recorderSource).toMatch(
+ /if finalization\.interactiveStopParticipated\s*\{\s*return\s*\}/,
+ );
+ });
+});
+
+describe("ScreenCaptureKitRecorder resume timing", () => {
+ it("anchors warm-start resume timing to video before accepting audio", () => {
+ expect(recorderSource).toContain(
+ "guard outputType == .screen, let pauseStartedHostTime else",
+ );
+ });
+
+ it("drops non-monotonic video and audio samples", () => {
+ expect(recorderSource).toContain(
+ "CMTimeCompare(presentationTime, lastVideoPresentationTime) <= 0",
+ );
+ expect(recorderSource).toContain(
+ "CMTimeCompare(presentationTime, lastPresentationTime) > 0",
+ );
+ });
+});
+
+describe("ScreenCaptureKitRecorder colour metadata", () => {
+ it("asks ScreenCaptureKit for BT.709-compatible video-range frames", () => {
+ expect(recorderSource).toContain(
+ "streamConfig.pixelFormat = kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange",
+ );
+ expect(recorderSource).toContain("streamConfig.colorSpaceName = CGColorSpace.sRGB");
+ expect(recorderSource).toContain(
+ "streamConfig.colorMatrix = CGDisplayStream.yCbCrMatrix_ITU_R_709_2",
+ );
+ expect(recorderSource).toContain(
+ "rawValue: kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange",
+ );
+ expect(recorderSource).toContain("sourceFormatHint: sourceVideoFormat");
+ expect(recorderSource).not.toContain("videoCodecType: .h264");
+ });
+
+ it("tags recordings as BT.709", () => {
+ expect(recorderSource).toContain("AVVideoColorPropertiesKey");
+ expect(recorderSource).toContain("AVVideoColorPrimaries_ITU_R_709_2");
+ expect(recorderSource).toContain("AVVideoTransferFunction_ITU_R_709_2");
+ expect(recorderSource).toContain("AVVideoYCbCrMatrix_ITU_R_709_2");
+ });
+});
diff --git a/electron/native/ScreenCaptureKitWindowList.swift b/electron/native/ScreenCaptureKitWindowList.swift
new file mode 100644
index 000000000..cdb2f5757
--- /dev/null
+++ b/electron/native/ScreenCaptureKitWindowList.swift
@@ -0,0 +1,155 @@
+import Foundation
+import CoreGraphics
+import ScreenCaptureKit
+
+struct WindowListEntry: Codable {
+ let id: String
+ let name: String
+ let display_id: String
+ let appName: String?
+ let windowTitle: String?
+ let bundleId: String?
+ let x: Double
+ let y: Double
+ let width: Double
+ let height: Double
+}
+
+func normalize(_ value: String?) -> String? {
+ guard let rawValue = value?.trimmingCharacters(in: .whitespacesAndNewlines), !rawValue.isEmpty else {
+ return nil
+ }
+
+ return rawValue
+}
+
+let excludedBundleIds: Set = [
+ "com.apple.controlcenter",
+ "com.apple.dock",
+ "com.apple.WindowManager",
+ "com.apple.wallpaper.agent",
+]
+
+let excludedWindowTitles: Set = [
+ "Display 1 Backstop",
+ "Event Shield Window",
+ "Menubar",
+ "Offscreen Wallpaper Window",
+ "Wallpaper-",
+]
+
+// Force CoreGraphics Services initialization before asking ScreenCaptureKit for
+// shareable content. Without this, the helper can stall sporadically when run
+// as a standalone CLI process from Electron.
+let _ = CGMainDisplayID()
+
+let group = DispatchGroup()
+group.enter()
+
+Task {
+ do {
+ let shareableContent = try await SCShareableContent.excludingDesktopWindows(false, onScreenWindowsOnly: true)
+
+ struct RawWindowEntry {
+ let entry: WindowListEntry
+ let hasRawTitle: Bool
+ let bundleId: String?
+ }
+
+ let rawEntries = shareableContent.windows.compactMap { window -> RawWindowEntry? in
+ let appName = normalize(window.owningApplication?.applicationName)
+ let windowTitle = normalize(window.title)
+ let bundleId = normalize(window.owningApplication?.bundleIdentifier)
+ let frame = window.frame
+
+ guard window.windowLayer == 0 else {
+ return nil
+ }
+
+ guard frame.width >= 50, frame.height >= 50 else {
+ return nil
+ }
+
+ guard appName != nil || windowTitle != nil else {
+ return nil
+ }
+
+ if let bundleId, excludedBundleIds.contains(bundleId) {
+ return nil
+ }
+
+ if let windowTitle, excludedWindowTitles.contains(windowTitle) {
+ return nil
+ }
+
+ let matchedDisplay = shareableContent.displays.first(where: { display in
+ display.frame.intersects(frame) || display.frame.contains(CGPoint(x: frame.midX, y: frame.midY))
+ })
+
+ let resolvedWindowTitle = windowTitle ?? appName ?? "Window"
+ let resolvedName: String
+ if let appName, let windowTitle {
+ resolvedName = "\(appName) — \(windowTitle)"
+ } else {
+ resolvedName = resolvedWindowTitle
+ }
+
+ let entry = WindowListEntry(
+ id: "window:\(window.windowID):0",
+ name: resolvedName,
+ display_id: matchedDisplay.map { String($0.displayID) } ?? "",
+ appName: appName,
+ windowTitle: resolvedWindowTitle,
+ bundleId: bundleId,
+ x: Double(frame.origin.x),
+ y: Double(frame.origin.y),
+ width: Double(frame.width),
+ height: Double(frame.height)
+ )
+
+ return RawWindowEntry(entry: entry, hasRawTitle: windowTitle != nil, bundleId: bundleId)
+ }
+
+ // For apps with multiple windows, drop auxiliary windows that lack a
+ // distinct title (e.g. Arc's sidebar/tab-bar chrome). If ALL windows
+ // from an app lack titles, keep them all.
+ var titledCountByBundle: [String: Int] = [:]
+ for raw in rawEntries {
+ if let bid = raw.bundleId, raw.hasRawTitle {
+ titledCountByBundle[bid, default: 0] += 1
+ }
+ }
+
+ let entries = rawEntries
+ .filter { raw in
+ guard let bid = raw.bundleId else { return true }
+ if let titled = titledCountByBundle[bid], titled > 0 {
+ return raw.hasRawTitle
+ }
+ return true
+ }
+ .map { $0.entry }
+ .sorted { lhs, rhs in
+ let lhsApp = lhs.appName ?? lhs.name
+ let rhsApp = rhs.appName ?? rhs.name
+ if lhsApp != rhsApp {
+ return lhsApp.localizedCaseInsensitiveCompare(rhsApp) == .orderedAscending
+ }
+
+ return (lhs.windowTitle ?? lhs.name).localizedCaseInsensitiveCompare(rhs.windowTitle ?? rhs.name) == .orderedAscending
+ }
+
+ let encoder = JSONEncoder()
+ encoder.outputFormatting = [.sortedKeys]
+ let data = try encoder.encode(entries)
+ FileHandle.standardOutput.write(data)
+ } catch {
+ fputs("Error listing windows: \(error.localizedDescription)\n", stderr)
+ fflush(stderr)
+ exit(1)
+ }
+
+ group.leave()
+}
+
+group.wait()
diff --git a/electron/native/SystemCursorAssets.swift b/electron/native/SystemCursorAssets.swift
new file mode 100644
index 000000000..b3adee519
--- /dev/null
+++ b/electron/native/SystemCursorAssets.swift
@@ -0,0 +1,210 @@
+import Foundation
+import AppKit
+
+// Force AppKit initialization so all system cursor images are populated
+let _ = NSApplication.shared
+
+struct CursorAsset: Codable {
+ let dataUrl: String
+ let hotspotX: Double
+ let hotspotY: Double
+ let width: Double
+ let height: Double
+}
+
+let minimumCursorRenderScale: CGFloat = 12
+
+/// Reference pixel height that all cursor images are normalized to after trimming.
+/// Kept high so large in-app cursor scaling still preserves raster detail up to 10x.
+let referencePixelHeight: CGFloat = 1024
+
+func bestCursorCGImage(for image: NSImage) -> CGImage? {
+ var proposedRect = CGRect(origin: .zero, size: image.size)
+ if let cgImage = image.cgImage(forProposedRect: &proposedRect, context: nil, hints: nil) {
+ return cgImage
+ }
+
+ let sortedRepresentations = image.representations.sorted { lhs, rhs in
+ let lhsPixels = lhs.pixelsWide * lhs.pixelsHigh
+ let rhsPixels = rhs.pixelsWide * rhs.pixelsHigh
+ return lhsPixels > rhsPixels
+ }
+
+ for representation in sortedRepresentations {
+ if let bitmap = representation as? NSBitmapImageRep, let cgImage = bitmap.cgImage {
+ return cgImage
+ }
+ }
+
+ return nil
+}
+
+func makeRetinaImage(from cgImage: CGImage, pointSize: NSSize) -> NSImage {
+ let bitmap = NSBitmapImageRep(cgImage: cgImage)
+ bitmap.size = pointSize
+ let image = NSImage(size: pointSize)
+ image.addRepresentation(bitmap)
+ return image
+}
+
+/// Find the bounding box of non-transparent pixels in a bitmap.
+/// Returns (x, y, width, height) in pixel coordinates (origin top-left).
+func findOpaqueBounds(_ bitmap: NSBitmapImageRep) -> (x: Int, y: Int, width: Int, height: Int)? {
+ let w = bitmap.pixelsWide
+ let h = bitmap.pixelsHigh
+ guard let data = bitmap.bitmapData else { return nil }
+ let bpr = bitmap.bytesPerRow
+ var minX = w, minY = h, maxX = -1, maxY = -1
+ for y in 0.. 2 {
+ if x < minX { minX = x }
+ if x > maxX { maxX = x }
+ if y < minY { minY = y }
+ if y > maxY { maxY = y }
+ }
+ }
+ }
+ if maxX < 0 { return nil }
+ return (minX, minY, maxX - minX + 1, maxY - minY + 1)
+}
+
+func makeAsset(for cursor: NSCursor) -> CursorAsset? {
+ let baseImage = cursor.image
+ let pointSize = baseImage.size
+ guard let sourceCGImage = bestCursorCGImage(for: baseImage) else { return nil }
+ let sourcePixelWidth = max(1, sourceCGImage.width)
+ let sourcePixelHeight = max(1, sourceCGImage.height)
+ let sourceScaleX = CGFloat(sourcePixelWidth) / max(1, pointSize.width)
+ let sourceScaleY = CGFloat(sourcePixelHeight) / max(1, pointSize.height)
+ let sourceScale = max(sourceScaleX, sourceScaleY)
+ let image = makeRetinaImage(from: sourceCGImage, pointSize: pointSize)
+ let renderScale = max(
+ minimumCursorRenderScale,
+ referencePixelHeight / max(1, CGFloat(sourcePixelHeight))
+ )
+ let pixelWidth = max(1, Int((CGFloat(sourcePixelWidth) * renderScale).rounded(.up)))
+ let pixelHeight = max(1, Int((CGFloat(sourcePixelHeight) * renderScale).rounded(.up)))
+
+ // Render at full resolution
+ guard let bitmap = NSBitmapImageRep(
+ bitmapDataPlanes: nil,
+ pixelsWide: pixelWidth,
+ pixelsHigh: pixelHeight,
+ bitsPerSample: 8,
+ samplesPerPixel: 4,
+ hasAlpha: true,
+ isPlanar: false,
+ colorSpaceName: .deviceRGB,
+ bytesPerRow: 0,
+ bitsPerPixel: 0
+ ) else { return nil }
+
+ bitmap.size = NSSize(width: CGFloat(pixelWidth), height: CGFloat(pixelHeight))
+
+ NSGraphicsContext.saveGraphicsState()
+ guard let context = NSGraphicsContext(bitmapImageRep: bitmap) else {
+ NSGraphicsContext.restoreGraphicsState()
+ return nil
+ }
+ NSGraphicsContext.current = context
+ context.imageInterpolation = .none
+ context.cgContext.interpolationQuality = .none
+ image.draw(
+ in: NSRect(x: 0, y: 0, width: CGFloat(pixelWidth), height: CGFloat(pixelHeight)),
+ from: .zero,
+ operation: .copy,
+ fraction: 1
+ )
+ context.flushGraphics()
+ NSGraphicsContext.restoreGraphicsState()
+
+ // Find opaque bounds and crop away transparent padding
+ guard let bounds = findOpaqueBounds(bitmap) else { return nil }
+ guard let fullCG = bitmap.cgImage else { return nil }
+ let cropRect = CGRect(x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height)
+ guard let croppedCG = fullCG.cropping(to: cropRect) else { return nil }
+
+ // Scale cropped image to referencePixelHeight
+ let aspect = CGFloat(bounds.width) / CGFloat(bounds.height)
+ let outH = Int(referencePixelHeight)
+ let outW = max(1, Int((referencePixelHeight * aspect).rounded(.up)))
+
+ guard let outBitmap = NSBitmapImageRep(
+ bitmapDataPlanes: nil,
+ pixelsWide: outW,
+ pixelsHigh: outH,
+ bitsPerSample: 8,
+ samplesPerPixel: 4,
+ hasAlpha: true,
+ isPlanar: false,
+ colorSpaceName: .deviceRGB,
+ bytesPerRow: 0,
+ bitsPerPixel: 0
+ ) else { return nil }
+
+ outBitmap.size = NSSize(width: outW, height: outH)
+
+ NSGraphicsContext.saveGraphicsState()
+ guard let outCtx = NSGraphicsContext(bitmapImageRep: outBitmap) else {
+ NSGraphicsContext.restoreGraphicsState()
+ return nil
+ }
+ NSGraphicsContext.current = outCtx
+ outCtx.imageInterpolation = .none
+ outCtx.cgContext.interpolationQuality = .none
+ let nsImage = NSImage(cgImage: croppedCG, size: NSSize(width: bounds.width, height: bounds.height))
+ nsImage.draw(
+ in: NSRect(x: 0, y: 0, width: outW, height: outH),
+ from: .zero,
+ operation: .copy,
+ fraction: 1
+ )
+ outCtx.flushGraphics()
+ NSGraphicsContext.restoreGraphicsState()
+
+ guard let pngData = outBitmap.representation(using: .png, properties: [:]) else { return nil }
+ let base64 = pngData.base64EncodedString()
+
+ // Adjust hotspot using the extracted source image scale so 2x cursor reps keep the correct anchor.
+ let hotspot = cursor.hotSpot
+ let hotspotPxX = hotspot.x * sourceScale * renderScale - CGFloat(bounds.x)
+ let hotspotPxY = hotspot.y * sourceScale * renderScale - CGFloat(bounds.y)
+ let scaleToOut = referencePixelHeight / CGFloat(bounds.height)
+ let outHotspotX = hotspotPxX * scaleToOut
+ let outHotspotY = hotspotPxY * scaleToOut
+
+ return CursorAsset(
+ dataUrl: "data:image/png;base64,\(base64)",
+ hotspotX: Double(outHotspotX),
+ hotspotY: Double(outHotspotY),
+ width: Double(outW),
+ height: Double(outH)
+ )
+}
+
+let cursorMap: [String: NSCursor] = [
+ "arrow": .arrow,
+ "text": .iBeam,
+ "pointer": .pointingHand,
+ "crosshair": .crosshair,
+ "open-hand": .openHand,
+ "closed-hand": .closedHand,
+ "resize-ew": .resizeLeftRight,
+ "resize-ns": .resizeUpDown,
+ "not-allowed": .operationNotAllowed,
+]
+
+var assets: [String: CursorAsset] = [:]
+for (key, cursor) in cursorMap {
+ if let asset = makeAsset(for: cursor) {
+ assets[key] = asset
+ }
+}
+
+let encoder = JSONEncoder()
+encoder.outputFormatting = [.sortedKeys]
+let data = try encoder.encode(assets)
+FileHandle.standardOutput.write(data)
+
diff --git a/electron/native/bin/darwin-arm64/openscreen-window-list b/electron/native/bin/darwin-arm64/openscreen-window-list
new file mode 100755
index 000000000..4cf4957bc
Binary files /dev/null and b/electron/native/bin/darwin-arm64/openscreen-window-list differ
diff --git a/electron/native/bin/darwin-arm64/recordly-native-cursor-monitor b/electron/native/bin/darwin-arm64/recordly-native-cursor-monitor
new file mode 100755
index 000000000..962161c1c
Binary files /dev/null and b/electron/native/bin/darwin-arm64/recordly-native-cursor-monitor differ
diff --git a/electron/native/bin/darwin-arm64/recordly-screencapturekit-helper b/electron/native/bin/darwin-arm64/recordly-screencapturekit-helper
new file mode 100755
index 000000000..233cfd172
Binary files /dev/null and b/electron/native/bin/darwin-arm64/recordly-screencapturekit-helper differ
diff --git a/electron/native/bin/darwin-arm64/recordly-system-cursors b/electron/native/bin/darwin-arm64/recordly-system-cursors
new file mode 100755
index 000000000..f4b41ab66
Binary files /dev/null and b/electron/native/bin/darwin-arm64/recordly-system-cursors differ
diff --git a/electron/native/bin/darwin-arm64/recordly-window-list b/electron/native/bin/darwin-arm64/recordly-window-list
new file mode 100755
index 000000000..76a7dab4a
Binary files /dev/null and b/electron/native/bin/darwin-arm64/recordly-window-list differ
diff --git a/electron/native/bin/darwin-arm64/whisper-bench b/electron/native/bin/darwin-arm64/whisper-bench
new file mode 100755
index 000000000..5d33dbf00
Binary files /dev/null and b/electron/native/bin/darwin-arm64/whisper-bench differ
diff --git a/electron/native/bin/darwin-arm64/whisper-cli b/electron/native/bin/darwin-arm64/whisper-cli
new file mode 100755
index 000000000..695c8c9a4
Binary files /dev/null and b/electron/native/bin/darwin-arm64/whisper-cli differ
diff --git a/electron/native/bin/darwin-arm64/whisper-quantize b/electron/native/bin/darwin-arm64/whisper-quantize
new file mode 100755
index 000000000..d51722d9b
Binary files /dev/null and b/electron/native/bin/darwin-arm64/whisper-quantize differ
diff --git a/electron/native/bin/darwin-arm64/whisper-runtime.json b/electron/native/bin/darwin-arm64/whisper-runtime.json
new file mode 100644
index 000000000..380d1adf6
--- /dev/null
+++ b/electron/native/bin/darwin-arm64/whisper-runtime.json
@@ -0,0 +1,6 @@
+{
+ "version": "v1.8.4",
+ "platform": "darwin",
+ "arch": "arm64",
+ "binary": "whisper-cli"
+}
diff --git a/electron/native/bin/darwin-arm64/whisper-server b/electron/native/bin/darwin-arm64/whisper-server
new file mode 100755
index 000000000..790c1fe82
Binary files /dev/null and b/electron/native/bin/darwin-arm64/whisper-server differ
diff --git a/electron/native/bin/darwin-arm64/whisper-vad-speech-segments b/electron/native/bin/darwin-arm64/whisper-vad-speech-segments
new file mode 100755
index 000000000..65e963b39
Binary files /dev/null and b/electron/native/bin/darwin-arm64/whisper-vad-speech-segments differ
diff --git a/electron/native/bin/darwin-x64/recordly-native-cursor-monitor b/electron/native/bin/darwin-x64/recordly-native-cursor-monitor
new file mode 100755
index 000000000..3e55919f1
Binary files /dev/null and b/electron/native/bin/darwin-x64/recordly-native-cursor-monitor differ
diff --git a/electron/native/bin/darwin-x64/recordly-screencapturekit-helper b/electron/native/bin/darwin-x64/recordly-screencapturekit-helper
new file mode 100755
index 000000000..8982873fb
Binary files /dev/null and b/electron/native/bin/darwin-x64/recordly-screencapturekit-helper differ
diff --git a/electron/native/bin/darwin-x64/recordly-system-cursors b/electron/native/bin/darwin-x64/recordly-system-cursors
new file mode 100755
index 000000000..545613624
Binary files /dev/null and b/electron/native/bin/darwin-x64/recordly-system-cursors differ
diff --git a/electron/native/bin/darwin-x64/recordly-window-list b/electron/native/bin/darwin-x64/recordly-window-list
new file mode 100755
index 000000000..e165257ae
Binary files /dev/null and b/electron/native/bin/darwin-x64/recordly-window-list differ
diff --git a/electron/native/bin/win32-x64/cursor-monitor.exe b/electron/native/bin/win32-x64/cursor-monitor.exe
new file mode 100644
index 000000000..70738d118
Binary files /dev/null and b/electron/native/bin/win32-x64/cursor-monitor.exe differ
diff --git a/electron/native/bin/win32-x64/helpers-manifest.json b/electron/native/bin/win32-x64/helpers-manifest.json
new file mode 100644
index 000000000..62ee78b5a
--- /dev/null
+++ b/electron/native/bin/win32-x64/helpers-manifest.json
@@ -0,0 +1,35 @@
+{
+ "version": 1,
+ "platform": "win32",
+ "arch": "x64",
+ "helpers": {
+ "wgc-capture": {
+ "binaryName": "wgc-capture.exe",
+ "binarySha256": "4d89fdff8e3343998c7a3b4d75d964c1f75f93594aa097c6681e477d25ec9f01",
+ "sourceDir": "electron/native/wgc-capture",
+ "sourceFingerprint": "c6dac250c9d16f7aa881998353441b4ae3fb59731b802e3b8491a136e79726b0",
+ "updatedAt": "2026-07-11T11:58:45.856Z"
+ },
+ "cursor-monitor": {
+ "binaryName": "cursor-monitor.exe",
+ "binarySha256": "f1d8f30e8d7bee19ecea91c9a90a95ea4824138b8336b18030fa0602a641d70d",
+ "sourceDir": "electron/native/cursor-monitor",
+ "sourceFingerprint": "45bb72e4039e061a354af87317d7c42ec3d2118369b3f4379046ff497b701e72",
+ "updatedAt": "2026-07-11T11:58:56.534Z"
+ },
+ "recordly-gpu-export": {
+ "binaryName": "recordly-gpu-export.exe",
+ "binarySha256": "49a2ac588206305d0129e6263ce4be49780c50a9dc4efc7df63aad09178a919f",
+ "sourceDir": "electron/native/gpu-export-probe",
+ "sourceFingerprint": "37a5842eba63cdeccfddd02cc278a98207248fb0aa6b56153fb85ed152c908c1",
+ "updatedAt": "2026-07-11T11:58:51.659Z"
+ },
+ "recordly-nvidia-cuda-compositor": {
+ "binaryName": "recordly-nvidia-cuda-compositor.exe",
+ "binarySha256": "250a3f8cac7c6ea38a873434d23d4b2be7d6555e42cc0b405aa26f774169159c",
+ "sourceDir": "electron/native/nvidia-cuda-compositor",
+ "sourceFingerprint": "de1219228ce326e96d1f4815a3763b10d5f235cc1286bc6542c99707a85d5947",
+ "updatedAt": "2026-05-27T11:29:32.957Z"
+ }
+ }
+}
diff --git a/electron/native/bin/win32-x64/recordly-gpu-export.exe b/electron/native/bin/win32-x64/recordly-gpu-export.exe
new file mode 100644
index 000000000..b9d1efc9e
Binary files /dev/null and b/electron/native/bin/win32-x64/recordly-gpu-export.exe differ
diff --git a/electron/native/bin/win32-x64/recordly-nvidia-cuda-compositor.exe b/electron/native/bin/win32-x64/recordly-nvidia-cuda-compositor.exe
new file mode 100644
index 000000000..c23c14f90
Binary files /dev/null and b/electron/native/bin/win32-x64/recordly-nvidia-cuda-compositor.exe differ
diff --git a/electron/native/bin/win32-x64/wgc-capture.exe b/electron/native/bin/win32-x64/wgc-capture.exe
new file mode 100644
index 000000000..a882ee87a
Binary files /dev/null and b/electron/native/bin/win32-x64/wgc-capture.exe differ
diff --git a/electron/native/common/bt709_video.h b/electron/native/common/bt709_video.h
new file mode 100644
index 000000000..f4758dcce
--- /dev/null
+++ b/electron/native/common/bt709_video.h
@@ -0,0 +1,66 @@
+#pragma once
+
+#include
+#include
+#include
+#include
+
+inline int clampVideoSample(int value, int minimum, int maximum) {
+ return value < minimum ? minimum : (value > maximum ? maximum : value);
+}
+
+inline HRESULT setBt709LimitedVideoAttributes(IMFMediaType* mediaType) {
+ HRESULT result = mediaType->SetUINT32(MF_MT_VIDEO_PRIMARIES, MFVideoPrimaries_BT709);
+ if (FAILED(result)) return result;
+ result = mediaType->SetUINT32(MF_MT_TRANSFER_FUNCTION, MFVideoTransFunc_709);
+ if (FAILED(result)) return result;
+ result = mediaType->SetUINT32(MF_MT_YUV_MATRIX, MFVideoTransferMatrix_BT709);
+ if (FAILED(result)) return result;
+ return mediaType->SetUINT32(MF_MT_VIDEO_NOMINAL_RANGE, MFNominalRange_16_235);
+}
+
+inline void convertBgraToBt709LimitedNv12(
+ const uint8_t* bgra,
+ int bgraPitch,
+ int width,
+ int height,
+ std::vector& nv12Buffer) {
+ for (int y = 0; y < height; ++y) {
+ for (int x = 0; x < width; ++x) {
+ const uint8_t* pixel = bgra + y * bgraPitch + x * 4;
+ const int blue = pixel[0];
+ const int green = pixel[1];
+ const int red = pixel[2];
+ const int luma = ((47 * red + 157 * green + 16 * blue + 128) >> 8) + 16;
+ nv12Buffer[y * width + x] = static_cast(clampVideoSample(luma, 16, 235));
+ }
+ }
+
+ uint8_t* uvPlane = nv12Buffer.data() + width * height;
+ for (int y = 0; y < height; y += 2) {
+ for (int x = 0; x < width; x += 2) {
+ int red = 0;
+ int green = 0;
+ int blue = 0;
+ for (int offsetY = 0; offsetY < 2; ++offsetY) {
+ for (int offsetX = 0; offsetX < 2; ++offsetX) {
+ const uint8_t* pixel =
+ bgra + (y + offsetY) * bgraPitch + (x + offsetX) * 4;
+ blue += pixel[0];
+ green += pixel[1];
+ red += pixel[2];
+ }
+ }
+ red = (red + 2) / 4;
+ green = (green + 2) / 4;
+ blue = (blue + 2) / 4;
+
+ // Coefficients sum to zero so neutral greys remain neutral after quantization.
+ const int chromaBlue = ((-26 * red - 87 * green + 113 * blue + 128) >> 8) + 128;
+ const int chromaRed = ((112 * red - 102 * green - 10 * blue + 128) >> 8) + 128;
+ const int uvIndex = (y / 2) * width + x;
+ uvPlane[uvIndex] = static_cast(clampVideoSample(chromaBlue, 16, 240));
+ uvPlane[uvIndex + 1] = static_cast(clampVideoSample(chromaRed, 16, 240));
+ }
+ }
+}
diff --git a/electron/native/cursor-monitor/CMakeLists.txt b/electron/native/cursor-monitor/CMakeLists.txt
new file mode 100644
index 000000000..8155aed95
--- /dev/null
+++ b/electron/native/cursor-monitor/CMakeLists.txt
@@ -0,0 +1,9 @@
+cmake_minimum_required(VERSION 3.20)
+project(cursor-monitor LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_executable(cursor-monitor src/main.cpp)
+
+target_link_libraries(cursor-monitor PRIVATE user32)
diff --git a/electron/native/cursor-monitor/src/main.cpp b/electron/native/cursor-monitor/src/main.cpp
new file mode 100644
index 000000000..9a811f7be
--- /dev/null
+++ b/electron/native/cursor-monitor/src/main.cpp
@@ -0,0 +1,60 @@
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+static std::atomic g_running{true};
+
+static void stdinListener() {
+ std::string line;
+ while (std::getline(std::cin, line)) {
+ if (line == "stop") {
+ g_running.store(false);
+ return;
+ }
+ }
+ g_running.store(false);
+}
+
+int main() {
+ std::setvbuf(stdout, nullptr, _IONBF, 0);
+
+ std::unordered_map cursorMap;
+ cursorMap[LoadCursor(NULL, IDC_ARROW)] = "arrow";
+ cursorMap[LoadCursor(NULL, IDC_IBEAM)] = "text";
+ cursorMap[LoadCursor(NULL, IDC_HAND)] = "pointer";
+ cursorMap[LoadCursor(NULL, IDC_CROSS)] = "crosshair";
+ cursorMap[LoadCursor(NULL, IDC_NO)] = "not-allowed";
+ cursorMap[LoadCursor(NULL, IDC_SIZEWE)] = "resize-ew";
+ cursorMap[LoadCursor(NULL, IDC_SIZENS)] = "resize-ns";
+ cursorMap[LoadCursor(NULL, IDC_SIZEALL)] = "open-hand";
+ cursorMap[LoadCursor(NULL, IDC_WAIT)] = "arrow";
+ cursorMap[LoadCursor(NULL, IDC_APPSTARTING)] = "arrow";
+
+ std::thread listener(stdinListener);
+ listener.detach();
+
+ std::string lastType;
+
+ while (g_running.load()) {
+ CURSORINFO ci = {};
+ ci.cbSize = sizeof(ci);
+
+ if (GetCursorInfo(&ci) && (ci.flags & CURSOR_SHOWING)) {
+ auto it = cursorMap.find(ci.hCursor);
+ std::string type = (it != cursorMap.end()) ? it->second : "arrow";
+
+ if (type != lastType) {
+ lastType = type;
+ std::cout << "STATE:" << type << std::endl;
+ }
+ }
+
+ Sleep(50);
+ }
+
+ return 0;
+}
diff --git a/electron/native/gpu-export-probe/CMakeLists.txt b/electron/native/gpu-export-probe/CMakeLists.txt
new file mode 100644
index 000000000..31a718a0c
--- /dev/null
+++ b/electron/native/gpu-export-probe/CMakeLists.txt
@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 3.20)
+project(gpu-export-probe LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_executable(gpu-export-probe
+ src/main.cpp
+)
+
+set(NVIDIA_VIDEO_SDK_SAMPLES_DIR "${CMAKE_CURRENT_LIST_DIR}/../../../.tmp/video-sdk-samples/Samples")
+set(NVIDIA_NVENC_SDK_DIR "${NVIDIA_VIDEO_SDK_SAMPLES_DIR}/NvCodec")
+if(EXISTS "${NVIDIA_NVENC_SDK_DIR}/NvEncoder/NvEncoderD3D11.cpp")
+ target_sources(gpu-export-probe PRIVATE
+ "${NVIDIA_NVENC_SDK_DIR}/NvEncoder/NvEncoder.cpp"
+ "${NVIDIA_NVENC_SDK_DIR}/NvEncoder/NvEncoderD3D11.cpp"
+ )
+ target_include_directories(gpu-export-probe PRIVATE
+ "${NVIDIA_VIDEO_SDK_SAMPLES_DIR}"
+ "${NVIDIA_NVENC_SDK_DIR}"
+ )
+ target_compile_definitions(gpu-export-probe PRIVATE RECORDLY_GPU_EXPORT_ENABLE_NVENC_SDK=1)
+endif()
+
+target_compile_options(gpu-export-probe PRIVATE /EHsc /W4 /utf-8)
+
+target_link_libraries(gpu-export-probe PRIVATE
+ d3d11
+ d3dcompiler
+ dxgi
+ mfplat
+ mfreadwrite
+ mf
+ mfuuid
+ ole32
+ windowscodecs
+)
diff --git a/electron/native/gpu-export-probe/src/main.cpp b/electron/native/gpu-export-probe/src/main.cpp
new file mode 100644
index 000000000..158f103f7
--- /dev/null
+++ b/electron/native/gpu-export-probe/src/main.cpp
@@ -0,0 +1,3390 @@
+#define NOMINMAX
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+#include
+
+#ifdef RECORDLY_GPU_EXPORT_ENABLE_NVENC_SDK
+#include "NvEncoder/NvEncoderD3D11.h"
+#endif
+
+#pragma comment(lib, "d3d11.lib")
+#pragma comment(lib, "d3dcompiler.lib")
+#pragma comment(lib, "dxgi.lib")
+#pragma comment(lib, "mfplat.lib")
+#pragma comment(lib, "mfreadwrite.lib")
+#pragma comment(lib, "mf.lib")
+#pragma comment(lib, "mfuuid.lib")
+#pragma comment(lib, "windowscodecs.lib")
+
+using Microsoft::WRL::ComPtr;
+
+namespace {
+
+struct Options {
+ std::wstring inputPath;
+ std::wstring outputPath = L"gpu-export-probe.mp4";
+ UINT width = 1920;
+ UINT height = 1080;
+ UINT fps = 30;
+ double seconds = 60.0;
+ UINT bitrate = 12'000'000;
+ bool shaderComposite = false;
+ float radius = 32.0f;
+ float shadow = 36.0f;
+ float padding = 0.0f;
+ LONG contentLeft = -1;
+ LONG contentTop = -1;
+ LONG contentWidth = 0;
+ LONG contentHeight = 0;
+ LONG sourceCropLeft = 0;
+ LONG sourceCropTop = 0;
+ LONG sourceCropWidth = 0;
+ LONG sourceCropHeight = 0;
+ float backgroundR = 0.035f;
+ float backgroundG = 0.035f;
+ float backgroundB = 0.045f;
+ float backgroundBlurPx = 0.0f;
+ std::wstring backgroundImagePath;
+ std::wstring webcamInputPath;
+ LONG webcamLeft = -1;
+ LONG webcamTop = -1;
+ LONG webcamSize = 0;
+ float webcamRadius = 18.0f;
+ float webcamShadow = 0.0f;
+ bool webcamMirror = false;
+ double webcamTimeOffsetMs = 0.0;
+ std::wstring cursorTelemetryPath;
+ std::wstring cursorAtlasPath;
+ std::wstring cursorAtlasMetadataPath;
+ float cursorSize = 84.0f;
+ std::wstring zoomTelemetryPath;
+ std::wstring timelineMapPath;
+ bool preferHighPerformanceAdapter = false;
+ int adapterIndex = -1;
+ bool fastEncoderTuning = false;
+ UINT surfacePoolSize = 4;
+ bool nvencSdk = false;
+};
+
+struct ShaderConstants {
+ float outputWidth;
+ float outputHeight;
+ float radius;
+ float shadowSize;
+ float contentLeft;
+ float contentTop;
+ float contentRight;
+ float contentBottom;
+ float backgroundR;
+ float backgroundG;
+ float backgroundB;
+ float backgroundA;
+ float shadowR;
+ float shadowG;
+ float shadowB;
+ float shadowA;
+ float backgroundImageEnabled;
+ float backgroundImageWidth;
+ float backgroundImageHeight;
+ float webcamEnabled;
+ float webcamLeft;
+ float webcamTop;
+ float webcamRight;
+ float webcamBottom;
+ float webcamRadius;
+ float webcamShadowSize;
+ float webcamShadowA;
+ float webcamMirror;
+ float cursorEnabled;
+ float cursorX;
+ float cursorY;
+ float cursorSize;
+ float cursorAtlasEnabled;
+ float cursorAtlasLeft;
+ float cursorAtlasTop;
+ float cursorAtlasRight;
+ float cursorAtlasBottom;
+ float cursorAtlasAnchorX;
+ float cursorAtlasAnchorY;
+ float cursorAtlasAspect;
+ float cursorBounceScale;
+ float backgroundBlurPx;
+ float backgroundBlurPadding0;
+ float backgroundBlurPadding1;
+ float zoomEnabled;
+ float zoomScale;
+ float zoomX;
+ float zoomY;
+};
+
+struct CursorSample {
+ double timeMs = 0.0;
+ float cx = 0.0f;
+ float cy = 0.0f;
+ int cursorTypeIndex = 0;
+ float bounceScale = 1.0f;
+ bool visible = true;
+};
+
+struct CursorAtlasEntry {
+ float x = 0.0f;
+ float y = 0.0f;
+ float width = 1.0f;
+ float height = 1.0f;
+ float anchorX = 0.0f;
+ float anchorY = 0.0f;
+ float aspectRatio = 1.0f;
+ bool valid = false;
+};
+
+struct ZoomSample {
+ double timeMs = 0.0;
+ float scale = 1.0f;
+ float x = 0.0f;
+ float y = 0.0f;
+};
+
+struct TimelineSegment {
+ double sourceStartMs = 0.0;
+ double sourceEndMs = 0.0;
+ double outputStartMs = 0.0;
+ double outputEndMs = 0.0;
+ double speed = 1.0;
+};
+
+struct Timer {
+ std::chrono::steady_clock::time_point start = std::chrono::steady_clock::now();
+
+ double elapsedMs() const {
+ const auto now = std::chrono::steady_clock::now();
+ return std::chrono::duration(now - start).count();
+ }
+};
+
+std::wstring getArgValue(const std::vector& args, const std::wstring& key) {
+ for (size_t i = 0; i + 1 < args.size(); ++i) {
+ if (args[i] == key) {
+ return args[i + 1];
+ }
+ }
+ return L"";
+}
+
+UINT parseUIntArg(const std::vector& args, const std::wstring& key, UINT fallback) {
+ const auto value = getArgValue(args, key);
+ if (value.empty()) {
+ return fallback;
+ }
+
+ try {
+ return static_cast(std::stoul(value));
+ } catch (...) {
+ return fallback;
+ }
+}
+
+LONG parseLongArg(const std::vector& args, const std::wstring& key, LONG fallback) {
+ const auto value = getArgValue(args, key);
+ if (value.empty()) {
+ return fallback;
+ }
+
+ try {
+ return static_cast(std::stol(value));
+ } catch (...) {
+ return fallback;
+ }
+}
+
+float parseFloatArg(const std::vector& args, const std::wstring& key, float fallback) {
+ const auto value = getArgValue(args, key);
+ if (value.empty()) {
+ return fallback;
+ }
+
+ try {
+ return std::stof(value);
+ } catch (...) {
+ return fallback;
+ }
+}
+
+double parseDoubleArg(const std::vector 
-
- 
- 
-
+
+
+
+
+