多平台视频转录器代理“screenpal视频转录器”
这个项目已经发展 --视频转录管道现在作为一个5级无头管道在 鹅cli视频转录食谱该仓库具有并行gpu阶段、jaeger跟踪、批处理模式、恢复和鞭炮微管理调度。此存储库保留为原始的kiro-cli实现。
太长，读不下去了：将任何视频转换为文档
此存储库包含用于构建和增强AWS Kiro CLI自定义代理的文件，该代理从以下位置获取视频URL S3、ScreenPal、YouTube或Twitch 并生成一个包含音频转录、视觉分析和统一markdown文档的目录。
Kiro CLI架构集成
该代理遵循 三层Kiro CLI架构:
第1层：指导文件(~/.kiro/steering/)
治理和标准 -直接加载到代理推理上下文中：
- 代码风格约定（命名函数、JSDoc要求）
- JavaScript安全标准（类型安全、防御性编程）
- MCP健康标准（服务器可靠性、超时管理）
- 视频处理标准（质量阈值、格式验证）
第二层：知识库(~/.kiro/knowledge_bases/screenpal-video-transcriber/)
领域特定参考 -通过询问 /knowledge search:
- 视频处理工作流程和示例
- 特定于平台的API文档
- 故障排除指南和最佳实践
- MCP服务器配置模式
第3层：实时上下文注入（Context7）
实时文档 -通过触发 use context7:
- 来源的最新官方文件
- 最新API参考资料和示例
- 当前安装和设置程序
- 实时故障排除和错误解决
为何这很重要:
- 指导文档确保一致、安全的视频处理
- 知识库提供可搜索的参考资料
- Context7为快速发展的领域提供了新的文档
- 干净的分隔可以防止上下文污染，同时确保准确性
时间和学分+MCP概述
预计成本：~开发大约需要90个Kiro学分，~我建议部署30个学分，因为我还没有测试过重新部署。~从短视频创建一个文档大约需要3个学分，还没有尝试过更长的视频。适合每月50学分的免费等级，特别是claude-haiku-4.5（截至2026年1月为0.4倍学分倍数）。
开发时间：约6小时用于规划和建设，约5分钟用于处理短视频、截图并生成统一报告。
MCP服务器:
- 视频转录器：使用Whisper进行音频转录
- 视觉服务器：使用Moondream2 VLM进行帧分析
- ffmpeg mcp：使用场景检测进行帧提取
⚠️ 重要使用说明
此存储库包含可能会混淆screenpal视频转录器代理的代理开发文档。 从其他目录运行代理 避免代理认为它是在创建代理，而不是成为代理。
对于生产使用，考虑将开发文档移动到单独的存储库中。
___
/ _ \
| / \ |
| \_/ |
\___/ ___
_|_|_/[_]\__==_
[---------------]
| O /---\ |
| | | |
| \___/ |
[---------------]
[___]
| |\\
| | \\
[ ] \\_
/|_|\ ( \
//| |\\ \ \
// | | \\ \ \
// |_| \\ \_\
// | | \\
//\ | | /\\
// \ | | / \\
// \ | | / \\
// \|_|/ \\
// [_] \\
// H \\
// H \\
// H \\H H // \\ // \\
目的
screenpal视频转录代理为任何支持的视频平台提供完整的统一工作流程：
- 平台检测：自动从URL模式中检测ScreenPal、YouTube、Twitch或S3
- 音频转录：使用OpenAI Whisper提取和转录语音
- 视觉分析：提取场景变化时的视频帧，并使用Moondream2 VLM进行分析
- 统一文档：按时间戳自动将音频和视频数据与平台元数据相关联
输出：在中创建了三个集成文件 ~/Downloads/video-transcripts-{timestamp}/:
{video-id}-UNIFIED.json-将音频片段与视觉帧相结合的结构化数据{video-id}-UNIFIED.md-人类可读的同步漫游{video-id}-frames/-提取PNG帧以供参考
⚠️ 重要提示：统一工作流
代理在一个请求中自动处理所有三个步骤：
- 提取音频并转录为文本
- 提取视频帧并分析视觉效果
- 创建按时间戳关联音频+视频的统一文档
无需手动选择工具，只需提供ScreenPal URL即可。
建筑
代理协调一个统一的三阶段管道：
第一阶段：音频提取和转录
- yt-dlp从视频URL中提取音频流（支持ScreenPal、YouTube、Twitch、S3）
- OpenAI Whisper转录为带时间戳的文本段
第二阶段：视觉分析
- FFmpeg在场景变化时提取帧（阈值：0.4）
- Moondream2 VLM分析每个帧的UI元素和内容
- 生成带有时间戳的详细视觉描述
第三阶段：统一文档创建
- 按时间戳将音频片段与视觉帧相关联
- 创建同步的JSON和Markdown文档
- 将所有输出存储在
~/Downloads/video-transcripts-{timestamp}/
使用的MCP服务器
- 视频转录器mcp：音频提取和耳语转录
- ffmpeg mcp：使用场景检测进行帧提取
- 月亮梦mcp：使用Ollama+Moondream2进行视觉分析
- yt-dlp：媒体流提取
- 奥拉玛：本地VLM运行时（本地macOS或Docker）
知识库结构
knowledge/
├── transcription-tools/ # Core agent documentation and workflows
├── workflow-automation/ # MCP server setup and configuration
├── screenpal-api/ # ScreenPal platform integration
└── best-practices/ # Video processing best practicesPerl脚本
该项目使用Perl脚本进行系统自动化和配置管理。Perl为我们的视频处理工作流程提供了强大的文本处理、系统集成和跨平台兼容性。
安装脚本(setup.pl)
主安装脚本自动化了完整的安装和配置过程：
# Make executable and run
chmod +x setup.pl
./setup.pl它的作用：
- 验证Kiro CLI安装
- 安装依赖项（yt-dlp、OpenAI Whisper、uv包管理器）
- 从源代码克隆和构建MCP服务器
- 为Olama配置Moondream模型
- 创建MCP配置文件
- 设置代理配置文件
- 执行全面验证
备注：该脚本自2026年1月起运行，但未得到积极维护。如果遇到问题，请参阅文档中的手动设置说明。
为什么是Perl？
- 文本处理：非常适合配置文件操作和JSON处理
- 系统集成：原生支持shell命令和文件操作
- 交叉平台的：在macOS、Linux和Windows上一致工作
- 成熟生态系统：JSON、文件处理和HTTP操作的稳定库
- 错误处理：强大的错误检查和报告功能
代理人包括 execute_bash 该工具用于shell命令执行、文件清理和目录操作，以及现有的视频处理和视觉分析功能。
先决条件
- 已安装Kiro CLI
- Node.js 16+和npm
- 本地Ollama或Docker
- 4GB+RAM，5GB+磁盘空间
- ### 安全身份验证设置
选项1:GitHub CLI（建议用于本地开发）
# Authenticate with GitHub CLI
gh auth login
# Setup secure token access
./scripts/setup-github-token.sh
# Use secure authentication
./scripts/docker-auth-secure.sh选项2:AWS参数存储（建议用于生产）
# Store token securely in AWS Parameter Store
./scripts/store-github-token-aws.sh ghp_your_token_here
# Use secure authentication
./scripts/docker-auth-secure.shS3视频：环境中的AWS凭据（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN（如果需要））
备注：安装脚本会自动安装yt-dlp和OpenAI Whisper依赖项。
安装
# Run the automated setup script
chmod +x setup.pl
./setup.pl安装脚本将：
- 验证Kiro CLI安装
- 安装yt-dlp进行视频提取
- 安装OpenAI Whisper进行转录
- 从源构建MCP服务器
- 用Moondream模型设置Olama
- 配置全局MCP设置(
~/.kiro/settings/mcp.json) - 创建代理配置文件(
~/.kiro/agents/screenpal-video-transcriber.json) - 验证所有组件
启动代理
从项目目录中：
cd /path/to/kiro-cli-custom-agent-screenpal-video-transcription
kiro-cli chat --agent screenpal-video-transcriber备注：当您在项目目录中时，会自动发现代理。不需要全局链接。
处理视频
> Please transcribe this ScreenPal video: https://go.screenpal.com/[video-id]
> Please transcribe this YouTube video: https://youtube.com/watch?v=[video-id]
> Please transcribe this Twitch video: https://twitch.tv/videos/[video-id]
> Please transcribe this S3 video: https://bucket.s3.amazonaws.com/video.mp4代理人将：
- 验证URL
- 使用yt-dlp提取音频
- 用Whisper转录
- 提取关键帧
- 使用Moondream分析视觉内容
- 生成带有视觉描述的综合成绩单
- 创建按时间戳关联音频+视频的统一文档
输出文件 创建于 ~/Downloads/video-transcripts-{timestamp}/:
{video-id}-UNIFIED.json-结构化同步数据{video-id}-UNIFIED.md-人类可读的演练{video-id}-frames/-提取的PNG帧
配置
代理使用两级MCP配置系统：
全局MCP配置(~/.kiro/settings/mcp.json)
为所有代理定义所有可用的MCP服务器：
{
"mcpServers": {
"video-transcriber": {
"command": "sh",
"args": ["-c", "node /tmp/video-transcriber-mcp/dist/index.js 2>/dev/null"],
"env": {
"WHISPER_MODEL": "base",
"YOUTUBE_FORMAT": "bestaudio",
"WHISPER_DEVICE": "cpu"
},
"disabled": false
},
"vision-server": {
"command": "sh",
"args": ["-c", "node /tmp/moondream-mcp/build/index.js 2>/dev/null"],
"env": {
"OLLAMA_BASE_URL": "http://localhost:11434"
},
"disabled": false
},
"ffmpeg-mcp": {
"command": "uvx",
"args": ["video-creator"],
"env": {
"SCENE_THRESHOLD": "0.4"
},
"disabled": false
}
}
}代理人简介(~/.kiro/agents/screenpal-video-transcriber.json)
此代理的专用配置：
{
"name": "screenpal-video-transcriber",
"description": "Specialized agent for processing ScreenPal videos...",
"includeMcpJson": true,
"tools": [
"fs_read", "fs_write", "knowledge", "execute_bash",
"@video-transcriber/transcribe_video",
"@ffmpeg-mcp/extract_frames_from_video",
"@ffmpeg-mcp/get_video_info",
"@vision-server/analyze_image",
"@vision-server/detect_objects",
"@vision-server/generate_caption"
],
"model": "claude-sonnet-4"
}主要特点：
includeMcpJson: true-从全局配置继承所有服务器- 用于视频处理和视觉分析的完整工具链
- 无服务器重复-所有MCP服务器都来自全局配置
特性
- URL验证：从URL模式自动检测平台（ScreenPal、YouTube、Twitch、S3）
- 音频转录：带时间戳的高质量语音转文本
- 帧提取：关键时刻使用FFmpeg进行场景变化检测
- 详细的视觉分析：完整的UI元素描述，包括：
- 精确的文本和按钮标签 - 窗口标题和菜单项 - 显示的表单字段和数据 - 视觉布局和定位 - 交互元素和控件
- 时间戳相关性：同步视听演练
- 统一输出：单个文档结合了音频和视频
- 本地存储：有组织的产出
~/Downloads/video-transcripts-{timestamp}/ - 注重隐私：没有数据离开您的本地环境
故障排除
常见问题
“虚拟”工具错误：MCP服务器通信故障
- 根本原因：MCP服务器未在Kiro CLI中正确注册工具
- 解决方案：重新启动代理会话：
kiro-cli chat --agent screenpal-video-transcriber
未找到工具：缺少依赖关系或配置问题
- 解决方案：运行安装脚本：
./setup.pl - 检查：验证yt-dlp和Whisper是否已安装
Ollama没有回应：视觉分析不可用
- 解决方案：启动Ollama：
ollama serve或检查Docker容器 - 验证:
curl -s http://localhost:11434/api/tags
帧提取问题：场景检测或帧质量问题
- 原因：场景阈值不正确或视频格式问题
- 解决方案：调整scene_threshold参数或验证视频可访问性
文档
隐私和安全
- 本地处理：所有转录和分析都在本地进行
- 无云API：没有外部服务依赖关系
- 安全URL：仅处理经过验证的平台域（ScreenPal、YouTube、Twitch、S3）
- 受控访问：代理权限包括视频处理和视觉分析任务