# mat-player

**Repository Path**: mat-cloud/mat-player

## Basic Information

- **Project Name**: mat-player
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-26
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MAT Player

一个现代化的跨平台多媒体播放器，支持视频、音频及流媒体播放。基于 Vue 3 + TypeScript 构建，可运行在 Web、桌面端（Electron）和移动端（Capacitor）。

## 功能特性

- **多格式播放** - 支持 MP4、MKV、AVI、MOV、WebM、MP3、FLAC、WAV、AAC、OGG 等主流格式
- **流媒体支持** - HLS (.m3u8) 和 DASH (.mpd) 自适应码率流媒体，自动协议检测
- **字幕系统** - 支持 SRT、VTT、ASS/SSA 格式，实时同步渲染
- **播放列表** - 顺序播放、列表循环、单曲循环、随机播放四种模式
- **迷你播放器** - 浮窗模式，支持画中画
- **跨平台** - 一套代码运行在 Web、Windows、macOS、Linux、Android、iOS
- **键盘快捷键** - 完整的键盘操作支持
- **手势控制** - 移动端手势操作
- **深色主题** - 默认深色界面，响应式布局适配多种屏幕

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Vue 3、Vue Router、Pinia |
| 语言 | TypeScript |
| 构建 | Vite |
| 样式 | UnoCSS |
| 流媒体 | HLS.js、DASH.js |
| 桌面端 | Electron |
| 移动端 | Capacitor |
| 测试 | Vitest、Vue Test Utils |
| 规范 | ESLint |

## 项目结构

```
mat-player-sdd/
├── src/
│   ├── core/                # 核心引擎层（纯 TypeScript，无框架依赖）
│   │   ├── player/          #   播放器引擎（HTML5 Media API）
│   │   ├── streaming/       #   流媒体引擎（HLS/DASH 适配）
│   │   ├── subtitle/        #   字幕引擎（SRT/VTT/ASS 解析与渲染）
│   │   └── playlist/        #   播放列表管理
│   ├── platform/            # 平台适配层（Web/Electron/Capacitor）
│   ├── components/          # UI 组件
│   │   ├── layout/          #   布局组件（导航、标题栏）
│   │   ├── player/          #   播放器组件（视频、音频、控制条、进度条）
│   │   └── playlist/        #   播放列表组件
│   ├── composables/         # 组合式函数（连接 Core 层与 Vue 响应式）
│   ├── stores/              # Pinia 状态管理
│   ├── views/               # 页面视图
│   ├── router/              # 路由配置
│   ├── styles/              # 全局样式
│   └── utils/               # 工具函数
├── electron/                # Electron 主进程代码
├── vite.config.ts
├── capacitor.config.ts
└── electron-builder.json
```

项目采用三层架构：

- **Core 层** - 纯 TypeScript 实现的播放器引擎、流媒体、字幕和播放列表逻辑，无框架依赖，可独立测试
- **Platform 层** - 平台检测与适配，屏蔽 Web/Electron/Capacitor 差异
- **App 层** - Vue 组件、状态管理和路由，负责 UI 呈现与用户交互

## 快速开始

### 环境要求

- Node.js >= 18
- pnpm（推荐）或 npm

### 安装

```bash
# 克隆项目
git clone <repository-url>
cd mat-player-sdd

# 安装依赖
pnpm install
```

### 开发

```bash
# Web 开发模式
pnpm dev

# Electron 桌面开发模式
pnpm dev:electron
```

开发服务器默认运行在 `http://localhost:5173`。

### 测试与检查

```bash
# 运行测试
pnpm test

# 运行单元测试
pnpm test:unit

# 监听模式
pnpm test:watch

# 代码检查
pnpm lint

# 类型检查
pnpm typecheck
```

## 构建部署

### Web

```bash
pnpm build
pnpm preview    # 本地预览构建结果
```

构建产物输出到 `dist/` 目录。

### Electron 桌面端

```bash
pnpm build:electron
```

打包产物输出到 `release/` 目录，支持：
- Windows: NSIS 安装包
- macOS: DMG
- Linux: AppImage

### Capacitor 移动端

```bash
# 同步 Web 构建到原生项目
pnpm cap:sync

# 运行 Android
pnpm cap:android

# 运行 iOS
pnpm cap:ios

# 在 IDE 中打开原生项目
pnpm cap:open:android
pnpm cap:open:ios
```

## 键盘快捷键

| 快捷键 | 功能 |
|--------|------|
| `Space` | 播放 / 暂停 |
| `←` / `→` | 快退 / 快进 5 秒 |
| `↑` / `↓` | 音量增加 / 减少 |
| `M` | 静音 / 取消静音 |
| `F` | 全屏切换 |

## 支持格式

**视频**: MP4, MKV, AVI, MOV, WMV, FLV, WebM, M4V, TS, 3GP

**音频**: MP3, FLAC, WAV, AAC, OGG, WMA, M4A, Opus

**流媒体**: HLS (.m3u8), DASH (.mpd)

**字幕**: SRT, VTT, ASS/SSA