immich-automated-selfie-timelapse 与 Immich API 集成原理:按人物搜索照片并解析人脸元数据全流程
immich-automated-selfie-timelapse 与 Immich API 集成原理:按人物搜索照片并解析人脸元数据全流程
immich-automated-selfie-timelapse 是一个基于 Immich API 构建的自动化人脸处理工具:它调用 Immich 的人脸识别数据,按人物搜索照片库,解析每张照片的人脸边界框元数据,再经过裁剪、对齐、滤镜等多级流水线处理,最终把某个人物多年的照片自动编译成一段平滑的自拍延时视频(selfie timelapse)。本文将带你完整拆解"从人物检索到人脸元数据解析"的集成全流程。
一、整体架构:一个客户端串起整条链路
整个集成核心集中在 src/immich_api/mod.rs 中的 ImmichClient。它封装了与 Immich 服务端通信的全部 HTTP 请求,对外提供 5 类能力:
| 方法 | 对应 Immich 端点 | 作用 |
|---|---|---|
validate_connection |
GET /server/about |
校验 API Key 与连通性 |
get_people |
GET /people |
获取所有人像列表(人物 ID + 名称) |
get_person_thumbnail |
GET /people/{id}/thumbnail |
获取人物头像缩略图 |
get_assets_with_person |
POST /search/metadata |
按人物 ID 分页搜索照片 |
download_asset / download_asset_preview |
GET /assets/{id}/original 或 thumbnail?size=preview |
下载原图或 1440p 预览图 |
所有请求都携带 x-api-key 请求头。客户端在初始化时会对 base URL 做规范化(sanitize_base_url):无论你填 http://host:2283 还是 http://host:2283/api/,最终都会统一成 .../api 结尾,避免新手配置路径踩坑。
API Key 与地址通过环境变量 IMMICH_API_KEY、IMMICH_BASE_URL 注入(见 src/config.rs),需要开启的权限有:album.read、asset.download、asset.read、asset.view、person.read、server.about。
二、第一步:连通性校验与错误处理
启动或点击"检查连接"时,ImmichClient 会请求 /server/about 获取 ServerInfo(版本号)。这一步由 Web 层 src/web/handlers/health.rs 的 check_connection 处理器调用,结果直接展示在 Web UI 的连接状态栏。
值得注意的工程设计是 check_response_error:它在判断 HTTP 状态码时区分了三种情况,给出面向用户的明确报错——
- 401 → "invalid or expired API key"
- 403 → "missing permission"(权限未勾选)
- 其他 → 附带响应体的通用 HTTP 错误
这让新手在权限配错时能一眼定位问题,而不是面对一个笼统的"请求失败"。
三、第二步:按人物搜索照片
3.1 拉取人物列表
前端人物选择器(frontend/src/lib/components/PeopleSelector.svelte)背后的数据来自 GET /people。返回结果被反序列化为 Person 结构(id + 可选 name),头像则单独从 /people/{id}/thumbnail 获取。选中某个人后,界面还会调用 /api/people/{id}/asset-count(见 src/web/handlers/people.rs)预先统计该人物的照片总数与含人脸数据的照片数。
3.2 按人物 ID 分页搜索
核心搜索逻辑在 search_person_assets(src/immich_api/mod.rs)中。它向 POST /search/metadata 发送 SearchParams 请求体:
| 参数 | 值 | 说明 |
|---|---|---|
personIds |
选中人物的 ID | 按人物过滤 |
albumIds |
可选 | 限定相册范围 |
takenAfter / takenBefore |
可选 | 限定拍摄时间区间 |
type |
IMAGE |
只搜索照片,排除视频 |
page / size |
从 1 开始 / 每页 100 | 分页参数 |
withPeople |
true |
关键:要求返回结果附带人物与人脸数据 |
withPeople: true 是整个集成的枢纽——只有带上它,Immich 才会把每张资产的人物归属及人脸信息一并返回。搜索循环持续翻页直到 next_page 为空(设有 1000 页保护上限)。
当选择了多个相册时,get_assets_with_person 会逐相册分别请求,再用 HashSet 按资产 ID 去重合并,避免同一张照片被重复处理。
四、第三步:解析人脸元数据
4.1 三层嵌套的数据结构
搜索返回的 JSON 按三层结构组织(见 src/immich_api/mod.rs):
Asset(照片资产)
└── people: Vec<PersonWithFaces> // 照片中出现的所有人物
└── faces: Vec<FaceData> // 该人物在照片中的脸
其中 FaceData 就是人脸元数据本体:
| 字段 | 含义 |
|---|---|
bounding_box_x1 / y1 / x2 / y2 |
人脸边界框四个角点(像素坐标) |
image_width / image_height |
边界框所属图像的原始尺寸 |
4.2 为每个人物锁定"自己那张脸"
一张合影里可能有多个 PersonWithFaces。任务主流程在 src/job/mod.rs 的 find_face_for_person 中遍历资产内的人物列表,找出 id 等于目标人物 ID 的那一项,并取其第一张脸(Immich 不会对同一人在同一张照片中重复建脸)。没有人脸数据的资产会被直接过滤掉——因为后续所有裁剪、对齐都依赖这个边界框。
五、第四步:下载图像并进入处理流水线
5.1 两种下载策略
process_single_asset(src/job/processing.rs)根据配置 use_preview 决定:
- 预览图模式(默认):下载 Immich 预生成的 1440p JPEG,解码快、体积小;
- 原图模式:下载
/assets/{id}/original,下载前先检查Content-Length,超过 100MB 直接拒绝,防止内存被超大文件撑爆。
5.2 人脸元数据在流水线中的用途
人脸边界框并非一次性的"下载定位器",它在流水线(src/pipeline/mod.rs)中至少被三处复用:
- face_resolution(src/pipeline/steps/face_resolution.rs):在下载之前先用
x2-x1、y2-y1算出脸部像素尺寸,小于阈值(默认 80px)直接跳过——用最便宜的元数据先淘汰最没价值的照片,省下下载与计算开销; - crop_and_resize(src/pipeline/crop_utils.rs):把元数据中的边界框按"实际下载尺寸 / 元数据尺寸"的比值缩放,才能精确裁出人脸区域。因为预览图与原图分辨率不同,这一步的坐标换算必不可少;
- 后续步骤:亮度、模糊、头部姿态、眨眼检测、基于 68 点面部特征的双眼对齐(src/pipeline/types.rs 中定义了 EAR 眨眼比、眼球旋转角等几何计算),最终统一输出 512×512 的定帧图像。
5.3 并行与配额控制
任务层用信号量控制并发(max_workers),每张图的跳过原因(如 face_too_small、blurry)都会汇入原子计数器实时推送到前端;若开启"每时间段限片",TimeIntervalTracker 会按天/周/月分桶限制入选照片数,避免某次旅行密集拍摄霸占整段视频。
六、成果产出与进度可视化
所有通过流水线的图片按 时间戳_资产ID.jpg 命名保存(保证时序),再由 FFmpeg 按配置的帧率与 CRF 编译为 MP4 延时视频(src/video/ffmpeg.rs)。
进度方面,Web 服务(src/web/handlers/mod.rs)暴露了完整的 REST 端点:/api/people、/api/start、/api/progress、/api/cancel 等,并通过 /api/ws 的 WebSocket 通道把每一步的完成数、跳过统计实时广播给前端,无需轮询。
总结
immich-automated-selfie-timelapse 与 Immich API 的集成可以归纳为一条清晰的链路:
API Key 校验 →
/people选人物 →/search/metadata(withPeople=true)按人物分页搜图 → 解析FaceData边界框 → 下载图像 → 流水线裁剪/对齐/过滤 → FFmpeg 合成视频
它充分利用了 Immich 已有的人脸识别能力,把"找照片"这件最难的事交给图库本身,自己专注做好"选片 + 对齐 + 合成",这正是其集成方案对新手最友好、也最值得借鉴的设计思路。


