agora_akrtc_engine 1.0.0

Custom modified Flutter plugin of Agora RTC SDK.

agora_akrtc_engine

Real-time voice and video calling engine wrapper with production-ready Agora Call UI Kit for Flutter.

---

🌐 Platform Support & Verification Matrix

Platform	Support Status	Notes
Android	✅ Tested & Verified	Full Audio & Video calling supported (Mobile to Mobile)
iOS	✅ Tested & Verified	Full Audio & Video calling supported (Mobile to Mobile)
Web	🧪 In Development	Layout available; WebRTC integration undergoing active testing
Windows / macOS	🧪 Experimental	Plugins bundled; desktop UI undergoing active testing

---

📱 WhatsApp-Style Call UI Kit & Feature Overview

This package includes a pre-built, WhatsApp-style Agora Call UI Kit supporting Single Audio, Single Video, Group Audio, and Group Video call modes.

🌟 Key Features

• Zero-Drift Timer Architecture: Duration calculated dynamically from DateTime.now() - sessionStartedAt.
• Single Calls (Audio & Video):
  • Ringing state (Calling..., 00:00, yellow dot 🟡) with 60s timeout until remote user joins.
  • Remote user connect triggers connected state (Connected • 00:01, green dot 🟢), full-screen live video, and floating PiP inset card ("You").
  • Remote user offline triggers immediate endCall() and navigation pop.
• Group Calls (Audio & Video):
  • Dynamic Card Grid UI layout (Group Audio & Video) and Speaker View layout.
  • Session timer persists when members join, leave, or rejoin without resetting to 00:00.
  • 15-second grace period when all remote users temporarily leave.

---

🔑 Quick Setup (Initializing Credentials)

Pass your Agora App ID and App Certificate when creating AgoraCallController:

final AgoraCallController _callController = AgoraCallController(
  appId: 'YOUR_AGORA_APP_ID',
  appCertificate: 'YOUR_AGORA_APP_CERTIFICATE',
);

---

🛠️ Full UI & Event Customization Guide

1. ⚡ Event Callback Functions (onCallEnded, onUserJoined, onError)

Pass explicit event callbacks to AgoraCallUIKit or AgoraCallController to react to call lifecycle events in your app:

AgoraCallUIKit(
  controller: _callController,

  // 🔔 1. Call State Changed Callback
  onCallStateChanged: (CallState state) {
    print('Call state changed: $state');
  },

  // 🔔 2. Call Ended Callback (returns final CallSession with total duration)
  onCallEnded: (CallSession? session) {
    print('Call ended! Total duration: ${session?.formattedDuration}');
  },

  // 🔔 3. Participant Joined Callback
  onUserJoined: (CallParticipant participant) {
    print('Participant joined: ${participant.name} (UID: ${participant.uid})');
  },

  // 🔔 4. Participant Left Callback
  onUserOffline: (int uid) {
    print('Participant left: UID $uid');
  },

  // 🔔 5. Error Callback
  onError: (String errorMessage) {
    print('Call Error: $errorMessage');
  },
);

---

2. 🔘 Hiding & Showing Icons (Boolean true / false Flags)

Hide or show the top header bar, header buttons, or bottom dock control buttons using simple boolean flags:

AgoraCallUIKit(
  controller: _callController,

  // 📌 Top Header Visibility Flags
  showHeader: true,              // false = Hides entire top header bar (expands stage area)
  showInviteButton: false,       // false = Hides (+👤) invite participant button
  showMoreButton: true,          // false = Hides (...) options button

  // 📌 Bottom Control Dock Flags
  showCameraButton: true,        // false = Hides Camera ON/OFF button
  showSwitchCameraButton: false,  // false = Hides Switch Cam button
  showMicButton: true,           // false = Hides Microphone button
  showSpeakerButton: true,       // false = Hides Speakerphone button
  showEndCallButton: true,       // false = Hides Decline / End Call button
);

---

3. ⏱️ Timer Formatting Options (00:00 vs 00:00:00)

The call duration timer supports both 00:00 (mm:ss) and 00:00:00 (hh:mm:ss):

• Automatic Mode (Default): Displays 00:00 (mm:ss) when call duration is under 1 hour, and automatically switches to 01:04:15 (hh:mm:ss) when duration reaches 1 hour.
• Force Hours Mode: Pass includeHoursInTimer: true to display 00:00:00 (hh:mm:ss) right from the start:

AgoraCallUIKit(
  controller: _callController,
  includeHoursInTimer: true, // Forces '00:00:00' (hh:mm:ss) format
);

---

4. 🎨 Color Code & Theme Customization (AgoraCallTheme)

Customize background colors, gradients, button highlight colors, border radii, and avatar gradient palettes:

AgoraCallUIKit(
  controller: _callController,
  theme: const AgoraCallTheme(
    // 🌌 Screen Background Color & Gradient
    backgroundColor: Color(0xFF0F0F1A),
    backgroundGradient: LinearGradient(
      colors: [Color(0xFF0F0F1A), Color(0xFF1E1E2E)],
      begin: Alignment.topCenter,
      end: Alignment.bottomCenter,
    ),

    // 🟢 Active Speaker Border Highlight Color
    activeSpeakerBorderColor: Color(0xFF4CAF50),

    // 🔷 Control Button Active Highlight Color (e.g. Electric Blue)
    speakerActiveColor: Color(0xFF2196F3),

    // 🔴 End Call Button Color & Muted Indicator Badges
    endCallButtonColor: Color(0xFFFF3B30),
    micMutedBadgeColor: Color(0xFFFF3B30),

    // 🎛️ Control Dock Shape & Radius
    controlDockBackgroundColor: Color(0xFF1E1E26),
    controlDockRadius: 36.0,

    // 🎴 Video & Audio Tile Border Radius
    tileBorderRadius: 16.0,

    // 🎨 Avatar Gradient Palette Colors for User Cards
    avatarGradients: [
      [Color(0xFF9C27B0), Color(0xFF673AB7)], // Purple / Deep Purple
      [Color(0xFF2196F3), Color(0xFF00BCD4)], // Blue / Cyan
      [Color(0xFFFF5722), Color(0xFFE91E63)], // Orange / Pink
      [Color(0xFF4CAF50), Color(0xFF009688)], // Green / Teal
    ],
  ),
);

---

5. 🧩 Slot Builder Overrides (AgoraCallCustomBuilders)

Inject custom widgets for specific UI slots (Header, Control Dock, Avatars, or Video Tile Badges):

AgoraCallUIKit(
  controller: _callController,
  customBuilders: AgoraCallCustomBuilders(
    // Custom Top Header Bar
    headerBuilder: (context, controller) {
      return MyCustomHeader(
        title: controller.remoteUserName ?? 'Call',
        status: controller.statusText,
      );
    },
    // Custom Bottom Controls Dock
    controlsBuilder: (context, controller) {
      return MyCustomControlBar(
        onMicToggle: () => controller.toggleMic(),
        onCameraToggle: () => controller.toggleCamera(),
        onEndCall: () => controller.endCall(),
      );
    },
    // Custom Profile Avatar Renderer
    avatarBuilder: (context, name, avatarUrl, size) {
      return MyCustomAvatar(name: name, url: avatarUrl);
    },
  ),
);

---

6. ⚡ Headless Custom Page Layout (AgoraCallController)

For specialized apps (e.g. Telehealth / Medical consultation UI, Gaming, Fitness apps), use AgoraCallController as a headless state controller and build your own Flutter layout:

class TelehealthCallScreen extends StatelessWidget {
  final AgoraCallController controller;

  const TelehealthCallScreen({required this.controller});

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: controller,
      builder: (context, child) {
        final remoteUid = controller.remoteParticipant?.uid ?? 0;

        return Scaffold(
          body: Stack(
            children: [
              // 1. Doctor Full-Screen Live Video Feed
              if (remoteUid != 0)
                AgoraVideoView(
                  controller: VideoViewController.remote(
                    rtcEngine: controller.engine!,
                    canvas: VideoCanvas(uid: remoteUid),
                    connection: RtcConnection(channelId: controller.channelName),
                  ),
                ),

              // 2. Doctor Header Card (Top Left)
              Positioned(
                top: 50, left: 16, right: 16,
                child: MyDoctorCard(
                  name: 'Dr. Sarah Kim',
                  specialty: 'Cardiologist',
                  duration: controller.formattedDuration,
                ),
              ),

              // 3. Floating Inset Patient Video (Bottom Right)
              Positioned(
                right: 16, bottom: 140,
                child: MyPatientPipView(controller: controller),
              ),

              // 4. Custom Translucent Bottom Controls
              Positioned(
                bottom: 0, left: 0, right: 0,
                child: MyGlassControlSheet(controller: controller),
              ),
            ],
          ),
        );
      },
    );
  }
}

---

🚀 Quick Getting Started

1. Add Permissions

Android (AndroidManifest.xml):

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAMERA" />
<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_CONNECT" />

iOS (ios/Runner/Info.plist):

<key>NSCameraUsageDescription</key>
<string>Camera access is required for real-time video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for real-time voice and video calls.</string>

<!-- Background Audio Calls Support -->
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

---

📄 License

The project is under the MIT license.