# 媒体播放器缓存 (/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)enableAutoRemoveCache:(BOOL)enable NS_SWIFT_NAME(enableAutoRemoveCache(_:));
```

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

当缓存的媒体文件超过设置的数量或大小限制时，如果启用该功能，SDK 会自动删除最近最少使用的缓存文件。

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

### 参数 [#参数]

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

是否启用 SDK 自动删除缓存的媒体文件：

- YES：自动删除缓存的媒体文件。
- NO：（默认）不自动删除缓存的媒体文件。

</Parameter>
</ParameterList>

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

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

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

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

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

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

## cacheDir [#cachedir]

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

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

```objc
- (NSString *)cacheDir NS_SWIFT_NAME(cacheDir());
```

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

如果在调用该方法前未调用 [setCacheDir:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_setcachedir) 方法设置缓存媒体文件的存储路径，则该方法返回 SDK 默认使用的存储路径。

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

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

- 方法调用成功时，返回缓存媒体文件的存储路径。
- 方法调用失败，返回 nil，详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

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

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

## cacheFileCount [#cachefilecount]

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

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

```objc
- (NSInteger)cacheFileCount NS_SWIFT_NAME(cacheFileCount());
```

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

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

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

- 方法调用成功，返回已缓存的媒体文件数量。
- 方法调用失败，返回小于 0 的错误码，详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

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

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

## maxCacheFileCount [#maxcachefilecount]

获取可缓存的媒体文件的最大数量。

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

```objc
- (NSInteger)maxCacheFileCount NS_SWIFT_NAME(maxCacheFileCount());
```

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

默认情况下，最多可以缓存 1,000 个媒体文件。

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

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

方法调用成功，返回可缓存的媒体文件的最大数量。

- &lt; 0：方法调用失败，返回错误码，详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

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

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

## maxCacheFileSize [#maxcachefilesize]

获取缓存媒体文件的聚合存储空间的最大大小。

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

```objc
- (NSInteger)maxCacheFileSize NS_SWIFT_NAME(maxCacheFileSize());
```

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

你可以调用 [setMaxCacheFileSize:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_setmaxcachefilesize) 方法根据你的使用场景设置该限制。默认情况下，缓存媒体文件的聚合存储空间的最大大小为 1 GB。

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

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

- 方法调用成功，返回缓存媒体文件的聚合存储空间的最大大小（单位为字节）。
- 方法调用失败，返回小于 0 的错误码，详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)removeAllCaches NS_SWIFT_NAME(removeAllCaches());
```

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

:::note
注： [removeAllCaches](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_removeallcaches) 不会删除当前正在播放的缓存媒体文件。
:::

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

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

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

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)removeCacheByUri:(NSString *)uri NS_SWIFT_NAME(removeCache(byUri:));
```

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

:::note
注： [removeCacheByUri:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_removecachebyuri) 当前正在播放的缓存媒体文件不会被删除。
:::

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

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

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

要删除的媒体文件的 URI（统一资源标识符）。

</Parameter>
</ParameterList>

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

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

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

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)removeOldCache NS_SWIFT_NAME(removeOldCache());
```

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

当缓存文件的存储空间即将达到上限时，你可以调用该方法删除一个缓存媒体文件。SDK 会删除最少使用的缓存媒体文件。

:::note
注： [removeOldCache](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-cache#api_imediaplayercachemanager_removeoldcache) 当前不会删除正在播放的缓存媒体文件。
:::

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

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

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

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)setCacheDir:(NSString *)cacheDir NS_SWIFT_NAME(setCacheDir(_:));
```

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

:::note
注： 请确保在调用该方法前已初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)。
:::

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

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

<ParameterList>
<a id="cachedir"></a>
<Parameter name="cacheDir">

要缓存的媒体文件的绝对路径。确保该目录存在且可写。

</Parameter>
</ParameterList>

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

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

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)setMaxCacheFileCount:(NSInteger)count NS_SWIFT_NAME(setMaxCacheFileCount(_:));
```

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

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

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

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

可缓存的媒体文件数量上限（默认值为 1,000）。

</Parameter>
</ParameterList>

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

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

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见 [AgoraMediaPlayerReason](/zh-CN/api-reference/rtc/macos/enum-mediaplayerreason)。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/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>

```objc
- (int)setMaxCacheFileSize:(NSInteger)cacheSize NS_SWIFT_NAME(setMaxCacheFileSize(_:));
```

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

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

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

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

缓存媒体文件的聚合存储空间的最大大小（字节）（默认值为 1 GB）。

</Parameter>
</ParameterList>

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

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

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

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

<a id="api_imediaplayercachemanager_sharedinstance"></a>

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

## sharedInstance [#sharedinstance]

获取 [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager) 实例。

<a id="api_imediaplayercachemanager_sharedinstance__prototype"></a>

```objc
+ (instancetype)sharedInstance NS_SWIFT_NAME(sharedInstance());
```

<a id="api_imediaplayercachemanager_sharedinstance__detailed_desc"></a>

<a id="api_imediaplayercachemanager_sharedinstance__return_values"></a>

### 返回值 [#返回值-11]

方法调用成功，返回 [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager) 实例。

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

- [AgoraRtcMediaPlayerCacheManagerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayercachemanager)

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

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

## AgoraRtcMediaPlayer\:cacheStats: [#agorartcmediaplayercachestats]

上报正在缓存的媒体文件的统计信息。

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

```objc
- (void)AgoraRtcMediaPlayer:(id<AgoraRtcMediaPlayerProtocol> _Nonnull)playerKit cacheStats:(AgoraMediaPlayerCacheStatistics *_Nonnull)info NS_SWIFT_NAME(AgoraRtcMediaPlayer(_:cacheStats:));
```

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

<a id="callback_imediaplayersourceobserver_onplayercachestats__timing"></a>

### 触发时机 [#触发时机]

该回调在你调用 [openWithMediaSource:](/zh-CN/api-reference/rtc/macos/play/mediaplayer/mediaplayer-open#api_imediaplayer_openwithmediasource) 方法并将 `enableCache` 设置为 YES 后，每秒触发一次。

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

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

<ParameterList>
<a id="playerkit"></a>
<Parameter name="playerKit">

[AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer) 实例。详见 [AgoraRtcMediaPlayerProtocol](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayer)。

</Parameter>
<a id="info"></a>
<Parameter name="info">

正在缓存的媒体文件的统计信息。详见 [AgoraMediaPlayerCacheStatistics](/zh-CN/api-reference/rtc/macos/class-cachestatistics)。

</Parameter>
</ParameterList>

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

- [AgoraRtcMediaPlayerDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_imediaplayersourceobserver)