Frame-Sense

🎯 智能媒体文件重命名工具 - 基于 AI 的视频和图片文件自动语义化命名

Frame-Sense 是一个基于 AI 的智能命令行工具，结合 FFmpeg 和 Google Gemini AI 模型，自动分析视频和图片内容，生成语义化的文件名。支持批量处理、混合媒体类型处理，让文件管理变得更加智能和高效。

📋 目录

• ✨ 主要特性
• 📦 安装
• 🚀 快速开始
• 🔧 命令详解
• ⚙️ 系统要求
• 🚨 注意事项
• 技术栈
• 🌟 致谢

✨ 主要特性

• 🎯 AI 自动重命名 - 基于图像内容生成语义化文件名
• 📹 视频 + 图片支持 - 自动提取视频帧，统一处理所有媒体文件
• ⚡ 批量处理 - 一次性处理整个目录，支持混合媒体类型
• 👀 预览模式 - 先预览重命名结果，确认无误后再执行
• 🔧 自定义配置 - 支持自定义 AI 提示词、批次大小、文件名长度
• 📁 输出目录 - 可指定输出目录，避免覆盖原文件
• 🎬 多种帧提取策略 - 支持单帧、多帧、关键帧等不同提取策略
• 🏷️ 文件名模板 - 支持自定义文件名模板，包含前缀、日期格式等
• 📅 智能日期提取 - 自动从 EXIF 数据或文件系统提取日期信息

📦 安装

全局安装

npm install -g @zhangziheng/frame-sense

🚀 快速开始

1. 安装 FFmpeg（如已安装可跳过）

FFmpeg 是视频处理必需依赖，请根据您的系统安装：

macOS (使用 Homebrew)

brew install ffmpeg

Ubuntu/Debian

sudo apt update
sudo apt install ffmpeg

Windows (使用 Chocolatey)

choco install ffmpeg

验证安装

ffmpeg -version

2. 配置 API Key

首次使用需要配置 Google Gemini API Key：

frame-sense config --api YOUR_GEMINI_API_KEY

API 注册地址：Google AI Studio API

2. 处理单个文件

# 分析视频文件
frame-sense video.mp4

# 分析图片文件
frame-sense image.jpg

# 预览重命名结果（不实际重命名）
frame-sense video.mp4 --preview

3. 批量处理目录

# 处理目录中的所有媒体文件（自动识别为目录）
frame-sense /path/to/media/folder

# 预览批量重命名结果
frame-sense /path/to/media/folder --preview

# 指定输出目录
frame-sense /path/to/media/folder --output /path/to/output

使用示例

基础使用

# 分析单个视频文件
frame-sense vacation.mp4

# 预览重命名结果
frame-sense vacation.mp4 --preview

# 批量处理目录（自动识别）
frame-sense ./photos

# 输出到指定目录
frame-sense ./videos --output ./renamed_videos

高级配置

# 帧提取策略
frame-sense video.mp4 --frame-strategy

# 设置自定义提示模板
frame-sense config --custom-prompt "请详细描述这个图像的主要内容，包括人物、场景和动作"

# 设置文件名长度限制为20个字数
frame-sense config --filename-length 20

# 设置批处理大小为10
frame-sense config --batch-size 10

# 启用详细输出模式
frame-sense ./media --verbose

文件名模板功能

# 自定义前缀
frame-sense --template '2025-11_{ai}' ./photos/

# 年月日期格式
frame-sense --template 'YYYY-MM-DD_{ai}' ./photos/

# 中文日期格式
frame-sense --template 'YYYY年MM月DD日_{ai}' ./photos/

# 直接使用描述
frame-sense --template '{desc}' ./photos/

# 配置默认模板
frame-sense config --template 'YYYY-MM_{ai}'

# 查看模板示例
frame-sense --template-examples

系统检查

# 检查 API 连接
frame-sense --test

# 检查系统依赖（FFmpeg）
frame-sense --deps

# 查看支持的格式
frame-sense --formats

# 查看当前配置
frame-sense --config

🔧 命令详解

主命令

frame-sense [文件路径] [选项]

选项说明

• -p, --preview - 预览重命名结果，不实际执行
• -o, --output <dir> - 指定输出目录
• -b, --batch <size> - 设置批量处理大小
• -f, --frame-strategy [strategy] - 设置帧提取策略，不带值时进入交互选择
• -v, --verbose - 启用详细输出和调试模式
• -t, --test - 测试 AI API 连接
• --config - 显示当前配置信息
• --formats - 显示支持的媒体格式
• --deps - 检查系统依赖
• --template <template> - 自定义文件名模板，支持变量替换
• --date-source <sources> - 日期来源优先级，逗号分隔
• --template-examples - 显示文件名模板示例

配置管理

frame-sense config [选项]

配置选项

• --api <key> - 设置 Google Gemini API Key
• --batch-size <size> - 设置默认批量处理大小
• --filename-length <length> - 设置文件名字数长度限制
• --custom-prompt <template> - 设置自定义分析提示模板
• --template <template> - 设置默认文件名模板
• --date-source <sources> - 设置日期来源优先级
• --reset-prompt - 重置提示模板到默认值
• --reset - 重置所有配置到默认值
• --show - 显示当前配置

日期格式支持

| 格式 | 描述 | 示例 | |------|------|------| | YYYY-MM-DD | 完整日期 | 2024-12-25 | | YYYY-MM | 年月格式 | 2024-12 | | YYYY | 年份 | 2024 | | YYYYMMDD | 紧凑日期 | 20241225 | | MM-DD | 月日格式 | 12-25 | | YYYY年MM月DD日 | 中文日期 | 2024年12月25日 |

模板示例

# 查看所有模板示例
frame-sense --template-examples

# 自定义前缀
frame-sense --template '2025-11_{ai}' ./photos/
# 结果：2025-11_美丽的日落风景.jpg

# 日期 + AI 描述
frame-sense --template 'YYYY-MM-DD_{ai}' ./photos/
# 结果：2024-12-25_美丽的日落风景.jpg

# 年月 + AI 描述
frame-sense --template 'YYYY-MM_{ai}' ./photos/
# 结果：2024-12_美丽的日落风景.jpg

# 中文日期格式
frame-sense --template 'YYYY年MM月DD日_{ai}' ./photos/
# 结果：2024年12月25日_美丽的日落风景.jpg

# AI 描述在前
frame-sense --template '{ai}_YYYY-MM-DD' ./photos/
# 结果：美丽的日落风景_2024-12-25.jpg

日期来源优先级

Frame-Sense 支持从多个来源提取日期信息，按优先级顺序：

1. EXIF 数据：从图片的 EXIF 数据中提取拍摄日期
2. 文件创建时间：文件系统的创建时间
3. 文件修改时间：文件系统的修改时间

# 设置日期来源优先级
frame-sense --template 'YYYY-MM_{ai}' --date-source 'exif,created,modified' ./photos/

# 只使用 EXIF 数据
frame-sense --template 'YYYY-MM_{ai}' --date-source 'exif' ./photos/

# 只使用文件创建时间
frame-sense --template 'YYYY-MM_{ai}' --date-source 'created' ./photos/

⚙️ 系统要求

运行环境

• Node.js: >= 18.0.0
• FFmpeg: 用于视频处理（必需，安装步骤见快速开始）
• Google Gemini API Key: 用于 AI 分析

系统检查

# 检查所有依赖是否正确安装
frame-sense --deps

帧提取策略详解

Frame-Sense 提供三种不同的帧提取策略，适应不同的使用场景：

| 策略 | 说明 | 适用场景 | 优势 | 注意事项 | |------|------|----------|------|----------| | single | 提取第10帧作为代表帧 | 快速预览、简单内容视频 | 处理速度快、资源占用少 | 可能错过重要内容变化 | | multiple | 均匀提取5帧覆盖整个视频 | 一般视频内容、教程视频 | 内容覆盖全面、结果可控 | 处理时间适中 | | keyframes | 提取所有关键帧（场景变化点） | 复杂场景、动作密集视频 | 捕获所有重要场景变化 | 提取帧数不可控、耗时较长 |

配置帧提取策略：

通过交互式选择设置（推荐）：

# 处理视频时交互式选择帧提取策略
frame-sense video.mp4 --frame-strategy

# 或者直接指定策略
frame-sense video.mp4 --frame-strategy multiple
frame-sense video.mp4 --frame-strategy keyframes
frame-sense video.mp4 --frame-strategy single

通过配置文件设置：

# 查看当前配置
frame-sense --config

# 手动编辑配置文件，修改 frameExtractionStrategy 字段：
# ~/.config/frame-sense-nodejs/frame-sense.json
{
  "frameExtractionStrategy": "multiple"  // 可选：single, multiple, keyframes
}

策略选择建议：

• 📷 日常视频、Vlog → single（快速处理）
• 🎬 电影、长视频 → multiple（全面覆盖）
• 🎮 游戏录像、运动视频 → keyframes（捕获动作变化）
• 📚 教程、演示视频 → multiple（平衡效果与速度）

混合批处理优化

• 智能分组: 将图片和视频帧混合分组，最大化 AI API 使用效率
• 并行处理: 支持多文件同时处理，提升整体速度
• 内存管理: 合理管理临时文件和内存使用
• 错误恢复: 单个文件失败不影响整体处理进程

🚨 注意事项

API 使用限制

• Google Gemini API 有调用频率限制
• 建议合理设置批处理大小，避免超出限制
• 大量文件处理时建议分批进行

性能优化建议

• 对于大量文件，建议使用 --batch-size 参数调整批处理大小
• 视频文件处理相对较慢，因为需要提取帧
• 启用 --verbose 模式可以查看详细的处理信息

数据安全

• 图像数据会发送到 Google Gemini API 进行分析
• 不会永久存储用户的图像数据

🌟 致谢

• Google Gemini AI - 提供强大的图像识别能力（主要是免费😅）
• FFmpeg - 视频处理核心
• Sharp - 高性能图像处理

让文件管理变得更智能 🚀

GitHub • NPM • Issues