使用 CompositionPlayer 预览编辑内容

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

什么是 CompositionPlayer？

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

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

CompositionPlayer 与 ExoPlayer 的比较

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

从本质上讲，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 方法控制播放器。

错误处理

将 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 代码库中提交 问题。