Skip to content

README_JA.md

Latest commit

 

History

History
239 lines (178 loc) · 7.88 KB

README_JA.md

File metadata and controls

239 lines (178 loc) · 7.88 KB
Raw

AtomicPlayer for Android

軽量・アトミックなライブ配信プレイヤー SDK — 起動が速い、切り替えが安定、拡張が軽い。

English | 简体中文 | 日本語 · ⬅ 全体概要に戻る

Platform minSdk

AtomicPlayer は低遅延ライブ配信（LEB / RTMP）および CDN プル配信シナリオ向けに、1 本のライブストリームを速く安定して再生することだけに特化しています。

  • 🚀 高速起動 — 初期フレーム目標 < 600ms
  • 🎞️ プレミアム画質 — AI 超解像・HDR などの画質強化を必要に応じて有効化
  • 🔄 シームレス切り替え — 画質切替もカクつきなし
  • 🌐 プラットフォーム間の一貫性 — すべてのプラットフォームで統一されたフローを共有

✨ 機能一覧

機能 API
再生制御 startPlay / stopPlay / pause / resume
シームレス切替 switchStream
描画制御 setRenderView / setRenderRotation / setRenderFillMode
スナップショット snapshot
音量 setVolume
SEI メッセージ enableReceiveSeiMessage
イベントコールバック AtomicPlayerObserver
高度な機能 enableAdvancedFeature（AI 超解像 / HDR …）

🚀 5 分クイックスタート

1. 動作要件

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

2. Maven 依存関係を追加

プロジェクトルートの settings.gradle（または build.gradle）に Maven リポジトリを追加します：

dependencyResolutionManagement {
    repositories {
        maven { url "" } // TODO: AtomicPlayer の Maven リポジトリ URL を記入
    }
}

モジュール側の 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. 3 行で再生

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) 初期フレーム描画。startPlay からの経過時間を返します
didStartBuffering(player) / didEndBuffering(player, elapsedMs) バッファリング開始 / 終了
didChangeVideoSize(player, width, height) 解像度変化
接続 didConnect(player) / didDisconnect(player) 接続確立 / 切断
didFailWithCode(player, code, message) 再生失敗
データ didUpdateStatistics(player, stats) 2 秒ごとの統計（解像度 / ビットレート / fps）
didSwitchStream(player, url, code) ストリーム切替完了
didTakeSnapshot(player, image) スナップショット完了
didReceiveSEI(player, data) SEI 受信

⚠️ すべてのコールバックはメインスレッドでディスパッチされます。UI 更新は直接実行可能ですが、重い処理はご自身でバックグラウンドスレッドへ移してください。

❗ エラーコード

Enum 値 説明
OK 0 成功
ERROR_FAILED -1 分類外の失敗
ERROR_INVALID_PARAMETER -1001 不正なパラメータ
ERROR_INSTANCE_NOT_EXIST -1002 インスタンスは解放済み
ERROR_NO_AVAILABLE_HEVC_DECODERS -2304 端末で利用可能な HEVC デコーダーがない