Pvauthor Development Guide

Contents

1 Introduction... 4

2 Architecture Overview... 4

2.1 pvauthor architecture... 4

2.2 overall sequence chart... 5

3 pvauthor state machine... 6

4. Create and open a session... 6

5 Data Source... 6

5.1 create and add a data source... 6

5.2 data source configuration... 7

6 file format composition... 7

6.1 select composer... 7

6.2 composer configuration... 8

6.2.1 3GPP and MPEG4 composer. 8

6.2.2 AMR and aac composer. 9

7 media audio tracks... 9

7.1 add media audio tracks... 9

7.2 encoder configuration... 9

8 Data sinks... 9

9. Additional Functions of the Extended Interface... 9

9.1 maximum file size, duration, and progress report... 10

10 initialize and start a session... 11

11 pause and resume a session... 12

12 stop a session... 12

13 reset and close sessions... 12

14. Function query and configuration settings... 13

14.1 key strings of the pvauthor engine... 13

14.2 node-level key strings... 13

15 error handling in pvauthor engine... 14

1 Introduction

This document uses the pvauthor engine for developers.
APIS guide. The pvauthor engine client can be an application or used to map pvauthor engine interfaces to different framework adaptation layers or applications using the API layer. This document describes
How to Use the pvauthor engine interface and create, configure, and control multimedia authoring sessions.

Pvauthor
As a part of the PV Multimedia Framework (pvmf), the engine provides the multimedia recording function for the client. It can capture audio, video, and text media data, encode media data into compression formats, and encode Media
The object data is output to different file formats. Input media data can be real-time sources, such as cameras and microphones, or other situations, such as unencoded media data files. Encode the input data to
Data format, and then output the selected file format from the multi-media data. The client writes multiple media data to the data output.

2 Architecture Overview
2.1 pvauthor
Architecture

In order to receive command end, status information, and error information, the client uses pvautthorengineinterface and executes the pvauthor engine Viewing Interface to affect each other.
To control the pvauthor engine.
The client must provide media data sources and sinks for recording sessions. The diversity of data sources, sinks numbers, and types depends on the characteristics of record sessions. These media sources and sinks should be executed
Pvmfnodeinterface, which allows the pvauthor engine to control them in a unified way. Use pvauthorengineinterface to execute client logs
Session recording control. Figure 1 shows the relationship between the pvauthor engine, client, and other targets. Figure 2 shows the client operation class and its list of properties. Note that this document will
List of these attributes involved.

Figure 1 pvauthor class diagram

Figure 2 client operations and their attributes

2.2 overall sequence diagram

In this section, Figure 3 shows the overall API sequential call design and control record sessions. The following sections describe APIs usage in detail.

Figure 3 Overall sequence diagram

Figure 4 General sequence diagram continued

3 pvauthor
State Machine

The pvauthor engine has six statuses: idle, open, initialized, recorded, paused, and error. To change from one state to another, you need to call the pvauthorengineinterface session to control APIs. Figure 5 shows the status transition chart.

Figure 5 
Pvauthor status transition diagram

4. Create and open a session

To create a record Session, the client first creates a pvauthor engine object. This step uses the CREATE () method in the pvauthorenginefactory class
The method is complete. An Inactive record session pvauthor engine is created. To open a session, the client needs to call the open () method of the pvauthor engine object. Figure 6 show
The sequence of calling methods for creating and opening a record session.

Figure 6 create and open a record session

5 Data sources
5.1 create and add data sources

As mentioned above, the client pvauthor engine needs to create a media data source object, which is provided by capturing the adddatasource () method of the source data in the writing session. Media
The object of the data source is pvmf.
Node, that is, capturing audio, video, and text data sources around the basic driver. The common method is to use the media I/O interface and pvmfmediainputnode to integrate the data source
Pvauthor engine. See media I/O interfaces in the relevant media I/O Development Guide. Figure 7 shows the order in which media sources are created and provided to the pvauthor engine.

Figure 7 create a media source and add it to the pvauthor Engine

5.2 data source configuration

In addition to creating data source objects and adding them to the pvauthor engine, client tasks also configure data sources to capture the required format or Attribute source data. The selection of valid configurations depends on the ability of the data source node to execute and basically capture devices. See the data source nodes and valid Capture Devices section in the document.

6. File Format Composition

Next, set the record session to select a file format composer for the session. The pvmf framework uses the pvauthor engine to effectively provide multi-channel media data encoding and format multi-channel data to the expected file format. The task of the client is to select the composer type and configure composer through the configuration object provided by the pvauthor engine.

6.1 composer
Select

The pvauthor engine object calls the selectcomposer () method to complete the composer selection. The client uses the specified MIME type composer and
The Pointer Points to the configuration object provided by the pvauthor engine. In addition, if such information is provided to the client, the client can specify UUID to replace the MIME type. When the method is asynchronous, select
If the composer is not clear, the response data is returned to the client. The client must store this ambiguous identifier and use it to identify the selected
Composer. Figure 8 shows the sequence in which a composer call method is selected.

Figure 8 composer Selection

6.2 composer
Configuration

The composer configuration is completed by calling the composer configuration object from the selectcomposer method through the author engine. Different objects implemented by the configuration interface depend on
In composer. The client can check the support of the QueryInterface method of the configuration object to call the configuration object. Unless other configuration interfaces are specified
Call the configuration method after selectcomposer is completed.

6.2.1 3GPP
And MPEG4 composer

If the client selects the 3GPP or MPEG4 file format composer, return the configuration object to implement pvmp4ffcnclipconfiginterface
Port. The client needs to call the setoutputfilename method to set the output file name for the authoring session. In addition, if the client needs an I-Motion
To call the setauthoringmode method. See the author interface documentation in different authoring modes. Displays the Call Sequence configuration ring mentioned above.
Environment.

Figure 9 file name and authoring mode configuration

Pvmp4ffcnclipconfiginterface also allows the client to add additional metadata information to the output file. The Call Sequence for Adding metadata. Note that Adding metadata is optional, and whether or not the data is added does not affect the validity of the output file.

Figure 10 Add a metadata string

Currently, the following metadata is supported through pvmp4ffcnclipconfiginterface.

A. Title

B. Author

C. Copyright

D. Type

E. Level

F. Date of creation

G. Artist

H. Genre

I. Category

J. Keyword

K. geographic information.

6.2.2 Amr
And AAC composer

When the client selects an AMR or
When the AAC file format is composer, the configuration object should implement the pvmffileoutputnodeconfiginterface interface. The client needs to call
The setoutputfilename method sets the name of the output file of the authoring session. See the sequence diagram in Figure 9.

7. Media audio streams

A media file, regardless of its format, should have at least one multimedia audio track. Therefore, to form a valid output file, the client must add at least one media track to the file format composer. Media
The maximum number and type of audio tracks supported depends on the selected file format composer. To create a multi-media audio track file, such as an AMR audio track with h263 video and subtitles, the client
Addmediatrack needs to be called for each audio track.

7.1 add media audio tracks

Call addmediatrack to add media audio streams. The client needs to provide the specified input pvmf node, which provides source data and Mime Type encoding for media audio streams.
It is used to encode source data and add media audio tracks in the file format composer. Ambiguous data requires commandcompleted callback in selectcomposer
Determine the file format composer when returning. In addition, if such information is provided to the client, the client can specify the uuid encoder instead of the MIME type. The client must also specify
The pvinterface Pointer Points to the pointer that saves the selected encoder configuration object instance. Figure 11 shows how to add a media track call sequence.

Figure 11 Add a media track

7.2 encoder Configuration

Encoder configuration is implemented through addmediatrack in the pvauthor engine to call the configuration interface object return value.
. The implementation of configuration interfaces for different objects depends on the selected encoder. If no interface is configured for the selected encoder, set this pointer to null. If the input node provides the encoding source data, the pvauthor Engine
If no encoder is selected, the configuration object is set to null. When the client can check the configuration object, the configuration object calls the interfaces supported by the QueryInterface method. Unless there is another
Configuration interface. After addmediatrack is called, the client can call the configuration method.

When the client selects an h263, MPEG4, or AVC Video Encoder, the configuration object must implement the pvmp4h263encextensioninterface interface. See the effective selection interface section in the pvauthor engine interface documentation.

8. Data sinks

Currently, pvauthor only supports the 3GPP/MPEG4, Amr, and aac file format composer nodes. these nodes have been integrated into file I/O, and the client does not need to add data sinks for the output data of the pvauthor engine. The client needs to set the output file name through the interface for configuring the selected composer.

In the future, the file format supports nodes without integration file I/O. The client needs to call the adddatasink method to specify a specific data output node. The specific file format composer must be written to the output.

9. Additional Functions of the Extended Interface

In addition to the functions and configurations that can be effectively obtained from the pvauthor engine interface and the configuration objects provided by the author engine, the additional functions can also be effectively obtained through the queryuuid and
Obtain the QueryInterface method. When these methods are effective, the pvauthor engine is allowed to expand and present new features to the client. The client can call queryuuid to query
The UUID-specific function specified by the MIME type. With UUID, the client can call QueryInterface to obtain an interface object. Figure 12 query of extended API calls
.

Figure 12 Extended Interface Query

9.1 maximum file size, duration, and progress report

The pvauthor engine has the function of setting the maximum value of the output file or the maximum duration of the output file. If the maximum file size and duration are set
When the file is output, the pvauthor engine checks these settings and when the value reaches the specified maximum size or duration value
The authoring session is automatically stopped. The pvauthor engine provides periodic progress reports to clients. Write the progress report or the duration of the current output file in the form of file size. This
Some functions are implemented through the pvmfcomposersizeanddurationinterface extension interface. To use these functions, the client first needs to query the Extended Interface
For example, configure the pvauthor engine through the provided interface. Figure 13 shows the order of these features.

Figure 13 maximum file size, duration, and progress report configuration

After the authoring session starts, if the progress report is enabled, pvauthorengine sends an information event to a specific frequency.
The client of the pvinformationaleventobserver session. If the maximum file size or persistence function is enabled, stop when the file size or duration value reaches the specified maximum.
Session and write the output file. pvauthorengine sends a message to the client. Figure 14 shows the maximum file value
The duration and progress report feature enable and send the information to the client.

Figure 14 informatization of progress reports, maximum files, and duration

10 initialize and start a session

Select the file format composer, add all media tracks, and configure all components and encoders. After the session is set, the client initializes and starts the authoring session. Once
Other sessions, unless the settings specified after pvauthor engine initialization or startup are modified. In addition, to modify the settings and configurations
You need to reset the authoring session and restart the session configuration progress. The pvauthor engine allocates resources for sessions and connects to the data source collection device during initialization. Pvauthor Engine Startup
The input data is encoded as the required data format from different collection devices, formatted into the required file format, and written into the file. Figure 15 shows the sequence of initialization and start authoring Session calls.

Figure 15 initialize and start an authoring session

11 pause and resume a session

After the authoring session is started, the client suspends the session if the application selects to suspend or a new call task is generated. When the pvauthor engine is paused, it does not
Process any new input data from the collection device. However, the pvauthor engine captures buffered input data before the pvauthor engine is suspended. The pvauthor engine continues to process the data and writes the data to the file until the data is buffered.
The input is empty. The client can resume the authoring session at any time after the session is successfully paused. After the recovery is complete, the pvauthor engine restores the input data from the collection device. Figure 16 shows
Authoring session call pause and Resume sequence diagram.

Figure 16 pause and resume an authoring session

12. Stop a session

When a session is started or paused, the client stops the authoring session by calling the stop method. If the source data in the data channel buffer of the collection and pvauthor engine is not encoded,
The default behavior is encoding and adding them to the output file. Therefore, all the collected media will be written to the output file before the session is stopped. Before the client receives the Stop call, this behavior will produce a latency, depending on the buffer
Quantity and device power supply. Figure 17 shows the sequence in which the authoring session call stops.

Figure 17 stop an authoring session

13 reset and close sessions

When the pvauthor engine is in the initialization, startup, or pause state, the reset command puts the pvauthor engine in the open state. If selectcomposer or
Addmediatrack and the pvauthor engine returns the configuration object of the composer or media track. The client needs to call the configuration object before the Reset Call.
Removeref. If the pvauthor engine is in the enabled or paused state, it will first stop authoring
Session. Then reset the session and cancel the selected session composer and media track. However, for the pvauthor engine, the added data source and sink node are still valid. Reset complete
The pvauthor engine returns to the open state, and the client calls selectcomposer and addmediatrack again to set the session.

To close the session, the client should call removedatasource to delete all data sources that were previously added to the pvauthor engine, and then call the function to close the session. Figure 18 shows the Call Sequence for resetting and disabling sessions.

Figure 18 reset and close an authoring session

14. Function query and configuration settings

The pvauthor engine uses the pvmf function and Configuration Setting interface to allow applications to access and modify the engine, and node settings are not displayed in the author
Interface. The requested extended interface (pvmicapabilityandconfig) associated with the uuid is displayed through the playback API and QueryInterface.
The returned interface pointer allows the application to query, verify, and configure the engine and node level. On a node, the engine used by the node must support functions and configuration interfaces, and the node settings can access the application
.

The function and configuration interface use the mime extended by the key string packetvideo
String (pvxms) format to specify the settings of interest. Pvxms extends the standard mime string format and allows additional levels of sub-class strings separated by slashes. Added the score using the key string
The complexity of analysis, and flexible and scalable settings are allowed. When adding, deleting, or modifying settings, you do not need to greatly modify the code. In addition to the specified settings of interest, Key Strings provide valuable key-value pairs.

The "type" parameter in the key string tells kVp whether there is a valid value if "type = value" is used. The "type" parameter in the key string tells kVp users what type of value is suitable for federated members to access in kVp.

14.1 pvauthor
Key engine strings

All key strings in the pvauthor engine start with "X-pvmf/author.

14.2 node-level key strings

Key Strings at the node level are used by the pvauthor engine at that time, depending on the support of pvmf nodes and special node Key Strings used by the pvauthor engine. For node-level keywords
The pvauthor engine acts as a route to any node with proper requests. Currently, the pvauthor engine completes a core function, from the string of keywords to the ing of specific nodes.
In the future, the pvplayer engine and nodes will decide to use the registration mechanism to complete the ing at runtime.

Currently, Key Strings are mapped to nodes in the pvauthor engine, as shown below.

Key substring	Node Type
X-pvmf/Video/render	Video Encoding Node
X-pvmf/Audio/render	Audio Encoding Node
Fileio/	Composer Node
X-pvmf/file/Output	File output Node
X-pvmf/media-io	Media input node
X-pvmf/AVC/Encoder	AVC Encoding

The key strings of the pvmf Video and Audio Encoding nodes are listed below. When pvmf video encoding is used to encode YUV
When bitstreams to MP4 or 3GP, the key string can be set with m4v, H.263, and
H.264 video encoding is consistent with query and modification. The AMR encoder uses key strings to encode PCM data into MP4/3GP files.

Key Strings with Value Type	Description
X-pvmf/Video/render/output_width; valtype = uint32	Set the frame width of the output file.
X-pvmf/Video/render/output_height; valtype = uint32	Set the frame height of the output file
X-pvmf/Audio/render/sampling_rate; valtype = uint32	Set audio stream Sampling Rate
X-pvmf/Audio/render/channels; valtype = uint32	Set the number of video stream channels
X-pvmf/AVC/encoder/encoding_mode; valtype = uint32	Set encoding Mode

The following lists the key strings of MP4 composer nodes.

Key Strings with Value Type	Description
Fileio/PV-Cache-size	Sets the file I/O cache size. This setting depends on the PV file cache settings in the osclconfig_io.h file.
Fileio/presentation-timescale	Set the time range for the entire MPEG4 display. The default value is 1000.

15 pvauthor
Engine error handling

Pvauthor
The engine is very important to map commands from application requests or high-level multi-steps and a set of node/component commands under the control of the pvauthor engine. When an error or external exception occurs when processing a special application request
An error may occur when a step Request (for example, an error occurs during the recording process after startup) occurs. Add the node/component to the pvauthor engine report using the following method:

1. handlenodeerrorevent errors occur asynchronously.

2. The nodeutilcommandcompleted error occurs when a specific request is processed. In pvauthor
If an error occurs when the engine processes an application request, pvauthor waits for any unknown command from the basic node/component and returns the error message as commandcomplete.
Status. If the error occurs in any external request or application command, call the handleerrorevent method. The idea is to handle an asynchronous error in a request and
Return a message in commandcomplete to avoid multiple similar errors. When it reports these errors and the application calls reset, pvauthor
Engine transfer error status, as described in section 13. Figures 19 and 20 describe the sequence and flowchart of the error handling API.

Figure 19 extended error message

Figure 20 pvauthor error handling Flowchart

Http://blog.csdn.net/mtv0312/archive/2011/05/10/6408936.aspx