更新记录

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(调用返回不支持提示)。


一、安装

  1. 把 uni_modules/screen-rtmp 整个目录拷贝到你的项目根目录 uni_modules/ 下(或用 HBuilderX 的插件市场导入)。
  2. 插件依赖原生 AAR 与第三方库,必须使用「自定义基座」才能在真机运行;标准基座不含本插件。
  3. 打自定义基座 / 正式包时,宿主工程需与 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 拉取。

隐私、权限声明

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

麦克风

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

无

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

无

许可协议

MIT协议