# videocompress

**Repository Path**: DragonCodingPlus/videocompress

## Basic Information

- **Project Name**: videocompress
- **Description**: VideoCompressLite（中文名：视频轻压）是一款 Android 视频压缩工具，基于 MediaCodec 硬件编码 + OpenGL ES 渲染管线实现纯离线压缩，所有处理在本地完成，不上传任何数据，保护用户隐私。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-18
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 视频轻压 / VideoCompressLite

一款现代、注重隐私的 Android 视频压缩工具，基于 MediaCodec 硬件编码和 GPU 加速三线程管线。

## 功能

- **纯离线压缩** — 所有处理在设备本地完成，数据不会离开手机
- **硬件加速** — 利用 Android MediaCodec + OpenGL ES 实现高效的帧缩放和编码
- **模板预设** — 提供预设画质/码率模板（如 1080p、720p、480p），一键压缩
- **批量处理** — 选择多个视频依次压缩，实时跟踪进度
- **深色沉浸 UI** — 蓝紫渐变主题，Material 3 Compose 实现，AMOLED 屏优化
- **压缩历史** — 持久化记录所有压缩任务，支持删除、分享、预览
- **取消清理** — 取消压缩时自动删除不完整的输出文件
- **相册集成** — 压缩后的视频自动出现在系统相册

## 截图

| 首页 | 模板选择 | 视频选择 | 压缩进度 |
|------|---------|---------|---------|
| ![首页](docs/screenshots/home.png) | ![模板](docs/screenshots/templates.png) | ![选择](docs/screenshots/picker.png) | ![进度](docs/screenshots/progress.png) |

| 历史记录 | 历史详情 | 关于 |
|---------|---------|------|
| ![历史](docs/screenshots/history.png) | ![详情](docs/screenshots/detail.png) | ![关于](docs/screenshots/about.png) |

## 架构

```
┌────────────────────────────────────────────────────────────┐
│                    MVVM + Navigation Compose                │
├──────────┬──────────┬───────────┬───────────┬──────────────┤
│   首页   │  模板选择 │  压缩进度  │  历史记录  │    关于      │
├──────────┴──────────┴───────────┴───────────┴──────────────┤
│                    AppState (ViewModel)                     │
├────────────────────────────────────────────────────────────┤
│                     CompressionEngine + Pipeline            │
├──────────────────┬──────────────────┬──────────────────────┤
│   Reader 线程    │   GL 线程        │   Writer 线程         │
│  (MediaExtractor)│ (SurfaceTexture  │  (MediaMuxer +       │
│                  │  + OpenGL ES 3.0)│   MediaCodec 编码器)  │
└──────────────────┴──────────────────┴──────────────────────┘
```

### 三线程 GPU 管线

视频轻压采用三线程 GPU 管线实现高效的实时帧处理：

1. **Reader** — 通过 `MediaExtractor` 解码源视频帧，将 `SurfaceTexture` 时间戳送入 `LinkedBlockingQueue`（容量 120，非阻塞 offer 语义）
2. **GL Scaler** — 将解码器输出绑定到 `SurfaceTexture`，通过自定义 OpenGL ES 3.0 透传着色器渲染，写入编码器输入 `Surface`。通过 `onFrameAvailable` 回调实现帧级同步
3. **Writer** — 将编码后的数据包写入 `MediaMuxer`，PTS 透传（编码器 Surface PTS 内部一致）

关键设计决策：

- **Surface-to-Surface 渲染** — 避免 CPU 回读（无 `glReadPixels`），整条管线保持在 GPU 上运行
- **HandlerThread 帧同步** — `onFrameAvailable` 回调分发到 GL 线程的 handler，协作式 yield 调度防止缓冲区队列溢出
- **Buffer 抽取纪律** — 每轮只抽取一帧，避免在 4 槽 `BufferQueue` 上死锁
- **CancellationException 安全** — 管线 + 校验包裹在 try-catch 中，确保取消时释放 GL 资源并删除不完整文件

## 设计系统

### 色板

| Token | 色值 | 用途 |
|-------|------|------|
| `DeepBackground` | `#0D0D1A` | 主背景色 |
| `MediumBackground` | `#1A1A2E` | 顶栏、底栏、状态表面 |
| `SurfaceCard` | `#1E1E36` | 卡片背景 |
| `GradientStart` | `#667EEA` | 渐变起始（蓝） |
| `GradientEnd` | `#764BA2` | 渐变终止（紫） |
| `TextPrimary` | `#E0E0FF` | 标题、主要内容 |
| `TextSecondary` | `#8888AA` | 描述、次要信息 |

### 排版

- Headlines: `headlineSmall`、Bold — 页面标题和段落标题
- Body: `bodyMedium` / `bodySmall` — 描述、状态文本
- Labels: `labelMedium` — 卡片字段标签
- Monospace：仅用于内部日志输出

## 技术栈

- **语言**: Kotlin
- **UI**: Jetpack Compose + Material 3（支持 Material You 动态色彩结构，当前锁定深色主题）
- **架构**: MVVM + Navigation Compose
- **状态管理**: ViewModel + StateFlow，Compose 友好的状态提升
- **异步**: Kotlin Coroutines + Dispatchers.Default/IO + 自定义 gpuDispatcher（基于 HandlerThread）
- **视频管线**: MediaExtractor → OpenGL ES 3.0 → MediaCodec（编码器）→ MediaMuxer
- **图片加载**: Coil（Compose 集成）
- **构建系统**: Gradle + Version Catalog（libs.versions.toml）
- **Min SDK**: 28 | **Target SDK**: 36 | **Compile SDK**: 36

## 快速开始

### 前置条件

- Android Studio Hedgehog（2023.1.1）或更新版本
- JDK 17+
- Android 设备或模拟器，API 28+

### 构建

```bash
# 克隆仓库
git clone https://github.com/dragon/VideoCompressLite.git
cd VideoCompressLite

# 构建 Debug APK
./gradlew assembleDebug

# 构建 Release APK
./gradlew assembleRelease
```

Debug APK 生成路径：`app/build/outputs/apk/debug/app-debug.apk`

### 安装

```bash
# 通过 ADB 安装 Debug 版本
adb install app/build/outputs/apk/debug/app-debug.apk
```

或在 Android Studio 中打开项目，直接运行到连接的设备上。

## 项目结构

```
VideoCompressLite/
├── app/
│   └── src/main/java/com/dragon/videocompresslite/
│       ├── MainActivity.kt              # 单一 Activity，Compose 宿主
│       ├── ui/
│       │   ├── theme/                   # 颜色、排版、主题
│       │   ├── navigation/
│       │   │   ├── Screen.kt            # 路由定义
│       │   │   └── NavGraph.kt          # 导航图
│       │   ├── home/                    # 首页
│       │   ├── template/               # 模板选择
│       │   ├── selection/              # 视频选择
│       │   ├── compression/            # 压缩进度
│       │   ├── history/                # 压缩历史
│       │   └── about/                  # 关于
│       ├── data/
│       │   ├── model/                  # 数据模型（VideoInfo、CompressionTemplate 等）
│       │   └── repository/            # MediaStore 仓库
│       └── engine/
│           ├── CompressionEngine.kt    # 总调度
│           ├── CompressionOrchestrator.kt  # 三线程管线协调器
│           └── GpuScaler.kt            # OpenGL ES 帧缩放器
├── docs/                              # 文档和设计规格
├── build.gradle.kts
├── settings.gradle.kts
└── gradle/
    └── libs.versions.toml             # 版本目录
```

## 许可

本项目由 **Dragon** 开发和维护。
- 下载：[视频轻压](https://gitee.com/DragonCodingPlus/videocompress/releases/download/V1.0/VideoCompressLite-1.0.apk)
- 作者主页：[mjlong123.top](http://mjlong123.top)
- 产品页面：[mjlong123.top/products/videocompress](http://mjlong123.top/products/videocompress)