dsh-agora 0.2.0

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

@@ -0,0 +1,282 @@
+# Agora RTC Flutter SDK
+
+## 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](#event-handling)
+- [Leaving and Cleanup](#leaving-and-cleanup)
+- [Complete Example](#complete-example)
+
+API Reference: <https://api-ref.agora.io/en/video-sdk/flutter/6.x/API/rtc_api_overview.html>
+
+## Installation
+
+Add to `pubspec.yaml`:
+
+```yaml
+dependencies:
+  agora_rtc_engine: ^6.5.0
+```
+
+Run `flutter pub get`.
+
+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_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" />
+```
+
+Add to `Info.plist` (iOS):
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Camera access for video calls</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>Microphone access for audio calls</string>
+```
+
+## Engine Initialization
+
+```dart
+import 'package:agora_rtc_engine/agora_rtc_engine.dart';
+
+late RtcEngine _engine;
+
+Future<void> initializeAgora() async {
+  _engine = createAgoraRtcEngine();
+  await _engine.initialize(const RtcEngineContext(
+    appId: 'your-app-id',
+    channelProfile: ChannelProfileType.channelProfileCommunication,
+  ));
+  await _engine.enableVideo();
+}
+```
+
+## Joining a Channel
+
+```dart
+Future<void> joinChannel() async {
+  await _engine.joinChannel(
+    token: null, // null for testing
+    channelId: 'channel-name',
+    uid: 0,      // 0 for auto-assignment
+    options: const ChannelMediaOptions(
+      clientRoleType: ClientRoleType.clientRoleBroadcaster,
+      publishMicrophoneTrack: true,
+      publishCameraTrack: true,
+      autoSubscribeAudio: true,
+      autoSubscribeVideo: true,
+    ),
+  );
+}
+```
+
+## Video Setup
+
+```dart
+// Local preview — use uid=0
+AgoraVideoView(
+  controller: VideoViewController(
+    rtcEngine: _engine,
+    canvas: const VideoCanvas(uid: 0),
+  ),
+)
+
+// Remote video — use the remote user's uid
+AgoraVideoView(
+  controller: VideoViewController.remote(
+    rtcEngine: _engine,
+    canvas: VideoCanvas(uid: remoteUid),
+    connection: const RtcConnection(channelId: 'channel-name'),
+  ),
+)
+```
+
+## Audio Setup
+
+```dart
+// Mute/unmute local audio
+await _engine.muteLocalAudioStream(true)   // mute
+await _engine.muteLocalAudioStream(false)  // unmute
+
+// Mute/unmute local video
+await _engine.muteLocalVideoStream(true)   // video off
+await _engine.muteLocalVideoStream(false)  // video on
+
+// Speaker vs earpiece
+await _engine.setEnableSpeakerphone(true)  // speaker
+await _engine.setEnableSpeakerphone(false) // earpiece
+```
+
+## Event Handling
+
+Register handlers **before** joining the channel.
+
+```dart
+_engine.registerEventHandler(
+  RtcEngineEventHandler(
+    onJoinChannelSuccess: (RtcConnection connection, int elapsed) {
+      print('Joined: ${connection.channelId}, uid: ${connection.localUid}');
+    },
+    onUserJoined: (RtcConnection connection, int remoteUid, int elapsed) {
+      print('Remote user joined: $remoteUid');
+      setState(() => _remoteUid = remoteUid);
+    },
+    onUserOffline: (RtcConnection connection, int remoteUid, UserOfflineReasonType reason) {
+      print('Remote user left: $remoteUid');
+      setState(() => _remoteUid = null);
+    },
+    onTokenPrivilegeWillExpire: (RtcConnection connection, String token) async {
+      final newToken = await fetchTokenFromServer();
+      await _engine.renewToken(newToken);
+    },
+    onError: (ErrorCodeType err, String msg) {
+      print('Error: $err $msg');
+    },
+  ),
+);
+```
+
+## Leaving and Cleanup
+
+```dart
+Future<void> leaveChannel() async {
+  await _engine.leaveChannel();
+}
+
+// Full cleanup when widget is disposed
+@override
+void dispose() {
+  _engine.leaveChannel();
+  _engine.release();
+  super.dispose();
+}
+```
+
+Always call `release()` when the engine is no longer needed.
+
+## Complete Example
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:agora_rtc_engine/agora_rtc_engine.dart';
+
+const appId = 'your-app-id';
+const token = null; // null for testing
+const channel = 'test';
+
+class VideoCallPage extends StatefulWidget {
+  const VideoCallPage({super.key});
+  @override
+  State<VideoCallPage> createState() => _VideoCallPageState();
+}
+
+class _VideoCallPageState extends State<VideoCallPage> {
+  late RtcEngine _engine;
+  bool _joined = false;
+  int? _remoteUid;
+
+  @override
+  void initState() {
+    super.initState();
+    _initAgora();
+  }
+
+  Future<void> _initAgora() async {
+    _engine = createAgoraRtcEngine();
+    await _engine.initialize(const RtcEngineContext(appId: appId));
+    await _engine.enableVideo();
+
+    _engine.registerEventHandler(RtcEngineEventHandler(
+      onJoinChannelSuccess: (_, __) => setState(() => _joined = true),
+      onUserJoined: (_, uid, __) => setState(() => _remoteUid = uid),
+      onUserOffline: (_, uid, __) => setState(() => _remoteUid = null),
+    ));
+  }
+
+  Future<void> _join() async {
+    await _engine.startPreview();
+    await _engine.joinChannel(
+      token: token,
+      channelId: channel,
+      uid: 0,
+      options: const ChannelMediaOptions(
+        clientRoleType: ClientRoleType.clientRoleBroadcaster,
+        publishMicrophoneTrack: true,
+        publishCameraTrack: true,
+      ),
+    );
+  }
+
+  Future<void> _leave() async {
+    await _engine.leaveChannel();
+    setState(() {
+      _joined = false;
+      _remoteUid = null;
+    });
+  }
+
+  @override
+  void dispose() {
+    _engine.release();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Stack(
+        children: [
+          if (_joined)
+            AgoraVideoView(
+              controller: VideoViewController(
+                rtcEngine: _engine,
+                canvas: const VideoCanvas(uid: 0),
+              ),
+            ),
+          if (_remoteUid != null)
+            Positioned(
+              right: 16, top: 16, width: 120, height: 160,
+              child: AgoraVideoView(
+                controller: VideoViewController.remote(
+                  rtcEngine: _engine,
+                  canvas: VideoCanvas(uid: _remoteUid!),
+                  connection: const RtcConnection(channelId: channel),
+                ),
+              ),
+            ),
+          Positioned(
+            bottom: 32, left: 0, right: 0,
+            child: Center(
+              child: ElevatedButton(
+                onPressed: _joined ? _leave : _join,
+                child: Text(_joined ? 'Leave' : 'Join'),
+              ),
+            ),
+          ),
+        ],
+      ),
+    );
+  }
+}
+```
+
+For test setup and mocking patterns, see [references/testing-guidance/SKILL.md](../testing-guidance/SKILL.md).
+
+## Official Documentation
+
+For APIs or features not covered above:
+
+- Quick-start guide: <https://docs-md.agora.io/en/video-calling/get-started/get-started-sdk.md?platform=flutter>
+- API Reference: <https://api-ref.agora.io/en/video-sdk/flutter/6.x/API/rtc_api_overview.html>

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

@@ -0,0 +1,306 @@
+# Agora RTC iOS SDK (Swift)
+
+## 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 (Delegate)](#event-handling-delegate)
+- [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/ios/4.x/API/rtc_api_overview_ng.html>
+
+## Installation
+
+### Swift Package Manager
+
+```text
+https://github.com/AgoraIO/AgoraRtcEngine_iOS
+```
+
+### CocoaPods
+
+```ruby
+pod 'AgoraRtcEngine_iOS', '~> 4.3'
+```
+
+Add to Info.plist:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>For video calling</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>For voice calling</string>
+```
+
+## Engine Initialization
+
+```swift
+import AgoraRtcKit
+
+let config = AgoraRtcEngineConfig()
+config.appId = "your-app-id"
+config.channelProfile = .communication  // or .liveBroadcasting
+
+let agoraEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
+```
+
+## Joining a Channel
+
+```swift
+// Communication mode
+let option = AgoraRtcChannelMediaOptions()
+option.clientRoleType = .broadcaster  // .broadcaster or .audience
+option.channelProfile = .communication
+
+agoraEngine.joinChannel(
+    byToken: token,      // nil for testing
+    channelId: "channel-name",
+    uid: 0,              // 0 = auto-assign
+    mediaOptions: option
+)
+```
+
+## Video Setup
+
+```swift
+// Enable video module
+agoraEngine.enableVideo()
+
+// Configure video encoder
+let videoConfig = AgoraVideoEncoderConfiguration(
+    size: CGSize(width: 640, height: 360),
+    frameRate: .fps24,
+    bitrate: AgoraVideoBitrateStandard,
+    orientationMode: .adaptative
+)
+agoraEngine.setVideoEncoderConfiguration(videoConfig)
+
+// Local video preview
+let localView = UIView(frame: localVideoContainer.bounds)
+let canvas = AgoraRtcVideoCanvas()
+canvas.uid = 0  // 0 = local user
+canvas.view = localView
+canvas.renderMode = .hidden
+agoraEngine.setupLocalVideo(canvas)
+agoraEngine.startPreview()
+
+// Remote video (call in didJoinedOfUid delegate)
+let remoteCanvas = AgoraRtcVideoCanvas()
+remoteCanvas.uid = remoteUid
+remoteCanvas.view = remoteVideoView
+remoteCanvas.renderMode = .hidden
+agoraEngine.setupRemoteVideo(remoteCanvas)
+```
+
+## Audio Setup
+
+```swift
+// Enable audio (enabled by default)
+agoraEngine.enableAudio()
+
+// Audio profile
+agoraEngine.setAudioProfile(.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, mute: true)
+```
+
+## Event Handling (Delegate)
+
+```swift
+extension ViewController: AgoraRtcEngineDelegate {
+    // Successfully joined channel
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) {
+        print("Joined channel: \(channel), uid: \(uid)")
+    }
+
+    // Remote user joined
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
+        // Setup remote video view
+        let canvas = AgoraRtcVideoCanvas()
+        canvas.uid = uid
+        canvas.view = remoteVideoView
+        canvas.renderMode = .hidden
+        engine.setupRemoteVideo(canvas)
+    }
+
+    // Remote user left
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
+        // Clean up remote view
+        let canvas = AgoraRtcVideoCanvas()
+        canvas.uid = uid
+        canvas.view = nil
+        engine.setupRemoteVideo(canvas)
+    }
+
+    // Token expiring
+    func rtcEngine(_ engine: AgoraRtcEngineKit, tokenPrivilegeWillExpire token: String) {
+        // Fetch new token from server and renew
+        fetchNewToken { newToken in
+            engine.renewToken(newToken)
+        }
+    }
+
+    // Error
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didOccurError errorCode: AgoraErrorCode) {
+        print("Agora error: \(errorCode.rawValue)")
+    }
+
+    // Network quality
+    func rtcEngine(_ engine: AgoraRtcEngineKit, networkQuality uid: UInt,
+                   txQuality: AgoraNetworkQuality, rxQuality: AgoraNetworkQuality) {
+        // 0=unknown, 1=excellent, 2=good, 3=poor, 4=bad, 5=very bad
+    }
+}
+```
+
+## Leaving and Cleanup
+
+```swift
+func leaveChannel() {
+    agoraEngine.stopPreview()
+    agoraEngine.leaveChannel(nil)
+}
+
+// Full cleanup (app termination)
+func destroy() {
+    agoraEngine.stopPreview()
+    agoraEngine.leaveChannel(nil)
+    AgoraRtcEngineKit.destroy()
+}
+```
+
+## Token Renewal
+
+```swift
+func rtcEngine(_ engine: AgoraRtcEngineKit, tokenPrivilegeWillExpire token: String) {
+    Task {
+        let newToken = await fetchTokenFromServer(channel: channelName, uid: localUid)
+        engine.renewToken(newToken)
+    }
+}
+```
+
+## Complete Example: Video Call
+
+```swift
+import UIKit
+import AgoraRtcKit
+
+class VideoCallViewController: UIViewController {
+    private var agoraEngine: AgoraRtcEngineKit!
+    private let appId = "your-app-id"
+    private var token: String? = nil
+    private let channelName = "test"
+
+    @IBOutlet weak var localVideoView: UIView!
+    @IBOutlet weak var remoteVideoView: UIView!
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        initializeAgora()
+    }
+
+    private func initializeAgora() {
+        let config = AgoraRtcEngineConfig()
+        config.appId = appId
+        config.channelProfile = .communication
+
+        agoraEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
+        agoraEngine.enableVideo()
+        agoraEngine.setVideoEncoderConfiguration(
+            AgoraVideoEncoderConfiguration(
+                size: CGSize(width: 640, height: 360),
+                frameRate: .fps24,
+                bitrate: AgoraVideoBitrateStandard,
+                orientationMode: .adaptative
+            )
+        )
+    }
+
+    @IBAction func joinChannel(_ sender: Any) {
+        // Setup local preview
+        let localCanvas = AgoraRtcVideoCanvas()
+        localCanvas.uid = 0
+        localCanvas.view = localVideoView
+        localCanvas.renderMode = .hidden
+        agoraEngine.setupLocalVideo(localCanvas)
+        agoraEngine.startPreview()
+
+        // Join
+        let option = AgoraRtcChannelMediaOptions()
+        option.clientRoleType = .broadcaster
+        option.channelProfile = .communication
+
+        agoraEngine.joinChannel(
+            byToken: token,
+            channelId: channelName,
+            uid: 0,
+            mediaOptions: option
+        )
+    }
+
+    @IBAction func leaveChannel(_ sender: Any) {
+        agoraEngine.stopPreview()
+        agoraEngine.leaveChannel(nil)
+    }
+
+    deinit {
+        agoraEngine.stopPreview()
+        agoraEngine.leaveChannel(nil)
+        AgoraRtcEngineKit.destroy()
+    }
+}
+
+extension VideoCallViewController: AgoraRtcEngineDelegate {
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
+        let remoteCanvas = AgoraRtcVideoCanvas()
+        remoteCanvas.uid = uid
+        remoteCanvas.view = remoteVideoView
+        remoteCanvas.renderMode = .hidden
+        agoraEngine.setupRemoteVideo(remoteCanvas)
+    }
+
+    func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
+        let canvas = AgoraRtcVideoCanvas()
+        canvas.uid = uid
+        canvas.view = nil
+        agoraEngine.setupRemoteVideo(canvas)
+    }
+
+    func rtcEngine(_ engine: AgoraRtcEngineKit, tokenPrivilegeWillExpire token: String) {
+        Task {
+            let newToken = await fetchTokenFromServer()
+            agoraEngine.renewToken(newToken)
+        }
+    }
+}
+```
+
+## Official Documentation
+
+For APIs or features not covered above:
+
+- API Reference: <https://api-ref.agora.io/en/video-sdk/ios/4.x/API/rtc_api_overview_ng.html>
+- Guides: <https://docs.agora.io/en/video-calling/overview/product-overview>

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

@@ -0,0 +1,87 @@
+# Agora RTC — Next.js / SSR
+
+The Agora Web SDK (`agora-rtc-sdk-ng`) and `agora-rtc-react` are browser-only. They cannot run during server-side rendering and will throw errors if imported at the module level in a Next.js Server Component or during SSR.
+
+## The Problem
+
+`next/dynamic` with `ssr: false` works in Pages Router and in Client Components, but **does NOT work in Server Components** in Next.js 14+ App Router. A Server Component importing a dynamically-loaded client module that references Agora will still fail at build time if the import is not properly isolated.
+
+## Pattern: Wrap Both the Provider and Component
+
+The correct pattern for Next.js App Router is to dynamically import both your Agora component **and** the `AgoraRTCProvider` together, inside a Client Component:
+
+```tsx
+'use client';
+
+import { useMemo, Suspense } from 'react';
+import dynamic from 'next/dynamic';
+
+// Dynamically import your RTC component with ssr disabled
+const ConversationComponent = dynamic(() => import('./ConversationComponent'), {
+  ssr: false,
+});
+
+// Dynamically import AgoraRTCProvider and create the client inside the same
+// dynamic boundary — this keeps all Agora imports out of the SSR bundle
+const AgoraProvider = dynamic(
+  async () => {
+    const { AgoraRTCProvider, default: AgoraRTC } =
+      await import('agora-rtc-react');
+    return {
+      default: ({ children }: { children: React.ReactNode }) => {
+        const client = useMemo(
+          () => AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8' }),
+          [],
+        );
+        return <AgoraRTCProvider client={client}>{children}</AgoraRTCProvider>;
+      },
+    };
+  },
+  { ssr: false },
+);
+
+export default function Page() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <AgoraProvider>
+        <ConversationComponent />
+      </AgoraProvider>
+    </Suspense>
+  );
+}
+```
+
+**Why this works:** Both `AgoraRTCProvider` and `AgoraRTC.createClient` are inside the dynamic import callback, so they only execute in the browser. The `useMemo` ensures the client is created once per component mount, not on every render.
+
+## Pattern: Simple Component Lazy Load (Pages Router / Client Components)
+
+If you're in a Pages Router context or inside an existing `"use client"` boundary, the simpler pattern works:
+
+```tsx
+'use client';
+
+import { useState, useEffect } from 'react';
+
+export default function Page() {
+  const [VideoCall, setVideoCall] = useState<React.ComponentType | null>(null);
+
+  useEffect(() => {
+    import('./VideoCall').then((m) => setVideoCall(() => m.default));
+  }, []);
+
+  if (!VideoCall) return <div>Loading...</div>;
+  return <VideoCall />;
+}
+```
+
+## Key Rules
+
+- Mark any component that imports Agora with `"use client"`.
+- Never import `agora-rtc-sdk-ng` or `agora-rtc-react` at the top level of a Server Component.
+- Create the `AgoraRTC.createClient` instance inside a `useMemo` (or outside the component tree) — never in the render function directly.
+- Wrap dynamic-loaded Agora components in `<Suspense>` to handle the async load state.
+
+## Node.js Version Requirements
+
+- Next.js 14 / 15: requires Node.js >= 18
+- Next.js 16+: requires Node.js >= 20.9.0 (used in agent-samples clients)