回车情感云计算 WebSocket 接口文档

综合说明
协议约定
- 协议基本结构
- 协议注意事项
服务接口会话协议
生物数据基础分析服务协议
情感计算服务协议
ErrCode

综合说明

简介

情感云计算平台 WebSocket 接口，根据客户端采集上传的脑电数据、心率数据等生物数据来计算并返回愉悦度、放松度等情感值。

生物数据基础分析服务

EEG：双通道脑电数据
HR：心率数据

情感计算服务

注意力
放松度
压力值
激活度
愉悦度
睡眠服务

接入注意事项

需要在情感云平台申请账号，并创建应用
接口使用 WebSocket 协议通信

测试服务器地址

wss://server-test.affectivecloud.com/ws/algorithm/v0.1/

版本

当前版本: v0.1

v0.1
- 当前版本为初始版本
- 提供：愉悦度、放松度、压力值、激活度、愉悦度、睡眠计算服务

协议约定

协议基本结构

Request结构体

services【必填，多选用","分隔】
- 服务类型：session、biodata、affective等
op【必填】
- 请求操作：start、restore、process、finish等
args
- 列表型参数
kwargs
- 字典型参数

Response结构体

code【必填】
- 0请求成功其它见ErrCode表
request【必填】
- services【必填】
- op【必填】
data
- 请求返回数据包
msg
- 请求返回信息

协议注意事项

所有数据传输都需要做gzip压缩
请求数据计算服务必须先进行会话认证
以下协议中加 "" 的为字符串，不加的为变量名

服务接口会话协议

接口权限验证，使用对应的服务需要从情感云平台创建用户，并创建应用，创建应用时可以选型相应的服务，使用服务需要对账户进行验证。

服务	操作	备注
session	create	认证并创建会话
	restore	恢复会话
	close	结束会话

Session Create

认证并创建会话。

Request

{
    "services": "session",
    "op": "create",
    "kwargs": {
        "app_key": app_key, # 云后台生成的APP Key
        "sign": sign,   # 详见sign步骤
        "user_id": userid    # 会话关联的唯一用户 id 的 md5 哈希值，用于定位会话用户归属（可用于后期数据查询）
    }
}

sign 步骤

从后台获取 app_key & app_secret。

例如：对于如下的参数进行签名

params = {
    "app_key": "c821db84-6fbd-11e4-a9e3-c86000d26d7c",
    "app_secret": "b1a071f0d3f119de465a6d8c9a1c0e7d",
    "username": "test",  # 创建本app_key的用户
}

sign_str = "app_key={}&app_secret={}&username={}".format(
    params.get("app_key"), parmas.get('app_secret'), params.get("username")
) # 将待签名字符串要求按照参数名进行排序(首先比较所有参数名的第一个字母，按abcd顺序排列，若遇到相同首字母，则看第二个字母，以此类推)

md5 = hashlib.md5()
md5.update(sign_str)
sign = md5.hexdigest().upper()  # sign即为签名值（需全大写）

user_id

user_id 为开发者 app 内的唯一用户 id 经过 md5 哈希之后的值。此唯一用户 id 可为手机号、邮箱、用户id、账户名的。

Response

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "start"
    },
    "data": {
        "session_id": session_id    # 会话ID，每次Start连接会生成唯一ID, 可以用来做会话恢复
    }
}

Session Restore

恢复会话。会话因为网络条件不好而中断，可以选择恢复。会话保留时间为 30 分钟，30 分钟内可以根据 session_id 来恢复会话，超过 30 分钟会话将会被销毁。

Request

{
    "services": "session",
    "op": "restore",
    "kwargs": {
        "app_key": app_key, # 云后台生成的APP Key
        "sign": sign,   # 详见sign步骤
        "session_id": session_id    # 会话ID，由Session Start生成
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "restore"
    }
}

Session Close

结束会话

Request

{
    "services": "session",
    "op": "close"
}

Response

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "close"
    }
}

生物数据基础分析服务协议

生物数据（EEG、HR等）的基础分析服务。此部分数据为情感计算服务的数据基础。需要先初始化并上传生物数据，才能进行情感计算服务。

服务	操作	备注
biodata	init	启动、初始化生物数据基础分析服务
	subscribe	订阅实时生物数据
	unsubscribe	取消订阅实时生物数据
	upload	上传数据
	report	获取当前生物数据报表

Biodata init

启动、初始化生物数据基础分析服务。

Request

{
    "services": "biodata",
    "op": "init",
    "kwargs": {
        "bio_data_type": [ 
            bio_data_type1,  # 需要初始化的生物数据分析服务类型，eeg、hr
            bio_data_typeN
        ]
    }
}

类型	值
bio_data_type	eeg
	hr

Response

{
    "code": 0,
    "request": {
        "services": "biodata",
        "op": "init"
    },
    "data": {
        "bio_data_type": [
            bio_data_type1, # 已经初始化的生物数据分析服务类型
            bio_data_typeN
        ]
    }
}

Biodata Subscribe

订阅生物数据分析服务的实时数据。分析返回值为可选服务，如果你需要实时接收分析返回的值，则开启此订阅，并配置要返回的参数。具体参数见下表。

注意：Subscribe有两种Response
- 订阅成功Response
- 订阅数据Response

实时生物数据分析返回值表格

类别	参数	类型	取值范围	说明
eeg	eegl_wave	list[float]	[-2.4e6, 2.4e6]*100	左通道脑电波形片段，初始阶段返回为空数组，之后返回数组长度为100
	eegr_wave	list[float]	[-2.4e6, 2.4e6]*100	右通道脑电波形片段，初始阶段返回为空数组，之后返回数组长度为100
	eeg_alpha_power	float	[0, 1]	脑电α频段能量占比
	eeg_beta_power	float	[0, 1]	脑电β频段能量占比
	eeg_theta_power	float	[0, 1]	脑电θ频段能量占比
	eeg_delta_power	float	[0, 1]	脑电δ频段能量占比
	eeg_gamma_power	float	[0, 1]	脑电γ频段能量占比
	eeg_progress	float	[0, 100]	脑电信号质量进度，未达到100时表明脑电信号质量不佳，达到100时脑电信号质量良好
hr	hr	int	[0, 255]	心率值
	hrv	float	[0, 255]	心率变异性

Request

{
    "services": "biodata",
    "op": "subscribe",
    "kwargs": {
        bio_data_type1: [ # 生物数据类型，eeg、hr等
            data_type1, data_type2, data_typeN  # 配置你要返回的参数，详见 实时生物数据分析返回值表 参数 列
        ],
        bio_data_typeN: [
            data_type1, data_type2, data_typeN
        ]   
    }
}

订阅状态Response

{
    "code": 0,
    "request": {
        "services": "biodata",
        "op": "subscribe"
    },
    "data": {
        "sub_" + bio_data_type1 + "_fields": [ # bio_data_type1: 生物数据类型，eeg、hr等
            data_type1, data_typeN  # 详见 实时生物数据分析返回值表 参数 列
        ],
        "sub_" + bio_data_typeN + "_fields": [
            data_type1, data_typeN,
        ]
    }
}

订阅数据Response

返回的数据取决于 Subscribe 时设置的数据。

{
    "code": 0,
    "request": {
        "services": "biodata",
        "op": "subscribe"
    },
    "data": {
        bio_data_type1: {  # 生物数据类型，eeg、hr等
            data_type1: data1,    # 详见 实时生物数据分析返回值表
            data_typeN: dataN,
        },
        bio_data_typeN: {
            data_type1: data1,
            data_typeN: dataN,
        }
    }
}

Biodata Unsubscribe

取消订阅生物数据分析服务实时数据。

Request

{
    "services": "biodata",
    "op": "unsubscribe",
    "kwargs": {
        bio_data_type1: [ # 要取消订阅的生物数据类型，eeg、hr等
            data_type1, data_type2, data_typeN  # 详见 实时生物数据分析返回值表 参数 列
        ],
        bio_data_typeN: [
            data_type1, data_type2, data_typeN
        ]   
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "biodata",
        "op": "unsubscribe"
    },
    "data": {
        "sub_" + bio_data_type1 + "_fields": [ # bio_data_type1: 正在订阅的生物数据类型，eeg、hr等
            data_type1, data_typeN
        ],
        "sub_" + bio_data_typeN + "_fields": [
            data_type1, data_typeN,
        ]
    }
}

Biodata Upload

客户端上传生物数据。客户端将从硬件接收到的数据拼接，满足一定数量之后上传。比如脑电数据为从硬件接收到 30 个包拼接一次，然后上传；心率则为每 2 个包拼接一次，然后上传。

bio_data_type	描述	客户端每次上传拼接包数	从硬件接收数据包间隔时间	客户端上传理论间隔时间
eeg	双通道脑电数据	30	12 ms	360 ms
hr	心率数据	2	200 ms	400 ms

Request

{
    "services": "biodata",
    "op": "upload",
    "kwargs": {
        bio_data_type1: data, # bio_data_type1 生物数据类型, 如 eeg、hr等; data: 拼接后的生物数据包，见上表
        bio_data_typeN: dataN
    }
}

Biodata Report

获取生物数据分析统计报表。返回从开始到执行此操作区间的所有 biodata 的分析值。返回的报表结果见下表。

生物数据分析统计报表

类别	参数	类型	取值范围	说明
eeg	eeg_alpha_curve	list[float]	[0, 1]*k, (k≥20)	脑电α频段能量变化曲线
	eeg_beta_curve	list[float]	[0, 1]*k, (k≥20)	脑电β频段能量变化曲线
	eeg_theta_curve	list[float]	[0, 1]*k, (k≥20)	脑电θ频段能量变化曲线
	eeg_delta_curve	list[float]	[0, 1]*k, (k≥20)	脑电δ频段能量变化曲线
	eeg_gamma_curve	list[float]	[0, 1]*k, (k≥20)	脑电γ频段能量变化曲线
hr	hr_avg	float	[0, 255]	心率平均值
	hr_max	float	[0, 255]	心率最大值
	hr_min	float	[0, 255]	心率最小值
	hr_rec	list[int]	[0, 255]*k, (k≥20)	心率值全程记录
	hrv_rec	list[float]	[0, 255]*k, (k≥20)	心率变异性全程记录
	hrv_avg	float	[0, 255]	心率变异性平均值

Request

{
    "services": "biodata",
    "op": "report",
    "kwargs": {
        "bio_data_type": [
            bio_data_type1,   # 生物数据类型，eeg、hr等
            bio_data_typeN
        ]
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "biodata",
        "op": "report"
    },
    "data": {
        bio_data_type1: { # 生物数据类型，eeg、hr等
            data_type1: data1,  # 详见 生物数据分析统计报表 参数 列，data: 详见生物数据分析统计报表 类型、取值范围等
            data_typeN: dataN,
        },
        bio_data_typeN: {
            data_type1: data1,
            data_typeN: dataN,
        }
    }
}

情感计算服务协议

依赖生物数据基础分析服务，提供注意力、放松度、压力值计算等服务。服务需要在管理后台开通才能使用。

服务	操作	备注
affective	start	启动、初始化情感计算服务
	subscribe	订阅实时情感计算数据
	unsubscribe	取消订阅实时情感计算数据
	report	获取当前情感计算云计算服务报表
	finish	结束某云计算服务

Affective Start

启动情感云计算服务。

情感云计算服务和参数项

服务类型cloud_service	数据类型data_type	类型	取值范围	说明
attention	attention	float	[0, 100]	注意力值，数值越高代表注意力越高
relaxation	relaxation	float	[0, 100]	放松度值，数值越高代表放松度越高
pressure	pressure	float	[0, 100]	压力水平值，数值越高代表压力水平越高
pleasure	pleasure	float	[0, 100]	愉悦度值，数值越高代表情绪愉悦度越高
arousal	arousal	float	[0, 100]	激活度值，数值越高代表情绪激活度越高
sleep	sleep_degree	float	[0, 100]	睡眠程度，数值越小代表睡得越深
	sleep_state	int	{0, 1}	睡眠状态，0 表示未入睡，1 表示已入睡

Request

{
    "services": "affective",
    "op": "start",
    "kwargs": {
        "cloud_services": [
            cloud_service1, # 云计算服务类型，attention、relaxation、pressure等
            cloud_serviceN
        ]
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "start"
    },
    "data": {
        "cloud_service": [
            cloud_service1, # 已启动的云计算服务类型
            cloud_serviceN
        ]
    }
}

Affective Subscribe

订阅情感云计算服务实时数据。分析返回值为可选服务，如果你需要实时接收分析返回的值，则开启此订阅，并配置要返回的参数。具体参数见下表。

注意：Subscribe有两种Response
- 订阅成功Response
- 订阅数据Response

注意：服务需要在后台开通相关权限才可访问。

Request

{
    "services": "affective",
    "op": "subscribe",
    "kwargs": {
        cloud_service1: [   # 云计算服务类型，attention、relaxation、pressure等
            data_type1, data_type2, data_typeN  # 数据类型，详见情感云计算服务 参数 列
        ],
        cloud_serviceN: [
            data_type1, data_type2, data_typeN
        ]   
    }
}

订阅状态Response 订阅成功后的状态返回值。会返回所有正在订阅中的计算服务。

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "subscribe"
    },
    "data": {
        "sub_" + cloud_service1 + "_fields": [   # cloud_service1: 云计算服务类型，attention、relaxation、pressure等
            data_type1, data_typeN, # 已订阅数据，详见情感云计算服务参数列
        ]
        "sub_" + cloud_serviceN + "_fields": [
            data_type1, data_typeN,
        ]
    }
}

订阅数据Response

返回的数据取决于 Affective Subscribe 时设置的数据。

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "subscribe"
    },
    "data": {
            cloud_service1: {   # 云计算服务数据类型，attention、relaxation、pressure等
                data_type1: data1,  # 数据类型、数据包，详见情感云计算服务数据表
                data_typeN: dataN,
            },
            cloud_serviceN: {
                data_type1: data1,
                data_typeN: dataN,
            }
        }
    }
}

Affective Unsubscribe

取消订阅情感云计算服务实时数据。

Request

{
    "services": "affective",
    "op": "unsubscribe",
    "kwargs": {
        cloud_service1: [   # 云计算服务类型，attention、relaxation、pressure等
            data_type1, data_type2, data_typeN  # 数据类型，详见情感云计算服务参数列
        ],
        cloud_serviceN: [
            data_type1, data_type2, data_typeN
        ]   
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "unsubscribe"
    },
    "data": {
        "sub_" + cloud_service1 + "_fields": [   # cloud_service1: 云计算服务数据类型，attention、relaxation、pressure等
            data_type1, data_typeN, # 已订阅数据，详见情感云计算服务数据表参数列
        ]
        "sub_" + cloud_serviceN + "_fields": [
            data_type1, data_typeN,
        ]
    }
}

Affective Report

获取云计算服务数据报表。返回从服务开始到执行此操作区间的所有值的分析报表。具体可返回的报表结果见下表。

情感云计算服务数据报表

类别	参数	类型	取值范围	说明
attention	attention_avg	float	[0, 100]	注意力平均值
	attention_rec	list[float]	[0, 100]*k, (k≥10)	注意力全程记录
relaxation	relaxation_avg	float	[0, 100]	放松度平均值
	relaxation_rec	list[float]	[0, 100]*k, (k≥10)	放松度全程记录
pressure	pressure_avg	float	[0, 100]	压力水平平均值
	pressure_rec	list[float]	[0, 100]*k, (k≥10)	压力水平全程记录
pleasure	pleasure_avg	float	[0, 100]	愉悦度平均值
	pleasure_rec	list[float]	[0, 100]*k, (k≥10)	愉悦度全程记录
arousal	arousal_avg	float	[0, 100]	激活度平均值
	arousal_rec	list[float]	[0, 100]*k, (k≥10)	激活度全程记录
sleep	sleep_curve	list[float]	[0, 100]*k, (k≥20)	睡眠曲线，横坐标为8s一个点。连续描绘整个小睡过程的睡眠程度。该值越小表示越接近深睡；该值越大表示越接近清醒
	sleep_point	int	[0, +∞)	入睡点时间轴索引，用于标记入睡点。对应睡眠曲线数组的下标，表示那个数据点用户入睡
	sleep_latency	int	[0, +∞)	入睡用时，单位秒
	awake_duration	int	[0, +∞)	清醒时长，单位秒
	light_duration	int	[0, +∞)	浅睡时长，单位秒
	deep_duration	int	[0, +∞)	深睡时长，单位秒

Request

{
    "services": "affective",
    "op": "report",
    "kwargs": {
        "cloud_services": [
            cloud_service1, # 云计算服务数据类型，attention、relaxation、pressure等
            cloud_serviceN
        ]
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "report"
    },
    "data": {
        cloud_service1: {   # 生物数据类型，attention、relaxation、pressure等
            data_type1: data1,  # 数据类型、数据包 详见情感云计算服务数据报表
            data_typeN: dataN,
        },
        cloud_serviceN: {
            data_type1: data1,
            data_typeN: dataN,
        }
    }
}

Affective Finish

结束某情感云计算服务。

Request

{
    "services": "affective",
    "op": "finish",
    "kwargs": {
        "cloud_services": [
            cloud_service1, # 生物数据类型，attention、relaxation、pressure等
            cloud_serviceN
        ]
    }
}

Response

{
    "code": 0,
    "request": {
        "services": "affective",
        "op": "finish"
    },
    "data": {
        "cloud_service": [
            cloud_service1, # 生物数据类型，attention、relaxation、pressure等
            cloud_serviceN
        ]
    }
}

ErrCode

code	services	desc
400	all	请求异常
404	all	找不到服务
407	auth	找不到app_key、签名错误

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

回车情感云计算 WebSocket 接口文档

综合说明

简介

生物数据基础分析服务

情感计算服务

接入注意事项

测试服务器地址

版本

协议约定

协议基本结构

协议注意事项

服务接口会话协议

Session Create

Session Restore

Session Close

生物数据基础分析服务协议

Biodata init

Biodata Subscribe

Biodata Unsubscribe

Biodata Upload

Biodata Report

情感计算服务协议

Affective Start

Affective Subscribe

Affective Unsubscribe

Affective Report

Affective Finish

ErrCode

Clone this wiki locally