# holyplayer-video

**Repository Path**: holytreasure/holyplayer-video

## Basic Information

- **Project Name**: holyplayer-video
- **Description**: 一款基于 PHP 开发的苹果风格（Apple Design）全格式视频播放器。拥有极简美学、毛玻璃特效和流畅动画，完美支持 HLS (m3u8)、FLV 直播流以及 MP4 等主流格式，兼容 H.264/HEVC/AV1/VP9 等多种编码。
- **Primary Language**: PHP
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-28
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🍎 HolyPlayer Video

> **一款基于 PHP 开发的苹果风格（Apple Design）全格式视频播放器。**
>
> 🌐 **演示站点**: [http://player.holytreasure.cn/](http://player.holytreasure.cn/)
> 🚀 **实际调用地址**: `http://player.holytreasure.cn/video/`
> 📦 **Gitee 仓库**: [https://gitee.com/holytreasure/holyplayer-video](https://gitee.com/holytreasure/holyplayer-video)

---

## ✨ 项目简介

**HolyPlayer Video** 是一款专为现代 Web 设计的高性能视频播放器解决方案。它完美复刻了 macOS/iOS 的 **Liquid Glass (毛玻璃)** 设计语言，拥有极致的视觉体验和流畅的交互动画。

核心优势在于其强大的兼容性：不仅原生支持 MP4，更通过集成 `hls.js` 和 `flv.js` 完美支持 **HLS (m3u8)** 和 **FLV** 直播流，同时兼容 **H.264, HEVC (H.265), AV1, VP9** 等多种先进视频编码。无论是点播电影还是低延迟直播，都能轻松驾驭。

### 🚀 核心特性

- 🎨 **纯正苹果美学**：采用 SF Pro 字体体系，毛玻璃特效，细腻的微交互动画，支持深色/浅色模式自适应。
- 📺 **全格式引擎**：
  - ✅ **直播流**：完美支持 `.m3u8` (HLS) 和 `.flv` (HTTP-FLV)。
  - ✅ **点播**：原生支持 `.mp4`, `.webm`, `.ogg`。
- 🔧 **硬核编码支持**：智能识别并调用浏览器原生解码或 JS 软解，覆盖 H.264, HEVC, AV1, VP9, H.265。
- 🎛️ **全能控制台**：
  - 📍 **顶部**：可选内嵌标题、直播状态指示灯。
  - 📍 **底部**：高精度进度条（带缓冲预览）、平滑音量调节、0.25x-3.0x 倍速、多线路秒切、画面缩放（适应/填充/放大）。
- 🚀 **灵活集成**：
  - 🔗 **URL 参数直连**：链接带参即可生成播放页，零代码部署。
  - 🖼️ **iframe 嵌入**：一行代码嵌入任何网站，支持跨域 postMessage 通信。
  - 💻 **JS SDK**：提供完整的 Class 类接口，方便深度定制。
- ⌨️ **快捷键大全**：空格、方向键、F/T/M 等全套快捷操作。
- 📱 **全端响应式**：完美适配 PC、平板、手机（iOS/Android），支持微信内联播放。

---

## 🚀 快速开始

### 1. 环境要求
- PHP 7.4+
- Web 服务器 (Nginx / Apache)
- 开启 `allow_url_fopen` (推荐，用于部分后端验证)

### 2. 安装部署

#### 方式 A: Git 克隆
```bash
git clone https://gitee.com/holytreasure/holyplayer-video.git
cd holyplayer-video
# 确保 web 服务器根目录指向该项目文件夹
```

#### 方式 B: 下载源码
访问 [Gitee 仓库](https://gitee.com/holytreasure/holyplayer-video) 下载最新 Release 包并解压至服务器目录。

### 3. 访问测试
部署完成后，访问演示站查看效果：
- **首页演示**: [http://player.holytreasure.cn/](http://player.holytreasure.cn/)
- **直接调用**: `http://player.holytreasure.cn/video/`

---

## 🔗 使用指南

### 方式一：URL 参数配置（推荐）

无需修改代码，直接在 **实际调用地址** 后添加参数即可创建专属播放页。

**基础调用格式：**
```text
http://player.holytreasure.cn/video/?src=视频地址&title=标题
```

**📺 播放 HLS (m3u8) 直播：**
```text
http://player.holytreasure.cn/video/?src=https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8&title=CCTV直播&autoplay=true
```

**📹 播放 FLV 直播：**
```text
http://player.holytreasure.cn/video/?src=http://example.com/live.flv&type=video/x-flv&title=体育直播
```

**🎬 播放本地/远程 MP4：**
```text
http://player.holytreasure.cn/video/?src=https://example.com/movie.mp4&title=我的电影&poster=cover.jpg
```

**🔄 多线路切换（JSON 格式）：**
```text
http://player.holytreasure.cn/video/?sources=[{"src":"https://url1.m3u8","label":"高清线路"},{"src":"https://url2.flv","label":"备用线路"}]&title=多源测试
```

**⚙️ 完整参数列表：**

| 参数 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `src` | string | - | 单个视频地址 |
| `sources` | json | - | 多线路数组 (优先级高于 src) |
| `title` | string | "视频播放" | 视频标题 |
| `poster` | string | - | 封面图片 URL |
| `autoplay` | boolean | false | 是否自动播放 |
| `volume` | float | 0.8 | 默认音量 (0.0 - 1.0) |
| `speed` | float | 1.0 | 默认播放倍速 |
| `showtitle` | boolean | true | 是否显示顶部标题栏 |
| `type` | string | auto | 强制指定类型 (如 video/x-flv) |

### 方式二：iframe 嵌入

在任何 HTML 页面中一键嵌入：

```html
<iframe 
    src="http://player.holytreasure.cn/video/?src=https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8&title=嵌入演示&autoplay=true" 
    width="100%" 
    height="600" 
    frameborder="0" 
    allow="autoplay; fullscreen" 
    allowfullscreen>
</iframe>
```

**💡 高级用法：父页面控制播放器**
```javascript
const iframe = document.querySelector('iframe');

// 播放
iframe.contentWindow.postMessage({ action: 'play' }, '*');

// 暂停
iframe.contentWindow.postMessage({ action: 'pause' }, '*');

// 切换线路 (索引从 0 开始)
iframe.contentWindow.postMessage({ action: 'switchSource', data: 1 }, '*');

// 设置音量
iframe.contentWindow.postMessage({ action: 'setVolume', data: 0.5 }, '*');
```

### 方式三：JavaScript API (开发者模式)

如果你将 `js/player.js` 引入自己的项目进行深度开发：

```html
<div id="my-player"></div>
<script src="js/player.js"></script>
<script>
    const player = new ApplePlayer('my-player', {
        sources: [
            { src: 'https://example.com/live.m3u8', label: '主线路', type: 'application/x-mpegURL' },
            { src: 'https://example.com/live.flv', label: '备用线路', type: 'video/x-flv' }
        ],
        title: '实时监控中心',
        autoPlay: true,
        showTitle: true
    });

    // 控制方法
    player.play();              // 播放
    player.pause();             // 暂停
    player.setVolume(0.5);      // 设置音量
    player.setSpeed(2.0);       // 2倍速
    player.switchSource(1);     // 切换到第2个源
    player.toggleFullscreen();  // 全屏
    
    // 事件监听
    document.getElementById('my-player').addEventListener('player:play', () => {
        console.log('▶️ 开始播放了');
    });
    
    document.getElementById('my-player').addEventListener('player:ended', () => {
        console.log('⏹️ 播放结束');
    });
</script>
```

---

## ⌨️ 快捷键说明

| 按键 | 功能 | 备注 |
| :--- | :--- | :--- |
| `Space` / `K` | 播放 / 暂停 | 最常用 |
| `F` | 切换全屏 | - |
| `T` | 剧场模式 | 标准/剧场切换 |
| `M` | 静音开关 | - |
| `↑` / `↓` | 音量 +10% / -10% | - |
| `←` / `→` | 快退 5s / 快进 5s | - |
| `0` - `9` | 进度跳转 | 对应 0% - 90% |

---

## 📂 目录结构

```text
holyplayer-video/
├── index.php           # 主入口文件 (参数解析与渲染)
├── player.php          # 独立播放器页面 (适合 iframe)
├── api.php             # 后端 API 接口
├── config.php          # 全局配置文件
├── css/
│   └── style.css       # 苹果风格核心样式
├── js/
│   └── player.js       # 核心播放器逻辑 (Class ApplePlayer)
├── lib/                # 第三方依赖 (默认 CDN 加载，可本地化)
│   ├── hls.min.js      # HLS 流处理库
│   └── flv.min.js      # FLV 流处理库
├── README.md           # 项目说明文档
└── .gitignore          # Git 忽略配置
```

---

## ⚙️ 配置说明 (config.php)

编辑 `config.php` 可自定义默认行为和 CDN 源：

```php
return [
    'player' => [
        'default_volume' => 0.8,    // 默认音量
        'auto_play' => false,       // 是否默认自动播放
        'show_title' => true,       // 是否显示标题栏
        'controls_timeout' => 3000, // 控制栏自动隐藏时间 (ms)
    ],
    'cdn' => [
        // 建议替换为国内高速 CDN (如阿里云/腾讯云/七牛云)
        'hls_js' => 'https://cdn.jsdelivr.net/npm/hls.js@latest/dist/hls.min.js',
        'flv_js' => 'https://cdn.jsdelivr.net/npm/flv.js@latest/dist/flv.min.js',
    ],
    'security' => [
        'allow_external_sources' => true, // 允许播放外部域名视频
        'max_sources' => 10,              // 最大支持线路数量
    ]
];
```

---

## 🛠️ 常见问题 (FAQ)

**Q: 为什么 H.265/HEVC 视频在 Chrome 上无法播放？**
A: H.265 编码需要浏览器硬件解码支持（Safari 和新版 Edge 支持较好）。Chrome 默认不支持 H.265。解决方案：
1. 服务端转码为 H.264 (兼容性最好)。
2. 引入 `h265web.js` (WASM 软解方案，本项目预留了接口，可按需集成)。

**Q: FLV 直播延迟较高怎么办？**
A: 本项目已在 `js/player.js` 中针对直播做了优化配置 (`enableStashBuffer: false`)。若仍有延迟，请检查网络状况或推流服务器配置。

**Q: 如何在 iOS 微信中避免视频自动全屏？**
A: 代码已内置 `playsinline` 和 `webkit-playsinline` 属性，正常情况下会内联播放。如果仍全屏，请确保微信版本较新，且未触发系统的强制全屏策略。

**Q: 支持防盗链吗？**
A: 基础版支持简单的 Referer 判断（需在 Nginx/Apache 层配置）。高级防盗链（Token 鉴权）需要在 `api.php` 或 `index.php` 中自行扩展逻辑。

---

## 🤝 贡献与反馈

欢迎提交 Issue 或 Pull Request 帮助我们要善 HolyPlayer Video！

- 🐛 **问题反馈**: [Gitee Issues](https://gitee.com/holytreasure/holyplayer-video/issues)
- 📥 **源码仓库**: [https://gitee.com/holytreasure/holyplayer-video](https://gitee.com/holytreasure/holyplayer-video)
- 🌐 **演示站点**: [http://player.holytreasure.cn/](http://player.holytreasure.cn/)

---

## 📄 许可证

本项目采用 **Apache License 2.0** 开源协议。

你可以自由地使用、修改和分发本软件，但需要保留版权声明和许可证副本。有关详细信息，请参阅项目根目录下的 [LICENSE](LICENSE) 文件。

```text
Copyright 2024 HolyTreasure Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```

---