2.1 Overview
The APIs of the Media module are based on the C language. The following describes each API in detail.
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)
Arguments
Argument Description Value Range
chipName Name of the chip
interconnected with Ascend 310 Currently, only Hi3559 is
supported.
The value is 3559.
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 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)
Arguments
Argument Description Value Range
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
For details about the returned error codes, see the Error Code column in Error Codes.
Error Codes
True Value Error Code Description
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
Argument Description Value Range
cameraId Specified camera ID [0, 1]
Returns
For details about the returned error codes, see the Error Code column in Error Codes.
Error Codes
True Value Error Code Description
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
Argument Description Value Range
cameraId Specified camera ID [0, 1]
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_FA
ILED The camera fails to be opened.
1 LIBMEDIA_STATUS_O
K The camera is successfully
opened.
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
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 Camera properties fail to be set.
True Value Error Code Description
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
Argument Description Value Range
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
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_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.
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.
Argument Description Value Range
cameraId Specified camera ID [0, 1]
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.
Argument Description Value Range
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.
Argument Description Value Range
param User-defined callback
parameter After receiving the image data, the media library returns this parameter to the user through the callback function.
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_FA
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
Argument Description Value Range
cameralId Specified camera ID [0, 1]
pdata Pointer to the
user-provided buffer
-Argument Description Value Range
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
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_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
Argument Description Value Range
cameraId Specified camera ID [0, 1]
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_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
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
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.
Function Prototype
int OpenMIC()
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_FA
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)
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
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 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*/
MIC_AUDIO_SAMPLE_RATE_16000 = 16000, /* 16K samplerate*/
MIC_AUDIO_SAMPLE_RATE_22050 = 22050, /* 22.050K samplerate*/
MIC_AUDIO_SAMPLE_RATE_24000 = 24000, /* 24K samplerate*/
MIC_AUDIO_SAMPLE_RATE_32000 = 32000, /* 32K samplerate*/
MIC_AUDIO_SAMPLE_RATE_44100 = 44100, /* 44.1K samplerate*/
MIC_AUDIO_SAMPLE_RATE_48000 = 48000, /* 48K samplerate*/
MIC_AUDIO_SAMPLE_RATE_64000 = 64000, /* 64K samplerate*/
MIC_AUDIO_SAMPLE_RATE_96000 = 96000, /* 96K samplerate*/
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_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)
Arguments
Argument Description Value Range
propties Pointer to the property data structure provided by the user
For details, see the description of property values in 2.14
SetMICProperty.
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_FA
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.
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
param User-defined callback
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.
Argument Description Value Range
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.
param User-defined callback
parameter After receiving the audio data, the media library returns this parameter to the user through the callback function.
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_FA
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
Argument Description Value Range
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
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_FAI
LED Microphone audio data fails to
be read.
True Value Error Code Description
1 LIBMEDIA_STATUS_OK Microphone audio data is
successfully read.