# openharmony-video-player

**Repository Path**: openaicoding/openharmony-video-player

## Basic Information

- **Project Name**: openharmony-video-player
- **Description**: 基于 ArkTS + ArkUI 开发的 HarmonyOS 本地视频播放器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenHarmony 本地视频播放器

一个基于 ArkTS + ArkUI 开发的 HarmonyOS 本地视频播放应用，同时作为 AI 辅助鸿蒙开发的实验性 demo。

## 功能特性

- 📂 **视频列表扫描** - 通过 `photoAccessHelper` 扫描设备本地视频文件
- 🎬 **视频播放** - 基于 `AVPlayer` 支持常见视频格式
- ⏯️ **播放控制** - 播放/暂停、快进/快退 10 秒
- 📊 **进度条** - 可拖动的播放进度条（拖动结束才 seek，避免高频请求）
- ⚡ **倍速播放** - 支持 0.5x / 0.75x / 1.0x / 1.25x / 1.5x / 2.0x 切换
- 📁 **文件选择器** - 通过 `picker.VideoViewPicker` 手动选择视频文件

## 构建环境要求

### 推荐方案：Linux 原生工具链（WSL2 或 Linux）

| 工具 | 版本 | 获取方式 |
|------|------|---------|
| CommandLine Tools | 6.0.2（Linux 版） | [华为开发者官网](https://developer.huawei.com/consumer/cn/deveco-studio/) → 下载 CommandLine Tools |
| JDK | 17+ | `apt install openjdk-17-jdk` |
| Node.js | 18+ | `nvm install 18` |

> ⚠️ **WSL2 注意事项**：不要使用 Windows DevEco Studio 的工具链在 WSL2 下构建，详见 [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md#四构建环境搭建经验核心难点)。

### 环境变量配置

```bash
export DEVECO_SDK_HOME=/path/to/commandline-tools
export PATH=$DEVECO_SDK_HOME/sdk/default/openharmony/toolchains:$PATH
export PATH=$DEVECO_SDK_HOME/tools/ohpm/bin:$PATH
```

## 构建步骤

### 1. 安装依赖

```bash
cd openharmony-video-player
ohpm install
```

### 2. 构建 Debug HAP

```bash
./hvigorw assembleHap --mode module -p module=entry@default -p buildMode=debug
```

产物路径：`entry/build/default/outputs/default/entry-default-signed.hap`

### 3. 安装到设备

**Linux / WSL2 下**（需先复制到 Windows 本地路径）：

```bash
# 复制到 Windows 可访问路径
cp entry/build/default/outputs/default/entry-default-signed.hap /mnt/c/Users/yourname/

# 在 Windows CMD/PowerShell 中安装
hdc install C:\Users\yourname\entry-default-signed.hap
```

**Windows 环境下**（直接使用 DevEco Studio）：
1. 连接设备或启动模拟器
2. DevEco Studio → Run → Run 'entry'

## SDK 版本说明

- `compileSdkVersion`: **22**（使用 CommandLine Tools 6.0.2 内置 SDK 编译）
- `compatibleSdkVersion`: **21**（运行时兼容 API 21 设备和模拟器）

## 已知兼容性限制

### 真机限制

| 设备 | HarmonyOS 版本 | 状态 |
|------|---------------|------|
| MatePad Pro 11 | 4.2.0 | ❌ hdc 3.2.0b 无法连接，协议版本不匹配 |
| 其他 HarmonyOS 5.x 设备 | 5.x | 待测试 |

> 如需连接较新的真机，建议使用 DevEco Studio 5.x 内置的 hdc 版本。

### 模拟器限制

- 模拟器 API 21 下 `photoAccessHelper` 媒体库查询返回空（无预置视频文件）
- 请使用应用内"选择文件"按钮，通过系统文件选择器手动选择视频
- 画中画、后台播放等高级功能在模拟器上不可用

### API 限制

- 使用了 `photoAccessHelper`（API 10+），不支持 API 9 及以下设备
- `AVPlayer` 需要 API 9+

## 项目文档

- [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md) — 完整项目总结，包含构建环境搭建经验和 Bug Fix 清单
- [AI_HARMONY_ANALYSIS.md](./AI_HARMONY_ANALYSIS.md) — AI 辅助鸿蒙开发技术分析报告

## 项目结构

```
openharmony-video-player/
├── AppScope/
│   └── app.json5              # 应用全局配置
├── entry/
│   ├── src/main/ets/
│   │   ├── entryability/      # UIAbility 入口
│   │   ├── model/             # 数据模型
│   │   ├── pages/             # 页面（列表页 + 播放页）
│   │   └── service/           # 视频扫描服务
│   └── build-profile.json5    # 模块构建配置
├── build-profile.json5        # 项目构建配置
└── oh-package.json5           # 依赖配置
```

## 技术栈

- **语言**: ArkTS (TypeScript 超集)
- **UI 框架**: ArkUI 声明式 UI
- **媒体**: AVPlayer + photoAccessHelper
- **构建**: hvigorw + ohpm
- **目标 API**: HarmonyOS API 21/22

## 许可证

MIT License

## V2 版本

V2 版本（[harmony-video-player-v2](../harmony-video-player-v2/)）已完成，新增：手势调亮度/音量、双击播放暂停、SRT 字幕、文件夹分组、触摸锁定、横竖屏切换、属性弹窗等功能。

参考 Android 开源项目 [waleedtalha/VideoPlayer](https://github.com/waleedtalha/VideoPlayer) 重新设计。