智慧型住宅體積特徵結構定義

action.devices.traits.Volume - 這個特徵屬於可調整音量的裝置 (例如將音量設為特定音量、設為靜音或取消靜音)。

裝置屬性

具備這項特徵的裝置可能會回報下列資料： 在 SYNC 作業中使用屬性變更。學習 如要進一步瞭解如何處理 SYNC 意圖，請參閱 意圖執行要求。

屬性	類型	說明
volumeMaxLevel	整數	必要。 最大音量，假設基準為 0 (靜音)。Google 助理就會據此調整副指令，例如「稍微調高電視音量」。
volumeCanMuteAndUnmute	布林值	必要。 指出裝置是否可以將音量設為靜音及取消靜音。靜音是「靜音」的獨立選項所以記住上一個磁碟區時，音量會設為 0，這時取消靜音就會還原。音量狀態會反映到音量狀態。如果音量為 5，而使用者設為靜音，音量會維持在 5，且 isMuted 的值為 true。
volumeDefaultPercentage	整數	(預設值：40) 使用者或製造商定義的預設音量大小 (以百分比表示)。比例必須介於 0 至 100 之間。
levelStepSize	整數	(預設值：1) 相對量查詢的預設步數，例如「在 <device_name> 上增加量」。
commandOnlyVolume	布林值	(預設值：false) 指出裝置是透過單向 (true) 或雙向 (false) 通訊運作。舉例來說，如果控制器可以在傳送要求後確認新裝置狀態，這個欄位就會是 false。如果無法確認要求是否成功執行，或無法取得裝置狀態 (例如，該裝置為傳統紅外線遙控器)，請將這個欄位設為 true。

範例

喇叭裝置可設為靜音並回報目前狀態

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

裝置狀態

具有此特徵的實體可能會回報下列資料： 做為 QUERY 作業的一部分。學習 如要進一步瞭解如何處理 QUERY 意圖，請參閱 意圖執行要求。

州	類型	說明
currentVolume	整數	必要。 目前的音量百分比。這個值必須介於 >0 至 volumeMaxLevel 之間。
isMuted	布林值	如果 volumeCanMuteAndUnmute 屬性設為 true，則為必要欄位。如果裝置設為靜音，則為「是」；否則傳回 false。如果 isMuted 為 true，裝置仍會針對記住的點傳回 currentVolume。

範例

喇叭裝置可設為靜音並回報目前狀態

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

裝置指令

具備這種特徵的裝置可能會回應下列問題 做為 EXECUTE 作業的一部分。學習 如要進一步瞭解如何處理 EXECUTE 意圖，請參閱 意圖執行要求。

action.devices.commands.mute

將裝置設為靜音或取消靜音。

參數

參數	類型	說明
mute	布林值	必要。 是否將裝置設為靜音或取消靜音。

範例

將喇叭裝置設為靜音

{
  "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 步。如果指令使用相對體重計，Google 助理會適當選取「n」，以縮放至可用步驟。舉例來說，如果選擇「調高電視音量」，將設定步數比「稍微調高電視音量」。

參數

參數	類型	說明
relativeSteps	整數	必要。 代表「decrease」。

範例

在僅使用指令模式下設定揚聲器裝置的相對音量

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

裝置錯誤

查看完整清單 錯誤和例外狀況。

• volumeAlreadyMax：裝置收到 VolumeUp 指令時 已經達到最大音量
• volumeAlreadyMin：裝置收到 VolumeDown 指令時 當做最低音量。