Google Assistant Library

google.assistant.library 套件。

class google.assistant.library.Assistant(credentials, device_model_id)

Google 助理程式庫的用戶端。

為 Google 助理提供基本控制功能和生命週期處理機制。建議做法是將 Google 助理用作 ContextManager：

with Assistant(credentials, device_model_id) as assistant:

這可讓基礎原生實作項目正確處理記憶體管理。

呼叫 start() 後，Google 助理會產生事件串流，轉送 Google 助理目前處於的各種狀態，例如：

ON_CONVERSATION_TURN_STARTED
ON_END_OF_UTTERANCE
ON_RECOGNIZING_SPEECH_FINISHED:
    {'text': 'what time is it'}
ON_RESPONDING_STARTED:
    {'is_error_response': False}
ON_RESPONDING_FINISHED
ON_CONVERSATION_TURN_FINISHED:
    {'with_follow_on_turn': False}

如要進一步瞭解所有事件及其引數，請參閱 EventType。

詞彙解釋：

  • 啟動字詞：Google 助理在未靜音時會聽取的字詞：

    "OK Google" OR "Hey Google"

  • Turn：單一使用者要求，後面接著 Google 助理的回應。

  • 對話：一或多個回合，可讓 Google 助理提供所需的最終結果：

    "What time is it?" -> "The time is 6:24 PM" OR
"Set a timer" -> "Okay, for how long?" ->
"5 minutes" -> "Sure, 5 minutes, starting now!"
參數：
  • 憑證 (google.oauth2.credentials.Credentials) – 使用者的 Google OAuth2 憑證。
  • device_model_id (str)：您在 Google 註冊專案時所使用的 device_model_id。不得為空白字串。
發出：

ValueError：如果 device_model_id 為 None 或空白。
device_id

傳回 Google 助理產生的裝置 ID。

使用 Google 裝置動作等服務時，這個值會向伺服器識別您的裝置。這個屬性只有在呼叫 start() 後才會填入。

傳回：呼叫 start() 後的裝置 ID，否則為空字串。
傳回類型：str
send_text_query(查詢)

將 |query| 傳送至 Google 助理，就像使用者說話一樣。

這會產生與使用者說出熱鍵字並進行查詢，或說出後續查詢的答案相同的行為。

參數：query (str) – 要傳送給 Google 助理的文字查詢。
set_mic_mute(is_muted)

停止 Google 助理聽取啟動字詞。

可讓您停用 Google 助理偵聽啟動字詞的功能。這項功能的功能類似 Google Home 背面的隱私權按鈕。

如果 Google 助理尚未啟動，這個方法就會無效。

參數：is_muted (bool) – 如果為 True，Google 助理就會停止聆聽，如果為 False，Google 助理就會重新開始聆聽。
start()

啟動 Google 助理，包括聽取啟動字詞。

呼叫 start() 後，Google 助理就會開始從「預設」ALSA 音訊來源處理資料，並監聽熱字詞。這也會啟動 Google 助理提供的其他服務，例如計時器/鬧鐘。這個方法只能呼叫一次。呼叫後，Google 助理會持續執行，直到呼叫 __exit__ 為止。

傳回：事件佇列，用於通知 Google 助理狀態的變更。
傳回類型：google.assistant.event.IterableEventQueue
start_conversation()

手動與 Google 助理發起新對話。

開始錄製使用者的語音並傳送給 Google，類似於 Google 助理聽到關鍵字時的情況。

如果 Google 助理未啟動或已設為靜音，這個方法就會無效。

stop_conversation()

停止與 Google 助理的任何對話。

可能是 Google 助理正在聽取使用者的查詢或回應。如果沒有進行中的對話，則不會執行任何操作。

class google.assistant.library.event.AlertEvent(event_type, args, **_)

擴充事件，新增「alert_type」的剖析。

class google.assistant.library.event.AlertType

快訊類型。

可搭配 ON_ALERT_STARTED 和 ON_ALERT_FINISHED 事件使用。

ALARM = 0

以絕對時間設定的活動，例如「星期一凌晨 3 點」

TIMER = 1

以相對時間設定的事件，例如「從現在起 30 秒」

class google.assistant.library.event.DeviceActionEvent(event_type, args, **kwargs)

擴充事件以新增「actions」屬性。

actions

產生器，用於為目前裝置執行指令。

class google.assistant.library.event.Event(event_type, args, **_)

Google 助理產生的事件。

type

EventType：產生的事件類型。

args

dict – 與此事件相關聯的引數鍵/值組合。

static New(event_type, args, **kwargs)

視需要使用專屬的 Event 類別建立新事件。

參數：
  • event_type (int) – 與 google.assistant.event.EventType 中事件相對應的數字 ID。
  • args (dict) – 與此事件相關聯的引數鍵/值組合。
  • kwargs (dict) – 針對 EventType 的 Event 類別專屬的選用引數鍵/值組合。
class google.assistant.library.event.EventType

事件類型。

ON_ALERT_FINISHED = 11

表示 alert_type 的警示音已結束。

參數：alert_type (AlertType) – 代表剛結束的快訊類型的列舉 ID。
ON_ALERT_STARTED = 10

表示警報聲響已開始。

直到收到同一個 alert_type 的 ON_ALERT_FINISHED 為止。任何時間點都應只啟用一個快訊。

參數：alert_type (AlertType) – 代表目前快訊類型的列舉 ID。
ON_ASSISTANT_ERROR = 12

指出 Google 助理程式庫是否發生錯誤。

參數：is_fatal (bool)：如果為 True，則 Google 助理將無法復原，應重新啟動。
ON_CONVERSATION_TURN_FINISHED = 9

Google 助理已完成目前的轉彎。

這包括處理使用者的查詢，以及說出完整回應 (如有)。

參數：with_follow_on_turn (bool) – 如果為 True，Google 助理會預期使用者會進行後續互動。系統會重新開啟麥克風，讓使用者回答後續問題。
ON_CONVERSATION_TURN_STARTED = 1

表示新回合已開始。

Google 助理目前正在聆聽，等待使用者提出查詢。這可能是因為 Google 助理聽到啟動字詞或有人呼叫 start_conversation() 所致。

ON_CONVERSATION_TURN_TIMEOUT = 2

Google 助理在等待可辨識的查詢時逾時。

這可能是因為誤觸熱鍵，或是 Google 助理無法理解使用者所說的內容。

ON_DEVICE_ACTION = 14

表示已將 Device Action 要求調度至裝置。

如果裝置支援的特徵觸發任何裝置文法，就會傳送此事件。這個事件類型具有特殊的「actions」屬性，可傳回迭代器或裝置動作指令，以及與之相關聯的參數 (如適用)。

參數：dict – 裝置動作要求的解碼 JSON 酬載。
ON_END_OF_UTTERANCE = 3

Google 助理已停止收聽使用者查詢。

Google 助理可能尚未完成判斷使用者說了什麼，但已停止收聽更多音訊資料。

ON_MEDIA_STATE_ERROR = 20

表示播放曲目時發生錯誤。

如果沒有可播放的內容，內建媒體播放器會嘗試跳到下一首曲目，或返回 ON_MEDIA_STATE_IDLE。

ON_MEDIA_STATE_IDLE = 16

表示目前沒有任何內容正在播放，也沒有任何內容在播放佇列中。

這個事件會在 Google 助理程式庫的內建媒體播放器啟動時，以及當使用者停止或暫停媒體，導致媒體串流逾時時，透過該播放器廣播。

ON_MEDIA_TRACK_LOAD = 17

表示曲目正在載入，但尚未開始播放。

如果新中繼資料是異步載入，這項作業可能會調度多次。這通常會接著事件 ON_MEDIA_TRACK_PLAY 發生

參數：
  • metadata (dict) –

    已載入音軌的中繼資料。並非所有欄位都會在此時填入資料，如果欄位未知，就不會納入。中繼資料欄位包括：

    album(str)：曲目所屬專輯的名稱。 album_art(str)：專輯封面的網址。 artist(str)：製作此曲目的藝人。 duration_ms(double)：此曲目的長度 (以毫秒為單位)。 title(str)：曲目名稱。
  • track_type (MediaTrackType)：載入的曲目類型。
ON_MEDIA_TRACK_PLAY = 18

表示音軌目前正在輸出音訊。

只有在從一個狀態轉換至另一個狀態時才會觸發，例如從 ON_MEDIA_TRACK_LOAD 或 ON_MEDIA_TRACK_STOP

參數：
  • metadata (dict) –

    播放音軌的中繼資料。如果欄位不明，就不會納入。中繼資料欄位包括：

    album(str)：曲目所屬專輯的名稱。 album_art(str)：專輯封面的網址。 artist(str)：製作此曲目的藝人。 duration_ms(double)：此曲目的長度 (以毫秒為單位)。 title(str)：曲目名稱。
  • position_ms (double) – 播放中曲目中目前的位置，以毫秒為單位，從開頭開始計算。如果「metadata.duration_ms」不明 (設為 0)，系統就不會設定這個欄位。
  • track_type (MediaTrackType) – 播放的曲目類型。
ON_MEDIA_TRACK_STOP = 19

表示先前播放的曲目已停止。

這通常是使用者暫停的結果；如果使用者恢復播放，曲目就會返回 ON_MEDIA_TRACK_PLAY。

參數：
  • metadata (dict) –

    已停止的曲目中繼資料。如果欄位不明，就不會納入。中繼資料欄位包括：

    album(str)：曲目所屬專輯的名稱。 album_art(str)：專輯封面的網址。 artist(str)：製作此曲目的藝人。 duration_ms(double)：此曲目的長度 (以毫秒為單位)。 title(str)：曲目名稱。
  • position_ms (double) – 已停止的音軌中，從開頭開始的目前位置，以毫秒為單位。如果「metadata.duration_ms」不明 (設為 0)，系統就不會設定這個欄位。
  • track_type (MediaTrackType)：停止的曲目類型。
ON_MUTED_CHANGED = 13

指出 Google 助理目前是否正在聆聽。

start() 一律會產生 ON_MUTED_CHANGED 來回報初始值。

參數：is_muted (bool)：如果為 True，則 Google 助理目前並未聆聽啟動字詞，也不會回應使用者查詢。
ON_NO_RESPONSE = 8

Google 助理已順利完成其回應，但沒有任何回應。

ON_RECOGNIZING_SPEECH_FINISHED = 5

Google 助理已判斷出最終辨識的語音。

參數：text (str) – 使用者查詢的最終文字解讀結果。
ON_RENDER_RESPONSE = 15

表示 Google 助理有文字輸出內容，可用於回應。

參數：
  • type (RenderResponseType)：要算繪的回應類型。
  • text (str)：RenderResponseType.TEXT 要轉譯的字串。
ON_RESPONDING_FINISHED = 7

Google 助理已完成語音回應。

ON_RESPONDING_STARTED = 6

Google 助理開始以語音回應。

在收到 ON_RESPONDING_FINISHED 之前，Google 助理會持續回應。

參數：is_error_response (bool) – 如果為 True，表示系統正在播放本機錯誤 TTS，否則 Google 助理會回應伺服器回應。
ON_START_FINISHED = 0

Google 助理程式庫已完成啟動。

類別 google.assistant.library.event.IterableEventQueue(timeout=3600)

擴充 queue.Queue 以新增 __iter__ 介面。

offer(event)

提供要放入佇列的事件。

如果佇列目前已滿，系統會記錄事件，但不會新增事件。

參數：event (Event)：嘗試新增至佇列的事件。
class google.assistant.library.event.MediaStateChangeEvent(event_type, args, **_)

擴充事件，新增「state」的剖析。

class google.assistant.library.event.MediaTrackType

ON_MEDIA_TRACK_X 事件的音軌類型。

與 ON_MEDIA_TRACK_LOAD、ON_MEDIA_TRACK_PLAY 和 ON_MEDIA_TRACK_STOP 搭配使用

CONTENT = 2

項目 (新聞/Podcast) 的實際內容。

TTS = 1

與商品相關的 TTS 介紹或插播曲目。

class google.assistant.library.event.RenderResponseEvent(event_type, args, **_)

擴充事件，新增「response_type」的剖析功能。

class google.assistant.library.event.RenderResponseType

要轉譯的內容類型。

與 ON_RENDER_RESPONSE 搭配使用