企业官网建设流程全解析

简介：面向 Android 开发者的 DLNA 协议实现工程，以 Cling 开源库为基础，完整覆盖数字媒体渲染器（DMR）、数字媒体控制器（DMC）与数字媒体服务器（DMS）三大功能模块，并演示了设备发现、媒体浏览、播放控制和资源共享的衔接方式。压缩包约 53.73MB，共 7234 个文件，既有 Java 源码、XML 配置、Gradle 构建脚本等可读内容，也包含编译生成的 class、dex、jar、APK 等产物；文件类型覆盖源码、资源、配置、依赖与安装包，导入 Android Studio 后可核对整个构建链路。资源按 DMR、DMC、DMS 的角色拆解了实现重点：DMS 将本地媒体目录暴露给网络，DMC 负责查找设备并下发播放指令，DMR 则承担媒体渲染与状态反馈，结合 Cling 库说明 UPnP/DLNA 协议在 Android 平台的落地细节，同时保留工程说明、许可证等文档，适合做二次开发或协议学习。已有 2328 人学习下载，对关注投屏、多屏互动和家庭媒体共享的开发者具有直接参考价值。 做投屏类App开发的时候，DLNA这三个字母基本绕不开。我最近刚好把一个支持DMR、DMC、DMS三端角色的整套DLNA功能在Android上完整落地，踩了不少坑，也把协议细节摸了个透。这篇文章把我在Android端的实现思路、关键代码路径、联调问题和排查方法整理出来，给准备搞同类型项目的朋友一个参考。

这篇内容适合谁看？一是要在Android设备上实现“被投屏”能力的人，对应DMR角色；二是要做“手机控制电视/盒子/音响播放”的人，对应DMC角色；三是要把手机本地媒体共享给局域网设备的人，对应DMS角色。如果三个角色都要做，那这篇文章正好是一份从0到1的路线图。

1. 整体方案与协议栈拆解

1.1 认识DLNA三件套：DMS、DMC、DMR各自的职责边界

DLNA本质上是基于UPnP协议做的一套媒体互通规范。UPnP定义了设备发现、设备描述、服务调用、事件通知这套骨架，DLNA则在上面规定了媒体内容的格式标准、设备类型和交互行为。理解“UPnP是骨架、DLNA是血肉”这点很关键，后面很多问题排查都要靠这个认知。

在DLNA体系里，最常见的三个角色分别是：

• DMS（Digital Media Server）：媒体服务器，负责把本地媒体文件（视频、图片、音频）共享出去，暴露给网络上的其他设备。
• DMC（Digital Media Controller）：媒体控制器，负责发现DMS和DMR，并且指挥DMR去播放DMS上的内容。它就是“遥控器”角色，本身不播放也不存媒体。
• DMR（Digital Media Renderer）：媒体渲染器，负责接收DMC下发的播放指令，拉取DMS上的媒体流并播放。

在Android端的实际工程里，一个App可以同时实现这三种角色。比如手机既能当DMC控制电视播放，也能作为DMR接收其他设备的投屏，还能把自己的相册共享出去给别人拉取。三种角色的协议基础共通，但各自要打通的UPPnP服务完全不同，所以实现上建议分模块解耦，不要揉在一起。

1.2 Android端技术选型：UPnP框架与播放内核

在Android上实现DLNA，第一步是选UPnP协议栈。市面上常见的开源方案有Cling、CyberGarage、Platinum等，各有侧重。

我的选择是CyberGarage作为UPnP协议层。原因很简单：它非常薄，封装不多，开发者能直接看到SOAP报文和SSDP交互细节，调试起来很直观。相比之下Cling封装得很“舒服”，内部逻辑更现代，但出了问题时你会花很多时间在理解它的抽象层上。对于需要同时实现DMS/DMC/DMR三个角色的场景，能直接控制协议交互细节，是极大优势。另一个方案是Platinum，性能和稳定性好，但C++代码维护成本偏高，如果团队只有Java/Kotlin背景，我建议慎重。

播放内核方面，DMR角色推荐直接用ExoPlayer。因为播放器需要支持HTTP拉流、Seek、暂停/恢复，以及多种封装格式，ExoPlayer在这块的扩展性明显好于MediaPlayer。尤其到了后续要支持HLS、Dash或者自适应码率时，ExoPlayer能平滑过渡。

1.3 实现前必须想清楚的几个问题

动手写代码之前，有些问题是绕不开的，需要先想明白：

第一，网络通信是走Socket还是走HTTP？SSDP设备发现必须走UDP组播和多播，而SOAP控制指令走HTTP/TCP，媒体流传输走HTTP/TCP。这三个通道各司其职，不能合在一起。

第二，线程模型怎么设计？SSDP监听需要独立线程，SOAP协议处理需要每个请求独立处理，媒体流服务则需要独立的HTTP服务线程池。如果混在同一个线程里，设备发现扫描时播放会卡顿，这是新手最容易犯的错。

第三，Android版本兼容怎么做？Android 6.0之后多了运行时权限，Android 9开始限制了明文HTTP流量，Android 11加强了包可见性限制，这些都会影响DLNA功能的调试和运行。一开始就把这些兼容性问题考虑进去，能省掉后面大量回头改代码的时间。

2. DMR角色实现：让Android设备能接收投屏

2.1 服务暴露：AVTransport与RenderingControl

DMR角色的核心是向外暴露UPnP服务。DLNA规范要求DMR至少要暴露两个服务：AVTransport和RenderingControl。AVTransport负责“播什么、怎么播”，RenderingControl负责“音量、静音、亮度等渲染参数”。

用CyberGarage实现服务暴露的套路是：定义服务名、服务类型、服务版本、服务action列表和事件变量表，然后实现action对应的处理函数。要注意UPnP服务类型的命名有严格格式，例如AVTransport服务类型是urn:schemas-upnp-org:service:AVTransport:1，这里的版本号必须有，并且要与设备描述XML里的声明一致，一旦不一致，绝大多数控制点会直接忽略这个设备。

关键点：AVTransport的action列表是按InstanceID组织的。InstanceID在DLNA规范里几乎是常数0，但一定要在SOAP Action的参数里带上。很多DMC会严格校验InstanceID，漏了就直接返回错误。

2.2 播放状态机与SOAP Action处理

AVTransport服务里最核心的四个Action是SetAVTransportURI、Play、Pause和Stop，另外SetNextAVTransportURI和Seek也要尽早实现。它们对应了完整的播放控制链路。

以SetAVTransportURI为例，控制点会传入CurrentURI（媒体地址）和CurrentURIMetaData（媒体元数据）。DMR收到后，需要解析URI，判断协议头（HTTP还是本地文件），然后准备好播放器实例，但此时不要立即播放，要等Play指令到达后再调用play。这个“先预加载、再播放”的二阶段设计，是DLNA交互的关键，能够保证控制端精确控制播放时机。

我实现的时候，状态机是这样维护的：

• STOPPED：初始状态，播放器空闲。
• TRANSITIONING：收到SetAVTransportURI，正在准备播放器，此时如果收到Play，需要等准备完成再切换。
• PLAYING：播放中。
• PAUSED_PLAYBACK：暂停。

每次状态切换都要更新TransportState变量，并且向订阅了事件的DMC发送LastChange通知。很多DMC的UI和控制逻辑都依赖这个状态变化来刷新按钮状态，如果你忽略了事件推送，控制端会一直显示“停止”，用户点了播放也没反应。

2.3 事件订阅与状态上报

UPnP的事件订阅机制用的是GENA，基本原理是DMC发送SUBSCRIBE请求，DMR返回SID和一个回调URL，之后状态变化时DMR主动往这个回调URL推送NOTIFY消息。订阅有效期通常1800秒，到期后DMC需要重新SUBSCRIBE，DMR这边要做的是实现一个订阅管理器，记录当前订阅方列表，状态变化时广播。

实际项目中，很多DMC只订阅一次就不再续订，如果DMR状态变化时发现订阅方列表空了，就要做好降级处理。另外，事件推送的XML格式有规范要求，LastChange的结构是<Event><InstanceID val="0"><TransportState val="PLAYING"/></InstanceID></Event>，这里不能用自定义格式，否则像Windows Media Player、小米电视这类严格实现对不会认。

DMR还有一个容易忽略的点：RenderingControl服务的Volume变量需要支持事件推送。用户调节电视音量时，控制端要能看到实时音量值变化，否则会出现控制端和实际音量不同步的体验问题。

3. DMC角色实现：搜索、发现与远程控制

3.1 SSDP设备发现与描述解析

DMC要做的第一件事是发现局域网内的DMS和DMR设备。标准做法是往组播地址239.255.255.250:1900发送M-SEARCH报文，然后等待设备返回响应。M-SEARCH的请求头里有一个非常重要的参数：ST: urn:schemas-upnp-org:device:MediaRenderer:1或MediaServer:1，用来指定你要找的设备类型。

Android端这里有一个经典的坑：WifiManager的MulticastLock。很多Android设备默认会过滤组播包，不获取组播锁就收不到任何设备响应。我第一次联调时就栽在这里，整整查了两天才发现是用UDP那条链路根本没收到数据。正确姿势是：

WifiManager wifi = (WifiManager) context.getSystemService(Context.WIFI_SERVICE); MulticastLock lock = wifi.createMulticastLock("dlna-discovery"); lock.acquire();

拿到设备响应后，报文里会带有LOCATION字段（一个设备描述XML的URL），DMC需要去解析这个XML，拿到设备名称、UUID、服务列表。这里要注意处理XML里的特殊字符，有些电视厂商会在设备名称里放引号、&号之类，不转义的话XML解析直接失败，而且你根本拿不到任何报错，只会发现设备列表里少了一台设备。

3.2 AVTransport控制指令的构造与发送

DMC向DMR下发控制，靠的是通过HTTP POST发送SOAP Action。SOAP报文本身有一些非常严格的格式要求，最容易踩坑的我有以下几个：

SOAPAction头不能省。格式要求是"urn:schemas-upnp-org:service:AVTransport:1#Play"，注意是带引号的双引号包裹，很多库不会自动加引号，导致个别DMR不认。

Content-Type必须指定为text/xml; charset="utf-8"，且大小写要严格，很多实现写成了text/XML，也被会直接拒绝。

请求体必须有完整的SOAP envelope标签。网上找的很多简化示例删掉了命名空间声明，真正联调时控制点和渲染器不在同一个UPnP SDK下就会出现“Unsupported Action”之类的报错。

一个完整的Play指令大概长这样（这在行业里几乎所有UPnP实现都通用）：

<?xml version="1.0" encoding="utf-8"?> <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <s:Body> <u:Play xmlns:u="urn:schemas-upnp-org:service:AVTransport:1"> <InstanceID>0</InstanceID> <Speed>1</Speed> </u:Play> </s:Body> </s:Envelope>

3.3 多设备协同与应用侧状态同步

DMC在实际使用中不是只发指令就完了。比如手机当遥控器控制电视播放的同时，用户可能在手机上切歌、加音量，这些操作要实时同步到电视上，而且电视端播放状态变化（比如片源播完了、用户手动按了电视遥控器）也要能回传手机。

DMC侧需要在发现DMR后，立即向它的AVTransport和RenderingControl服务发送SUBSCRIBE，并且维护一个订阅有效期。这里有个经验性操作：把订阅有效期设置为规范支持的1800秒上限，但定时器设到600秒就提前续订一次。原因是很多电视盒子在WiFi休眠或机型差异下会提前干掉旧订阅，等真正到期再续订时已经来不及了。

另外，DMC往往要同时显示DMS里的媒体目录和DMR的状态。建议将DMS的Browse结果缓存到本地数据库，避免每次打开媒体库都去发一遍SOAP请求，响应速度能提升一个量级。Message推送的事件接收服务建议用独立的LocalBroadcast或Channel机制来解耦UI，防止播放器回调频繁刷新把UI线程卡死。

4. DMS角色实现：媒体库管理与流媒体输出

4.1 ContentDirectory服务：目录浏览与DIDL-Lite

DMS角色的核心是ContentDirectory服务，它负责向控制点返回媒体目录结构。最常见的操作是Browse，参数包括ObjectID（目录对象ID）、BrowseFlag（BrowseDirectChildren或BrowseMetadata）、Filter、StartingIndex、RequestedCount和SortCriteria。

返回结果是一个DIDL-Lite XML文档。DIDL-Lite的格式规范非常细，从根命名空间到元素属性都有严格要求。

我实现了三种基础对象类型：

• object.container.storageFolder：文件夹，包含子目录和子项。
• object.item.videoItem：视频文件。
• object.item.audioItem：音频文件。
• object.item.imageItem：图片文件。

实现时要注意容器对象的childCount属性必须正确。很多DMC会用它来显示“N个视频”，如果写错，会出现界面显示了内容但点击进去空白的情况。

4.2 HTTP流媒体服务与Range请求

DMS的另一个核心是HTTP媒体流服务。控制点告诉DMR去某个URI拉流，DMR就会直接在HTTP层请求数据。这里最关键的是要正确处理Range请求。用户快进/快退时，播放器会发送Range: bytes=xxx-请求，如果服务器忽略或不正确响应Range，DMR会直接卡死在Seek操作上。

正确的响应方式是这样的：

HTTP/1.1 206 Partial Content Content-Type: video/mp4 Content-Range: bytes 1048576-2097151/10485760 Content-Length: 1048576 Accept-Ranges: bytes

这里还有个容易忽略的点：如果视频文件本身不支持Seek（比如某些MP4的moov原子在文件末尾），DMR再发Range请求也会失败。建议在DMS侧提供媒体转封装能力，或者在索引媒体时提前处理好moov原子位置。实操中，我用的是MP4Parser把moov挪到文件头，几百兆的视频处理也就一两个毫秒，但Seek成功率能提升到100%。

4.3 媒体格式合规与转码策略

DLNA对媒体格式有严格限制。举个例子，如果是DMS共享视频给电视播放，电视端DMR往往只支持特定的Profile，如AVC视频+AAC音频封装到MPEG-TS或特定MP4容器。如果手机本地文件是RMVB、MKV内嵌特效字幕或者H.265高码率，直接共享给很多电视会黑屏无声。

业内相对稳妥的做法是：DMS在Browse返回元数据时，先做一次探测，如果判断文件格式不合规，就在资源URL上带一个参数（如?transcode=1），并在HTTP服务端对应当转码会话。转码可以用FFmpeg做软解软编，但要注意性能和并发数限制，一台上古手机同时转码两个1080p视频基本就是极限了。

我建议更务实的做法是：优先保证兼容性，转码仅作兜底。实现时可以做一个媒体探测流程，用MediaExtractor快速读取容器格式和编码信息，只有确认不合规时才触发转码。另外要留意码率不能随便设太高，无线网络环境下4Mbps到8Mbps是多数设备比较稳的范围。

5. 联调实测与高频问题排查

5.1 收不到设备发现广播：MulticastLock与WiFi网络

现象：同一WiFi下，手机作为DMC扫描不到电视/盒子设备，或者在部分路由器下必须切换网络才能发现。
排查思路：

1. 先确认MulticastLock已经获取且没有被释放。
2. 检查手机和电视是否在同一个网段。部分路由器开启了AP隔离（Client Isolation），会导致组播包无法互通。这个问题在访客WiFi和部分酒店WiFi上非常常见。
3. 用抓包工具看一眼UDP 1900端口是否有报文发出。如果没有M-SEARCH出包，多半是线程被回收或者代码没真正执行到发送逻辑。

处理：在App的WiFi连接状态变化时要重新获取锁；在路由器的管理页面关闭AP隔离；也可以增加一个“手动添加设备”的兜底入口，输入LOCATION URL直接加载设备描述。用户遇到设备扫描不到时，至少还能手动连接，提升体验不少。

5.2 SOAP调用失败与HTTP细节

现象：设备能发现、能获取描述，但是点击播放后没有任何反应，日志里能看到HTTP 500或SOAP错误响应。

排查思路：

用打印完整报文的方式去对比规范。我实际联调过几家电视盒子后发现，最常见的错误有三个：

• SOAPAction头写错大小写或漏了引号。
• Content-Type没有带charset，导致某些设备解不了UTF-8。
• 请求体里某个参数名写成了小写首字母（例如instanceID代替InstanceID），设备直接返回401 Invalid Action。

还有一种情况：DMR本身已处于播放状态，DMC再次下发SetAVTransportURI，没有先停掉当前会话，部分严格实现会返回TRANSITION_NOT_ACCEPTED。所以DMC侧在发起新播放前，建议先发Stop，确认返回成功后再走SetURI+Play流程。

5.3 播放中断、Seek失败与兼容性

现象：播放到一半卡住、拖动进度条无效、或者某些视频在电视上只有声音没有图像。

排查思路：

播放中断首先排查网络，特别是DMS的HTTP响应头。有没有设置Content-Length？DMR依赖它来判断文件大小，没有就无法正确显示进度条，甚至播完一段就认为流终结。另外Accept-Ranges: bytes必须带上，没有这个头基本和Seek无缘。

有声音没图像，基本就是格式兼容性问题了。可以看DMR设备描述里的ProtocolInfo，它列了该设备支持的媒体格式和Profile。DMS侧最好在建索引时就拿这个去筛选，匹配不上的文件直接在UI上标记“可能无法播放”，比用户点进去再失败体验好得多。

5.4 同一App内三角色同时运行时的资源冲突

现象：DMS正在共享视频时，本机DMR又在播放别的流，结果两个HTTP服务端口冲突或者网络速度互相挤占。

处理：

三个角色最好分别使用独立的端口号，并且端口绑定要支持配置化。DMS的HTTP服务建议在配置里允许指定端口范围，比如8070-8090，端口被占用时自动递增重试。DMR拉流时要做好缓存和缓冲，不要让网络抖动直接导致播放中断。

另外，如果产品不需要同时开启三个角色，强烈建议做成运行时切换模式。默认只开启当前用户使用的那一个角色，需要时再动态启动其他服务。这样不仅省电，也大幅降低联调复杂度。

最后分享一个实际操作中的小经验：调试DLNA功能时，建议电脑上装一个UPnP调试工具，比如Device Spy或者自写一个轻量的SOAP测试器，还有一个技巧是边调试边用日志输出完整的HTTP报文头和SOAP请求体。DLNA最让人头疼的往往不是逻辑复杂，而是你根本没看到设备返回的错误细节。把这些报文完整打出来，对照规范逐个字段检查，90%的问题都能在半小时内定位。我自己做的三端角色整套功能，从0到稳定跑通，大概用了三周时间，其中协议细节联调占了大头。但只要把我在上面列的这些关键路径和坑位理解到位，提前规避掉，你应该能比我快很多。

本文还有配套的精品资源，点击获取