智慧型住宅磁碟區特徵結構定義

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 整數

必要。

目前的音量百分比。必須介於 >0volumeMaxLevel 之間。

isMuted 布林

如果 volumeCanMuteAndUnmute 屬性設為 true,則為必要欄位。如果裝置設為靜音,則為「是」,否則傳回「否」。如果 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 整數

必要。

新音量,從 0volumeMaxLevel

範例

設定喇叭裝置的絕對音量

{
  "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 指令。