更新记录
1.0.0(2026-11-19)
首次发布:完成 Android / HarmonyOS 双端实现与真机验证。
平台兼容性
uni-app x(4.25)
| Chrome |
Safari |
Android |
iOS |
鸿蒙 |
微信小程序 |
| × |
× |
√ |
× |
√ |
× |
其他
| 多语言 |
暗黑模式 |
宽屏模式 |
蒸汽模式 |
| × |
× |
× |
√ |
uni-cast-screen · 投屏与录屏
一个插件解决两件相邻的事:屏幕录制(输出 MP4)和 DLNA 投屏(把视频投到电视)。全部用系统能力实现,不引三方 SDK、不需要推流服务端。
能力
| 能力 |
说明 |
| 屏幕录制 |
MediaProjection + VirtualDisplay + MediaRecorder,输出 MP4;支持分辨率、帧率、码率、是否录声音 |
| 设备发现 |
SSDP(M-SEARCH)扫描局域网内的 DLNA 渲染器,返回设备名、厂商、控制地址 |
| 投屏播放 |
SOAP SetAVTransportURI + Play,支持本地文件与 http(s) 链接 |
| 播放控制 |
播放 / 暂停 / 停止 / 快进(Seek) |
| 进度查询 |
GetTransportInfo + GetPositionInfo,返回播放状态、当前进度、总时长 |
| 局域网文件服务 |
内置 HTTP 服务(支持 Range),把本地视频变成电视可拉取的 URL,能拖进度 |
快速上手
屏幕录制
import { startRecord, stopRecord, getRecordState } from '@/uni_modules/uni-cast-screen'
startRecord({
fps: 30,
bitRate: 4000000,
audio: false, // 是否录麦克风
success: (res) => console.log('录制中', res.path, res.width, res.height),
fail: (err) => console.log(err.errMsg),
})
// 轮询时长
getRecordState({ success: (res) => console.log(res.recording, res.duration) })
// 停止并落盘
stopRecord({ success: (res) => console.log('已保存', res.path, res.duration + 's') })
投屏到电视
import { searchDevices, castMedia, castControl, getCastState, stopCast } from '@/uni_modules/uni-cast-screen'
// 1. 搜索设备(默认 4 秒超时)
searchDevices({
timeout: 4000,
success: (res) => {
console.log('发现', res.count, '台')
res.devices.forEach((d) => console.log(d.name, d.controlUrl))
},
})
// 2. 投屏:传本地路径会自动起 HTTP 服务,传 http 链接直接推过去
castMedia({
controlUrl: device.controlUrl,
url: '/storage/emulated/0/Movies/demo.mp4',
title: '我的视频',
success: (res) => console.log('电视正在播放', res.url),
})
// 3. 控制
castControl({ controlUrl: device.controlUrl, action: 'pause' })
castControl({ controlUrl: device.controlUrl, action: 'seek', position: 120 })
// 4. 查进度
getCastState({
controlUrl: device.controlUrl,
success: (res) => console.log(res.playing, res.position, res.duration),
})
// 5. 停止并释放本地服务
stopCast({ controlUrl: device.controlUrl })
API
| 方法 |
参数 |
说明 |
startRecord(options) |
{path?, width?, height?, fps?, bitRate?, audio?} |
弹系统授权后开始录制 |
stopRecord(options) |
— |
停止并落盘 |
getRecordState(options) |
— |
查询是否录制中、路径、尺寸、已录时长 |
searchDevices(options) |
{timeout?, deviceType?} |
搜索设备,deviceType 默认 MediaRenderer |
castMedia(options) |
{controlUrl, url, title?, mimeType?} |
投屏并开始播放 |
castControl(options) |
{controlUrl, action, position?} |
play / pause / stop / seek |
getCastState(options) |
{controlUrl} |
播放状态与进度 |
stopCast(options) |
{controlUrl?} |
停止投屏,释放本地 HTTP 服务 |
平台差异
| 能力 |
Android |
鸿蒙 |
| 屏幕录制 |
支持(MediaProjection + 前台服务) |
支持(AVScreenCaptureRecorder) |
| 搜索设备 |
支持(SSDP 多播) |
支持(UDPSocket) |
| 投屏 http 链接 |
支持 |
支持 |
| 投屏本地文件 |
支持(内置 HTTP 服务) |
不支持,传本地路径返回 9100007 |
鸿蒙端没有内置局域网 HTTP 服务,本地文件请先上传到可访问的 http 地址再投。
注意事项
- Android 14+ 录屏必须走前台服务。插件已在
AndroidManifest.xml 里声明 RecordService(foregroundServiceType="mediaProjection")与 FOREGROUND_SERVICE_MEDIA_PROJECTION 权限,因此需要自定义基座才生效。
- 授权是一次性的。Android 14 起 MediaProjection token 单次有效,每次
startRecord 都会重新弹系统授权框,这是系统行为。
- Android 15+ 锁屏会自动停止录制,状态栏还会出现录制中的芯片,用户可以一键终止。插件监听
MediaProjection.Callback.onStop 做收尾。
- 电视兼容性。不同品牌的 DIDL-Lite 解析宽容度不同,插件对内联元数据做了转义与标准化,但极端情况仍可能被个别盒子拒绝。建议先用主流电视/盒子验证。
- 必须同网段。手机与电视要在同一个 WiFi、同一个子网,且路由器不能开启 AP 隔离。
- 本地 HTTP 服务端口随机,服务生命周期跟随
castMedia / stopCast,不投屏时不会常驻。
错误码
| 错误码 |
说明 |
| 9100001 |
参数错误 |
| 9100002 |
录屏权限被拒绝 |
| 9100003 |
当前没有进行中的录制 |
| 9100004 |
录屏失败 |
| 9100005 |
未发现可投屏设备 |
| 9100006 |
投屏连接失败,请确认手机与电视在同一网络 |
| 9100007 |
当前平台不支持该能力 |
| 9100008 |
文件不存在或不可读 |
兼容性
- Android 5.0+(API 21),录屏建议 Android 10+
- HarmonyOS NEXT
- uni-app x(HBuilderX 4.25+)
- 需要自定义基座(含前台服务声明与权限)