agora_akrtc_engine 1.0.2

Custom modified Flutter plugin of Agora RTC SDK.

agora_akrtc_engine

🚀 The Ultimate Real-Time Audio & Video Calling Engine for Flutter featuring Built-in Dynamic Token Generation, Boolean Control Toggling, Full Color & Theme Customization, Production-Ready Mobile UI Kit, and 100% Custom Headless Layout Freedom.

---

🌐 Platform Support & Roadmap

Platform	Support Status	Capabilities
Android	✅ Tested & Verified	Full Audio & Video calling (Single & Group)
iOS	✅ Tested & Verified	Full Audio & Video calling (Single & Group)
Web	🚀 Future Support (In Dev)	WebRTC integration & responsive layout in active development
Windows / macOS	🚀 Future Support (In Dev)	Desktop UI & bundled native plugins in active development

---

🌟 Why Developers Choose agora_akrtc_engine

🔑 1. Built-in Dynamic Token Generation (Zero Extra Token Packages Needed!)

Forget setting up complex third-party token server dependencies or external packages! agora_akrtc_engine includes a built-in dynamic RTC token generator. Simply provide your Agora App ID and App Certificate, and the engine automatically generates and refreshes secure AccessToken2 RTC tokens on-the-fly.

🎨 2. 100% Customizable Color Codes & Themes (AgoraCallTheme)

Tailor every color, gradient, border radius, text style, dock shape, and avatar color palette to match your brand identity perfectly. Change background dark modes, active speaker highlights, button active colors, and mute badges effortlessly!

🔘 3. Instant Control Toggling with Simple Boolean Flags

Hide or show any control button or top header element using simple bool (true / false) flags:

AgoraCallUIKit(
  controller: _callController,

  // 📌 Visibility Flags
  showHeader: true,             // false = Hides entire top header bar
  showInviteButton: false,      // false = Hides (+👤) invite button
  showMoreButton: true,         // false = Hides (...) options button
  showCameraButton: true,       // false = Hides Camera ON/OFF button
  showSwitchCameraButton: true, // false = Hides Switch Camera button
  showMicButton: true,          // false = Hides Microphone button
  showSpeakerButton: true,      // false = Hides Speakerphone button
  showEndCallButton: true,      // false = Hides End Call button
);

⚡ 4. 100% Headless Custom UI Freedom (AgoraCallController)

Need a completely unique UI for specialized applications (e.g. Telehealth / Doctor Consultation, Social Dating, Gaming, or Fitness)? Use AgoraCallController as a pure headless state controller. Build your own Flutter layout from scratch while delegating all WebRTC engine state, RTC tokens, mute toggles, and live video streams to the engine!

---

🎨 Complete Color Code & Theme Customization Guide (AgoraCallTheme)

Use AgoraCallTheme to configure custom colors, gradients, dock shapes, and typography across the calling UI:

AgoraCallUIKit(
  controller: _callController,

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

    // 🟢 2. Active Speaker Highlight Border Color
    activeSpeakerBorderColor: Color(0xFF4CAF50), // Vibrant Emerald Green

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

    // 🔴 4. End Call Button & Muted Badge Color
    endCallButtonColor: Color(0xFFFF3B30), // Crimson Red
    micMutedBadgeColor: Color(0xFFFF3B30), // Mute Badge Red

    // 🎛️ 5. Control Dock Background & Shape Radius
    controlDockBackgroundColor: Color(0xFF1E1E26), // Dark Slate Gray Sheet
    controlDockRadius: 36.0,                      // Rounded Capsule Shape

    // 🎴 6. Video & Audio Card Tile Border Radius
    tileBorderRadius: 16.0,                       // Rounded Tile Corners

    // ✏️ 7. Top Header Typography Styles
    headerTitleStyle: TextStyle(
      color: Colors.white,
      fontSize: 18,
      fontWeight: FontWeight.bold,
    ),
    headerSubtitleStyle: TextStyle(
      color: Colors.white70,
      fontSize: 12,
      fontWeight: FontWeight.w500,
    ),

    // 🎨 8. User Avatar Multi-Color Gradient Palette
    avatarGradients: [
      [Color(0xFF9C27B0), Color(0xFF673AB7)], // Purple Gradient
      [Color(0xFF2196F3), Color(0xFF00BCD4)], // Cyan Blue Gradient
      [Color(0xFFFF5722), Color(0xFFE91E63)], // Orange Pink Gradient
      [Color(0xFF4CAF50), Color(0xFF009688)], // Teal Green Gradient
    ],
  ),
);

📋 Theme Property Color Reference Table

Property	Default Color / Value	Description
backgroundColor	Color(0xFF121218)	Full-screen background color
backgroundGradient	null (Optional)	Multi-color linear gradient overlay
activeSpeakerBorderColor	Color(0xFF4CAF50)	Border glow highlight around active speaker tile
speakerActiveColor	Color(0xFF2196F3)	Highlight color for enabled mic/speaker buttons
endCallButtonColor	Color(0xFFFF3B30)	Circle background color for Decline / End Call button
micMutedBadgeColor	Color(0xFFFF3B30)	Small badge indicator color for muted users
controlDockBackgroundColor	Color(0xFF1E1E26)	Translucent bottom sheet control bar color
controlDockRadius	36.0	Rounded corner radius for bottom control dock
tileBorderRadius	16.0	Corner radius for video & audio user cards
avatarGradients	4 Gradient Sets	Gradient color pairs used for rendering user avatars

---

📱 Supported Calling Modes

• 📞 Single Audio Call (1-on-1): Clean audio stage with animated speaker waveforms.
• 📹 Single Video Call (1-on-1): Full-screen remote video feed with floating Picture-in-Picture (PiP) local preview.
• 👥 Group Audio Call: Dynamic responsive user card grid with active speaker highlight borders.
• 🎥 Group Video Call: Responsive Grid View or Active Speaker View layout options.

---

⏱️ Key Features

• 🔐 Zero-Drift Call Timer: Duration calculated dynamically from DateTime.now() - sessionStartedAt to prevent clock drift.
• 🟡 Smart Ringing & Auto-Timeout: Automatic 60-second timeout handling for unanswered calls.
• 🟢 Automatic Reconnection & Grace Period: Session timer persists during temporary network drops or member reconnects.
• 🎛️ Comprehensive Event Callbacks: React to lifecycle events (onCallStateChanged, onCallEnded, onUserJoined, onUserOffline, onError).

---

📦 Installation

Add agora_akrtc_engine to your pubspec.yaml:

dependencies:
  agora_akrtc_engine: ^1.0.1

Run command:

flutter pub get

---

🚀 Quick Setup & Credentials

Initialize the controller with your Agora App ID and App Certificate. Dynamic RTC tokens are generated automatically:

import 'package:agora_akrtc_engine/agora_rtc_engine.dart';

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

---

💻 Integration Code Examples

Option 1: Out-of-the-Box Call UI (AgoraCallUIKit)

class CallScreen extends StatelessWidget {
  final AgoraCallController controller;

  const CallScreen({super.key, required this.controller});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: AgoraCallUIKit(
        controller: controller,
        onCallEnded: (session) {
          Navigator.pop(context);
        },
      ),
    );
  }
}

---

Option 2: Headless Custom UI (Telehealth / Custom Apps)

Build any custom layout from scratch using AgoraCallController to drive your state:

class TelehealthCallScreen extends StatelessWidget {
  final AgoraCallController controller;

  const TelehealthCallScreen({super.key, 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 Stream
              if (remoteUid != 0)
                AgoraVideoView(
                  controller: VideoViewController.remote(
                    rtcEngine: controller.engine!,
                    canvas: VideoCanvas(uid: remoteUid),
                    connection: RtcConnection(channelId: controller.channelName),
                  ),
                ),

              // 2. Doctor Overlay Header Card
              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 PiP)
              Positioned(
                right: 16, bottom: 140,
                child: MyPatientPipView(controller: controller),
              ),

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

---

🛠️ Event Callbacks

Listen to real-time session events easily:

AgoraCallUIKit(
  controller: _callController,

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

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

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

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

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

---

🔒 Platform Permissions

📱 Android (android/app/src/main/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

This project is licensed under the MIT License.