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

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，則為必要屬性。如果裝置設為靜音，則為 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 整數

必要。

設為「負值」。

範例

設定僅限語音指令的揚聲器音量

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

裝置 ERRORS

請參閱錯誤和例外狀況的完整清單。
  • volumeAlreadyMax：裝置在最大音量時接收 VolumeUp 指令。
  • volumeAlreadyMin：如果裝置最低音量，裝置會收到 VolumeDown 指令。