# KoodVideo

**Repository Path**: lythen/kood-video

## Basic Information

- **Project Name**: KoodVideo
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KoodVideo — Android 视频播放器

[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Min SDK](https://img.shields.io/badge/minSdk-26-green)](https://developer.android.com/about/versions/8.0)
[![Target SDK](https://img.shields.io/badge/targetSdk-34-green)](https://developer.android.com/about/versions/14)
[![Kotlin](https://img.shields.io/badge/Kotlin-1.9.22-purple)](https://kotlinlang.org/)
[![Compose](https://img.shields.io/badge/Compose-BOM%202024.02-blue)](https://developer.android.com/jetpack/compose)

KoodVideo 是一款基于开源播放组件 Media3 的 Android 视频播放器，支持常规视频文件播放、全面手势控制、字幕加载与管理、目录递归扫描、播放历史与断点续播、播放列表管理、后台播放、睡眠定时、收藏夹等功能，可注册为系统默认视频播放器。

## 功能特性

### 🎬 播放核心
- **Media3 ExoPlayer** 引擎，支持几乎所有视频格式（mp4, mkv, avi, mov, wmv, flv, webm, 3gp, ts 等）
- **硬件加速**，检测到性能问题时自动回退软件解码
- **画面缩放**：适应屏幕、裁剪全屏、拉伸填充、16:9、4:3
- **视频旋转**：90° 步进旋转
- **A-B 循环**：片段重复播放
- **截图**：保存当前帧到相册
- **视频信息**：编码格式、分辨率、帧率、码率详情

### 👆 手势控制
| 手势 | 区域 | 功能 |
|------|------|------|
| 长按 | 全区域 | 临时倍速播放（可配置） |
| 右滑 | 下半部 | 快进（可配置秒数） |
| 左滑 | 下半部 | 快退（可配置秒数） |
| 左侧上/下滑 | 左半屏 | 调节亮度 |
| 右侧上/下滑 | 右半屏 | 调节音量 |
| 双击 | 全区域 | 播放/暂停 |
| 短按 | 全区域 | 切换控制栏显隐 |
- **防误触锁屏**：横屏播放自动推荐锁定

### 📝 字幕系统
- **自动加载**：自动扫描同目录同名 .srt/.vtt/.ass/.ssa 字幕文件
- **手动加载**：通过 SAF 选择任意字幕文件
- **字幕设置**：字体、大小、颜色、背景、位置、延迟/提前可调

### 🎵 音频
- **多音轨切换**：支持多语言音轨
- **音频延迟**：-500ms ~ +500ms 音画同步微调

### 📂 文件管理
- **打开文件/目录**：SAF 文件选择器
- **目录递归扫描**：可选是否递归加载子目录
- **同目录加载**：打开文件时可自动加载同目录视频
- **播放列表管理**：拖拽排序、长按删除/移除、拖拽播放
- **收藏夹**：收藏常用目录
- **文件搜索**：实时模糊搜索
- **播放历史**：自动记录、进度条显示

### ⚙️ 其他
- **睡眠定时**：15/30/45/60/90 分钟或当前播放结束后停止
- **后台播放**：切到后台时音频继续播放
- **播放历史 & 断点续播**：自动保存播放位置，下次询问是否续播
- **默认播放器**：可注册为系统默认视频播放器
- **全面设置**：所有功能均可自定义配置

## 技术栈

| 层级 | 选型 |
|------|------|
| 语言 | Kotlin 1.9.22 |
| UI 框架 | Jetpack Compose + Material3 |
| 播放引擎 | Media3 (ExoPlayer) 1.3.1 |
| 架构 | MVVM (ViewModel + Repository) |
| 导航 | Compose Navigation |
| 依赖注入 | Hilt 2.51 |
| 持久化 | Room 2.6.1 + DataStore Preferences |
| 文件访问 | SAF (Storage Access Framework) |
| 异步 | Kotlin Coroutines + Flow |

## 环境要求

| 工具 | 版本 |
|------|------|
| Android Studio | Hedgehog 2023.1+ |
| JDK | 17+ |
| Android SDK | Platform 34 + Build-tools 34 |
| Gradle | 8.5 |

## 快速开始

```bash
# 克隆项目
git clone https://gitee.com/lythen/kood-video.git
cd kood-video

# 编译 Debug APK
./gradlew assembleDebug

# 运行单元测试
./gradlew test

# 安装到设备
./gradlew installDebug
```

## 项目结构

```
KoodVideo/
├── app/src/main/java/com/koodvideo/
│   ├── MainActivity.kt              # 单 Activity
│   ├── KoodVideoApp.kt              # Application 类
│   ├── navigation/                   # 导航路由
│   ├── ui/
│   │   ├── player/                  # 播放器页面
│   │   ├── browser/                 # 文件浏览页面
│   │   ├── settings/                # 设置页面
│   │   └── theme/                  # 主题
│   ├── data/
│   │   ├── model/                   # 数据模型
│   │   ├── db/                      # Room 数据库
│   │   ├── repository/              # 仓库层
│   │   └── settings/               # 设置存储
│   ├── player/                      # 播放器引擎封装
│   └── util/                        # 工具类
├── docs/
│   ├── superpowers/specs/           # 设计文档
│   └── superpowers/plans/           # 实施计划
├── CLAUDE.md                        # Claude 项目配置
└── build.gradle.kts                 # 构建配置
```

## 构建配置

项目使用 Gradle 8.5 + Kotlin DSL。依赖版本统一管理在 `gradle/libs.versions.toml`。

关键依赖：
- **Compose BOM 2024.02.00** — Compose UI、Material3、Icons
- **Media3 1.3.1** — ExoPlayer、UI、Session
- **Hilt 2.51** — Android Hilt + Navigation Compose
- **Room 2.6.1** — Runtime、KTX、Compiler
- **DataStore Preferences 1.0.0** — 设置存储

## License

MIT License