更新记录
0.1.0(2026-11-16) 下载此版本
支持自定义参数 支持授权校验
平台兼容性
uni-app(5.23)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-vue插件版本 | app-nvue | app-nvue插件版本 | Android | Android插件版本 | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | √ | 0.1.0 | √ | 0.1.0 | 5.0 | 0.1.0 | - | - |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
uni-app x(5.23)
| Chrome | Safari | Android | iOS | 鸿蒙 | 微信小程序 |
|---|---|---|---|---|---|
| - | - | - | - | - | - |
其他
| 多语言 | 暗黑模式 | 宽屏模式 | 蒸汽模式 |
|---|---|---|---|
| × | × | √ | √ |
screen-rtmp —— Android 屏幕共享推流插件(uni-app x / UTS)
把手机屏幕画面(含可选麦克风声音)实时推流到任意地址,支持 rtmp / rtmps / rtsp / srt / udp。
- 采集屏幕(
MediaProjection)→ H.264 硬编 → 推流,低延迟 - 推流地址与全部视频参数(分辨率 / 帧率 / 码率 / GOP)均由调用方传入
- 内置离线授权校验:授权码与 App 包名强绑定,App 内只存公钥,无法伪造
- 未填授权码或校验失败 → 试用模式:画面叠加 45° 水印,并在 60 秒后自动停止推流
平台支持:仅 App-Android。iOS / Web 目前为 STUB(调用返回不支持提示)。
一、安装
- 把
uni_modules/screen-rtmp整个目录拷贝到你的项目根目录uni_modules/下(或用 HBuilderX 的插件市场导入)。 - 插件依赖原生 AAR 与第三方库,必须使用「自定义基座」才能在真机运行;标准基座不含本插件。
- 打自定义基座 / 正式包时,宿主工程需与 AAR 的 Kotlin 版本匹配(见文末「常见问题」)。
目录结构:
uni_modules/screen-rtmp/
├── package.json
├── readme.md
└── utssdk/
├── index.uts # 非 Android 平台默认实现(STUB)
├── app-android/
│ ├── index.uts # UTS 薄壳:参数整理 + 回调转发
│ ├── config.json # 声明 RootEncoder 依赖与 jitpack 仓库
│ ├── AndroidManifest.xml # 权限 + Activity/Service 声明
│ └── libs/
│ └── screen-rtmp-facade.aar # 原生实现(采集/编码/推流/验签/水印)
├── app-ios/index.uts # STUB
└── web/index.uts # STUB
二、快速开始
import {
scStart, scStop, scSetStateCallback, scGetRuntimeInfo, scGetPackageName
} from "@/uni_modules/screen-rtmp"
// 1)(可选)注册状态回调,便于把推流状态展示到界面
scSetStateCallback((state: string, message: string) => {
console.log("screen-rtmp:", state, message)
})
// 2) 启动推流:会先弹出系统「录屏授权」对话框,用户点确认后才真正开始推流
const r = scStart({
license: "", // 授权码;留空 = 试用模式(水印 + 60 秒)
url: "rtmp://your.server:1935/live/streamKey",
withAudio: false, // 是否采集麦克风音轨
video: {
width: 720,
height: 1280,
fps: 30,
bitrate: 2500000, // 单位 bps
gop: 2 // 关键帧间隔(秒)
},
android: {
notifTitle: "屏幕共享中",
notifText: "正在向直播服务器推送屏幕画面"
}
})
console.log("start →", r) // 返回 "OK: ..." 仅表示流程已发起,真实状态看回调
// 3) 停止推流并释放资源
scStop()
三、参数详解
scStart(options) / scSetOptions(options) 的 options 结构:
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
url |
string |
无(必填) | 推流地址。按前缀自动路由:rtmp:// rtmps:// rtsp:// srt:// udp:// |
license |
string \| null |
null |
授权码。为空或校验失败 → 试用模式(水印 + 60 秒自动停推) |
withAudio |
boolean \| null |
false |
是否采集麦克风音轨并混入推流 |
video |
object \| null |
见下 | 视频编码参数,不传则使用原生默认值 |
video.width |
number |
720 |
视频宽(像素) |
video.height |
number |
1280 |
视频高(像素) |
video.fps |
number |
30 |
帧率 |
video.bitrate |
number |
2500000 |
码率(bps) |
video.gop |
number |
2 |
关键帧间隔(秒),影响首屏与 seek 速度 |
android |
object \| null |
见下 | 仅 Android:前台服务通知文案 |
android.notifTitle |
string |
屏幕共享中 |
通知标题 |
android.notifText |
string |
正在向直播服务器推送屏幕画面 |
通知内容 |
默认值即为兼容性最佳的组合:H.264 + 720×1280 + 30fps + 2.5Mbps + 2s GOP,绝大多数 RTMP 服务端/播放器(含 HTTP-FLV、HLS、WebRTC 网关)都能直接转发与播放。若只是快速接入,
video整个字段都可以不传。
四、API
| 方法 | 说明 |
|---|---|
scStart(options) |
下发参数 → 校验授权码 → 申请录屏授权 → 用户确认后推流。返回 OK: 仅表示流程已发起 |
scStop() |
停止推流并释放采集/编码资源 |
scSetOptions(options) |
仅更新参数(地址/分辨率等),不启动推流 |
scIsAuthorized() |
当前是否已通过授权码校验 |
scGetRuntimeInfo() |
返回 { authorized, trial, watermarkText, maxDurationMs } |
scSetStateCallback(cb) |
注册状态回调 (state, message) => void |
scSetErrorCallback(cb) |
注册错误回调(由 state === "error" 触发) |
scGetPackageName() |
当前 App 包名(申请授权码时需提供此值) |
scLastMsg() |
最近一次操作的文本结果(排障用) |
state 取值:
connecting / connected / streaming / disconnected / failed / auth_error / auth_ok / error / warn / trial_end / stopped
常量:SC_TRIAL_LIMIT_MS = 60000、SC_TRIAL_WATERMARK_TEXT
五、授权码与试用模式
授权码格式
license = base64url(payload) + "." + base64url(SHA256withRSA(payload))
payload:
{ "v": 1, "product": "screen-rtmp", "pkg": "com.your.app", "exp": 0 }
pkg必须与 App 的packageName完全一致(用scGetPackageName()获取)exp = 0表示永久有效;否则为到期时间(毫秒时间戳)- App 内仅内置公钥做离线验签,私钥只在签发方手里,无法在客户端伪造
试用模式
未提供授权码、或授权码与包名不匹配 / 已过期时:
- 画面叠加 45° 水印(居中、描边白字,整块按原始像素绘制,不会被拉伸)
- 推流在 60 秒后自动停止,并回调
state = "trial_end" - 其余功能与已授权一致
生成授权码(签发方本机执行)
cd tools/license
node license-tool.js gen --pkg com.your.app --days 365
客户提供包名 → 生成对应授权码 → 客户填入 scStart({ license }) 即解除限制。
六、示例工程
screen-rtmp 的示例工程演示了:自行填写推流地址、在线调整分辨率/帧率/码率/GOP、切换音轨、查看授权与试用状态。工程默认不填授权码,因此运行时即处于试用模式(带水印),便于直接体验。
七、常见问题
Q:真机运行报「找不到插件」/ 功能不生效? 必须使用包含本插件的自定义基座(或正式包)。标准基座不含插件。
Q:修改了插件(含 AAR)后? 需要重新制作自定义基座才会生效。
Q:打正式包时报 Kotlin metadata 版本不兼容? 本插件的 AAR 由 Kotlin 2.2 编译。请确保宿主工程的 Kotlin 版本与之匹配(过低会报 metadata 不兼容)。
Q:关闭音频会崩溃?
已修复。插件在关闭音轨时仍会初始化音频编码器(但不产生音频轨道),不会再抛 audioEncoder not prepared yet。
Q:推流成功但播放端放不出? 先确认服务端已正确开启对应输出:RTMP 拉流需服务端提供 HTTP-FLV / HLS 输出,WebRTC 需有 WHEP/WHIP 网关。插件推的是标准 H.264/AAC 的 RTMP 流,通用。
Q:能推 RTSP/SRT/UDP 吗?
可以,url 前缀即协议。地址按前缀自动路由。
八、构建原生层(维护者)
cd native-facade/screen-rtmp-facade
gradle assembleRelease
# 产物 app/build/outputs/aar/app-release.aar
# 拷贝为 utssdk/app-android/libs/screen-rtmp-facade.aar
依赖 RootEncoder 2.8.1(Apache-2.0),由 config.json 声明,宿主打包时从 jitpack 拉取。

收藏人数:
下载插件并导入HBuilder
下载示例项目ZIP
赞赏(0)
下载 4181
赞赏 0
下载 12770358
赞赏 1959
赞赏
京公网安备:11010802035340号