Metadata-Version: 2.1
Name: lebai_robot_voice_sdk
Version: 1.0.0
Summary: 乐白机器人语音播报SDK，提供播放、停止、音量等基础能力
Author-email: 张庆风 <aurora.xiaofeng@zohomail.cn>
License: MIT
Keywords: lebai,robot,voice,audio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: miniaudio>=1.61
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"

乐白机器人语音播报 Python SDK。提供播放、停止、设置音量和语速等基础能力，音频文件由调用方自行传入。

# 安装

```powershell
lpy -m pip install -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple lebai_robot_voice_sdk
```

```powershell
pip install -i https://mirrors.aliyun.com/pypi/simple lebai_robot_voice_sdk
```

## 更新 pip 包

```powershell
lpy -m pip install --upgrade -i https://mirrors.aliyun.com/pypi/simple lebai_robot_voice_sdk
```

要求 Python 3.7 及以上。默认语速播放只依赖 `miniaudio`；若需要调整语速（`rate != 1`），系统还需安装 [FFmpeg](https://ffmpeg.org/) 并将其加入 `PATH`。

# 快速上手

安装完成后，引入并初始化实例即可使用：

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError
import pathlib

audio_path = pathlib.Path("your_audio.mp3")
voice = LebaiRobotVoice()

try:
    # 按原始语速播放
    voice.play(audio_path)

    # 按 1.2 倍语速播放（需要系统已安装 FFmpeg）
    voice.play(audio_path, rate=1.2)

    # 设置音量（0-100）
    voice.set_volume(50)

    # 停止播放
    voice.stop()
except LebaiAudioError as e:
    print(f"语音播报错误: {e}")
```

播放是串行、阻塞的：`play()` 会等到当前音频播完才返回。

```python
voice.play(path)
print("播放完了")
```

上面两行只有等语音完全播放完毕，才会执行打印。可以据此做后续逻辑，例如播完后再 `time.sleep(3)`，或循环播放。

若当前已有音频在播，再次调用 `play()` 会直接返回，不会打断、也不会排队。需要换一条语音时，先 `stop()` 再 `play()`。

# 方法

实例化 `voice = LebaiRobotVoice()` 后即可调用以下方法。

## play

播放本地音频文件（推荐 mp3）。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| file_path | 已存在的音频文件路径 | str / Path | 必填 |
| rate | 语速，范围 0.5～1.5。`1` 为原始语速，不调用 FFmpeg；其它值需要系统已安装 FFmpeg | float | `1` |

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError
import pathlib

voice_path = pathlib.Path(__file__).parent / "assets" / "test.mp3"

if __name__ == "__main__":
    try:
        voice = LebaiRobotVoice()
        voice.play(voice_path)              # 原始语速
        voice.play(voice_path, rate=0.8)    # 慢放
        voice.play(voice_path, rate=1.5)    # 快放
    except LebaiAudioError as e:
        print(f"Error: {e}")
```

## set_volume

设置播放音量。内部通过 `amixer` 调整系统 Playback 音量，适用于机器人 Linux 环境。

| 参数 | 说明 | 类型 |
| --- | --- | --- |
| volume | 0～100 的整数 | int |

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    voice.set_volume(50)
except LebaiAudioError as e:
    print(f"Error: {e}")
```

## get_audio_duration

获取音频文件时长（秒）。

| 参数 | 说明 | 类型 |
| --- | --- | --- |
| file_path | 已存在的音频文件路径 | str / Path |

返回值：`float`，单位为秒。

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    duration = voice.get_audio_duration(path)
    print(duration)
except LebaiAudioError as e:
    print(f"Error: {e}")
```

## stop

停止当前播放。

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    voice.stop()
except LebaiAudioError as e:
    print(f"Error: {e}")
```

## close_audio_device

关闭音频设备。一般在程序退出或调度结束时调用。

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    voice.close_audio_device()
except LebaiAudioError as e:
    print(f"Error: {e}")
```

# 属性

## playing

当前是否正在播放。`True` 表示正在播报，`False` 表示空闲。

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    print(voice.playing)
except LebaiAudioError as e:
    print(f"Error: {e}")
```

# 异常处理

SDK 相关错误都会以 `LebaiAudioError` 抛出，用 `try/except` 捕获即可打日志。

```python
from lebai_robot_voice_sdk import LebaiRobotVoice, LebaiAudioError

try:
    voice = LebaiRobotVoice()
    voice.play(audio_path, rate=1.2)
except LebaiAudioError as e:
    logger.error(e)
    print(f"lebai_robot_voice_sdk 相关错误: {e}")
```

常见情况包括：音频设备不可用、音量或语速超出范围、音频文件无法读取、未安装 FFmpeg 却使用了非 1 的语速。
