# Frame-Sense
[![npm](https://img.shields.io/npm/v/@zhangziheng/frame-sense)](https://www.npmjs.com/package/@zhangziheng/frame-sense) [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/typescript-5.7.2-blue)](https://www.typescriptlang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 🎯 **智能媒体文件重命名工具** - 基于 AI 的视频和图片文件自动语义化命名

Frame-Sense Hero
Frame-Sense 是一个基于 AI 的智能命令行工具，结合 FFmpeg 和 Google Gemini AI 模型，自动分析视频和图片内容，生成语义化的文件名。支持批量处理、混合媒体类型处理，让文件管理变得更加智能和高效。 ## 📋 目录 - [✨ 主要特性](#-主要特性) - [📦 安装](#-安装) - [🚀 快速开始](#-快速开始) - [🔧 命令详解](#-命令详解) - [⚙️ 系统要求](#️-系统要求) - [🚨 注意事项](#-注意事项) - [技术栈](#技术栈) - [🌟 致谢](#-致谢) ## ✨ 主要特性 - 🎯 **AI 自动重命名** - 基于图像内容生成语义化文件名 - 📹 **视频 + 图片支持** - 自动提取视频帧，统一处理所有媒体文件 - ⚡ **批量处理** - 一次性处理整个目录，支持混合媒体类型 - 👀 **预览模式** - 先预览重命名结果，确认无误后再执行 - 🔧 **自定义配置** - 支持自定义 AI 提示词、批次大小、文件名长度 - 📁 **输出目录** - 可指定输出目录，避免覆盖原文件 - 🎬 **多种帧提取策略** - 支持单帧、多帧、关键帧等不同提取策略 - 🏷️ **文件名模板** - 支持自定义文件名模板，包含前缀、日期格式等 - 📅 **智能日期提取** - 自动从 EXIF 数据或文件系统提取日期信息 ## 📦 安装 ### 全局安装 ```bash npm install -g @zhangziheng/frame-sense ``` ## 🚀 快速开始 ### 1. 安装 FFmpeg（如已安装可跳过） FFmpeg 是视频处理必需依赖，请根据您的系统安装： #### macOS (使用 Homebrew) ```bash brew install ffmpeg ``` #### Ubuntu/Debian ```bash sudo apt update sudo apt install ffmpeg ``` #### Windows (使用 Chocolatey) ```bash choco install ffmpeg ``` #### 验证安装 ```bash ffmpeg -version ``` ### 2. 配置 API Key 首次使用需要配置 Google Gemini API Key： ```bash frame-sense config --api YOUR_GEMINI_API_KEY ``` API 注册地址：[Google AI Studio API](https://aistudio.google.com/apikey) ### 2. 处理单个文件 ```bash # 分析视频文件 frame-sense video.mp4 # 分析图片文件 frame-sense image.jpg # 预览重命名结果（不实际重命名） frame-sense video.mp4 --preview ``` ### 3. 批量处理目录 ```bash # 处理目录中的所有媒体文件（自动识别为目录） frame-sense /path/to/media/folder # 预览批量重命名结果 frame-sense /path/to/media/folder --preview # 指定输出目录 frame-sense /path/to/media/folder --output /path/to/output ``` ### 使用示例 #### 基础使用 ```bash # 分析单个视频文件 frame-sense vacation.mp4 # 预览重命名结果 frame-sense vacation.mp4 --preview # 批量处理目录（自动识别） frame-sense ./photos # 输出到指定目录 frame-sense ./videos --output ./renamed_videos ``` #### 高级配置 ```bash # 帧提取策略 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 ``` #### 文件名模板功能 ```bash # 自定义前缀 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 ``` #### 系统检查 ```bash # 检查 API 连接 frame-sense --test # 检查系统依赖（FFmpeg） frame-sense --deps # 查看支持的格式 frame-sense --formats # 查看当前配置 frame-sense --config ``` ## 🔧 命令详解 ### 主命令 ```bash frame-sense [文件路径] [选项] ``` #### 选项说明 - `-p, --preview` - 预览重命名结果，不实际执行 - `-o, --output ` - 指定输出目录 - `-b, --batch ` - 设置批量处理大小 - `-f, --frame-strategy [strategy]` - 设置帧提取策略，不带值时进入交互选择 - `-v, --verbose` - 启用详细输出和调试模式 - `-t, --test` - 测试 AI API 连接 - `--config` - 显示当前配置信息 - `--formats` - 显示支持的媒体格式 - `--deps` - 检查系统依赖 - `--template