> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.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` 流水线

<img
  src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-staging/zh/SDKs/QIR-SDK-2.0/media/80-65220-2-qirp-sdk-qsg/qrb_ros_audio_service_pipeline-regenerate.svg"
  style={{
width: "70%",
display: "block",
margin: "0 auto" }}
/>

<p style={{ textAlign: 'center', fontWeight: 'bold' }}>
  图：qrb\_ros\_audio\_service 流水线
</p>

## `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 topic

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

## 前提条件

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

## 开箱即用运行 `qrb_ros_audio_service`

<Accordion title="试一试">
  <Steps>
    <Step title="设置环境">
      在设备上启动三个命令行终端并运行以下命令。

      ```bash theme={null}
      ssh root@[ip-addr]
      ```

      ```bash title="SSH Session" theme={null}
      export HOME=/home
      source /usr/share/qirp-setup.sh
      ```
    </Step>

    <Step title="运行 audio 服务">
      在第一个 SSH 终端中，使用 `ros2 launch` 命令运行 audio 服务包。

      ```bash title="SSH Session" theme={null}
      ros2 launch qrb_ros_audio_service audio_service.launch.py
      ```
    </Step>

    <Step title="检查 pipewire 的默认设备">
      1. 验证默认扬声器和听筒麦克风的状态。
         ```bash title="SSH Session" theme={null}
         wpctl status
         ```
         ```text 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>` 设置默认设备。
         ```bash title="SSH Session" theme={null}
         # Set the default speaker
         wpctl set-default 42
         # Set the default handset mic
         wpctl set-default 48
         ```
    </Step>

    <Step title="运行测试用例">
      在第三个 SSH 终端中，根据下表使用 ROS 命令或 Python 脚本运行测试用例。

      <Note>
        **注意**

        对于所有分步测试用例，`stream_handle` 表示当命令为 `create` 时由 audio 服务创建的流。

        audio 服务创建流后，命令在第三个 SSH 终端中打印 `stream_handle` 的值。

        * 对于 ROS 命令，你会看到以下输出：
          > `stream_handle=<***>`
        * 对于 Python 脚本，你会看到以下输出：`command create success 1 stream_handle <***>.` 使用以下命令下载 Python 脚本：
          ```bash 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 命令">
                  ```bash 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 命令">
                  ```bash 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` topic 订阅音频 PCM 数据。音频数据应使用 `qrb_ros_audio_service_msgs::msg::AudioData` 填充。</td>

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

                  ```bash 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>,
                  }"
                  ```

                  启动一键流式播放：

                  ```bash 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 命令">
                  ```bash 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>
              * 将录制数据发布到 topic（默认 topic 名称：`qrb_audiodata`。你可以使用 `topic_name` 指定另一个名称）。
              * 音频数据将使用 `qrb_ros_audio_service_msgs::msg::AudioData` 填充。
            </td>

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

                  ```bash 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`。同时将其保存到文件：

                  ```bash 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 脚本">
                  将录制数据发布到 topic（默认 topic 名称是 "`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
                  ```

                  在另一个终端中，echo 该 topic：

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

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