自定义配置

概念介绍

三层配置体系

AliPlayerKit 的完整配置体系包含三个层级：

┌─────────────────────────────────────────────────────────┐
│              1. 全局配置 (OnGlobalInitBlock)              │
│         应用启动时执行一次，影响所有播放器实例                │
├─────────────────────────────────────────────────────────┤
│              2. 模型配置 (AliPlayerModel)                 │
│         每次 configure: 时通过属性设置播放参数               │
├─────────────────────────────────────────────────────────┤
│           3. 实例配置 (onPlayerConfigBlock)               │
│       每次 configure: 时在 prepare 前回调底层播放器          │
└─────────────────────────────────────────────────────────┘

全局配置（Global Config）

适用场景

• 设置全局 Option（如全局日志级别）

• 启用 HTTP/2 多路复用

• 配置全局 DNS 解析策略

• 其他需要在所有播放器实例创建前生效的全局行为

机制说明

• 通过 +[AliPlayerKit setOnGlobalInitBlock:] 注册回调 Block

• 回调在 +setup 完成内部初始化后触发，仅执行一次

• 执行后 Block 被置 nil，后续不再触发

• 此时底层 SDK 已就绪，可安全调用全局 API

使用方式

在 application:didFinishLaunchingWithOptions: 中，调用 +setup 之前注册回调：

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 1. 注册全局自定义配置回调（必须在 setup 之前调用）
    [AliPlayerKit setOnGlobalInitBlock:^{
        // 示例：启用 HTTP/2 多路复用
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];

        // 示例：设置全局日志级别
        // [AliPlayerFactory setLogLevel:AF_LOG_LEVEL_INFO];
    }];

    // 2. 初始化（内部完成初始化后触发上面注册的回调）
    [AliPlayerKit setup];

    return YES;
}

配置时序

application:didFinishLaunchingWithOptions:
    │
    ├── [AliPlayerKit setOnGlobalInitBlock:block]   ← 注册回调
    │
    └── [AliPlayerKit setup]
            │
            ├── [GlobalManager setup]    ← 底层 SDK 初始化
            │
            ├── sInitialized = YES
            │
            └── block()                  ← 触发全局配置回调（仅一次）

注意事项

实例配置（Player Config）

适用场景

• 自定义缓冲策略（maxBufferDuration、highBufferDuration 等）

• 设置 Referer 防盗链

• 配置 HTTP Header

• 设置实例级 Option

• 其他 AliPlayerKit 未直接透出的播放器接口

机制说明

• 通过 AliPlayerModel.onPlayerConfigBlock 设置回调 Block

• 每次调用 [controller configure:model] 时触发

• 回调在 setDataSource: 之后、prepare 之前执行

• 回调参数为遵循 MediaPlayer 协议的底层播放器实例

使用方式

在构建 AliPlayerModel 时设置 onPlayerConfigBlock：

VideoSource *source = [VideoSource urlSourceWithUrl:@"https://example.com/video.mp4"];
AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

// 设置实例级自定义配置回调
model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
    // 示例 1：自定义缓冲策略
    AVPConfig *config = [player getConfig];
    config.maxBufferDuration = 50000;       // 最大缓冲时长 50s
    config.highBufferDuration = 3000;       // 高水位缓冲 3s
    config.startBufferDuration = 500;       // 起播缓冲 500ms
    [player setConfig:config];

    // 示例 2：设置 Referer 防盗链
    AVPConfig *refConfig = [player getConfig];
    refConfig.referer = @"https://your-domain.com";
    [player setConfig:refConfig];

    // 示例 3：设置实例级 Option
    // [player setOption:key value:value];
};

// 配置并播放
[controller configure:model];

配置时序

[controller configure:model]
    │
    ├── lifecycleStrategy.acquire()             ← 获取播放器实例
    │
    ├── [mediaPlayer setDataSource:model]       ← 配置视频源
    │
    ├── model.onPlayerConfigBlock(mediaPlayer)  ← 触发实例配置回调
    │
    ├── [strategyManager start/reset]           ← 策略系统启动
    │
    └── [mediaPlayer prepare]                   ← 开始准备播放

注意事项

内置配置项

AliPlayerKit 全局配置

通过 AliPlayerKit 类方法直接设置的内置配置项：

AliPlayerModel 实例配置

通过 AliPlayerModel 属性设置的实例级配置项：

AliPlayerController 运行时配置

通过 AliPlayerController 方法在运行时动态调整的配置：

配置优先级

优先级规则

当同一配置项在不同层级都有设置时，按以下优先级生效：

实例配置（onPlayerConfigBlock） > AliPlayerModel 属性 > 全局配置 > SDK 默认值

配置生效范围

完整配置示例

综合示例

// ===== 全局配置（AppDelegate 中，仅一次）=====
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 全局自定义配置
    [AliPlayerKit setOnGlobalInitBlock:^{
        // 启用 HTTP/2 多路复用
        [AliPlayerFactory setOption:ALLOW_H2_MULTIPLEX value:1];
    }];

    // 初始化
    [AliPlayerKit setup];

    // 全局内置配置（需在 setup 之后调用）
    [AliPlayerKit setLogLevel:LogLevelWarn];
    [AliPlayerKit enableConsoleLog:YES];

    return YES;
}

// ===== 实例配置（播放页中，每次播放）=====
- (void)startPlayback {
    VideoSource *source = [VideoSource urlSourceWithUrl:videoUrl];
    AliPlayerModel *model = [[AliPlayerModel alloc] initWithVideoSource:source];

    // Model 属性配置
    model.sceneType = SceneTypeVOD;
    model.videoTitle = @"精彩视频";
    model.coverUrl = coverImageUrl;
    model.autoPlay = YES;
    model.hardwareDecode = YES;
    model.startTime = resumePosition; // 断点续播

    // 实例级自定义配置（底层 SDK）
    model.onPlayerConfigBlock = ^(id<MediaPlayer> player) {
        AVPConfig *config = [player getConfig];
        config.maxBufferDuration = 50000;
        config.highBufferDuration = 3000;
        config.startBufferDuration = 500;
        config.referer = @"https://your-domain.com";
        [player setConfig:config];
    };

    [_controller configure:model];
}

API 速查

全局配置 API

实例配置 API

相关文件

完整API请参见API参考。

常见问题

全局配置和实例配置的执行顺序是什么？

全局配置在应用启动时（+setup 内）执行一次；实例配置在每次 configure: 时的 prepare 前执行。两者互不干扰。

如果不设置自定义配置会怎样？

AliPlayerKit 已内置最佳实践配置，不设置任何自定义配置即可正常使用，适合大多数场景。

实例配置回调中可以做异步操作吗？

不建议。回调是同步执行的，完成后才会继续执行 prepare。如果在回调中执行耗时操作，会阻塞播放器的启动流程。

可以在实例配置中修改视频源吗？

不建议。视频源在回调前已通过 setDataSource: 设置完成，在回调中修改可能导致不可预期的行为。实例配置回调应仅用于设置播放参数（如缓冲策略、Referer 等）。

setOnGlobalInitBlock: 在 +setup 之后调用会怎样？

不会生效。+setup 使用 dispatch_once 保证只执行一次，如果 Block 在 +setup 之后设置，将永远不会被触发。

日志配置应该在 setup 之前还是之后？

setLogLevel: 和 enableConsoleLog: 需在 +setup 之后调用，因为它们直接操作 LogHub 单例。而 setOnGlobalInitBlock: 必须在 +setup 之前设置。