# 格式工坊

**Repository Path**: deepin20/FormatGo

## Basic Information

- **Project Name**: 格式工坊
- **Description**: 格式工坊 FormatGo，让格式转换像呼吸一样简单。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-29
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 格式工坊 FormatGo

让格式转换像呼吸一样简单。

**一个应用，四种转换**：图片 / 文档 / 音视频 / 压缩文件。基于 **Python 3 + PyQt5**，
核心转换交给 Pillow、ImageMagick、Pandoc、LibreOffice、FFmpeg 这些成熟后端，
为统信 UOS / deepin 桌面做了原生适配。

## 特性

### 四种转换类型

界面上按类型切换，**参数区互不串味**；目标格式与源文件过滤器都跟着类型换。

| 类型 | 能做 | 后端 |
|---|---|---|
| **图片** | 26 种目标格式 / 67 个源扩展名互转，缩放、水印、EXIF、体积上限 | Pillow + ImageMagick |
| **文档** | Markdown / HTML / RST / DOCX / ODT / RTF / PPTX / EPUB / PDF… 互转 | Pandoc + LibreOffice + Calibre |
| **音视频** | MP4 / MKV / WebM / MOV / MP3 / FLAC… **能复制就不重编** | FFmpeg |
| **压缩文件** | ZIP / 7Z / TAR / TAR.GZ / TAR.XZ / GZ / XZ / ZSTD 互转，**内容逐字节不变**，支持加密 | 标准库 + 7z + zstd |

### 图片域

- 常用：PNG、JPEG、WebP、GIF、BMP、TIFF、ICO、ICNS、TGA、JPEG 2000
- 专业：HEIC、PSD、EXR、HDR、PDF、EPS、PS、AI、FITS、PNM、QOI、DDS、PCX、XPM、XBM、CUR
- 只读源：AVIF、SVG、XCF、相机 RAW（DNG/CR2/NEF/ARW/RAF/ORF/RW2/PEF）
- 智能颜色模式自动处理（RGBA → RGB 对 JPEG 自动铺白底；不承载透明的格式统一铺白底）
- 质量 / 压缩级别可调，且**按格式自动启用**（无损格式自动灰掉质量滑杆）
- **EXIF 元数据控制**（保留或清除拍摄信息，按拍摄方向自动旋正）
- **目标体积上限**（自动二分调节质量，把图片压到指定大小以内）
- 动画支持（多帧源转 PNG 保留为 APNG，转 WebP / TIFF / GIF 保留多帧）

### 音视频域

- **换壳是一等公民**：目标容器装得下源编码就只复制轨（秒级、零损失），
  装不下才重编码，并且**把区别写在结果里**（"复制（换壳）" vs "重编码视频"）
- 容器的兼容性矩阵在数据层，所以非法组合**在动手之前**就被拦住，
  而不是等 ffmpeg 报一句 `Invalid argument`
- 装不进目标容器时**自动改配**编码并在标签里注明（如 MP3 抽出 AAC 源的音轨）
- 多实现编码器自动回退（某个 AV1 实现编不动这个尺寸就换下一个）
- 双层进度条（总进度 + 当前文件内的进度）

### 压缩文件域

- **内容逐字节不变**是一个承诺：写出的包会回头校验**真格式**，
  静默降级（后缀写 ZIP、内容是 tar）会被发现并把产物**丢弃**
- 支持**加密**（ZIP 用 ZipCrypto，Windows 资源管理器与 `unzip` 都认；
  7Z 用 AES-256）。没有 7z 时**明确报错，绝不退回明文**
- 单流格式（gz / bz2 / xz / zst）装不下多条目时会**明确报错**，
  而不是"只写第一个、退出码 0"

### 通用

- 批量递归转换，可选保留目录结构；单个文件失败不拖垮整批
- **转换可取消** + 逐文件进度与耗时
- **参数预设与转换历史**（预设带类型，跨类型套用时自动先切类型）
- 拖拽文件/文件夹即可载入（Qt 原生拖放，无需额外库）
- **格式能力运行时探测，不写死**：装了什么就多出什么；
  没装也能正常启动，缺的格式在界面里置灰并**注明缺什么**
  （`formatgo --list-formats` 可查本机实际支持情况）
- 跨平台（Windows / macOS / Linux）

## 统信 UOS / Deepin 原生适配

- 界面基于 **Qt（PyQt5）**，通过系统 Qt 平台主题插件 `libqdeepin` 取色，
  **自动跟随系统深色模式与强调色**；程序不硬编码任何颜色或字体。
- 按**统信应用商店规范**打包为 deb，装到 `/opt/apps/com.gitee.deepin20.formatgo/`；
  图标、菜单入口、`StartupWMClass` 全部对齐，任务栏图标不再丢失。
- 载荷是**纯 Python 源码**（不含 ELF），因此不受 UOS「仅允许签名应用」限制；
  装到 `/opt` 也避开了 Deepin 25「磐石」下 `/usr` 只读的问题。
- 同时提供**玲珑（linyaps）** 包格式，适配 UOS 应用商店主推的沙箱分发
  （**但沙箱下只有图片原生格式与标准库归档格式可用**，见下）。

## 安装

### 统信 UOS / Deepin 25（推荐用 deb）

```bash
./build.sh                                        # 产出 dist/*.deb
sudo apt install ./dist/*.deb                     # 自动补齐依赖
```

菜单入口由系统自动建立。卸载：`sudo apt remove com.gitee.deepin20.formatgo`

> UOS 上首次安装第三方 deb 需要在「控制中心 → 通用」里打开**开发者模式**。

> **只想要图片功能？** 用
> `sudo apt install --no-install-recommends ./dist/*.deb`。
> 默认装在 `Recommends` 里的 `libreoffice-core` 是百兆量级的大包。

### 用玲珑包安装

```bash
./build.sh --layout linglong
ll-cli install dist/*_binary.layer
```

> ⚠️ **玲珑版能力受限**：沙箱隔离了宿主机的可执行文件，
> ImageMagick / Pandoc / LibreOffice / FFmpeg / 7z / zstd 全部不可用，
> 即**音视频整个域都转不了**，文档域与压缩域只剩标准库能做的部分。
> 需要完整功能请装 deb 版。

### 从源码运行

```bash
git clone https://gitee.com/deepin20/FormatGo.git
cd FormatGo
pip install -r requirements.txt
./run.sh                       # 启动图形界面
```

Debian / UOS / deepin 上更推荐装发行版包，再直接用启动脚本：

```bash
sudo apt install python3-pyqt5 python3-pil
./run.sh                       # 图形界面
./run.sh --list-formats        # 看这台机器到底支持哪些格式
./run.sh clip.mkv -o ./out -f MP4       # 命令行转换（参数原样透传给 CLI）
```

`run.sh` 会**逐个真的去 import 验证**候选解释器，自动挑出装了 PyQt5/Pillow 的那个——
免得在多版本 / 虚拟环境混用的机器上，被一句没头没脑的 `ImportError` 带偏方向。
也可以 `./run.sh --which-python` 先看它选中了谁。

运行期需要 **Python ≥ 3.7**、**PyQt5**（界面）与 **Pillow**（图像处理）：

```bash
sudo apt install python3-pyqt5 python3-pil
```

**可选依赖**（全部不装也能正常启动，只是对应的类型/格式会置灰并注明原因）：

| 包 | 解锁 |
|---|---|
| `imagemagick` | 专业图片格式（HEIC / EXR / PSD / RAW…） |
| `pandoc` | 文档·纯文本子领域（Markdown / HTML / RST / LaTeX…） |
| `libreoffice-core` | 文档·办公子领域（DOCX / XLSX / PPTX / ODT…） |
| `ffmpeg` | **音视频整个域** |
| `p7zip-full` | 压缩·7z，以及**加密 ZIP** 的写入 |
| `zstd` | 压缩·ZSTD |
| `calibre`（Suggests） | 电子书（EPUB / MOBI / AZW3 / FB2） |
| `unrar`（Suggests） | 读取 RAR |

```bash
sudo apt install imagemagick pandoc libreoffice-core ffmpeg p7zip-full zstd
```

### 使用打包的可执行文件

前往 [Releases](https://gitee.com/deepin20/FormatGo/releases) 下载对应系统的版本。

## 使用说明

1. 选择转换类型（图片 / 文档 / 音视频 / 压缩文件）
2. 选择转换模式（单个文件 / 文件夹）
3. 选择源文件或文件夹（也可以直接拖进来）
4. 选择输出文件夹
5. 选择目标格式（以及可选的参数）
6. 点击「开始转换」

详细文档请查看 [用户手册](docs/USER_GUIDE.md)

## 命令行用法（进阶）

```bash
# 图片
formatgo photo.webp -o ./out -f PNG
formatgo ./origin -o ./out -f JPEG -q 90 -k            # 批量，保结构
formatgo ./origin -o ./out -f JPEG --max-size 500      # 压到 500KB 以内
formatgo ./origin -o ./out -f JPEG --strip-exif        # 清除 EXIF/GPS

# 文档
formatgo notes.md -o ./out -f PDF
formatgo ./docs -o ./out -f DOCX -k

# 音视频
formatgo clip.mkv -o ./out -f MP4 --vcodec H264 --crf 20
formatgo clip.mp4 -o ./out -f MP3                      # 抽出音轨
formatgo clip.mp4 -o ./out -f MKV --reencode           # 强制重编码

# 压缩文件
formatgo src.zip -o ./out -f 7Z --level 9
formatgo src.zip -o ./out -f ZIP --encrypt-password 口令   # 产物加密
formatgo secret.zip -o ./out -f TAR.GZ --password 口令     # 打开加密的源包

# 查看本机支持
formatgo --list-formats              # 四个类型全部
formatgo --list-formats media        # 只看音视频
```

类型一般会**按输入扩展名自动判断**；认不出来时会明确要求 `-t image|document|media|archive`，
不会猜错了悄悄按别的类型转。

## 开发

请参考 [开发者指南](docs/DEVELOPER.md)、[格式调研](docs/FORMAT_SURVEY.md) 与
[路线图](docs/ROADMAP.md)。

```bash
python -m pytest tests/ -q           # 回归测试
python3 scripts/probe_formats.py     # 四域格式实测（真跑一遍并更新文档白名单）
```

> 结构是「模块化内核 + 四个域包」：`formatgo/core/` 放与"转什么"无关的东西，
> `images/` `documents/` `media/` `archives/` 各自管一个域，**域间不互相 import**。
> 「支持哪些格式」在每个域的注册表模块里单点定义，界面、命令行、转换器、打包都从那里派生。

## 更新日志

见 [CHANGELOG.md](CHANGELOG.md)。

## 许可证

MIT License