Skip to content

README_ZH.md

Latest commit

 

History

History
239 lines (178 loc) · 6.79 KB

README_ZH.md

File metadata and controls

239 lines (178 loc) · 6.79 KB
Raw

AtomicPlayer for Android

一个轻量、原子化的直播播放器 SDK — 启播快、切流稳、扩展轻。

English | 简体中文 | 日本語 · ⬅ 返回全端总览

Platform minSdk

AtomicPlayer 面向低延迟直播（LEB / RTMP）与 CDN 拉流场景，只做一件事：把一路直播流又快又稳地播出来。

  • 🚀 秒开 — 首帧目标 < 600ms
  • 🎞️ 臻彩画质 — AI 超分、HDR 等画质增强能力按需开启
  • 🔄 无缝切流 — 清晰度切换无卡顿
  • 🌐 多端一致 — 各端共用同一套统一流程

✨ 特性一览

能力 接口
播放控制 startPlay / stopPlay / pause / resume
无缝切流 switchStream
渲染控制 setRenderView / setRenderRotation / setRenderFillMode
截图 snapshot
音量 setVolume
SEI 消息 enableReceiveSeiMessage
事件回调 AtomicPlayerObserver
高级特性 enableAdvancedFeature（AI 超分 / HDR …）

🚀 5 分钟快速上手

1. 环境要求

  • Android minSdk 21+（Android 5.0）
  • 架构：armeabi-v7a / arm64-v8a / x86_64

2. 添加 Maven 依赖

在项目根目录的 settings.gradle（或 build.gradle）中添加 Maven 仓库：

dependencyResolutionManagement {
    repositories {
        maven { url "" } // TODO: 填写 AtomicPlayer Maven 仓库地址
    }
}

在业务模块的 build.gradle 中添加依赖：

dependencies {
    implementation "" // TODO: 填写 AtomicPlayer 依赖坐标，如 "io.trtc:atomic-player:x.y.z"
}

3. 添加权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

4. 布局中放一个 AtomicView

<io.trtc.tuikit.atomicxcore.api.view.AtomicView
    android:id="@+id/atomic_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

5. 三行代码播起来

val player = AtomicPlayerImpl()
player.setRenderView(findViewById(R.id.atomic_view))
player.startPlay("https://your-cdn.com/live/stream.m3u8")

6. 完整示例

class PlayerActivity : AppCompatActivity() {

    private lateinit var player: AtomicPlayer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_player)

        player = AtomicPlayerImpl()
        player.setRenderView(findViewById(R.id.atomic_view))

        player.setObserver(object : AtomicPlayerObserver() {
            override fun didRenderFirstVideoFrame(player: AtomicPlayer, elapsedMs: Int) {
                Log.i("AtomicPlayer", "首帧耗时: ${elapsedMs}ms")
            }
            override fun didFailWithCode(
                player: AtomicPlayer,
                code: AtomicPlayerCode,
                message: String
            ) {
                Log.e("AtomicPlayer", "播放失败: $code, $message")
            }
        })

        player.startPlay("https://your-cdn.com/live/stream.m3u8")
    }

    override fun onDestroy() {
        super.onDestroy()
        player.stopPlay()
        player.setObserver(null)
    }
}

支持的协议：FLV / HLS (http(s)://…) · LEB (webrtc://) · RTMP (rtmp://)

📖 常用场景

▶ 无缝切换清晰度（不黑屏） 
// ✅ 推荐：无缝切流，无黑屏
player.switchStream("webrtc://.../stream_1080p")

// ❌ 不推荐：会明显黑屏 + 重走首帧
player.stopPlay()
player.startPlay("webrtc://.../stream_1080p")

切换结果通过 didSwitchStream(player, url, code) 异步回调。

▶ 设置画面填充模式 
import com.tencent.cloud.tuikit.engine.common.TUICommonDefine.VideoRenderParams.FillMode

player.setRenderFillMode(FillMode.Fill)       // 铺满，超出裁剪（默认）
player.setRenderFillMode(FillMode.Fit)        // 等比缩放，可能有黑边
player.setRenderFillMode(FillMode.ScaleFill)  // 拉伸铺满，可能变形
▶ 截图 
player.snapshot()

override fun didTakeSnapshot(player: AtomicPlayer, image: Bitmap) {
    // 保存 / 分享 / 显示
}
▶ 接收 SEI 消息（弹幕位置、连麦信令、时间戳对齐等） 
player.enableReceiveSeiMessage(enable = true, payloadType = 243)

override fun didReceiveSEI(player: AtomicPlayer, data: ByteArray) {
    Log.i(TAG, "收到 SEI: ${String(data, Charsets.UTF_8)}")
}

支持的 payloadType：5 / 100 / 242 / 243。

▶ HEVC 不支持时降级到 H.264 
override fun didFailWithCode(
    player: AtomicPlayer,
    code: AtomicPlayerCode,
    message: String
) {
    if (code == AtomicPlayerCode.ERROR_NO_AVAILABLE_HEVC_DECODERS) {
        player.stopPlay()
        player.startPlay(h264FallbackUrl)
    }
}
▶ 开启高级特性（AI 超分 / HDR） 
player.enableAdvancedFeature("setVideoSuperResolutionEnableMode", 1)             // AI 超分
player.enableAdvancedFeature("enableHdrEnhancement", "{\"enable\": 1}") // HDR

📡 事件回调

AtomicPlayerObserver 全部方法均为默认空实现，只需重写关心的：

分类 回调 说明
播放状态 didRenderFirstVideoFrame(player, elapsedMs) 首帧渲染，返回从起播到首帧的耗时
didStartBuffering(player) / didEndBuffering(player, elapsedMs) 卡顿开始 / 结束
didChangeVideoSize(player, width, height) 分辨率变化
连接 didConnect(player) / didDisconnect(player) 连接建立 / 断开
didFailWithCode(player, code, message) 播放失败
数据 didUpdateStatistics(player, stats) 每 2s 上报一次统计（分辨率 / 码率 / 帧率）
didSwitchStream(player, url, code) 切流完成
didTakeSnapshot(player, image) 截图完成
didReceiveSEI(player, data) 收到 SEI

⚠️ 所有回调均在主线程分发，UI 更新可直接执行；耗时逻辑请自行切子线程。

❗ 错误码

枚举 数值 说明
OK 0 成功
ERROR_FAILED -1 未分类失败
ERROR_INVALID_PARAMETER -1001 参数非法
ERROR_INSTANCE_NOT_EXIST -1002 实例已释放
ERROR_NO_AVAILABLE_HEVC_DECODERS -2304 设备无可用 HEVC 解码器