PVAuthor开发指南

目 录

1 引言.... 4

2 架构概述.... 4

2.1 PVAuthor架构... 4

2.2 整体顺序图... 5

3 PVAuthor状态机.... 6

4 创建和打开会话.... 6

5 数据源.... 6

5.1 创建和增加数据源... 6

5.2 数据源配置... 7

6 文件格式组成.... 7

6.1 composer选择... 7

6.2 composer配置... 8

6.2.1 3GPP 和 MPEG4 composer. 8

6.2.2 AMR 和 AAC composer. 9

7 媒体音轨.... 9

7.1 增加媒体音轨... 9

7.2 编码器配置... 9

8 数据Sinks.. 9

9 通过扩展接口的附加功能.... 9

9.1 最大文件大小、持续时间和进度报告... 10

10 初始化和启动会话.... 11

11 暂停和恢复会话.... 12

12 停止会话.... 12

13 复位和关闭会话.... 12

14 功能查询和配置设置.... 13

14.1 PVAuthor引擎关键字符串... 13

14.2 节点级关键字符串... 13

15 PVAuthor引擎中的错误处理.... 14

1 引言

本文档为开发者使用PVAuthor 引擎 APIs指南。PVAuthor引擎客户端可以是一个应用程序或用于映射PVAuthor引擎接口到不同框架适配层或应用程序使用API层。本文档描述了怎样使用PVAuthor引擎接口及其创建、配置和控制多媒体authoring 会话。

PVAuthor 引擎作为PV多媒体框架（PVMF）的一部分，为客户端提供了多媒体录制功能。具有捕获音频、视频和文字媒体数据，将媒体数据编码成压缩格式，并将编码媒体数据多路输出到不同的文件格式中。输入媒体数据可以是实时源，像摄像机和话筒，或其它情况，如未编码的媒体数据文件。然后将输入数据编码成客户端选定的数据格式，其次从多路媒体数据中输出选定的文件格式。客户端把多路媒体数据写到数据输出上。

2 架构概述

2.1 PVAuthor架构

为了接收命令结束、状态信息和错误信息，客户端通过PVAutthorEngineInterface和执行PVAuthor引擎观看接口相互影响来控制PVAuthor引擎。 接口需要客户端为记录会话提供媒体数据源和sinks。数据源、sinks数目和类型的多样性取决于记录会话的特性。这些媒体源、sinks应该执行PVMFNodeInterface，允许PVAuthor引擎用统一的方法控制它们。通过PVAuthorEngineInterface执行客户端记录会话的控制。图1显示了PVAuthor引擎、客户端及其它目标之间的关系。图2显示了客户端操作类及其表示的属性列表。注意本文档在后面的顺序图中会涉及到这些属性列表。

图 1 PVAuthor的类图

图2客户端操作及其属性

2.2 整体顺序图

在本节中，图3显示的是API整体顺序调用设计和控制记录会话。在本文档的以下章节中会详细描述APIs的用法。

图3总体顺序图

图4总体顺序图续

3 PVAuthor状态机

PVAuthor引擎有六个状态：空闲、打开、初始化、记录、暂停和错误。为了从一个状态到另一个状态的转变，用户需要调用PVAuthorEngineInterface会话控制APIs。图5为状态转变图。

图5 PVAuthor 状态转变图

4 创建和打开会话

为了创建一个记录会话，客户端首先创建一个PVAuthor引擎对象。这步通过PVAuthorEngineFactory类中Create()方法来完成，将创建一个没有激活的记录会话PVAuthor引擎。为了打开一个会话，客户端需要调用PVAuthor引擎对象的Open()方法。图6显示了调用创建和打开一个记录会话的方法顺序。

图6创建和打开一个记录会话

5 数据源

5.1 创建和增加数据源

像上面章节提到的，客户端PVAuthor引擎需要创建媒体数据源对象，在编写会话中通过捕获源数据的AddDataSource()方法提供。媒体数据源对象是PVMF 节点，即围绕基本的驱动程序捕捉音频、视频和文本数据源。通常的办法是用媒体I/O接口和PvmfMediaInputNode集成数据源数据到PVAuthor引擎。请参考有关媒体I/O开发指南里的媒体I/O接口。图7显示了创建媒体数据源和提供它们给PVAuthor引擎的顺序。

图7创建媒体源并增加到PVAuthor引擎

5.2 数据源配置

除了创建数据源对象并增加它们到PVAuthor引擎外，客户端的任务还有配置数据源去捕捉需要的格式或属性源数据。选择有效配置取决于数据源节点执行和基本捕获设备的能力。请参考文档里数据源节点和有效的捕获设备部分。

6 文件格式组成

下一步设置记录会话为会话选择一个文件格式composer。PVMF框架通过PVAuthor引擎有效的提供多路编码媒体数据和格式化多路数据到期望的文件格式。客户端的任务是选择composer类型，并通过PVAuthor引擎提供的配置对象配置composer。

6.1 composer选择

PVAuthor引擎对象调用SelectComposer()方法完成composer选择。客户端将使用指定Mime类型composer，且指针指向PVAuthor引擎提供的配置对象。另外，如果此类信息提供给客户端，客户端可以指定UUID组成代替Mime类型。当方法异步完成，一个为选定composer不明确标志会返回给客户端的响应数据。客户端必须存储这个不明确的标志，必要时用它去标识PVAuthor引擎API调用选定的composer。图8显示了选择一个composer调用方法的顺序。

图8 composer选择

6.2 composer配置

composer配置通过author引擎从SelectComposer方法调用composer配置对象返回完成。配置接口实现的不同对象取决于composer的选择。客户端能检查配置对象调用配置对象的queryInterface方法对接口的支持。除非指定其它配置接口，客户端在SelectComposer完成之后调用配置方法。

6.2.1 3GPP 和 MPEG4 composer

如果客户端选择了3GPP或者MPEG4文件格式composer，返回配置对象实现PVMp4FFCNClipConfigInterface接口。客户端需要调用SetOutputFileName方法为authoring会话设置输出文件名。此外，如果客户端需要一个I-Motion格式文件，也要调用SetAuthoringMode方法。请参考在不同authoring模式下的author接口文档。下图显示了上面提到的调用顺序配置环境。

图 9 文件名和authoring模式配置

PVMp4FFCNClipConfigInterface也允许客户端增加额外的元数据信息到输出文件。以下图来说明增加元数据时调用顺序。请注意增加元数据是可选的，且数据增加与否不影响输出文件的有效性。

图10增加元数据字符串

目前，通过PVMp4FFCNClipConfigInterface支持下面的元数据。

a. 标题

b. 作者

c. 版权

d. 类型

e. 等级

f. 创建日期

g. 艺术家

h. 流派

i. 分类

j. 关键字

k. 地理信息.

6.2.2 AMR 和 AAC composer

当客户端选择一个AMR 或 AAC文件格式composer时，配置对象应该实现PvmfFileOutputNodeConfigInterface接口。客户端需要调用SetOutputFileName方法设置authoring会话输出文件名。请参阅图9的序列图。

7 媒体音轨

媒体文件，无论其格式，应至少有一个多媒体音轨。因此，为了构成一个有效的输出文件，客户端至少增加一个媒体音轨到文件格式composer。媒体音轨支持的最大数目和不同类型取决于选定的文件格式composer。为了创建一个多路媒体音轨文件，例如带H263视频和字幕的AMR音频音轨，客户端需要为每路音轨调用AddMediaTrack。

7.1 增加媒体音轨

通过调用AddMediaTrack方法完成增加媒体音轨。客户端需要提供指定的输入PVMF节点，此节点为媒体音轨提供源数据，MIME类型编码器用于编码源数据，增加文件格式composer里的媒体音轨。不明确的数据在SelectComposer需要CommandCompleted回调返回时确定文件格式composer。另外，如果此类信息提供给客户端，客户端可以指定Uuid编码器代替Mime类型。客户端也必须指定PVInterface指针指向保存选定编码器配置对象实例的指针。图11显示了增加一个媒体音轨调用顺序。

图11增加媒体音轨

7.2 编码器配置

编码器配置通过PVAuthor引擎中AddMediaTrack调用配置接口对象返回值实现 。不同对象的配置接口实现取决于选定的编码器。如果选定的编码器没有配置接口，将此指针设为NULL。如果输入节点提供编码源数据，PVAuthor引擎的媒体音轨没有编码器选择，则配置对象也置为NULL。客户端能检查配置对象时配置对象调用queryInterface方法所支持的接口。除非有另外的配置接口，客户端在AddMediaTrack调用完成后可以调用配置方法。

当客户端选择一个H263, MPEG4或AVC视频编码器时，配置对象应实现PVMp4H263EncExtensionInterface接口。请参考PVAuthor引擎接口文档有效选择接口部分。

8 数据Sinks

目前，PVAuthor仅支持3GPP/MPEG4, AMR 和 AAC文件格式composer节点.这些节点已经集成到文件IO，不需要客户端为PVAuthor引擎为它的输出数据而增加数据sink。客户端需要通过配置选定composer的接口设置输出文件名。

将来，文件格式支持无集成文件IO的节点，客户端需要调用AddDataSink方法指定特定数据输出节点，特定的文件格式composer必须写到输出上。

9 通过扩展接口的附加功能

除了功能和配置能有效的从PVAuthor引擎接口和Author引擎提供的配置对象获得外，附加功能也能有效的通过QueryUUID 和 QueryInterface方法得到。当这些方法有效时，允许PVAuthor引擎扩展和展现新功能给客户端。客户端能调用QueryUUID查询Mime类型指定的Uuid特定功能。使用Uuid，客户端能调用QueryInterface得到一个接口对象使用该功能。图12显示扩展接口调用查询的顺序。

图12扩展接口查询

9.1 最大文件大小、持续时间和进度报告

PVAuthor引擎有个功能是设置输出文件的最大值或输出文件最大的时间持续值。如果文件大小和持续时间的最大值设定， 当authoring 输出文件时，PVAuthor引擎将检查这些设置，并当值达到了指定的最大大小或者持续值 时，自动停止authoring会话。PVAuthor引擎配置周期性提供进度报告给客户端。以文件大小形式写入这些进度报告或当前输出文件持续时间。这些功能通过PvmfComposerSizeAndDurationInterface扩展接口实现。为了使用这些功能，客户端需要首先查询扩展接口实例，然后通过提供的接口配置PVAuthor引擎。图13显示了这些功能的顺序图。

图13最大文件大小、持续时间和进度报告配置

在authoring会话开始后，如果进度报告使能，PVAuthorEngine将发送信息事件给特定频率PVInformationalEventObserver会话的客户端。如果最大文件大小或持续功能使能，当文件大小或持续值到达指定的最大值时，停止会话并完成输出文件的写入，PVAuthorEngine将发送一个信息给客户端。图14显示如果最大文件值 、持续时间和进度报告功能使能，信息将发送到客户端。

图14进度报告、最大文件和持续时间信息化

10 初始化和启动会话

选择文件格式composer、增加所有的媒体音轨和配置所有的组件及编码器，设置会话之后，客户端初始化并开始authoring会话。一旦初始化，其它的会话设置authoring会话的环境和配置，除非PVAuthor引擎初始化或启动后特别指定的设置要修改。另外，为了修改设置和配置，客户端需要复位authoring会话和重启会话配置进度。PVAuthor引擎为会话分配资源，当初始化时，连接到数据源采集设备。PVAuthor引擎启动后，输入数据从不同的采集设备编码为要求的数据格式，格式化成要求的文件格式并写到文件里。图15显示初始化和开始authoring会话调用顺序。

图15初始化和启动authoring 会话

11 暂停和恢复会话

Authoring会话启动后，如果应用程序用户选择暂停或新的调用任务产生，客户端会暂停会话。当PVAuthor引擎处于暂停状态时，它将不会从采集设备处理任何新的输入数据。然而，在PVAuthor引擎暂停以前捕获到缓冲输入数据，PVAuthor引擎会继续处理数据并写入文件，直到缓冲输入为空。客户端能在会话成功暂停后任何时候恢复Authoring会话。恢复完成后，PVAuthor引擎将从采集设备恢复处理输入数据。图16显示了Authoring会话调用暂停和恢复顺序图。

图16暂停和恢复authoring 会话

12 停止会话

当会话启动或处于暂停状态时，调用停止方法，客户端会停止authoring会话。如果采集和PVAuthor引擎数据通道缓冲里的源数据未编码，默认行为是编码并增加它们到输出文件，因此所有采集到的媒体在会话停止以前会写入到输出文件。客户端收到停止调用前，这个行为会产生一个延时，取决于缓冲数量和设备电源。图17显示了authoring会话调用停止顺序。

图17停止authoring会话

13 复位和关闭会话

当PVAuthor引擎处于初始化、启动或暂停状态时，复位命令使PVAuthor引擎处于打开状态。如果调用SelectComposer或 AddMediaTrack 且PVAuthor引擎返回composer或媒体音轨的配置对象，客户端需要在复位调用前在配置对象上调用 removeRef 。如果PVAuthor引擎处于启动或暂停状态，它将首先停止authoring 会话。然后会话复位，并取消选定的会话composer和媒体音轨。然而，对于PVAuthor引擎，增加的数据源和sink节点仍有效。复位完成后，PVAuthor引擎返回到打开状态，客户端再一次调用SelectComposer 和AddMediaTrack设置会话。

为了关闭会话，客户端应该调用RemoveDataSource删除所有以前增加到PVAuthor引擎的数据源，然后调用关闭函数关闭会话。图18显示了复位和关闭会话的调用顺序。

图18复位和关闭authoring会话

14 功能查询和配置设置

PVAuthor 引擎采用PVMF 功能和配置设置接口 允许应用程序访问和修改引擎且节点设置不显示在author 接口上。请求UUID与接口关联的扩展接口(PvmiCapabilityAndConfig)通过播放API、QueryInterface()显示。利用返回的接口指针，应用程序能查询、核实和配置设置引擎和节点等级。在节点上，节点所使用的引擎必须支持功能和配置接口，以及节点设置可以访问应用程序。

功能和配置接口使用关键字符串PacketVideo扩展的MIME 字符串(PvXms)格式来指定感兴趣的设置。PvXms扩展了标准MIME字符串格式，允许附加级别的带斜杠分离的子类字符串。利用关键字符串增加了分析的复杂性，而允许灵活和可扩展的设置，在增加、删除或修改设置时，不用大大修改代码。除了指定的感兴趣的设置，关键字符串提供了有价值的键值对信息。

在关键字符串里的“type”参数告诉KVP使用者如果“type=value”，是否有一个有效值。在关键字符串里的“type”参数告诉KVP使用者什么类型的值是合适的联合成员可以在KVP中访问。

14.1PVAuthor引擎关键字符串

在PVAuthor引擎中所有的关键字符串以“x-pvmf/author”开头。

14.2节点级关键字符串

节点级关键字符串在PVAuthor引擎使用时有效取决于当时PVAuthor引擎使用PVMF节点和特殊节点关键字符串的支持。对于节点级关键字符串PVAuthor引擎扮演一个路由通往任何一个有适当请求的节点。当前，PVAuthor引擎完成一个核心的作用，从关键字串到特定节点的映射，而在将来，pvPlayer引擎和节点将决定在运行时使用注册机制完成映射。

当前，在PVAuthor引擎中使用关键字符串映射到节点，如下所示。

关键子字符串	节点类型
x-pvmf/video/render	视频编码节点
x-pvmf/audio/render	音频编码节点
fileio/	Composer节点
x-pvmf/file/output	文件输出节点
x-pvmf/media-io	媒体输入节点
x-pvmf/avc/encoder	AVC 编码

PVMF视频和音频编码节点关键字符串列表如下。当PVMF视频编码用于编码yuv bitstreams到mp4或3gp时，关键字符串允许设置与M4v, H.263 和 H.264视频编码成查询和修改一致。Amr编码器用关键字符串编码成pcm数据到mp4/3gp 文件。

Key Strings With Value Type	Description
x-pvmf/video/render/output_width;valtype=uint32	设置输出文件帧宽度
x-pvmf/video/render/output_height;valtype=uint32	设置输出文件帧高度
x-pvmf/audio/render/sampling_rate;valtype=uint32	设置音频流采样率
x-pvmf/audio/render/channels;valtype=uint32	设置视频流通道数
x-pvmf/avc/encoder/encoding_mode;valtype=uint32	设置编码模式

MP4 Composer节点关键字符串列表如下所示。

Key Strings With Value Type	Description
fileio/pv-cache-size	设置文件IO高速缓存大小. 此设置依赖于osclconfig_io.h 文件中PV文件缓存设置
fileio/presentation-timescale	为整个mpeg4显示设置时间量程。默认值为1000

15 PVAuthor引擎中的错误处理

PVAuthor 引擎对映射命令来自应用程序的请求或高等级多步骤和在PVAuthor引擎的控制下的一套节点/组件命令是很重要的。当处理一个特别应用请求出错或外部异步请求（例如：在已经启动后录音过程中发生错误）发生时可能产生错误。通过下面方法节点/组件附在PVAuthor引擎报告中：

1. HandleNodeErrorEvent 错误异步发生。

2. 处理一个特定的请求时NodeUtilCommandCompleted 错误发生。在PVAuthor 引擎处理一个应用程序请求时任何错误发生，PVAuthor将等待基本的节点/组件任何待定的命令，然后返回错误信息作为CommandComplete状态的一部分。如果错误发生在外部任何请求或应用程序命令时，调用HandleErrorEvent方法。收集的想法是在处理一个请求中，发生异步错误并在CommandComplete中送回，避免报告多次同样的错误。当它报告这些错误和应用程序调用复位时，PVAuthor 引擎传送错误状态，如13节所述。图 19和20 描述的是错误处理API顺序和流程图。

图19扩展错误信息

图20 PVAuthor错误处理流程图