# electron-video-player

**Repository Path**: L_Kevin/electron-video-player

## Basic Information

- **Project Name**: electron-video-player
- **Description**: electron实时视频播放器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎬 Electron 视频播放器

> 基于 Electron + Vue3 + Element Plus 构建的现代化桌面视频播放器应用

![Vue3](https://img.shields.io/badge/Vue-3.4-4FC08D?logo=vue.js)
![Electron](https://img.shields.io/badge/Electron-28.0-47848F?logo=electron)
![Element Plus](https://img.shields.io/badge/Element_Plus-2.5-409EFF?logo=element)
![License](https://img.shields.io/badge/License-MIT-blue.svg)

## ✨ 功能特性

### 📹 摄像头监控
- ✅ 实时访问电脑摄像头
- ✅ 支持多摄像头设备切换
- ✅ 高清视频预览（最高 1280x720）
- ✅ 一键开启/关闭控制
- ✅ 智能权限管理和错误提示

### 🎥 监控视频流
- ✅ 支持多种视频流协议
  - RTSP（实时监控常用）
  - RTMP（直播推流）
  - HLS/m3u8（HTTP 直播）
- ✅ 智能协议选择器
- ✅ 实时连接状态显示
- ✅ 自动重连机制
- ✅ 详细的错误诊断

### 🎬 本地视频播放
- ✅ 支持主流视频格式（MP4、WebM、Ogg 等）
- ✅ 完整的播放控制
  - 播放/暂停
  - 快进/快退（10秒步进）
  - 精确进度条拖拽
- ✅ 音量控制系统
  - 音量调节滑块
  - 一键静音
- ✅ 播放速度调整（0.5x - 2.0x）
- ✅ 全屏播放支持
- ✅ 视频信息展示
  - 文件名、时长、大小、格式
- ✅ 时间格式化显示

## 🖼️ 界面预览

### 主界面
采用侧边栏导航设计，清晰的功能分区，现代化的 UI 风格。

### 摄像头监控
简洁的摄像头控制面板，支持设备选择和实时预览。

### 监控视频流
专业的视频流播放器，支持多种协议和实时状态显示。

### 本地视频播放
功能完善的视频播放器，提供丰富的控制选项和信息展示。

## 🛠️ 技术栈

### 核心框架
- **Electron 28.x** - 跨平台桌面应用框架
- **Vue 3.4** - 渐进式 JavaScript 框架（Composition API）
- **Vite 5.x** - 下一代前端构建工具

### UI 组件
- **Element Plus 2.5** - Vue 3 企业级 UI 组件库
- **Element Plus Icons** - 图标系统

### 开发工具
- **ESLint** - 代码质量检查
- **Concurrently** - 并行任务执行
- **Electron Builder** - 应用打包工具

## 📦 快速开始

### 环境要求
- Node.js >= 16.0.0
- npm >= 7.0.0
- Windows / macOS / Linux

### 安装依赖

```bash
# 克隆或进入项目目录
cd electron-video-player

# 设置国内镜像源（加速下载，推荐）
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
set ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

# 安装依赖
npm install
```

**💡 提示：** 如果下载速度慢，请查看 [MIRROR_CONFIG.md](MIRROR_CONFIG.md) 配置国内镜像。

### 开发模式

#### 方式一：使用启动脚本（推荐 Windows 用户）

```bash
# 双击运行
start-dev.bat
```

#### 方式二：手动启动

```bash
# 终端 1：启动 Vite 开发服务器
npm run dev

# 终端 2：启动 Electron（PowerShell）
$env:NODE_ENV='development'
npx electron .

# 终端 2：启动 Electron（CMD）
set NODE_ENV=development
npx electron .
```

#### 方式三：使用 concurrently

```bash
npm run electron:dev
```

> 💡 **提示**：开发模式下，Electron 窗口会自动打开开发者工具，方便调试。

### 生产构建

#### Windows 安装包（推荐）

**方式一：使用打包脚本（最简单）**
```bash
# 双击运行
build-win.bat
```

**方式二：使用 npm 命令**
```bash
# NSIS 安装包（标准安装程序）
npm run electron:build:win

# 便携版（无需安装）
npm run electron:build:win:portable

# 使用默认配置
npm run electron:build
```

**输出位置：** `dist-electron/VideoPlayer-1.0.0-x64.exe`

**详细说明：** 查看 [BUILD_GUIDE.md](BUILD_GUIDE.md)

#### 其他平台

```bash
# macOS
npm run electron:build:mac

# Linux
npm run electron:build:linux
```

## 📖 使用指南

### 1. 摄像头监控

**步骤：**
1. 点击左侧菜单「摄像头监控」
2. 点击「开启摄像头」按钮
3. 在浏览器弹出的权限请求中点击「允许」
4. 如有多个摄像头，可从下拉列表选择设备

**注意事项：**
- 首次使用需要授予摄像头权限
- 确保没有其他应用独占摄像头
- 建议在光线充足的环境下使用

### 2. 监控视频流

**✅ 已支持 HLS 格式！** 应用现已集成 hls.js，可以直接播放 HLS (m3u8) 视频流。

**步骤：**
1. 点击左侧菜单「监控视频流」
2. 从下拉框选择协议类型（推荐 HTTP/HTTPS）
3. 输入视频流地址
4. 点击「连接」或「开始监控」

**✅ 推荐的测试地址：**
```bash
# HLS 测试流（立即可用）
https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8
```

**⚠️ RTSP/RTMP 使用说明：**

浏览器原生不支持 RTSP/RTMP，但您可以：

1. **转换为 HLS 格式**（推荐）
   ```bash
   ffmpeg -i rtsp://admin:password@192.168.1.100:554/stream \
          -c:v libx264 -c:a aac -f hls \
          -hls_time 2 -hls_list_size 5 \
          output.m3u8
   ```

2. **使用转码服务**
   - SRS 流媒体服务器
   - MediaMTX
   - ZLMediaKit

3. **查看详细说明**
   - 阅读 [STREAMING_GUIDE.md](STREAMING_GUIDE.md) 获取完整指南

**示例地址格式：**
```bash
# HLS（✅ 完全支持）
https://example.com/stream.m3u8

# RTSP（需要转码为 HLS）
rtsp://admin:password@192.168.1.100:554/h264/ch1/main/av_stream

# RTMP（需要转码为 HLS）
rtmp://live.example.com/stream/key
```

**注意事项：**
- 确保网络连接正常
- 某些视频流可能需要认证信息
- RTSP 流可能需要特定的解码器支持

### 3. 本地视频播放

**步骤：**
1. 点击左侧菜单「本地视频」
2. 点击「选择视频文件」按钮
3. 从文件对话框选择视频文件
4. 使用控制栏进行播放操作

**支持的操作：**
- ⏯️ 播放/暂停：点击播放按钮或空格键
- ⏪ 快退：点击快退按钮，后退 10 秒
- ⏩ 快进：点击快进按钮，前进 10 秒
- 🔊 音量：拖动滑块或点击静音按钮
- ⚡ 倍速：从下拉框选择播放速度
- 🖥️ 全屏：点击全屏按钮或按 F11

**支持的视频格式：**
- MP4 (H.264/AAC) - 推荐
- WebM (VP8/VP9)
- Ogg (Theora)
- MOV (部分支持)

## 🏗️ 项目结构

```
electron-video-player/
├── electron/                    # Electron 主进程
│   ├── main.js                 # 主进程入口文件
│   └── preload.js              # 预加载脚本（IPC 通信）
│
├── src/                        # Vue 3 前端源码
│   ├── components/             # Vue 组件
│   │   ├── CameraView.vue      # 摄像头监控组件
│   │   ├── MonitorView.vue     # 监控视频流组件
│   │   └── PlayerView.vue      # 本地视频播放器组件
│   │
│   ├── App.vue                 # 根组件（应用布局）
│   └── main.js                 # Vue 应用入口
│
├── index.html                  # HTML 入口模板
├── vite.config.js              # Vite 构建配置
├── package.json                # 项目配置和依赖
├── .gitignore                  # Git 忽略规则
├── start-dev.bat               # Windows 快速启动脚本
├── README.md                   # 项目说明文档
├── QUICK_START.md              # 快速开始指南
└── PROJECT_SUMMARY.md          # 项目开发总结
```

## 🔧 配置说明

### Vite 配置

编辑 `vite.config.js` 修改开发服务器端口：

```javascript
export default defineConfig({
  server: {
    port: 5173  // 修改端口
  }
})
```

### Electron 配置

编辑 `package.json` 中的 `build` 字段自定义打包选项：

```json
{
  "build": {
    "appId": "com.yourcompany.videoplayer",
    "productName": "MyVideoPlayer",
    "win": {
      "target": ["nsis", "portable"]
    }
  }
}
```

### 添加新的 IPC 通信

1. 在 `electron/main.js` 中添加处理函数：

```javascript
ipcMain.handle('custom-api', async (event, data) => {
  // 处理逻辑
  return result
})
```

2. 在 `electron/preload.js` 中暴露接口：

```javascript
contextBridge.exposeInMainWorld('electronAPI', {
  customApi: (data) => ipcRenderer.invoke('custom-api', data)
})
```

3. 在 Vue 组件中使用：

```javascript
const result = await window.electronAPI.customApi(data)
```

## 🐛 常见问题

### Q1: 摄像头无法打开？

**可能原因和解决方案：**

1. **权限被拒绝**
   - 检查浏览器地址栏的权限图标
   - 点击并选择「始终允许」
   - 刷新页面重试

2. **摄像头被其他应用占用**
   - 关闭其他使用摄像头的程序
   - 重启应用

3. **驱动问题**
   - 更新摄像头驱动程序
   - 在设备管理器中检查摄像头状态

### Q2: Electron 窗口无法打开？

**解决方案：**

1. 确认 Vite 服务器正在运行
   ```bash
   # 访问 http://localhost:5173 确认服务正常
   ```

2. 检查终端错误信息
   ```bash
   # 查看是否有模块缺失或语法错误
   ```

3. 清除缓存重新启动
   ```bash
   rm -rf node_modules
   npm install
   npm run dev
   ```

### Q3: 监控视频流无法播放？

**排查步骤：**

1. **验证地址正确性**
   - 使用 VLC 播放器测试同一地址
   - 确认协议前缀正确

2. **检查网络连接**
   ```bash
   # 测试网络连通性
   ping 192.168.1.100
   ```

3. **防火墙设置**
   - 确认端口未被阻止
   - 添加例外规则

4. **编解码器支持**
   - 某些 RTSP 流需要 H.264 解码器
   - 尝试转换为 HLS 格式

### Q4: 本地视频无法播放？

**解决方案：**

1. **检查文件格式**
   - 推荐使用 MP4 (H.264 + AAC)
   - 避免使用特殊编码格式

2. **验证文件完整性**
   - 使用其他播放器测试
   - 重新下载或复制文件

3. **浏览器兼容性**
   - Electron 基于 Chromium
   - 支持的格式与 Chrome 相同

### Q5: 应用打包后体积过大？

**优化建议：**

1. 启用代码压缩
   ```javascript
   // vite.config.js
   export default defineConfig({
     build: {
       minify: 'terser'
     }
   })
   ```

2. 移除未使用的依赖
   ```bash
   npm prune --production
   ```

3. 使用 asar 打包
   ```json
   {
     "build": {
       "asar": true
     }
   }
   ```

## 🚀 性能优化

### 开发阶段
- 使用 Vite 的热模块替换（HMR）
- 启用浏览器缓存
- 按需加载组件

### 生产阶段
- 代码分割和懒加载
- 资源压缩和优化
- 启用 asar 打包

### 运行时
- 及时释放媒体流资源
- 避免内存泄漏
- 合理使用定时器

## 🔐 安全考虑

- ✅ 启用 `contextIsolation` 隔离上下文
- ✅ 使用 `preload` 脚本暴露安全 API
- ✅ 禁用 `nodeIntegration` 防止节点注入
- ✅ 验证所有用户输入
- ✅ 处理敏感数据时使用 IPC 通信

## 📝 开发规范

### 代码风格
- 使用 ESLint 进行代码检查
- 遵循 Vue 3 官方风格指南
- 使用 Composition API
- 组件命名使用 PascalCase

### 提交规范
```
feat: 添加新功能
fix: 修复 bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建过程或辅助工具变动
```

### 分支策略
- `main` - 主分支，稳定版本
- `develop` - 开发分支
- `feature/*` - 功能分支
- `bugfix/*` - 修复分支

## 🎯 未来规划

### 短期目标（v1.x）
- [ ] 视频录制功能
- [ ] 截图保存
- [ ] 播放历史记录
- [ ] 收藏夹管理
- [ ] 快捷键支持

### 中期目标（v2.x）
- [ ] 多语言支持（i18n）
- [ ] 主题切换（深色/浅色）
- [ ] 播放列表管理
- [ ] 视频编辑基础功能
- [ ] 云端同步

### 长期目标（v3.x）
- [ ] AI 智能分析
- [ ] 人脸识别
- [ ] 运动检测
- [ ] 视频摘要生成
- [ ] 插件系统

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'feat: add some amazing feature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 👥 作者

- **开发团队** - *Initial work*

## 🙏 致谢

感谢以下开源项目：
- [Electron](https://www.electronjs.org/)
- [Vue.js](https://vuejs.org/)
- [Element Plus](https://element-plus.org/)
- [Vite](https://vitejs.dev/)

## 📞 联系方式

- 问题反馈：[GitHub Issues](https://github.com/yourusername/electron-video-player/issues)
- 功能建议：[GitHub Discussions](https://github.com/yourusername/electron-video-player/discussions)

---

<div align="center">

**如果这个项目对您有帮助，请给个 ⭐ Star 支持一下！**

Made with ❤️ by Electron Video Player Team

</div>