스마트 홈 볼륨 특성 스키마

action.devices.traits.Volume: 이 특성은 볼륨을 변경할 수 있는 기기에 속합니다 (예: 볼륨을 특정 수준으로 설정, 음소거 또는 음소거 해제).

기기 속성

이 특성이 있는 기기는 SYNC 작업의 일부로 다음 속성을 보고할 수 있습니다. SYNC 인텐트 처리에 관한 자세한 내용은 인텐트 처리를 참고하세요.

속성 유형 설명
volumeMaxLevel 정수

필수.

기준을 0 (음소거)으로 가정한 최대 볼륨 수준 어시스턴트는 부사 명령 (예: 'TV 소리 좀 크게')을 조정합니다.
volumeCanMuteAndUnmute Boolean

필수.

기기에서 볼륨을 음소거 및 음소거 해제할 수 있는지 여부를 나타냅니다. 음소거는 별도의 옵션으로, 이전 볼륨을 기억하는 동안 '음소거' 동작은 볼륨을 0으로 설정하여 음소거 해제가 복원됩니다. 이는 볼륨 상태에 반영됩니다. 볼륨이 5이고 사용자가 음소거한 경우 볼륨은 5로 유지되며 isMuted은 true입니다.
volumeDefaultPercentage 정수

(기본값: 40)

사용자 또는 제조업체에서 정의한 기본 볼륨의 볼륨 (백분율)입니다. 척도는 0~100이어야 합니다.
levelStepSize 정수

(기본값: 1)

'<device_name>의 볼륨 업 버튼'과 같은 상대적인 볼륨 쿼리의 기본 단계 크기입니다.
commandOnlyVolume Boolean

(기본값: false)

기기가 단방향 통신 (true) 또는 양방향 통신 (false)을 사용하는지 나타냅니다. 예를 들어 요청을 보낸 후 컨트롤러가 새 기기 상태를 확인할 수 있는 경우 이 필드는 false입니다. 요청이 성공적으로 실행되었는지 확인하거나 기기의 상태를 확인할 수 없는 경우 (예: 기기가 기존 적외선 리모컨인 경우) 이 필드를 true로 설정합니다.

예시

음소거가 가능하며 현재 상태를 보고하는 스피커 기기

{
  "volumeMaxLevel": 11,
  "volumeCanMuteAndUnmute": true,
  "levelStepSize": 2,
  "commandOnlyVolume": false,
  "volumeDefaultPercentage": 6
}

기기 상태: STATES

이 특성이 있는 항목은 QUERY 작업의 일부로 다음 상태를 보고할 수 있습니다. QUERY 인텐트 처리에 관한 자세한 내용은 인텐트 처리를 참고하세요.

상태 유형 설명
currentVolume 정수

필수.

현재 볼륨 비율 >0에서 volumeMaxLevel 사이여야 합니다.
isMuted Boolean

volumeCanMuteAndUnmute 속성이 true로 설정된 경우 필수입니다. 기기가 음소거된 경우 true, 그렇지 않은 경우 false입니다. isMuted이 true인 경우 기기가 저장된 포인트에 currentVolume를 반환합니다.

예시

음소거가 가능하며 현재 상태를 보고하는 스피커 기기

{
  "currentVolume": 5,
  "isMuted": false
}

기기 COMMANDS

이 특성이 있는 기기는 EXECUTE 작업의 일부로 다음 명령어에 응답할 수 있습니다. EXECUTE 인텐트 처리에 관한 자세한 내용은 인텐트 처리를 참고하세요.

action.devices.commands.mute

기기를 음소거하거나 음소거 해제합니다.

매개변수

매개변수 유형 설명
mute Boolean

필수.

기기를 음소거할지 또는 음소거 해제할지 여부

예시

스피커 기기 음소거

{
  "command": "action.devices.commands.mute",
  "params": {
    "mute": true
  }
}

action.devices.commands.setVolume

volumeMaxLevel에 따라 요청된 수준으로 볼륨을 설정합니다.

매개변수

매개변수 유형 설명
volumeLevel 정수

필수.

0권에서 volumeMaxLevel권까지 새 볼륨

예시

스피커 기기의 절대 볼륨 설정

{
  "command": "action.devices.commands.setVolume",
  "params": {
    "volumeLevel": 6
  }
}

action.devices.commands.volumeRelative

volumeMaxLevel을 기준으로 n단계씩 볼륨을 높이거나 낮춥니다. 상대적 배율을 사용하는 명령어의 경우 어시스턴트는 n을 적절히 선택하여 사용 가능한 단계로 확장합니다. 예를 들어 TV 소리 크게는 TV 소리 좀 키워 줘보다 더 높은 걸음 수를 설정합니다.

매개변수

매개변수 유형 설명
relativeSteps 정수

필수.

'감소'를 나타냅니다.

예시

명령어 모드에서 스피커 기기의 상대적 볼륨 설정

{
  "command": "action.devices.commands.volumeRelative",
  "params": {
    "relativeSteps": -1
  }
}

기기 ERRORS

오류 및 예외의 전체 목록을 참조하세요.
  • volumeAlreadyMax: 기기가 이미 최대 볼륨일 때 VolumeUp 명령어를 수신합니다.
  • volumeAlreadyMin: 기기가 이미 가장 작은 볼륨인 경우 VolumeDown 명령어를 수신합니다.