# 视频音频对齐合成工具

**Repository Path**: az13js/timetag

## Basic Information

- **Project Name**: 视频音频对齐合成工具
- **Description**: 将录音通过时间平移与视频合成，使音频内容与视频内容对齐。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-01
- **Last Updated**: 2026-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# timetag

视频音频对齐合成工具。将录音通过时间平移与视频合成，使音频内容与视频内容对齐。

> See English version at [README.md](README.md)

## 依赖

- Python 3（仅使用内置库）
- ffmpeg（需在 PATH 中）

## 快速使用

1. 准备 `info.json`（参见下方配置格式）
2. 将音频和视频文件放入项目目录
3. 运行 `python align.py`
4. 输出 `output.mp4`

## 配置文件 info.json

```json
{
  "audio": {
    "filePath": "./export.wav",
    "AlignSecond": 0.009
  },
  "screenshot": {
    "filePath": "./screenshot.mp4",
    "AlignSecond": 2.6825
  }
}
```

| 字段 | 含义 |
|------|------|
| `audio.filePath` | 音频文件路径（相对或绝对） |
| `audio.AlignSecond` | 音频中参考标签出现的时间点（秒） |
| `screenshot.filePath` | 视频文件路径（相对或绝对） |
| `screenshot.AlignSecond` | 视频中参考标签出现的时间点（秒） |

## 对齐逻辑

视频长度不裁剪、不延长。音频按以下规则处理：

1. **音频早于视频**：延迟音频使其与视频标签对齐
2. **音频晚于视频**：裁剪音频开头
3. **音频短于视频**：末尾填充静音
4. **视频原音频**：完全替换，不保留

## 输出格式

- **视频**：h264（原画质，无损复制）
- **音频**：AAC（48kHz 立体声）
- **时长**：与视频完全一致

## 工作原理

`offset = 视频.AlignSecond - 音频.AlignSecond`

- `offset > 0`：音频落后于视频 → `adelay` 延迟音频
- `offset < 0`：音频领先于视频 → `atrim` 裁剪音频开头
- `offset == 0`：无需偏移，仅裁剪至视频时长