# HBPlayer

**Repository Path**: thb1314/hbplayer

## Basic Information

- **Project Name**: HBPlayer
- **Description**: HBPlayer 是一个面向 Windows 的桌面播放器，基于 `FFmpeg + Qt5 + SDL2`，提供简单干净本地播放体验，支持视频截取转码、视频缩放转码、视频截图等功能。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HBPlayer

[English README](./README.en.md)

HBPlayer 是一个面向 Windows 的桌面播放器，基于 `FFmpeg + Qt5 + SDL2`，提供简单干净本地播放体验，支持视频精确截取转码、视频精确缩放转码、视频截图等功能。

支持能力覆盖：

- 本地音视频文件播放
- RTSP/HTTP 网络流播放
- 字幕渲染（`libass`）
- 截图与本地文件定位
- 格式转换与精确时间段截取
- 中英文界面
- Windows 右键“使用 HBPlayer 打开”

![](images/00.png)
![](images/01.png)
![](images/02.png)
![](images/03.png)


## 主要特性

- 硬解优先（`D3D11VA / DXVA2`），失败自动回退软解。
- 视频与纯音频统一播放能力，支持音频封面与播放态 UI。
- `libass` 字幕渲染。
- 完整播放控制：播放/暂停/停止、进度条拖拽与点击 Seek、悬浮时间点提示、倍速、音量。
- 全屏与窗口控制：双击全屏、Esc 退出全屏、无边框窗口、窗口缩放与拖动。
- 文件拖拽打开、右键“使用 HBPlayer 打开”。
- 内置格式转换 + 截取工具（音频/视频输出类型、编码与封装）。
- 中英文界面切换。
- 路径兼容优化：截图与转码结果的“点击定位文件”支持中文路径与特殊字符路径。

## UI 与交互说明

- 顶部栏：应用菜单、窗口控制、置顶控制。
- 底部栏：播放/停止、进度条、时间显示、转码按钮、截图按钮、音量控制。
- 音频模式：音频文件播放时切换为音频界面（封面/唱片风格）。
- 拖拽打开：支持将文件直接拖到播放区域打开（音频与视频）。

## 播放与解码策略

- 默认硬解优先，硬解失败会自动回退软解，避免黑屏不可恢复。
- Seek 走统一 flush 管线，并对弱索引/原始流补充了回退策略。
- 针对流媒体场景有缓冲与恢复处理，兼顾本地文件与网络流。

## 支持格式（播放）

| 类型 | 支持格式 |
| --- | --- |
| 音频 | m4a、aac、mp3、flac、wav、ogg、opus、ac3、eac3、mp2、mka、wma、aiff、aif、au、caf、w64、ape、wv、tta、tak、amr、dts、m4b、isma |
| 视频 | mp4、mkv、mov、avi、flv、webm、ts、m2ts、mts、mpg、mpeg、m4v、wmv、asf、3gp、3g2、f4v、ism、ismv、mj2、psp、mxf、rm、rmvb、wtv |

补充：

- 字幕：ASS/SSA、SRT（按流信息与渲染链支持）。
- 以上为播放器当前白名单与实测覆盖的主要格式集合。

## 支持格式（转换输出）

| 类型 | 支持编码/封装 |
| --- | --- |
| 音频 | aac、fdk_aac、mp3、opus、flac、vorbis、pcm_s16le、alac、ac3、eac3、mp2、wmav1、wmav2、copy |
| 视频 | h264、h265、av1、vp9、vp8、mpeg4、xvid、prores、jpeg2000、mpeg2、wmv1、wmv2、copy |

转换工具能力说明：

- 支持精确时间段输入（时/分/秒/毫秒）。
- 支持音频输出与视频输出二选一。
- 视频输出支持分辨率设定与等比例缩放选项。
- 输出文件名自动避免重名冲突。
- 音频源限制：音频源不能输出视频（工具内有约束提示）。

## 下载与安装

发布产物位于 `release/`：

- `HBPlayer-v0.1-win64-setup.exe`（安装版）
- `HBPlayer-v0.1-win64.zip`（绿色版）

建议使用方式：

1. 安装版：运行 `HBPlayer-v0.1-win64-setup.exe`。  
2. 绿色版：解压 `HBPlayer-v0.1-win64.zip` 后运行 `HBPlayer-v0.1-win64/hbplayer.exe`。

## 快速上手

1. 启动 HBPlayer。
2. 通过“打开文件”或拖拽文件到窗口开始播放。
3. 需要截图时点击截图按钮，顶部提示条可直接点击定位到文件。
4. 需要转码时点击转换按钮，设置时间段与输出参数后开始执行。

## 命令行

```powershell
.\hbplayer.exe
.\hbplayer.exe D:\media\demo.mp4
.\hbplayer.exe rtsp://127.0.0.1:8554/live/test
```

常用参数：

- `--no-hwaccel`
- `--hwaccel=auto|none|d3d11|dxva2`
- `--no-audio`
- `--no-video`
- `--verbose`
- `--log=<path>`

## 已知限制

- 当前发布目标是 Windows（Qt5 + MinGW64 运行时）。
- 极少数非常规损坏媒体文件可能仍存在解码失败或时序异常。
- 转码能力以当前打包 FFmpeg 编译选项为准。

## 常见问题（FAQ）

- Q: 截图/转码完成后点击路径没有定位到正确文件？  
  A: 新版本已修复中文路径与特殊字符路径定位问题。若仍异常，请确认使用的是最新 `v0.1` 包。

- Q: 播放黑屏但有声音？  
  A: 可先尝试 `--no-hwaccel`，或在设置中切换硬解策略；播放器会在多数场景自动回退软解。

- Q: 转换提示找不到 ffmpeg？  
  A: release 包内已携带 `ffmpeg.exe/ffprobe.exe`，请确保使用完整 release 目录运行。

## 发布校验

安装包与压缩包哈希见 `RELEASE_NOTES.md`（英文）。