# VideoConv - 视频格式转换器

一个功能强大的视频格式转换工具，支持多种视频格式之间的转换，并提供丰富的配置选项。

## 功能特性

- **广泛的格式支持**
  - 输入格式：MP4, AVI, MKV, MOV, WMV, FLV, WebM, M4S, MPEG, MPG, 3GP, VOB, MTS, M2TS, DIVX, ASF, RM, RMVB
  - 输出格式：MP4, AVI, MKV, MOV, WMV, FLV, WebM, GIF

- **灵活的编码设置**
  - 视频编码器选择（H.264, H.265 等）
  - 音频编码器选择（AAC, MP3 等）
  - 可调节视频/音频比特率
  - CRF 质量控制（0-51）
  - 编码速度预设

- **高级功能**
  - 分辨率缩放（保持宽高比）
  - 帧率调整
  - 移除音频轨道
  - 自定义 FFmpeg 参数

- **配置持久化**
  - 基于 `pytola_core.config.ConfigMixin` 的配置系统
  - 自动保存和加载用户配置
  - JSON 格式的配置文件

## 安装要求

本工具依赖系统安装的 **FFmpeg**。请确保 FFmpeg 已正确安装并添加到系统 PATH 中。

### 安装 FFmpeg

**Windows:**

```bash
# 使用 winget
winget install Gyan.FFmpeg

# 或使用 chocolatey
choco install ffmpeg

# 或从官网下载：https://ffmpeg.org/download.html
```

**macOS:**

```bash
brew install ffmpeg
```

**Linux:**

```bash
# Debian/Ubuntu
sudo apt update && sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

# Arch Linux
sudo pacman -S ffmpeg
```

## 使用方法

### GUI 图形界面（推荐）

```bash
# 启动图形界面
videoconv-gui

# 或者使用参数
videoconv --gui
```

GUI 功能特点：

- 🎨 **精美界面**：使用 pytola_qtstyles 内置 dark 主题
- 📁 **文件选择**：可视化浏览和选择输入/输出文件
- ⚙️ **实时设置**：所有转换参数一目了然
- 📊 **进度显示**：实时转换进度条和状态提示
- 📝 **日志记录**：详细的转换日志输出
- 💾 **配置保存**：自动保存您的偏好设置

### 命令行模式

### 基本用法

```bash
# 转换为默认格式（MP4）
videoconv input.mp4

# 指定输出格式
videoconv input.m4s -f mkv

# 指定输出目录
videoconv input.avi -o ./output
```

### 编码设置

```bash
# 使用 H.265 编码器
videoconv input.avi -f mp4 -c:v libx265

# 设置视频比特率 (kbps)
videoconv input.mp4 -b:v 5000

# 设置音频比特率 (kbps)
videoconv input.mkv -b:a 256

# 设置 CRF 质量值（18-28 推荐）
videoconv input.mp4 -crf 18

# 设置编码速度预设
videoconv input.avi --preset fast
```

### 高级设置

```bash
# 设置帧率
videoconv input.mkv -r 60

# 分辨率缩放到 50%
videoconv input.mp4 --scale 0.5

# 移除音频轨道
videoconv input.avi --no-audio

# 组合多个选项
videoconv input.m4s -f mp4 -c:v libx265 -b:v 3000 -crf 20 -r 30 --scale 0.75
```

## 命令行参数

```bash
usage: videoconv [-h] [-f FORMAT] [-c:v VIDEO_CODEC] [-c:a AUDIO_CODEC]
                 [-b:v VIDEO_BITRATE] [-b:a AUDIO_BITRATE] [-r FRAME_RATE]
                 [--scale SCALE] [-crf CRF] [--preset PRESET]
                 [--no-audio] [-v]
                 input [output]

Convert video files between different formats.

positional arguments:
  input                 Input video file
  output                Output directory (optional, defaults to same directory as input)

optional arguments:
  -h, --help            show this help message and exit
  -f, --format FORMAT   Output format (default: mp4)
  -c:v, --video-codec VIDEO_CODEC
                        Video codec (default: libx264)
  -c:a, --audio-codec AUDIO_CODEC
                        Audio codec (default: aac)
  -b:v, --video-bitrate VIDEO_BITRATE
                        Video bitrate in kbps (default: 2500)
  -b:a, --audio-bitrate AUDIO_BITRATE
                        Audio bitrate in kbps (default: 128)
  -r, --frame-rate FRAME_RATE
                        Frame rate (default: 30)
  --scale SCALE         Scale factor for resolution (default: 1.0)
  -crf, --crf CRF       Constant Rate Factor (0-51, lower=better, default: 23)
  --preset PRESET       Encoding preset (default: medium)
  --no-audio            Remove audio track
  -v, --verbose         Enable verbose output
```

## 配置说明

配置文件保存在 `~/.pytola/video_converter.json`，包含以下默认设置：

```json
{
    "OUTPUT_FORMAT": "mp4",
    "VIDEO_CODEC": "libx264",
    "AUDIO_CODEC": "aac",
    "VIDEO_BITRATE": 2500,
    "AUDIO_BITRATE": 128,
    "FRAME_RATE": 30,
    "SCALE_FACTOR": 1.0,
    "CRF": 23,
    "PRESET": "medium",
    "REMOVE_AUDIO": false
}
```

## 质量参数建议

### CRF 值参考

- **18**: 视觉无损（高质量，大文件）
- **20-23**: 高质量（推荐范围）
- **24-28**: 中等质量（平衡文件大小）
- **29+**: 较低质量（小文件）

### 编码预设参考

- **ultrafast/superfast**: 最快编码，最低压缩率
- **veryfast/faster/fast**: 快速编码，适合实时处理
- **medium**: 平衡速度和质量（推荐）
- **slow/slower/veryslow**: 慢速编码，最高压缩率

### 比特率建议

- **1080p**: 2500-5000 kbps
- **720p**: 1500-3000 kbps
- **4K**: 8000-20000 kbps

## 示例场景

### 1. 将 M4S 流媒体文件转换为 MP4

```bash
videoconv stream.m4s -f mp4 -c:v libx264 -crf 23
```

### 2. 压缩大型视频文件

```bash
videoconv large_video.avi -f mp4 -c:v libx265 -crf 28 --preset slow
```

### 3. 为网络准备视频（降低分辨率）

videoconv source.mkv -f mp4 --scale 0.5 -b:v 1500

````bash

### 4. 创建 GIF 动图
```bash
videoconv clip.mp4 -f gif -r 15 --scale 0.5
````

### 5. 提取视频为无音频版本

```bash
videoconv music_video.mp4 --no-audio
```

## 技术架构

- **核心类**:
  - `VideoConverterConfig`: 配置管理类，继承自 `ConfigMixin`
  - `VideoConverterRunner`: 视频转换执行类
- **依赖**:
  - `pytola-core`: 提供配置管理基础功能
  - `ffmpeg`: 视频处理引擎

- **设计模式**:
  - 配置与执行分离
  - 数据类用于参数传递
  - 缓存属性优化性能

## 故障排除

### 常见问题

**Q: 提示 "ffmpeg not found"**
A: 请确保 FFmpeg 已安装并添加到系统 PATH。运行 `ffmpeg -version` 验证安装。

**Q: 转换失败，错误码 1**
A: 检查输入文件格式是否受支持，查看详细错误日志。

**Q: 输出文件过大**
A: 尝试增加 CRF 值（如 28），或使用 H.265 编码器提高效率。

**Q: 转换速度太慢**
A: 使用更快的编码预设（如 `--preset veryfast`）或降低分辨率。

## 开发信息

- **作者**: Pytola Team
- **版本**: 0.1.0
- **许可证**: MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v0.1.0 (2026-03-30)

- 初始版本发布
- 支持主流视频格式转换
- 完整的配置管理系统
- 命令行界面
