# simple-player

**Repository Path**: ningerjohn/simple-player

## Basic Information

- **Project Name**: simple-player
- **Description**: 基于Electron开发的本地播放器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple Player

基于 Electron + Vue3 + Element Plus 的跨平台本地音视频播放器。

## 功能特性

### 核心播放功能
- ✅ 音量控制
- ✅ 倍速播放（0.5x - 2.0x）
- ✅ 进度条拖动
- ✅ 播放/暂停控制
- ✅ 上一首/下一首切换

### 格式支持
- 📹 视频格式：MP4, MKV, AVI, MOV, FLV, WebM
- 🎵 音频格式：MP3, FLAC, WAV, OGG, WMA, M4A
- 🔄 自动转码：不支持格式通过 FFmpeg 实时转码为浏览器支持格式

### 自动加载
- 📋 自动加载相似名称文件到播放列表
- 📝 自动加载同名字幕（SRT, ASS, SSA, VTT 格式）
- 🎶 自动加载同名歌词（LRC 格式）
- 🔍 音频文件自动查找歌词，视频文件自动查找字幕

### 字幕和歌词
- 🎬 实时字幕显示（支持 SRT/ASS/SSA/VTT）
- 🎵 实时歌词滚动显示（支持 LRC）
- 🔤 自动编码检测（支持 UTF-8, GBK, GB2312, GB18030, Big5）

### 快捷键支持
| 快捷键 | 功能 |
|---------|------|
| 空格 | 播放/暂停 |
| ← | 后退 5 秒 |
| → | 前进 5 秒 |
| ↑ | 增加音量 |
| ↓ | 减小音量 |
| F | 全屏切换 |
| M | 静音切换 |
| 1-9 | 跳转到 10%-90% 进度 |

### 播放历史
- 📅 自动记录播放进度
- 🕐 显示播放时间
- 📊 显示播放进度条
- 🔄 一键恢复播放

### 用户界面
- 🎨 深色主题（类似 PotPlayer）
- 📱 响应式布局
- 🖼️ 全屏模式支持
- 🎛️ 悬浮控制栏（全屏时）

## 技术栈

### 前端
- **Vue 3.4** - 渐进式 JavaScript 框架
- **Element Plus 2.5** - Vue 3 组件库
- **Pinia 2.1** - 状态管理
- **Vite 5.0** - 构建工具
- **TypeScript 5.3** - 类型安全

### 后端
- **Electron 28.0** - 跨平台桌面应用框架
- **FFmpeg** - 音视频编解码
- **Express** - HTTP 转码服务器

### 工具库
- **iconv-lite** - 字符编码转换
- **fluent-ffmpeg** - FFmpeg Node.js 封装

## 项目结构

```
simple-player/
├── electron/                 # Electron 主进程
│   ├── main.ts              # 应用入口
│   ├── preload.ts           # 预加载脚本
│   ├── file-service.ts       # 文件操作服务
│   ├── ffmpeg-service.ts     # FFmpeg 转码服务
│   ├── shortcut-service.ts    # 快捷键服务
│   └── history-service.ts    # 播放历史服务
├── src/                     # 渲染进程（Vue3）
│   ├── components/
│   │   ├── Player.vue           # 主播放器组件
│   │   ├── SubtitleDisplay.vue  # 字幕显示组件
│   │   ├── LyricDisplay.vue    # 歌词显示组件
│   │   └── HistoryPanel.vue     # 历史面板组件
│   ├── stores/
│   │   └── player.ts            # Pinia 状态管理
│   ├── utils/
│   │   ├── subtitle-parser.ts   # 字幕解析（SRT/ASS）
│   │   └── lrc-parser.ts        # 歌词解析（LRC）
│   ├── main.ts               # Vue 入口
│   ├── App.vue               # 根组件
│   └── vite-env.d.ts         # 类型声明
├── resources/                # 资源文件
├── package.json
├── vite.config.ts
├── tsconfig.json
└── index.html
```

## 安装

### 环境要求
- Node.js >= 16.0
- npm >= 7.0

### 安装依赖
```bash
npm install
```

## 使用

### 开发模式
```bash
npm run dev
```

### 构建打包
```bash
# Windows
npm run build

# 打包但不安装（更快）
npm run build:dir
```

### 打包输出
- **Windows**: `release/Simple Player Setup x.x.x.exe`
- **macOS**: `release/Simple Player-x.x.x.dmg`
- **Linux**: `release/Simple Player-x.x.x.AppImage`

## 开发说明

### 添加新功能
1. 在 `src/stores/player.ts` 中添加状态
2. 在 `src/components/` 中创建组件
3. 在 `electron/` 中添加主进程逻辑
4. 通过 IPC 通信连接前后端

### IPC 通信示例

**主进程（electron/main.ts）**
```typescript
ipcMain.handle('custom-action', async (_, param) => {
  // 处理逻辑
  return result
})
```

**渲染进程（src/components/）**
```typescript
const result = await window.electronAPI.customAction(param)
```

### 状态管理示例
```typescript
// 定义状态
const usePlayerStore = defineStore('player', () => {
  const customState = ref(initialValue)
  
  function updateState(value: any) {
    customState.value = value
  }
  
  return {
    customState,
    updateState
  }
})

// 使用状态
const { customState, updateState } = usePlayerStore()
```

## 常见问题

### 视频无法播放
- 检查文件格式是否受支持
- 查看 FFmpeg 转码服务是否正常运行
- 尝试重启应用

### 字幕/歌词乱码
- 确保 LRC/SRT 文件使用正确的编码（UTF-8 或 GBK）
- 应用会自动检测编码，如仍有问题请转换文件编码

### 快捷键不生效
- 确保应用处于窗口焦点状态
- 检查快捷键是否被其他应用占用
- 重启应用重新注册快捷键

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT

## 致谢

- [Electron](https://www.electronjs.org/) - 跨平台桌面应用框架
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [Element Plus](https://element-plus.org/) - Vue 3 组件库
- [FFmpeg](https://ffmpeg.org/) - 音视频处理工具