> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# PlayBackgroundFileSkill

> Control background audio/video playback during calls from a pre-configured file list.

[add-skill]: /docs/server-sdks/reference/typescript/agents/agent-base/add-skill

Control background audio/video playback during calls using SWML playback
actions. Supply `files` and the skill emits a single tool whose `action` enum
includes `start_<key>` for each configured file plus `stop`. The skill refuses
to load when `files` is empty.

**Class:** `PlayBackgroundFileSkill`

**Tools:** `play_background_file` (configurable via `tool_name`)

**Env vars:** None

**Multi-instance:** yes — set a distinct `tool_name` per instance.

**`tool_name`** `string` — default: play\_background\_file

Custom name for the generated SWAIG tool. Required when registering
multiple instances on the same agent.

---

**`files`** `object[]` — required

Array of pre-configured file entries that become selectable via the tool's
`action` enum.

Each entry has:

* `key` (string, required) — unique identifier (alphanumeric, underscores,
  hyphens); mapped to `start_<key>` in the `action` enum.
* `description` (string, required) — human-readable description shown to
  the AI.
* `url` (string, required) — URL of the audio/video file.
* `wait` (boolean, optional, default `false`) — whether to wait for the
  file to finish playing.

---

## Example

```typescript {6-14}
import { AgentBase, PlayBackgroundFileSkill } from '@signalwire/sdk';

const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
agent.setPromptText('You are a helpful assistant.');

await agent.addSkill(new PlayBackgroundFileSkill({
  tool_name: 'play_testimonial',
  files: [
    {
      key: 'massey',
      description: 'Customer success story from Massey Energy',
      url: 'https://example.com/massey.mp4',
      wait: true,
    },
  ],
}));

agent.run();
```

> Control background audio/video playback during calls from a pre-configured file list.