Metadata-Version: 2.4
Name: flicker-detector-cpu
Version: 1.1.0
Summary: Windows CPU build: bundled cpu-flicker-detector*.exe (CLI/web/client), no C++/TS/web source in the package.
Author: internal
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
Requires-Dist: python-multipart>=0.0.9; extra == "web"
Requires-Dist: pydantic>=2.6; extra == "web"
Requires-Dist: pyinstaller>=6.0; extra == "web"

# flicker-detector-cpu（Windows CPU 后端）

本发行版是 **`flicker-detector[cpu]`** 的 **CPU 后端**：PyPI 项目名为 **`flicker-detector-cpu`**（名称里不能写方括号 `[]`）。捆绑 **`cpu-flicker-detector.exe`**、**`cpu-flicker-detector-server.exe`**、**`cpu-flicker-detector-client.exe`**（位于 `flicker_detector_bundle\bin\`），由包内薄启动器 `execv` 调用（**不含** C++ / 前端 / 服务端 Python 源码）。

**控制台入口**：仅注册 **`cpu-flicker-detector`**、**`cpu-flicker-detector-server`**、**`cpu-flicker-detector-client`**（`pip` 在 `Scripts` 下生成的启动器也带 **`cpu-` 前缀**，不会再安装无此前缀的同名命令）。

- **要求**：Python **≥ 3.10**，操作系统 **Windows 64 位**。

## 推荐安装（与命令名一致）

```powershell
py -m pip install "flicker-detector[cpu]"
```

会安装 **`flicker-detector`**（元包）与 **`flicker-detector-cpu`**（本 wheel）。仅要后端、不要元包时：

```powershell
py -m pip install flicker-detector-cpu
```

安装后可直接使用下列命令（与 `flicker_detector_bundle\bin\` 下三个 `cpu-*.exe` 等价，经启动器转发）。

**GPU 后端**：在 PyPI 上存在 **`flicker-detector-gpu`** 时，可安装 **`flicker-detector[gpu]`**。若 GPU 包使用 **`gpu-` 前缀**的控制台脚本，可与本 CPU 包装在同一环境；若 GPU 仍使用无前缀旧名，则**不要**同时安装 `[cpu]` 与 `[gpu]`。

---

## 1. `cpu-flicker-detector` — 本地命令行检测

在**本机**对图片目录、视频或多张图片路径（有序序列）做闪屏/异常画面检测，输出 **JSON**。

```text
cpu-flicker-detector --type <dir|video|sequence> --input <路径> [--input <路径>...] --output <结果.json>
```

- **`--type`**：`dir`（图片目录，不递归）、`video`（单个视频）、`sequence`（至少两个 `--input`，每张图为图片路径，顺序即时间序）。
- 可选门限、JSON 配置等见帮助：

```text
cpu-flicker-detector --help
```

---

## 2. `cpu-flicker-detector-server` — Web 服务与浏览器界面

启动 **HTTP 服务**，在浏览器里上传素材、查看检测结果并可做**人工反馈**；任务与记录默认落在 exe 旁的 **`flicker_detector_web_data`**（可用环境变量改写）。若仍使用旧目录名，可设置 `FLICKER_DETECTOR_WEB_DATA` 或沿用 `FLASH_DETECTOR_WEB_DATA` 指向原路径。

默认在浏览器打开：

**http://127.0.0.1:8765**

### 2.1 页面与功能

| 区域 | 作用 |
|------|------|
| **工作台** | 上传**视频**、**文件夹（整目录图片）**或**多张图片**；查看任务进度、统计、**findings** 列表；点开单条可预览起止帧、时间范围；可对每条结果标记 **人工确认（正确 / 错误）**。 |
| **检测记录** | 历史任务表格：支持按时间范围、状态、输入类型、客户端 IP、检出数量、**故障类型**、是否已反馈等筛选；行可展开查看与工作台类似的详情；点击任务可在新标签打开单任务页。 |
| **趋势图（检测记录页上方）** | **请求量 / 检出量** 按时间粒度（分钟〜月）统计。 |
| **反馈趋势图（单独一块）** | **用户反馈率**、**反馈正确率**；可按 **故障类型（flash_type）** 筛选，默认**全部类型**。 |

### 2.2 常用环境变量

优先读取 **`FLICKER_*`**；未设置时仍接受旧名 **`FLASH_*`** / **`IMAGE_FLASH_DETECTOR_EXE`**（便于升级）。

| 变量（新） | 旧名（仍有效） | 含义 |
|------------|----------------|------|
| `FLICKER_DETECTOR_EXE` | `IMAGE_FLASH_DETECTOR_EXE` | 检测程序路径（可选） |
| `FLICKER_DETECTOR_BIND` | `FLASH_DETECTOR_BIND` | 监听地址，默认 `127.0.0.1` |
| `FLICKER_DETECTOR_PORT` | `FLASH_DETECTOR_PORT` | 端口，默认 `8765` |
| `FLICKER_DETECTOR_WEB_DATA` | `FLASH_DETECTOR_WEB_DATA` | SQLite 与上传缓存目录 |
| `FLICKER_DETECTOR_MAX_UPLOAD_MB` | `FLASH_DETECTOR_MAX_UPLOAD_MB` | 单次上传总大小上限（MB） |
| `FLICKER_DETECTOR_MAX_CONCURRENT_JOBS` | `FLASH_DETECTOR_MAX_CONCURRENT_JOBS` | 并发检测任务数 |
| `FLICKER_DETECTOR_JOB_TIMEOUT_SEC` | `FLASH_DETECTOR_JOB_TIMEOUT_SEC` | 单任务子进程超时（秒） |
| `FLICKER_DETECTOR_TRUST_PROXY` | `FLASH_DETECTOR_TRUST_PROXY` | 设为 `1` 时从 `X-Forwarded-For` 取客户端 IP |

示例：

```powershell
$env:FLICKER_DETECTOR_PORT = "9000"
cpu-flicker-detector-server
```

---

## 3. `cpu-flicker-detector-client` — 远程提交检测（B/S）

在**任意能访问服务地址**的机器上，把本地视频或图片**上传到已在运行的 `cpu-flicker-detector-server`**，由**服务端**调用检测 exe；**不需要**在客户端安装检测主程序。

```text
cpu-flicker-detector-client --mode <video|sequence|folder> --url <服务根地址> [选项] <路径...>
```

| `--mode` | 含义 | 路径参数 |
|----------|------|----------|
| `video` | 单个视频 | 恰好一个视频文件 |
| `sequence` | 有序图片序列 | 至少两张图 |
| `folder` | 图片目录（会遍历子目录中的图片） | 恰好一个目录 |

常用选项（完整列表见 `cpu-flicker-detector-client --help`）：

- `--url`：服务地址，如 `http://192.168.1.10:8765`
- `--output`：将最终任务 JSON 写入文件；不写则打印到标准输出
- `--poll`：轮询间隔（秒）
- `--timeout` / `--http-timeout` / `--upload-timeout`：超时控制
- `--quiet`：少打印进度
- `--skip-health`：跳过启动前健康检查

示例：

```powershell
cpu-flicker-detector-client --mode video --url http://127.0.0.1:8765 clip.mp4
cpu-flicker-detector-client --mode sequence --url http://127.0.0.1:8765 .\a.png .\b.png .\c.png
cpu-flicker-detector-client --mode folder --url http://192.168.1.10:8765 --output result.json D:\shots\seq1
```

**退出码**：`0` 成功；`1` 任务失败；`2` 网络/HTTP/解析错误；`3` 参数或本地路径错误；`4` 等待超时。

---

## 4. 其他说明

- 若命令提示缺少捆绑 exe，请从 **PyPI** 重新安装 **`win_amd64`** wheel（项目名 **`flicker-detector-cpu`**，或通过 **`flicker-detector[cpu]`**）。
- 算法细节、自编译、源码级 Web 开发见 **GitHub** 仓库 **`flicker-detector-cpu`** 中的主 `README.md`（本页仅说明 **pip 安装后的三个入口与界面**）。
