---
sidebarDepth: 1
---
# 音效

# 索引

---

| 接口 | <div style="width: 3em"></div> | 描述 |
| --- | --- | --- |
| [DisableOriginMusic](音效.md#disableoriginmusic) | <span style="display:inline;color:#7575f9">客户端</span> | 停止原生背景音乐 |
| [PlayCustomMusic](音效.md#playcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 播放场景音效，包括原版音效及自定义音效 |
| [PlayGlobalCustomMusic](音效.md#playglobalcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 播放背景音乐 |
| [SetCustomMusicLoop](音效.md#setcustommusicloop) | <span style="display:inline;color:#7575f9">客户端</span> | 设定指定音乐是否循环播放，包括场景音效与背景音乐 |
| [SetCustomMusicLoopById](音效.md#setcustommusicloopbyid) | <span style="display:inline;color:#7575f9">客户端</span> | 设定指定音乐是否循环播放 |
| [StopCustomMusic](音效.md#stopcustommusic) | <span style="display:inline;color:#7575f9">客户端</span> | 停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件 |
| [StopCustomMusicById](音效.md#stopcustommusicbyid) | <span style="display:inline;color:#7575f9">客户端</span> | 停止场景音效 |

## DisableOriginMusic

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    停止原生背景音乐

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | disable | bool | True表示停止，False表示恢复 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 设置是否成功 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.DisableOriginMusic(True)
```



## PlayCustomMusic

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    播放场景音效，包括原版音效及自定义音效

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | name | str | 音效名称 |
    | pos | tuple(float,float,float) | 播放位置 |
    | volume | float | 音量倍率，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小 |
    | pitch | float | 播放速度，范围0-256，1表示原速，可以从json文件里进行修改 |
    | loop | bool | 是否循环播放 |
    | entityId | str | 绑定的实体id，默认为None，若有绑定的实体，则pos参数为相对于实体的坐标 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | str | 音乐播放id，可用于控制音乐的停止和循环 |

- 备注
    - 当播放音乐错误时，将返回相应的错误id
        | 错误 | 错误描述 |
        | -- | -- |
        | -1   | 无法在服务端播放音效  |
        | -2   | 播放位置错误               |
        | -3   | 已有同名背景音乐正在播放    |
        | -4   | 播放失败                   |
        | -5   | 绑定实体不存在             |
        | -6   | **位置距离本地玩家距离大于16格，跳过音效播放**（绑定实体的音效不受此限制）  |
    - 当背景音乐在播放的时候，请不要播放同名的场景音效
    - 针对比较大的音乐，请将load_on_low_memory和stream设为true
    - 该接口触发[PlaySoundClientEvent](../事件/音效.md#playsoundclientevent)
    - 与示例对应的sound_definitions.json配置：
        ```json
        {
          "sound001": {
            "min_distance": 0,
            "max_distance": 20.0,
            "sounds": [
              {
                "name": "sounds/testaudio/largeBlast1",
                "load_on_low_memory": true,
                "stream": true,
                "pitch": 1,
                "volume": 1
              }
            ]
          }
        }
        ```

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
musicId = comp.PlayCustomMusic("music.global0", (1,1,1), 1, 1, False, None)
```



## PlayGlobalCustomMusic

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    播放背景音乐

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | name | str | 音乐名称 |
    | volume | float | 音量大小，范围0-1，与json中的volume乘算后为游戏中实际播放的音量大小 |
    | loop | bool | 是否循环播放 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 播放是否成功 |

- 备注
    - 背景音乐同时仅能播放一个，当播放背景音乐时，会停止掉当前播放的音乐。这个规则也包括原版的背景音乐，所以为了避免原版背景音乐覆盖掉自定义背景音乐，建议先使用DisableOriginMusic屏蔽原版背景音乐。
    - 背景音乐的优先级大于场景音效，当背景音乐在播放时，会让同名场景音效播放失败
    - 背景音乐的播放速度需要从配置json里进行修改
    - 针对比较大的背景音乐，请将load_on_low_memory和stream设为true
    - 背景音乐需要在json里定义category为music
    - 该接口触发[PlayMusicClientEvent](../事件/音效.md#playmusicclientevent)
    - 与示例对应的sound_definitions.json配置：
        ```json
        {
          "Gsound001": {
            "category": "music",
            "sounds": [
              {
                "name": "sounds/testaudio/Music001",
                "load_on_low_memory": true,
                "stream": true,
                "pitch": 1,
                "volume": 1
              }
            ]
          }
        }
        ```

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.PlayGlobalCustomMusic("Gsound001", 1, False)
```



## SetCustomMusicLoop

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    设定指定音乐是否循环播放，包括场景音效与背景音乐

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | name | str | 音乐名称 |
    | loop | bool | True则循环播放，False则停止循环，停止会持续到播放到本次结束 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 停止是否成功 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.SetCustomMusicLoop("soundName", True)
```



## SetCustomMusicLoopById

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    设定指定音乐是否循环播放

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | musicId | str | 音乐id，播放指定音乐获取的音乐id |
    | loop | bool | True则循环播放，False则停止循环，停止会持续到播放到本次结束 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 停止是否成功 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
musicId = comp.PlayCustomMusic("sound001", (1,1,1), 1, 1, False, False)
comp.SetCustomMusicLoopById(musicId, True)
```



## StopCustomMusic

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    停止音效，包括场景音效与背景音乐，将依据fadeOutTime触发OnMusicStopClientEvent事件

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | name | str | 音乐名称 |
    | fadeOutTime | float | 停止的淡出时间，单位为秒，如果剩余时间小于淡出时间，将以剩余时间为准 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 停止是否成功 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
comp.StopCustomMusic("music.global0", 0)
```



## StopCustomMusicById

<span style="display:inline;color:#7575f9">客户端</span>

method in mod.client.component.audioCustomCompClient.AudioCustomComponentClient

- 描述

    停止场景音效

- 参数

    | 参数名 | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- | :--- |
    | musicId | str | 音乐id，播放指定音乐获取的音乐id |
    | fadeOutTime | float | 停止的淡出时间，单位为秒 |

- 返回值

    | <div style="width: 4em">数据类型</div> | 说明 |
    | :--- | :--- |
    | bool | 停止是否成功 |

- 示例

```python
import mod.client.extraClientApi as clientApi
comp = clientApi.GetEngineCompFactory().CreateCustomAudio(levelId)
musicId = comp.PlayCustomMusic("sound001", (1,1,1), 1, 1, False, False)
comp.StopCustomMusicById(musicId, 0)
```