# agora_rtc_engine: the Flutter wrapper around the Agora Video SDK

> agora_rtc_engine is a Flutter plugin that wraps the Agora Video SDK for Android, iOS, macOS and Windows, with a web build still in alpha. It gives a Dart API for real time voice and video, and it reserves raw media processing for native code, which is the main constraint to plan around.

**AgoraIO-Extensions/Agora-Flutter-SDK** — Flutter plugin of Agora RTC SDK for Android/iOS/macOS/Windows

- Repository: https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK
- Website: https://pub.dev/packages/agora_rtc_engine
- Stars: 796 · Forks: 447
- Language: Dart
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/agoraio-extensions-agora-flutter-sdk

## A wrapper, and the distinction that matters

The README is explicit about what this package is: a Flutter plugin that wraps the Agora Video SDK. Agora provides building blocks for adding real time voice and video communication, and this plugin is the Dart layer that exposes those blocks to a Flutter application.

That framing matters because it sets expectations about the ceiling of the API. The plugin is a binding over a native SDK, not an independent implementation, so what you can do is bounded by what the native SDK exposes and what the wrapper has ported. The repository layout is consistent with that: separate android, ios, macos and windows directories for the platform sides, a lib directory for the Dart API, and a shared directory for code common to the platforms.

The published package is agora_rtc_engine on pub.dev, and the repository topics cover agora, android, flutter, ios, macos, rtc, sdk, video and windows.

The audience is a Flutter team that already decided to use Agora's infrastructure and now needs the client side. It is not a conferencing product in itself: there is no signalling or user management described here, and the examples in the example/lib/examples folder are the documented starting point, ranging from basic to advanced usage.

## The main branch tracks Native SDK 4.x and breaks with it

The note at the top of the README is the single most important line for anyone pinning a version.

The main branch is described as a major update based on the Agora Native SDK 4.x, which introduces some breaking changes. Previous releases are on other branches, and the README points at the 5.x branch for versions below 6.0.0.

So there are two lines of development with different semantics. The current branch tracks a native SDK generation that changed the API underneath, and the older branch preserves compatibility with the previous generation. That is a deliberate structure for a plugin that mirrors a native SDK, but it means your choice of branch is a choice about which native API generation you are binding to, and the plugin version alone does not tell you that.

The release list in the repository shows how this plays out in practice. Release 6.6.4 is dated 2026-09-04, Release 6.5.5 is dated 2026-09-16, and Release 6.5.4 is dated 2026-05-15. A 6.5.5 published after a 6.6.4 is unusual for a semantic version scheme, and it suggests that more than one release line is being published at once rather than a single ordered sequence.

For a team that wants to upgrade on a schedule, that ambiguity is worth resolving with the project before you choose a pin, rather than discovering it at the next dependency bump.

## Permissions are the real first run: camera, microphone and Bluetooth

The Agora Video SDK requires Camera and Microphone permission to start a video call, and the plugin does not remove that step. The Android side points at the AndroidManifest.xml file in the plugin's own android/src/main directory, and the permissions it needs are listed there.

```xml
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<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_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
```

Below that block come the Bluetooth permissions, with a comment explaining that the Agora SDK requires them in case users are on Bluetooth devices, and a further permission for Android 12 and above devices.

On iOS and macOS the equivalent work is in Info.plist, where you add the Privacy - Microphone Usage Description and Privacy - Camera Usage Description keys with your own text in the Value column. The README links to the Agora project setup documentation for each platform for the latest permission settings, which is the sensible reference because platform requirements move.

The practical consequence for a team is that permissions are per platform and per application, and a wrapper cannot remove that work. It can only tell you where the keys belong.

## The web build is alpha and gives you a subset of the native API

The README is unusually blunt about the web target. The web version of agora_rtc_engine is in alpha, the documentation is incomplete, and it has only been tested on desktop web.

The reason for the limitation is structural. The web build sits on top of iris_web, a wrapper for the Agora Web SDK 4.x, and the goal of iris_web is to align the native SDK APIs for Android, iOS, macOS and Windows with the web APIs. Because the underlying web SDK is what actually runs, only a subset of the native SDK APIs can be implemented on the web.

The failure mode is documented as well. If an API returns AgoraRtcException with a -4 error code, that means the API is not supported at this time. That is a usable contract, since you can branch on the error code rather than discovering the gap in production.

The web target also has a different setup story, because you have to place the iris_web artifact yourself as a script tag in your project's web/index.html file.

```html
<!-- <your-project>/web/index.html -->
<!DOCTYPE html>
<html>
...
<body>
  ...
  <script src="iris-web-rtc_<x.y.z>.js"></script>
</body>
</html>
```

For testing only, the README shows depending on the Agora CDN copy of the same artifact directly in the script tag, with a download link to the iris-web-rtc file listed under the example.

## Raw media processing is deliberately left in native code

There is one feature in this plugin that deserves a careful reading, because it explains the boundary of what you can do from Dart.

The README says that, due to performance constraints, direct implementation of advanced features like video and audio raw data processing is not currently feasible on the Flutter side. Instead, the plugin lets you create an RtcEngine within Flutter by using the native handle from the RtcEngine on Android or the AgoraRtcEngineKit on iOS of the Agora RTC Native SDK. The intent is to let an application reach the advanced features of the native SDK while staying inside a Flutter project.

That feature requires agora_rtc_engine 6.3.0 or later, and the README points at the ProcessVideoRawData example as the reference implementation.

The design tells you something about the plugin's priorities. The team that wrote it judged that moving raw frames across the Dart boundary would cost too much performance, so they kept the fast path native and made the escape hatch explicit, requiring the platform code and the Dart code to work together. If your product needs per frame processing, audio effects, or custom video pipelines, you are signing up for a native module no matter which SDK you choose. The plugin reduces how much of that code you have to write; it does not remove it.

This path is Android and iOS only, since it depends on the native handle those two platforms expose.

## Known issue: iOS builds that fail only in release mode

The README has a known issues section with a single entry: iOS does not work in release mode.

The fix offered is to set a configuration so that symbols are not stripped, and the README links to the Flutter documentation on stripping iOS symbols for more detail. In other words, the failure is not in the plugin logic, it is in how the release build of an iOS application interacts with the native binary that the plugin ships.

This is the kind of entry that is easy to skim and expensive to discover for yourself, because debug builds work. A team that tests in debug and demos in release is exactly the setup that hits it.

The broader documentation situation is better than that entry suggests. The README ends with an API reference section linking to the reference documentation for the Flutter API, for Android, for iOS and macOS, for Windows through the C++ SDK, and for the web, each for the 4.x or 6.x line. So the plugin does not have to carry the whole reference on its own, and the API reference for the plugin itself is the one on the Flutter side.

There is also a CHANGELOG.md, a CONTRIBUTING.md, an analysis_options.yaml for the Dart analyzer, a build.yaml, a scripts directory and a ci directory, so the repository carries the tooling of a maintained package even though the README itself is brief.

## Licence, alternatives and where the wrapper ends

The plugin is MIT licensed, with the licence file at the root of the repository and the pub.dev page as the published homepage. The repository is not archived and the last push was on 2026-09-16, with the 6.5.5 release published the same day.

The realistic alternative is to skip the wrapper and integrate the Agora Native SDK directly into your Flutter project, which is the same native code the plugin wraps, without the Dart layer. The difference in approach is real. Direct integration gives you the complete native API and none of the wrapper's constraints, including the fact that only some of the native surface is reachable from Dart and that the web target implements a subset. The wrapper gives you one Dart API across four platforms, a consistent event and callback surface, and a plugin you can update by changing a version constraint.

The trade runs along that same line. If your application is Android and iOS only, needs advanced native features, and the team is comfortable with two native code bases, the wrapper adds a layer you do not need. If your application targets several desktop and mobile platforms from one Flutter codebase, the wrapper is doing exactly the job it was built for.

There is a third option for the web only, since the plugin's web story is built on iris_web, which wraps the Agora Web SDK 4.x. If your target is a browser application, that artifact and its API reference are the layer you would evaluate.

The boundary to keep in mind is that this is a client side binding. The plugin does not provide the service, the account, the project configuration or the access control, so what you build on top of it inherits all of that from the Agora side.

## Conclusion

Take agora_rtc_engine if you are building a Flutter application with real time voice or video and you want one Dart API across Android, iOS, macOS and Windows rather than four native integrations. Do not expect the web target to be production ready, since the README calls it alpha with incomplete documentation and only desktop web tested, and do not plan to process raw audio or video frames in Dart, because the plugin routes that to native code. Before you start, read the note that the main branch tracks Agora Native SDK 4.x with breaking changes and that older releases live on the 5.x branch, and check whether the release numbering in the repository, where 6.6.4 and 6.5.5 were both released in September 2026, matches the version your project pins.

## FAQ

### What is the agora_rtc_engine Flutter plugin and which platforms does it support?

It is a Flutter plugin that wraps the Agora Video SDK to add real time voice and video communication to an application. The published platforms are Android, iOS, macOS and Windows, with a web build that the README describes as alpha, with incomplete documentation and tested only on desktop web.

### How do I add agora_rtc_engine to a Flutter project?

The README instructs you to add agora_rtc_engine as a dependency in your pubspec.yaml file, and to get basic and advanced examples from the example/lib/examples folder of the repository.

### Which permissions does the Agora Video SDK need on Android and iOS?

On Android the plugin's AndroidManifest.xml lists Internet, read phone state, record audio, camera, modify audio settings, wifi state and network state, plus Bluetooth and, for Android 12 and above, Bluetooth Connect. On iOS and macOS you add the Privacy - Microphone Usage Description and Privacy - Camera Usage Description keys to Info.plist.

### How do I use raw audio or video processing with the Flutter SDK?

The plugin cannot process raw media in Dart because of performance constraints. From agora_rtc_engine 6.3.0 you can create an RtcEngine in Flutter using the native handle from RtcEngine on Android or AgoraRtcEngineKit on iOS, and the ProcessVideoRawData example shows the reference implementation.

### What does the -4 error code mean in the agora_rtc_engine web build?

The web build is built on iris_web over the Agora Web SDK 4.x, so only a subset of the native SDK APIs can be implemented. If an API returns AgoraRtcException with a -4 error code, that API is not supported at this time.

### Why does iOS not work in release mode with agora_rtc_engine?

The README lists it as a known issue and points to a configuration change that avoids stripping symbols, referring to the Flutter documentation on stripping iOS symbols for details. The plugin ships a native binary, and the failure only shows up in a release build, so it needs to be tested there rather than only in debug.

## Sources

- [AgoraIO-Extensions/Agora-Flutter-SDK on GitHub](https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK)
- [License: MIT](https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/blob/main/LICENSE)
- [Project website](https://pub.dev/packages/agora_rtc_engine)
- [README](https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/blob/main/README.md)
- [Releases](https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/agoraio-extensions-agora-flutter-sdk