智慧型住宅音量音量結構定義
action.devices.traits.Volume
- 這個特質屬於可以調整音量的裝置 (例如將音量設為特定等級、靜音或取消靜音)。
裝置屬性
具有此特性的裝置可能會在 SYNC
作業中回報下列屬性。如要進一步瞭解如何處理 SYNC
意圖,請參閱意圖執行要求一文。
屬性 | 類型 | 說明 |
---|---|---|
volumeMaxLevel |
整數 |
必填。 最大音量等級 (假設基準為 0 (靜音)。Google 助理會據此調整副詞指令 (例如「讓電視更大聲」)。 |
volumeCanMuteAndUnmute |
布林 |
必填。 指出裝置是否可以設為靜音及取消靜音。「靜音」是另外的選擇,因為「靜音」行為會將音量設定為 0,同時記住先前的音量,以便取消靜音。這反映的是磁碟區狀態 - 如果音量為 5,而使用者將音量設為靜音,音量則會保持 5,而 |
volumeDefaultPercentage |
整數 |
(預設: 使用者或製造商定義的預設音量音量 (百分比)。比例範圍必須為 0-100。 |
levelStepSize |
整數 |
(預設: 相關音量查詢的預設步驟大小,例如「在 <裝置名稱> 上調高音量」。 |
commandOnlyVolume |
布林 |
(預設: 指出裝置是否使用單向 (true) 或雙向 (false) 通訊。舉例來說,如果控制器在傳送要求後可確認新裝置狀態,這個欄位就會是 false。如果無法確認要求是否成功執行或取得裝置狀態 (例如裝置是傳統紅外線遙控器),請將這個欄位設為 true。 |
範例
可設為靜音並回報目前狀態的揚聲器裝置
{ "volumeMaxLevel": 11, "volumeCanMuteAndUnmute": true, "levelStepSize": 2, "commandOnlyVolume": false, "volumeDefaultPercentage": 6 }
裝置狀態:STATE
具有此特性的實體可能會在 QUERY
作業中回報下列狀態。如要進一步瞭解如何處理 QUERY
意圖,請參閱意圖執行要求一文。
州 | 類型 | 說明 |
---|---|---|
currentVolume |
整數 |
必填。 目前的音量百分比。這個值必須介於 |
isMuted |
布林 |
如果 |
範例
可設為靜音並回報目前狀態的揚聲器裝置
{ "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 |
整數 |
必填。 新的音量,從 |
範例
設定揚聲器裝置的絕對音量
{ "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 } }
裝置錯誤:ERRORS
請參閱錯誤和例外狀況的完整清單。volumeAlreadyMax
:裝置在最大音量時會收到VolumeUp
指令。volumeAlreadyMin
:如果裝置已處於最小音量,則會收到VolumeDown
指令。