# miniVideo

**Repository Path**: newjcj/mini-video

## Basic Information

- **Project Name**: miniVideo
- **Description**: 一个特色的视频播放器，主要针对mp4播放，方便的拖入视频，可设置透明度，可以记忆上次播放位置，可记忆上次大小，和在window的位置，有沉浸模式，方便的双击关闭
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniVideo - 视频播放器

一个基于 Go + Wails 构建的桌面视频播放器。

## 技术架构

### 核心技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| **后端框架** | Go 1.21+ / Wails v2.12.0 | 跨平台桌面应用框架 |
| **渲染引擎** | WebView2 | Windows 系统自带，基于 Chromium |
| **视频播放** | HTML5 Video API | 原生视频播放，无额外依赖 |
| **视频传输** | 自定义 HTTP Handler | 支持 Range 请求，实现视频流式传输 |
| **数据存储** | JSON 文件 | 本地持久化，无需数据库 |

### 视频播放架构详解

```
┌─────────────────────────────────────────────────────────────┐
│                      MiniVideo 播放流程                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   用户点击视频                                                │
│         │                                                   │
│         ▼                                                   │
│   前端请求 /videos/{filename}                                │
│         │                                                   │
│         ▼                                                   │
│   Wails AssetServer Handler                                 │
│         │                                                   │
│         ▼                                                   │
│   Go 后端读取本地文件                                         │
│         │                                                   │
│         ▼                                                   │
│   HTTP Range Response (支持分段传输)                         │
│         │                                                   │
│         ▼                                                   │
│   WebView2 渲染 HTML5 Video                                  │
│         │                                                   │
│         ▼                                                   │
│   用户观看视频                                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### 关键技术点

#### 1. 视频流式传输 (HTTP Range Request)

视频文件不一次性加载，而是通过 HTTP Range 请求按需传输：
- 支持视频进度条拖拽跳转
- 大文件也能快速开始播放
- 减少内存占用

```go
// Range 请求处理示例
func handleRangeRequest(w, r, file, fileSize, contentType) {
    // 解析 Range: bytes=0-1000
    // 只传输请求的数据段
    // 支持 Seek 操作
}
```

#### 2. WebView2 渲染引擎

- Windows 10/11 系统自带 WebView2 运行时
- 基于 Chromium 内核，兼容性优秀
- 支持现代 HTML5/CSS3/ES6+
- 硬件加速视频解码

#### 3. 播放进度自动保存

三种保存机制确保进度不丢失：
- **定时保存**: 每 5 秒自动保存播放位置
- **关闭保存**: 关闭播放器时保存
- **应用退出保存**: 程序关闭前强制保存

#### 4. 分块上传机制

大文件上传采用分块策略：
- 4MB 分块传输
- Base64 编码（适配 Wails 绑定）
- 上传失败自动清理残留文件

## 项目结构

```
miniVideo/
├── main.go              # Wails 入口 + Video HTTP Handler
├── app.go               # 应用逻辑 (视频管理、数据存储)
├── frontend/            # 前端界面
│   ├── index.html       # 主页面
│   ├── main.js          # JavaScript 逻辑
│   └── styles.css       # 样式文件
├── videos/              # 视频文件目录 (git忽略)
├── data/                # 用户数据目录 (git忽略)
│   └── settings.json    # 播放记录和设置
└── wails.json           # Wails 配置
```

## 依赖组件

### Go 依赖
```go
github.com/wailsapp/wails/v2 v2.12.0  // Wails 框架
```

### 前端依赖
- 无第三方依赖，纯原生 JavaScript
- HTML5 Video API（浏览器原生支持）
- CSS3 动画和渐变

### 系统依赖
- **Windows**: WebView2 运行时（系统自带或自动安装）
- **Go**: 1.21+ 版本

## 功能特性

### 核心功能
- 🎬 视频列表管理
- ▶️ 点击播放视频
- ⏯️ 播放/暂停控制
- 📺 全屏播放
- 🎚️ 进度条拖拽跳转
- 🔊 音量调节
- 🗑️ 删除视频

### 📥 上传视频
- 导航栏点击"上传视频"按钮打开上传弹框
- 支持两种上传方式：
  - **选择文件**: 点击"选择文件"按钮浏览本地视频
  - **拖放上传**: 拖放视频文件到上传区域
- 实时显示上传进度条
- 上传完成后显示成功/失败状态
- 支持 MP4, AVI, MKV, MOV, WMV, FLV, WEBM 格式

### 🔍 自动识别
- 点击"自动识别"按钮扫描 videos 目录
- 识别新添加的视频文件
- 清理已删除视频的数据记录

### 🌟 特色功能 - 隐私模式

**隐秘播放体验**：
- 点击视频后弹出播放窗口
- 背景变为半透明遮罩
- 视频可设置透明度 0% ~ 100%
- 0% = 完全透明（几乎看不见）
- 100% = 完全不透明
- 防止他人窥视屏幕内容

**沉浸模式**：
- 点击"沉浸"按钮或双击视频进入沉浸模式
- 沉浸模式下隐藏所有控制栏，只显示视频
- 双击切换：普通模式 → 沉浸 → 沉浸全屏 → 退出沉浸
- 沉浸模式下单击视频暂停/播放
- 沉浸模式顶部有透明拖拽条，可拖动窗口
- 双击顶部拖拽条可关闭应用

### 数据持久化
- 自动记忆每个视频的播放进度
- 保存音量和透明度设置
- **自动保存窗口状态**（大小、位置、最大化状态）
- 程序关闭前强制保存，防止数据丢失
- 再次打开自动恢复上次的窗口状态
- 数据存储在 `data/settings.json`

## 快速开始

### 开发环境
```bash
# 安装 Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# 开发模式运行
wails dev

# 构建生产版本
wails build
```

### 使用方式
1. **上传视频**: 点击导航栏"上传视频"按钮
2. **手动添加**: 将视频文件放入 `videos` 目录，点击"自动识别"
3. **播放**: 点击视频卡片开始播放
4. **调节透明度**: 使用播放器底部的透明度滑块

构建后的程序位于 `build/bin/miniVideo.exe`

## 数据存储结构

```json
{
  "videos": {
    "video_name.mp4": {
      "lastPosition": 125.5,
      "volume": 0.8,
      "opacity": 1.0,
      "tag": "默认",
      "lastPlayed": "2024-01-15T10:30:00Z"
    }
  },
  "globalVolume": 0.8,
  "windowWidth": 1024,
  "windowHeight": 768,
  "windowX": 100,
  "windowY": 50,
  "isMaximized": false
}
```

## 快捷键

| 按键 | 功能 |
|------|------|
| Space | 播放/暂停 |
| Left/Right | 快进/快退 5秒 |
| Up/Down | 音量增减 10% |
| F | 全屏切换 |
| I | 沉浸模式切换 |
| Esc | 退出全屏/退出沉浸/关闭播放 |
| Delete | 删除当前视频 |

## 性能说明

### 视频加载
- 采用 HTTP Range 请求，无需等待整个文件加载
- 首次播放仅需加载视频头部数据（moov atom）

### 内存占用
- 视频文件不加载到内存，直接从磁盘读取
- 仅缓存当前播放所需数据块

### 已知限制
- MP4 文件如果 moov atom 在末尾，首次 seek 可能较慢
- 建议使用 qt-faststart 工具优化 MP4 文件结构

## 许可证

MIT License