Schemas

Speaker

A network audio speaker: playback transport, volume/mute, URI playback, and group membership.

https://hometruth.ai/schemas/speaker · Speaker

Instances

• SpeakersSonos speaker · Great room

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hometruth.ai/schemas/speaker",
  "title": "Speaker",
  "description": "A network audio speaker (e.g. Sonos): playback transport, volume/mute, arbitrary URI playback, an optional spoken/announcement shortcut, and group membership for whole-home audio.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "state": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "availability": {
          "enum": [
            "online",
            "offline",
            "degraded",
            "unknown"
          ]
        },
        "observedAt": {
          "type": "string",
          "format": "date-time"
        },
        "playback": {
          "enum": [
            "playing",
            "paused",
            "stopped",
            "transitioning",
            "unknown"
          ]
        },
        "volumePercent": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "muted": {
          "type": "boolean"
        },
        "track": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "title": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "artist": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "album": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "uri": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2000
            },
            "durationSeconds": {
              "type": "number",
              "minimum": 0
            },
            "positionSeconds": {
              "type": "number",
              "minimum": 0
            }
          }
        },
        "group": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "coordinatorHost": {
              "type": "string",
              "minLength": 1,
              "maxLength": 253
            },
            "isCoordinator": {
              "type": "boolean"
            },
            "memberHosts": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 253
              },
              "maxItems": 32
            }
          },
          "required": [
            "coordinatorHost",
            "isCoordinator"
          ]
        }
      },
      "required": [
        "availability"
      ]
    },
    "actions": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "properties": {
        "play": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "pause": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "stop": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "setVolume": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "minimumPercent": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "maximumPercent": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          },
          "required": [
            "minimumPercent",
            "maximumPercent"
          ]
        },
        "setMute": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "playUri": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "say": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "maxLength": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000
            }
          }
        },
        "joinGroup": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "leaveGroup": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        },
        "getState": {
          "type": "object",
          "additionalProperties": false,
          "properties": {}
        }
      },
      "required": [
        "play",
        "pause",
        "stop",
        "setVolume",
        "setMute",
        "playUri",
        "joinGroup",
        "leaveGroup",
        "getState"
      ]
    }
  },
  "required": [
    "id",
    "state",
    "actions"
  ],
  "examples": [
    {
      "id": "living-room-sonos",
      "state": {
        "availability": "online",
        "observedAt": "2026-09-06T20:00:00Z",
        "playback": "playing",
        "volumePercent": 35,
        "muted": false,
        "track": {
          "title": "Example Track",
          "artist": "Example Artist",
          "positionSeconds": 42,
          "durationSeconds": 210
        },
        "group": {
          "coordinatorHost": "10.77.0.170",
          "isCoordinator": true,
          "memberHosts": [
            "10.77.0.170"
          ]
        }
      },
      "actions": {
        "play": {},
        "pause": {},
        "stop": {},
        "setVolume": {
          "minimumPercent": 0,
          "maximumPercent": 100
        },
        "setMute": {},
        "playUri": {},
        "say": {
          "maxLength": 500
        },
        "joinGroup": {},
        "leaveGroup": {},
        "getState": {}
      }
    }
  ]
}