---
document_type: "extension_design"
title: "声音识别扩展设计 (Phase 5+)"
service: "MOMENTRY_CORE"
date: "2026-04-28"
status: "planning"
current_state: "draft"
owner: "Warren"
created_by: "OpenCode"
created_at: "2026-04-28"
version: "V1.0"
tags:
  - "sound_recognition"
  - "audio_embedding"
  - "animal_sound"
  - "environmental_sound"
  - "weapon_sound"
  - "musical_instrument"
  - "phase_5"
related_documents:
  - "IDENTITY_REFERENCE_VECTOR_DESIGN.md"
  - "MOMENTRY_CORE_ARCHITECTURE_V2.md"
ai_query_hints:
  - "查詢声音识别扩展设计"
  - "查詢動物叫聲 embedding"
  - "查詢雷雨聲 embedding"
  - "查詢槍炮聲 embedding"
  - "查詢樂器聲 embedding"
---

# 声音识别扩展设计 (Phase 5+)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-28 |
| 文件版本 | V1.0 |
| 状态 | Phase 5+ 待辦事項 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-28 | 創建声音识别扩展设计（Phase 5+） | OpenCode | OpenCode |

---

## 概述

本文檔定義 Momentry Core Identity 系統的 **声音识别扩展设计**，屬於 **Phase 5+ 待辦事項**。

核心理念：**将声音作为 Identity 进行识别和注册，支持动物叫聲、雷雨聲、槍炮聲、樂器聲等。**

---

## 设计目标

### 核心目标

| 目標 | 說明 |
|------|------|
| **声音 Identity** | 将声音作为 Identity 进行注册和管理 |
| **声音 Embedding** | 提取声音的 embedding vector |
| **声音匹配** | 在音频中识别特定声音的出现 |
| **1对多参考向量** | 同一声音可存储多个 embedding（不同样本、不同质量） |
| **声音分类** | 支持多種声音类型（动物、环境、武器、樂器） |

### 适用场景

| 场景 | 说明 |
|------|------|
| **电影/视频分析** | 识别电影中的枪声、雷声、狗叫声等 |
| **环境监控** | 监控特定环境声音（雷雨、警报等） |
| **音频搜索** | 搜索包含特定声音的音频片段 |
| **声音数据库** | 建立声音 Identity 数据库（动物叫声库、乐器声音库） |

---

## 声音类型分类

### identity_type 扩展

```sql
-- identities 表 identity_type 字段扩展
identity_type VARCHAR(30) -- 新增类型: sound, animal, environmental
```

### 声音类型定义

| identity_type | 说明 | 子类型 | 示例 |
|---------------|------|--------|------|
| **sound** | 通用声音 | TBD | 各种声音 |
| **animal** | 动物叫声 | animal_dog_bark, animal_cat_meow, animal_bird_chirp | 狗叫声、猫叫声、鸟叫声 |
| **environmental** | 环境音 | environmental_thunder, environmental_rain, environmental_wind | 雷声、雨声、风声 |
| **weapon** | 武器声 | weapon_gunshot, weapon_explosion, weapon_siren | 枪声、爆炸声、警报声 |
| **musical** | 乐器声 | musical_guitar, musical_piano, musical_drums | 吉他声、钢琴声、鼓声 |

---

## reference_data JSONB 结构

### sound_embeddings 结构

```json
{
  "sound_embeddings": [
    {
      "embedding": [0.1, 0.2, ...],          // TBD (声音 embedding 维度)
      "source": "audio_segment",
      "file_uuid": "vid_001",
      "timestamp_start": 10.0,
      "timestamp_end": 15.0,
      "sound_type": "animal_dog_bark",
      "quality_score": 0.95,
      "sample_rate": 44100,
      "duration": 5.0,
      "created_at": "2026-04-28T13:00:00Z"
    },
    {
      "embedding": [0.3, 0.4, ...],
      "source": "audio_segment",
      "file_uuid": "vid_002",
      "timestamp_start": 20.0,
      "timestamp_end": 25.0,
      "sound_type": "animal_dog_bark",
      "quality_score": 0.88,
      "sample_rate": 44100,
      "duration": 5.0,
      "created_at": "2026-04-28T14:00:00Z"
    }
  ],
  "audio_urls": [
    "https://cdn.xxx.com/sounds/dog_bark_001.wav",
    "https://cdn.xxx.com/sounds/dog_bark_002.wav"
  ]
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| embedding | Array[TBD] | Yes | 声音 embedding vector（维度 TBD） |
| source | String | Yes | 来源: audio_segment, audio_file, manual_upload |
| file_uuid | String | Yes | 档案 UUID |
| timestamp_start | Float | Yes | 开始时间（秒） |
| timestamp_end | Float | Yes | 结束时间（秒） |
| sound_type | String | Yes | 声音类型（见上表） |
| quality_score | Float | No | 质量评分（0.0-1.0） |
| sample_rate | Integer | No | 音频采样率 |
| duration | Float | No | 音频时长（秒） |
| created_at | String | Yes | 建立时间（ISO 8601） |

---

## 声音 Embedding 模型选择

### 待评估模型

| 模型 | 维度 | 说明 | 适用场景 |
|------|------|------|----------|
| **PANNs** | TBD | AudioSet 预训练模型 | 通用声音识别 |
| **YAMNet** | 1024-dim | TensorFlow 音频分类模型 | 通用声音分类 |
| **VGGish** | 128-dim | YouTube-8M 音频模型 | 音频特征提取 |
| **Audio Spectrogram Transformer** | TBD | 基于 Transformer 的音频模型 | 音频理解 |
| **CLAP** | 512-dim | Contrastive Language-Audio Pretraining | 文本-音频匹配 |

### 模型评估指标

| 指标 | 说明 |
|------|------|
| **Embedding 维度** | 维度大小影响存储和计算效率 |
| **识别准确率** | 声音识别准确率 |
| **提取速度** | Embedding 提取速度 |
| **模型大小** | 模型文件大小 |
| **GPU 支持** | 是否支持 MPS/CUDA |

---

## 声音 Identity 注册流程

### 示例: 注册狗叫声 Identity

```python
def register_animal_sound_identity(sound_name, sound_type, audio_files):
    """
    声音 Identity 注册流程:
    1. 提取多个音频样本的 embedding
    2. 存储到 reference_data JSONB
    3. 注册到 identities 表
    """
    
    # Step 1: 提取 embedding
    sound_embeddings = []
    for audio_file in audio_files:
        # 加载音频
        audio_data = load_audio(audio_file)
        
        # 提取 embedding
        embedding = audio_model.extract_embedding(audio_data)
        
        # 评估质量
        quality_score = evaluate_audio_quality(audio_data)
        
        # 存储到 reference_data
        sound_embeddings.append({
            "embedding": embedding.tolist(),
            "source": "audio_file",
            "sound_type": sound_type,
            "quality_score": quality_score,
            "sample_rate": audio_data["sample_rate"],
            "duration": audio_data["duration"],
            "created_at": datetime.now().isoformat()
        })
    
    # Step 2: 注册 Identity
    identity = {
        "identity_id": generate_uuid(),
        "name": sound_name,
        "identity_type": "animal",
        "source": "manual",
        "reference_data": {
            "sound_embeddings": sound_embeddings,
            "audio_urls": [audio_file.url for audio_file in audio_files]
        }
    }
    
    # Step 3: 计算 centroid
    centroid = calculate_centroid([e["embedding"] for e in sound_embeddings])
    identity["sound_embedding"] = centroid
    
    # 存储到資料庫
    db.insert_identity(identity)
    
    return identity
```

---

## 声音匹配流程

### 示例: 在视频中识别狗叫声

```python
def detect_animal_sound(file_uuid, sound_identity, threshold=0.85):
    """
    声音匹配流程:
    1. 提取视频音频段落的 embedding
    2. 与 Identity 的 sound_embeddings 进行匹配
    3. 返回匹配结果
    """
    
    # Step 1: 提取视频音频段落
    audio_segments = extract_audio_segments(file_uuid, segment_duration=5.0)
    
    # Step 2: 匹配
    results = []
    for segment in audio_segments:
        # 提取段落 embedding
        segment_embedding = audio_model.extract_embedding(segment)
        
        # 1对多匹配
        match_result = combined_match(
            detected_embedding=segment_embedding,
            reference_embeddings=sound_identity["reference_data"]["sound_embeddings"],
            threshold=threshold
        )
        
        if match_result["is_match"]:
            results.append({
                "timestamp_start": segment["timestamp_start"],
                "timestamp_end": segment["timestamp_end"],
                "match_score": match_result["final_score"],
                "sound_type": sound_identity["name"]
            })
    
    return results
```

---

## 数据库设计

### identities 表扩展

```sql
-- Migration TBD: identities 表添加 sound_embedding
ALTER TABLE identities ADD COLUMN sound_embedding VECTOR(TBD);

-- 索引配置
CREATE INDEX idx_identities_sound_embedding ON identities 
 USING ivfflat (sound_embedding vector_cosine_ops) 
 WITH (lists = 100);
```

### sound_type 分类表（可选）

```sql
CREATE TABLE sound_types (
    sound_type_code    VARCHAR(50) PRIMARY KEY,  -- animal_dog_bark
    sound_type_name    TEXT NOT NULL,            -- 狗叫声
    category           VARCHAR(20),              -- animal, environmental, weapon, musical
    description        TEXT,
    created_at         TIMESTAMPTZ DEFAULT NOW()
);
```

---

## 实作计划

### Phase 5.1: 模型评估和选择

- [ ] 评估 PANNs、YAMNet、VGGish、CLAP 等模型
- [ ] 确定 embedding 维度
- [ ] 确定 GPU 支持（MPS/CUDA）
- [ ] 性能基准测试

### Phase 5.2: 数据库扩展

- [ ] Migration TBD: identities 表添加 sound_embedding VECTOR(TBD)
- [ ] sound_types 分类表建立
- [ ] 测试数据建立

### Phase 5.3: 声音 Identity 注册

- [ ] 声音 embedding 提取脚本
- [ ] reference_data JSONB 存储
- [ ] Identity 注册 API

### Phase 5.4: 声音匹配

- [ ] 音频段落提取脚本
- [ ] 1对多匹配算法实现
- [ ] 匹配结果存储到 pre_chunks

### Phase 5.5: 前端集成

- [ ] 声音 Identity 管理界面
- [ ] 声音匹配结果展示
- [ ] 声音搜索功能

---

## 待辦事項

| 項目 | 優先級 | 說明 |
|------|--------|------|
| 模型评估和选择 | 高 | Phase 5.1 |
| 数据库扩展 | 高 | Phase 5.2 |
| 声音 Identity 注册 | 中 | Phase 5.3 |
| 声音匹配 | 中 | Phase 5.4 |
| 前端集成 | 低 | Phase 5.5 |

---

## 技术挑战

### 挑战 1: Embedding 维度选择

| 问题 | 说明 |
|------|------|
| **维度过高** | 存储成本高，计算效率低 |
| **维度过低** | 信息损失，识别准确率下降 |
| **解决方案** | 评估不同模型，选择平衡维度（推荐 128-512 dim） |

### 挑战 2: 声音样本质量

| 问题 | 说明 |
|------|------|
| **噪音干扰** | 背景噪音影响 embedding 质量 |
| **采样率不统一** | 不同音频采样率差异 |
| **解决方案** | 1对多参考向量 + 质量评分机制 |

### 挑战 3: 声音重叠识别

| 问题 | 说明 |
|------|------|
| **多声音重叠** | 同时出现多种声音 |
| **解决方案** | 音频分离技术 + 多 Identity 匹配 |

---

## 限制條件

- 本设计为 Phase 5+ 待辦事項，不在当前实作范围
- 声音 embedding 维度 TBD，需模型评估
- 声音识别准确率依赖模型性能
- 需要 GPU 支持（MPS/CUDA）

---

## 相关文件

- `docs_v1.0/ARCHITECTURE/IDENTITY_REFERENCE_VECTOR_DESIGN.md` - 1对多参考向量设计
- `docs_v1.0/ARCHITECTURE/MOMENTRY_CORE_ARCHITECTURE_V2.md` - 核心架构设计
- `docs_v1.0/IMPLEMENTATION/FILE_IDENTITY_API_DESIGN.md` - API 设计

---

## 版本信息

- 版本: V1.0
- 建立日期: 2026-04-28
- 文件更新: 2026-04-28
- 状态: Phase 5+ 待辦事項
