Recordly 深度教學：開源螢幕錄影與影片編輯利器

目錄

1. 專案概覽
2. 核心價值與使用場景
3. 系統架構
4. 安裝與建置指南
5. 功能深度解析
6. 資安審查報告
7. Extension 系統與 Marketplace
8. 原生層技術剖析
9. 效能最佳化與 GPU 加速
10. 常見問題與限制
11. 總結與評估

1. 專案概覽

Recordly 是一款開源跨平台桌面螢幕錄影與影片編輯應用程式，目標是讓使用者在錄製螢幕後，不需要專業影片編輯軟體（如 After Effects、Premiere），就能直接在 app 內產出具有「自動縮放 (auto-zoom)」、「游標美化 (cursor polish)」、「網路攝影機疊加 (webcam overlay)」等專業效果的展示影片。

起源：Recordly 最初從 OpenScreen fork 而來，目前已有超過 80% 的程式碼分歧，由 @webadderall 獨立維護。

定位對標：Screen Studio（付費，macOS 限定）的開源免費替代品，且支援三大平台。

2. 核心價值與使用場景

2.1 核心價值主張

1. 零門檻影片美化：錄製完成後，自動偵測游標活動區域並建議縮放，無需手動設定關鍵影格
2. 一站式工作流：從錄製 → 編輯 → 匯出全部在同一個 app 內完成
3. 三平台支援：macOS/Windows/Linux 一致體驗
4. 完全開源免費：AGPL-3.0 授權，可自行建置與修改
5. 社群 Extension 生態：透過 Marketplace 擴充功能

2.2 適用場景

2.3 競品比較

3. 系統架構

3.1 高階架構圖

graph TB
    subgraph "Recordly Application"
        subgraph "Renderer Process (React)"
            UI["UI Layer
React + Radix UI + Tailwind"]
            VE["Video Editor
Timeline + Settings"]
            VP["Video Playback
PixiJS Renderer"]
            EXT_UI["Extension Manager UI"]
        end

        subgraph "Main Process (Electron)"
            MAIN["Main Process
Window Management"]
            IPC["IPC Handlers
Recording / Export / Captions"]
            EXT["Extension Loader
Manifest Validation"]
            UPD["Auto Updater
electron-updater"]
            MS["Media Server
Local HTTP"]
        end

        subgraph "Native Helpers"
            MAC_SCK["macOS
ScreenCaptureKit Helper"]
            MAC_CURSOR["macOS
Cursor Monitor (Swift)"]
            WIN_WGC["Windows
WGC Capture (C++)"]
            WIN_WASAPI["Windows
WASAPI Audio (C++)"]
            CUDA["NVIDIA
CUDA Compositor"]
            WHISPER["Whisper
Speech-to-Text"]
        end

        subgraph "Export Pipeline"
            FFMPEG["FFmpeg
Static Binary"]
            PIXI["PixiJS
Scene Composition"]
            MP4["MP4 Output"]
            GIF["GIF Output"]
        end
    end

    UI --> VE
    VE --> VP
    VP --> PIXI
    UI <-->|contextBridge| IPC
    IPC --> MAC_SCK
    IPC --> WIN_WGC
    IPC --> WIN_WASAPI
    IPC --> CUDA
    IPC --> WHISPER
    IPC --> FFMPEG
    PIXI --> MP4
    PIXI --> GIF
    MAIN --> UPD
    MAIN --> MS
    MAIN --> EXT
    EXT_UI <--> EXT

3.2 目錄結構

 1Recordly/
 2├── electron/                  # Electron 主程序
 3│   ├── main.ts                # 應用入口 + 視窗管理
 4│   ├── preload.ts             # contextBridge API 暴露
 5│   ├── windows.ts             # BrowserWindow 建立邏輯
 6│   ├── updater.ts             # 自動更新系統
 7│   ├── mediaServer.ts         # 本地媒體伺服器
 8│   ├── ipc/                   # IPC 處理器
 9│   │   ├── recording/         # 錄製邏輯（mac/win/linux）
10│   │   ├── export/            # 匯出邏輯（含 native video）
11│   │   ├── captions/          # Whisper 語音轉文字
12│   │   ├── cursor/            # 游標追蹤/遙測
13│   │   ├── ffmpeg/            # FFmpeg 濾鏡/二進位
14│   │   ├── project/           # 專案檔管理
15│   │   └── register/          # IPC handler 註冊
16│   ├── extensions/            # Extension 載入/驗證/Marketplace
17│   └── native/                # 平台原生 helper
18│       ├── ScreenCaptureKitRecorder.swift
19│       ├── NativeCursorMonitor.swift
20│       ├── wgc-capture/       # Windows Graphics Capture (C++)
21│       ├── windows-capture/   # Windows DXGI 擷取 (C++)
22│       ├── nvidia-cuda-compositor/  # CUDA GPU 合成器
23│       └── cursor-monitor/    # 跨平台游標監控 (C++)
24├── src/                       # React 前端
25│   ├── components/
26│   │   ├── video-editor/      # 編輯器核心（40+ 檔案）
27│   │   ├── launch/            # 啟動/錄製介面
28│   │   ├── ui/                # shadcn/ui 元件
29│   │   └── countdown/         # 倒數計時 overlay
30│   ├── hooks/                 # 自訂 hooks
31│   ├── contexts/              # Theme/Shortcuts/I18n context
32│   ├── lib/                   # 共用工具函式
33│   ├── i18n/                  # 國際化設定
34│   └── utils/                 # 平台/比例工具
35├── scripts/                   # 建置腳本（native helpers, release）
36├── public/                    # 靜態資源（wallpapers, WASM）
37└── branding/                  # Logo 與圖示素材

3.3 技術棧一覽

3.4 資料流

sequenceDiagram
    participant U as 使用者
    participant R as Renderer (React)
    participant M as Main Process
    participant N as Native Helper
    participant F as FFmpeg

    U->>R: 選擇螢幕源 + 開始錄製
    R->>M: IPC: start-recording
    M->>N: 啟動原生擷取 (SCK/WGC/Electron)
    N-->>M: 影音資料流
    M-->>R: 錄製狀態更新

    U->>R: 停止錄製
    R->>M: IPC: stop-recording
    M->>N: 停止擷取
    M-->>R: 開啟編輯器 + 載入影片

    U->>R: 編輯（縮放/修剪/標註/游標/webcam）
    R->>R: PixiJS 即時預覽

    U->>R: 匯出 MP4/GIF
    R->>M: IPC: start-export
    M->>F: FFmpeg 編碼管線
    M->>N: (可選) CUDA 合成
    F-->>M: 匯出完成
    M-->>R: 匯出結果

4. 安裝與建置指南

4.1 快速安裝（預建版本）

直接從 GitHub Releases 下載對應平台的安裝檔。

目前最新穩定版：v1.3.3

4.2 Arch Linux / Manjaro

1yay -S recordly-bin

4.3 從原始碼建置

前置需求

macOS：

1xcode-select --install

Linux (Ubuntu/Debian)：

1sudo apt install build-essential cmake libx11-dev libxtst-dev libxrandr-dev libxt-dev

Windows：Visual Studio 2022 + C++ workload + CMake

建置步驟

 1# 1. 取得原始碼
 2git clone https://github.com/webadderallorg/Recordly.git recordly
 3cd recordly
 4
 5# 2. 安裝依賴
 6npm install
 7
 8# 3. 開發模式執行
 9npm run dev
10
11# 4. 打包建置
12npm run build           # 自動偵測平台
13npm run build:mac       # macOS
14npm run build:win       # Windows
15npm run build:linux     # Linux

建置腳本說明

4.4 macOS 建置後注意事項

本地建置的 app 可能被 macOS quarantine 阻擋：

1xattr -rd com.apple.quarantine /Applications/Recordly.app

5. 功能深度解析

5.1 錄製系統

Recordly 的錄製系統根據作業系統使用不同的原生後端：

錄製流程：

1. 啟動 Recordly → 選擇螢幕/視窗源
2. 設定麥克風與系統音訊選項
3. 倒數計時後開始錄製
4. 停止錄製 → 自動進入編輯器

5.2 時間軸編輯器

編輯器是 Recordly 的核心差異化功能。基於 React 構建，使用 PixiJS 進行即時場景合成預覽。

主要功能：

• 修剪 (Trim)：選取時間範圍移除不需要的段落
• 縮放 (Zoom)：手動設定或使用自動建議的縮放區域，v1.3.0 後使用「camera physics」讓縮放過渡更自然
• 速度調整 (Speed)：加速/減速指定區域
• 標註 (Annotation)：新增文字、圖片、圖形標註
• 音訊區域 (Audio Region)：疊加額外音訊
• 裁切 (Crop)：裁切錄製畫面
• 復原/重做 (Undo/Redo)：完整的編輯歷史記錄

5.3 游標系統

Recordly 不直接使用系統游標，而是渲染一個獨立的「美化游標疊加」，並提供以下控制：

5.4 匯出管線

graph LR
    subgraph "Export Pipeline"
        EDITOR["編輯器狀態"] --> PIXI["PixiJS
場景渲染"]
        PIXI --> FRAMES["影格序列"]
        FRAMES --> |MP4| FFMPEG["FFmpeg
H.264 編碼"]
        FRAMES --> |GIF| GIFENC["GIF
編碼器"]
        FRAMES --> |CUDA| CUDA["NVIDIA
CUDA 合成"]
        CUDA --> FFMPEG
        FFMPEG --> OUTPUT["輸出檔案"]
        GIFENC --> OUTPUT
    end

匯出選項：

• MP4：標準 H.264 影片，品質可調
• GIF：輕量分享格式，可調幀率/迴圈/尺寸
• Lightning Export (Beta)：使用 WebCodecs 加速（實驗性）
• CUDA Export：NVIDIA GPU 加速合成，顯著降低匯出時間

5.5 專案持久化

Recordly 使用 .recordly 專案檔儲存編輯器狀態，包含：

• 來源媒體路徑
• 時間軸區域設定（zoom/trim/speed/annotation）
• 游標與 webcam 設定
• 框架造型設定
• 匯出偏好

這讓使用者可以隨時儲存、關閉、再重新開啟繼續編輯。

6. 資安審查報告

6.1 整體評級

6.2 詳細發現

🟢 Electron 安全配置（良好）

所有 5 個 BrowserWindow 實例均正確設定：

1webPreferences: {
2    nodeIntegration: false,     // 禁止 renderer 直接存取 Node.js
3    contextIsolation: true,     // 啟用 context 隔離
4}

透過 contextBridge.exposeInMainWorld("electronAPI", {...}) 安全暴露 API，符合 Electron 安全最佳實踐。

🟡 預編譯 Native Binary

electron/native/bin/ 目錄下包含預編譯的二進位檔案：

• macOS arm64: 11 個 binary（含 whisper、ScreenCaptureKit helper、cursor monitor 等）
• macOS x64: 4 個 binary
• Windows x64: 5 個 binary（.exe）

風險評估：這些 binary 由專案維護者編譯，原始碼在 electron/native/ 下可驗證。但使用者應注意，預編譯 binary 的供應鏈安全取決於維護者的建置環境。

🟡 Extension 系統

Extension loader (electron/extensions/extensionLoader.ts) 實作了 manifest 驗證機制。但社群開發的 extension 可能包含任意 JavaScript，使用者安裝第三方 extension 前應評估信任度。

🟢 無遙測

專案不包含任何第三方分析或遙測 SDK。grep 結果中的 “telemetry” 命中僅為游標追蹤資料結構（CursorTelemetryPoint）和 CSS class 名稱中的 “tracking”（字間距），非隱私追蹤。

6.3 建議

1. Extension 安全：安裝社群 extension 前，建議先檢視其原始碼
2. Native Binary 驗證：如有安全需求，可自行從原始碼重新編譯 native helpers
3. 自動更新：建議啟用但設定手動安裝（目前預設 autoDownload: false），先確認版本再更新

7. Extension 系統與 Marketplace

7.1 架構

Recordly 的 Extension 系統允許社群開發者擴充應用功能：

7.2 Extension 能力

根據文件，Extension 可提供：

• 游標點擊音效
• 裝置框架（手機/平板外框）
• 瀏覽器模型
• 桌布/背景
• 渲染 hooks
• 設定面板

7.3 Marketplace

Recordly Marketplace 提供瀏覽與安裝社群 extension 的入口。Extension Manager UI 整合在編輯器中，方便管理已安裝的 extension。

8. 原生層技術剖析

8.1 macOS 原生 (Swift)

macOS 14.0+ 限制：ScreenCaptureKit 是 macOS 14 引入的現代擷取框架，提供比舊版 CGWindowListCopyWindowInfo 更高效的螢幕/音訊擷取能力。

8.2 Windows 原生 (C++)

兩套擷取管線並存：

WGC Capture（主要）：

• wgc-capture/: Windows Graphics Capture API
• 包含 WGC session 管理、WASAPI loopback 音訊、Media Foundation 編碼
• 需 Windows 10 Build 19041+

DXGI Capture（備用）：

• windows-capture/: DXGI Desktop Duplication
• 較舊的擷取方式，作為 WGC 不支援時的 fallback

8.3 CUDA 合成器

nvidia-cuda-compositor/src/main.cu (~3.3K 行) 提供 GPU 加速的影片合成：

• 在 NVIDIA GPU 上進行場景合成（背景 + 影片 + 游標 + webcam）
• 透過 Media Foundation Sink Writer 輸出 H.264
• 顯著降低 MP4 匯出時間

8.4 Whisper 整合

Recordly 內建 Whisper 語音辨識 runtime，用於自動字幕生成：

• 本地執行，無需雲端 API
• macOS arm64 提供預編譯 binary
• 支援 VAD (Voice Activity Detection) 分段

9. 效能最佳化與 GPU 加速

9.1 GPU 相關設定

Recordly 主程序啟動時設定了多項 GPU 最佳化：

1app.commandLine.appendSwitch("ignore-gpu-blocklist");
2app.commandLine.appendSwitch("enable-unsafe-webgpu");
3app.commandLine.appendSwitch("enable-gpu-rasterization");

另有平台特定的 GPU 切換邏輯（gpuSwitches.ts），根據作業系統與環境變數調整 ANGLE/GL 後端。

9.2 NVIDIA CUDA Export

對於配備 NVIDIA GPU 的系統，可啟用 CUDA 加速匯出：

• 在編輯器設定中 opt-in（useNvidiaCudaExportOptIn.ts）
• 透過 recordly-nvidia-cuda-compositor native binary 執行
• 利用 GPU 平行處理場景合成，大幅縮短匯出時間

9.3 匯出管線最佳化

• Export Stream：串流式匯出，避免一次性載入所有影格到記憶體
• Native Video Export：繞過 WebCodecs，直接使用原生 FFmpeg/MF 編碼
• 靜態佈局路由規劃：根據場景複雜度自動選擇最佳匯出路徑

10. 常見問題與限制

10.1 平台限制

10.2 已知活躍問題

根據近期 Issues，目前社群回報的主要問題：

• 音訊問題：錄音斷斷續續 (#667) / 音訊迴音 (#662) / 音訊問題 (#658)
• 匯出問題：Lightning Beta 在 Linux 失敗 (#644)
• HUD 互動：無法與浮動視窗後方的應用互動 (#657)
• 裁切延遲：裁切操作時出現 lag (#603)

10.3 macOS 疑難排解

「App cannot be opened」錯誤：

1xattr -rd com.apple.quarantine /Applications/Recordly.app

ScreenCaptureKit 權限：

• 系統偏好設定 → 隱私與安全 → 螢幕錄製 → 啟用 Recordly
• 系統偏好設定 → 隱私與安全 → 輔助使用 → 啟用 Recordly

11. 總結與評估

11.1 優勢

11.2 風險與考量

1. AGPL-3.0 授權：任何修改或 SaaS 使用都必須開源全部程式碼，對商業使用有嚴格限制
2. 單一維護者：目前主要由 @webadderall 一人維護，長期可持續性取決於社群成長
3. 預編譯 binary：repo 內含預編譯 native binary，供應鏈安全需信任維護者
4. Linux 體驗：游標隱藏不支援 + 系統音訊依賴 PipeWire，Linux 使用者體驗明顯弱於 macOS/Windows

11.3 適用建議

11.4 未來展望

根據近期 commit 與 issue 趨勢，Recordly 正在以下方向發展：

• 字幕系統：Whisper 整合 + SRT/VTT 匯出
• Extension 生態：社群 extension 數量持續增長
• 效能提升：CUDA 匯出 + WebCodecs Lightning 實驗
• 國際化：多語言支援持續擴展（印尼語等新語言 PR）
• 點擊效果：v1.3.x 引入 click effects 與 spotlight 特效