✨ Support mediaplayer local cache

android/src/main/java/im/zego/zego_express_engine/internal/ZegoExpressEngineEventHandler.java

@@ -1637,6 +1637,24 @@ public void onMediaPlayerVideoSizeChanged(ZegoMediaPlayer mediaPlayer, int width
 
             sink.success(map);
         }
+
+        @Override
+        public void onMediaPlayerLocalCache(ZegoMediaPlayer mediaPlayer, int errorCode, String resource, String cachedFile) {
+            super.onMediaPlayerLocalCache(mediaPlayer, errorCode, resource, cachedFile);
+            ZegoLog.log("[onMediaPlayerLocalCache] idx: %d, error: %d, resource: %s, cachedFile: %s", mediaPlayer.getIndex(), errorCode, resource, cachedFile);
+
+            if (guardSink()) { return; }
+
+            HashMap<String, Object> map = new HashMap<>();
+
+            map.put("method", "onMediaPlayerLocalCache");
+            map.put("mediaPlayerIndex", mediaPlayer.getIndex());
+            map.put("errorCode", errorCode);
+            map.put("resource", resource);
+            map.put("cachedFile", cachedFile);
+
+            sink.success(map);
+        }
     };
 
 

android/src/main/java/im/zego/zego_express_engine/internal/ZegoExpressEngineMethodHandler.java

@@ -4144,6 +4144,20 @@ public static void mediaPlayerSetPlayMediaStreamType(MethodCall call, final Resu
         result.success(null);
     }
 
+    @SuppressWarnings("unused")
+    public static void mediaPlayerEnableLocalCache(MethodCall call, final Result result) {
+        Integer index = call.argument("index");
+        ZegoMediaPlayer mediaPlayer = mediaPlayerHashMap.get(index);
+
+        if (mediaPlayer != null) {
+            boolean enable = ZegoUtils.boolValue((Boolean) call.argument("enable"));
+            String cacheDir = call.argument("cacheDir");
+
+            mediaPlayer.enableLocalCache(enable, cacheDir);
+        }
+        result.success(null);
+    }
+
     /* AudioEffectPlayer */
 
     @SuppressWarnings("unused")

ios/Classes/internal/ZegoExpressEngineEventHandler.m

@@ -1462,6 +1462,22 @@ - (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer videoSizeChanged:(CGSize)size
     }
 }
 
+- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer localCacheError:(int)errorCode resource:(NSString *)resource cachedFile:(NSString *)cachedFile {
+    FlutterEventSink sink = _eventSink;
+    ZGLog(@"[onMediaPlayerLocalCache] idx: %d, error: %d, resource: %s, cached: %s", mediaPlayer.index.intValue, errorCode, resource, cachedFile);
+
+    GUARD_SINK
+    if (sink) {
+        sink(@{
+            @"method": @"onMediaPlayerLocalCache",
+            @"mediaPlayerIndex": mediaPlayer.index,
+            @"errorCode": @((int)errorCode),
+            @"resource": resource,
+            @"cachedFile": cachedFile,
+        });
+    }
+}
+
 #pragma mark - ZegoAudioEffectPlayerEventHandler
 
 - (void)audioEffectPlayer:(ZegoAudioEffectPlayer *)audioEffectPlayer audioEffectID:(unsigned int)audioEffectID playStateUpdate:(ZegoAudioEffectPlayState)state errorCode:(int)errorCode {

ios/Classes/internal/ZegoExpressEngineMethodHandler.m

@@ -3887,6 +3887,19 @@ - (void)mediaPlayerSetPlayMediaStreamType:(FlutterMethodCall *)call result:(Flut
     result(nil);
 }
 
+- (void)mediaPlayerEnableLocalCache:(FlutterMethodCall *)call result:(FlutterResult)result {
+    NSNumber *index = call.arguments[@"index"];
+    ZegoMediaPlayer *mediaPlayer = self.mediaPlayerMap[index];
+
+    if (mediaPlayer) {
+        BOOL enable = [ZegoUtils boolValue:call.arguments[@"enable"]];
+        NSString *cacheDir = call.arguments[@"cacheDir"];
+        [mediaPlayer enableLocalCache:enable cacheDir:cacheDir];
+    }
+
+    result(nil);
+}
+
 #pragma mark - AudioEffectPlayer
 
 - (void)createAudioEffectPlayer:(FlutterMethodCall *)call result:(FlutterResult)result {

lib/src/impl/zego_express_impl.dart

@@ -3061,7 +3061,17 @@ class ZegoExpressImpl {
               mediaPlayer, map['width'], map['height']);
         }
         break;
+      case 'onMediaPlayerLocalCache':
+        if (ZegoExpressEngine.onMediaPlayerLocalCache == null) return;
 
+        int? mediaPlayerIndex = map['mediaPlayerIndex'];
+        ZegoMediaPlayer? mediaPlayer =
+            ZegoExpressImpl.mediaPlayerMap[mediaPlayerIndex!];
+        if (mediaPlayer != null) {
+          ZegoExpressEngine.onMediaPlayerLocalCache!(mediaPlayer,
+              map['errorCode'], map['resource'], map['cachedFile']);
+        }
+        break;
       /* AudioEffectPlayer */
 
       case 'onAudioEffectPlayStateUpdate':
@@ -3732,6 +3742,12 @@ class ZegoMediaPlayerImpl extends ZegoMediaPlayer {
         'mediaPlayerSetPlayMediaStreamType',
         {'index': _index, 'streamType': streamType.index});
   }
+
+  Future<void> enableLocalCache(bool enable, String cacheDir) async {
+    return await ZegoExpressImpl._channel.invokeMethod(
+        'mediaPlayerEnableLocalCache',
+        {'index': _index, 'enable': enable, 'cacheDir': cacheDir});
+  }
 }
 
 class ZegoAudioEffectPlayerImpl extends ZegoAudioEffectPlayer {

lib/src/zego_express_api.dart

@@ -1207,6 +1207,21 @@ class ZegoExpressEngine {
           ZegoMediaPlayer mediaPlayer, ZegoMediaPlayerFirstFrameEvent event)?
       onMediaPlayerFirstFrameEvent;
 
+  /// The callback triggered when the media player caches http/https network resource locally.
+  ///
+  /// Available since: 3.12.0
+  /// Description: The callback triggered when the media player caches http/https network resource locally.
+  /// Trigger: This callback occurs after the media player caches http/https network resources.
+  /// Caution: This callback will not take effect until the [enableLocalCache] API is called and the http/https network resources are played.
+  /// Related APIs: Need to call the [enableLocalCache] interface.
+  ///
+  /// - [mediaPlayer] Callback player object.
+  /// - [errorCode] Error code.
+  /// - [resource] Played resource
+  /// - [cachedFile] Cached file
+  static void Function(ZegoMediaPlayer mediaPlayer, int errorCode,
+      String resource, String cachedFile)? onMediaPlayerLocalCache;
+
   /// Audio effect playback state callback.
   ///
   /// Available since: 1.16.0

lib/src/zego_express_defines.dart

@@ -4457,6 +4457,18 @@ abstract class ZegoMediaPlayer {
   /// - [enable] Whether to enable live audio effect.
   /// - [mode] Live audio effect mode.
   Future<void> enableLiveAudioEffect(bool enable, ZegoLiveAudioEffectMode mode);
+
+  /// Enable local caching of http/https network resources.
+  ///
+  /// Available since: 3.12.0
+  /// Description: When playing http/https network resources, when the local cache is enabled, the network resources will be saved locally and the cache information will be called back through [onMediaPlayerLocalCache].
+  /// When to call: It can be called after the engine by [createEngine] has been initialized and the media player has been created by [createMediaPlayer]. Called after [loadResource] or during playback, it will take effect next playback.
+  /// Caution: Only http/https single file type network resources are supported. If there is a [seek] operation during playback, the cache will fail.
+  ///
+  /// - [enable] Whether to enable local caching.
+  /// - [cacheDir] Cache dir. If left blank, the directory specified internally by SDK will be used.
+  Future<void> enableLocalCache(bool enable, String cacheDir);
+
 }
 
 abstract class ZegoAudioEffectPlayer {

lib/src/zego_express_error_code.dart

@@ -706,6 +706,9 @@ class ZegoErrorCode {
   /// Description: the passed parameter is not in the valid value range. <br>Cause: error setting parameters. <br>Solutions: Review the interface comment and pass in a value within the legal range.
   static const int MediaPlayerParamValueRangeIllegal = 1008043;
 
+  /// Description: Failed to cache network resource file. <br>Cause: During playback, [seekTo] operation will cause cache failure, and network reasons or incomplete playback caused by active stop will also cause cache failure. <br>Solutions: Check whether there is a [seekTo] operation, whether the playback failed due to network reasons, or whether the playback stopped actively.
+  static const int MediaPlayerLocalCacheFailed = 1008044;
+
   /// Description: MediaPlayer internal error. <br>Cause: internal error. <br>Solutions: Contact Technical support.
   static const int MediaPlayerInnerError = 1008099;
 

windows/internal/ZegoExpressEngineEventHandler.cpp

@@ -882,6 +882,21 @@ void ZegoExpressEngineEventHandler::onMediaPlayerVideoSizeChanged(EXPRESS::IZego
     }
 }
 
+void ZegoExpressEngineEventHandler::onMediaPlayerLocalCache(IZegoMediaPlayer * mediaPlayer, int errorCode, const std::string &resource, const std::string & cachedFile) {
+    ZF::logInfo("[onMediaPlayerLocalCache] index: %d, error: %d, resource: %s, cachedFile: %s", mediaPlayer->getIndex(), errorCode, resource, cachedFile);
+
+    if (eventSink_) {
+        FTMap retMap;
+        retMap[FTValue("method")] = FTValue("onMediaPlayerLocalCache");
+        retMap[FTValue("mediaPlayerIndex")] = FTValue(mediaPlayer->getIndex());
+
+        retMap[FTValue("errorCode")] = FTValue(errorCode);
+        retMap[FTValue("resource")] = FTValue(resource);
+        retMap[FTValue("cachedFile")] = FTValue(cachedFile);
+
+        eventSink_->Success(retMap);
+    }
+}
 
 // MediaDataPublisher
 void ZegoExpressEngineEventHandler::onMediaDataPublisherFileOpen(EXPRESS::IZegoMediaDataPublisher *mediaDataPublisher, const std::string &path) {

windows/internal/ZegoExpressEngineEventHandler.h

@@ -225,6 +225,8 @@ class ZegoExpressEngineEventHandler
 
     void onMediaPlayerVideoSizeChanged(EXPRESS::IZegoMediaPlayer* mediaPlayer, int width, int height) override;
 
+    void onMediaPlayerLocalCache(IZegoMediaPlayer * mediaPlayer, int errorCode, const std::string &resource, const std::string & cachedFile) override;
+
 // MediaDataPublisher
 protected:
     void onMediaDataPublisherFileOpen(EXPRESS::IZegoMediaDataPublisher *mediaDataPublisher, const std::string &path) override;

windows/internal/ZegoExpressEngineMethodHandler.cpp

@@ -2824,6 +2824,25 @@ void ZegoExpressEngineMethodHandler::mediaPlayerSetPlayMediaStreamType(
     }
 }
 
+void mediaPlayerEnableLocalCache(
+    flutter::EncodableMap &argument,
+    std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result) {
+    auto index = std::get<int32_t>(argument[FTValue("index")]);
+    auto mediaPlayer = mediaPlayerMap_[index];
+
+    if (mediaPlayer) {
+        auto enable = std::get<bool>(argument[FTValue("enable")]);
+        std::string cacheDir = std::get<std::string>(argument[FTValue("cacheDir")]);
+
+        mediaPlayer->enableLocalCache(enable, cacheDir);
+
+        result->Success();
+    } else {
+        result->Error("mediaPlayerEnableLocalCache_Can_not_find_player",
+                      "Invoke `mediaPlayerEnableLocalCache` but can't find specific player");
+    }
+}
+
 void ZegoExpressEngineMethodHandler::createMediaDataPublisher(
     flutter::EncodableMap &argument,
     std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result) {

windows/internal/ZegoExpressEngineMethodHandler.h

@@ -665,6 +665,9 @@ class ZegoExpressEngineMethodHandler {
     void mediaPlayerSetPlayMediaStreamType(
         flutter::EncodableMap &argument,
         std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result);
+    void mediaPlayerEnableLocalCache(
+        flutter::EncodableMap &argument,
+        std::unique_ptr<flutter::MethodResult<flutter::EncodableValue>> result);
     /* Media Data Publisher */
     void createMediaDataPublisher(
         flutter::EncodableMap &argument,