Google Assistant Library

بسته google.assistant.library.

کلاس google.assistant.library. Assistant ( اعتبار ، device_model_id )

مشتری برای کتابخانه دستیار Google.

عملکرد کنترل اولیه و مدیریت چرخه عمر را برای دستیار Google ارائه می دهد. بهترین روش استفاده از Assistant به عنوان ContextManager است:

with Assistant(credentials, device_model_id) as assistant:

این اجازه می دهد تا پیاده سازی اصلی زیربنایی به درستی مدیریت حافظه را مدیریت کند.

هنگامی که start() فراخوانی شد، Assistant جریانی از رویدادها را ایجاد می کند که حالت های مختلفی را که دستیار در حال حاضر در آن قرار دارد، انتقال می دهد، به عنوان مثال:

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"

  • Turn : یک درخواست تک کاربر و به دنبال آن پاسخی از دستیار.

  • مکالمه : یک یا چند چرخش که منجر به نتیجه نهایی مطلوب از دستیار می شود:

    "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 ) – device_model_id که برای پروژه شما در Google ثبت شده است. این نباید یک رشته خالی باشد.
افزایش می دهد:

ValueError – اگر device_model_id به عنوان None یا خالی باقی بماند.

device_id

شناسه دستگاه تولید شده توسط «دستیار» را برمی‌گرداند.

این مقدار هنگام استفاده از خدماتی مانند Google Device Actions دستگاه شما را به سرور شناسایی می کند. این ویژگی فقط پس از فراخوانی start() پر می شود.

برمی گرداند: شناسه دستگاه یک بار start() فراخوانی شد، در غیر این صورت رشته را خالی کنید.
نوع برگشت: خ
send_text_query ( query )

ارسال |پرس و جو| به دستیار طوری که گویی توسط کاربر صحبت می شود.

این کار به همان صورت عمل می‌کند که کاربر کلمه کلیدی را بیان می‌کند و یک پرس و جو ایجاد می‌کند یا پاسخ یک پرسش بعدی را بیان می‌کند.

مولفه های: query ( str ) - عبارت متنی برای ارسال به دستیار.
set_mic_mute ( is_muted )

دستیار را از گوش دادن به کلمه کلیدی باز می دارد.

به غیرفعال کردن دستیار از گوش دادن به کلمه کلیدی اجازه می دهد. این عملکردی شبیه به دکمه حریم خصوصی در پشت Google Home را ارائه می دهد.

اگر Assistant هنوز راه اندازی نشده باشد، این روش غیرفعال است.

مولفه های: is_muted ( bool ) - True از گوش دادن دستیار جلوگیری می کند و False اجازه می دهد تا دوباره شروع شود.
start ( )

«دستیار» را راه‌اندازی می‌کند که شامل گوش دادن به کلمه کلیدی می‌شود.

هنگامی که start() فراخوانی شد، دستیار پردازش داده‌ها را از منبع صوتی ALSA «پیش‌فرض» آغاز می‌کند و به کلمه کلیدی گوش می‌دهد. با این کار سایر خدمات ارائه شده توسط دستیار مانند تایمر/زنگ هشدار نیز شروع می شود. این روش فقط یک بار قابل فراخوانی است. پس از فراخوانی، دستیار تا زمانی که __exit__ فراخوانی نشود به کار خود ادامه می دهد.

برمی گرداند: صفی از رویدادها که از تغییرات در وضعیت دستیار مطلع می شود.
نوع برگشت: google.assistant.event.IterableEventQueue
start_conversation ( )

به صورت دستی مکالمه جدیدی را با دستیار شروع می کند.

شروع به ضبط گفتار کاربر و ارسال آن به Google می‌کند، مشابه آنچه وقتی «دستیار» کلمه کلیدی را می‌شنود، اتفاق می‌افتد.

اگر دستیار راه‌اندازی نشده باشد یا بی‌صدا شده باشد، این روش غیرفعال است.

stop_conversation ( )

هرگونه مکالمه فعال با دستیار را متوقف می کند.

دستیار ممکن است به درخواست کاربر گوش دهد یا پاسخ دهد. اگر مکالمه فعالی وجود نداشته باشد، این یک غیرفعال است.

کلاس 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 ثانیه از هم اکنون"

کلاس google.assistant.library.event. DeviceActionEvent ( event_type , args , **kwargs )

رویداد را گسترش می دهد تا ویژگی «اقدامات» را اضافه کند.

actions

تولید کننده دستورات برای اجرا برای دستگاه فعلی.

کلاس google.assistant.library.event. Event ( رویداد_نوع ، args ، **_ )

رویدادی که توسط دستیار ایجاد شده است.

type

EventType – نوع رویدادی که ایجاد شد.

args

dict – جفت های کلید/مقدار آرگومان مرتبط با این رویداد.

static New ( event_type , args , **kwargs )

در صورت نیاز با استفاده از یک کلاس رویداد تخصصی رویداد جدید ایجاد کنید.

مولفه های:
  • event_type ( int ) – یک شناسه عددی مربوط به یک رویداد در google.assistant.event.EventType.
  • args ( dict ) - جفت های کلید/مقدار آرگومان مرتبط با این رویداد.
  • kwargs ( dict ) - جفت های کلید/مقدار آرگومان اختیاری مخصوص یک تخصصی از کلاس Event برای یک EventType.
کلاس google.assistant.library.event. EventType

انواع رویداد

ON_ALERT_FINISHED = 11

نشان می دهد که صدای هشدار alert_type به پایان رسیده است.

مولفه های: alert_type ( AlertType ) - شناسه Enum نشان دهنده نوع هشداری است که به تازگی به پایان رسیده است.
ON_ALERT_STARTED = 10

نشان می دهد که یک هشدار شروع به پخش کرده است.

این هشدار تا زمانی که ON_ALERT_FINISHED با همان alert_type دریافت نشود ادامه خواهد داشت. فقط یک هشدار باید در هر لحظه فعال باشد.

مولفه های: alert_type ( AlertType ) - شناسه Enum که نشان دهنده نوع هشدار فعلی است.
ON_ASSISTANT_ERROR = 12

نشان می دهد که آیا کتابخانه Assistant با خطا مواجه شده است.

مولفه های: is_fatal ( bool ) - اگر True باشد، دستیار قادر به بازیابی نخواهد بود و باید دوباره راه اندازی شود.
ON_CONVERSATION_TURN_FINISHED = 9

دستیار چرخش فعلی را به پایان رساند.

این شامل پردازش درخواست کاربر و گفتن پاسخ کامل در صورت وجود است.

مولفه های: with_follow_on_turn ( bool ) - اگر درست باشد، دستیار انتظار دارد یک تعامل بعدی از کاربر داشته باشد. میکروفون مجدداً باز می شود تا کاربر بتواند به سؤال بعدی پاسخ دهد.
ON_CONVERSATION_TURN_STARTED = 1

نشان می دهد چرخش جدیدی شروع شده است.

دستیار در حال حاضر در حال گوش دادن است و منتظر درخواست کاربر است. این می تواند نتیجه شنیدن کلمه کلیدی یا start_conversation() در دستیار باشد.

ON_CONVERSATION_TURN_TIMEOUT = 2

زمان انتظار دستیار برای یک درخواست قابل تشخیص تمام شد.

این ممکن است به دلیل اشتباه کردن کلمه کلیدی باشد یا دستیار نتواند آنچه کاربر گفته است بفهمد.

ON_DEVICE_ACTION = 14

نشان می دهد که یک درخواست Device Action به دستگاه ارسال شده است.

اگر گرامر دستگاه برای ویژگی های پشتیبانی شده توسط دستگاه فعال شود، این مورد ارسال می شود. این نوع رویداد دارای یک ویژگی «عملیات» ویژه است که یک تکرار کننده یا دستورات Device Action و پارامترهای مرتبط با آنها (در صورت وجود) را برمی گرداند.

مولفه های: dict – محموله JSON رمزگشایی شده درخواست Device Action.
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 دنبال می شود

مولفه های:
  • فراداده ( دیکت ) –

    فراداده برای آهنگ بارگذاری شده. همه فیلدها تا این زمان پر نمی شوند - اگر قسمتی ناشناخته باشد شامل نمی شود. فیلدهای فراداده عبارتند از:

    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 انتقال پیدا کنیم.

مولفه های:
  • فراداده ( دیکت ) –

    متادیتا برای آهنگ پخش. اگر فیلدی ناشناخته باشد شامل نمی شود. فیلدهای فراداده عبارتند از:

    album(str): نام آلبومی که قطعه به آن تعلق دارد. album_art(str): URL برای هنر آلبوم. artist(str): هنرمندی که این آهنگ را ایجاد کرده است. duration_ms(double): طول این آهنگ بر حسب میلی ثانیه. title(str): عنوان آهنگ.
  • position_ms ( دوبل ) – موقعیت فعلی در یک آهنگ در حال پخش در میلی ثانیه از ابتدا. اگر "metadata.duration_ms" ناشناخته باشد (روی 0 تنظیم شود) این فیلد تنظیم نخواهد شد.
  • track_type ( MediaTrackType ) – نوع آهنگ پخش می شود.
ON_MEDIA_TRACK_STOP = 19

نشان می دهد که آهنگی که قبلاً پخش شده است متوقف شده است.

این معمولاً نتیجه مکث کاربر است. اگر کاربر از سر گرفته شود، آهنگ می تواند به ON_MEDIA_TRACK_PLAY برگردد.

مولفه های:
  • فراداده ( دیکت ) –

    فراداده برای مسیر متوقف شده. اگر فیلدی ناشناخته باشد شامل نمی شود. فیلدهای فراداده عبارتند از:

    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 ( bool ) - اگر True باشد، دستیار در حال حاضر به کلمه کلیدی خود گوش نمی دهد و به سؤالات کاربر پاسخ نمی دهد.
ON_NO_RESPONSE = 8

دستیار نوبت خود را با موفقیت به پایان رساند اما چیزی برای گفتن ندارد.

ON_RECOGNIZING_SPEECH_FINISHED = 5

«دستیار» گفتار شناخته شده نهایی را تعیین کرده است.

مولفه های: text ( str ) – تفسیر متن نهایی درخواست کاربر.
ON_RENDER_RESPONSE = 15

نشان می دهد که دستیار دارای خروجی متنی برای ارائه پاسخ است.

مولفه های:
  • type ( RenderResponseType ) – نوع پاسخ به رندر.
  • text ( str ) – رشته ای که برای RenderResponseType.TEXT رندر می شود.
ON_RESPONDING_FINISHED = 7

«دستیار» پاسخ صوتی را به پایان رسانده است.

ON_RESPONDING_STARTED = 6

دستیار شروع به پاسخ دادن با صدا می کند.

تا زمانی که ON_RESPONDING_FINISHED دریافت نشود، دستیار پاسخ خواهد داد.

مولفه های: is_error_response ( bool ) - True به این معنی است که یک خطای محلی TTS در حال پخش است، در غیر این صورت دستیار با یک پاسخ سرور پاسخ می دهد.
ON_START_FINISHED = 0

شروع به کار کتابخانه دستیار به پایان رسیده است.

کلاس google.assistant.library.event. IterableEventQueue ( timeout=3600 )

صف را برای افزودن یک رابط __iter__ گسترش می دهد.

offer ( رویداد )

رویدادی را برای قرار دادن در صف پیشنهاد دهید.

اگر صف در حال حاضر پر باشد، رویداد ثبت می شود اما اضافه نمی شود.

مولفه های: رویداد ( رویداد ) - رویدادی که باید سعی کنید به صف اضافه کنید.
کلاس google.assistant.library.event. MediaStateChangeEvent ( event_type , args , **_ )

رویداد را گسترش می دهد تا تجزیه «وضعیت» را اضافه کند.

کلاس 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 یا آهنگ بینابینی مربوط به یک مورد.

کلاس google.assistant.library.event. RenderResponseEvent ( event_type , args , **_ )

رویداد را گسترش می دهد تا تجزیه «response_type» را اضافه کند.

کلاس google.assistant.library.event. RenderResponseType

انواع محتوا برای ارائه

استفاده شده با ON_RENDER_RESPONSE