QPlay 协议框架

QPlay设备描述

目前QPlay最新规范为QPlay 2.0，QPlay所有的功能必须遵循UPnP结构体系。在QPlay规范中，QQ音乐应用充当控制点（Control Point），第三方设备充当媒体渲染器（Media Render）。而媒体渲染器必须实现至少四种服务：音视频传输（AVTransport），播放控制（RenderingControl），连接管理（ConnectionManager）三个标准服务；最后一个为QPlay服务，是QPlay规范最核心的服务，包含QPlay播放列表功能，QPlay认证功能，QPlay设置功能等。该规范定义了QPlay设备的最基础的服务，相应的动作和状态变量，第三方设备都应该支持。
在QQ音乐程序启动后
，将广播发送搜索信息查找设备类型为“urn:schemas-upnp-org:device:MediaRenderer”的设备。当QQ音乐发现设备可用时，将读取描述文件。UPnP的设备描述包含几个信息：设备制造商信息、所有的嵌入式设备定义和设备URL，所有的服务列表和控制URL（controlURL）、事件URL（eventURL）等。
QPlay设备还需要一个标签声明其支持QPlay功能：

<qq:X_QPlay_SoftwareCapability xmlns:qq="http://www.tencent.com">QPlay:VersionNumber</qq:X_QPlay_SoftwareCapability>

其中VersionNumber（版本号）描述了设备支持的QPlay版本，版本号的值可以是1或者2，其中的区别见表。

QPlay各版本功能

Services	QPlay:1	QPlay:2
AVTranpsort	√	√
RenderingControl	√	√
ConnectionManager	√	√
QPlay	N/A	√

AVTransport 服务

该服务必须符合UPnP设备架构1.0版本（UPnP Device Architecture Version 1.0）。QPlay仅支持部分UPnP音视频传输服务（AVTransport）。该服务主要实现音频流的传输控制。

AVTransport服务在设备描述中的模板：

<serviceType>urn:schemas-upnp-org:service:AVTransport:1</serviceType>
<serviceId>urn:upnp-org:service:AVTransport</serviceId>
<controlURL>_urn-schemas-upnp-org-service-AVTransport_control</controlURL>
<eventSubURL>_urn-schemas-upnp-org-service-AVTransport_event</eventSubURL>

RenderingControl 服务

该服务必须符合UPnP设备架构1.0版本（UPnP Device Architecture Version 1.0）。QPlay仅支持部分UPnP播放控制服务（RenderingControl）。该服务使控制点：发现设备所支持的状态变量表；获取任何状态变量当前值；可以改变任何可修改的状态变量；初始化设置。
RenderingControl服务在设备描述中的模板：

<serviceType>urn:schemas-upnp-org:service:RenderingControl:1</serviceType>
<serviceId>urn:upnp-org:service:RenderingControl</serviceId>
<controlURL>_urn-schemas-upnp-org-service-RenderingControl_control</controlURL>
<eventSubURL>_urn-schemas-upnp-org-service-RenderingControl_event</eventSubURL>

ConnectionManager 服务

QPlay仅支持部分UPnP连接管理服务（ConnectionManager）。该服务使控制点：进行控制点和媒体渲染器之间的能力匹配；查找当前网络中正在进行的相关传输信息；设备之间的连接建立和解除。
QQ音乐应用程序通过连接管理服务（ConnectionManager）的“GetProtocolInfo”动作获取媒体格式信息。QPlay规定设备制造商应该支持的格式有：he-aac v2、he-aac v1、lc-aac、mp3。如果扬声器设备想支持高质量的音乐，应该支持OGG和AAC格式。
ConnectionManager服务在设备描述中的模板：

<serviceType>urn:schemas-upnp-org:service:ConnectionManager:1</serviceType>
<serviceId>urn:upnp-org:service:ConnectionManager</serviceId>
<controlURL>_urn-schemas-upnp-org-service-ConnectionManager_control</controlURL>
<eventSubURL>_urn-schemas-upnp-org-service-ConnectionManager_event</eventSubURL>

QPlay服务

QPlay服务是QPlay协议的核心。目前最新版本为QPlay 2.0，QPlay 2.0主要特点有：队列（Queue），认证（Authentication），安装（Setup）。

QPlay服务在设备描述中的模板：

<serviceType>urn:schemas-tencent-com:service:QPlay:1</serviceType>
<serviceId>urn:tencent-com:serviceId:QPlay</serviceId>
<controlURL>/QPlay/Control</controlURL>
<eventSubURL>/QPlay/Event</eventSubURL>

QPlay 服务具有三个明显特点：队列（Queue），认证（Authentication），安装（Setup）。

队列（Queue）

队列使MediaRenderer的曲目列表（或“队列”）的播放和播放控制之间没有相互影响。播放列表可以在设备播放期间进行编辑（edited）和更新（updated）（仅支持SetTracksInfo动作）。某些厂商可能会提供一个叫共享队列的队列，该共享队列仅在厂商自身的控制器中可见。但QPlay队列与该共享队列不同，QPlay的队列只能是QQ音乐的私有队列。

认证（Authentication）

认证为制造商提供了一种展现QPlay认证设备的方式。在QPlay2中，认证是强制性的功能要求。

安装（Setup）

安装为制造商提供了一种通过QQ音乐应用程序的QPlay模式设置扬声器的方式。安装是可选的功能。安装动作在设备的描述中说明，如果QQ音乐应用程序发现设备支持安装，它将尝试调用该动作。

QPlay队列

在QPlay中，队列的数据结构如图所示。

其中TracksMetaData是队列的核心数据结构，使用Json格式的UTF-8来表示。

在歌曲队列中，播放时应该从“trackURIs”中找到一个有效的歌曲曲目URI用于播放，若所以的URI都无效，则QPlay设备应该跳到下一个歌曲进行播放。
QPlay设备的服务中与队列操作相关的动作有：

基于QPlay服务的：插入曲目（InsertTracks）、删除曲目（RemoveTracks）、获取曲目（GetTracksInfo）、设置曲目（SetTracksInfo）、获取曲目总数（GetTracksCount）、获取队列的最大曲目容量（GetMaxTracks）；
基于AVTransport服务的：设置音视频流URI（SetAVTransportURI）、获取当前媒体信息（GetMediaInfo）、获取歌曲时间线位置（GetPositionInfo）、（Seek）、获取传输模式（GetTransportSettings）、设置播放模式（SetPlayMode）以及相关的；

◆ “InsertTracks”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：在QPlay队列的指定位置开始插入一个或多个曲目
● 参数：(in) QueueID – 该值在SetAVTransportURI动作时设置。这个参数必须等于SetAVTransportURI动作中的QueueID。否则，该动作失败，返回错误码（718）。(in) StartingIndex - 在队列插入的起始位置(索引从1开始)。(in) TracksMetaData - 队列曲目信息在TracksMetaData中定义。(out) NumberOfSuccess - 成功插入的曲目数量。
● 错误码：718 – invalid QueueID
● 备注：这个动作是原子的。只有当所有的曲目都成功时，QPlay设备才返回零。否则，QPlay设备返回的非零值，NumberOfSuccess的值应该为零。

◆ “RemoveTracks”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：在QPlay队列的指定位置开始移除一个或多个曲目
● 参数：(in) QueueID – 该值在SetAVTransportURI动作时设置。这个参数必须等于SetAVTransportURI动作中的QueueID。否则，该动作失败，返回错误码（718）。(in) StartingIndex - 在队列移除的起始位置(索引从1开始)。 (in) NumberOfTracks - 要移除的曲目数。如果该值为-1，则从StartingIndex位置开始，到队列末尾的曲目全部移除。(out) NumberOfSuccess - 成功移除的曲目数量。
● 错误码：718 – invalid QueueID
● 备注：这个动作是原子的。只有当所有的曲目都成功时，QPlay设备才返回零。否则，QPlay设备返回的非零值，NumberOfSuccess的值应该为零。

◆ “GetTracksInfo”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：获取一个范围内的曲目信息。
● 参数：(in) QueueID – 该值在SetAVTransportURI动作时设置。这个参数必须等于SetAVTransportURI动作中的QueueID。否则，该动作失败，返回错误码（718）。(in) StartingIndex - 在队列获取的起始位置(索引从1开始)。(in) TracksMetaData - 队列曲目信息在TracksMetaData中定义。(out) NumberOfSuccess - 成功获取的曲目数量。
● 错误码：参考UPnP规范。
● 备注：这个动作是原子的。只有当所有的曲目都成功时，QPlay设备才返回零。否则，QPlay设备返回的非零值，NumberOfSuccess的值应该为零。

◆ “SetTracksInfo”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：替换一个范围内的曲目信息。
● 参数：
(in) QueueID –该值在SetAVTransportURI动作时设置。这个参数必须等于SetAVTransportURI动作中的QueueID。否则，该动作失败，返回错误码（718）。(in) StartingIndex - 在队列替换的起始位置(索引从1开始)。如果该值为-1，则整个队列被替换。(in) NextIndex – 如果NextIndex是一个有效的队列位置，则旧队列的当前播放曲目保持不变，播放完后下一个播放的曲目应该在NextIndex位置。如果NextIndex无效（NextIndex<1或者NextIndex>newPlaylist.length），则当前播放的曲目应该立即停止播放。(in) TracksMetaData - 队列曲目信息在TracksMetaData中定义。(out) NumberOfSuccess - 成功设置的曲目数量。
● 错误码：718 – invalid QueueID
● 备注：这个动作是原子的。只有当所有的曲目都成功时，QPlay设备才返回零。否则，QPlay设备返回的非零值，NumberOfSuccess的值应该为零。如果一个曲目播放失败，应该自动播放下一个曲目。

◆ “GetTracksCount”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：返回QPlay队列中曲目的数量。
● 参数：(out) NrTracks - 曲目数量。
● 错误码：参考UPnP规范。

◆ “GetMaxTracks”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：返回QPlay设备的队列最大支持曲目数量。
● 参数：(out) MaxTracks – 曲目最大数量。
● 错误码：参考UPnP规范。

◆ “SetAVTransportURI”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
● 参数：(in) CurrentURI - 如果该参数用于QPlay队列，它必须是 “qplay://QueueID”的形式。否则，参考UPnP规范。(in) CurrentURIMetaData – 对于QPlay队列来说不需要该参数。可以由InsertTracks，SetTracksInfo提供。QPlay设备使用GetMediaInfo替代“CurrentURIMetaData”的功能。
● 错误码：参考UPnP规范。
● 备注：该动作必须在InsertTracks、RemoveTracks和SetTracksInfo动作之前执行，因为这三个动作都需要QueueID作为其参数。QPlay设备应该记忆上一次控制点的QueueID，若InsertTracks、RemoveTracks和SetTracksInfo动作的QueueID与之不一致，则失败，返回错误码（718）。

◆ “GetMediaInfo”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
如果“CurrentURI”的前缀是“qplay://”，表示当前正在使用QPlay队列，(out) NrTracks - 当前队列的曲目总数，应该GetTrackCount的返回值相同。(out) MediaDuration – 队列所有曲目的播放时间总和。(out) CurrentURI - 返回的“CurrentURI”在SetAVTransportURI动作中被设置。“QueueID”可以用来确定当前队列是否被更改。(out) CurrentURIMetaData - 返回的“CurrentURIMetaData”在SetAVTransportURI动作中被设置。
其余参数符合UPnP规范。如果“CurrentURI”的前缀不是“qplay://”，可以把它当作正常歌曲。
● 错误码：参考UPnP规范。

◆ “GetPositionInfo”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
如果GetMediaInfo动作的“CurrentURI”的前缀是“qplay://”。(out) Track - 当前播放曲目的位置(索引从1开始)。(out) TrackDuration - 当前曲目的“duration”在“TrackMetaData”中。(out) TrackMetaData - 当前曲目的“TrackMetaData”。(out) TrackURI – 当前曲目使用的URI在“TrackURIs”中。其余参数符合UPnP规范。如果GetMediaInfo动作的“CurrentURI”的前缀不是“qplay://”，你可以把它当作正常歌曲。
● 错误码：参考UPnP规范。

◆ “Seek”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
● 参数：
(in) Unit – 如果当前正在使用QPlay队列，而且“Target”是个曲目位置。那么该参数必须是“TRACK_NR”。
● 错误码：参考UPnP规范。

◆ “GetTransportSettings”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
● 参数：
(out) PlayMode – 只能是“NORMAL”、“REPEAT_TRACK”或“REPEAT_ALL”。
● 错误码：参考UPnP规范。

◆ “SetPlayMode”动作
● 服务ID：urn:upnp-org:serviceId:AVTransport
● 功能：DLNA标准定义的动作，一些参数将被重用。
● 参数：(in) NewPlayMode – “NORMAL”: 当前歌曲播放结束后停止播放。“REPEAT_TRACK”: 当前歌曲播放结束后，重新播放当前歌曲。“REPEAT_ALL”: 最后一首歌曲播放结束后，重新播放第一首歌曲。
● 错误码：参考UPnP规范。
最后，在AVTransport服务中。如果有任何状态变量（stateVariable）发送变化，LastChange事件应立即发送已变化的状态变量。而每次状态变量“TransportState”发生改变时，“CurrentTrackMetaData”、“CurrentTrackURI”和“AVTransportURI”这三个状态变量值应该加入到LastChange的事件通知中。

QPlay认证

QPlay2为扬声器制造商的扬声器提供QPlay认证，保证用户的听觉体验。

这种机制有利于各扬声器对用户行为的统一解析，以及提供功能拓展。

扬声器被识别为QPlay认证设备，该设备将会在QQ音乐应用程序中显示为特定的UI定制图标。

QPlay认证是基于UPnP的服务拓展。

制造商ID（Manufacture ID，MID）、设备类型ID（Device Type ID，DID）和预共享密钥（pre-shared key，PSK）由QQ音乐（腾讯公司）分配。
QQ音乐应用程序发送的QPlay发现信息会拓展包含一个随机字符串（Seed）。
扬声器返回的结果有：制造商ID（MID）、设备类型ID（DID）、随机字符串（Seed）与预共享密钥（PSK）相结合的哈希值（计算方式为：Code = MD5[Seed + PSK]）。
QQ音乐应用程序将这些信息转发到QQ音乐服务器。
QQ音乐服务器验证这些信息后，将响应信息返回给QQ音乐应用程序。
QQ音乐应用程序收到QQ音乐服务器的响应后，将决定是否显示为QPlay设备的图标。
QPlay认证功能由QPlay服务中的QPlay认证（QPlayAuth）动作实现。

◆ “QPlayAuth”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：提供Seed，获取认证需要的MID、DID和Code信息。
● 参数：(in) Seed – 随机字符串，由QQ音乐应用程序生成，用于防止重复攻击。(out) Code - Seed与预共享密钥（PSK）的哈希值，PSK由腾讯公司提供，计算方式为：Code = MD5[ Seed + PSK ]。(out) MID - 制造商ID，一般为设备制造商名称。(out) DID - 设备类型ID，一般为扬声器设备名称。
● 错误码：参考UPnP规范。
● 备注：设备制造商向腾讯公司申请QPlay认证后，由设备制造商提供MID和DID，腾讯公司做备份并生成PSK提供给设备制造商。

QPlay设置

QPlay2可以使QPlay服务通过扬声器设备的SetNetwork动作进行WiFi网络设置。
当扬声器设备进入WiFi接入点模式时。QQ音乐应用程序可以通过调用扬声器设备的SetNetwork动作，使扬声器设备获得到SSID和密码等WiFi信息。然后扬声器设备可以用来连接到特定的WiFi网络。

◆ “SetNetwork”动作
● 服务ID：urn:upnp-org:serviceId:QPlay
● 功能：设备连接到特定的WiFi网络。
● 参数：(in) SSID – WiFi网络的名称。(in) Key - WiFi网络的密码。(in) AuthAlgo - 设备信息。(in) CipherAlgo - WiFi加密算法。
● 错误码：参考UPnP规范。
● 备注：该动作是可选的。

DLNA和QPlay的关系

DLNA推出较早，DLNA在数字家庭方面给消费者提供：支持在家庭范围内便捷访问、分享、存储音频视频等流媒体；可以提供方便快捷的浏览图片、管理图片、打印图片的服务；支持娱乐内容的提取并在户外环境播放；以及记录各用户的访问，且支持访问过程的重放等功能。这些优点使得其在数字家庭中占有重要的地位，市面上不少数字家庭设备都支持DLNA功能。

但由于DLNA没有强制认证要求，各大制造商实现功能时可能导致兼容性差。而且DLNA并未深入定义有关多媒体家庭的功能，实现的多媒体功能较为简单。也就导致在多媒体播放体验上较为单一。

QPlay专注于音频分享部分，定义了很多提高音乐分享体验的功能。和DLNA一样选择UPnP架构为基础，使用了UPnP的发现和控制机制。在音频的控制和传输的设计上重用了DLNA的动作，使得QPlay设备拥有兼容DLNA功能的可能。

因此，在QPlay设备设计时兼容DLNA功能，设备就可以支持使用DLNA播放器进行播放控制。