Google Assistant Library

google.assistant.library 软件包。

类 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"

  • 回合：一次用户请求，后跟 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!"
参数：
  • credentials (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（布尔值）- 如果为 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”的解析。

类 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)

扩展了 Event，以添加“actions”属性。

actions

用于为当前设备生成要执行的命令的生成器。

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

由 Google 助理生成的事件。

type

EventType - 生成的事件类型。

args

字典 - 与此事件关联的参数键值对。

static New(event_type, args, **kwargs)

在需要时，使用专用 Event 类创建新事件。

参数：
  • event_type（int）- 与 google.assistant.event.EventType 中的事件对应的数字 ID。
  • args（字典）- 与此事件关联的参数键值对。
  • kwargs（字典）- 特定于 EventType 的 Event 类的特殊化的实参键值对（可选）。
类 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（布尔值）- 如果为 True，则 Google 助理将无法恢复，并且应重启。
ON_CONVERSATION_TURN_FINISHED = 9

Google 助理已完成当前转弯。

这包括处理用户的询问，以及读出完整的回答（如果有）。

参数：with_follow_on_turn（布尔值）- 如果为 True，则表示 Google 助理希望用户进行后续互动。系统会重新打开麦克风，以便用户回答后续问题。
ON_CONVERSATION_TURN_STARTED = 1

表示新转弯已开始。

Google 助理目前正在聆听，等待用户发出询问。这可能是由于 Google 助理听到启动指令或有人调用 start_conversation() 而导致的。

ON_CONVERSATION_TURN_TIMEOUT = 2

Google 助理在等待可辨别的询问时超时。

这可能是由于热词误触发或 Google 助理无法理解用户所说的内容所致。

ON_DEVICE_ACTION = 14

表示已向设备分派 Device Action 请求。

如果设备支持的特征触发了任何设备语法，系统就会调度此 intent。此事件类型具有一个特殊的“actions”属性，该属性将返回迭代器或设备操作命令及其关联的参数（如果适用）。

参数：dict - 设备 Action 请求的已解码 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（字典）-

    已加载轨道的元数据。此时，并非所有字段都会填充 - 如果字段未知，则不会包含。元数据字段包括：

    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）时，此操作才会触发

参数：
  • 元数据（字典）-

    正在播放的曲目的元数据。如果字段未知，则不会包含。元数据字段包括：

    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。

参数：
  • 元数据（字典）-

    已停止的轨道的元数据。如果字段未知，则不会包含。元数据字段包括：

    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（布尔值）- 如果为 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（事件）- 要尝试添加到队列中的事件。
class google.assistant.library.event.MediaStateChangeEvent(event_type, args, **_)

扩展了事件以添加“state”的解析。

类 google.assistant.library.event.MediaTrackType

ON_MEDIA_TRACK_X 事件的轨道类型。

与 ON_MEDIA_TRACK_LOAD、ON_MEDIA_TRACK_PLAY 和 ON_MEDIA_TRACK_STOP 搭配使用

CONTENT = 2

内容（新闻/播客）的实际内容。

TTS = 1

与商品相关的 TTS 简介或插页式广告曲目。

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

扩展了事件，以添加“response_type”的解析。

类 google.assistant.library.event.RenderResponseType

要呈现的内容类型。

与 ON_RENDER_RESPONSE 搭配使用