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

# Play Audio & Stop Audio

> Control audio playback in your training

## Overview

The **Play Audio** and **Stop Audio** actions manage audio playback. Use Play Audio to trigger narration, sound effects, or ambient audio. Use Stop Audio to silence audio clips or stop looping sounds.

Multiple audio clips can play simultaneously, allowing you to layer narration over ambient sound or play multiple sound effects at once.

## Play Audio

### When to Use

* **Narration**: voice-over instructions or explanations
* **Sound effects**: feedback tones, alert sounds, or interaction sounds
* **Ambient audio**: background music or environmental sounds
* **Audio cues**: alert the learner to important information

### Parameters

| Parameter   | Type    | Required | Description                                                                             |
| ----------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| Audio Asset | string  | Yes      | Select an audio file from your asset library.                                           |
| Loop        | boolean | No       | Set to `true` to loop the audio continuously. Default is `false` (play once).           |
| Volume      | number  | No       | Set the volume level from 0 to 1, where 0 is silent and 1 is full volume. Default is 1. |

### Key Behavior

* **Fire and forget**: Play Audio actions start the audio and the action completes immediately; subsequent actions don't wait for the audio to finish.
* **Simultaneous playback**: You can add multiple Play Audio actions to the same action list, and they will all play at once.
* **Action ID tracking**: Each Play Audio action is assigned an ID that you can reference in Stop Audio actions if you need to stop that specific audio.

## Stop Audio

### When to Use

* **Interrupt narration**: stop a narration clip if the learner advances before it finishes
* **Ambient sound cleanup**: stop looping ambient audio when exiting a state
* **Layered audio**: stop one audio clip while another continues
* **Audio fallback**: if audio is playing unexpectedly, stop it

### Parameters

| Parameter        | Type   | Required | Description                                                                                                              |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| Target Action ID | string | No       | (Optional) Reference the ID of a specific Play Audio action to stop only that clip. If omitted, all playing audio stops. |

### Key Behavior

* **Omnibus stop**: If no Target Action ID is provided, Stop Audio stops all currently playing audio.
* **Selective stop**: If you specify a Target Action ID, only that audio clip stops; other audio continues.
* **Safe to call on silent**: Calling Stop Audio when no audio is playing has no effect.

## Practical Examples

### Narration with Delay

**Scenario**: Play a 3-second narration, then show a text prompt. The learner should not see the prompt until narration is done.

<Steps>
  <Step>
    In a state's `onEntry` action list:

    1. **Play Audio**: select `narration_step1.mp3`
    2. **Delay**: `3000` (milliseconds, matching narration duration)
    3. **Show Prompt**: display interaction instructions
  </Step>

  <Step>
    The training plays audio, waits 3 seconds, then shows the prompt in sync.
  </Step>
</Steps>

### Looping Ambient Sound

**Scenario**: A factory floor training state should have background machinery noise while learners work.

<Steps>
  <Step>
    In the **FactoryFloor** state's `onEntry`:

    * **Load Scene**: `factory_floor_main`
    * **Play Audio**: `machinery_ambient.mp3`, Loop: `true`, Volume: `0.3`
  </Step>

  <Step>
    In the `onExit`:

    * **Stop Audio**: (no Target Action ID — stops all audio, including the ambient loop)
  </Step>

  <Step>
    Ambient sound plays throughout the state and is cleaned up when exiting.
  </Step>
</Steps>

### Stop Interrupted Narration

**Scenario**: Learner clicks "skip" or advances before narration finishes.

<Steps>
  <Step>
    In the `onEntry` action list, give your Play Audio action a memorable name/ID in the system (e.g., `narration_main`).
  </Step>

  <Step>
    Create a transition triggered by a "skip" button:

    * **Stop Audio**: Target Action ID: `narration_main`
    * **Training Navigation** or transition to next state
  </Step>

  <Step>
    The narration stops immediately, and the training moves forward.
  </Step>
</Steps>

<Tip>
  Keep ambient sound volumes low (0.2–0.4) so they don't drown out narration. Narration should typically be at volume 1.0.
</Tip>

<Note>
  Audio plays from the system's default audio output. If the learner's device is muted, no sound will be heard. Some trainings may require captions or text alternatives for accessibility.
</Note>

<Warning>
  If you Play Audio in `onEntry` without a corresponding Stop Audio in `onExit`, the audio may continue playing even after the state is exited. Always clean up looping audio or long-duration audio when leaving a state.
</Warning>