# TinyPNG 批量压缩工具

这是一个基于 Tinify/TinyPNG Python SDK 的批量图片压缩和格式转换工具。支持 GUI 界面、多个 API Key 按顺序接力使用、官方额度同步、批量转换格式，以及递归处理目录。

## 功能

- 图形界面选择输入目录和输出目录。
- 支持多个 Tinify API Key，每个 Key 默认每月 500 张额度，处理时会先用完前一个 Key，再切换到下一个。
- 启动处理前可同步官方本月已用额度。
- 支持 PNG、JPG/JPEG、WebP、AVIF 图片。
- 支持转换为 png、jpeg、webp、avif，也支持“全部格式”一次输出四种格式。
- 支持递归扫描目录。
- 支持覆盖已有输出文件或跳过已有文件。
- 支持试运行，只预览计划，不调用 Tinify API。

## 目录说明

```text
C:\dev\py\tinypng
├─ source\                 默认输入目录，把待处理图片放这里
├─ optimized\              默认输出目录，运行后自动生成
├─ tinypng_gui.py          GUI 程序
├─ tinypng_balancer.py     命令行和核心处理逻辑
├─ run_gui.bat             双击启动 GUI
├─ tinify_keys.json        实际 API Key 配置文件
├─ tinify_usage.json       本月额度缓存文件，运行后自动生成
├─ pyproject.toml          uv 项目依赖配置
└─ uv.lock                 uv 锁定文件
```

## 启动 GUI

推荐直接双击：

```text
run_gui.bat
```

也可以在命令行运行：

```powershell
cd C:\dev\py\tinypng
uv run tinypng_gui.py
```

程序通过 `uv run` 启动，会自动使用 `pyproject.toml` 中声明的 `tinify` SDK 依赖。

## 配置 API Key

打开 GUI 后点击 `填写 API Key`。

支持以下输入方式：

```text
KEY_1
KEY_2
KEY_3
```

也支持用逗号、分号或空格分隔。保存后会生成 `tinify_keys.json`，主界面的“配置文件”会自动指向该文件。

配置文件格式示例：

```json
{
  "api_keys": [
    {
      "key": "YOUR_TINIFY_API_KEY_1",
      "monthly_limit": 500,
      "name": "账号-1"
    },
    {
      "key": "YOUR_TINIFY_API_KEY_2",
      "monthly_limit": 500,
      "name": "账号-2"
    }
  ],
  "proxy": null
}
```

不要把真实 API Key 写入 `tinify_keys.sample.json`，它只作为模板示例。

## GUI 使用流程

1. 把图片放入当前目录下的 `source` 文件夹。
2. 双击 `run_gui.bat` 打开界面。
3. 点击 `填写 API Key`，粘贴一个或多个 API Key 并保存。
4. 确认输入目录为 `source`。
5. 选择输出目录，默认是 `optimized`。
6. 按需选择转换格式、递归扫描、覆盖输出、同步官方额度等选项。
7. 点击 `开始处理`。

## 转换格式

`转换格式` 默认是 `保持原格式`。

可选值：

- `源格式`：只压缩，不改变格式。
- `png`：输出 PNG。
- `jpeg` / `jpg`：输出 JPEG。
- `webp`：输出 WebP。
- `avif`：输出 AVIF。
- 可多选，例如默认会同时选择 `源格式` 和 `webp`，每张图片会输出源格式压缩结果和 WebP 结果。
- 命令行的 `all` 会输出源格式、`.png`、`.jpg`、`.webp`、`.avif`。

注意：转换、缩放等 Tinify API 操作可能会消耗压缩额度。“全部格式”会为每张输入图片生成多个输出，因此额度消耗也会更多。

## 额度同步

GUI 默认勾选 `同步官方额度`。

处理开始前，程序会对每个 API Key 调用官方 SDK 的 `tinify.validate()`，然后读取 `tinify.compression_count`，同步该 Key 本月已经使用的数量。

同步后的额度会写入：

```text
tinify_usage.json
```

后续每次处理成功后，程序也会读取 SDK 更新后的 `tinify.compression_count` 并回写本地用量缓存。

## 命令行用法

压缩目录：

```powershell
uv run tinypng_balancer.py source -o optimized
```

递归压缩：

```powershell
uv run tinypng_balancer.py source -o optimized --recursive
```

转换为 WebP：

```powershell
uv run tinypng_balancer.py source -o optimized --convert webp
```

同时输出源格式和 WebP：

```powershell
uv run tinypng_balancer.py source -o optimized --convert source --convert webp
```

输出全部格式：

```powershell
uv run tinypng_balancer.py source -o optimized --convert all
```

试运行：

```powershell
uv run tinypng_balancer.py source -o optimized --dry-run
```

跳过启动前官方额度同步：

```powershell
uv run tinypng_balancer.py source -o optimized --no-sync-usage
```

## 常见问题

### 提示 No module named 'tinify'

请使用 `uv run` 启动：

```powershell
uv run tinypng_gui.py
```

或者双击 `run_gui.bat`。

### 没有找到图片

确认图片放在输入目录中。默认输入目录是：

```text
C:\dev\py\tinypng\source
```

支持的扩展名包括：

```text
.png .jpg .jpeg .webp .avif
```

### API Key 不可用

检查 `tinify_keys.json` 中是否写入了真实 Key。模板中的 `YOUR_TINIFY_API_KEY_1` 不能直接使用。

### 全部格式输出时额度消耗变多

这是正常的。因为每张图片会分别转换为 PNG、JPEG、WebP、AVIF 四种格式，每个输出都可能消耗 Tinify 额度。