# 媒体播放器缓存 (/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-cache)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_mediaplayer_cache"></a>

<a id="api_imediaplayercachemanager_enableautoremovecache"></a>

<a id="ariaid-title2"></a>

## enableAutoRemoveCache [#enableautoremovecache]

设置是否开启自动清除缓存文件功能。

<a id="api_imediaplayercachemanager_enableautoremovecache__prototype"></a>

```dart
Future<void> enableAutoRemoveCache(bool enable);
```

<a id="api_imediaplayercachemanager_enableautoremovecache__detailed_desc"></a>

开启自动清除缓存文件后，当播放器中缓存的媒体文件超过你设置的文件数量或总缓存大小的上限时，SDK 会自动清除近期最少使用的一个缓存文件。

<a id="api_imediaplayercachemanager_enableautoremovecache__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="enable"></a>
<Parameter name="enable">

是否自动清除缓存文件：

- true：开启自动清除缓存文件功能。
- false：（默认）关闭自动清除缓存文件功能。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_enableautoremovecache__return_values"></a>

### 返回值 [#返回值]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_getcachedir"></a>

<a id="ariaid-title3"></a>

## getCacheDir [#getcachedir]

获取缓存文件的储存路径。

<a id="api_imediaplayercachemanager_getcachedir__prototype"></a>

```dart
Future<String> getCacheDir(int length);
```

<a id="api_imediaplayercachemanager_getcachedir__detailed_desc"></a>

如果你在调用该方法前未曾调用 [setCacheDir](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_setcachedir) 方法自定义缓存文件的储存路径，该方法返回的为 SDK 默认的缓存文件储存路径。

<a id="api_imediaplayercachemanager_getcachedir__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="length"></a>
<Parameter name="length">

输入参数，缓存文件储存路径字符串的最大长度。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_getcachedir__return_values"></a>

### 返回值 [#返回值-1]

- 方法调用成功时，返回缓存文件的储存路径。
- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-1]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_getcachefilecount"></a>

<a id="ariaid-title4"></a>

## getCacheFileCount [#getcachefilecount]

获取当前已缓存的媒体文件的总数量。

<a id="api_imediaplayercachemanager_getcachefilecount__prototype"></a>

```dart
Future<int> getCacheFileCount();
```

<a id="api_imediaplayercachemanager_getcachefilecount__detailed_desc"></a>

<a id="api_imediaplayercachemanager_getcachefilecount__return_values"></a>

### 返回值 [#返回值-2]

- ≥ 0：方法调用成功，返回当前已缓存的媒体文件的总数量。
- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-2]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_getmaxcachefilecount"></a>

<a id="ariaid-title5"></a>

## getMaxCacheFileCount [#getmaxcachefilecount]

获取所设置的缓存文件数量上限。

<a id="api_imediaplayercachemanager_getmaxcachefilecount__prototype"></a>

```dart
Future<int> getMaxCacheFileCount();
```

<a id="api_imediaplayercachemanager_getmaxcachefilecount__detailed_desc"></a>

SDK 默认的缓存文件数量上限为 1000。

<a id="api_imediaplayercachemanager_getmaxcachefilecount__return_values"></a>

### 返回值 [#返回值-3]

- &gt; 0：方法调用成功，返回缓存文件数量的上限。
- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-3]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_getmaxcachefilesize"></a>

<a id="ariaid-title6"></a>

## getMaxCacheFileSize [#getmaxcachefilesize]

获取所设置的缓存文件总缓存的上限。

<a id="api_imediaplayercachemanager_getmaxcachefilesize__prototype"></a>

```dart
Future<int> getMaxCacheFileSize();
```

<a id="api_imediaplayercachemanager_getmaxcachefilesize__detailed_desc"></a>

SDK 默认的缓存文件总缓存上限为 1GB。你可以调用 [setMaxCacheFileSize](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_setmaxcachefilesize) 方法自定义总缓存大小的上限。

<a id="api_imediaplayercachemanager_getmaxcachefilesize__return_values"></a>

### 返回值 [#返回值-4]

- &gt; 0：方法调用成功，返回缓存文件的总缓存上限，单位为字节。
- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-4]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_removeallcaches"></a>

<a id="ariaid-title7"></a>

## removeAllCaches [#removeallcaches]

删除媒体播放器中所有已缓存的媒体文件。

<a id="api_imediaplayercachemanager_removeallcaches__prototype"></a>

```dart
Future<void> removeAllCaches();
```

<a id="api_imediaplayercachemanager_removeallcaches__detailed_desc"></a>

:::note
注： 该方法不会删除正在播放中的已缓存媒体文件。
:::

<a id="api_imediaplayercachemanager_removeallcaches__return_values"></a>

### 返回值 [#返回值-5]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-5]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_removecachebyuri"></a>

<a id="ariaid-title8"></a>

## removeCacheByUri [#removecachebyuri]

删除指定的已缓存媒体文件。

<a id="api_imediaplayercachemanager_removecachebyuri__prototype"></a>

```dart
uture<void> removeCacheByUri(String uri);
```

<a id="api_imediaplayercachemanager_removecachebyuri__detailed_desc"></a>

:::note
注： 该方法不会删除正在播放中的已缓存媒体文件。
:::

<a id="api_imediaplayercachemanager_removecachebyuri__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="uri"></a>
<Parameter name="uri">

待删除的缓存文件的 URI（Uniform Resource Identifier），可用于标识媒体文件。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_removecachebyuri__return_values"></a>

### 返回值 [#返回值-6]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-6]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_removeoldcache"></a>

<a id="ariaid-title9"></a>

## removeOldCache [#removeoldcache]

删除媒体播放器中近期最少使用的一个缓存媒体文件。

<a id="api_imediaplayercachemanager_removeoldcache__prototype"></a>

```dart
Future<void> removeOldCache();
```

<a id="api_imediaplayercachemanager_removeoldcache__detailed_desc"></a>

缓存媒体文件占用过多空间时，你可以调用该方法清理缓存文件。调用该方法后，SDK 会删除最少使用的一个缓存媒体文件。

:::note
注： 当你调用此方法删除缓存媒体文件时，当前正在播放的已缓存媒体文件不会被删除。
:::

<a id="api_imediaplayercachemanager_removeoldcache__return_values"></a>

### 返回值 [#返回值-7]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-7]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_setcachedir"></a>

<a id="ariaid-title10"></a>

## setCacheDir [#setcachedir]

设置待缓存的媒体文件的储存路径。

<a id="api_imediaplayercachemanager_setcachedir__prototype"></a>

```dart
Future<void> setCacheDir(String path);
```

<a id="api_imediaplayercachemanager_setcachedir__detailed_desc"></a>

:::note
注： 该方法需在初始化 [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine) 之后调用。
:::

<a id="api_imediaplayercachemanager_setcachedir__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="path"></a>
<Parameter name="path">

缓存文件储存的绝对路径。请确保指定的目录存在且可写。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_setcachedir__return_values"></a>

### 返回值 [#返回值-8]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-8]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_setmaxcachefilecount"></a>

<a id="ariaid-title11"></a>

## setMaxCacheFileCount [#setmaxcachefilecount]

设置缓存媒体文件数量的上限。

<a id="api_imediaplayercachemanager_setmaxcachefilecount__prototype"></a>

```dart
Future<void> setMaxCacheFileCount(int count);
```

<a id="api_imediaplayercachemanager_setmaxcachefilecount__detailed_desc"></a>

<a id="api_imediaplayercachemanager_setmaxcachefilecount__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="count"></a>
<Parameter name="count">

可缓存的媒体文件数量的上限，默认值为 1000。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_setmaxcachefilecount__return_values"></a>

### 返回值 [#返回值-9]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-9]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_setmaxcachefilesize"></a>

<a id="ariaid-title12"></a>

## setMaxCacheFileSize [#setmaxcachefilesize]

设置缓存媒体文件的总缓存大小的上限。

<a id="api_imediaplayercachemanager_setmaxcachefilesize__prototype"></a>

```dart
Future<void> setMaxCacheFileSize(int cacheSize);
```

<a id="api_imediaplayercachemanager_setmaxcachefilesize__detailed_desc"></a>

<a id="api_imediaplayercachemanager_setmaxcachefilesize__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="cachesize"></a>
<Parameter name="cacheSize">

缓存媒体文件的总缓存上限，单位为字节。默认为 1 GB。

</Parameter>
</ParameterList>

<a id="api_imediaplayercachemanager_setmaxcachefilesize__return_values"></a>

### 返回值 [#返回值-10]

方法成功调用时，无返回值；方法调用失败时，会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常，你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

- &lt; 0：方法调用失败，详见 [MediaPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-mediaplayerreason)。

### 所属接口类 [#所属接口类-10]

- [MediaPlayerCacheManager](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayercachemanager)

<a id="callback_imediaplayersourceobserver_onplayercachestats"></a>

<a id="ariaid-title13"></a>

## onPlayerCacheStats [#onplayercachestats]

报告当前缓存中的媒体资源的相关信息。

<a id="callback_imediaplayersourceobserver_onplayercachestats__prototype"></a>

```dart
final void Function(CacheStatistics stats)? onPlayerCacheStats;
```

<a id="callback_imediaplayersourceobserver_onplayercachestats__detailed_desc"></a>

调用 [openWithMediaSource](/zh-CN/api-reference/rtc/flutter/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法且设置 `enableCache` 成员为 true 后，SDK 会在媒体文件打开后每秒触发一次该回调，报告当前缓存的媒体文件的统计数据。

<a id="callback_imediaplayersourceobserver_onplayercachestats__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="stats"></a>
<Parameter name="stats">

缓存中的媒体资源的相关信息，详见 [CacheStatistics](/zh-CN/api-reference/rtc/flutter/class-cachestatistics)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-11]

- [MediaPlayerSourceObserver](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_imediaplayersourceobserver)