当前版本: v1.2

苏州必捷网络有限公司

1.概述

1.1 目的

用于指导使用必捷Miracast 接收端SDK的开发人员进行开发及测试。

1.2 读者对象

本文档适用于使用BJSDK开发Linux平台Miracast 接收端的开发人员。

2. 范围

2.1 功能

本SDK可以接受来自Android手机，PC电脑，安卓系统ipad使用Miracast方式的投屏处理，并提供接口给应用层调用处理。

2.2 SDK 框架

media_define.h ：定义了接口相关的宏定义以及结构体。
mira_itf.h：定义了初始化信息接口体，以及用户可调用的Miracast接口。
libmira_media.so：它是一个C库，内部实现了Miracast接口。

2.3 SDK Demo实现

bj_mira_demo 是接收端的一个参考实现，它基于libmira_media.so实现了Miracast接收端功能。

2.4 SDK 交付物

SDK库

DEMO源码

SDK接口文档

3. 接口

接口主要以C接口的形式吐出。

3.1 回调

回调接口均在MiraFunCbs 结构体中定义，通过初始化接口传入到SDK中。

3.1.1 音视频吐出回调

c++

void(*render)(int channelId, unsigned char* data,unsigned int len,long long ts,int trackId);

描述

吐出音视频数据。

参数

名称	类型	描述
channelId	int	投屏会话ID。
data	unsigned char*	音视频数据。
len	unsigned int	数据长度。
ts	long long	时间戳，时间戳单位为1/1000000秒。
trackId	int	音频流的ID。

3.1.2 音频编码特定信息回调

c++

void(*setTrackCodecInfo)(int channelId, unsigned char* data,unsigned int len,int trackId,const char* dscp);

描述

回调接口，SDK通知上层获取的音频流 codec specific data 信息。

参数

名称		描述
channelId	int	投屏会话ID。
data	unsigned char*	音频编码所需配置信息。
len	unsigned int	data 字节长度。
trackId	int	音频流的ID。
dscp	const char*	codec specific data。

3.1.3 音频基本信息回调

c++

void(*notifyAudioTrackCodecInfo)(int channelId, int trackId, int sampleRate, int channelNum, int channelLayOut, int bitDep, int codecType);

描述

回调接口，投屏过程中SDK调用，通知用户层音频相关基本信息，用户通过音频信息创建对应的的音频播放器，应用层实现相关逻辑。

参数

名称	类型	描述
channelId	int	投屏会话ID
trackId	int	音频流的ID。
sampleRate	int	采样率。
channelNum	int	声道。
channelLayOut	int	音频声道布局。
bitDep	int	音频采样精度。
codecType	int	音频编码器类型。

3.1.4 鼠标位置更新回调

c++

void(*updateCursorPosition)(int channelId, short xpos, short ypos);

描述

通知上层鼠标位置。用于接收端鼠标绘制。

参数

名称	类型	描述
channelId	int	投屏会话ID。
xpos	short	鼠标x轴位置。
ypos	short	鼠标Y轴位置。

3.1.5 鼠标图片更新回调

c++

void(*updateCursorShape)(int channelId, unsigned char* pngData,unsigned int len);

描述

通知上层鼠标图片更新，以及携带鼠标图片数据，用于接收端绘制鼠标。

参数

名称	类型	描述
channelId	int	投屏会话ID。
pngData	unsigned char*	鼠标图片数据。
len	unsigned int	鼠标图片数据长度。

3.1.6 鼠标隐藏回调

c++

void(*hindCursor)(int channelId);

描述

通知上层隐藏鼠标，用于接收端绘制鼠标。

参数

名称	类型	描述
channelId	int	投屏会话ID。

3.1.7 统计信息通知回调

c++

void(*onMediaStatistics)(const BJCastMediaStatistics& vStatistics, const BJCastMediaStatistics& aStatistics);

描述

回调接口，投屏过程中SDK调用，用于统计实时媒体数据信息，用于开发者查看实时传输数据，应用层实现相关逻辑。

参数

名称	类型	描述
vStatistics	const BJCastMediaStatistics&	视频传输的相关实时数据对象。具体见3.3.4节
aStatistics	const BJCastMediaStatistics&	音频传输的相关实时数据对象。具体见3.3.4节

3.1.8 关键帧请求通知回调

c++

void (*reqIFrame)(int channelId);

描述

通知上层发送关键帧请求，开发者可自行决定是否发送关键帧请求。

参数

名称	类型	描述
channelId	int	投屏会话ID。

调用例子

c++

static void reqIFrame(int channelId){
    sendIFrame(id); //发送关键帧接口
}

3.1.9 长时间无音视频流通知

c++

void (*noMediaNotify)(int id);

描述

通知上层长时间没有收到音视频流。

参数

名称	类型	描述
channelId	int	投屏会话ID。

3.1.10 setup回调

c++

void(*onSetup)(int channelId, const char* device_name,const char* ip,const char* mac, int width,int height, int frameRate,int is_support_uibc);

描述

当RTSP协商完成，通过该回调通知用户，进行播放器设置，反控连接等。

参数

名称	类型	描述
channelId	int	投屏会话ID。
device_name	const char*	投屏设备名称。
ip	const char*	投屏设备IP。
mac	const char*	投屏设备MAC地址。
width	int	视频流宽。
height	int	视频流高。
frameRate	int	视频流帧率。
is_support_uibc	int	投屏设备是否支持反控。

3.1.11 RTSP收到反控信息回调

c++

void(*onUibcInfo)(int channelId,unsigned int port, unsigned int hres, unsigned int vres,int uibc_setting);

描述

投屏后，反控信息有变化时触发。一般仅widi投屏中使用。

参数

名称	类型	描述
channelId	int	投屏会话ID。
port	unsigned int	UIBC端口。
hres	unsigned int	UIBC反控画面宽。
vres	unsigned int	UIBC反控画面高。
uibc_setting	int	投屏设备是否禁用UIBC。

3.1.12 RTSP收到视频信息回调

c++

void(*onVideoInfo)(int channelId, unsigned int width,unsigned int height,unsigned int frameRate);

描述

投屏中视频流信息变化时触发。

参数

名称	类型	描述
channelId	int	投屏会话ID。
width	int	视频流宽。
height	int	视频流高。
frameRate	int	视频流帧率。

3.1.13 MiraCast状态通知回调(目前仅PIN码使用)

c++

void(*onMiraStatus)(int channelId,int status);

描述

Miracast状态变化通知上层。

参数

名称	类型	描述
channelId	int	投屏会话ID。
status	int	状态值。

3.1.14 Hangup回调

c++

void(*onHangup)(int channelId);

描述

投屏结束时SDK触发该回调通知上层。

参数

名称	类型	描述
channelId	int	投屏会话ID。

返回值

3.1.15 SDK日志吐出回调

c++

void(*onLogTrace)(unsigned int level, const char *format,  va_list argp);

描述

SDK内部日志输出回调接口。用户可以通过该接口自行设置日志存储方式。

参数

名称	类型	描述
level	unsigned int	日志级别。
format	const char*	字符串。
argp	va_list	可变参数。

3.2 SDK接口

3.2.1 初始化接口

c++

int miraProxyModule_init(InitMiraPara *confPara, const char* licensetkey);

描述

用于初始化Miracast模块。

参数

名称	类型	描述
confPara	InitMiraPara*	初始化结构体，具体见3.3节。

返回值

0：成功。

非0：错误码。

调用例子

c++

void main(){
	InitMiraPara confPara;
    memset(&confPara,0,sizeof(confPara));
    FILE * file = fopen("license_mircast.file", "r");
	if (file)
	{
		char key[1024];
		memset(key,0,1024);

		int size = fread(key, 1, 1024, file);
		snprintf(confPara.licensekey, sizeof(confPara.licensekey), "%s", key);
        strncpy(confPara.license_check_token, "", sizeof(confPara.license_check_token) - 1);
        strncpy(confPara.license_check_pass, "", sizeof(confPara.license_check_pass) - 1);
        printf("licenseKey: %s\n license token:%s\n license pass:%s\n", confPara.licensekey,confPara.license_check_token,confPara.license_check_pass);
		fclose(file);
	}
	else
	{
		printf("oepn license file failed\n");
        return -1;
	}
    strncpy(confPara.name, "A_He", sizeof(confPara.name) - 1);
    strncpy(confPara.miraFormat, "00 00 02 08 0001bcab 05557fff 00000fff 00 0000 0000 11 0780 0438", sizeof(confPara.miraFormat) - 1);
    strncpy(confPara.widiFormat, "40 01 10 0040 000001cfffff 00017fffffff 000000000fff 10 0000 001f 11, 01 20 0040 000001cfffff 00017fffffff 000000000fff 10 0000 001f 11, 01 02 0040 000001cfffff 00017fffffff 000000000fff 10 0000 001f 11 00", sizeof(confPara.widiFormat) - 1);
    strncpy(confPara.pin, "", sizeof(confPara.pin) - 1);
    strncpy(confPara.hdcpPort, "0", sizeof(confPara.hdcpPort) - 1);

    confPara.freq = freqs;
    confPara.miraConfig = 80;
    confPara.jitterbuffermode = 1;
    confPara.errorVideoDropNode = 0;
    confPara.keyFrameReqIntervalMS = 3000;
    confPara.dropFristFrameWithLostPac = 1;
    confPara.miraConfig = 0;
    
    confPara.callback.render = render;
    confPara.callback.setTrackCodecInfo = setTrackCodecInfo;
    confPara.callback.notifyAudioTrackCodecInfo = notifyAudioTrackCodecInfo;
    confPara.callback.updateCursorPosition = updateCursorPosition;
    confPara.callback.updateCursorShape = updateCursorShape;
    confPara.callback.hindCursor = hindCursor;
    confPara.callback.onMediaStatistics = onMediaStatistics;
    confPara.callback.reqIFrame = reqIFrame;
    confPara.callback.noMediaNotify = noMediaNotify;
    confPara.callback.onSetup = onSetup;

    confPara.callback.onUibcInfo = onUibcInfo;
    confPara.callback.onMiraStatus = onMiraStatus;
    confPara.callback.onVideoInfo = onVideoInfo;
    confPara.callback.onHangup = onHangup;
    confPara.callback.onLogTrace = onLogTrace;

    printf("init start\n");
    if(miraProxyModule_init(&confPara)!=0){
        return -1;
    }
    printf("init sucess\n");
	...
 }

3.2.2 修改名称接口

c++

void updateMiraName(const char* name);

描述

用于初始化Miracast模块。

参数

名称	类型	描述
name	const char*	更新Miracast服务名称,调用后需要配合重新启动cq_mira服务才可生效。

3.2.3 修改PIN码接口

c++

void updateMiraPin(const char* pin);

描述

用于初始化Miracast模块。

参数

名称	类型	描述
pin	const char*	更新Miracast pin码,调用后需要重新启动cq_mira服务才可生效。

3.2.4 修改P2P频段接口

c++

void updateMiraFreq(int freq);

描述

用于初始化Miracast模块。

参数

名称	类型	描述
freq	int	更新Miracast freq,调用后需要重新启动cq_mira服务才可生效。

3.2.5 结束投屏接口

c++

void stopMediaSession(int channelId);

描述

主动结束投屏。

参数

名称	类型	描述
channelId	int	投屏会话ID。

3.2.6 发送关键帧接口

c++

void sendIFrame(int channelId);

描述

发送关键帧，当关键帧请求回调触发时，用户可自行根据需求调用该接口发送关键帧请求。

参数

名称	类型	描述
channelId	int	投屏会话ID。

3.2.7 去初始化接口

c++

void fini();

描述

去初始化接口。

3.2.8 获取反控接收端类型接口

c++

int mira_uibc_getSinkType(int channelId);

描述

获取反控接收端类型。目前基本无调用需求。

参数

名称	类型	描述
channelId	int	投屏会话ID。

返回值

0：手机

1：电脑

3.2.9 建立反控连接

c++

bool mira_uibc_connect(int channelId);

描述

建立反控连接。建议单独建立线程去处理反控部分。

参数

名称	类型	描述
channelId	int	投屏会话ID。

返回值

true : 反控连接成功

false: 反控连接失败

3.2.10 关闭反控连接

c++

 void mira_uibc_close(int channelId);

描述

关闭反控连接。

参数

名称	类型	描述
channelId	int	投屏会话ID。

3.2.11 重新发送UIBC Setting

c++

void mira_uibc_reSetting(int channelId, int uibc_setting);

描述

重新发送HID描述符。在onUibcInfo回调中调用。使反控生效，若不调用会导致电脑反控不生效。

参数

名称	类型	描述
channelId	int	投屏会话ID。
uibc_setting	int	onUibcInfo 回调触发。

3.2.12 发送鼠标事件

c++

void mira_uibc_mouseAction(int channelId, int action, long time, float x, float y,int video_width, int video_height, int view_width, int view_height);

描述

发送鼠标点击消息。当接收端使用鼠标操作时，建议使用调用该接口。

参数

名称	类型	描述
channelId	int	投屏会话ID。
action	int	点击事件动作。
time	long	反控事件时间，单位ms。
x	float	播放器中的 x 坐标。
y	float	播放器中的 y 坐标。
video_width	int	视频流宽
video_height	int	视频流高
view_width	int	播放器画面宽
view_height	int	播放器画面高

3.2.13 发送触控事件

c++

void mira_uibc_touchAction(int channelId, uint8_t actionId, uint8_t action, long time, Pointer_t* pointsList, int pointsCount, int video_width, int video_height, int view_width, int view_height);

描述

发送触控类型消息。当接收端使用触控屏操作时，建议使用调用该接口。使用该接口反向控制手机时只支持单指，如果传入多个触点也只会处理第一个。

参数

名称	类型	描述
channelId	int	投屏会话ID。
actionId	uint8_t	本次事件的触点ID，每次仅可以处理一个触点动作，其他触点保持原样。
action	uint8_t	点击事件动作。
time	long	反控事件时间，单位ms。
pointsList	Pointer_t*	触点信息的结构体数组指针，结构体具体见3.3节。
pointsCount	int	触点数量。
video_width	int	视频流宽
video_height	int	视频流高
view_width	int	播放器画面宽
view_height	int	播放器画面高

3.3 接口相关结构体

3.3.1 InitMiraPara结构体

描述

用于初始化接口传参使用，包含初始化所需的一些信息。

属性

名称	类型	描述	大小
name	char[]	服务发现名称设置。	64 bit
pin	char[]	PIN码设置。(需要特殊订制，默认不支持)	16 bit
hdcpPort	char[]	hdcp 端口设置。	16bit
widiFormat	char[]	接收端支持的widi投屏分辨率能力集，用于用户想要限制投屏分辨率的需求，如无需求使用demo中的字符串即可。	1024bit
miraFormat	char[]	接收端支持的手机投屏分辨率能力集，用于用户想要限制投屏分辨率的需求，如无需求使用demo中的字符串即可。	1024bit
freq	int	信道设置，用于设置P2P_GROUP_ADD的信道设置，需系统支持对应的信道才可设置成功。
miraConfig	int	ft值，64代表禁用UIBC，否则设置0即可。
jitterbuffermode	int	jitterbuffer设置。（0：禁用，1：启用）
errorVideoDropNode	int	错误帧处理方式。(1:丢掉错误帧，0：不丢)
keyFrameReqIntervalMS	int	关键帧请求最小间隔。(设置区间 1000ms - 5000ms)
dropFristFrameWithLostPac	int	第一帧丢包的处理方式。(1:drop 0:not drop)
licensekey	char[]	BJ提供的license key
license_check_token	char[]	BJ提供的license token,用于适配部分用户使用非mac地址作为唯一ID时使用。不需要设为空字符即可。
license_check_pass	char[]	BJ提供的license pass,,用于适配部分用户使用非mac地址作为唯一ID时使用。不需要设为空字符即可。
callback	MiraFunCbs	回调函数。

3.3.2 Pointer_t 结构体

描述

包含每个触点的ID，坐标信息。

成员

名称	类型	描述
id	int	触点ID
x	int	触点x坐标
y	int	触点y坐标

3.3.3 MiraFunCbs 结构体

描述

保存初始化回调函数的结构体。

成员

具体信息见3.1小节内容

typedef struct {
    void(*render)(int channelId, unsigned char* data,unsigned int len,long long ts,int trackId);
    void(*setTrackCodecInfo)(int channelId, unsigned char* data,unsigned int len,int trackId,const char* dscp);
    void(*notifyAudioTrackCodecInfo)(int channelId, int trackId, int sampleRate, int channelNum, int channelLayOut, int bitDep, int codecType);
    void(*updateCursorPosition)(int channelId, short xpos, short ypos);
    void(*updateCursorShape)(int channelId, unsigned char* pngData,unsigned int len);
    void(*hindCursor)(int channelId);
    void(*onMediaStatistics)(const BJCastMediaStatistics& vStatistics, const BJCastMediaStatistics& aStatistics);
    void(*reqIFrame)(int id);
    void(*noMediaNotify)(int id);
    void(*onSetup)(int channelId, const char* device_name,const char* ip,const char* mac, int width,int height, int frameRate,int is_support_uibc);
    void(*onUibcInfo)(int channelId,unsigned int port, unsigned int hres, unsigned int vres,int uibc_setting);
    void(*onVideoInfo)(int channelId, unsigned int width,unsigned int height,unsigned int frameRate);
    void(*onMiraStatus)(int channelId,int status);
    int(*onHangup)(int channelId);
    void(*onLogTrace)(unsigned int level, const char *format,  va_list argp);
}MiraFunCbs;

3.3.4 BJCastMediaStatistics 结构体

描述

保存媒体传输中的实时监测信息的结构体。

成员

名称	类型	描述
bitratekbps_this_round	float	当前时间段的视频码率
bitratekbps	float	当前瞬时视频码率
lostrate_this_round	float	当前时间段的丢包率
lostrate	float	当前瞬时丢包率
disable	int	是否失效，如建立的为TCP连接，该值则为1。

3.4 UIBC相关事件

描述

SDK中UIBC接口的事件处理方式是基于Android event事件进行实现的。所以action事件和Android一样，每次只支持一种事件。

事件

支持的android事件以及对应的值如下：

名称	描述	值
ACTION_DOWN	按下	0
ACTION_UP	松开	1
ACTION_MOVE	移动	2
ACTION_POINTER_DOWN	触点按下(仅触控接口时使用)	5
ACTION_POINTER_UP	触点松开(仅触控接口时使用)	6

4 Demo 简要说明

demo 是一个简单的服务实现。SDK和源码请联系我司商务或技术接口获取。

1.概述 ​

1.1 目的 ​

1.2 读者对象 ​

2. 范围 ​

2.1 功能 ​

2.2 SDK 框架 ​

2.3 SDK Demo实现 ​

2.4 SDK 交付物 ​

3. 接口 ​

3.1 回调 ​

3.1.1 音视频吐出回调 ​

3.1.2 音频编码特定信息回调 ​

3.1.3 音频基本信息回调 ​

3.1.4 鼠标位置更新回调 ​

3.1.5 鼠标图片更新回调 ​

3.1.6 鼠标隐藏回调 ​

3.1.7 统计信息通知回调 ​

3.1.8 关键帧请求通知回调 ​

3.1.9 长时间无音视频流通知 ​

3.1.10 setup回调 ​

3.1.11 RTSP收到反控信息回调 ​

3.1.12 RTSP收到视频信息回调 ​

3.1.13 MiraCast状态通知回调(目前仅PIN码使用) ​

3.1.14 Hangup回调 ​

3.1.15 SDK日志吐出回调 ​

3.2 SDK接口 ​

3.2.1 初始化接口 ​

3.2.2 修改名称接口 ​

3.2.3 修改PIN码接口 ​

3.2.4 修改P2P频段接口 ​

3.2.5 结束投屏接口 ​

3.2.6 发送关键帧接口 ​

3.2.7 去初始化接口 ​

3.2.8 获取反控接收端类型接口 ​

3.2.9 建立反控连接 ​

3.2.10 关闭反控连接 ​

3.2.11 重新发送UIBC Setting ​

3.2.12 发送鼠标事件 ​

3.2.13 发送触控事件 ​

3.3 接口相关结构体 ​

3.3.1 InitMiraPara结构体 ​

3.3.2 Pointer_t 结构体 ​

3.3.3 MiraFunCbs 结构体 ​

3.3.4 BJCastMediaStatistics 结构体 ​

3.4 UIBC相关事件 ​

4 Demo 简要说明 ​

1.概述

1.1 目的

1.2 读者对象

2. 范围

2.1 功能

2.2 SDK 框架

2.3 SDK Demo实现

2.4 SDK 交付物

3. 接口

3.1 回调

3.1.1 音视频吐出回调

3.1.2 音频编码特定信息回调

3.1.3 音频基本信息回调

3.1.4 鼠标位置更新回调

3.1.5 鼠标图片更新回调

3.1.6 鼠标隐藏回调

3.1.7 统计信息通知回调

3.1.8 关键帧请求通知回调

3.1.9 长时间无音视频流通知

3.1.10 setup回调

3.1.11 RTSP收到反控信息回调

3.1.12 RTSP收到视频信息回调

3.1.13 MiraCast状态通知回调(目前仅PIN码使用)

3.1.14 Hangup回调

3.1.15 SDK日志吐出回调

3.2 SDK接口

3.2.1 初始化接口

3.2.2 修改名称接口

3.2.3 修改PIN码接口

3.2.4 修改P2P频段接口

3.2.5 结束投屏接口

3.2.6 发送关键帧接口

3.2.7 去初始化接口

3.2.8 获取反控接收端类型接口

3.2.9 建立反控连接

3.2.10 关闭反控连接

3.2.11 重新发送UIBC Setting

3.2.12 发送鼠标事件

3.2.13 发送触控事件

3.3 接口相关结构体

3.3.1 InitMiraPara结构体

3.3.2 Pointer_t 结构体

3.3.3 MiraFunCbs 结构体

3.3.4 BJCastMediaStatistics 结构体

3.4 UIBC相关事件

4 Demo 简要说明