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

# Enable core audio with qrb_ros_audio_service

The `qrb_ros_audio_service` sample application is a ROS package that delivers core audio functionalities, serving as the primary interface for audio capabilities (currently supporting playback and recording) within the ROS ecosystem.

<Note>
  **Note**

  For more information, see the [qrb\_ros\_audio\_service](https://github.com/qualcomm-qrb-ros/qrb_ros_audio_service) GitHub repo.
</Note>

## **Pipeline for** `qrb_ros_audio_service`

The following figure shows the pipeline.

**Figure :** `qrb_ros_audio_service `**pipeline**

## **ROS nodes/services used in the** `qrb_ros_audio_service `**pipeline**

|   **ROS node**   |                                                                          **Description**                                                                         |
| :--------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `/audio_service` | This node functions as the primary entry point for the `qrb_ros_audio_service`, offering audio playback and recording capabilities through ROS service requests. |

| **ROS service** |                     **Type**                    |                                   **Description**                                  |
| :-------------: | :---------------------------------------------: | :--------------------------------------------------------------------------------: |
| `/audio_server` | `qrb_ros_audio_service_msgs::srv::AudioRequest` | Allows ROS applications to send service requests for audio playback and recording. |

## **ROS topics used in the** `qrb_ros_audio_service `**pipeline**

|   **ROS topic**  |                   **Type**                  |                                                                                                                                             **Description**                                                                                                                                            |
| :--------------: | :-----------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `/qrb_audiodata` | `qrb_ros_audio_common_msgs::msg::AudioData` | Used for streaming audio playback and recording. Publishes the recorded real-time raw audio data, or allows subscription to this node's raw data for playback. You can modify the topic name using the `--topic_name` parameter. Supports using separate topics for playback and recording operations. |

## **Prerequisites**

You have **Set up the device** according to [Set up the environment for running sample applications](./set-up-env-for-sample-app).

## **Run out-of-the-box** `qrb_ros_audio_service`

1. Start three commandline terminals on your device and run the following commands to set up the environment.
   ```python theme={null}
   ssh root@[ip-addr]
   (ssh) export HOME=/home
   (ssh) source /usr/share/qirp-setup.sh
   ```
2. In the first SSH terminal, run the audio service package using the `ros2 launch` command.
   ```undefined theme={null}
   ros2 launch qrb_ros_audio_service audio_service.launch.py
   ```
3. In the second SSH terminal, run `qrb_ros_audio_common`.
   ```undefined theme={null}
   ros2 launch qrb_ros_audio_common component.launch.py
   ```
4. Check the default devices for the pipewire.
   1. Verify the status of default speaker and handset mic.
      ```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. If the default speaker or handset mic isn't set, use `wpctl set-default <device-num>` to set the default device(s).
      ```python theme={null}
      # Set the default speaker
      wpctl set-default 42
      # Set the default handset mic
      wpctl set-default 48
      ```
5. In the third SSH terminal, run the test cases using either ROS commands or Python scripts according to the following table.
   <Note>
     1. **Note** For all step-by-step test cases, `stream_handle` indicates the stream created by the audio service when the command is `create`. After the audio service creates a stream, the command prints the value of `stream_handle` in the third SSH terminal.
        * For the ROS command, you see the following output:
          > `stream_handle=<***>`
        * For the Python script, you see the following output: `command create success 1 stream_handle <***>.` Download the Python script using
          ```cpp theme={null}
          wget https://raw.githubusercontent.com/qualcomm-qrb-ros/qrb_ros_audio_service/main/tests/audio_service_test.py
          ```
   </Note>

<table>
  <caption>Table: Audio service commands</caption>

  <thead>
    <tr>
      <th style={{ width: '16.7%' }}>Case name</th>
      <th style={{ width: '16.7%' }}>Description</th>
      <th style={{ width: '66.7%' }}>ROS command/Python script</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>One-touch playback</td>
      <td>Start playback with a one-touch command. The speaker outputs the audio. Supports the WAV file format. Place the music file on a device path, for example, `/tmp/music.wav`.</td>

      <td>
        <Tabs>
          <Tab title="ROS command">
            ```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 script">
            ```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>Step-by-step playback</td>
      <td>Start playback with step-by-step commands. The speaker outputs the audio. Supports the WAV file format.</td>

      <td>
        <Tabs>
          <Tab title="ROS command">
            ```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 script">
            ```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>Streaming playback</td>
      <td>Create and start a streaming playback. It subscribes to the audio PCM data from the `loopback` topic. Audio data should be filled with `qrb_ros_audio_common_msgs::msg::AudioData`.</td>

      <td>
        <Tabs>
          <Tab title="ROS command">
            Start a step-by-step streaming playback:

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

            Start a one-touch streaming playback:

            ```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 script">
            Start a step-by-step streaming playback:

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

            Start a one-touch streaming playback:

            ```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>Step-by-step record</td>
      <td>Use the default input device to record with step-by-step commands and write the audio data to the `/tmp/rec.wav` file.</td>

      <td>
        <Tabs>
          <Tab title="ROS command">
            ```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 script">
            ```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>Publish recording data</td>

      <td>
        * Publish the recording data to a topic (default topic name: `qrb_audiodata`. You can specify another name using `topic_name`).
        * The audio data will be filled with `qrb_ros_audio_common_msgs::msg::AudioData`.
      </td>

      <td>
        <Tabs>
          <Tab title="ROS command">
            Publish the recording data to a topic (default topic name is "`qrb_audiodata`", but it can be specified using `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",
            }"
            ```

            Or, publish the recording data to `/qrb_audiodata`. Meanwhile, save it to a file:

            ```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 script">
            Publish the recording data to a topic (default topic name is "`qrb_audiodata`", but it can be specified using `--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
            ```

            Or, publish the recording data to `/qrb_audiodata`. Meanwhile, save it to a file:

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

            In another terminal, echo the topic:

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

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