Package google.assistant.embedded.v1alpha1

Índice

EmbeddedAssistant

Serviço que implementa a API Google Assistant.

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

Inicia ou continua uma conversa com o serviço de assistente incorporado. Cada chamada realiza uma viagem de ida e volta, enviando uma solicitação de áudio ao serviço e recebendo a resposta de áudio. Usa streaming bidirecional para receber resultados, como o evento END_OF_UTTERANCE, ao enviar áudio.

Uma conversa é uma ou mais conexões gRPC, cada uma consistindo em várias solicitações e respostas transmitidas. Por exemplo, o usuário diz Adicionar à minha lista de compras e o assistente responde O que você quer adicionar?. A sequência das solicitações e respostas transmitidas na primeira mensagem gRPC pode ser:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

O usuário diz bagels e o assistente responde Ok, adicionei bagels à sua lista de compras. Isso é enviado como outra chamada de conexão gRPC para o método Converse, novamente com solicitações e respostas transmitidas, como:

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

Ainda que a ordem exata das respostas não seja garantida, as mensagens sequenciais ConverseResponse.audio_out sempre vão ter partes sequenciais de áudio.

Autorização

Requer o seguinte escopo OAuth:

  • https://www.googleapis.com/auth/assistant-sdk-prototype

Para mais informações, consulte o Guia de autenticação.

AudioInConfig

Especifica como processar os dados do audio_in que serão fornecidos nas próximas solicitações. Para conferir as configurações recomendadas, consulte as práticas recomendadas da API gRPC do Google Assistente.

Campos
encoding

Encoding

Obrigatório Codificação de dados de áudio enviados em todas as mensagens audio_in.

sample_rate_hertz

int32

Obrigatório Taxa de amostragem (em Hertz) dos dados de áudio enviados em todas as mensagens audio_in. Os valores válidos vão de 16.000 a 24.000, mas 16.000 é o ideal. Para melhores resultados, defina a taxa de amostragem da fonte de áudio para 16.000 Hz. Se isso não for possível, use a taxa de amostragem nativa da fonte de áudio em vez de fazer nova amostragem.

Codificação

Codificação de áudio dos dados enviados na mensagem de áudio. O áudio precisa ser de um canal (mono). O único idioma compatível é "en-US".

Enums
ENCODING_UNSPECIFIED Não especificado. Retorna o resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Amostras pouco elaboradas de 16 bits sem compactação (PCM Linear). Essa codificação não inclui cabeçalho, somente os bytes brutos de áudio.
FLAC FLAC (Free Lossless Audio Codec) é a codificação recomendada porque não tem perdas. Portanto, o reconhecimento não é comprometido e requer apenas cerca de metade da largura de banda do LINEAR16. Essa codificação inclui o cabeçalho de stream FLAC seguido pelos dados de áudio. Ele oferece suporte a amostras de 16 e 24 bits, mas nem todos os campos em STREAMINFO são compatíveis.

AudioOut

O áudio que contém a resposta do assistente à consulta. Os blocos sequenciais de dados de áudio são recebidos em mensagens ConverseResponse sequenciais.

Campos
audio_data

bytes

Somente saída: os dados de áudio que contêm a resposta do assistente à consulta. Os blocos sequenciais de dados de áudio são recebidos em mensagens ConverseResponse sequenciais.

AudioOutConfig

Especifica o formato desejado que o servidor usará quando retornar mensagens audio_out.

Campos
encoding

Encoding

Obrigatório A codificação dos dados de áudio a ser retornada em todas as mensagens audio_out.

sample_rate_hertz

int32

Obrigatório A taxa de amostragem em Hertz dos dados de áudio retornados em mensagens audio_out. Os valores válidos são: 16.000-24.000.

volume_percentage

int32

Obrigatório Configuração de volume atual da saída de áudio do dispositivo. Os valores válidos são de 1 a 100 (correspondente a 1% a 100%).

Codificação

Codificação dos dados retornados na mensagem de áudio. Todas as codificações são bytes de áudio brutos sem cabeçalho, exceto conforme indicado abaixo.

Enums
ENCODING_UNSPECIFIED Não especificado. Retorna o resultado google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Amostras pouco elaboradas de 16 bits sem compactação (PCM Linear).
MP3 Codificação de áudio MP3. A taxa de amostragem é codificada no payload.
OPUS_IN_OGG Áudio codificado em Opus unido em um contêiner ogg. O resultado será um arquivo que pode ser reproduzido de forma nativa no Android e em alguns navegadores, como o Chrome. A qualidade da codificação é consideravelmente maior do que a do MP3 e usa a mesma taxa de bits. A taxa de amostragem é codificada no payload.

ConverseConfig

Especifica como processar as mensagens ConverseRequest.

Campos
audio_in_config

AudioInConfig

Obrigatório Especifica como processar o áudio de entrada subsequente.

audio_out_config

AudioOutConfig

Obrigatório Especifica como formatar o áudio que será retornado.

converse_state

ConverseState

Obrigatório representa o estado atual da caixa de diálogo.

ConverseRequest

A mensagem de nível superior enviada pelo cliente. Os clientes precisam enviar pelo menos duas e, normalmente, várias mensagens ConverseRequest. A primeira mensagem precisa conter uma mensagem config e não pode conter dados audio_in. Todas as mensagens subsequentes precisam conter dados audio_in e não podem conter uma mensagem config.

Campos
Campo de união converse_request. Exatamente um desses campos precisa ser especificado em cada ConverseRequest. converse_request pode ser apenas de um dos tipos a seguir:
config

ConverseConfig

A mensagem config fornece informações ao reconhecedor que especificam como processar a solicitação. A primeira mensagem ConverseRequest precisa conter uma mensagem config.

audio_in

bytes

Dados de áudio a serem reconhecidos. Os blocos sequenciais de dados de áudio são enviados em mensagens ConverseRequest sequenciais. A primeira mensagem ConverseRequest não pode conter dados audio_in, e todas as mensagens ConverseRequest subsequentes precisam conter dados audio_in. Os bytes de áudio precisam ser codificados conforme especificado em AudioInConfig. O áudio precisa ser enviado aproximadamente em tempo real (16.000 amostras por segundo). Um erro será retornado se o áudio for enviado significativamente mais rápido ou mais devagar.

ConverseResponse

A mensagem de nível superior recebida pelo cliente. É feito streaming de uma ou mais mensagens ConverseResponse de volta para o cliente.

Campos
Campo de união converse_response. Exatamente um desses campos será preenchido em cada ConverseResponse. converse_response pode ser apenas de um dos tipos a seguir:
error

Status

Somente saída: se definido, retorna uma mensagem google.rpc.Status que especifica o erro para a operação. Se ocorrer um erro durante o processamento, essa mensagem será configurada e não haverá mais mensagens enviadas.

event_type

EventType

Somente saída Indica o tipo de evento.

audio_out

AudioOut

Somente saída: o áudio que contém a resposta do assistente à consulta.

result

ConverseResult

Somente saída O resultado semântico para a consulta falada do usuário.

EventType

Indica o tipo de evento.

Enums
EVENT_TYPE_UNSPECIFIED Nenhum evento especificado.
END_OF_UTTERANCE Esse evento indica que o servidor detectou o fim da fala do usuário e não espera nenhuma fala adicional. Portanto, o servidor não processará áudio adicional, ainda que possa retornar resultados adicionais posteriormente. O cliente deve parar de enviar dados de áudio adicionais, fechar a metade da conexão gRPC e aguardar quaisquer resultados adicionais até o servidor fechar a conexão gRPC.

ConverseResult

O resultado semântico para a consulta falada do usuário.

Campos
spoken_request_text

string

Somente saída A transcrição reconhecida do que o usuário disse.

spoken_response_text

string

Somente saída O texto da resposta falada do assistente. Esse valor só é retornado para uma ação IFTTT.

conversation_state

bytes

Informações de estado somente saída para o ConverseRequest subsequente. Esse valor precisa ser salvo no cliente e retornado no conversation_state com o próximo ConverseRequest. O cliente não precisa interpretar nem usar esse valor. Não é necessário salvar essas informações nas reinicializações do dispositivo.

microphone_mode

MicrophoneMode

Somente saída Especifica o modo do microfone depois que essa RPC Converse é processada.

volume_percentage

int32

Somente saída nível de volume atualizado. O valor será 0 ou omitido (indicando nenhuma alteração), a menos que um comando de voz como "Aumentar o volume" ou "Definir nível de volume 4" seja reconhecido. Nesse caso, o valor vai estar entre 1 e 100 (correspondente ao novo nível de volume de 1% a 100%). Normalmente, um cliente precisa usar esse nível de volume ao reproduzir os dados do audio_out, manter esse valor como o nível de volume atual e fornecê-lo no AudioOutConfig do próximo ConverseRequest. Alguns clientes também podem implementar outras maneiras de permitir que o nível de volume atual seja alterado, por exemplo, fornecendo um botão em que o usuário pode girar.

MicrophoneMode

Estados possíveis do microfone após a conclusão de uma RPC Converse.

Enums
MICROPHONE_MODE_UNSPECIFIED Nenhum modo especificado.
CLOSE_MICROPHONE O serviço não espera uma pergunta seguinte do usuário. O microfone precisa permanecer desativado até ser reativado.
DIALOG_FOLLOW_ON O serviço espera uma pergunta complementar do usuário. O microfone precisa ser aberto novamente quando a reprodução de AudioOut for concluída, iniciando uma nova chamada de RPC Converse para enviar o novo áudio.

ConverseState

Fornece informações sobre o estado atual da caixa de diálogo.

Campos
conversation_state

bytes

Obrigatório O valor conversation_state retornado no ConverseResponse anterior. Omita (não defina o campo) se não houver ConverseResponse anteriores. Se havia um ConverseResponse anterior, não omita esse campo. Isso encerra a conversa, e essa nova solicitação inicia uma nova.