🎬 OrangeCloud Player SDK 开发者文档

快速集成（5 分钟）

1. 获取凭证

在 OMS 后台 → 基础SDK → 播放器管理 中创建应用，获取：

• PlayerAppId — 应用标识
• SecretKey — 密钥（用于 License 校验签名）
• LicenseUrl — License 校验服务地址

2. 初始化 SDK

// Flutter
await OrangeCloudPlayerClient.initialize(
  appId: 'your_player_app_id',
  licenseUrl: 'https://sdk-api.your-domain.com/License/Validate',
  secretKey: 'your_secret_key',
);

3. 播放视频

final player = OrangeCloudPlayerClient();
await player.startVodPlay('https://example.com/video.mp4');

Flutter 安装配置

添加依赖

# pubspec.yaml
dependencies:
  orangecloud_player_client: ^1.0.0

最低版本要求

• Flutter: >= 3.0.0
• Dart: >= 3.0.0
• Android: minSdk 21
• iOS: 14.0+

Flutter 初始化

import 'package:orangecloud_player_client/orangecloud_player_client.dart';

// 在 main() 或 App 启动时调用（只需一次）
await OrangeCloudPlayerClient.initialize(
  appId: 'your_player_app_id',
  licenseUrl: 'https://sdk-api.your-domain.com/License/Validate',
  secretKey: 'your_secret_key', // 可选，提供后启用 License 校验
);

注意：initialize 必须在使用任何播放功能之前调用。

Flutter 播放控制

// 创建播放器
final player = OrangeCloudPlayerClient();

// 播放
await player.startVodPlay('https://example.com/video.mp4');

// 暂停 / 恢复
await player.pause();
await player.resume();

// Seek（秒）
await player.seek(30.0);

// 倍速
await player.setRate(1.5);

// 音量（0.0 - 1.0）
await player.setAudioPlayoutVolume(0.8);

// 静音
await player.setMute(true);

// 循环播放
await player.setLoop(true);

// 截图
final imageData = await player.snapshot();

// 切换清晰度
await player.setBitrateIndex(2);

// 停止
await player.stopPlay();

// 释放资源
await player.dispose();

渲染视频画面

// 在 Widget 中使用
Widget build(BuildContext context) {
  return AspectRatio(
    aspectRatio: 16 / 9,
    child: player.videoWidget,
  );
}

Flutter 事件监听

class MyObserver extends PlayerObserver {
  @override
  void onPlayEvent(PlayerEvent event, Map<String, dynamic> params) {
    switch (event) {
      case PlayerEvent.onPlayBegin:
        print('播放开始');
        break;
      case PlayerEvent.onPlayProgress:
        print('进度: ${params["currentTime"]}s / ${params["duration"]}s');
        break;
      case PlayerEvent.onPlayEnd:
        print('播放结束');
        break;
      case PlayerEvent.onError:
        print('错误: ${params["code"]} - ${params["message"]}');
        break;
      default:
        break;
    }
  }

  @override
  void onNetStatus(Map<String, dynamic> netStatus) {
    print('网速: ${netStatus["speedKBps"]} KB/s');
  }
}

// 注册监听
player.addObserver(MyObserver());

// 移除监听
player.removeObserver(observer);

iOS 安装配置

Swift Package Manager

// Package.swift
dependencies: [
    .package(path: "../OrangeCloudPlayerClient"),
]

初始化

import OrangeCloudPlayerClient

// AppDelegate 中初始化
OCPlayerClient.initialize(appId: "your_app_id", licenseUrl: "https://...")

iOS 播放控制

let player = OCPlayerClient()
player.delegate = self

// 添加播放器视图
view.addSubview(player.playerView)

// 播放
player.startVodPlay("https://example.com/video.mp4")

// 暂停 / 恢复
player.pause()
player.resume()

// Seek（秒）
player.seek(30.0)

// 倍速
player.setRate(1.5)

// 截图
let image = player.snapshot()

Android 安装配置

Gradle 依赖

// settings.gradle.kts
include(":orangecloud-player-client")

// app/build.gradle.kts
dependencies {
    implementation(project(":orangecloud-player-client"))
}

初始化

// Application.onCreate() 中
OrangeCloudPlayerClient.initialize(this, "your_app_id", "https://...")

Android 播放控制

val player = OrangeCloudPlayerClient(context)
player.setPlayerListener(listener)
player.setSurface(surfaceView.holder.surface)

// 播放
player.startVodPlay("https://example.com/video.mp4")

// 暂停 / 恢复
player.pause()
player.resume()

// Seek（秒）
player.seek(30.0f)

// 倍速
player.setRate(1.5f)

// 音量（0.0 - 1.0）
player.setAudioPlayoutVolume(0.8f)

// 释放
player.release()

Web 安装配置

npm install @orangecloud/player-client

初始化

import { OrangeCloudPlayerClient } from '@orangecloud/player-client';

OrangeCloudPlayerClient.initialize({
  appId: 'your_app_id',
  licenseUrl: 'https://...',
});

Web 播放控制

const container = document.getElementById('player');
const player = new OrangeCloudPlayerClient(container);

// 播放
await player.startVodPlay('https://example.com/video.mp4');

// 暂停 / 恢复
player.pause();
player.resume();

// 事件监听
player.on(PlayerEvent.OnPlayProgress, (data) => {
  console.log(`进度: ${data.currentTime}s`);
});

// 释放
player.dispose();

预加载

预播放（Pre-play）

提前创建播放器实例加载到首帧就绪，实现秒切。

// Flutter
final prePlayer = PrePlayerManager(maxConcurrent: 3);
await prePlayer.preload('https://example.com/next-video.mp4');

// 切换时秒开
final readyPlayer = prePlayer.getPreloadedPlayer(url);

预下载（Pre-download）

后台下载视频前 N MB 数据，不创建播放器实例。

// Flutter
final preloadManager = PreloadManager();
await preloadManager.startPreload(
  url: 'https://example.com/video.mp4',
  preloadSizeMB: 2.0,
  preferredResolution: 1080,
);

离线下载

// Flutter
final dm = DownloadManager();
final taskId = await dm.startDownload(url: 'https://example.com/video.mp4');

// 监听进度
dm.onProgress.listen((event) {
  print('下载进度: ${(event.progress * 100).toStringAsFixed(1)}%');
});

// 暂停 / 恢复（断点续传）
await dm.pauseDownload(taskId);
await dm.resumeDownload(taskId);

// 离线播放
final localPath = dm.playOffline(taskId);
if (localPath != null) {
  await player.startVodPlay(localPath);
}

DRM 加密

HLS AES-128

final drm = DRMManager();
drm.configureHLSDecryption(keyUrl: 'https://key-server.com/key');

FairPlay (iOS) / Widevine (Android)

drm.configureDRM(
  licenseUrl: 'https://license.example.com/drm',
  headers: {'Authorization': 'Bearer token'},
);

画中画

// Flutter
final pip = PIPController();
await pip.enterPictureInPictureMode();

// 监听事件
pip.onPIPEvent.listen((event) {
  if (event == PIPEvent.exit) print('退出画中画');
});

字幕

// Flutter
final subtitle = SubtitleEngine();
subtitle.loadSubtitleFromContent(srtContent, SubtitleFormat.srt);

// 监听字幕文本
subtitle.onSubtitleData.listen((data) {
  print('字幕: ${data.text}');
});

完整 API 列表

错误码