# mat-player

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

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-26
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MAT-Player

一个基于 Taro + Vue 3 开发的跨平台音视频播放器，支持移动端原生音视频播放。采用**三层架构设计**（壳工程层、应用层、内核层），提高了代码复用性和可维护性。

## 🌟 特性

- 📱 **跨平台支持**：同时支持 iOS、Android、鸿蒙移动端
- 🎬 **原生音视频播放**：使用原生播放器（ExoPlayer/AVPlayer）
- 🎨 **现代化 UI**：基于 Vue 3 + Taro UI 构建的优雅界面
- ⚡ **高性能**：原生插件确保音视频播放流畅无卡顿
- 🔧 **易扩展**：模块化架构设计，支持自定义功能扩展

## 🛠️ 技术栈

### 核心框架
- **Taro 3.x**：跨平台应用开发框架
- **Vue 3**：渐进式 JavaScript 框架
- **TypeScript**：类型安全的 JavaScript 超集

### 音视频处理
- **移动端**：
  - Android: ExoPlayer
  - iOS: AVPlayer

### 状态管理
- **Pinia**：Vue 3 官方推荐的状态管理库

### UI 组件
- **Taro UI Vue**：Taro 官方 Vue 组件库

## 📁 项目架构

Mat Player 采用**三层架构设计**，将音视频核心功能与应用业务逻辑分离，提高了代码复用性和可维护性。

### 架构概览

```
mat-player-project/
├── mat-player-shell/          # 壳工程层
│   ├── platforms/            # 多平台实现
│   ├── src/                  # 共享代码
│   ├── package.json
│   └── README.md
│
├── mat-player-app/            # 应用层
│   ├── src/                  # 应用源码
│   ├── config/               # Taro配置
│   └── package.json
│
└── mat-player-kernel/         # 内核层
    ├── src/                  # 核心实现
    ├── package.json
    └── tsconfig.json
```

### 壳工程层(mat-player-shell)

多平台的应用外壳，提供统一的原生实现：
- iOS 原生实现
- Android 原生实现
- 鸿蒙原生实现
- 统一的平台抽象接口

### 应用层(mat-player-app)

基于 Taro + Vue 3 的应用层，专注于用户体验和业务逻辑：
- 现代化的 UI 界面
- 播放列表管理
- 文件系统访问
- 用户设置管理
- 应用生命周期管理

### 内核层(mat-player-kernel)

独立的音视频播放核心，提供跨平台的音视频播放能力，支持：
- 移动端原生播放器（Android ExoPlayer / iOS AVPlayer）
- 统一的 TypeScript 接口定义
- 完善的事件机制和状态管理

## 🎯 分离架构优势

1. **代码复用**：核心插件可被多个项目复用
2. **独立开发**：插件和壳工程可并行开发，提高效率
3. **灵活扩展**：支持为不同平台定制插件版本
4. **维护简便**：问题定位更精准，降低调试成本
5. **商业价值**：核心插件可作为独立产品对外提供

## 📁 详细架构设计

关于分离架构的详细设计，请参考：
- [应用架构设计](doc/架构设计/应用架构.md)

## 🚀 快速开始

### 环境要求

- Node.js >= 16.0.0
- npm >= 7.0.0 或 yarn >= 1.22.0
- Taro CLI >= 3.6.0

### 安装依赖

```bash
# 安装 Taro CLI
npm install -g @tarojs/cli

# 安装项目依赖
npm install
```

### 开发模式

#### 移动端开发

```bash
# 微信小程序
npm run dev:weapp

# H5
npm run dev:h5

# React Native
npm run dev:rn
```

### 构建生产版本

#### 移动端构建

```bash
# 微信小程序
npm run build:weapp

# H5
npm run build:h5

# React Native
npm run build:rn
```

## 📱 原生插件开发

### Android 插件

1. 进入 `src/plugins/native/android` 目录
2. 使用 Android Studio 打开项目
3. 开发 ExoPlayer 相关功能
4. 构建 AAR 文件
5. 在 Taro 中引用插件

### iOS 插件

1. 进入 `src/plugins/native/ios` 目录
2. 使用 Xcode 打开项目
3. 开发 AVPlayer 相关功能
4. 构建 Framework 文件
5. 在 Taro 中引用插件

##  Android Packaging

To package the application for Android, follow these steps:

1. Ensure you have completed the build process:
   ```bash
   pnpm run build
   ```

2. Build the app-plus platform resources:
   ```bash
   pnpm run build:app-plus
   ```

3. Before packaging, ensure you have set a valid AppID in src/manifest.json. The project has already configured a default AppID (__UNI__098DC4F) for you.

4. Choose one of the following methods for packaging:
   
   a) Local packaging with HBuilderX:
      - Open the project in HBuilderX
      - Right-click on the project and select "发行" -> "原生App-云打包"
      - Choose Android platform and configure other settings as needed
   
   b) DCloud cloud packaging service:
      - Upload the project to DCloud developer center
      - Configure packaging parameters in the cloud
      - Download the packaged APK after completion
   
   c) Offline packaging:
      - Refer to the detailed guide in [doc/安卓打包指南.md](./doc/安卓打包指南.md) for offline packaging instructions

For more details, refer to the [安卓打包指南](./doc/安卓打包指南.md).

## 🎯 核心功能

### 播放器组件

## 📁 本地视频扫描功能

我们已经实现了本地视频扫描功能，用户可以扫描本地视频文件并在应用中播放。有关技术调研的详细信息，请参阅[本地视频文件扫描方案](./doc/技术预研/本地视频文件扫描方案.md)。

UI设计文档请参阅[本地视频文件扫描UI设计](./doc/技术预研/本地视频文件扫描UI设计.md)。

核心逻辑实现方案请参阅[本地视频文件扫描核心逻辑实现方案](./doc/技术预研/本地视频文件扫描核心逻辑实现方案.md)。

测试方案请参阅[本地视频文件扫描功能测试方案](./doc/技术预研/本地视频文件扫描功能测试方案.md)。

性能优化方案请参阅[本地视频文件扫描性能优化方案](./doc/技术预研/本地视频文件扫描性能优化方案.md)。

播放器组件是整个应用的核心，负责音视频的渲染和控制：

```vue
<template>
  <view class="player-container">
    <VideoRender 
      :src="videoUrl" 
      :controls="false"
      @loaded="handleLoaded"
      @play="handlePlay"
      @pause="handlePause"
      @ended="handleEnded"
    />
    <PlayerControl 
      :is-playing="isPlaying"
      :current-time="currentTime"
      :duration="duration"
      @play="handlePlayControl"
      @pause="handlePauseControl"
      @seek="handleSeek"
    />
  </view>
</template>
```

### 状态管理

使用 Pinia 管理播放器状态：

```typescript
import { defineStore } from 'pinia'

export const usePlayerStore = defineStore('player', {
  state: () => ({
    isPlaying: false,
    currentTime: 0,
    duration: 0,
    videoUrl: '',
    volume: 1.0
  }),
  actions: {
    play() {
      this.isPlaying = true
      // 调用原生插件播放
    },
    pause() {
      this.isPlaying = false
      // 调用原生插件暂停
    },
    seek(time: number) {
      this.currentTime = time
      // 调用原生插件跳转
    }
  }
})
```

## 🤝 贡献

欢迎大家参与贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献指南。

## 📄 许可证

本项目采用 **木兰宽松许可证，第2版**，详情请查看 [LICENSE](LICENSE) 文件。

## 📞 联系方式

如有问题或建议，欢迎通过以下方式联系：

- Issue: [GitHub Issues](https://github.com/your-repo/mat-player/issues)
- Email: your-email@example.com

---

**Mat Player** - 专注于提供流畅的跨平台音视频播放体验！