AIEraDev/Clypra

# Clypra ## 概述 Clypra 是一款**免费、开源的视频编辑器**（MIT License），具备专业级功能。核心编辑器、特效引擎以及所有 UI 组件永久免费——无水印、无功能限制、无需订阅。 想要 AI 超能力？可选的 [Pro 功能](#pro-features-ai-layer) 提供自然语言编辑、自动字幕、智能重构图等更多功能。 ### 目标平台 - **桌面端**：macOS (Apple Silicon & Intel)、Windows、Linux - **移动端**：iOS（通过 Capacitor）、Android（通过 Capacitor） ## 功能 ### 核心剪辑 - **多格式媒体导入**：MP4、MOV、WebM、MKV、M4V、AVI（视频）；MP3、WAV、AAC（音频）；JPG、PNG、WebP（图像） - **逐帧精确修剪**：具备毫秒级精度的精准时间轴控制 - **多轨时间轴**：带标尺和视觉反馈的专业时间轴界面 - **撤销/重做系统**：采用命令模式架构的 100 级历史记录栈 ### 专业音频 - **高保真波形**：峰值 + RMS 可视化与镜像显示（[技术细节](WAVEFORM_RENDERING.md)） - **音频同步**：在播放和导出期间实现帧精确的音视频同步 - **音量控制**：支持实时预览的逐片段音量调整 ### 视觉特性 - **胶片条缩略图**：硬件加速的缩略图生成，具备自适应密度 - **文本叠加**：用于标题和字幕的自定义字体、样式和动画 - **预览画布**：带变换控制的实时合成 ### 性能 - **硬件加速**：通过 FFmpeg 进行原生 GPU 解码 (VideoToolbox/D3D11VA/VAAPI) - **解码器预热**：通过预测性解码器初始化实现低于 10ms 的首帧延迟 - **并行处理**：使用 Web Worker 池生成缩略图（渲染速度提升 2-4 倍） - **高效缓存**：带有 20 个并发解码器的基于 LRU 的解码器池 - **实时监控**：跨视频流水线跟踪 30 多项性能指标 ### 项目管理 - **持久化项目**：基于 SQLite 的项目存储，支持自动保存 - **媒体库**：带有元数据缓存的集中式资产管理 - **导出流水线**：基于 FFmpeg 的导出，支持编解码器选择 (H.264, H.265, ProRes) ## 架构 Clypra 的架构定位为**原生桌面和移动应用**，在前端 UI 和后端处理之间实现了清晰的分离。 ### 技术栈 **前端** - React 19 结合 TypeScript（严格模式） - Zustand 用于状态管理（按领域分离的 store） - Vite 用于构建工具和热模块替换 **后端** - Rust 结合 Tauri v2 用于原生平台集成 - FFmpeg（通过 ffmpeg-next）用于视频/音频处理 - 硬件加速：VideoToolbox (macOS)、D3D11VA (Windows)、VAAPI (Linux) - DashMap 用于并发数据结构 **移动端** - Capacitor 用于 iOS/Android 部署 - 原生桥接用于平台特定功能 ### 设计原则 1. **原生性能**：Rust FFmpeg 后端消除了浏览器的限制 2. **桌面优先架构**：针对桌面级工作流进行优化，可移植到移动端 3. **硬件加速**：通过原生 FFmpeg 硬件解码器直接访问 GPU 4. **高效 IPC**：对 Tauri 命令进行了优化，以最小化序列化开销 5. **零浏览器依赖**：不依赖 WebCodecs、MSE 或特定于 Web 的 API ### 视频流水线架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (React/TS) │ │ ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐ │ │ │ Timeline UI │ │ Preview Canvas│ │ Filmstrip Cache │ │ │ └──────┬───────┘ └──────┬────────┘ └────────┬────────┘ │ │ │ │ │ │ │ └─────────────────┴─────────────────────┘ │ │ │ │ │ Tauri IPC Layer │ │ │ │ └───────────────────────────┼─────────────────────────────────┘ │ ┌───────────────────────────┼─────────────────────────────────┐ │ Backend (Rust/FFmpeg) │ │ ┌─────────────────┴──────────────────┐ │ │ │ Decoder Pool (LRU, size=20) │ │ │ │ ┌──────────────────────────────┐ │ │ │ │ │ Hardware Decoder Context │ │ │ │ │ │ (VideoToolbox/D3D11/VAAPI) │ │ │ │ │ └──────────────────────────────┘ │ │ │ └─────────────┬────────────────────┬─┘ │ │ │ │ │ │ ┌─────────────▼────────┐ ┌────────▼──────────┐ │ │ │ Frame Decoder │ │ Export Pipeline │ │ │ │ (seek + decode) │ │ (encode + mux) │ │ │ └──────────────────────┘ └───────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### 关键优化 **解码器预热** - 在项目加载时初始化解码器（消除 50-100ms 的冷启动时间） - 并发预热（一次 4 个解码器） - 首帧延迟：5-10ms（无预热时为 50-100ms） **缩略图生成** - Web Worker 池（CPU 核心数 - 1，最多 4 个） - 通过 Transferable 实现零拷贝 ImageBitmap 传输 - 滚动期间主线程 CPU 占用减少 60% **批处理** - 基于图集的缩略图存储（减少 90% 的 IPC 开销） - 基于通道交付的流式解码 - 并发帧解码（同时处理多达 20 个视频） **顺序解码优化** - 智能寻址：在 GOP 边界内进行正向解码（避免冗余寻址） - 顺序命中跟踪：检测擦洗模式 - 在时间轴导航期间减少 70% 的寻址操作 有关详细的性能指标和优化路线图，请参阅 [PERFORMANCE-DESKTOP-ROADMAP.md](./PERFORMANCE-DESKTOP-ROADMAP.md)。 ## 安装说明 ### 二进制发布版 所有支持的平台均提供预构建的二进制文件。可从[最新发布版](https://github.com/AIEraDev/Clypra/releases/latest)下载。 #### macOS **推荐：Homebrew 安装** ``` brew install AIEraDev/tap/clypra ``` 此方法会自动处理 Gatekeeper 授权和更新。 **替代方案：直接下载** 1. 从发布版中下载 `Clypra-universal.dmg` 2. 打开 DMG 文件并将 Clypra 拖至 `/Applications` 3. 右键点击应用图标并选择“打开”，以授权首次启动 支持：macOS 11+（Big Sur 及更高版本），同时支持 Apple Silicon 和 Intel #### Windows 1. 从发布版中下载 `Clypra-x64.msi` 2. 运行安装程序 3. 如果 Windows SmartScreen 阻止执行，请点击“更多信息”→“仍要运行” 支持：Windows 10（版本 1809+）及 Windows 11 #### Linux 1. 从发布版中下载 `Clypra-x86_64.AppImage` 2. 赋予执行权限：`chmod +x Clypra-x86_64.AppImage` 3. 运行：`./Clypra-x86_64.AppImage` 支持：Ubuntu 20.04+、Fedora 35+、Debian 11+ 及其衍生版本 ## 开发 ### 前置条件 **必需** - Node.js 18+ 配合 npm - Rust 1.70+（通过 [rustup](https://rustup.rs/) 安装） - FFmpeg 6.0+ 及其开发库 **特定平台** - **macOS**：Xcode Command Line Tools (`xcode-select --install`) - **Windows**：Visual Studio 2019+ 及 C++ 桌面开发工具 - **Linux**：构建基础工具、webkit2gtk、libayatana-appindicator ### FFmpeg 安装 **macOS** ``` brew install ffmpeg ``` **Ubuntu/Debian** ``` sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev ``` **Windows (Chocolatey)** ``` choco install ffmpeg ``` **Windows（手动安装）** 1. 从 [ffmpeg.org/download.html](https://ffmpeg.org/download.html) 下载 2. 解压至 `C:\ffmpeg` 3. 将 `C:\ffmpeg\bin` 添加到系统 PATH ### 从源码构建 ``` # Clone repository git clone https://github.com/AIEraDev/clypra.git cd clypra # Install dependencies npm install # Configure environment cp .env.example .env # 编辑 .env 并添加你的 Clypra API key（text effects 必需） # 带 hot reload 的 Development mode npm run tauri dev # Production build npm run build npm run tauri build ``` ### 开发架构 代码库按领域组织，实现了清晰的关注点分离： ``` src/ ├── components/ # React components │ ├── editor/ # Core editor UI (Timeline, Preview, Filmstrip) │ ├── screens/ # Full-screen views (Launch, Settings) │ └── ui/ # Reusable UI primitives (Modals, Icons, Buttons) ├── store/ # Zustand state stores (by domain) │ ├── timelineStore.ts # Timeline structure (tracks, clips, gaps) │ ├── playbackStore.ts # Playback state and AV sync │ ├── projectStore.ts # Project metadata and media assets │ └── ... # uiStore, settingsStore, historyStore ├── core/ # Core engine logic │ ├── runtime/ # ProjectSession and lifecycle management │ ├── scheduler/ # Frame scheduler for preview rendering │ ├── resources/ # PreviewMediaPool (video/audio elements) │ ├── render/ # Canvas rasterization and compositing │ └── timeline/ # Timeline calculations and utilities ├── lib/ # Shared utilities │ ├── platform/ # Tauri IPC wrappers │ ├── monitoring/ # Performance monitoring │ ├── workers/ # Web worker pool │ └── ... # Audio, video, filmstrip utilities ├── hooks/ # Custom React hooks ├── types/ # TypeScript type definitions └── App.tsx # Application entry point src-tauri/ ├── src/ │ ├── commands/ # Tauri command handlers │ │ ├── thumbnail.rs # Video decode commands │ │ ├── export.rs # Export pipeline │ │ └── ... │ ├── thumbnail_engine/# FFmpeg decoder pool │ │ ├── decoder.rs # Hardware-accelerated decoder │ │ ├── cache.rs # LRU caching │ │ └── ... │ └── lib.rs # Tauri application setup └── Cargo.toml # Rust dependencies ``` ### API 配置 Clypra 使用 Clypra API 提供文本特效和模板。要启用这些功能： 1. 复制 `.env.example` 到 `.env`： cp .env.example .env 2. 将你的 API 密钥添加到 `.env`： VITE_CLYPRA_API_KEY=your_api_key_here 3. **重要提示**：切勿将 `.env` 提交到版本控制（已在 `.gitignore` 中忽略） 该 API 提供： - 具有可自定义样式的文本特效库 - 带有 WebM 视频预览的基于 Canvas 的文本模板 - Google Fonts 集成 ### 测试 ``` # 运行所有测试 npm test # 运行 Rust 测试 cd src-tauri && cargo test # 运行特定 test suite npm test -- src/lib/__tests__/timelineUtils.test.ts # Run with coverage npm test -- --coverage ``` ### 代码质量 ``` # TypeScript type checking npx tsc --noEmit # Rust linting cd src-tauri && cargo clippy -- -D warnings # Format code npm run format cd src-tauri && cargo fmt ``` ## 项目结构 ### 状态管理架构 Clypra 使用 Zustand 和按领域分离的 store，以保持清晰的所有权边界： - **timelineStore**：时间轴结构（轨道、片段、转场、间隙） - **playbackStore**：播放状态、播放头位置、音视频同步 - **projectStore**：项目元数据、媒体资产、持久化 - **historyStore**：撤销/重做命令栈 - **uiStore**：UI 状态（模态框、选择、拖拽状态） - **settingsStore**：用户偏好和应用设置 每个 store 拥有其领域并公开操作。跨 store 通信通过显式调用进行，而非共享可变状态。 ### 视频处理流水线 1. **导入**：FFmpeg 探测提取元数据（时长、尺寸、编解码器） 2. **缩略图**：Rust 解码器生成胶片条图块（L0-L3 密度等级） 3. **预览**：HTMLVideoElement（实时播放）或 Canvas（合成帧） 4. **导出**：帧调度器 → RGBA 帧 → FFmpeg 编码器 → MP4/MOV ### 性能监控 应用包含全面的性能监控： - **解码器指标**：缓存命中、驱逐、解码延迟 - **导出指标**：帧写入时间、fps、总时长 - **渲染指标**：图层渲染时间、Canvas 池效率 - **缓存指标**：胶片条缓存命中率、内存使用情况 在开发环境中，可通过 `window.__performanceMonitor` 访问指标。 ## 贡献 我们欢迎您的贡献！请查阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解指南。 ### 开发工作流 1. Fork 本仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 进行更改并附带测试 4. 确保所有测试通过 (`npm test && cd src-tauri && cargo test`) 5. 使用约定式提交进行提交 (`feat:`、`fix:`、`docs:` 等) 6. 推送到你的 Fork 并开启 Pull Request ### 代码风格 - **TypeScript**：启用严格模式，ESLint + Prettier - **Rust**：`cargo fmt` + `cargo clippy`（无警告） - **提交**：约定式提交格式 - **文档**：公共 API 使用 JSDoc，复杂逻辑使用内联注释 ## License 本项目基于 MIT License 授权 - 详见 [LICENSE](./LICENSE) 文件了解详情。 ### FFmpeg 许可 Clypra 使用 FFmpeg 进行视频处理。FFmpeg 的授权基于： - LGPL 2.1+（默认构建） - GPL 2+（如果使用仅限 GPL 的组件构建） 二进制发布版包含基于 LGPL 协议的 FFmpeg。如果您使用 GPL 组件构建，请确保符合 GPL 规定。 ## 致谢 - **Tauri**：跨平台原生应用框架 - **FFmpeg**：视频/音频处理引擎 - **React**：UI 框架 - **shadcn/ui**：组件库基础 ## 支持 - **问题**：[GitHub Issues](https://github.com/AIEraDev/clypra/issues) - **讨论**：[GitHub Discussions](https://github.com/AIEraDev/clypra/discussions) - **文档**：[项目 Wiki](https://github.com/AIEraDev/clypra/wiki) ## Open Core 模式 Clypra 采用 **Open Core** 商业模式： ### 免费且开源 (MIT License) ✅ **核心视频编辑器** - 多轨时间轴、帧精确编辑、硬件加速处理 ✅ **特效引擎** - 专业视频特效、转场、滤镜（通过 `@clypra-studio/engine`） ✅ **音频工具** - 波形可视化、音量控制、音视频同步 ✅ **导出流水线** - 通过 FFmpeg 进行.264, H.265, ProRes 导出 ✅ **文本叠加** - 自定义字体、样式和动画 ✅ **所有 UI 组件** - 完整源代码，无专有依赖 **无水印。无功能限制。无需订阅。永久。** ### Pro 功能 (AI 层) 🎯 **自然语言编辑** - “移除所有停顿”、“添加字幕”、“让这部分变短” 🎯 **自动字幕** - 带有说话人检测和可自定义样式的转录 🎯 **智能重构图** - 针对 Instagram Stories、TikTok、YouTube Shorts 的自动裁剪 🎯 **场景检测** - AI 驱动的场景分割与 B-roll 建议 🎯 **音频增强** - 降噪、EQ、压缩 🎯 **声音克隆** - 跨片段匹配旁白声音（即将推出） 🎯 **多语言配音** - 带有唇形同步的翻译与配音（即将推出） **定价**：免费版（每月 100 次 AI 调用） • Pro（$10/月，无限制） • 企业版（定制） [了解更多关于 Pro 功能的信息 →](https://clypra.com/pricing) ### 为什么选择 Open Core？ 我们坚信专业视频剪辑应该对所有人免费且易于获取。开源确保了： - **透明度** - 您可以审计每一行代码 - **所有权** - 您的剪辑、您的数据、您的工作流 - **社区** - 来自全球创作者的贡献 - **长久性** - 该编辑器不会被关闭或置于付费墙后 Pro AI 功能为开源核心的全职开发提供资金支持。实现双赢。 ## 路线图 有关即将推出的性能改进，请参阅 [PERFORMANCE-DESKTOP-ROADMAP.md](./PERFORMANCE-DESKTOP-ROADMAP.md)。 计划中的功能： - 移动端应用发布（通过 Capacitor 支持 iOS/Android） - 高级调色 - 多机位剪辑 - 扩展插件系统 - GPU 加速特效渲染 **Pro 路线图**（AI 功能）： - 自然语言指令（2026 年第三季度） - 自动字幕（2026 年第三季度） - 智能重构图（2026 年第四季度） - 声音克隆（2027 年第一季度） - 多语言配音（2027 年第二季度）

标签：React, Rust, Syscalls, Tauri, 人工智能, 可视化界面, 用户模式Hook绕过, 网络流量审计, 自动化攻击, 视频编辑器