OmniFormat

OmniFormat 是一个基于 Electron + React 的桌面端全能格式转换器。当前版本支持视频、图片和文档三类文件，可进行单文件或批量队列转换，并尽量使用内置能力降低用户安装额外工具的成本。

当前能力

视频转换

• 输入：常见视频文件，例如 mp4、mkv、webm、mov、avi、flv、wmv、m4v
• 输出格式：mp4、mkv、webm、mov
• 清晰度：保持原始、720p、1080p、4K
• 支持高级选项：视频码率、帧率、编码器、音频保留/移除
• 编码器支持自动、H.264、H.265、VP9；VP9 当前限制为 webm 输出
• 实现：通过随应用分发的 @ffmpeg-installer/ffmpeg 调用 FFmpeg
• 支持转换进度和取消任务

图片转换

• 输入：png、jpg、jpeg、webp、bmp、tif、tiff
• 输出格式：png、jpg、webp、bmp、tiff
• 支持压缩质量、画质增强、按宽度/高度缩放、适配指定尺寸框、保持比例
• 画质增强提供轻微锐化、清晰增强、降噪清晰三档，基于 FFmpeg 滤镜实现，不依赖额外 AI 模型
• 实现：通过内置 FFmpeg
• 支持取消任务

文档转换

• Markdown：Markdown -> PDF / HTML / DOCX
• HTML：HTML -> PDF / DOCX / Markdown
• DOCX：DOCX -> PDF / HTML / Markdown
• PDF：PDF -> TXT / Markdown / DOCX / PNG / JPG
• 支持高级选项：PDF 页面范围、PDF 转图片 DPI、Markdown 转 HTML/PDF 模板样式
• 支持转换前预览：Markdown 预览排版效果，PDF 预览首页
• 默认输出到源文件旁边，并生成带目标格式后缀的新文件，避免覆盖原文件
• 支持取消任务和中文错误提示

体验优化

• 支持将视频、图片或文档直接拖拽到窗口中导入，应用会自动识别模块
• 支持一次拖入多个文件，或通过“批量添加文件”加入转换队列
• 队列会串行执行视频、图片、文档转换，并显示每个文件的等待、转换中、完成、失败状态
• 转换过程中会锁定模块切换和文件选择，避免任务状态混乱
• 文档模块支持在转换前生成 Markdown/PDF 预览，减少输出样式和页面选择的试错成本
• 转换完成后可以直接打开输出文件，或定位到输出文件所在目录
• 右侧任务区显示最近 8 条转换记录，支持从历史记录打开文件、打开目录、复用输出目录
• 历史记录保存在本机应用前端存储中，仅用于当前用户快速复用路径
• 首次启动会显示依赖检测向导，检查内置 FFmpeg、Pandoc 和 Poppler 状态
• 右侧任务区提供诊断入口，可复制错误详情、打开日志目录、手动检查应用更新

打包与自动更新

Windows 安装包使用 electron-builder 的 NSIS target：

npm run dist

• npm run pack：构建未安装的本地目录包，适合快速检查打包产物
• npm run dist：生成 Windows NSIS 安装包
• npm run publish：构建安装包并发布到 GitHub Releases，用于自动更新分发

自动更新基于 electron-updater，发布源配置为 GitHub 仓库 codehyq/OmniFormat。开发模式下不会检查更新；安装包运行后可在右侧“诊断与更新”中手动检查。

发布前需要设置 GitHub token，例如：

$env:GH_TOKEN="你的 GitHub token"
npm run publish

诊断与日志

• 转换失败时，应用会保存更完整的错误详情，包括版本、平台、用户数据目录、日志文件路径和堆栈信息
• “复制错误”会将最近一次错误详情复制到剪贴板，便于发 issue 或排查
• “日志目录”会打开 electron-log 写入目录，方便查看历史错误
• “依赖检测”会重新检查 FFmpeg、Pandoc、Poppler 状态；FFmpeg 随应用内置，Pandoc/Poppler 可按需安装或配置

PDF 与外部工具说明

当前 PDF 输入转换优先使用内置 npm 依赖：

• pdfjs-dist：解析 PDF 文本与页面
• @napi-rs/canvas：渲染 PDF 页面为图片
• docx：生成基础 DOCX 文档

因此 PDF -> TXT / Markdown / DOCX / PNG / JPG 不再强制依赖 Poppler。

仍然保留外部工具配置入口：

• Pandoc：用于部分 DOCX 相关转换路径，例如 Markdown/HTML -> DOCX、DOCX -> HTML/Markdown/PDF
• Poppler：作为后续兼容或兜底工具入口，当前不是 PDF 输入转换的必需项

如果需要使用 Pandoc，请安装后在文档模块中检测或手动选择 pandoc.exe。

开发命令

npm install
npm run dev
npm test
npm run build
npm run dist

• npm run dev：启动 Electron 主进程和 React 渲染进程
• npm test：运行转换逻辑测试
• npm run build：执行 TypeScript 检查并构建应用
• npm run dist：构建 Windows 安装包

测试覆盖

当前测试覆盖：

• 视频输出路径、FFmpeg 参数、高级选项映射、进度时间解析
• 图片输出路径、FFmpeg 参数、质量、尺寸和画质增强映射
• 文档格式识别、默认输出路径、支持路径判断
• 文档高级选项：PDF 页面范围、PDF 转图片 DPI、Markdown 模板样式
• 文档预览：Markdown HTML 预览、PDF 首页图片预览
• Markdown/HTML 基础互转
• PDF fixture 到 Markdown 的内置解析转换
• Pandoc/Poppler 命令路径解析

测试样本位于 tests/fixtures。

目录结构

• src/main：Electron 主进程、文件选择、转换调度、工具配置、取消任务
• src/preload：安全暴露给前端的 Electron API
• src/renderer：React 桌面界面
• src/shared：前后端共享类型
• tests：转换 helper 和真实样本测试
• resources：应用图标和 Logo 资源

已知限制

• 当前批量队列为串行执行，暂不支持队列内单项并发和单项参数覆盖
• PDF 转 DOCX 以文本提取为主，不保证复杂版式完全还原
• PDF 转图片会按页输出，多页 PDF 会生成带页码后缀的图片文件
• PDF 页面范围只支持明确页码和闭区间，例如 1-3,5
• 仍有部分深度参数暂未开放，例如视频音频编码细节、PDF OCR、DOCX 样式还原等