Package Exports

@zhangziheng/frame-sense
@zhangziheng/frame-sense/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@zhangziheng/frame-sense) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Frame-Sense

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

Frame-Sense Hero

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 支持从多个来源提取日期信息，按优先级顺序：

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

# 设置日期来源优先级
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