更新记录

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 地址再投。

注意事项

  1. Android 14+ 录屏必须走前台服务。插件已在 AndroidManifest.xml 里声明 RecordService(foregroundServiceType="mediaProjection")与 FOREGROUND_SERVICE_MEDIA_PROJECTION 权限,因此需要自定义基座才生效。
  2. 授权是一次性的。Android 14 起 MediaProjection token 单次有效,每次 startRecord 都会重新弹系统授权框,这是系统行为。
  3. Android 15+ 锁屏会自动停止录制,状态栏还会出现录制中的芯片,用户可以一键终止。插件监听 MediaProjection.Callback.onStop 做收尾。
  4. 电视兼容性。不同品牌的 DIDL-Lite 解析宽容度不同,插件对内联元数据做了转义与标准化,但极端情况仍可能被个别盒子拒绝。建议先用主流电视/盒子验证。
  5. 必须同网段。手机与电视要在同一个 WiFi、同一个子网,且路由器不能开启 AP 隔离。
  6. 本地 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+)
  • 需要自定义基座(含前台服务声明与权限)

隐私、权限声明

1. 本插件需要申请的系统权限列表:

录屏需用户每次授权(系统弹窗);投屏需网络与局域网多播权限;Android 14+ 录屏使用前台服务并显示常驻通知

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件不采集、不上传任何数据;投屏与录屏均在局域网内完成

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。