# emby-util

**Repository Path**: armyant/emby-util

## Basic Information

- **Project Name**: emby-util
- **Description**: emby工具集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2020-11-14
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Emby-Util 工具集

一个专为 Emby 媒体服务器设计的 Python 工具集，提供媒体文件管理、元数据处理、演员信息管理等功能。

## 📋 项目概述

Emby-Util 是一个综合性的 Python 工具包，旨在简化和自动化 Emby 媒体服务器的管理任务。该项目包含多个独立的脚本工具，可以处理视频文件、获取演员信息、管理媒体库、同步文件等操作。

## 🚀 核心功能

### 1. JAV 内容处理工具 (`jav_process.py` / `jav_process_ai.py`)
- **视频文件处理与重命名**：自动识别和处理 JAV 视频文件
- **智能内容分析**：AI 增强版本提供更智能的内容识别
- **批量操作支持**：支持批量处理大量视频文件
- **日志记录**：完整的操作日志记录，便于追踪和调试

### 2. TMDB 集成工具 (`tmdb-tools.py` / `tmdb-tools-ai.py`)
- **演员信息获取**：从 TMDB API 获取详细的演员信息
- **电影元数据处理**：自动获取和更新电影的元数据信息
- **图片资源下载**：下载演员头像和电影海报
- **数据库存储**：将获取的信息存储到本地数据库

### 3. 文件镜像同步工具 (`mirror-tools.py` / `mirror-tools-ai.py`)
- **目录结构镜像**：在不同位置创建相同的目录结构
- **文件同步**：智能同步文件，避免重复传输
- **视频文件处理**：特殊处理视频文件，支持占位符创建
- **字幕和封面同步**：同步相关的字幕文件和封面图片

### 4. Emby 媒体库管理 (`emby_movie_tool.py` / `emby_lib-tools.py`)
- **媒体库操作**：直接与 Emby API 交互进行媒体库管理
- **电影信息更新**：批量更新电影的文件路径和元数据
- **库结构管理**：获取和管理媒体库的结构信息

### 5. 演员信息管理 (`person_util.py` / `person_util_ai.py`)
- **演员数据管理**：添加、更新演员信息
- **图片上传处理**：处理演员头像的上传和更新
- **信息验证**：验证演员信息的完整性和准确性

### 6. 视频文件名处理系统 (`extract_video_names/`)
- **企业级文件名处理**：功能强大的视频文件名清理和标准化系统
- **多类型视频支持**：支持 FC2、有码、无码三种主要视频类型识别
- **智能清理规则**：自动清理网站前缀、质量标记、中文描述等脏数据
- **流水线式架构**：采用函数式编程和配置驱动的可扩展设计
- **Excel导出**：处理结果导出为格式化的Excel文件

### 7. 文件管理工具
- **115 网盘工具** (`115-util.py`)：与 115 网盘进行文件操作
- **视频文件移动** (`移动视频文件.py`)：批量移动和整理视频文件
- **Markdown 辅助** (`md_help.py`)：辅助处理 Markdown 文档

## 🛠️ 技术栈

- **Python 3.7+**
- **Web 框架**: 
  - requests - HTTP 请求处理
  - beautifulsoup4 - HTML 解析
- **数据处理**:
  - tmdbv3api - TMDB API 客户端
  - pymediainfo - 媒体信息提取
- **CLI 工具**:
  - click - 命令行界面框架
- **日志系统**:
  - loguru - 现代化日志记录
- **文件处理**:
  - Unipath - 路径操作
  - threadpool - 多线程处理
- **数据格式**:
  - xlrd/xlwt - Excel 文件处理
  - prettytable - 表格格式化显示

## 📦 安装指南

### 1. 环境要求
- Python 3.7 或更高版本
- Windows 操作系统（推荐）
- Emby 服务器运行在本地或可访问的网络位置

### 2. 依赖安装

```bash
# 克隆项目
git clone <repository-url>
cd emby-util

# 安装依赖
pip install -r requirements.txt
```

### 3. 配置设置

在使用工具前，需要配置以下参数：

1. **Emby 服务器配置**:
   - 在各脚本中设置 `domain`（默认：`http://localhost:8096`）
   - 配置 `api_key` 和 `user_id`

2. **TMDB API 配置**:
   - 获取 TMDB API 密钥
   - 在 `tmdb-tools.py` 中配置代理设置（如需要）

3. **路径配置**:
   - 根据实际环境调整各脚本中的文件路径

## 📖 使用指南

### JAV 内容处理

```bash
# 基础版本
python jav_process.py --input /path/to/videos --output /path/to/processed

# AI 增强版本
python jav_process_ai.py --help
```

### TMDB 演员信息获取

```bash
# 获取演员信息
python tmdb-tools.py

# AI 增强版本
python tmdb-tools-ai.py
```

### 文件镜像同步

```bash
# 基础镜像工具
python mirror-tools.py

# AI 增强版本
python mirror-tools-ai.py
```

### 视频文件名处理

```bash
# 进入文件名处理模块目录
cd extract_video_names

# 处理单个目录树文件
python main.py input.txt -o result.xlsx

# 处理并包含统计信息
python main.py input.txt -o result.xlsx --include-summary

# 仅显示成功提取的结果
python main.py input.txt -o result.xlsx --success-only

# 运行测试用例
cd test
python simple_debug.py    # 简单清理测试
python regex_test.py      # 正则表达式测试
python test_domains.py    # 域名清理测试
```

### Emby 媒体库管理

```bash
# 电影工具
python emby_movie_tool.py

# 媒体库工具
python emby_lib-tools.py
```

## 🗂️ 项目结构

```
emby-util/
├── 核心工具脚本/
│   ├── jav_process.py          # JAV 内容处理
│   ├── jav_process_ai.py       # JAV 内容处理 (AI 增强)
│   ├── tmdb-tools.py           # TMDB 集成工具
│   ├── tmdb-tools-ai.py        # TMDB 集成工具 (AI 增强)
│   ├── mirror-tools.py         # 文件镜像工具
│   ├── mirror-tools-ai.py      # 文件镜像工具 (AI 增强)
│   ├── emby_movie_tool.py      # Emby 电影管理
│   ├── emby_lib-tools.py       # Emby 媒体库管理
│   ├── person_util.py          # 演员信息管理
│   ├── person_util_ai.py       # 演员信息管理 (AI 增强)
│   ├── 115-util.py            # 115 网盘工具
│   ├── 移动视频文件.py          # 视频文件移动工具
│   └── md_help.py             # Markdown 辅助工具
├── extract_video_names/        # 视频文件名处理系统
│   ├── config/                # 配置模块
│   │   ├── __init__.py
│   │   └── patterns.py        # 正则表达式模式配置
│   ├── processors/            # 处理器模块
│   │   ├── __init__.py
│   │   ├── cleaner.py         # 文件名清理器
│   │   ├── fc2_extractor.py   # FC2视频提取器
│   │   ├── censored_extractor.py  # 有码视频提取器
│   │   └── uncensored_extractor.py # 无码视频提取器
│   ├── utils/                 # 工具模块
│   │   ├── __init__.py
│   │   ├── file_utils.py      # 文件操作工具
│   │   └── excel_utils.py     # Excel导出工具
│   ├── test/                  # 测试模块
│   │   ├── __init__.py
│   │   ├── README.md          # 测试说明文档
│   │   ├── debug_test.py      # 完整流水线测试
│   │   ├── simple_debug.py    # 简单清理测试
│   │   ├── regex_test.py      # 正则表达式测试
│   │   └── test_domains.py    # 域名清理测试
│   ├── result/                # 输出结果目录
│   └── main.py               # 主程序入口
├── 数据文件/
│   ├── data/                  # 数据存储目录
│   ├── database.db            # 主数据库
│   ├── tmdb_actors.db         # TMDB 演员数据库
│   ├── logs/                  # 日志文件目录
│   ├── temp/                  # 临时文件目录
│   └── scrapy_result/         # 爬取结果目录
├── 配置文件/
│   ├── requirements.txt       # Python 依赖
│   ├── .gitignore            # Git 忽略文件
│   └── CLAUDE.md             # 项目指导文档
└── 文档/
    └── README.md             # 项目说明文档
```

## 📋 视频文件名处理系统详细说明

### 系统架构

视频文件名处理系统 (`extract_video_names/`) 采用企业级模块化设计，具备以下特性：

#### 核心特性
- **函数式编程**：纯函数设计，无副作用，易于测试和维护
- **流水线架构**：清理 → 识别 → 提取 → 验证 → 输出的完整处理流程
- **配置驱动**：所有正则表达式模式通过配置文件管理，便于扩展
- **类型安全**：完整的类型注解，提高代码可靠性

#### 支持的视频类型

1. **FC2 视频**：FC2-PPV-1234567, FC2PPV-1234567, fc1234567 等格式
2. **有码视频**：SSIS-001, WAAA-123, START-001 等格式  
3. **无码视频**：090612_422, 220301-001 等日期格式

#### 清理功能

- **网站前缀清理**：自动识别并清理 `4k2.com@`, `www.98T.la@` 等域名前缀
- **质量标记清理**：清理 `.FHD`, `_4K60fps` 等视频质量标记
- **方括号标记清理**：清理 `[Thz.la]`, `[456k.me]` 等下载站标记
- **中文描述清理**：清理 `【高清无码】` 等中文方括号描述
- **特殊变换**：`_4K60fps` → `-4K`, `part2` → `-CD2` 等智能转换

### 使用方法

#### 基础用法
```bash
cd extract_video_names

# 处理目录树文件
python main.py input.txt

# 指定输出文件
python main.py input.txt -o result.xlsx

# 输出到CSV格式  
python main.py input.txt -o result.csv
```

#### 高级选项
```bash
# 包含处理统计信息
python main.py input.txt -o result.xlsx --include-summary

# 仅显示成功提取的结果
python main.py input.txt -o result.xlsx --success-only

# 不显示统计信息
python main.py input.txt -o result.xlsx --no-summary
```

#### 测试用例
```bash
cd test

# 简单清理功能测试
python simple_debug.py

# 正则表达式匹配测试
python regex_test.py

# 域名清理功能测试
python test_domains.py

# 完整流水线测试（需要修复导入问题）
python debug_test.py
```

### 输出格式

处理结果自动保存到 `extract_video_names/result/` 目录，包含以下列：

- **原始文件名**：输入的原始文件名
- **处理后文件名**：清理和标准化后的文件名
- **视频类型**：FC2/有码/无码/未识别
- **提取结果**：标准化的视频编号
- **处理状态**：成功/失败/跳过
- **备注信息**：错误说明或特殊标记

### 扩展开发

系统支持通过配置文件轻松扩展新的清理规则和识别模式：

```python
# 在 config/patterns.py 中添加新的清理模式
pattern_config.add_cleaning_pattern(
    CleaningPattern(
        name="custom_rule",
        pattern=r'新的正则表达式',
        description="自定义清理规则",
        priority=10
    )
)

# 添加新的视频类型识别模式
pattern_config.add_extraction_pattern(
    "CENSORED",  # 视频类型
    ExtractionPattern(
        name="new_series",
        pattern=r'(NEW[-_]?\d+)',
        description="新系列格式",
        priority=10
    )
)
```

## ⚙️ 配置说明

### API 密钥配置

各工具需要配置相应的 API 密钥：

- **Emby API**: 在 Emby 控制面板 → 高级 → API 密钥 中获取
- **TMDB API**: 在 [TMDB 官网](https://www.themoviedb.org/settings/api) 申请

### 代理设置

如果需要使用代理访问外部 API，在相关脚本中配置：

```python
proxies = {
    'http': 'socks5://127.0.0.1:7890',
    'https': 'socks5://127.0.0.1:7890'
}
```

## 🔧 开发指南

### 代码规范

- 遵循 PEP 8 编码规范
- 使用类型注解提高代码可读性
- 编写详细的 docstring 文档
- 使用 loguru 进行结构化日志记录

### 错误处理

- 实现完善的异常处理机制
- 提供用户友好的错误信息
- 记录详细的错误日志用于调试

### 测试

建议为核心功能编写单元测试：

```bash
# 运行测试（如果存在）
python -m pytest tests/
```

## 📊 日志系统

项目使用 loguru 提供结构化日志记录：

- **控制台输出**: 实时显示操作状态
- **文件日志**: 详细记录到 `logs/` 目录
- **日志轮换**: 按天分割，保留 30 天历史
- **多级别记录**: DEBUG、INFO、WARNING、ERROR

## 🚨 注意事项

1. **安全提醒**: 
   - 保护好 API 密钥，不要提交到公共代码库
   - 定期更新依赖包以修复安全漏洞

2. **性能优化**:
   - 大批量操作时建议分批处理
   - 网络请求使用适当的超时设置
   - 合理使用多线程避免阻塞

3. **数据备份**:
   - 在执行批量操作前备份重要数据
   - 定期备份数据库文件

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证，详见 [LICENSE](LICENSE) 文件。

## 🆘 支持与反馈

如果您在使用过程中遇到问题或有改进建议，请：

1. 查看现有的 [Issues](../../issues)
2. 创建新的 Issue 描述问题
3. 在项目讨论区参与交流

## 🔗 相关链接

- [Emby 官方文档](https://emby.media/)
- [TMDB API 文档](https://developers.themoviedb.org/3)
- [Python 官方文档](https://docs.python.org/3/)

---

**最后更新**: 2024-09-14
**维护者**: [项目维护者姓名]
**版本**: v1.0.0