dsh-agora 0.2.0

package/assets/agora/references/rtc/README.md

@@ -0,0 +1,104 @@
+# Agora RTC (Video/Voice SDK)
+
+Real-time audio and video communication. Users join channels, publish local tracks, and subscribe to remote tracks.
+
+## Critical Rules
+
+1. **Register event handlers BEFORE joining** the channel, or you will miss events for users already present.
+2. **`user-published` fires separately** for audio and video. A user publishing both triggers two events — handle each.
+3. **Track cleanup**: Always `stop()` then `close()` local tracks before setting to null. Failure to clean up causes memory leaks and device locks. (React SDK hooks handle this automatically — see `react.md`.)
+4. **HTTPS required** for Web SDK (except `localhost`).
+5. **Token management is mandatory in production**. Handle `token-privilege-will-expire` (Web) / `onTokenPrivilegeWillExpire` (native) to renew tokens. UID in token must match UID used to join.
+6. **Stream bombing prevention**: In production, generate tokens with subscriber role (`kRoleSubscriber` / `RtcRole.SUBSCRIBER`) for audience-only users to prevent unauthorized publishing.
+7. **Audio autoplay (non-standard flows only)**: Browser autoplay policy is not an issue in typical RTC flows because the user has already clicked to join (satisfying the gesture requirement). However, if you auto-join on page load, trigger audio from a non-user event, or run in a headless/test environment, `audioTrack.play()` may be silently blocked. Wrap the join + publish sequence in a user gesture handler in these cases.
+
+## Channel Profiles
+
+- `rtc` (communication): All peers are equal. Best for video calls, conferencing.
+- `live` (live streaming): Host/audience roles. Higher bitrate, lower latency for hosts.
+
+## Video Encoder Profiles (Web)
+
+```text
+"120p_1"  → 160×120,   15fps, 65kbps
+"180p_1"  → 320×180,   15fps, 140kbps
+"360p_1"  → 640×360,   15fps, 400kbps
+"480p_1"  → 640×480,   15fps, 500kbps
+"720p_1"  → 1280×720,  15fps, 1130kbps
+"720p_2"  → 1280×720,  30fps, 2000kbps
+"1080p_1" → 1920×1080, 15fps, 2080kbps
+"1080p_2" → 1920×1080, 30fps, 3000kbps
+```
+
+Or use custom config: `{ width: 640, height: 360, frameRate: 24, bitrateMin: 400, bitrateMax: 1000 }`
+
+## Audio Encoder Profiles (Web)
+
+```text
+"speech_low_quality"      → mono, 16kHz, 24kbps
+"speech_standard"         → mono, 32kHz, 24kbps
+"high_quality"            → mono, 48kHz, 40kbps
+"high_quality_stereo"     → stereo, 48kHz, 128kbps
+```
+
+## Dual Stream (Simulcast)
+
+Send high+low quality streams simultaneously. Subscribers choose which to receive, enabling large-scale calls:
+
+```javascript
+// Web: Enable after joining
+await client.enableDualStream();
+client.setLowStreamParameter({
+  width: 160,
+  height: 90,
+  framerate: 24,
+  bitrate: 200,
+});
+// Switch remote user to low stream
+client.setRemoteVideoStreamType(uid, 1); // 0=high, 1=low
+```
+
+## Screen Sharing (Web)
+
+```javascript
+const screenTrack = await AgoraRTC.createScreenVideoTrack(
+  {
+    optimizationMode: 'detail', // or "motion" for video content
+    encoderConfig: { width: 1280, height: 720, frameRate: 15 },
+  },
+  'auto',
+); // "auto" returns [videoTrack, audioTrack] if audio available
+```
+
+Screen share typically uses a separate client instance to avoid replacing the camera track.
+
+## Cross-Platform Interop Notes
+
+When Web, iOS, and Android clients share the same channel:
+
+- **Codec**: `"vp8"` and `"vp9"` scale better in multi-user calls — prefer these over `"h264"`, which does not scale well beyond small groups. If codecs differ between Web and native clients, Agora's server transcodes transparently (works but adds latency).
+- **UID types**: iOS uses `UInt` (unsigned 32-bit), Android uses `Int` (signed 32-bit), Web uses `number`. UIDs > 2,147,483,647 wrap to negative on Android. RTM uses **string UIDs** — use `String(rtcUid)` as a mapping convention.
+- **Audio profiles**: Align encoder settings across platforms to avoid one side sending stereo 128kbps while another expects mono. Use `"speech_standard"` (Web) / `AUDIO_PROFILE_DEFAULT` (native) for voice calls.
+- **Orientation**: Mobile uses adaptive orientation (rotates with device). Web cameras are typically landscape. Handle aspect ratio changes on the viewer side.
+- **Dual stream**: Enable on all platforms for large calls, not just Web.
+
+## Platform Reference Files
+
+Read the file matching the user's platform:
+
+- **[web.md](web.md)** — `agora-rtc-sdk-ng` (JS/TS): client creation, tracks, events, complete examples
+- **[react.md](react.md)** — `agora-rtc-react` hooks and components
+- **[nextjs.md](nextjs.md)** — Next.js / SSR dynamic import patterns (App Router + Pages Router)
+- **[ios.md](ios.md)** — `AgoraRtcEngineKit` (Swift): engine setup, delegation, permissions
+- **[android.md](android.md)** — `RtcEngine` (Kotlin/Java): engine setup, callbacks, permissions
+- **[react-native.md](react-native.md)** — `react-native-agora`: engine init, events, video views, complete example
+- **[flutter.md](flutter.md)** — `agora_rtc_engine` (Dart): engine init, events, AgoraVideoView, complete example
+- **[cross-platform-coordination.md](cross-platform-coordination.md)** — UID strategy, codec interop, screen sharing across platforms, audio routing, common cross-platform bugs
+
+For additional platforms and advanced features: <https://docs-md.agora.io/en/video-calling/get-started/get-started-sdk.md> — voice-only: <https://docs-md.agora.io/en/voice-calling/get-started/get-started-sdk.md>
+
+For test setup and mocking patterns, see [references/testing-guidance/SKILL.md](../testing-guidance/SKILL.md).
+
+## When to Fetch More
+
+Always use Level 2 fetch for: encoder profile parameter details, error code listings, release notes, Windows/Electron/Unity platform quick-starts. See [../doc-fetching.md](../doc-fetching.md).

package/assets/agora/references/rtc/android.md

@@ -0,0 +1,344 @@
+# Agora RTC Android SDK (Kotlin)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Engine Initialization](#engine-initialization)
+- [Joining a Channel](#joining-a-channel)
+- [Video Setup](#video-setup)
+- [Audio Setup](#audio-setup)
+- [Event Handling (IRtcEngineEventHandler)](#event-handling)
+- [Leaving and Cleanup](#leaving-and-cleanup)
+- [Token Renewal](#token-renewal)
+- [Complete Example: Video Call](#complete-example-video-call)
+
+API Reference: <https://api-ref.agora.io/en/video-sdk/android/4.x/API/rtc_api_overview.html>
+
+## Installation
+
+Add to `build.gradle`:
+
+```groovy
+dependencies {
+    implementation 'io.agora.rtc:full-sdk:4.3.+'
+    // or for voice-only: implementation 'io.agora.rtc:voice-sdk:4.3.+'
+}
+```
+
+Add permissions to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.BLUETOOTH" />
+<!-- Android 12+ (API 31+): required for Bluetooth audio headsets -->
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+```
+
+Request runtime permissions for `CAMERA` and `RECORD_AUDIO` before initializing.
+
+## Engine Initialization
+
+```kotlin
+import io.agora.rtc2.RtcEngine
+import io.agora.rtc2.RtcEngineConfig
+import io.agora.rtc2.Constants
+
+val config = RtcEngineConfig().apply {
+    mContext = applicationContext
+    mAppId = "your-app-id"
+    mEventHandler = rtcEventHandler
+    mChannelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION
+    // or Constants.CHANNEL_PROFILE_LIVE_BROADCASTING
+}
+
+val agoraEngine = RtcEngine.create(config)
+```
+
+## Joining a Channel
+
+```kotlin
+import io.agora.rtc2.ChannelMediaOptions
+
+val options = ChannelMediaOptions().apply {
+    clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
+    channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION
+    publishMicrophoneTrack = true
+    publishCameraTrack = true
+    autoSubscribeAudio = true
+    autoSubscribeVideo = true
+}
+
+agoraEngine.joinChannel(token, "channel-name", 0, options)
+// token: null for testing, uid: 0 for auto-assignment
+```
+
+## Video Setup
+
+```kotlin
+// Enable video module
+agoraEngine.enableVideo()
+
+// Configure encoder
+val videoConfig = VideoEncoderConfiguration().apply {
+    dimensions = VideoEncoderConfiguration.VideoDimensions(640, 360)
+    frameRate = VideoEncoderConfiguration.FRAME_RATE.FRAME_RATE_FPS_24.value
+    bitrate = VideoEncoderConfiguration.STANDARD_BITRATE
+    orientationMode = VideoEncoderConfiguration.ORIENTATION_MODE.ORIENTATION_MODE_ADAPTIVE
+}
+agoraEngine.setVideoEncoderConfiguration(videoConfig)
+
+// Local preview
+val localSurfaceView = SurfaceView(context)
+localVideoContainer.addView(localSurfaceView)
+agoraEngine.setupLocalVideo(
+    VideoCanvas(localSurfaceView, VideoCanvas.RENDER_MODE_HIDDEN, 0)
+)
+agoraEngine.startPreview()
+
+// Remote video (call in onUserJoined callback)
+val remoteSurfaceView = SurfaceView(context)
+remoteVideoContainer.addView(remoteSurfaceView)
+agoraEngine.setupRemoteVideo(
+    VideoCanvas(remoteSurfaceView, VideoCanvas.RENDER_MODE_HIDDEN, remoteUid)
+)
+```
+
+## Audio Setup
+
+```kotlin
+// Enable audio (enabled by default)
+agoraEngine.enableAudio()
+
+// Audio profile (SDK 4.x: set profile and scenario separately)
+agoraEngine.setAudioProfile(Constants.AUDIO_PROFILE_DEFAULT)
+agoraEngine.setAudioScenario(Constants.AUDIO_SCENARIO_DEFAULT)
+
+// Mute/unmute local audio
+agoraEngine.muteLocalAudioStream(true)   // mute
+agoraEngine.muteLocalAudioStream(false)  // unmute
+
+// Mute/unmute local video (stops sending video, camera stays active)
+agoraEngine.muteLocalVideoStream(true)   // video off
+agoraEngine.muteLocalVideoStream(false)  // video on
+
+// Or disable video entirely (stops camera capture)
+agoraEngine.enableLocalVideo(false)      // camera off
+agoraEngine.enableLocalVideo(true)       // camera on
+
+// Switch between speaker and earpiece
+agoraEngine.setEnableSpeakerphone(true)  // speaker
+agoraEngine.setEnableSpeakerphone(false) // earpiece
+
+// Mute remote user
+agoraEngine.muteRemoteAudioStream(remoteUid, true)
+```
+
+## Event Handling
+
+```kotlin
+private val rtcEventHandler = object : IRtcEngineEventHandler() {
+    // Successfully joined channel
+    override fun onJoinChannelSuccess(channel: String?, uid: Int, elapsed: Int) {
+        runOnUiThread {
+            Log.d("Agora", "Joined channel: $channel, uid: $uid")
+        }
+    }
+
+    // Remote user joined
+    override fun onUserJoined(uid: Int, elapsed: Int) {
+        runOnUiThread {
+            val remoteSurfaceView = SurfaceView(context)
+            remoteVideoContainer.addView(remoteSurfaceView)
+            agoraEngine.setupRemoteVideo(
+                VideoCanvas(remoteSurfaceView, VideoCanvas.RENDER_MODE_HIDDEN, uid)
+            )
+        }
+    }
+
+    // Remote user left
+    override fun onUserOffline(uid: Int, reason: Int) {
+        runOnUiThread {
+            agoraEngine.setupRemoteVideo(VideoCanvas(null, VideoCanvas.RENDER_MODE_HIDDEN, uid))
+            // Remove remote view from container
+        }
+    }
+
+    // Token expiring
+    override fun onTokenPrivilegeWillExpire(token: String?) {
+        // Fetch new token and renew
+        fetchNewToken { newToken ->
+            agoraEngine.renewToken(newToken)
+        }
+    }
+
+    // Error
+    override fun onError(err: Int) {
+        Log.e("Agora", "Error code: $err")
+    }
+
+    // Network quality
+    override fun onNetworkQuality(uid: Int, txQuality: Int, rxQuality: Int) {
+        // 0=unknown, 1=excellent, 2=good, 3=poor, 4=bad, 5=very bad, 6=disconnected
+    }
+}
+```
+
+## Leaving and Cleanup
+
+```kotlin
+fun leaveChannel() {
+    agoraEngine.stopPreview()
+    agoraEngine.leaveChannel()
+}
+
+// Full cleanup (activity/app destruction)
+fun destroy() {
+    agoraEngine.stopPreview()
+    agoraEngine.leaveChannel()
+    RtcEngine.destroy()
+}
+```
+
+## Token Renewal
+
+```kotlin
+override fun onTokenPrivilegeWillExpire(token: String?) {
+    lifecycleScope.launch {
+        val newToken = fetchTokenFromServer(channelName, localUid)
+        agoraEngine.renewToken(newToken)
+    }
+}
+```
+
+## Complete Example: Video Call
+
+```kotlin
+class VideoCallActivity : AppCompatActivity() {
+    private val appId = "your-app-id"
+    private var token: String? = null
+    private val channelName = "test"
+    private var agoraEngine: RtcEngine? = null
+    private var isJoined = false
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_video_call)
+
+        // Request permissions first
+        if (checkPermissions()) {
+            initializeAgora()
+        } else {
+            requestPermissions()
+        }
+    }
+
+    private fun initializeAgora() {
+        val config = RtcEngineConfig().apply {
+            mContext = applicationContext
+            mAppId = appId
+            mEventHandler = rtcEventHandler
+        }
+        agoraEngine = RtcEngine.create(config)
+        agoraEngine?.enableVideo()
+
+        agoraEngine?.setVideoEncoderConfiguration(
+            VideoEncoderConfiguration().apply {
+                dimensions = VideoEncoderConfiguration.VideoDimensions(640, 360)
+                frameRate = VideoEncoderConfiguration.FRAME_RATE.FRAME_RATE_FPS_24.value
+                bitrate = VideoEncoderConfiguration.STANDARD_BITRATE
+            }
+        )
+    }
+
+    fun joinChannel() {
+        // Setup local preview
+        val localView = SurfaceView(this)
+        findViewById<FrameLayout>(R.id.local_video_container).addView(localView)
+        agoraEngine?.setupLocalVideo(VideoCanvas(localView, VideoCanvas.RENDER_MODE_HIDDEN, 0))
+        agoraEngine?.startPreview()
+
+        // Join channel
+        val options = ChannelMediaOptions().apply {
+            clientRoleType = Constants.CLIENT_ROLE_BROADCASTER
+            channelProfile = Constants.CHANNEL_PROFILE_COMMUNICATION
+            publishMicrophoneTrack = true
+            publishCameraTrack = true
+        }
+        agoraEngine?.joinChannel(token, channelName, 0, options)
+    }
+
+    fun leaveChannel() {
+        agoraEngine?.stopPreview()
+        agoraEngine?.leaveChannel()
+        isJoined = false
+    }
+
+    private val rtcEventHandler = object : IRtcEngineEventHandler() {
+        override fun onJoinChannelSuccess(channel: String?, uid: Int, elapsed: Int) {
+            runOnUiThread { isJoined = true }
+        }
+
+        override fun onUserJoined(uid: Int, elapsed: Int) {
+            runOnUiThread {
+                val remoteView = SurfaceView(this@VideoCallActivity)
+                findViewById<FrameLayout>(R.id.remote_video_container).addView(remoteView)
+                agoraEngine?.setupRemoteVideo(
+                    VideoCanvas(remoteView, VideoCanvas.RENDER_MODE_HIDDEN, uid)
+                )
+            }
+        }
+
+        override fun onUserOffline(uid: Int, reason: Int) {
+            runOnUiThread {
+                agoraEngine?.setupRemoteVideo(VideoCanvas(null, VideoCanvas.RENDER_MODE_HIDDEN, uid))
+            }
+        }
+
+        override fun onTokenPrivilegeWillExpire(token: String?) {
+            lifecycleScope.launch {
+                val newToken = fetchTokenFromServer(channelName, 0)
+                agoraEngine?.renewToken(newToken)
+            }
+        }
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        agoraEngine?.stopPreview()
+        agoraEngine?.leaveChannel()
+        RtcEngine.destroy()
+        agoraEngine = null
+    }
+
+    private fun checkPermissions(): Boolean {
+        return ContextCompat.checkSelfPermission(this, Manifest.permission.CAMERA) ==
+            PackageManager.PERMISSION_GRANTED &&
+            ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) ==
+            PackageManager.PERMISSION_GRANTED
+    }
+
+    private fun requestPermissions() {
+        ActivityCompat.requestPermissions(
+            this,
+            arrayOf(Manifest.permission.CAMERA, Manifest.permission.RECORD_AUDIO),
+            PERMISSION_REQUEST_CODE
+        )
+    }
+
+    companion object {
+        private const val PERMISSION_REQUEST_CODE = 22
+    }
+}
+```
+
+## Official Documentation
+
+For APIs or features not covered above:
+
+- API Reference: <https://api-ref.agora.io/en/video-sdk/android/4.x/API/rtc_api_overview.html>
+- Guides: <https://docs.agora.io/en/video-calling/overview/product-overview>

package/assets/agora/references/rtc/cross-platform-coordination.md

@@ -0,0 +1,61 @@
+# RTC Cross-Platform Coordination
+
+Patterns for apps where users on different platforms (Web, iOS, Android) join the same Agora RTC channel.
+
+## UID Strategy
+
+Agora assigns UIDs per channel. For multi-platform apps:
+
+- **Auto-assign on all clients**: Pass `null`/`0` to `join()` — each platform auto-receives a unique numeric UID. Clients subscribe to all remote users regardless of platform.
+- **Fixed UIDs**: Assign specific UIDs per user role (e.g., `1001` for host, `1002` for co-host) when you need deterministic lookup. Must be unique per channel — duplicates cause undefined behavior.
+- **UID limits**: Numeric UIDs must be `0` to `2^32 - 1`. String UIDs must be ASCII and at most `255` characters.
+- **RTC + RTM coordination**: After RTC join, use `String(rtcUid)` as the RTM user ID to correlate users across both systems (see [../rtm/README.md](../rtm/README.md)).
+
+## Codec Interoperability
+
+Agora handles codec negotiation automatically for most scenarios. What to know:
+
+| Codec | Notes |
+|-------|-------|
+| VP8 | Web default. Scales well in multi-user calls. Supported on Safari 13+. Recommended. |
+| VP9 | Better compression than VP8. Scales well on desktop. **iOS Safari: hardware-only** — requires iPhone 15 Pro / M3 Mac or newer; software fallback degrades battery significantly on older devices. |
+| H.264 | Default on iOS and Android native SDKs. Does not scale well beyond small groups — avoid for multi-user Web calls. |
+| H.265 (HEVC) | Not universally supported on Web; avoid for cross-platform channels. |
+
+**Recommendation**: `'vp8'` is the safest default for multi-user Web calls — scales well and works on all modern Safari (13+). Use `'vp9'` only if you can ensure participants are on modern hardware. Avoid `'h264'` for multi-user Web scenarios. If codecs differ between Web and native clients, Agora's server transcodes transparently, which adds latency and is billed separately.
+
+## Screen Sharing (Cross-Platform)
+
+Screen share is a separate track/stream, not a replacement for the camera track.
+
+- **Web**: `AgoraRTC.createScreenVideoTrack()` — publishes as a second video track. See [web.md](web.md) for dual-stream setup.
+- **iOS**: `AgoraRtcEngineKit.startScreenCapture(_:)` with broadcast extension — different lifecycle than camera.
+- **Android**: `MediaProjection` API + `RtcEngine.startScreenCapture()`.
+
+Remote users on any platform subscribe to the screen share UID as a normal remote user — the stream is just another video track from a different UID.
+
+**Key rule**: Screen share uses a separate channel join with a different UID. Never publish camera and screen share from the same UID.
+
+## Audio Routing Differences
+
+| Platform | Default audio output | Override |
+|----------|---------------------|---------|
+| Web | Speaker (browser-controlled) | Not configurable via SDK |
+| iOS | Earpiece for `rtc` mode | `setDefaultAudioRouteToSpeakerphone(true)` for speaker |
+| Android | Earpiece by default | `setEnableSpeakerphone(true)` |
+
+When a user plugs in headphones, iOS/Android switch automatically. Web relies on the browser and OS audio routing — the SDK cannot override this.
+
+## Testing Multi-Platform Channels Locally
+
+1. **Web + Simulator/Emulator**: Connect both to the same channel; verify remote tracks appear on both sides.
+2. **Different UIDs on same machine**: Open two browser tabs or two simulator instances — each gets its own UID automatically.
+3. **Cross-device**: Use the Agora [Web Demo](https://webdemo.agora.io) to join from a browser while testing your native app in the same channel.
+4. **Codec check**: In the Agora Console → Real-time Monitoring, inspect active streams to confirm codec negotiation.
+
+## Common Cross-Platform Bugs
+
+- **Remote user appears then immediately disappears on iOS** — usually a token expiry or UID collision. Check `connectionStateChanged` delegate for the reason code.
+- **No video from Android on Web** — codec mismatch. Android may be sending H.265; Web can't decode it. Force H.264 on Android via `VideoEncoderConfiguration`.
+- **Audio works, video doesn't on mobile** — camera permission not granted. Check permission before calling `startPreview()`.
+- **Web user sees mobile user but not vice versa** — `user-published` event not registered before `client.join()`. Event handlers must be set up before joining — see RTC critical rules in [README.md](README.md).