本文为您介绍播放器 SDK 的常见问题。

License 常见问题

如何申请测试 License？

详情请见申请免费测试 License。

Android 和 iOS 可以共用一个 License 吗？

可以，双端支持共用一个 License。

License 到期后如何延期？

续期指充值 License 的可用时间。

• 测试版 License 默认一个月到期，需要重新申请新的测试 License。
• 正式版 License 直接单击续期按钮即可。

License 鉴权哪几个信息？

鉴权需要鉴别 AppId、包名、有效期，集成时需要确认这几个信息与视频点播控制台上 License 是否一致，任何信息不一致都会鉴权失败。

Android SDK

播放有声无画时，如何解决？

请检查 TextureView/SurfaceView 的 Surface 是否成功设置 TTVideoEngine 实例。

Android SDK 处理音频焦点吗？

播放器 SDK 内部不处理音频焦点，接入方需监听 AudioManager.OnAudioFocusChangeListener 来处理音频焦点的获取和释放。详情请见官方文档音频焦点。

如何调节显示 view 大小？

提供 DisplayMode 接口，详情请见调节显示view大小。

如何根据日志判断是否降级系统播放器？

您可通过检索如下关键字进行判断：

• 如果检索到 ownplayer，那么用的是火山引擎视频点播的播放器。
• 如果检索到 sysplayer，那么说明降级到了系统播放器。

iOS SDK

开启预加载后没有效果，如何解决？

• 请确认预加载是否生效，详情请见明确播放时是否命中预加载。
• 是否降级到系统播放器，需要输出日志进行分析。您可通过检索如下关键字进行判断：
  • 如果检索到 ownplayer，那么用的是火山引擎视频点播的播放器。
  • 如果检索到 sysplayer，那么说明降级到了系统播放器。

如何 Seek 到视频最后一帧？

具体请见 Seek 到最后一帧。

如何让视频在静音模式下依然有声音？

问题表现

在 iOS 设备上，当用户通过侧边的物理按键将手机设置为静音模式后，使用播放器 SDK 播放的视频内容也随之静音，无法发出声音。

问题原因

iOS 通过 AVAudioSession 来管理整个 App 的音频行为。默认情况下，App 的音频会话类别（Category）是 AVAudioSessionCategorySoloAmbient，这个类别会遵循系统静音开关。当用户开启静音模式时，系统会中断遵循此规则的音频播放。播放器 SDK 作为 App 内的一个模块，会继承 App 全局的音频会话设置。因此，如果 App 未更改默认设置，播放器就会表现出静音的行为。要改变这一行为，需要由 App 主动配置其音频会话。

解决方案

您需要在 App 的适当位置（例如，在 App 启动时或播放器初始化前），通过系统 API 设置 AVAudioSession 的类别为 AVAudioSessionCategoryPlayback，告知 iOS 系统 App 正在进行核心的音频播放，即使用户开启了静音模式，也应继续播放声音。播放器 SDK 本身不提供 API 来控制此行为。关于 AVAudioSession 的详细信息，请参阅 Apple 官方文档：AVAudioSession。示例代码：

#import <AVFoundation/AVFoundation.h>

- (void)setupAudioSession {
    NSError *categoryError = nil;
    // 设置音频会话类别为 AVAudioSessionCategoryPlayback，这会让音频在静音模式下也能播放
    [[AVAudioSession sharedInstance] setCategory:AVAudioSessionCategoryPlayback error:&categoryError];
    
    NSError *activationError = nil;
    // 激活音频会话
    [[AVAudioSession sharedInstance] setActive:YES error:&activationError];
    
    if (categoryError || activationError) {
        NSLog(@"Error: Failed to set up AVAudioSession.");
    }
}

画中画 (PiP) 模式下 seek 或切换视频后黑屏或画面卡住怎么办？

问题表现

在 iOS 设备上，当视频进入画中画模式后，如果用户执行了 seek 操作拖动进度条或切换到另一个视频，可能会出现以下现象：

• 视频画面定格在操作前的最后一帧，不再更新。
• 视频画面直接黑屏。
• 音频可能仍在正常播放，但画面已停止渲染。

解决方案

对于该问题解决方案是在进入画中画模式时，通过 SDK 提供的全局设置，显式地告知播放器在后台模式下继续保持渲染激活状态；在退出画中画模式后，再恢复默认行为以避免不必要的性能开销。

示例代码：

#pragma mark - AVPictureInPictureControllerDelegate
- (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController {
    // 即将进入画中画模式，打开该开关
    // 1.47.3 及以后版本
    [TTVideoEngine setGlobalForKey:VEGSKeyEnableBackgroundMode value:@(1)];
    // 1.47.3 以前的版本（不含 1.47.3）
    [TTVideoEngine setGlobalForKey:VEGSKeyIgnoreGlActive value:@(1)];
}

- (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController
failedToStartPictureInPictureWithError:(NSError *)error {
    // 启动画中画失败，关闭该开关
    // 1.47.3 及以后版本
    [TTVideoEngine setGlobalForKey:VEGSKeyEnableBackgroundMode value:@(0)];
    // 1.47.3 以前的版本（不含1.47.3）
    [TTVideoEngine setGlobalForKey:VEGSKeyIgnoreGlActive value:@(0)];
}

- (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController
failedToStartPictureInPictureWithError:(NSError *)error {
    // 已经退出画中画模式，关闭该开关
    // 1.47.3 及以后版本
    [TTVideoEngine setGlobalForKey:VEGSKeyEnableBackgroundMode value:@(0)];
    // 1.47.3 以前的版本（不含 1.47.3）
    [TTVideoEngine setGlobalForKey:VEGSKeyIgnoreGlActive value:@(0)];
}

Web SDK

Web 端播放器是否区分基础版和高级版？

区分。自 2025 年 3 月 20 日起，Web 播放器 SDK 将分为以下两个版本实行收费：

• 基础版：提供核心播放功能，满足基本业务需求。
• 高级版：在基础版之上，提供更丰富的功能与优化体验，如预加载、H.265 策略、动态 Buffer、多码率自适应播放 (ABR) 等。

自 1.11.0 版本起，集成 Web 播放器 SDK 时，您必须获取并配置 License，才可使用播放器 SDK。具体操作请见集成 SDK。如果您使用的是 1.11.0 之前的版本，虽然不受此次变更影响，但我们建议您升级到最新版，以享受更全面的服务和支持。

iOS 端嵌入 Web 页面，为什么切换全屏后降级到系统播放器？

• 问题原因：iOS 端不支持全屏，切换全屏会默认降级到系统播放器。

• 解决方案：禁用全屏按钮，启用网页全屏，用 cssFullscreen 插件代替 fullscreen 插件。示例代码如下：

  const playerSdk = new VePlayer({
    //...
    fullscreen: {
      useCssFullscreen: true, 
    },
  });
  

  说明

  useCssFullscreen 参数说明请见 IFullscreenConfig。

iOS 端嵌入 Web 页面，无法播放 MP4 格式的 DRM 加密视频？

• 如果是移动 Web 端，建议使用 HLS 加密播放。
• iOS 系统不支持使用 MSE (Media Source Extensions)，也就是不支持播放加密 DASH 和加密 MP4。

Web SDK 如何上报日志？

需要在实例化播放器时，通过设置 vodLogOpts 参数来配置播放质量上报，详情请见步骤 4：实现播放质量上报。