Atlas 200DK V100R020C10. Media API Reference. Issue 01 Date HUAWEI TECHNOLOGIES CO., LTD.

(1)

V100R020C10

Media API Reference

Issue 01

Date 2021-03-24

(2)

No part of this document may be reproduced or transmitted in any form or by any means without prior written consent of Huawei Technologies Co., Ltd.

Trademarks and Permissions

and other Huawei trademarks are trademarks of Huawei Technologies Co., Ltd.

All other trademarks and trade names mentioned in this document are the property of their respective holders.

Notice

The purchased products, services and features are stipulated by the contract made between Huawei and the customer. All or part of the products, services and features described in this document may not be within the purchase scope or the usage scope. Unless otherwise specified in the contract, all statements, information, and recommendations in this document are provided "AS IS" without warranties, guarantees or representations of any kind, either express or implied.

The information in this document is subject to change without notice. Every effort has been made in the preparation of this document to ensure accuracy of the contents, but all statements, information, and recommendations in this document do not constitute a warranty of any kind, express or implied.

(3)

1 Introduction... 1

2 Media Library APIs... 2

2.1 Overview... 2

2.2 MediaLibInit... 3

2.3 IsChipAlive...3

2.4 QueryCameraIds... 4

2.5 QueryCameraStatus...5

2.6 OpenCamera... 6

2.7 SetCameraProperty... 7

2.8 GetCameraProperty... 8

2.9 CapCamera... 9

2.10 ReadFrameFromCamera... 11

2.11 CloseCamera... 12

2.12 QueryMICStatus... 13

2.13 OpenMIC... 13

2.14 SetMICProperty... 14

2.15 GetMICProperty...16

2.16 CapMIC...17

2.17 ReadMicSound... 19

2.18 CloseMIC... 20

3 Appendix...21

3.1 Example... 21

(4)

1 Introduction

The Media module is an API media library that helps developers easily obtain camera-captured images and audio data. The media library runs at the application layer of the OS which is powered by the Ascend AI Processor on the Atlas 200 DK developer board. Video streams and audio streams in various formats can be easily obtained by calling API functions. These APIs also allow you to easily control the operating modes of the cameras and microphones (MICs) on the Atlas 200 DK developer board and query their operating status and various supported

parameters.

The Media module can:

1. Initialize the media library.

2. Control media devices, including enabling and disabling cameras and MICs and setting parameters for operating, such as the frame rate, resolution, and audio sampling rate.

3. Query the supported operating modes and current running status of media devices, such as the supported resolution and the online status of cameras.

4. Collect audio and video streams and process raw audio and video data based on the algorithms required by users.

(5)

2 Media Library APIs

2.1 Overview 2.2 MediaLibInit 2.3 IsChipAlive 2.4 QueryCameraIds 2.5 QueryCameraStatus 2.6 OpenCamera 2.7 SetCameraProperty 2.8 GetCameraProperty 2.9 CapCamera

2.10 ReadFrameFromCamera 2.11 CloseCamera

2.12 QueryMICStatus 2.13 OpenMIC 2.14 SetMICProperty 2.15 GetMICProperty 2.16 CapMIC

2.17 ReadMicSound 2.18 CloseMIC

2.1 Overview

The APIs of the Media module are based on the C language. The following describes each API in detail.

(6)

Find the API definitions in the driver/peripheral_api.h file extracted from the A200dk-npu-driver-{software version}-ubuntu18.04-aarch64-minirc.tar.gz package.

2.2 MediaLibInit

Initializes the internal status of the media library. This API must be called before you call the media library function.

Function Prototype

int MediaLibInit()

Arguments

Argument Description Value Range

- - -

Returns

For details about the returned error codes, see the Error Code column in Error Codes.

Error Codes

True Value Error Code Description

0 LIBMEDIA_STATUS_FAIL

ED The media library fails to be

initialized.

1 LIBMEDIA_STATUS_OK The media library is successfully initialized.

2.3 IsChipAlive

Checks whether Hi3559 is properly connected with Ascend 310 on the Atlas DK developer board.

Function Prototype

int IsChipAlive(char* chipName)

(7)

Arguments

chipName Name of the chip

interconnected with Ascend 310 Currently, only Hi3559 is

supported.

The value is 3559.

Returns

Error Codes

ED The interconnection with Hi3559

fails.

1 LIBMEDIA_STATUS_OK The interconnection with Hi3559 is normal.

2.4 QueryCameraIds

Queries the available camera channel IDs on the Atlas DK developer board.

Currently, the developer board supports a maximum of two cameras at the same time.

Function Prototype

uint32_t QueryCameraIds(int* cameraIds, uint32_t *count)

(8)

Arguments

cameraIds Array for storing the

query result An array with the size of at least 2 x sizeof(int) should be provided to save the returned result.

NOTEIf the size of the user- provided array exceeds the actual number of cameras, the function sets the invalid ID to –1. The valid ID is 0 or 1.

count Number of IDs that can

be contained in the cameraIds array space

[1,2]

Returns

Error Codes

0 LIBMEDIA_STATU

S_FAILED The query fails.

1 LIBMEDIA_STATU

S_OK The query is successful.

2.5 QueryCameraStatus

Queries the current operating status of the camera with a specified ID.

Function Prototype

enum CameraStatus QueryCameraStatus(int cameraId)

Arguments

cameraId Specified camera ID [0, 1]

(9)

Returns

Error Codes

1 CAMERA_STATUS_

OPEN The camera is opened.

2 CAMERA_STATUS_C

LOSED The camera is closed.

3 CAMERA_NOT_EXIS

TS The camera does not exist.

4 CAMERA_STATUS_U

NKOWN The camera status is unknown.

2.6 OpenCamera

Opens a camera. You need to open the camera before performing related operations.

Function Prototype

int OpenCamera(int cameraId)

Arguments

Returns

Error Codes

0 LIBMEDIA_STATUS_FA

ILED The camera fails to be opened.

1 LIBMEDIA_STATUS_O

K The camera is successfully

opened.

(10)

2.7 SetCameraProperty

Sets and modifies the properties of a specified camera.

Function Prototype

int SetCameraProperty(int cameraId, enum CameraProperties prop, const void* pInValue)

Arguments

Argument Description Value Range cameraId Specified

camera ID [0, 1]

prop Type of a

camera property

Only the following properties are supported:

enum CameraProperties {

CAMERA_PROP_RESOLUTION =1, // [Read/Write]

Image resolution of the camera. The data type is CameraResolution and the length is 1.

CAMERA_PROP_FPS =2, // [Read/Write] Frame rate. The data type is uint32_t. The value ranges from 1 fps to 20 fps.

CAMERA_PROP_CAP_MODE =5, // [Read/Write]

Frame obtaining mode: active or passive. The data type is CameraCapMode.

};

pInValue Value of a

property See the preceding description. Each property has its own structure. Pay attention to the input data type.

Returns

Error Codes

ED Camera properties fail to be set.

(11)

1 LIBMEDIA_STATUS_OK Camera properties are

successfully set.

CameraResolution

● Function: Specifies the resolution of the image captured by the camera.

● Member description

Member Type Description

width int Image width

height int Image height

● Definition prototype

struct CameraResolution { int width;

int height;

};

● Value range

The following resolutions are supported: 1920 x 1080, 1280 x 720, 704 x 576, 704 x 288, and 352 x 288.

CameraCapMode

● Function: Specifies the mode in which the camera obtains data.

● Value range

enum CameraCapMode

{ CAMERA_CAP_ACTIVE = 1, // Active mode CAMERA_CAP_PASSIVE = 2, // Passive mode };

2.8 GetCameraProperty

Obtains the value of the specified property of a camera.

Function Prototype

int GetCameraProperty(int cameraId, enum CameraProperties prop, void*

pValue)

Arguments

Argument Description Value Range cameraId Specified

camera ID 0~1

(12)

prop Type of a

camera property

Only the following properties are supported:

enum CameraProperties {

CAMERA_PROP_RESOLUTION =1, // [Read/

Write] Image resolution of the camera. The data type is CameraResolution and the length is 1.

CAMERA_PROP_FPS =2, // [Read/Write] Frame rate. The data type is uint32_t. The value ranges from 1 fps to 20 fps.

CAMERA_PROP_SUPPORTED_RESOLUTION

=4, // [Read] List of resolutions supported by the camera. The data type is

CameraResolution, and the array length is HIAI_MAX_CAMERARESOLUTION_COUNT:

25.

CAMERA_PROP_CAP_MODE =5, // [Read/

Write] Frame obtaining mode: active or passive. The data type is CameraCapMode.

};

pInValue Value of a

property See the preceding description. Each property has its own structure. Pay attention to the input data type.

Returns

Error Codes

0 LIBMEDIA_STATUS_FAI

LED Camera properties fail to be

obtained.

1 LIBMEDIA_STATUS_OK Camera properties are

successfully obtained.

2.9 CapCamera

Captures camera image data using the callback function. A callback function has to be provided for the media library. If images are generated at the bottom layer, the callback function will be called by the underlying thread of the media library.

(13)

You are advised to copy the image data to the specified buffer in the callback function for the subsequent processing.

Function Prototype

int CapCamera(int cameraId, CAP_CAMERA_CALLBACK , void* param)

Arguments

The following table describes the arguments of the CapCamera function.

CAP_CAMERA_CALLBACK Callback function used to receive data.

The format of the callback function is as follows:

typedef int

(*CAP_CAMERA_CALLBA CK) (const void* pdata, int size, void* param)

Valid address of a callback function

param User-defined callback

parameter After receiving the image data, the media library returns this parameter to the user through the callback function.

The following table describes the arguments of the callback function.

pdata Address of a frame of

image data This buffer is maintained by the media library and is read-only to users.

Users themselves cannot release the memory that the address points to.

Otherwise, exceptions may occur.

size Image data size The value varies

according to the image format and resolution.

(14)

parameter After receiving the image data, the media library returns this parameter to the user through the callback function.

Returns

Error Codes

ILED Image data fails to be captured.

1 LIBMEDIA_STATUS_O

K Image data is captured

successfully.

2.10 ReadFrameFromCamera

Reads the image data returned by cameras in a user thread. Note that this function returns values only after it receives image data. The user is responsible for providing a buffer for receiving image data. After receiving the complete image data of one frame, the media library copies the image data to the user-provided buffer.

Function Prototype

int ReadFrameFromCamera(int cameralId, void* pdata, int* size)

Arguments

cameralId Specified camera ID [0, 1]

pdata Pointer to the user-

provided buffer -

(15)

size Size of the user-provided

buffer, in bytes You need to calculate the buffer size of an image frame based on the preset image format and resolution to ensure that the buffer size is sufficient to store the output image data.

Returns

Error Codes

0 LIBMEDIA_STATUS_F

AILED Image data fails to be captured.

1 LIBMEDIA_STATUS_O

K Image data is captured

successfully.

2.11 CloseCamera

Closes a camera to stop image capture.

Function Prototype

int CloseCamera(int cameraId)

Arguments

Returns

(16)

Error Codes

0 LIBMEDIA_STATUS_F

AILED The camera fails to be closed.

1 LIBMEDIA_STATUS_O

K The camera is successfully

closed.

2.12 QueryMICStatus

Queries the current operating status of the microphone on the Atlas 200 DK developer board.

Function Prototype

enum MICStatus QueryMICStatus()

Arguments

- - -

Returns

Error Codes

1 MIC_STATUS_OPEN The microphone is opened.

2 MIC_STATUS_CLOSED The microphone is closed.

3 MIC_NOT_EXISTS The microphone does not exist.

4 MIC_STATUS_UNKOW

N The microphone status is

unknown.

2.13 OpenMIC

Opens the microphone on the Atlas 200 DK developer board. A silicon microphone is built in the board. To record audio, place the audio source close to the silicon microphone.

(17)

Function Prototype

int OpenMIC()

Arguments

- - -

Returns

Error Codes

ILED The microphone fails to be

opened.

1 LIBMEDIA_STATUS_O

K The microphone is successfully

opened.

2.14 SetMICProperty

Sets microphone properties and operating parameters.

Function Prototype

int SetMICProperty(struct MICProperties *propties)

(18)

Arguments

Argument Description Value Range propties Data structure

of amicrophone property

struct MICProperties {

enum AudioSampleRate sample_rate; [Read/

Write] Sampling rate. The data type is uint32_t.

enum MICCapMode cap_mode; [Read/Write]

Audio capture mode of the microphone enum AutoBitWidth bit_width; [Read/Write]

Bit width of each sample

enum AudioSampleNumPerFrame

frame_sample_rate; [Read/Write] Number of samples per frame

enum AudioMode sound_mode; [Read/Write]

Sound mode (mono or stereo) };

Returns

Error Codes

ED Microphone properties fail to be

set.

1 LIBMEDIA_STATUS_OK Microphone properties are

successfully set.

AudioSampleRate

● Function: Specifies the sampling rate of audio data captured by the microphone.

● Value range:

enum AudioSampleRate

{ MIC_AUDIO_SAMPLE_RATE_8000 = 8000, /* 8K samplerate*/

MIC_AUDIO_SAMPLE_RATE_12000 = 12000, /* 12K samplerate*/

MIC_AUDIO_SAMPLE_RATE_11025 = 11025, /* 11.025K samplerate*/

(19)

MIC_AUDIO_SAMPLE_RATE_BUTT, };

MICCapMode

● Function: Specifies the mode for obtaining audio data from the microphone.

● Value range:

enum MICCapMode

{ MIC_CAP_ACTIVE = 1, // Active mode MIC_CAP_PASSIVE = 2, // Passive mode };

AutoBitWidth

● Function: Specifies the bit width of an audio sample.

● Value range:

enum AudioBitWidth

{ MIC_AUDIO_BIT_WIDTH_16 = 1, /* 16bit width*/

MIC_AUDIO_BIT_WIDTH_24 = 2, /* 24bit width*/

MIC_AUDIO_BIT_WIDTH_BUTT, };

AudioSampleNumPerFrame

● Function: Specifies the number of samples for each frame.

● Value range:

enum AudioSampleNumPerFrame { MIC_SAMPLE_NUM_80 = 80, MIC_SAMPLE_NUM_160 = 160, MIC_SAMPLE_NUM_240 = 240, MIC_SAMPLE_NUM_320 = 320, MIC_SAMPLE_NUM_480 = 480, MIC_SAMPLE_NUM_1024 = 1024, MIC_SAMPLE_NUM_2048 = 2048, };

AudioMode

● Function: Specifies the audio playback mode, that is, mono or stereo.

● Value range:

enum AudioMode

{ MIC_AUDIO_SOUND_MODE_MONO =0, // Mono MIC_AUDIO_SOUND_MODE_STEREO =1, // Stereo MIC_AUDIO_SOUND_MODE_BUTT

};

2.15 GetMICProperty

Obtains the current operating property value of a microphone.

Function Prototype

int GetMICProperty(struct MICProperties *propties)

(20)

Arguments

propties Pointer to the property data structure provided by the user

For details, see the description of property values in 2.14

SetMICProperty.

Returns

Error Codes

ILED Microphone properties fail to be obtained.

1 LIBMEDIA_STATUS_O

K Microphone properties are

successfully obtained.

2.16 CapMIC

Captures audio data using a callback function. If the callback function generates a frame of audio data at the bottom layer, it will be called by the underlying thread of the media library. You are advised to copy the audio data to the specified buffer in the callback function for the subsequent processing.

Function Prototype

int CapMIC(CAP_MIC_CALLBACK, void* param)

Arguments

The following table describes the arguments of the CapMIC function.

(21)

Argument Description Value Range CAP_CAMERA_CALLBACK Callback function used to

receive data.

The format of the callback function is as follows:

typedef int

(*CAP_MIC_CALLBACK) (const void* pdata, int size, void* param)

Valid address of a callback function

parameter After receiving the audio data, the media library returns this parameter to the user through the callback function.

The following table describes the arguments of the callback function.

pdata Address of a frame of

audio data This buffer is maintained by the media library and is read-only to users.

Users themselves cannot release the memory that the address points to.

Otherwise, exceptions may occur.

size Audio data size The value varies

according to the audio format and sampling rate.

parameter After receiving the audio data, the media library returns this parameter to the user through the callback function.

Returns

(22)

Error Codes

ILED Microphone audio data fails to

be captured.

1 LIBMEDIA_STATUS_O

K Microphone audio data is

successfully captured.

2.17 ReadMicSound

Reads the audio data captured by the microphone in a user thread. Note that this function returns values only after it receives audio data. The user is responsible for providing a buffer for receiving audio data. After receiving the complete audio data of one frame, the media library copies the frame data to the user-provided buffer.

Function Prototype

int ReadMicSound(void* pdata, int *size)

Arguments

pdata Pointer to the user-

provided buffer -

size Size of the user-provided

buffer, in bytes You need to calculate the buffer size of an audio frame based on the preset audio format and sampling rate to ensure that the buffer size is sufficient for the output audio data.

Returns

Error Codes

0 LIBMEDIA_STATUS_FAI

LED Microphone audio data fails to

be read.

(23)

1 LIBMEDIA_STATUS_OK Microphone audio data is

successfully read.

2.18 CloseMIC

Closes the microphone.

Function Prototype

int CloseMIC()

Arguments

- - -

Returns

Error Codes

ILED The microphone fails to be

closed.

1 LIBMEDIA_STATUS_O

K The microphone is successfully

closed.

(24)

3 ^Appendix

This chapter provides a complete example to describe how the APIs described in this document work, including opening the camera and microphone, modifying and querying their property parameters, calling the APIs for capturing video and audio data, saving the audio and video data streams to files, and closing the camera and microphone. This example code helps you get familiar with the API usage and then use these APIs flexibly based on actual project requirements.

For more usage examples, see https://github.com/Atlas200dk.

3.1 Example

#include "stdio.h"

#include "stdlib.h"

#include <sys/types.h>

#include <sys/stat.h>

#include <fcntl.h>

#include "pthread.h"

#include <unistd.h>

#include "peripheral_api.h"

int Camera0UserFunc(const void* pdata, int size, void* param)

{// pdata is the pointer to the start address of the image memory. You are advised to read it directly without modifying it. If you need to modify it, you are advised to copy it to the user-defined memory space before the modification.

printf("Camera0UserFunc Get frame size = %d\r\n", size);

return 1;

}

int Camera1UserFunc(const void* pdata, int size, void* param)

{// pdata is the pointer to the start address of the image memory. You are advised to read it directly without modifying it. If you need to modify it, you are advised to copy it to the user-defined memory space before the modification.

printf("Camera1UserFunc Get frame size = %d\r\n", size);

return 1;

}

int main() { int ret;

(25)

int para, i;

unsigned char *framebuffer;

int framebuffer_size;

struct CameraResolution resolution;

struct MICProperties micprop;

struct CameraResolution supported_resolution[HIAI_MAX_CAMERARESOLUTION_COUNT];

// Initializes the media library.

ret = MediaLibInit();

if(LIBMEDIA_STATUS_OK != ret) {

printf("MediaLibInit failed %d\r\n", ret);

return -1;

}

printf("MediaLibInit success %d\r\n", ret);

ret = IsChipAlive(NULL);

if(LIBMEDIA_STATUS_OK != ret) { printf("success failed %d\r\n", ret);

return -1;

}

printf("IsChipAlive success ret %d\r\n", ret);

// Open the camera.

ret = OpenCamera(0);

printf("OpenCamera 0 failed %d\r\n", ret);

return -1;

}

ret = OpenCamera(1);

printf("OpenCamera 0 failed %d\r\n", ret);

return -1;

}

ret = GetCameraProperty(0, CAMERA_PROP_SUPPORTED_RESOLUTION, supported_resolution);

printf("GetCameraProperty 0 failed %d\r\n", ret);

return -1;

} i = 0;

do{

printf("Camera0 supportted width = %d, height = %d\r\n", supported_resolution[i].width, supported_resolution[i].height);

i++;

}while(supported_resolution[i].width != -1);

ret = GetCameraProperty(1, CAMERA_PROP_SUPPORTED_RESOLUTION, supported_resolution);

printf("GetCameraProperty 1 failed %d\r\n", ret);

return -1;

} i = 0;

do{

printf("Camera1 supportted width = %d, height = %d\r\n", supported_resolution[i].width, supported_resolution[i].height);

i++;

}while(supported_resolution[i].width != -1);

// Set the frame rate.

para = 20;

ret = SetCameraProperty(0, CAMERA_PROP_FPS, &para);

printf("SetCameraProperty 0 failed %d\r\n", ret);

return -1;

}

ret = SetCameraProperty(1, CAMERA_PROP_FPS, &para);

return -1;

(26)

}

// Set the resolution.

resolution.height = 1080;

resolution.width = 1920;

ret = SetCameraProperty(0, CAMERA_PROP_RESOLUTION, &resolution);

return -1;

}

ret = SetCameraProperty(1, CAMERA_PROP_RESOLUTION, &resolution);

return -1;

}

// Register the user-defined callback function.

ret = CapCamera(0, Camera0UserFunc , NULL);

printf("CapCamera 0 failed %d\r\n", ret);

return -1;

}

ret = CapCamera(1, Camera1UserFunc , NULL);

printf("CapCamera 1 failed %d\r\n", ret);

return -1;

}

// Wait for 5s, which simulates the actual use process.

sleep(5);

// Close the camera.

ret = CloseCamera(0);

printf("CloseCamera 0 failed %d\r\n", ret);

return -1;

}

printf("CloseCamera 1 success %d\r\n", ret);

ret = CloseCamera(1);

printf("CloseCamera 1 failed %d\r\n", ret);

return -1;

}

printf("CloseCamera 0 success %d\r\n", ret);

return 0;

}

Atlas 200DK V100R020C10. Media API Reference. Issue 01 Date HUAWEI TECHNOLOGIES CO., LTD.

V100R020C10

Media API Reference

Contents

1 Introduction... 1

2 Media Library APIs... 2

3 Appendix...21

1 Introduction

2 Media Library APIs

2.1 Overview

2.2 MediaLibInit

Function Prototype

Arguments

Returns

Error Codes

2.3 IsChipAlive

Function Prototype

Arguments

Returns

Error Codes

2.4 QueryCameraIds

Function Prototype

Arguments

Returns

Error Codes

2.5 QueryCameraStatus

Function Prototype

Arguments

Returns

Error Codes

2.6 OpenCamera

Function Prototype

Arguments

Returns

Error Codes

2.7 SetCameraProperty

Function Prototype

Arguments

Returns

Error Codes

CameraResolution

CameraCapMode

2.8 GetCameraProperty

Function Prototype

Arguments

Returns

Error Codes

2.9 CapCamera

Function Prototype

Arguments

Returns

Error Codes

2.10 ReadFrameFromCamera

Function Prototype

Arguments

Returns

Error Codes

2.11 CloseCamera

Function Prototype

Arguments

Returns

Error Codes

2.12 QueryMICStatus

Function Prototype

Arguments

Returns

Error Codes

2.13 OpenMIC

Function Prototype

Arguments

Returns

Error Codes

2.14 SetMICProperty

Function Prototype

Arguments

Returns

Error Codes

AudioSampleRate

MICCapMode

AutoBitWidth

3 ^Appendix