智慧型住宅音量特徵結構定義

action.devices.traits.Volume - 這項特徵屬於可變更音量的裝置 (例如將音量設為特定大小、設為靜音或取消靜音)。

裝置屬性

具有這項特徵的裝置可能會回報下列屬性，做為 SYNC 作業的一部分。如要進一步瞭解如何處理 SYNC 意圖，請參閱「意圖完成」。

屬性	類型	說明
volumeMaxLevel	整數	必要。 最大音量等級，假設基準為 0 (靜音)。Google 助理會相應調整副詞指令 (例如「把電視音量調大一點」)。
volumeCanMuteAndUnmute	布林值	必要。 指出裝置是否可以將音量設為靜音或取消靜音。「靜音」是獨立的選項，因為「靜音」行為會將音量設為 0，同時記住先前的音量，以便還原。這會反映在音量狀態中，如果音量為 5，使用者將音量調為靜音後，音量仍為 5，且 isMuted 為 true。
volumeDefaultPercentage	整數	(預設值：40) 使用者或製造商定義的預設音量百分比。範圍必須介於 0 到 100 之間。 值必須介於 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 之間。 最小值：0。
isMuted	布林值	如果 volumeCanMuteAndUnmute 屬性設為 true，則為必要屬性。如果裝置設為靜音，則傳回 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。 最小值：0。

範例

設定音箱裝置的絕對音量

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

action.devices.commands.volumeRelative

根據 volumeMaxLevel，將音量調高或調低 n 個步驟。如果指令使用相對比例，Google 助理會適當選取 n，以便根據可用步驟調整比例。舉例來說，「把電視音量調高很多」會比「把電視音量調高一點點」多調高幾個音量級距。

參數

參數	類型	說明
relativeSteps	整數	必要。 「減少」則為負數。

範例

在僅限指令模式下設定音箱裝置的相對音量

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

裝置錯誤

請參閱「錯誤和例外狀況」的完整清單。

• volumeAlreadyMax：裝置已達最高音量，但仍收到 VolumeUp 指令。
• volumeAlreadyMin：裝置音量已調到最小，但仍收到 VolumeDown 指令。