{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://jambonz.org/schema/verbs/play",
  "minVersion": "0.9.6",
  "title": "Play",
  "description": "Plays an audio file to the caller. Supports WAV and MP3 formats hosted at a URL. Can play a single file or cycle through a list of files.",
  "type": "object",
  "properties": {
    "verb": {
      "const": "play",
      "description": "The verb name."
    },
    "id": {
      "type": "string",
      "description": "An optional unique identifier for this verb instance."
    },
    "url": {
      "oneOf": [
        {
          "type": "string",
          "format": "uri"
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uri"
          }
        }
      ],
      "description": "The URL(s) of the audio file(s) to play. Supports WAV and MP3. If an array, files are played in sequence.",
      "examples": [
        "https://example.com/sounds/greeting.wav",
        [
          "https://example.com/sounds/part1.wav",
          "https://example.com/sounds/part2.wav"
        ]
      ]
    },
    "loop": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Number of times to repeat playback. Use 0 or 'forever' to loop indefinitely until interrupted.",
      "examples": [
        3,
        "forever"
      ]
    },
    "earlyMedia": {
      "type": "boolean",
      "description": "If true, play the audio as early media before the call is answered."
    },
    "seekOffset": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Start playback at this offset in seconds from the beginning of the file."
    },
    "timeoutSecs": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Maximum time in seconds to play the audio. Playback stops after this duration even if the file has not finished."
    },
    "actionHook": {
      "$ref": "../components/actionHook",
      "description": "A webhook to invoke when playback completes."
    }
  },
  "required": [
    "url"
  ],
  "examples": [
    {
      "verb": "play",
      "url": "https://example.com/sounds/hold-music.mp3",
      "loop": "forever"
    }
  ]
}