使用 CompositionPlayer 预览编辑内容

Jetpack Media3 库提供了 CompositionPlayer API，这是一种强大的 Player 实现，可用于实时预览视频编辑。 如果您的应用允许用户编辑视频（例如应用效果、剪辑或合成多个输入媒体项），CompositionPlayer 可帮助您显示准确的输出预览。在您不需要保存应用的编辑内容，或者在将编辑内容提交到最终视频以供导出之前验证编辑内容是否按预期配置的情况下，此功能非常有用。

注意： CompositionPlayer 处于早期预览阶段。这意味着该 API 可能会发生变化，我们正在积极开发该 API 以便在未来进行增强。因此，它被注释为 @ExperimentalApi ，您需要选择启用opt-in才能使用。

什么是 CompositionPlayer？

CompositionPlayer 是 Player 接口的专用实现，专门用于播放 Composition 对象。 Composition 定义了输入媒体素材资源（例如视频片段和音轨）的排列方式，以及应向其应用哪些音频和视频效果。如需详细了解 Composition API，请参阅定义媒体项的Composition。

CompositionPlayer 的主要目的是实时呈现此 Composition，并包含所有指定的编辑内容，让用户在提交可能耗时且耗费资源的导出过程之前，准确了解编辑内容的效果。然后，可以将同一 Composition 对象与 Transformer 实例一起用于导出，如需了解详情，请参阅导出 Composition。

CompositionPlayer 与 ExoPlayer 的比较

虽然 CompositionPlayer 和 ExoPlayer 都是 Player 实现 在 Media3 中，但它们针对不同的用例进行了优化：

功能	CompositionPlayer	ExoPlayer
输入媒体	接受单个 Composition 对象，该对象可以包含多个 EditedMediaItem 实例，每个实例都有自己的效果。	接受单个 MediaItem 或 MediaItem 实例的 播放列表。
时间轴	时间和时长基于整个 Composition。	时间和时长与正在播放的 MediaItem 相对应。
效果	效果在 Composition 中定义，可以应用于单个 EditedMediaItem 或整个 Composition。	效果在 ExoPlayer 实例本身上使用 setVideoEffects() 设置，并且每个效果都会单独应用于播放列表中的每个项。

从本质上讲，CompositionPlayer 当您需要呈现 复杂的 Composition 媒体和效果（通常在编辑上下文中）时，最有用。使用 ExoPlayer 进行音频或视频内容的一般播放，或使用 setVideoEffects() 预览单素材资源编辑。

用于预览的 CompositionPlayer

将 CompositionPlayer 集成到您的应用中涉及几个关键步骤。首先， 使用构建器模式实例化 CompositionPlayer，然后设置要播放的 Composition：

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()
CompositionPlayer.kt

如需有关如何创建 Composition 的指导，请参阅 创建 Composition 部分。

请注意，由于 CompositionPlayer 实现的是 Player 接口，因此您可以 然后 设置目标输出 并 通过标准 Player 方法控制播放器。

重要提示 ：必须从单个应用 线程访问 CompositionPlayer。默认情况下，这是创建播放器的线程的 Looper，或者如果创建线程没有 Looper，则是应用的主线程。 如需了解详情，请参阅关于线程处理的注意事项。

错误处理

将 Player.Listener 实例附加到您的 CompositionPlayer，以响应 播放事件和错误。The onPlayerError() 回调还会 显示来自编辑专用组件（例如 Composition 或 VideoGraph.Factory）的任何问题。如需了解详情，请参阅播放器事件 文档。

重要注意事项

使用 CompositionPlayer 时需要注意的一些功能和限制：

• 虽然 CompositionPlayer 基于 Player 接口，但由于它依赖于 Composition 进行播放，因此其某些 行为与 ExoPlayer 不同。例如，CompositionPlayer 仅支持将重复模式 设置为 REPEAT_MODE_OFF 或 REPEAT_MODE_ALL。
• 默认情况下，CompositionPlayer 使用 SingleInputVideoGraph.Factory，但如果您的 Composition 使用多个包含图片或视频项的序列，则在构建您的 CompositionPlayer 实例时，您应使用 setVideoGraphFactory() 来改为使用 MultipleInputVideoGraph.Factory。如果只有一个序列包含图片或视频项，而其他序列仅包含音频，则 SingleInputVideoGraph.Factory 就足够了。
• Composition 中的所有媒体项都应明确设置时长， 对于图片，使用 MediaItem.Builder.setImageDurationMs() 设置时长；对于音频或视频，使用 EditedMediaItem.Builder.setDurationUs() 设置时长。

支持以下应用场景：

• 单素材资源预览。
• 单序列（即按顺序排列的媒体项）预览。
• 单个视频序列 + 单个音频序列（例如背景音频）预览。

以下用例正在积极开发中：

• 多素材资源预览，包括画中画、并排和网格等布局，其中涉及多个视频序列。
• 使用不同的图形引擎自定义编辑流水线。

功能请求

如果您有任何功能请求或反馈要提供给 CompositionPlayer，请在 Media3 GitHub 代码库中提交 问题。