Google Assistant Library

google.assistant.library 패키지

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

Google 어시스턴트 라이브러리의 클라이언트입니다.

Google 어시스턴트의 기본 제어 기능과 수명 주기 처리를 제공합니다. 어시스턴트를 ContextManager로 사용하는 것이 좋습니다.

with Assistant(credentials, device_model_id) as assistant:

이렇게 하면 기본 네이티브 구현에서 메모리 관리를 올바르게 처리할 수 있습니다.

start()가 호출되면 어시스턴트는 현재 어시스턴트가 있는 다양한 상태를 전달하는 이벤트 스트림을 생성합니다(예:

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를 참고하세요.

용어:

  • 핫워드: 음소거되지 않은 상태에서 어시스턴트가 듣는 문구입니다.

    "OK Google" OR "Hey 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

어시스턴트에서 생성한 기기 ID를 반환합니다.

이 값은 Google 기기 작업과 같은 서비스를 사용할 때 서버에 기기를 식별합니다. 이 속성은 start()가 호출된 후에만 채워집니다.

반환:start()가 호출된 후의 기기 ID이며, 그렇지 않으면 빈 문자열입니다.
반환 유형:str
send_text_query(쿼리)

사용자가 말한 것처럼 |query|를 어시스턴트로 전송합니다.

이는 사용자가 핫워드를 말하고 쿼리를 실행하거나 후속 쿼리에 대한 답변을 말하는 것과 동일하게 작동합니다.

매개변수:query (str): 어시스턴트로 전송할 텍스트 쿼리입니다.
set_mic_mute(is_muted)

어시스턴트가 핫워드를 듣지 못하게 합니다.

어시스턴트가 핫워드를 리슨하지 못하도록 사용 중지할 수 있습니다. 이 기능은 Google Home 뒷면의 개인 정보 보호 버튼과 유사한 기능을 제공합니다.

어시스턴트가 아직 시작되지 않은 경우 이 메서드는 아무 작업도 하지 않습니다.

매개변수:is_muted (불리언) – true이면 어시스턴트가 리슨을 중지하고 false이면 다시 시작할 수 있습니다.
start()

핫워드 수신 대기를 포함하여 어시스턴트를 시작합니다.

start()이 호출되면 어시스턴트는 '기본' ALSA 오디오 소스의 데이터를 처리하기 시작하여 핫워드를 리슨합니다. 이렇게 하면 타이머/알람과 같이 어시스턴트에서 제공하는 다른 서비스도 시작됩니다. 이 메서드는 한 번만 호출할 수 있습니다. 호출되면 어시스턴트는 __exit__가 호출될 때까지 계속 실행됩니다.

반환:어시스턴트 상태 변경을 알리는 이벤트 큐입니다.
반환 유형:google.assistant.event.IterableEventQueue
start_conversation()

어시스턴트와 새 대화를 수동으로 시작합니다.

어시스턴트가 호출어를 들을 때와 마찬가지로 사용자의 음성 녹음과 Google에 전송을 모두 시작합니다.

어시스턴트가 시작되지 않았거나 음소거된 경우 이 메서드는 아무 작업도 하지 않습니다.

stop_conversation()

어시스턴트와의 활성 대화를 중지합니다.

어시스턴트가 사용자의 쿼리를 듣고 있거나 응답하고 있을 수 있습니다. 활성 대화가 없는 경우 아무 일도 일어나지 않습니다.

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

현재 기기에서 실행할 명령어 생성기입니다.

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

어시스턴트에서 생성한 이벤트입니다.

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 클래스 특수화에 관한 선택적 인수 키-값 쌍입니다.
클래스 google.assistant.library.event.EventType

이벤트 유형

ON_ALERT_FINISHED = 11

alert_type 알림이 울리기를 완료했음을 나타냅니다.

매개변수:alert_type (AlertType): 방금 완료된 알림 유형을 나타내는 enum의 ID입니다.
ON_ALERT_STARTED = 10

알림이 울리기 시작했음을 나타냅니다.

이 알림은 동일한 alert_type가 포함된 ON_ALERT_FINISHED이 수신될 때까지 계속됩니다. 한 번에 하나의 알림만 활성화되어야 합니다.

매개변수:alert_type (AlertType): 현재 울리는 알림 유형을 나타내는 enum의 ID입니다.
ON_ASSISTANT_ERROR = 12

어시스턴트 라이브러리에서 오류가 발생했는지 여부를 나타냅니다.

매개변수:is_fatal (불리언): True이면 어시스턴트를 복구할 수 없으므로 다시 시작해야 합니다.
ON_CONVERSATION_TURN_FINISHED = 9

어시스턴트가 현재 차례를 완료했습니다.

여기에는 사용자의 쿼리 처리와 전체 응답(있는 경우) 음성 출력이 모두 포함됩니다.

매개변수:with_follow_on_turn (불리언): true인 경우 어시스턴트는 사용자의 후속 상호작용을 예상합니다. 사용자가 후속 질문에 답변할 수 있도록 마이크가 다시 열립니다.
ON_CONVERSATION_TURN_STARTED = 1

새로운 차례가 시작되었음을 나타냅니다.

어시스턴트가 현재 대기 중이며 사용자 쿼리를 기다리고 있습니다. 이는 호출어를 듣거나 어시스턴트에서 start_conversation()이 호출된 결과일 수 있습니다.

ON_CONVERSATION_TURN_TIMEOUT = 2

구분 가능한 쿼리를 기다리는 중에 어시스턴트의 제한 시간이 초과되었습니다.

호워드가 잘못 트리거되었거나 어시스턴트가 사용자가 말한 내용을 이해하지 못한 것일 수 있습니다.

ON_DEVICE_ACTION = 14

기기 작업 요청이 기기에 전달되었음을 나타냅니다.

이는 기기에서 지원하는 트레잇에 대해 기기 문법이 트리거되는 경우 전달됩니다. 이 이벤트 유형에는 특수한 '작업' 속성이 있습니다. 이 속성은 반복자 또는 기기 작업 명령어와 관련된 매개변수 (해당하는 경우)를 반환합니다.

매개변수:dict: 기기 작업 요청의 디코딩된 JSON 페이로드입니다.
ON_END_OF_UTTERANCE = 3

어시스턴트가 사용자 쿼리 수신을 중지했습니다.

어시스턴트가 사용자가 말한 내용을 파악하지 못했지만 더 이상 오디오 데이터를 수신하지 않았을 수 있습니다.

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): 앨범 아트의 URL입니다. 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): 앨범 아트의 URL입니다. 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): 앨범 아트의 URL입니다. artist(str): 이 트랙을 만든 아티스트입니다. duration_ms(double): 이 트랙의 길이(밀리초)입니다. title(str): 트랙의 제목입니다.
  • position_ms(double): 중지된 트랙의 현재 위치(시작부터 밀리초)입니다. 'metadata.duration_ms'가 알 수 없는 경우 (0으로 설정됨) 이 필드는 설정되지 않습니다.
  • track_type (MediaTrackType): 중지된 트랙의 유형입니다.
ON_MUTED_CHANGED = 13

어시스턴트가 현재 듣고 있는지 여부를 나타냅니다.

start()는 항상 초기 값을 보고하기 위해 ON_MUTED_CHANGED를 생성합니다.

매개변수:is_muted (불리언): true인 경우 어시스턴트가 현재 핫워드를 리슨하고 있지 않으며 사용자 쿼리에 응답하지 않습니다.
ON_NO_RESPONSE = 8

어시스턴트가 자신의 차례를 완료했지만 할 말이 없습니다.

ON_RECOGNIZING_SPEECH_FINISHED = 5

어시스턴트가 최종 인식된 음성을 확인했습니다.

매개변수:text (str): 사용자 쿼리의 최종 텍스트 해석입니다.
ON_RENDER_RESPONSE = 15

어시스턴트에게 응답을 렌더링할 텍스트 출력이 있음을 나타냅니다.

매개변수:
  • 유형 (RenderResponseType): 렌더링할 응답 유형입니다.
  • text (str): RenderResponseType.TEXT에 렌더링할 문자열입니다.
ON_RESPONDING_FINISHED = 7

어시스턴트가 음성으로 응답을 완료했습니다.

ON_RESPONDING_STARTED = 6

어시스턴트가 음성으로 응답하기 시작합니다.

ON_RESPONDING_FINISHED가 수신될 때까지 어시스턴트가 응답합니다.

매개변수:is_error_response (불리언) – true이면 로컬 오류 TTS가 재생되고 있는 것이고, 그렇지 않으면 어시스턴트가 서버 응답으로 응답합니다.
ON_START_FINISHED = 0

어시스턴트 라이브러리 시작이 완료되었습니다.

클래스 google.assistant.library.event.IterableEventQueue(timeout=3600)

queue.Queue를 확장하여 __iter__ 인터페이스를 추가합니다.

offer(event)

대기열에 추가할 이벤트를 제공합니다.

현재 대기열이 가득 차면 이벤트가 기록되지만 추가되지는 않습니다.

매개변수:event (이벤트): 큐에 추가하려는 이벤트입니다.
class google.assistant.library.event.MediaStateChangeEvent(event_type, args, **_)

'state' 파싱을 추가하도록 Event를 확장합니다.

클래스 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와 함께 사용