gfriends-inputer：轻量级输入处理框架从安装到定制的全方位指南

作为一款专注于头像导入的轻量级Python输入处理工具，gfriends-inputer为Emby/Jellyfin媒体服务器提供高效的头像管理解决方案。本文将从核心功能解析、快速上手指南到进阶配置技巧，全方位展示如何利用这款工具实现零代码配置的头像自动化管理。

核心功能解析：模块化输入处理架构

gfriends-inputer采用配置驱动开发模式，通过模块化设计实现头像下载、尺寸优化、元数据管理等核心功能。其架构主要包含三大功能模块：

1. 智能头像获取模块

该模块负责从远程仓库或本地路径获取头像资源，支持多源优先级配置和增量更新机制。通过get_gfriends_map()函数解析仓库文件树，建立头像资源映射关系，并通过download_avatar()实现多线程下载。

# 核心下载逻辑示例
def download_avatar(url, actor_name):
    gfriends_response = session.get(url)
    pic_path = download_path + actor_name + ".jpg"
    with open(pic_path, "wb") as code:
        code.write(gfriends_response.content)

2. AI驱动的图像处理模块

集成OpenCV DNN和百度AI两种人脸检测方案，提供四种头像尺寸优化策略：

• 高斯平滑处理（填充毛玻璃样式）
• 直接裁剪处理（可能裁剪面部）
• 本地AI检测裁剪（默认，基于OpenCV）
• 云端AI检测裁剪（基于百度人体分析API）

# 本地AI裁剪实现
def fix_size(type, path):
    pic = Image.open(path)
    (wf, hf) = pic.size
    if type == 3:
        x_nose, y_nose = find_faces(pic)  # 本地人脸检测
        # 根据面部特征计算裁剪区域
        x_left = x_nose - 1/3 * hf
        fixed_pic = pic.crop((x_left, 0, x_left + 2/3 * hf, hf))
        fixed_pic.save(path, quality=95)

3. 媒体服务器集成模块

通过Emby/Jellyfin API实现头像和元数据的无缝导入，支持批量处理和断点续传。关键函数input_avatar()负责与服务器交互，read_persons()获取服务器演员列表。

💡 技巧提示：模块间通过配置文件解耦，可通过修改config.ini灵活调整各模块行为，无需修改源代码。

快速上手指南：零代码配置实现头像自动化管理

环境准备与安装

1. 系统要求

• Python 3.6+ 或直接使用预编译可执行文件
• 网络连接（用于获取远程头像资源）
• Emby/Jellyfin媒体服务器

2. 安装步骤

方法一：直接使用可执行程序

1. 从项目仓库下载对应系统的压缩包
2. 解压到任意目录
3. 运行可执行文件（Windows为Gfriends Inputer.exe，Linux/Mac为Gfriends Inputer）

方法二：源码运行

git clone https://gitcode.com/gh_mirrors/gf/gfriends-inputer
cd gfriends-inputer
pip install -r requirements.txt
python3 "Gfriends Inputer.py"

基础配置与运行

首次运行程序会自动生成config.ini配置文件，关键配置项如下：

配置项	默认值	常用配置	说明
Host_Url	http://localhost:8096/	实际服务器地址	Emby/Jellyfin服务器地址
Host_API	空	用户API密钥	服务器API访问密钥
Size_Fix	3	3或4	头像尺寸优化方式，3为本地AI
OverWrite	2	2	增量更新模式，仅更新变化头像
MAX_DL	5	3-10	下载线程数，网络差时减小

⚠️ 注意事项：API密钥获取方式：进入Emby/Jellyfin控制台 → 高级 → API密钥 → 新API密钥。

配置完成后再次运行程序，工具将自动完成：

1. 连接媒体服务器
2. 获取演员列表
3. 下载缺失/更新的头像
4. 优化头像尺寸
5. 导入服务器

进阶配置技巧：定制化输入处理流程

本地头像优先策略

工具支持导入本地自定义头像，实现步骤：

1. 将本地头像命名为演员姓名.jpg
2. 放置在./Avatar/目录（可在配置文件修改路径）
3. 程序将优先使用本地头像，不存在时才从远程仓库获取

💡 技巧提示：对于特殊演员头像，可通过此方式实现个性化管理，同时不影响其他演员的自动更新。

多头像手动选择

当仓库存在多张同一演员头像时，可开启手动选择功能：

1. 编辑config.ini，设置Conflict_Proc = 1
2. 程序将下载所有可用头像
3. 下载完成后，手动删除不需要的头像
4. 剩余头像将被导入服务器

元数据刮削配置

工具支持自动刮削演员个人信息：

1. 编辑config.ini，设置Get_Intro = 1
2. 程序将自动从XSlist获取演员信息（生日、三围等）
3. 信息将与头像一并导入服务器

⚠️ 注意事项：开启此功能会增加处理时间，且受网络状况影响较大。

常见问题排查

1. 连接服务器失败

• 检查Host_Url是否正确，确保以/结尾
• 验证API密钥是否有效
• 测试服务器网络可达性：ping <服务器IP>

2. 头像下载缓慢或失败

• 尝试降低MAX_DL下载线程数
• 配置代理：在config.ini中设置Proxy
• 检查网络连接，推荐使用全局代理

3. AI裁剪功能不工作

• 确认Size_Fix配置值为3（本地AI）或4（百度AI）
• 本地AI需确保opencv-python已正确安装
• 百度AI需填写正确的BD_App_ID、BD_API_Key和BD_Secret_Key

4. 程序运行中断

• 检查./Getter/proc.tmp文件，程序支持断点续传
• 查看./Getter/logger.log日志文件定位错误
• 尝试删除配置文件重新生成默认配置

功能扩展建议

1. 定时自动更新

利用系统任务调度实现定期自动更新：

# Linux Crontab示例：每周一凌晨2点运行
0 2 * * 1 /path/to/gfriends-inputer/"Gfriends Inputer" -q

2. 自定义头像来源

通过修改Repository_Url配置，使用第三方头像仓库：

# 自定义头像仓库
Repository_Url = https://your-custom-repo.com/

3. 批量头像导出

修改Gfriends Inputer.py，添加导出功能：

def export_avatars(output_dir):
    # 遍历actor_dict，将已下载头像复制到输出目录
    for actor_name, actor_id in actor_dict.items():
        src_path = f"{download_path}{actor_name}.jpg"
        if os.path.exists(src_path):
            shutil.copy(src_path, f"{output_dir}/{actor_name}.jpg")

4. 头像质量筛选

实现基于分辨率的头像质量筛选：

def filter_low_quality(path, min_resolution=(500, 750)):
    with Image.open(path) as img:
        return img.size[0] >= min_resolution[0] and img.size[1] >= min_resolution[1]

gfriends-inputer通过灵活的配置系统和模块化设计，为媒体服务器头像管理提供了高效解决方案。无论是初级用户的零代码配置，还是高级用户的定制化开发，都能找到合适的使用方式。通过本文介绍的功能解析和配置技巧，您可以充分发挥这款轻量级输入处理框架的潜力，实现头像管理的自动化和智能化。