AgentsSkills

PlayBackgroundFileSkill

View as MarkdownOpen in Claude

Control background audio/video playback during calls using SWML playback actions. Two configuration modes are supported:

  • Pre-configured mode (matches Python) — supply files and the skill emits a single tool whose action enum includes start_<key> for each configured file plus stop.
  • Free-form mode (TypeScript-specific) — omit files and supply default_file_url and/or allowed_domains. The skill emits two tools, play_background and stop_background, which accept arbitrary URLs (with optional domain allowlist).

Class: PlayBackgroundFileSkill

Tools (pre-configured mode): play_background_file (configurable via tool_name)

Tools (free-form mode): play_background, stop_background

Env vars: None

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

tool_name
stringDefaults to play_background_file

Custom name for the generated SWAIG tool in pre-configured mode. Required when registering multiple instances on the same agent.

files
object[]

Array of pre-configured file entries that become selectable via the tool’s action enum. When supplied (and non-empty), the skill runs in pre-configured mode; when omitted or empty, the skill falls back to free-form mode.

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.
default_file_url
string

Default audio file URL for free-form mode. When set, the file_url parameter on the play_background tool becomes optional.

allowed_domains
string[]

Allowlist of domains for audio file URLs in free-form mode. When set, only URLs whose hostname matches or is a subdomain of one of these entries are accepted.

Example — pre-configured files

1import { AgentBase, PlayBackgroundFileSkill } from '@signalwire/sdk';
2
3const agent = new AgentBase({ name: 'assistant', route: '/assistant' });
4agent.setPromptText('You are a helpful assistant.');
5
6await agent.addSkill(new PlayBackgroundFileSkill({
7  tool_name: 'play_testimonial',
8  files: [
9    {
10      key: 'massey',
11      description: 'Customer success story from Massey Energy',
12      url: 'https://example.com/massey.mp4',
13      wait: true,
14    },
15  ],
16}));
17
18agent.run();

Example — free-form URL

1await agent.addSkill(new PlayBackgroundFileSkill({
2  default_file_url: 'https://example.com/hold-music.mp3',
3  allowed_domains: ['example.com', 'cdn.example.com'],
4}));