> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 qrb_ros_audio_service 启用核心音频

`qrb_ros_audio_service` 示例应用是一个提供核心音频功能的 ROS 软件包，作为 ROS 生态系统中音频能力（当前支持播放和录音）的主要接口。

<Note>
  **注意**

  更多信息请参阅 [qrb\_ros\_audio\_service](https://github.com/qualcomm-qrb-ros/qrb_ros_audio_service) GitHub 仓库。
</Note>

## `qrb_ros_audio_service` **的管线**

下图显示了该管线。

**图：** `qrb_ros_audio_service `**管线**

## `qrb_ros_audio_service `**管线中使用的 ROS 节点/服务**

|    **ROS 节点**    |                            **说明**                           |
| :--------------: | :---------------------------------------------------------: |
| `/audio_service` | 该节点是 `qrb_ros_audio_service` 的主要入口点，通过 ROS 服务请求提供音频播放和录音功能。 |

|    **ROS 服务**   |                      **类型**                     |          **说明**          |
| :-------------: | :---------------------------------------------: | :----------------------: |
| `/audio_server` | `qrb_ros_audio_service_msgs::srv::AudioRequest` | 允许 ROS 应用发送音频播放和录音的服务请求。 |

## `qrb_ros_audio_service `**管线中使用的 ROS 话题**

|    **ROS 话题**    |                    **类型**                   |                                            **说明**                                            |
| :--------------: | :-----------------------------------------: | :------------------------------------------------------------------------------------------: |
| `/qrb_audiodata` | `qrb_ros_audio_common_msgs::msg::AudioData` | 用于流式音频播放和录音。发布录制的实时原始音频数据，或允许订阅此节点的原始数据进行播放。您可以使用 `--topic_name` 参数修改话题名称。支持为播放和录音操作使用不同的话题。 |

## **前提条件**

您已根据[为运行示例应用设置环境](./set-up-env-for-sample-app)完成了**设置设备**。

## **运行开箱即用的** `qrb_ros_audio_service`

1. 在设备上启动三个命令行终端，并运行以下命令设置环境。
   ```python theme={null}
   ssh root@[ip-addr]
   (ssh) export HOME=/home
   (ssh) source /usr/share/qirp-setup.sh
   ```
2. 在第一个 SSH 终端中，使用 `ros2 launch` 命令运行音频服务软件包。
   ```undefined theme={null}
   ros2 launch qrb_ros_audio_service audio_service.launch.py
   ```
3. 在第二个 SSH 终端中，运行 `qrb_ros_audio_common`。
   ```undefined theme={null}
   ros2 launch qrb_ros_audio_common component.launch.py
   ```
4. 检查 pipewire 的默认设备。
   1. 验证默认扬声器和听筒麦克风的状态。
      ```undefined theme={null}
      wpctl status
      ```
      ```undefined theme={null}
      Audio
       ├─ Devices:
       │
       ├─ Sinks:
       │      * 42. pal sink speaker ll         [vol: 1.00]
       │        44. pal sink speaker_db         [vol: 1.00]
       │        46. pal sink headset_ll         [vol: 1.00]
       │        47. pal sink headset_db         [vol: 1.00]
       ├─ Sources:
       │      * 48. pal source handset mic      [vol: 1.00]
       │        50. pal source headset mic      [vol: 1.00]
      ```
   2. 如果未设置默认扬声器或听筒麦克风，请使用 `wpctl set-default <device-num>` 设置默认设备。
      ```python theme={null}
      # Set the default speaker
      wpctl set-default 42
      # Set the default handset mic
      wpctl set-default 48
      ```
5. 在第三个 SSH 终端中，根据下表使用 ROS 命令或 Python 脚本运行测试用例。
   <Note>
     1. **注意** 对于所有分步测试用例，`stream_handle` 表示当命令为 `create` 时音频服务创建的流。音频服务创建流后，命令会在第三个 SSH 终端中打印 `stream_handle` 的值。
        * 对于 ROS 命令，您会看到以下输出：
          > `stream_handle=<***>`
        * 对于 Python 脚本，您会看到以下输出：`command create success 1 stream_handle <***>.` 使用以下命令下载 Python 脚本
          ```cpp theme={null}
          wget https://raw.githubusercontent.com/qualcomm-qrb-ros/qrb_ros_audio_service/main/tests/audio_service_test.py
          ```
   </Note>

<table>
  <caption>表：音频服务命令</caption>

  <thead>
    <tr>
      <th style={{ width: '16.7%' }}>用例名称</th>
      <th style={{ width: '16.7%' }}>说明</th>
      <th style={{ width: '66.7%' }}>ROS 命令/Python 脚本</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>一键播放</td>
      <td>使用一键命令开始播放。扬声器输出音频。支持 WAV 文件格式。将音乐文件放置在设备路径下，例如 `/tmp/music.wav`。</td>

      <td>
        <Tabs>
          <Tab title="ROS 命令">
            ```powershell theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "play",
            source: "/tmp/music.wav",
            volume: 100,
            }"
            ```
          </Tab>

          <Tab title="Python 脚本">
            ```python theme={null}
            python3 audio_service_test.py --mode one-touch --type playback --source /tmp/music.wav --volume 100
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>分步播放</td>
      <td>使用分步命令开始播放。扬声器输出音频。支持 WAV 文件格式。</td>

      <td>
        <Tabs>
          <Tab title="ROS 命令">
            ```powershell theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            type: "playback",
            command: "create",
            source: "/tmp/music.wav",
            volume: 100,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "start",
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "mute",
            mute: true,
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "mute",
            mute: false,
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "stop",
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "release",
            stream_handle: <stream_handle>,
            }"
            ```
          </Tab>

          <Tab title="Python 脚本">
            ```python theme={null}
            # Create and start the stream (step-by-step mode automatically starts after create)
            python3 audio_service_test.py --mode step-by-step --type playback --source /tmp/music.wav --volume 100

            # In another terminal, mute the stream using the printed stream_handle
            python3 audio_service_test.py --set-mute --stream_handle <stream_handle> --mute true

            # Unmute the stream
            python3 audio_service_test.py --set-mute --stream_handle <stream_handle> --mute false

            # Press Ctrl+C in the first terminal to stop and release the stream
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>流式播放</td>
      <td>创建并启动流式播放。它从 `loopback` 话题订阅音频 PCM 数据。音频数据应使用 `qrb_ros_audio_common_msgs::msg::AudioData` 填充。</td>

      <td>
        <Tabs>
          <Tab title="ROS 命令">
            启动分步流式播放：

            ```css theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            audio_info: {
            channels: 1,
            sample_rate: 16000,
            sample_format: 16,
            },
            type: "playback",
            command: "create",
            volume: 100,
            topic_name: "loopback",
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "start",
            stream_handle: <stream_handle>,
            }"
            ```

            启动一键流式播放：

            ```css theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            audio_info: {
            channels: 1,
            sample_rate: 16000,
            sample_format: 16,
            },
            command: "play",
            volume: 100,
            topic_name: "loopback",
            }"
            ```
          </Tab>

          <Tab title="Python 脚本">
            启动分步流式播放：

            ```python theme={null}
            python3 audio_service_test.py --mode step-by-step --type playback --channels 1 --sample_rate 16000 --sample_format 16 --volume 100 --topic_name loopback
            ```

            启动一键流式播放：

            ```python theme={null}
            python3 audio_service_test.py --mode one-touch --type playback --channels 1 --sample_rate 16000 --sample_format 16 --volume 100 --topic_name loopback
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>分步录音</td>
      <td>使用分步命令通过默认输入设备录音，并将音频数据写入 `/tmp/rec.wav` 文件。</td>

      <td>
        <Tabs>
          <Tab title="ROS 命令">
            ```css theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            audio_info: {
            channels: 1,
            sample_rate: 16000,
            sample_format: 16,
            },
            type: "record",
            command: "create",
            source: "/tmp/rec.wav",
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "start",
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "stop",
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "release",
            stream_handle: <stream_handle>,
            }"
            ```
          </Tab>

          <Tab title="Python 脚本">
            ```python theme={null}
            # Create and start the recording stream (step-by-step mode automatically starts after create)
            python3 audio_service_test.py --mode step-by-step --type record --channels 1 --sample_rate 16000 --sample_format 16 --source /tmp/rec.wav

            # Press Ctrl+C to stop and release the stream
            ```
          </Tab>
        </Tabs>
      </td>
    </tr>

    <tr>
      <td>发布录音数据</td>

      <td>
        * 将录音数据发布到某个话题（默认话题名称：`qrb_audiodata`。您可以使用 `topic_name` 指定其他名称）。
        * 音频数据将使用 `qrb_ros_audio_common_msgs::msg::AudioData` 填充。
      </td>

      <td>
        <Tabs>
          <Tab title="ROS 命令">
            将录音数据发布到某个话题（默认话题名称为"`qrb_audiodata`"，但可以使用 `topic_name` 指定）：

            ```css theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            audio_info: {
            channels: 1,
            sample_rate: 16000,
            sample_format: 16,
            },
            type: "record",
            command: "create",
            pub_pcm: true,
            topic_name: "loopback",
            }"
            ```

            或者，将录音数据发布到 `/qrb_audiodata`，同时保存到文件：

            ```css theme={null}
            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            audio_info: {
            channels: 1,
            sample_rate: 16000,
            sample_format: 16,
            },
            type: "record",
            command: "create",
            pub_pcm: true,
            source: "/tmp/rec.wav",
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{command: "start",
            stream_handle: <stream_handle>,
            }"

            ros2 topic echo /qrb_audiodata

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "stop",
            stream_handle: <stream_handle>,
            }"

            ros2 service call /audio_server qrb_ros_audio_service_msgs/srv/AudioRequest "{
            command: "release",
            stream_handle: <stream_handle>,
            }"
            ```
          </Tab>

          <Tab title="Python 脚本">
            将录音数据发布到某个话题（默认话题名称为"`qrb_audiodata`"，但可以使用 `--topic_name` 指定）：

            ```python theme={null}
            python3 audio_service_test.py --mode step-by-step --type record --channels 1 --sample_rate 16000 --sample_format 16 --pub_pcm true --topic_name loopback
            ```

            或者，将录音数据发布到 `/qrb_audiodata`，同时保存到文件：

            ```python theme={null}
            python3 audio_service_test.py --mode step-by-step --type record --channels 1 --sample_rate 16000 --sample_format 16 --pub_pcm true --source /tmp/rec.wav
            ```

            在另一个终端中，回显该话题：

            ```python theme={null}
            ros2 topic echo /qrb_audiodata
            ```

            在第一个终端中按 Ctrl+C 停止并释放流。
          </Tab>
        </Tabs>
      </td>
    </tr>
  </tbody>
</table>