# Survey audio

The **survey audio** experiment presents raters with individual audio stimuli and asks them to
answer custom survey questions about each one. Unlike [ACR audio](/experiments/audio/acr_audio/)
where raters select a score from a fixed category scale, the survey experiment supports open-ended
text responses, single-choice (radio), and multiple-choice (checkbox) questions.

This is useful when you need qualitative feedback or structured responses that go beyond a simple
quality rating, such as asking raters to describe what they hear, identify specific artifacts, or
classify the type of audio content.

Survey audio interface
## Survey questions

You can configure up to 10 survey questions per experiment. Each question requires a **kind**
(the question type), a **question** (the prompt), and a **dimension** (a short label used to
identify the question in the results).

Three question types are supported:

| Kind | Description |
|  --- | --- |
| `textarea` | An open-ended text response field. |
| `radio` | A single-choice question where the rater selects one option. |
| `checkbox` | A multiple-choice question where the rater selects one or more options. |


For `radio` and `checkbox` questions, you must also provide a list of **choices**. For `checkbox`
questions, you can optionally set `minSelect` and `maxSelect` to constrain the number of
selections.

## Options

### Hidden reference

When enabled, a hidden reference is included among the stimuli that raters evaluate.

### Show reference

When enabled, an explicitly labeled reference audio sample is shown alongside the stimulus.

### Waveform

This option controls how the waveform is rendered. Setting it to **stimulus** renders a waveform
based on each audio sample. Setting it to **reference** uses the waveform of the reference for all
audio samples.

### Minimum play duration

This option controls the minimum duration (in milliseconds) for which the audio must be played
before raters can submit their response.

## Configuration via API

Below is an example configuration to get you started when using our [API](/api/openapi/experiments/experiments_create) to create a survey
audio experiment.


```python
config = {
    "surveyAudio": {
        "survey": [
            {
                "kind": "textarea",
                "dimension": "Overall",
                "question": "How do you feel about the audio quality?",
            },
            {
                "kind": "radio",
                "dimension": "Content type",
                "question": "What type of audio is this?",
                "choices": [
                    {"label": "Speech"},
                    {"label": "Music"},
                    {"label": "Environmental sound"},
                    {"label": "Other"},
                ],
            },
            {
                "kind": "checkbox",
                "dimension": "Artifacts",
                "question": "Which artifacts do you notice? (Select all that apply)",
                "choices": [
                    {"label": "Background noise"},
                    {"label": "Clipping"},
                    {"label": "Muffled sound"},
                    {"label": "Echo"},
                    {"label": "None"},
                ],
                "minSelect": 1,
            },
        ],
        "hiddenReference": True,
        "showWaveform": "stimulus",
        "minPlayDuration": 1000,
    },
}
```