@pickleball/rtmp-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pickleball Live contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/android/build.gradle

@@ -0,0 +1,30 @@
+plugins {
+  id 'com.android.library'
+  id 'expo-module-gradle-plugin'
+}
+
+group = 'expo.modules.pickleballrtmp'
+version = '0.1.0'
+
+android {
+  namespace 'expo.modules.pickleballrtmp'
+  defaultConfig {
+    versionCode 1
+    versionName '0.1.0'
+  }
+  lintOptions { abortOnError false }
+}
+
+repositories {
+  // HaishinKit.kt phát hành qua JitPack, không có trên Maven Central.
+  maven { url 'https://jitpack.io' }
+}
+
+dependencies {
+  implementation 'androidx.core:core-ktx:1.15.0'
+  // Bản Kotlin của HaishinKit. API KHÁC bản Swift: MediaMixer(context),
+  // StreamSession.Builder(...).build(), mixer.registerOutput(...).
+  implementation 'com.github.HaishinKit.HaishinKit~kt:haishinkit:0.18.2'
+  // Module rtmp tách riêng — thiếu nó thì không có RtmpStreamSessionFactory.
+  implementation 'com.github.HaishinKit.HaishinKit~kt:rtmp:0.18.2'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,5 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.CAMERA" />
+  <uses-permission android:name="android.permission.RECORD_AUDIO" />
+  <uses-permission android:name="android.permission.INTERNET" />
+</manifest>

package/android/src/main/java/expo/modules/pickleballrtmp/PickleballRtmpNativeModule.kt

@@ -0,0 +1,340 @@
+package expo.modules.pickleballrtmp
+
+import android.content.Context
+import android.graphics.Rect
+import android.hardware.camera2.CameraCharacteristics
+import android.hardware.camera2.CameraManager
+import android.net.Uri
+import com.haishinkit.media.MediaMixer
+import com.haishinkit.media.source.AudioRecordSource
+import com.haishinkit.media.source.Camera2Source
+import com.haishinkit.stream.StreamSession
+import com.haishinkit.rtmp.RtmpStreamSessionFactory
+import expo.modules.kotlin.functions.Coroutine
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import expo.modules.kotlin.records.Field
+import expo.modules.kotlin.records.Record
+import expo.modules.kotlin.exception.CodedException
+
+/**
+ * Bản Android của cầu nối deliveryMode="device-rtmp" — song song với
+ * ios/PickleballRtmpNativeModule.swift.
+ *
+ * API Kotlin của HaishinKit KHÁC hẳn bản Swift dù cùng tên dự án:
+ * MediaMixer nhận Context, attachVideo/attachAudio đặt track TRƯỚC nguồn, và
+ * session build() ném lỗi thay vì trả optional. Đừng suy từ file Swift sang.
+ */
+class PickleballRtmpNativeModule : Module() {
+  private var mixer: MediaMixer? = null
+  private var session: StreamSession? = null
+  private var videoSource: Camera2Source? = null
+  /** Phải khớp mặc định của engine (`isCameraFront: false`) như bên iOS. */
+  private var cameraId: String = BACK_DEFAULT_ID
+  private var microphoneEnabled = true
+  private var publishing = false
+  private var videoBitrate = 6_000_000
+  /** Luôn giữ dạng NGANG (cạnh dài trước); hướng thật tính ở orientedSize(). */
+  private var videoLongEdge = 1920
+  private var videoShortEdge = 1080
+  private var landscape = true
+
+  private val context: Context
+    get() = appContext.reactContext ?: throw RtmpException("thiếu Android context")
+
+  override fun definition() = ModuleDefinition {
+    Name("PickleballRtmpNative")
+    Events("onStatusChanged", "onBandwidth")
+
+    View(PickleballRtmpPreviewView::class) {}
+
+    AsyncFunction("prepare") Coroutine { options: PrepareOptions ->
+      prepare(options)
+    }
+
+    AsyncFunction("connect") Coroutine { options: ConnectOptions ->
+      connect(options)
+    }
+
+    AsyncFunction("setPublishing") Coroutine { enabled: Boolean ->
+      setPublishing(enabled)
+    }
+
+    AsyncFunction("disconnect") Coroutine { ->
+      closeSession("client")
+    }
+
+    AsyncFunction("switchCamera") Coroutine { ->
+      val target = if (isFront(cameraId)) BACK_DEFAULT_ID else frontCameraId()
+      attachCamera(target ?: BACK_DEFAULT_ID)
+    }
+
+    Function("listCameras") {
+      availableCameras().map {
+        mapOf(
+          "deviceId" to it.id,
+          "label" to it.label,
+          "facing" to if (it.front) "front" else "environment",
+        )
+      }
+    }
+
+    AsyncFunction("selectCamera") Coroutine { deviceId: String, _: String ->
+      attachCamera(deviceId)
+    }
+
+    AsyncFunction("setMicrophoneEnabled") Coroutine { enabled: Boolean ->
+      microphoneEnabled = enabled
+      // Gỡ hẳn nguồn audio thay vì mute — mic tắt thì không encode luôn.
+      mixer?.attachAudio(0, if (enabled) AudioRecordSource(context) else null)
+      Unit
+    }
+
+    AsyncFunction("setVideoBitrate") Coroutine { bitsPerSecond: Int ->
+      applyVideoBitrate(bitsPerSecond)
+    }
+
+    Function("getStats") {
+      mapOf(
+        "isConnected" to (session?.isConnected ?: false),
+        "isPublishing" to publishing,
+        "videoBitrate" to videoBitrate,
+        "currentFps" to 0,
+      )
+    }
+
+    AsyncFunction("dispose") Coroutine { ->
+      teardown()
+    }
+
+    OnDestroy {
+      // OnDestroy không phải coroutine — chỉ dọn phần đồng bộ được.
+      mixer?.stopRunning()
+      PickleballRtmpPreviewRegistry.setMixer(null)
+      mixer = null
+      session = null
+    }
+  }
+
+  // MARK: - Vòng đời
+
+  private suspend fun prepare(options: PrepareOptions) {
+    val active = mixer ?: MediaMixer(context).also { mixer = it }
+    PickleballRtmpPreviewRegistry.setMixer(active)
+
+    if (options.quality == 720) {
+      videoLongEdge = 1280
+      videoShortEdge = 720
+    } else {
+      videoLongEdge = 1920
+      videoShortEdge = 1080
+    }
+    landscape = options.landscape
+
+    // PHẢI đặt TRƯỚC startRunning(): Camera2Source.open() đọc `mixer.screen.frame`
+    // qua getCameraSize() để chọn kích thước capture. Đặt sau là camera đã chốt
+    // kích thước theo frame mặc định rồi, sửa frame lúc đó không còn tác dụng.
+    applyScreenGeometry()
+    attachCamera(cameraId)
+    if (microphoneEnabled) {
+      active.attachAudio(0, AudioRecordSource(context))
+    }
+    active.startRunning()
+    emitStatus(mapOf("status" to "idle"))
+  }
+
+  /** Kích thước khung thật theo hướng người dùng chọn (9:16 dọc hay 16:9 ngang). */
+  private fun orientedSize(): Pair<Int, Int> =
+    if (landscape) videoLongEdge to videoShortEdge else videoShortEdge to videoLongEdge
+
+  /**
+   * Đặt khung ảnh theo hướng người dùng chọn.
+   *
+   * `Screen.create()` đặt frame cứng ở kích thước ngang mặc định, không hề biết
+   * người dùng chọn 9:16 — không set lại là khung dọc bị bóp/cắt và
+   * Camera2Source cũng chọn sai kích thước capture.
+   *
+   * LiveKit không cần bước này vì WebRTC gắn metadata xoay vào TỪNG FRAME rồi
+   * để phía phát xoay; HaishinKit nướng thẳng hướng vào ảnh đã mã hoá.
+   *
+   * Ghi chú: `VideoScreenObject.isRotatesWithContent` (cờ quyết định có cộng
+   * `deviceOrientation` vào góc xoay hay không) KHÔNG chạm tới được từ ngoài —
+   * `findByClass` là `internal` và `id` của object là UUID ngẫu nhiên nên
+   * `findById` cũng vô dụng. Nếu chỉ set frame mà hình vẫn lệch thì phải tự
+   * thêm một VideoScreenObject của mình vào screen.
+   */
+  private fun applyScreenGeometry() {
+    val active = mixer ?: return
+    val (width, height) = orientedSize()
+    active.screen.frame = Rect(0, 0, width, height)
+  }
+
+  private suspend fun connect(options: ConnectOptions) {
+    val active = mixer ?: throw RtmpException("gọi prepare() trước khi connect()")
+
+    // Cùng cái bẫy như iOS: registry factory khởi tạo RỖNG, thiếu bước này thì
+    // build() không nhận ra scheme rtmp:// dù URL hoàn toàn hợp lệ.
+    StreamSession.Builder.registerFactory(RtmpStreamSessionFactory)
+
+    emitStatus(mapOf("status" to "connecting"))
+    try {
+      val built = StreamSession.Builder(context, Uri.parse(options.url))
+        .setMode(StreamSession.Mode.PUBLISH)
+        .build()
+      session = built
+      active.registerOutput(built.stream)
+
+      videoBitrate = options.videoBitrate
+      applyVideoBitrate(options.videoBitrate)
+      options.audioBitrate?.let { built.stream.audioSetting.bitRate = it }
+
+      emitStatus(mapOf("status" to "connected"))
+      if (options.publish) setPublishing(true)
+    } catch (error: Throwable) {
+      session = null
+      emitStatus(
+        mapOf(
+          "status" to "error",
+          "code" to "connect_failed",
+          "message" to (error.message ?: error.toString()),
+        ),
+      )
+      throw error
+    }
+  }
+
+  private suspend fun setPublishing(enabled: Boolean) {
+    val active = session ?: throw RtmpException("chưa kết nối RTMP")
+    if (enabled) {
+      if (publishing) return
+      active.connect().getOrThrow()
+      publishing = true
+      emitStatus(mapOf("status" to "publishing"))
+    } else {
+      if (!publishing) return
+      active.close()
+      publishing = false
+      emitStatus(mapOf("status" to "connected"))
+    }
+  }
+
+  private suspend fun closeSession(reason: String) {
+    val active = session ?: return
+    active.close()
+    session = null
+    publishing = false
+    emitStatus(mapOf("status" to "disconnected", "reason" to reason))
+  }
+
+  private suspend fun teardown() {
+    closeSession("dispose")
+    mixer?.let {
+      it.stopRunning()
+      it.attachAudio(0, null)
+      it.attachVideo(0, null)
+    }
+    PickleballRtmpPreviewRegistry.setMixer(null)
+    videoSource = null
+    mixer = null
+  }
+
+  // MARK: - Điều chỉnh
+
+  private fun applyVideoBitrate(bitsPerSecond: Int) {
+    val setting = session?.stream?.videoSetting ?: return
+    val (width, height) = orientedSize()
+    setting.bitRate = bitsPerSecond
+    // Encoder phải cùng hướng với screen, nếu không khung ra bị bóp méo.
+    setting.width = width
+    setting.height = height
+    // Keyframe 2 giây, khớp ranh giới segment HLS phía MediaMTX.
+    setting.IFrameInterval = 2
+    videoBitrate = bitsPerSecond
+  }
+
+  private suspend fun attachCamera(id: String) {
+    val active = mixer ?: return
+    val source = Camera2Source(context, id)
+    active.attachVideo(0, source)
+    videoSource = source
+    cameraId = id
+  }
+
+  // MARK: - Liệt kê ống kính
+
+  private data class LensInfo(val id: String, val label: String, val front: Boolean)
+
+  /**
+   * Android không có `localizedName` như AVFoundation, nên nhãn phải TỰ DỰNG
+   * đúng dạng tiếng Anh mà UI dò (`/ultra\s*wide/i`, `/telephoto/i` trong
+   * livestream-screen). Trả nhãn dạng khác thì cả ba ống kính đều hiện "1x" —
+   * đúng lỗi đã gặp trên iOS.
+   *
+   * Phân loại theo tiêu cự so với ống chính: ngắn hơn = siêu rộng, dài hơn = tele.
+   */
+  private fun availableCameras(): List<LensInfo> {
+    val manager = context.getSystemService(Context.CAMERA_SERVICE) as? CameraManager
+      ?: return emptyList()
+    val entries = manager.cameraIdList.mapNotNull { id ->
+      runCatching {
+        val chars = manager.getCameraCharacteristics(id)
+        val capabilities = chars.get(CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES)
+        // Bỏ camera depth/logic phụ: chúng không quay được video thường.
+        val usable = capabilities?.contains(
+          CameraCharacteristics.REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE,
+        ) ?: false
+        if (!usable) return@runCatching null
+        val focal = chars.get(CameraCharacteristics.LENS_INFO_AVAILABLE_FOCAL_LENGTHS)
+          ?.minOrNull() ?: 0f
+        val front = chars.get(CameraCharacteristics.LENS_FACING) ==
+          CameraCharacteristics.LENS_FACING_FRONT
+        Triple(id, focal, front)
+      }.getOrNull()
+    }.filterNotNull()
+
+    val (front, back) = entries.partition { it.third }
+    // Ống chính = tiêu cự trung vị của nhóm sau; so với nó để gọi tên hai ống kia.
+    val mainFocal = back.map { it.second }.sorted().getOrNull(back.size / 2) ?: 0f
+    return back.map { (id, focal, _) ->
+      val label = when {
+        focal < mainFocal * 0.8f -> "Back Ultra Wide Camera"
+        focal > mainFocal * 1.2f -> "Back Telephoto Camera"
+        else -> "Back Camera"
+      }
+      LensInfo(id, label, false)
+    } + front.map { LensInfo(it.first, "Front Camera", true) }
+  }
+
+  private fun isFront(id: String) = availableCameras().firstOrNull { it.id == id }?.front == true
+
+  private fun frontCameraId() = availableCameras().firstOrNull { it.front }?.id
+
+  private fun emitStatus(payload: Map<String, Any?>) {
+    sendEvent("onStatusChanged", payload)
+  }
+
+  private companion object {
+    const val BACK_DEFAULT_ID = "0"
+  }
+}
+
+class PrepareOptions : Record {
+  @Field val quality: Int = 1080
+
+  @Field val frameRate: Int = 30
+
+  /** Khung người dùng chọn: true = 16:9 ngang, false = 9:16 dọc. */
+  @Field val landscape: Boolean = true
+}
+
+class ConnectOptions : Record {
+  @Field val url: String = ""
+
+  @Field val videoBitrate: Int = 6_000_000
+
+  @Field val audioBitrate: Int? = null
+
+  @Field val publish: Boolean = true
+}
+
+class RtmpException(detail: String) : CodedException("ERR_PICKLEBALL_RTMP", detail, null)

package/android/src/main/java/expo/modules/pickleballrtmp/PickleballRtmpPreviewView.kt

@@ -0,0 +1,61 @@
+package expo.modules.pickleballrtmp
+
+import android.content.Context
+import android.view.ViewGroup
+import com.haishinkit.media.MediaMixer
+import com.haishinkit.view.HkSurfaceView
+import expo.modules.kotlin.AppContext
+import expo.modules.kotlin.views.ExpoView
+
+/**
+ * Nối view preview với mixer bất kể bên nào sẵn sàng trước.
+ *
+ * React mount view và JS gọi prepare() theo thứ tự không đoán trước được; giữ
+ * tham chiếu ở đây để bên đến sau tự bắt được bên đến trước. Thiếu cơ chế này
+ * thì màn hình đen dù camera đã chạy — đúng lỗi đã gặp trên iOS.
+ */
+object PickleballRtmpPreviewRegistry {
+  private var mixer: MediaMixer? = null
+  private var view: HkSurfaceView? = null
+
+  @Synchronized
+  fun setMixer(value: MediaMixer?) {
+    mixer = value
+    bind()
+  }
+
+  @Synchronized
+  fun setView(value: HkSurfaceView?) {
+    view?.let { previous -> mixer?.unregisterOutput(previous) }
+    view = value
+    bind()
+  }
+
+  private fun bind() {
+    val currentMixer = mixer ?: return
+    val currentView = view ?: return
+    currentMixer.registerOutput(currentView)
+  }
+}
+
+class PickleballRtmpPreviewView(
+  context: Context,
+  appContext: AppContext,
+) : ExpoView(context, appContext) {
+  private val surface = HkSurfaceView(context).also {
+    it.layoutParams = ViewGroup.LayoutParams(
+      ViewGroup.LayoutParams.MATCH_PARENT,
+      ViewGroup.LayoutParams.MATCH_PARENT,
+    )
+    addView(it)
+  }
+
+  init {
+    PickleballRtmpPreviewRegistry.setView(surface)
+  }
+
+  override fun onDetachedFromWindow() {
+    PickleballRtmpPreviewRegistry.setView(null)
+    super.onDetachedFromWindow()
+  }
+}

package/expo-module.config.json

@@ -0,0 +1,16 @@
+{
+  "platforms": [
+    "apple",
+    "android"
+  ],
+  "apple": {
+    "modules": [
+      "PickleballRtmpNativeModule"
+    ]
+  },
+  "android": {
+    "modules": [
+      "expo.modules.pickleballrtmp.PickleballRtmpNativeModule"
+    ]
+  }
+}

package/ios/PickleballRtmpNative.podspec

@@ -0,0 +1,17 @@
+Pod::Spec.new do |s|
+  s.name           = 'PickleballRtmpNative'
+  s.version        = '0.1.0'
+  s.summary        = 'Hardware-encoded RTMP publisher'
+  s.description    = 'Expo bridge over HaishinKit for the device-rtmp delivery mode.'
+  s.author         = 'Pickleball Live contributors'
+  s.homepage       = 'https://github.com/Cabinfood/livestream-pickleball'
+  s.license        = { :type => 'MIT', :file => '../LICENSE' }
+  s.platform       = :ios, '16.4'
+  s.source         = { :http => "https://registry.npmjs.org/@pickleball/rtmp-native/-/rtmp-native-#{s.version}.tgz" }
+  s.static_framework = true
+  s.dependency 'ExpoModulesCore'
+  # HaishinKit 2.x: API actor-based (MediaMixer/Session). Bản CocoaPods mới nhất
+  # là 2.0.9 — ghim minor để không nhảy sang API khác lúc pod install.
+  s.dependency 'HaishinKit', '~> 2.0.9'
+  s.source_files = '**/*.swift'
+end

package/ios/PickleballRtmpNativeModule.swift

@@ -0,0 +1,359 @@
+import AVFoundation
+import ExpoModulesCore
+import HaishinKit
+import UIKit
+
+/// Cầu nối Expo cho mode deliveryMode="device-rtmp".
+///
+/// Thiết bị mã hoá H.264 BẰNG PHẦN CỨNG một lần rồi đẩy thẳng RTMP — server chỉ
+/// remux sang HLS. Đây là lý do mode này tốn $0 transcode, khác với đường
+/// LiveKit egress (giải mã → dựng lại trong Chrome → mã hoá lại).
+///
+/// Viết theo API HaishinKit 2.0.9 (actor-based: MediaMixer / Session).
+public final class PickleballRtmpNativeModule: Module {
+  private var mixer: MediaMixer?
+  private var session: (any Session)?
+  // PHẢI khớp mặc định của engine (`isCameraFront: false`) và LiveKitRoomAdapter.
+  // Lệch một chỗ là nhãn UI và hình thực tế ngược nhau vĩnh viễn, và
+  // switchCamera() càng làm lệch thêm.
+  private var cameraPosition: AVCaptureDevice.Position = .back
+  private var microphoneEnabled = true
+  private var publishing = false
+  private var videoBitrate = 6_000_000
+  private var videoSize = CGSize(width: 1920, height: 1080)
+  /// SessionBuilderFactory KHÔNG có sẵn factory nào — phải tự đăng ký, nếu không
+  /// build() ném Error.notFound (error 1). Đăng ký một lần cho cả vòng đời app.
+  private static var sessionFactoriesRegistered = false
+  private var orientationObserver: NSObjectProtocol?
+
+  public func definition() -> ModuleDefinition {
+    Name("PickleballRtmpNative")
+    Events("onStatusChanged", "onBandwidth")
+
+    // View hiển thị camera. Thiếu nó thì màn preview tối đen dù camera đã mở.
+    View(PickleballRtmpPreviewView.self) {}
+
+    AsyncFunction("prepare") { (options: PrepareOptions) in
+      try await self.prepare(options)
+    }
+
+    AsyncFunction("connect") { (options: ConnectOptions) in
+      try await self.connect(options)
+    }
+
+    AsyncFunction("setPublishing") { (enabled: Bool) in
+      try await self.setPublishing(enabled)
+    }
+
+    AsyncFunction("disconnect") {
+      await self.closeSession(reason: "client")
+    }
+
+    AsyncFunction("switchCamera") {
+      try await self.switchCamera()
+    }
+
+    Function("listCameras") {
+      self.availableCameras().map { device in
+        [
+          "deviceId": device.uniqueID,
+          "label": Self.lensLabel(for: device),
+          // "environment" chứ không phải "back" — khớp cách đặt tên của WebRTC
+          // mà engine và mode LiveKit đang dùng.
+          "facing": device.position == .front ? "front" : "environment",
+        ]
+      }
+    }
+
+    AsyncFunction("selectCamera") { (deviceId: String, facing: String) in
+      try await self.selectCamera(deviceId: deviceId, facing: facing)
+    }
+
+    AsyncFunction("setMicrophoneEnabled") { (enabled: Bool) in
+      self.microphoneEnabled = enabled
+      // Gỡ hẳn thiết bị audio thay vì chỉ mute: mic tắt thì không encode luôn.
+      try await self.mixer?.attachAudio(enabled ? AVCaptureDevice.default(for: .audio) : nil)
+    }
+
+    AsyncFunction("setVideoBitrate") { (bitsPerSecond: Int) in
+      await self.applyVideoBitrate(bitsPerSecond)
+    }
+
+    Function("getStats") {
+      [
+        "isConnected": self.session != nil,
+        "isPublishing": self.publishing,
+        "videoBitrate": self.videoBitrate,
+        "currentFps": 0,
+      ] as [String: Any]
+    }
+
+    AsyncFunction("dispose") {
+      await self.teardown()
+    }
+
+    OnDestroy {
+      let mixer = self.mixer
+      let session = self.session
+      self.mixer = nil
+      self.session = nil
+      Task {
+        try? await session?.close()
+        await mixer?.stopRunning()
+      }
+    }
+  }
+
+  // MARK: - Vòng đời
+
+  private func prepare(_ options: PrepareOptions) async throws {
+    if mixer == nil {
+      // useManualCapture: tự quản vòng đời capture để camera không bị mở/đóng
+      // ngoài ý muốn giữa buổi live 10 tiếng.
+      mixer = MediaMixer(
+        multiCamSessionEnabled: false,
+        multiTrackAudioMixingEnabled: false,
+        useManualCapture: true
+      )
+    }
+    guard let mixer else { return }
+    // Cho view preview bám vào mixer (view có thể đã mount từ trước).
+    RtmpPreviewRegistry.shared.setMixer(mixer)
+
+    videoSize = options.quality == 720
+      ? CGSize(width: 1280, height: 720)
+      : CGSize(width: 1920, height: 1080)
+
+    try await mixer.attachVideo(
+      AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: cameraPosition),
+      track: 0
+    ) { unit in
+      // Lần gắn đầu cũng phải lật gương như switchCamera(), nếu không khởi động
+      // bằng camera trước sẽ hiện ngược so với mode LiveKit.
+      unit.isVideoMirrored = self.cameraPosition == .front
+    }
+    if microphoneEnabled {
+      try await mixer.attachAudio(AVCaptureDevice.default(for: .audio))
+    }
+    await applyVideoOrientation()
+    observeOrientation()
+    await mixer.startRunning()
+    emitStatus(["status": "idle"])
+  }
+
+  private func connect(_ options: ConnectOptions) async throws {
+    guard let mixer else {
+      throw RtmpException("gọi prepare() trước khi connect()")
+    }
+    guard let url = URL(string: options.url) else {
+      throw RtmpException("URL RTMP không hợp lệ")
+    }
+
+    await Self.registerSessionFactories()
+
+    emitStatus(["status": "connecting"])
+    do {
+      // build() trả optional: URL sai scheme (không phải rtmp/srt) thì trả nil
+      // chứ không ném lỗi.
+      guard let built = try await SessionBuilderFactory.shared.make(url).build() else {
+        throw RtmpException("không tạo được phiên cho URL này — scheme phải là rtmp://")
+      }
+      self.session = built
+      // Session và HKStream đều là actor nên mọi truy cập đều phải await.
+      let stream = await built.stream
+      await mixer.addOutput(stream)
+
+      videoBitrate = options.videoBitrate
+      await applyVideoBitrate(options.videoBitrate)
+      await applyAudioBitrate(options.audioBitrate)
+
+      emitStatus(["status": "connected"])
+      if options.publish {
+        try await setPublishing(true)
+      }
+    } catch {
+      self.session = nil
+      emitStatus([
+        "status": "error",
+        "code": "connect_failed",
+        "message": String(describing: error),
+      ])
+      throw error
+    }
+  }
+
+  /// `SessionBuilderFactory.shared` khởi tạo RỖNG. Thiếu bước này thì mọi
+  /// build() đều ném `Error.notFound` dù URL rtmp:// hoàn toàn hợp lệ.
+  private static func registerSessionFactories() async {
+    guard !sessionFactoriesRegistered else { return }
+    sessionFactoriesRegistered = true
+    await SessionBuilderFactory.shared.register(RTMPSessionFactory())
+  }
+
+  private func setPublishing(_ enabled: Bool) async throws {
+    guard let session else {
+      throw RtmpException("chưa kết nối RTMP")
+    }
+    if enabled {
+      guard !publishing else { return }
+      try await session.connect(.ingest)
+      publishing = true
+      emitStatus(["status": "publishing"])
+    } else {
+      guard publishing else { return }
+      try await session.close()
+      publishing = false
+      emitStatus(["status": "connected"])
+    }
+  }
+
+  private func closeSession(reason: String) async {
+    guard let session else { return }
+    try? await session.close()
+    self.session = nil
+    publishing = false
+    emitStatus(["status": "disconnected", "reason": reason])
+  }
+
+  private func teardown() async {
+    stopObservingOrientation()
+    await closeSession(reason: "dispose")
+    if let mixer {
+      await mixer.stopRunning()
+      try? await mixer.attachAudio(nil)
+      try? await mixer.attachVideo(nil, track: 0)
+    }
+    RtmpPreviewRegistry.shared.setMixer(nil)
+    mixer = nil
+  }
+
+  // MARK: - Điều chỉnh
+
+  /// Hạ/nâng bitrate thay cho BWE của WebRTC. Mạng yếu mà giữ nguyên bitrate thì
+  /// hàng đợi RTMP phình ra và tràn bộ nhớ.
+  private func applyVideoBitrate(_ bitsPerSecond: Int) async {
+    guard let session else { return }
+    let stream = await session.stream
+    var settings = await stream.videoSettings
+    settings.bitRate = bitsPerSecond
+    settings.videoSize = videoSize
+    // Keyframe 2 giây: khớp ranh giới segment HLS phía server, nếu không segment
+    // sẽ không cắt được đúng chỗ và người xem bị giật.
+    settings.maxKeyFrameIntervalDuration = 2
+    await stream.setVideoSettings(settings)
+    videoBitrate = bitsPerSecond
+  }
+
+  private func applyAudioBitrate(_ bitsPerSecond: Int?) async {
+    guard let session, let bitsPerSecond else { return }
+    let stream = await session.stream
+    var settings = await stream.audioSettings
+    settings.bitRate = bitsPerSecond
+    await stream.setAudioSettings(settings)
+  }
+
+  /// Không gọi hàm này thì HaishinKit giữ hướng mặc định và KHÔNG xoay theo máy
+  /// — video ra bị nằm ngang/dọc sai so với mode LiveKit (WebRTC tự xử lý xoay).
+  private func applyVideoOrientation() async {
+    guard let mixer else { return }
+    let deviceOrientation = await MainActor.run { UIDevice.current.orientation }
+    // faceUp/faceDown/unknown trả nil — giữ nguyên hướng cũ thay vì lật bừa.
+    guard let videoOrientation = DeviceUtil.videoOrientation(by: deviceOrientation) else {
+      return
+    }
+    await mixer.setVideoOrientation(videoOrientation)
+  }
+
+  private func observeOrientation() {
+    guard orientationObserver == nil else { return }
+    orientationObserver = NotificationCenter.default.addObserver(
+      forName: UIDevice.orientationDidChangeNotification,
+      object: nil,
+      queue: .main
+    ) { [weak self] _ in
+      Task { await self?.applyVideoOrientation() }
+    }
+  }
+
+  private func stopObservingOrientation() {
+    guard let orientationObserver else { return }
+    NotificationCenter.default.removeObserver(orientationObserver)
+    self.orientationObserver = nil
+  }
+
+  /// Liệt kê mọi ống kính vật lý: siêu rộng (0.5x), chính (1x), tele.
+  /// Thiếu hàm này thì UI không có gì để hiện và người dùng kẹt ở ống kính mặc định.
+  private func availableCameras() -> [AVCaptureDevice] {
+    AVCaptureDevice.DiscoverySession(
+      deviceTypes: [
+        .builtInUltraWideCamera,
+        .builtInWideAngleCamera,
+        .builtInTelephotoCamera,
+      ],
+      mediaType: .video,
+      position: .unspecified
+    ).devices
+  }
+
+  /// Dùng `localizedName` của AVFoundation ("Back Ultra Wide Camera",
+  /// "Back Telephoto Camera", ...) — KHÔNG tự đặt nhãn tiếng Việt.
+  ///
+  /// UI nhận diện ống kính bằng regex trên nhãn tiếng Anh (livestream-screen:
+  /// /ultra\s*wide/i, /telephoto/i) và mặc định về "1x" khi không khớp. Trả nhãn
+  /// khác dạng thì cả ba ống kính đều hiện "1x". Mode LiveKit lấy nhãn từ
+  /// WebRTC cũng chính là localizedName, nên dùng nó thì hai mode đồng nhất.
+  private static func lensLabel(for device: AVCaptureDevice) -> String {
+    device.localizedName
+  }
+
+  private func selectCamera(deviceId: String, facing: String) async throws {
+    guard let mixer else { return }
+    guard let device = availableCameras().first(where: { $0.uniqueID == deviceId }) else {
+      throw RtmpException("không tìm thấy ống kính \(deviceId)")
+    }
+    cameraPosition = device.position == .front ? .front : .back
+    let mirrored = cameraPosition == .front
+    try await mixer.attachVideo(device, track: 0) { unit in
+      unit.isVideoMirrored = mirrored
+    }
+  }
+
+  private func switchCamera() async throws {
+    guard let mixer else { return }
+    let next: AVCaptureDevice.Position = cameraPosition == .back ? .front : .back
+    try await mixer.attachVideo(
+      AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: next),
+      track: 0
+    ) { unit in
+      unit.isVideoMirrored = next == .front
+    }
+    cameraPosition = next
+  }
+
+  private func emitStatus(_ payload: [String: Any]) {
+    sendEvent("onStatusChanged", payload)
+  }
+}
+
+// MARK: - Records
+
+internal struct PrepareOptions: Record {
+  @Field var quality: Int = 1080
+  @Field var frameRate: Int = 30
+}
+
+internal struct ConnectOptions: Record {
+  @Field var url: String = ""
+  @Field var videoBitrate: Int = 6_000_000
+  @Field var audioBitrate: Int?
+  @Field var publish: Bool = true
+}
+
+internal final class RtmpException: Exception {
+  private let detail: String
+  init(_ detail: String) {
+    self.detail = detail
+    super.init()
+  }
+  override var reason: String { detail }
+}

package/ios/PickleballRtmpPreviewView.swift

@@ -0,0 +1,74 @@
+import AVFoundation
+import ExpoModulesCore
+import HaishinKit
+import UIKit
+
+/**
+ Giữ `MediaMixer` dùng chung giữa module (capture + publish) và view (hiển thị).
+
+ Chỉ có một camera nên một mixer là đủ. View có thể mount TRƯỚC khi module gọi
+ prepare(), hoặc mount lại sau khi màn hình remount — nên phải gắn được cả hai
+ chiều, không giả định thứ tự.
+ */
+final class RtmpPreviewRegistry {
+  static let shared = RtmpPreviewRegistry()
+
+  private var mixer: MediaMixer?
+  private let views = NSHashTable<MTHKView>.weakObjects()
+
+  /// Module gọi khi tạo/huỷ mixer; gắn lại mọi view đang chờ.
+  func setMixer(_ next: MediaMixer?) {
+    mixer = next
+    guard let next else { return }
+    for view in views.allObjects {
+      attach(view, to: next)
+    }
+  }
+
+  func register(_ view: MTHKView) {
+    views.add(view)
+    if let mixer {
+      attach(view, to: mixer)
+    }
+  }
+
+  func unregister(_ view: MTHKView) {
+    views.remove(view)
+    guard let mixer else { return }
+    Task { await mixer.removeOutput(view) }
+  }
+
+  private func attach(_ view: MTHKView, to mixer: MediaMixer) {
+    Task { await mixer.addOutput(view) }
+  }
+}
+
+/**
+ Hiển thị camera cho mode device-rtmp.
+
+ Không có view này thì màn hình preview TỐI ĐEN: HaishinKit vẫn mở camera và
+ encode bình thường, nhưng không có đích nào để vẽ khung hình lên.
+
+ `MTHKView` đã conform `MediaMixerOutput` nên chỉ cần addOutput vào mixer là
+ nhận được frame — không phải dựng pipeline hiển thị riêng.
+ */
+public final class PickleballRtmpPreviewView: ExpoView {
+  private let hkView = MTHKView(frame: .zero)
+
+  public required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    // Lấp đầy khung và cắt bớt phần thừa — khớp objectFit="cover" của bản LiveKit.
+    hkView.videoGravity = .resizeAspectFill
+    addSubview(hkView)
+    RtmpPreviewRegistry.shared.register(hkView)
+  }
+
+  deinit {
+    RtmpPreviewRegistry.shared.unregister(hkView)
+  }
+
+  public override func layoutSubviews() {
+    super.layoutSubviews()
+    hkView.frame = bounds
+  }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@pickleball/rtmp-native",
+  "version": "0.1.0",
+  "description": "Hardware-encoded RTMP publisher for Pickleball Live (device-rtmp delivery mode)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cabinfood/livestream-pickleball.git",
+    "directory": "packages/pickleball-rtmp-native"
+  },
+  "homepage": "https://github.com/Cabinfood/livestream-pickleball#readme",
+  "bugs": "https://github.com/Cabinfood/livestream-pickleball/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "ios",
+    "android/src",
+    "android/build.gradle",
+    "src",
+    "expo-module.config.json",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "expo": ">=56 <58",
+    "react": ">=19 <20",
+    "react-native": ">=0.85 <0.87"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.0",
+    "expo": "57.0.4",
+    "react": "19.2.0",
+    "react-native": "0.86.0",
+    "typescript": "^5.8.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit"
+  }
+}

package/src/PickleballRtmpNative.types.ts

@@ -0,0 +1,59 @@
+/** Trạng thái đường RTMP — map thẳng sang RoomEvent của expo-sdk engine. */
+export type NativeRtmpStatus =
+  | { readonly status: "idle" | "connecting" | "connected" | "publishing" }
+  | { readonly status: "disconnected"; readonly reason?: string }
+  | { readonly status: "error"; readonly code: string; readonly message: string };
+
+/**
+ * Phản hồi băng thông từ tầng RTMP — thay cho BWE của WebRTC.
+ *
+ * Mạng yếu mà không hạ bitrate thì hàng đợi phình ra và tràn bộ nhớ; đây là
+ * tín hiệu để engine hạ chất lượng thay vì để dồn ứ.
+ */
+export interface NativeRtmpBandwidth {
+  /** false = encoder đang đẩy nhanh hơn đường truyền chịu được. */
+  readonly sufficient: boolean;
+  /** Bitrate video encoder đang dùng thật (bit/giây). */
+  readonly videoBitrate: number;
+}
+
+export interface NativeRtmpStats {
+  readonly isConnected: boolean;
+  readonly isPublishing: boolean;
+  readonly videoBitrate: number;
+  readonly currentFps: number;
+}
+
+export interface RtmpPrepareOptions {
+  readonly quality: 720 | 1080;
+  readonly frameRate?: number;
+  /**
+   * Khung người dùng chọn: true = 16:9 ngang, false = 9:16 dọc.
+   *
+   * LiveKit không cần trường này vì WebRTC gắn metadata xoay vào từng frame;
+   * HaishinKit nướng hướng thẳng vào ảnh đã mã hoá nên phải biết trước.
+   */
+  readonly landscape?: boolean;
+}
+
+export interface RtmpConnectOptions {
+  /** URL RTMP đầy đủ, đã gồm stream key (rtmp://host:1935/live/sk_...). */
+  readonly url: string;
+  readonly videoBitrate: number;
+  readonly audioBitrate?: number;
+  /** false = chuẩn bị sẵn nhưng chưa phát (standby). */
+  readonly publish: boolean;
+}
+
+export type PickleballRtmpNativeEvents = {
+  onStatusChanged(event: NativeRtmpStatus): void;
+  onBandwidth(event: NativeRtmpBandwidth): void;
+};
+
+/** Một ống kính vật lý của máy (siêu rộng / chính / tele). */
+export interface NativeCameraInfo {
+  readonly deviceId: string;
+  readonly label: string;
+  /** "environment" = camera sau — khớp cách đặt tên của WebRTC. */
+  readonly facing: "front" | "environment";
+}

package/src/PickleballRtmpNativeModule.ts

@@ -0,0 +1,29 @@
+import { NativeModule, requireNativeModule } from "expo";
+import type {
+  NativeCameraInfo,
+  NativeRtmpStats,
+  PickleballRtmpNativeEvents,
+  RtmpConnectOptions,
+  RtmpPrepareOptions,
+} from "./PickleballRtmpNative.types";
+
+declare class PickleballRtmpNativeModule extends NativeModule<PickleballRtmpNativeEvents> {
+  /** 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. */
+  connect(options: RtmpConnectOptions): Promise<void>;
+  /** Bật/tắt phát khi đã kết nối (standby ↔ live). */
+  setPublishing(enabled: boolean): Promise<void>;
+  disconnect(): Promise<void>;
+  switchCamera(): Promise<void>;
+  /** Ống kính vật lý: siêu rộng (0.5x), chính (1x), tele. */
+  listCameras(): NativeCameraInfo[];
+  selectCamera(deviceId: string, facing: string): Promise<void>;
+  setMicrophoneEnabled(enabled: boolean): Promise<void>;
+  /** Hạ/nâng bitrate khi mạng đổi — thay cho BWE của WebRTC. */
+  setVideoBitrate(bitsPerSecond: number): Promise<void>;
+  getStats(): NativeRtmpStats;
+  dispose(): Promise<void>;
+}
+
+export default requireNativeModule<PickleballRtmpNativeModule>("PickleballRtmpNative");

package/src/PickleballRtmpPreviewView.ts

@@ -0,0 +1,12 @@
+import { requireNativeView } from "expo";
+import type { ComponentType } from "react";
+import type { ViewProps } from "react-native";
+
+/**
+ * Hiển thị camera cho mode device-rtmp.
+ *
+ * Bắt buộc phải render view này ở đâu đó, nếu không màn preview TỐI ĐEN: native
+ * vẫn mở camera và encode bình thường nhưng không có đích để vẽ khung hình.
+ */
+export const PickleballRtmpPreviewView: ComponentType<ViewProps> =
+  requireNativeView("PickleballRtmpNative");

package/src/index.ts

@@ -0,0 +1,3 @@
+export { default } from "./PickleballRtmpNativeModule";
+export { PickleballRtmpPreviewView } from "./PickleballRtmpPreviewView";
+export type * from "./PickleballRtmpNative.types";