OrangePlayer 橘子播放器

For Developers: Professional Android video player library for building video applications.
Open source under Apache 2.0 License.

功能完整的 Android 视频播放器 SDK

基于 GSYVideoPlayer 的增强视频播放器库，为 Android 开发者提供完整的视频播放解决方案

📱 下载 Demo APK | 📖 快速开始 | 📚 API 文档 | ❓ 常见问题

---

截图预览

功能特性

功能	说明
🎬 多播放内核	系统/ExoPlayer/IJK/阿里云，运行时切换
📝 字幕系统	SRT/ASS/VTT 格式，大小可调
🔤 OCR 识别	Tesseract 硬字幕识别 + ML Kit 翻译
🎤 语音识别	Vosk 离线语音识别，实时字幕生成
💬 弹幕功能	大小/速度/透明度可调，支持发送
🎛️ 倍速播放	0.35x - 10x，长按倍速
⏰ 定时关闭	30/60/90/120 分钟
⏭️ 跳过片头尾	0-300 秒可调
📺 投屏	DLNA 投屏支持
🖼️ 画中画	PiP 小窗模式
📸 截图	视频截图保存
📺 Android TV	完整的 TV 适配，遥控器支持
📱 多平台	手机、平板、Android TV 全平台支持

---

📚 文档导航

• 快速开始

  • 安装指南 - 完整的依赖配置和环境设置
  • 基本使用 - 最简单的集成示例
  • 完整示例 - 15 个实用代码示例

• 功能指南

  • 播放内核切换 - 系统/ExoPlayer/IJK/阿里云
  • OCR 字幕翻译 - 硬字幕识别与翻译
  • 语音识别字幕 - 实时语音转字幕
  • 投屏功能 - DLNA 投屏配置
  • Android TV 适配 - TV 平台快速集成

• 开发文档

  • API 文档 - 完整的 API 参考
  • 项目结构 - 代码组织说明

• 其他

  • 常见问题 - 问题排查和解决方案
  • 更新日志 - 版本更新记录
  • 最新更新 - 2024年2月9日更新详情

---

快速开始

系统要求

• Android 4.0+ (API 14+) - 从 v1.1.0+ 开始支持 Android 4.0 及以上版本
• Android 5.0+ (API 21+) - 推荐使用，支持所有功能（包括 ExoPlayer 和 AI 功能）

1. 添加依赖

⚠️ 重要更新：我们已从 JitPack 迁移到 Maven Central

在 app/build.gradle 中添加：

dependencies {
    // OrangePlayer 核心库（Maven Central）- 请使用最新版本
    implementation 'io.github.706412584:orangeplayer:+'
    
    // 必需依赖
    implementation 'com.github.bumptech.glide:glide:4.16.0'  // 图片加载
    
    // 播放器内核（至少选择一个）- 请使用最新版本
    implementation 'io.github.706412584:gsyVideoPlayer-java:+'      // IJK 播放器（推荐）
    implementation 'io.github.706412584:gsyVideoPlayer-exo_player2:+' // ExoPlayer
    
    // 可选依赖（按需添加）
    implementation 'com.github.bilibili:DanmakuFlameMaster:0.9.25'  // 弹幕功能
    implementation 'cz.adaptech.tesseract4android:tesseract4android:4.7.0'  // OCR 识别
    implementation 'com.google.mlkit:translate:17.0.2'  // ML Kit 翻译
    implementation 'com.alphacephei:vosk-android:0.3.47'  // 语音识别
    implementation 'androidx.media3:media3-decoder-ffmpeg:1.5.0'  // FFmpeg 解码器(可选)
}

📦 可用的播放器内核组件（所有组件请使用最新版本）：

• gsyVideoPlayer-java - IJK 播放器（推荐，支持更多格式）
• gsyVideoPlayer-exo_player2 - ExoPlayer（性能好，RTSP 支持完整）
• gsyVideoPlayer-aliplay - 阿里云播放器（商业级，RTMP 延迟低）
• gsyVideoPlayer-base - 播放器基础库
• gsyVideoPlayer-proxy_cache - 代理缓存支持
• gsyVideoPlayer-armv7a - ARMv7a 架构 so 库
• gsyVideoPlayer-armv64 - ARM64 架构 so 库
• gsyVideoPlayer-x86 - x86 架构 so 库
• gsyVideoPlayer-x86_64 - x86_64 架构 so 库

💡 版本说明：

• 使用 + 可自动获取最新版本
• 或访问 Maven Central 查看最新版本号
• 当前最新版本：

阿里云播放器（可选）：

dependencies {
    // 阿里云播放器支持（排除内置版本，避免授权问题）- 请使用最新版本
    implementation('io.github.706412584:gsyVideoPlayer-aliplay:+') {
        exclude group: 'com.aliyun.sdk.android', module: 'AliyunPlayer'
        exclude group: 'com.alivc.conan', module: 'AlivcConan'
    }
    
    // 使用 5.4.7.1 版本（无需授权）
    implementation 'com.aliyun.sdk.android:AliyunPlayer:5.4.7.1-full'
}

需要在项目根目录的 build.gradle 中添加阿里云 Maven 仓库：

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://maven.aliyun.com/repository/releases' }
    }
}

💡 依赖说明：

• 必需：orangeplayer + glide + 至少一个播放器内核
• 播放器内核：IJK（推荐，支持更多格式）、ExoPlayer（性能好）、系统播放器（无需额外依赖）、阿里云（商业级）
• 可选功能：弹幕、OCR、语音识别、FFmpeg 解码器等按需添加
• 完整的依赖配置请查看 安装指南

2. 布局文件

<com.orange.playerlibrary.OrangevideoView
    android:id="@+id/video_player"
    android:layout_width="match_parent"
    android:layout_height="200dp" />

3. 基本使用

import com.orange.playerlibrary.OrangevideoView;

public class MainActivity extends AppCompatActivity {
    private OrangevideoView mVideoView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        mVideoView = findViewById(R.id.video_player);
        
        // 设置视频地址和标题
        mVideoView.setUp("https://example.com/video.mp4", true, "示例视频");
        
        // 开始播放
        mVideoView.startPlayLogic();
    }
    
    @Override
    protected void onPause() {
        super.onPause();
        mVideoView.onVideoPause();
    }
    
    @Override
    protected void onResume() {
        super.onResume();
        mVideoView.onVideoResume();
    }
    
    @Override
    protected void onDestroy() {
        super.onDestroy();
        mVideoView.release();
    }
    
    @Override
    public void onBackPressed() {
        if (mVideoView.isFullScreen()) {
            mVideoView.exitFullScreen();
            return;
        }
        super.onBackPressed();
    }
}

就这么简单！OrangePlayer 会自动创建和配置所有 UI 组件。

4. Android TV 使用

OrangePlayer 完全支持 Android TV 平台，自动适配遥控器操作和 TV UI。

布局文件（与手机相同）：

<com.orange.playerlibrary.OrangevideoView
    android:id="@+id/video_player"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Activity 代码：

public class TvPlayerActivity extends AppCompatActivity {
    private OrangevideoView videoPlayer;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_tv_player);
        
        videoPlayer = findViewById(R.id.video_player);
        
        // TV 模式会自动检测，无需额外配置
        videoPlayer.setUp(videoUrl, false, videoTitle);
        videoPlayer.startPlayLogic();
    }
    
    @Override
    public boolean onKeyDown(int keyCode, KeyEvent event) {
        // 处理遥控器按键
        switch (keyCode) {
            case KeyEvent.KEYCODE_BACK:
                if (videoPlayer.isIfCurrentIsFullscreen()) {
                    videoPlayer.onBackFullscreen();
                    return true;
                }
                break;
            case KeyEvent.KEYCODE_MEDIA_PLAY_PAUSE:
                // 播放/暂停切换
                if (videoPlayer.getCurrentState() == GSYVideoPlayer.CURRENT_STATE_PLAYING) {
                    videoPlayer.onVideoPause();
                } else {
                    videoPlayer.onVideoResume();
                }
                return true;
        }
        return super.onKeyDown(keyCode, event);
    }
}

TV 模式特性：

• ✅ 自动检测 TV 设备（通过 PackageManager.FEATURE_LEANBACK）
• ✅ 自动隐藏不适合 TV 的 UI（投屏、小窗按钮）
• ✅ 保留所有播放控制功能（播放、暂停、进度、设置等）
• ✅ 支持遥控器导航和按键操作
• ✅ 完整的焦点管理
• ✅ 与手机版使用相同的代码和 API

详细文档：

• TV 快速开始 - 5 分钟快速集成
• TV 适配指南 - 完整的 TV 开发指南

---

完整使用示例

查看 完整示例代码，包含 15 个实用场景：

1. 基础播放器 - 最简单的实现
2. 带自定义请求头
3. 播放状态监听
4. 播放进度监听
5. 播放完成监听
6. 倍速播放
7. 字幕加载
8. 弹幕功能
9. 播放列表
10. 画中画模式
11. 投屏功能
12. OCR 字幕识别
13. 语音识别字幕
14. 播放器设置
15. 错误处理

---

播放内核切换

OrangePlayer 支持 4 种播放内核，并提供智能自动选择功能。

自动内核选择（可选）⭐

从 v1.0.8 开始，OrangePlayer 提供智能内核选择功能，可根据视频 URL 协议自动选择最合适的播放器内核。

启用自动选择：

// 在 Application 或 Activity 中启用
PlayerSettingsManager.getInstance(context).setAutoSelectEngine(true);

// 之后直接使用 setUp，播放器会自动选择最合适的内核
videoView.setUp("rtsp://192.168.1.6:8554/live", true, "RTSP 直播");
videoView.startPlayLogic();

// RTSP → 自动使用 ExoPlayer
// RTMP → 自动使用阿里云（延迟低）
// HLS  → 自动使用阿里云（性能好）
// HTTP → 自动使用 ExoPlayer

自动选择规则：

• RTSP 协议 → ExoPlayer（阿里云不支持）
• RTMP 协议 → 阿里云（延迟极低 1-3秒）⭐
• HLS (m3u8) → 阿里云（商业级优化）
• HTTP/HTTPS → ExoPlayer（性能好）
• 本地文件 → ExoPlayer

智能特性：

• ✅ 自动检测依赖是否已导入
• ✅ 只在需要时才切换内核（避免不必要的切换）
• ✅ 如果推荐的内核不可用，继续使用当前内核
• ✅ 默认禁用，需要手动启用

禁用自动选择：

// 禁用后恢复手动选择模式
PlayerSettingsManager.getInstance(context).setAutoSelectEngine(false);

手动切换内核（默认方式）

如果不启用自动选择，或需要手动指定内核，可以在 setUp 之前调用：

// 手动切换到 ExoPlayer
videoView.selectPlayerFactory(PlayerConstants.ENGINE_EXO);

// 手动切换到 IJK 播放器
videoView.selectPlayerFactory(PlayerConstants.ENGINE_IJK);

// 手动切换到系统播放器
videoView.selectPlayerFactory(PlayerConstants.ENGINE_DEFAULT);

// 手动切换到阿里云播放器
videoView.selectPlayerFactory(PlayerConstants.ENGINE_ALI);

使用智能选择器工具类（高级用法）

如果需要在 setUp 之外使用智能选择功能：

import com.orange.playerlibrary.utils.PlayerEngineSelector;

// 获取推荐的内核
String url = "rtsp://192.168.1.6:8554/live";
int engine = PlayerEngineSelector.selectEngine(url);
videoView.selectPlayerFactory(engine);

// 打印内核支持情况（调试用）
PlayerEngineSelector.printEngineSupportInfo(url);

// 检查某个内核是否支持该 URL
boolean supported = PlayerEngineSelector.isEngineSupported(url, PlayerConstants.ENGINE_ALI);

详细对比和配置请查看 播放内核指南。

---

可选功能依赖

OrangePlayer 采用模块化设计，所有高级功能都是可选的，按需添加即可。

弹幕功能

dependencies {
    implementation 'com.github.bilibili:DanmakuFlameMaster:0.9.25'
}

使用方法：

// 启用弹幕
videoView.setDanmakuEnabled(true);

// 发送弹幕
videoView.sendDanmaku("弹幕内容", textSize, textColor);

OCR 字幕翻译

识别视频画面中的硬字幕并翻译。

dependencies {
    implementation 'cz.adaptech.tesseract4android:tesseract4android:4.7.0'
    implementation 'com.google.mlkit:translate:17.0.2'
}

详细配置请查看 OCR 功能指南。

语音识别字幕

实时识别视频音频并生成字幕（需要 Android 10+）。

dependencies {
    implementation 'com.alphacephei:vosk-android:0.3.47'
}

详细配置请查看 语音识别指南。

FFmpeg 解码器（可选）

增强的音视频解码支持，处理更多编码格式。

dependencies {
    // 方案 1：Google 官方 Media3 FFmpeg 解码器（推荐）
    implementation 'androidx.media3:media3-decoder-ffmpeg:1.5.0'
    
    // 方案 2：Jellyfin 定制版 FFmpeg 解码器
    implementation 'org.jellyfin.media3:media3-ffmpeg-decoder:1.8.0+1'
}

⚠️ 重要说明：两个方案二选一即可，不要同时添加。

FFmpeg 解码器的作用：

media3-decoder-ffmpeg 和 media3-ffmpeg-decoder 都是音视频解码器（Decoder），不是协议处理器或解封装器。

它能做什么：

• ✅ 解码音视频编码格式：
  • 视频：H.264, H.265/HEVC, VP8, VP9, AV1, MPEG-2, MPEG-4 等
  • 音频：AAC, MP3, Opus, Vorbis, FLAC, AC-3, DTS 等
• ✅ 增强格式支持：处理 Android 原生不支持的编码格式
• ✅ 提高兼容性：在不同设备上提供一致的解码能力
• ✅ 软件解码：在硬件解码失败时提供备选方案

它不能做什么：

• ❌ 不提供网络协议支持（RTSP, RTMP, HLS 等协议由播放器内核处理）
• ❌ 不提供解封装能力（MP4, MKV, FLV 等容器格式由播放器内核处理）
• ❌ 不能解决阿里云播放器不支持 RTSP 的问题（这是协议层的限制，需要切换内核）

播放器架构说明：

完整的视频播放流程：

网络协议层 (Protocol)  ← 处理 RTSP/RTMP/HLS 等协议（播放器内核负责）
    ↓
解封装层 (Demuxer)     ← 处理 MP4/MKV/FLV 等容器（播放器内核负责）
    ↓
解码层 (Decoder)       ← FFmpeg 解码器在这里工作 ⭐
    ↓
渲染层 (Renderer)      ← 显示画面和播放声音

使用场景：

• ✅ 播放包含特殊编码格式的视频（如 VP9, AV1, HEVC）
• ✅ 在低端设备上提供软件解码支持
• ✅ 确保在所有设备上的解码一致性
• ✅ 播放包含 AC-3, DTS 等音频编码的视频

不适用场景：

• ❌ 解决协议不支持问题（如阿里云不支持 RTSP）→ 应该切换播放器内核
• ❌ 添加新的网络协议支持 → 由播放器内核决定
• ❌ 处理容器格式问题 → 由播放器内核决定

有无 FFmpeg 解码器的区别：

场景	无 FFmpeg 解码器	有 FFmpeg 解码器
H.264 视频	✅ 硬件解码	✅ 硬件解码（优先）+ 软件解码（备选）
H.265/HEVC	✅ 硬件解码（部分设备）	✅ 硬件解码 + 软件解码（兼容性更好）
VP9 视频	⚠️ 部分设备不支持	✅ 软件解码（所有设备支持）
AV1 视频	❌ 大部分设备不支持	✅ 软件解码（所有设备支持）
AC-3/DTS 音频	❌ 不支持	✅ 软件解码
RTSP 协议	取决于播放器内核	取决于播放器内核（解码器不影响）

推荐配置：

dependencies {
    // 播放器内核（必需）
    implementation 'io.github.706412584:gsyVideoPlayer-exo_player2:1.1.1'
    
    // FFmpeg 解码器（可选，增强编码格式支持）
    implementation 'androidx.media3:media3-decoder-ffmpeg:1.5.0'
}

💡 提示：

• 如果只播放常见格式（H.264 + AAC），可以不添加 FFmpeg 解码器
• 如果需要播放 VP9, AV1, HEVC 或 AC-3/DTS 音频，建议添加
• 如果遇到协议不支持的问题（如阿里云无法播放 RTSP），应该切换播放器内核，而不是添加 FFmpeg 解码器
• 详见 阿里云 FFmpeg 分析

ExoPlayer 内核

Google 官方播放器，性能优秀。

dependencies {
    implementation 'io.github.706412584:gsyVideoPlayer-exo_player2:1.1.1'
}

切换到 ExoPlayer：

videoView.selectPlayerFactory(PlayerConstants.ENGINE_EXO);

阿里云播放器

商业级播放器，支持加密视频、更好的直播支持。

// 在项目根目录 build.gradle 添加阿里云仓库
allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/releases' }
    }
}

// 在 app/build.gradle 添加依赖
dependencies {
    // 排除内置的阿里云播放器，避免授权问题
    implementation('io.github.706412584:gsyVideoPlayer-aliplay:1.1.1') {
        exclude group: 'com.aliyun.sdk.android', module: 'AliyunPlayer'
        exclude group: 'com.alivc.conan', module: 'AlivcConan'
    }
    
    // 使用指定版本的阿里云播放器（5.4.7.1 版本无需授权）
    implementation 'com.aliyun.sdk.android:AliyunPlayer:5.4.7.1-full'
}

⚠️ 重要提示：

• gsyvideoplayer-aliplay 内置的阿里云播放器版本较新，需要授权才能播放
• 使用 5.4.7.1-full 版本可以免授权使用
• 如需使用最新版本，请到阿里云官网申请授权

切换到阿里云播放器：

videoView.selectPlayerFactory(PlayerConstants.ENGINE_ALI);

DLNA 投屏

dependencies {
    implementation 'com.github.AnyListen:UaoanDLNA:1.0.1'
    implementation 'com.squareup.okhttp3:okhttp:4.12.0'
}

详细配置请查看 投屏功能指南。

---

播放内核对比

内核	优点	缺点	推荐场景	支持协议
IJK	格式支持最全，开源免费	包体积较大（~10MB）	通用场景，格式复杂	RTSP, RTMP, HLS, HTTP, FLV
ExoPlayer	性能好，Google 官方，RTSP 支持完整	部分格式支持有限	性能要求高，RTSP 直播	RTSP, HLS, DASH, HTTP
系统播放器	无额外依赖，包体积小	功能有限，兼容性差	简单场景	取决于设备
阿里云	RTMP 延迟极低（1-3秒），商业级优化	收费，包体积大，不支持 RTSP	RTMP 直播，HLS 直播	HLS, RTMP, FLV, HTTP

⚠️ 直播流播放建议：

• RTSP 直播：使用 ExoPlayer 或 IJK（阿里云不支持）
• RTMP 直播：⭐ 强烈推荐阿里云（延迟极低 1-3秒，商业级优化）
  • 阿里云 RTMP：1-3 秒延迟
  • IJK RTMP：3-5 秒延迟
  • HLS：10-30 秒延迟
• HLS 直播 (m3u8)：阿里云、ExoPlayer、IJK 均可
• 系统播放器：不推荐用于直播（兼容性差）

💡 协议选择建议：

• 超低延迟直播（1-3秒）：RTMP + 阿里云 ⭐
• RTSP 直播：ExoPlayer 或 IJK
• HLS 直播 (m3u8)：阿里云、ExoPlayer、IJK 均可
• 点播视频 (MP4/HTTP)：所有内核均支持

🚀 自动内核选择： 从 v1.0.8 开始，OrangePlayer 提供智能内核选择功能，可根据 URL 协议自动选择最合适的内核。

启用方式：

PlayerSettingsManager.getInstance(context).setAutoSelectEngine(true);

特性：

• ✅ 自动检测依赖是否已导入
• ✅ 只在需要时才切换内核
• ✅ 默认禁用，需要手动启用

---

可选功能

常见问题

遇到问题？查看 常见问题解答：

• NoClassDefFoundError: BasePlayerManager
• 播放黑屏或无声音
• 阿里云播放器黑屏/水印
• 字幕不显示
• 语音识别无法启动
• OCR 识别不准确

更多问题请查看完整的 FAQ 文档。

---

API 文档

完整的 API 参考请查看 API 文档。

主要类

• OrangevideoView - 主播放器视图
• OrangeVideoController - 播放器控制器
• SubtitleManager - 字幕管理器
• LanguagePackManager - OCR 语言包管理
• PlayerSettingsManager - 设置管理器
• PlayerConstants - 常量定义

渲染模式设置

OrangePlayer 支持两种渲染模式，默认使用 TextureView（已修复横竖屏切换崩溃问题）：

1. TextureView 模式（推荐，默认）

// 设置为 TextureView 渲染模式
mVideoView.setRenderMode(true);

优点：

• ✅ 已修复横竖屏切换崩溃问题（通过 MediaCodecTexture）
• ✅ 支持 OCR 字幕识别
• ✅ 支持视频截图
• ✅ 可以应用动画和变换
• ✅ 所有 Android 版本都支持

适用场景：

• 需要 OCR 字幕识别
• 需要视频截图功能
• 需要应用视频特效

2. SurfaceView 模式

// 设置为 SurfaceView 渲染模式
mVideoView.setRenderMode(false);

优点：

• ✅ Android Q+ 支持 SurfaceControl 无缝切换
• ✅ 性能更好，内存占用更低
• ✅ 适合直播流（RTSP/RTMP）

适用场景：

• Android Q+ 设备
• 直播流播放
• 对性能要求高的场景

3. 查询当前渲染模式

boolean isTextureView = mVideoView.isTextureViewMode();
if (isTextureView) {
    Log.d(TAG, "当前使用 TextureView 渲染");
} else {
    Log.d(TAG, "当前使用 SurfaceView 渲染");
}

4. 技术说明

TextureView 横竖屏切换修复原理：

之前 ExoPlayer 和系统播放器在 TextureView 模式下横竖屏切换会崩溃，原因是系统会销毁 SurfaceTexture，导致 MediaCodec 抛出 IllegalStateException。

我们通过启用 MediaCodecTexture 修复了这个问题：

• enableMediaCodecTexture() 让 onSurfaceTextureDestroyed() 返回 false
• 系统不会销毁 SurfaceTexture，横竖屏切换时复用
• MediaCodec 继续渲染到同一个 Surface，不会崩溃

适用范围：

• ✅ 所有播放器内核（ExoPlayer、系统播放器、IJK）
• ✅ 所有 Android 版本
• ✅ 硬解和软解模式

💡 建议：

• 大多数场景使用默认的 TextureView 模式即可
• 如果是 Android Q+ 设备且对性能要求高，可以切换到 SurfaceView
• 切换渲染模式需要在 setUp() 之前调用

---

项目结构

详细结构请查看 STRUCTURE.md

---

混淆配置

# GSYVideoPlayer
-keep class com.shuyu.gsyvideoplayer.** { *; }
-keep class tv.danmaku.ijk.** { *; }

# OrangePlayer
-keep class com.orange.playerlibrary.** { *; }

# Tesseract OCR
-keep class com.googlecode.tesseract.android.** { *; }

# ML Kit Translation
-keep class com.google.mlkit.** { *; }

# Vosk 语音识别
-keep class org.vosk.** { *; }

# 阿里云播放器
-keep class com.aliyun.player.** { *; }
-keep class com.cicada.player.** { *; }

# DLNA 投屏
-keep class com.uaoanlao.tv.** { *; }

---

License

Apache License 2.0

---

作者

QQ: 706412584

如有问题或建议，欢迎联系交流。

致谢

• GSYVideoPlayer
• Tesseract4Android
• DanmakuFlameMaster
• UaoanDLNA