VoiceToVision 🎙️→🎬

让 AI 听懂你的声音，为每个故事找到最完美的画面

✨ 这是什么？

VoiceToVision 是一款 AI 驱动的智能视频匹配工具：你只需提供一段旁白音频和一堆视频素材，它就能自动为每个音频片段找到最相关的视频画面。

🎯 核心功能

• 🎧 语音识别 - 使用 OpenAI Whisper 将音频转为带时间戳的文本
• 🧠 语义理解 - 用 Sentence Transformer 为视频生成语义指纹
• 🔍 智能匹配 - 计算音频片段与视频的语义相似度
• 📋 一键导出 - 生成编辑决策列表 + 导出匹配视频片段 + HTML 预览
• 👥 多用户支持 - 每个用户独立的资料隔离工作空间

🚀 快速开始

安装

# 克隆仓库
git clone https://github.com/Looperswag/AutoSmartMixer_draft_VO.git
cd AutoSmartMixer_draft_VO

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate    # Windows

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

使用

# 运行主程序
python -m src.main

程序会提示你输入用户名，然后自动创建你的工作空间目录。

📖 使用场景

• 短视频创作者 - 快速为旁白匹配合适的 B-roll 素材
• 纪录片制作 - 自动整理和归类视频素材库
• 教育视频 - 为课程音频补充视觉内容
• 播客转视频 - 将音频播客自动转换为视频内容

🏗️ 项目结构

VoiceToVision/
├── src/                          # 源代码目录
│   ├── __init__.py
│   ├── main.py                   # 程序主入口
│   ├── phase_1_analyzer.py       # 音频和视频分析模块
│   ├── phase_2_matcher.py        # 语义匹配模块
│   ├── phase_3_timeline_generator.py # 时间线/EDL生成模块
│   ├── phase_4_clip_exporter.py  # 视频片段导出模块
│   └── utils/                    # 工具类模块
│       ├── __init__.py
│       ├── config_loader.py      # YAML 配置文件加载
│       ├── file_handler.py       # JSON 文件读写、目录创建
│       ├── logger_setup.py       # 日志系统设置
│       ├── exceptions.py         # 自定义异常类
│       ├── config_validator.py   # 配置验证器
│       └── path_builder.py       # 路径构建工具
├── config.yaml                   # 主配置文件
├── requirements.txt              # Python 依赖列表
└── user/                         # 用户工作区根目录 (自动创建)
    └── <username>/               # 特定用户的工作目录
        ├── data/                 # 用户输入数据
        │   ├── input_audio/      # 存放输入的音频文件
        │   └── input_video_clips/ # 存放视频素材片段
        └── output/               # 用户输出结果
            ├── processed_data/   # 处理后的中间数据
            ├── edl/              # 编辑决策列表
            ├── exported_clips/   # 导出的视频片段
            └── app.log           # 应用程序日志文件

🛠️ 环境依赖

Python

• Python 3.8 或更高版本

核心依赖

openai-whisper       # 音频转录
sentence-transformers # 语义嵌入生成
moviepy              # 视频处理
PyYAML               # 配置文件解析
numpy                # 数值计算

可选依赖

• FFmpeg - moviepy 和 whisper 在处理某些音视频格式时需要 FFmpeg 支持

⚙️ 配置说明

配置文件 config.yaml 包含以下主要部分：

模型配置

models:
  whisper_model_name: "base"      # Whisper 模型大小
  embedding_model_name: "LaBSE"   # 语义嵌入模型

匹配设置

settings:
  similarity_threshold: -1.0      # 相似度阈值 (-1 表示不过滤)
  top_k_candidates: 5             # 每个音频片段匹配的视频数量
  video_reuse_strategy: "reuse_different_segments"  # 视频重用策略

导出设置

clip_export:
  max_clips_per_segment: 5        # 每个片段导出的视频数量
  extract_subclips: true          # 是否提取子片段
  padding_seconds: 2.0            # 前后填充时间
  create_preview_metadata: true   # 生成 HTML 预览

📊 输出说明

处理完成后，所有输出文件位于 user/<username>/output/ 目录：

目录/文件	说明
processed_data/audio_transcription.json	音频转录结果，包含时间戳
processed_data/video_metadata_embeddings.json	视频元数据和语义嵌入
edl/final_edit_list.json	编辑决策列表 (EDL)
exported_clips/	导出的视频片段
exported_clips/index.html	浏览器预览页面
app.log	应用程序日志