@pickleball/rtmp-native 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pickleball/rtmp-native",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hardware-encoded RTMP publisher for Pickleball Live (device-rtmp delivery mode)",
   "license": "MIT",
   "repository": {
@@ -31,9 +31,9 @@
   },
   "devDependencies": {
     "@types/react": "~19.2.0",
-    "expo": "57.0.4",
+    "expo": "~57.0.14",
     "react": "19.2.0",
-    "react-native": "0.86.0",
+    "react-native": "0.86.2",
     "typescript": "^5.8.0"
   },
   "scripts": {

package/src/PickleballRtmpNative.types.ts

@@ -17,11 +17,53 @@ export interface NativeRtmpBandwidth {
   readonly videoBitrate: number;
 }
 
+/**
+ * Nhiệt/pin của máy — trùng tên trường với `deviceMetrics` phía server.
+ *
+ * `thermal` dùng THANG CỦA ANDROID (`PowerManager.THERMAL_STATUS_*`): 0 none ·
+ * 1 light · 2 moderate · 3 severe · 4 critical · 5 emergency · 6 shutdown.
+ * iOS chỉ có 4 bậc nên native đã quy đổi sang thang này (serious→3,
+ * critical→4) để ngưỡng "máy quá nóng ≥ 3" của dashboard đúng trên cả hai nền.
+ *
+ * Cả hai optional: Android < API 29 không có `thermal`; iOS KHÔNG có
+ * `batteryTempC` (không API công khai nào cho nhiệt độ pin).
+ */
+export interface NativeDeviceHealth {
+  readonly thermal?: number;
+  readonly batteryTempC?: number;
+}
+
+/**
+ * Một lần tiến trình app chết trước đó, theo ApplicationExitInfo của Android 11+.
+ * `reasonName` là tên hằng REASON_* ("PACKAGE_UPDATED", "CRASH", "ANR", "OTHER"…)
+ * — native đã quy đổi để JS/dashboard không giữ bảng mã. `description` là chuỗi
+ * hệ thống tự do, VD "stop com.google.android.webview due to installPackageLI"
+ * hay "SwipeUpClean" (HyperOS). iOS luôn trả mảng rỗng.
+ */
+export interface NativeProcessExit {
+  /** epoch ms lúc tiến trình chết. */
+  readonly at: number;
+  readonly pid: number;
+  readonly reason: number;
+  readonly reasonName: string;
+  readonly description?: string;
+  /** RunningAppProcessInfo.IMPORTANCE_* lúc chết — 100 = đang ở tiền cảnh. */
+  readonly importance: number;
+  readonly status: number;
+}
+
 export interface NativeRtmpStats {
   readonly isConnected: boolean;
   readonly isPublishing: boolean;
   readonly videoBitrate: number;
   readonly currentFps: number;
+  /**
+   * Tổng byte đã RỜI máy qua socket RTMP; -1 = chưa có số liệu. iOS nuôi từ
+   * NetworkMonitor (~1s/nhịp) — watchdog native tự cắt khi số này đứng yên 30s
+   * lúc đang publish (reason "media_stalled") để engine quay số lại. Android
+   * chưa trả trường này.
+   */
+  readonly totalBytesOut?: number;
 }
 
 export interface RtmpPrepareOptions {
@@ -34,6 +76,11 @@ export interface RtmpPrepareOptions {
    * HaishinKit nướng hướng thẳng vào ảnh đã mã hoá nên phải biết trước.
    */
   readonly landscape?: boolean;
+  /**
+   * Camera mở ngay ở lần prepare này. Thiếu = native giữ camera sau mặc định.
+   * Id không tồn tại trên máy sẽ bị native bỏ qua thay vì ném lỗi.
+   */
+  readonly cameraId?: string;
 }
 
 export interface RtmpConnectOptions {
@@ -57,3 +104,96 @@ export interface NativeCameraInfo {
   /** "environment" = camera sau — khớp cách đặt tên của WebRTC. */
   readonly facing: "front" | "environment";
 }
+
+/**
+ * Khả năng điều khiển của ống kính ĐANG gắn — refresh sau mỗi lần đổi lens.
+ *
+ * `supported:false` = control không dùng được trên máy/lens này (hoặc reflection
+ * vào HaishinKit Android không đào được) → UI ẨN control tương ứng, không hiện
+ * nút chết. Degrade từng control, không phải cả sheet.
+ */
+export interface CameraCapabilities {
+  /**
+   * Các mức fps ống kính ĐANG gắn thật sự chạy được, lọc từ {24, 30, 60}.
+   *
+   * Native lọc theo đúng tiêu chí lúc chạy (iOS: có format cùng kích thước với
+   * activeFormat phủ được fps; Android: có AE target range phủ được fps) — cả
+   * hai đều bỏ qua trong im lặng nếu không khớp, nên UI chỉ được chào những
+   * mức có trong đây. Không bao giờ rỗng: thiếu dữ liệu thì trả [30].
+   */
+  readonly supportedFrameRates: readonly number[];
+  readonly zoom: { readonly min: number; readonly max: number; readonly supported: boolean };
+  readonly exposureBias: {
+    readonly min: number;
+    readonly max: number;
+    readonly step: number;
+    readonly supported: boolean;
+  };
+  readonly torch: { readonly supported: boolean };
+  readonly focusLock: { readonly supported: boolean };
+  readonly exposureLock: { readonly supported: boolean };
+}
+
+/**
+ * Ô đặt logo trên khung hình, tính bằng PIXEL của độ phân giải đang encode,
+ * gốc trên-trái. Dựng bằng `logoRect()` của @pickleball/shared.
+ */
+export interface RtmpOverlayLogo {
+  /** File ảnh đã tải về đĩa máy (app cache theo URL). */
+  filePath: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** 0-1. Native nướng thẳng vào pixel vì ScreenObject không có opacity. */
+  opacity: number;
+}
+
+/**
+ * Một lớp overlay ĐỘNG (gif chạy khung / video lặp) — vẽ chồng lên logo tĩnh.
+ * Cùng hệ pixel với RtmpOverlayLogo. `opacity`: gif nướng vào từng khung lúc
+ * decode; video bị ép về 1 (AssetScreenObject không có opacity).
+ */
+export interface RtmpOverlayAnimatedItem {
+  /** Bất biến theo lớp — native tái dùng object/animator theo id. */
+  id: string;
+  kind: "gif" | "video";
+  filePath: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  opacity: number;
+}
+
+/**
+ * Một lớp CHỮ đã điền sẵn (JS điền biến từ tỉ số/metadata — native chỉ VẼ,
+ * không biết template). Cùng hệ pixel với RtmpOverlayLogo; `x` là MỎ NEO theo
+ * `align` (left = mép trái chữ tại x, center = tâm, right = mép phải), `y` là
+ * mép TRÊN của nền (không nền thì của chữ).
+ *
+ * Chữ đổi ~2 lần/phút (mỗi pha bóng) — native cập nhật layer TẠI CHỖ theo `id`,
+ * tuyệt đối không rebuild cả dàn layer (Android: rebuild là restart MediaPlayer
+ * của lớp video — churn đã đo).
+ */
+export interface RtmpOverlayTextItem {
+  /** Bất biến theo lớp — native tái dùng texture/ScreenObject theo id. */
+  id: string;
+  text: string;
+  x: number;
+  y: number;
+  fontSizePx: number;
+  align: "left" | "center" | "right";
+  weight: "regular" | "bold";
+  /** #rrggbb. */
+  color: string;
+  /** 0-1 cho CẢ lớp (chữ + nền) — nướng vào pixel lúc vẽ. */
+  opacity: number;
+  /**
+   * Nền sau chữ — field PHẲNG (Record hai nền tảng không phải lồng object).
+   * Không có bgColor = không nền. Padding/bo góc suy từ fontSizePx theo
+   * OVERLAY_TEXT_BG của shared (0.45/0.25/0.22 × fontSize).
+   */
+  bgColor?: string;
+  bgOpacity?: number;
+}

package/src/PickleballRtmpNativeModule.ts

@@ -1,13 +1,27 @@
 import { NativeModule, requireNativeModule } from "expo";
 import type {
+  CameraCapabilities,
   NativeCameraInfo,
+  NativeDeviceHealth,
+  NativeProcessExit,
   NativeRtmpStats,
   PickleballRtmpNativeEvents,
   RtmpConnectOptions,
+  RtmpOverlayAnimatedItem,
+  RtmpOverlayLogo,
+  RtmpOverlayTextItem,
   RtmpPrepareOptions,
 } from "./PickleballRtmpNative.types";
 
 declare class PickleballRtmpNativeModule extends NativeModule<PickleballRtmpNativeEvents> {
+  /**
+   * Xin quyền camera + mic (iOS, ≥ 0.2.0): SDK 1.0 không còn getUserMedia của
+   * WebRTC để "mượn" hộp thoại quyền, nên hỏi qua AVFoundation TRƯỚC khi
+   * prepare — không thì camera đen im lặng ở lần mở đầu tiên. Android dùng
+   * PermissionsAndroid ở JS (không có hàm này); binary cũ cũng thiếu → JS
+   * PHẢI guard `typeof` trước khi gọi. false = một trong hai quyền bị từ chối.
+   */
+  requestPermissions(): Promise<boolean>;
   /** Mở camera + mic và bắt đầu capture (chưa gửi đi đâu). */
   prepare(options: RtmpPrepareOptions): Promise<void>;
   /** Kết nối tới server RTMP; publish ngay nếu options.publish. */
@@ -22,7 +36,62 @@ declare class PickleballRtmpNativeModule extends NativeModule<PickleballRtmpNati
   setMicrophoneEnabled(enabled: boolean): Promise<void>;
   /** Hạ/nâng bitrate khi mạng đổi — thay cho BWE của WebRTC. */
   setVideoBitrate(bitsPerSecond: number): Promise<void>;
+  /** Bounds + cờ hỗ trợ của lens đang gắn — UI ẩn control có supported:false. */
+  getCameraCapabilities(): Promise<CameraCapabilities>;
+  setZoom(factor: number): Promise<void>;
+  setExposureBias(ev: number): Promise<void>;
+  setFocusLocked(locked: boolean): Promise<void>;
+  setExposureLocked(locked: boolean): Promise<void>;
+  setTorch(enabled: boolean): Promise<void>;
+  /**
+   * Chống chớp đèn (antibanding 50/60Hz). Android-only — iOS không có API
+   * tương đương (sau này đi đường shutter-priority riêng), và build cũ cũng
+   * thiếu hàm: JS PHẢI guard `typeof` trước khi gọi. Không ném khi chưa có
+   * camera — native lưu giá trị và tự áp lại mỗi lần mở camera/đổi lens.
+   */
+  setAntiFlicker(mode: "auto" | "50hz" | "60hz"): Promise<void>;
+  /**
+   * Logo nướng vào khung hình trước encoder; `null` = gỡ.
+   *
+   * Ô đặt logo tính SẴN ở JS bằng `logoRect()` của @pickleball/shared — cùng
+   * công thức dashboard vẽ preview, nên "thấy sao ra vậy". Native cố ý không
+   * tính lại: hai bản công thức lệch nhau được, mà cái lệch bị nướng vĩnh viễn
+   * vào video.
+   *
+   * Có logo thì mixer chuyển sang render offscreen (tốn thêm một vòng vẽ mỗi
+   * khung); `null` trả về passthrough như cũ.
+   */
+  setOverlayLogo(options: RtmpOverlayLogo | null): Promise<Record<string, unknown> | void>;
+  /**
+   * Các lớp overlay ĐỘNG (gif/video) — `null` = gỡ hết. Vẽ CHỒNG LÊN logo/
+   * composite tĩnh theo thứ tự mảng. Build cũ không có hàm này — JS phải guard
+   * `typeof` trước khi gọi. iOS trước; Android chưa có (trả lỗi/undefined).
+   */
+  setOverlayAnimated(items: RtmpOverlayAnimatedItem[] | null): Promise<Record<string, unknown> | void>;
+  /**
+   * Các lớp CHỮ đã điền sẵn (tỉ số/tên đội) — `null` = gỡ hết. Trên cùng mọi
+   * lớp khác. Native cập nhật TẠI CHỖ theo `id` khi chỉ có chuỗi đổi — không
+   * rebuild dàn layer. Build cũ không có hàm này — JS guard `typeof`.
+   */
+  setOverlayTexts(items: RtmpOverlayTextItem[] | null): Promise<Record<string, unknown> | void>;
   getStats(): NativeRtmpStats;
+  /**
+   * Nhiệt/pin của máy cho heartbeat. Không package Expo nào đọc được hai giá
+   * trị này nên phải đi đường native. Mọi trường optional — máy không báo thì
+   * thiếu trường, KHÔNG ném lỗi (đang chạy trong nhịp heartbeat).
+   */
+  getDeviceHealth(): Promise<NativeDeviceHealth>;
+  /**
+   * Hộp đen: các lần tiến trình chết gần đây, mới nhất trước (tối đa `max`,
+   * kẹp 1–16). Android 11+; máy cũ hơn và iOS trả []. Không bao giờ ném.
+   */
+  getProcessExitReasons(max: number): Promise<NativeProcessExit[]>;
+  /**
+   * Chụp 1 ảnh JPEG từ khung hình đang compose → chuỗi base64 (không kèm tiền tố
+   * data:). Dùng cho xem trước từ xa trên dashboard khi previewActive. Ném lỗi
+   * nếu camera chưa chạy (chưa prepare / chưa có frame).
+   */
+  snapshot(): Promise<string>;
   dispose(): Promise<void>;
 }