Você está na página 1de 154

Amazon Transcribe

Guia do desenvolvedor
Amazon Transcribe Guia do desenvolvedor

Amazon Transcribe: Guia do desenvolvedor


Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's,
in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits
Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not
be affiliated with, connected to, or sponsored by Amazon.
Amazon Transcribe Guia do desenvolvedor

Table of Contents
O que é o Amazon Transcribe? ............................................................................................................ 1
Reconhecer vozes ...................................................................................................................... 2
Transcrever canais de áudio separados ......................................................................................... 2
Transcrever streaming de áudio .................................................................................................... 2
Vocabulário personalizado ........................................................................................................... 3
Você é um usuário iniciante do Amazon Transcribe? ....................................................................... 3
Como ele funciona .............................................................................................................................. 4
Entrada de voz .......................................................................................................................... 5
Transcrição de números .............................................................................................................. 5
Identificar oradores ..................................................................................................................... 7
Transcrever streaming de áudio .................................................................................................... 8
Identificação de canal ................................................................................................................. 8
Vocabulários personalizados ....................................................................................................... 10
Criar um vocabulário personalizado usando uma lista ............................................................. 11
Criar um vocabulário personalizado usando uma tabela .......................................................... 12
Conjuntos de caracteres para vocabulários personalizados ..................................................... 13
Conceitos básicos ............................................................................................................................. 30
Etapa 1: Configurar uma conta ................................................................................................... 30
Cadastre-se na AWS ......................................................................................................... 30
Criar um usuário do IAM .................................................................................................... 31
Próxima etapa .................................................................................................................. 31
Etapa 2: Configurar aAWS CLI ................................................................................................... 31
Próxima etapa .................................................................................................................. 32
Etapa 3: conceitos básicos do uso do console .............................................................................. 32
Como criar um trabalho de transcrição ................................................................................. 32
Como exibir um trabalho de transcrição ............................................................................... 33
Etapa 4: Conceitos básicos do uso da API ................................................................................... 36
Conceitos básicos (AWS CLI) ............................................................................................. 36
Conceitos básicos (SDK for Python) .................................................................................... 38
Etapa 5: Conceitos básicos do streaming de áudio ........................................................................ 40
Transcrição de streaming ................................................................................................................... 44
Codificação de fluxo de evento ................................................................................................... 46
Uso de streaming com WebSocket .............................................................................................. 47
Adicionar uma política para solicitações WebSocket à sua função do IAM .................................. 48
Criação de uma Pre-Signed URL ........................................................................................ 48
Manipular a resposta de atualização do WebSocket ............................................................... 52
Criar uma solicitação de streaming WebSocket ..................................................................... 52
Manipular uma resposta de streaming WebSocket ................................................................. 53
Manipular erros de streaming WebSocket ............................................................................. 53
Uso de streaming com HTTP/2 ................................................................................................... 54
Solicitação de streaming .................................................................................................... 54
Resposta de streaming ...................................................................................................... 57
Exemplo de solicitação e resposta ...................................................................................... 58
Cliente de nova tentativa HTTP/2 ........................................................................................ 60
Uso do cliente de nova tentativa HTTP/2 .............................................................................. 66
Segurança ....................................................................................................................................... 69
Proteção de dados .................................................................................................................... 69
Criptografia em repouso ..................................................................................................... 70
Criptografia em trânsito ...................................................................................................... 70
Gerenciamento de chaves .................................................................................................. 70
Identity and Access Management ................................................................................................ 71
Público ............................................................................................................................ 72
Autenticação com identidades ............................................................................................. 72
Gerenciamento do acesso usando políticas .......................................................................... 74

iii
Amazon Transcribe Guia do desenvolvedor

Como o Amazon Transcribe funciona com o IAM .................................................................. 76


Exemplos de políticas baseadas em identidade ..................................................................... 77
Solução de problemas ....................................................................................................... 81
Monitoramento do Amazon Transcribe ......................................................................................... 83
Monitorar o Amazon Transcribe com o CloudTrail .................................................................. 83
Eventos do CloudWatch ..................................................................................................... 86
Validação de conformidade ........................................................................................................ 88
Resiliência ............................................................................................................................... 88
Segurança da infraestrutura ....................................................................................................... 89
Diretrizes e limites ............................................................................................................................ 90
Regiões compatíveis ................................................................................................................. 90
Limitação ................................................................................................................................. 90
Diretrizes ................................................................................................................................. 90
Limites .................................................................................................................................... 90
Histórico do documento ..................................................................................................................... 91
Referência da API ............................................................................................................................ 94
Actions .................................................................................................................................... 94
Amazon Transcribe Service ................................................................................................ 94
Amazon Transcribe Streaming Service ............................................................................... 121
Data Types ............................................................................................................................ 125
Amazon Transcribe Service .............................................................................................. 126
Amazon Transcribe Streaming Service ............................................................................... 137
Common Errors ...................................................................................................................... 146
Common Parameters ............................................................................................................... 147
AWS Glossary ................................................................................................................................ 150

iv
Amazon Transcribe Guia do desenvolvedor

O que é o Amazon Transcribe?


O Amazon Transcribe usa tecnologias de machine learning avançadas para reconhecer a fala em
arquivos de áudio e transcrevê-la em texto. É possível usar o Amazon Transcribe para converter áudio em
texto e para criar aplicativos que incorporam o conteúdo de arquivos de áudio. Por exemplo, é possível
transcrever a faixa de áudio de uma gravação de vídeo para criar legendas para o vídeo.

É possível usar o Amazon Transcribe para transcrever os seguintes idiomas para texto:

• Árabe padrão moderno (ar-SA)


• Mandarim (China Continental) (ZH-CN)
• Inglês australiano (en-AU)
• Inglês britânico (en-GB)
• Inglês indiano (es-IN)
• Inglês EUA (en-US)
• Francês (fr-FR)
• Francês canadense (fr-CA)
• Alemão (de-DE)
• Hindi indiano (hi-IN)
• Italiano (it-IT)
• Coreano (ko-KR)
• Português do Brasil (pt-BR)
• Russo (ru-RU)
• Espanhol (es-ES)
• Espanhol dos EUA (es-US)

Você pode transcrever o áudio de streaming nos seguintes idiomas:

• Inglês australiano (en-AU)


• Inglês britânico (en-GB)
• Inglês EUA (en-US)
• Francês (fr-FR)
• Francês canadense (fr-CA)
• Espanhol dos EUA (es-US)

É possível usar o Amazon Transcribe com outros serviços da AWS para criar aplicativos. Por exemplo, é
possível:

• Use o Amazon Transcribe para converter voz em texto, enviar o texto para o Amazon Translate para
traduzi-lo para outro idioma e enviar o texto traduzido para o Amazon Polly para leitura em voz alta do
texto traduzido.
• Use o Amazon Transcribe para transcrever gravações de chamadas de atendimento ao cliente para
análise. Depois de transcrever uma gravação, envie a transcrição para o Amazon Comprehend para
identificar palavras-chave, tópicos ou sentimentos.

1
Amazon Transcribe Guia do desenvolvedor
Reconhecer vozes

• Use o Amazon Transcribe para transcrever transmissões ao vivo, como as de televisão, para fornecer
legendas em tempo real.

Para usar o Amazon Transcribe, armazene o arquivo de áudio em um bucket do Amazon S3. A saída do
trabalho de transcrição também é armazenada em um bucket do S3. O conteúdo entregue aos buckets do
Amazon S3 podem conter conteúdo do cliente. Para obter mais informações sobre como remover dados
confidenciais, consulte Como eu faço para esvaziar um bucket do S3? ou Como eu faço para excluir um
bucket do S3?

Reconhecer vozes
O Amazon Transcribe pode identificar cada orador em um clipe de áudio, uma técnica conhecida como
diarização ou identificação do orador. Quando você ativa a identificação do orador, o Amazon Transcribe
inclui um atributo que identifica cada orador no clipe de áudio. Você pode usar a identificação do orador
para:

• identificar o cliente e o representante de suporte em uma gravação de chamada de atendimento ao


cliente
• identificar personagens para legendas
• identificar o orador e os autores das perguntas em uma coletiva de imprensa ou palestra gravada

Você pode especificar o número de vozes que deseja que o Amazon Transcribe reconheça em um clipe de
áudio.

Transcrever canais de áudio separados


Para criar uma transcrição para cada canal ou streaming único de som gravado em um arquivo de áudio,
use a identificação de canal. Com a identificação de canal, o Amazon Transcribe retorna duas ou mais
transcrições: uma transcrição combinada de todos os canais de áudio e transcrição de cada canal de
áudio.

Use a identificação de canal quando o áudio estiver em vários canais. Por exemplo, use identificação de
canal:

• Quando a gravação tiver um representante do atendimento ao cliente em um canal e um cliente em


outro
• Ao transcrever um podcast em que o apresentador está gravado em um canal e o convidado em outro

Para obter mais informações sobre a identificação de canal, consulte Identificação de canal (p. 8).

Transcrever streaming de áudio


É possível usar o Amazon Transcribe para transcrever streaming de áudio em tempo real. Você envia para
o Amazon Transcribe um streaming de áudio, e o Amazon Transcribe retorna um streaming de objetos
JSON com a transcrição do áudio.

Para obter mais informações sobre como processar streaming de áudio, consulte Transcrição de
streaming (p. 44).

2
Amazon Transcribe Guia do desenvolvedor
Vocabulário personalizado

Vocabulário personalizado
Crie um vocabulário personalizado para ajudar o Amazon Transcribe a reconhecer palavras que são
específicas do seu caso de uso e melhorar a precisão na conversão de fala em texto. Por exemplo, você
pode criar um vocabulário personalizado que inclui palavras e expressões específicas do setor.

Use um vocabulário personalizado para ajudar o Amazon Transcribe a reconhecer:

• palavras que não estão sendo reconhecidas


• palavras desconhecidas que são específicas do seu domínio

Para obter mais informações sobre a criação de um vocabulário personalizado, consulte Vocabulários
personalizados (p. 10).

Você é um usuário iniciante do Amazon


Transcribe?
Caso seja um usuário iniciante, recomendamos que você leia as seções a seguir em ordem:

1. Como o Amazon Transcribe funciona (p. 4)—Apresenta o Amazon Transcribe.


2. Conceitos básicos do Amazon Transcribe (p. 30) — Explica como configurar sua conta da AWS e
usar o Amazon Transcribe.
3. Referência da API (p. 94) — Contém a documentação de referência das operações do Amazon
Transcribe.

3
Amazon Transcribe Guia do desenvolvedor

Como o Amazon Transcribe funciona


O Amazon Transcribe analisa os arquivos de áudio que contêm voz e usa técnicas avançadas de machine
learning para transcrever os dados de voz em texto. Você pode usar a transcrição como você faria com
qualquer documento de texto.

Para transcrever um arquivo de áudio, o Amazon Transcribe usa três operações:

• StartTranscriptionJob (p. 114) – Inicia um trabalho assíncrono para transcrever a fala de um arquivo de
áudio em texto.
• ListTranscriptionJobs (p. 108) – retorna uma lista de trabalhos de transcrição que foram iniciados. Você
pode especificar o status dos trabalhos que deseja que a operação retorne. Por exemplo, você pode
obter uma lista de todos os trabalhos pendentes ou uma lista de trabalhos concluídos.
• GetTranscriptionJob (p. 103) – retorna o resultado de um trabalho de transcrição. A resposta contém
um link para um arquivo JSON que contém os resultados.

Para transcrever um streaming de áudio em texto, o Amazon Transcribe fornece uma operação:

• StartStreamTranscription (p. 122) – inicia um fluxo de HTTP/2 bidirecional onde o áudio é transmitido
para o Amazon Transcribe e os resultados da transcrição são transmitidos para o seu aplicativo.

Você também pode iniciar um streaming com protocolo WebSocket para enviar áudios ao
Amazon Transcribe. Para mais informações, consulte Usar streaming do Amazon Transcribe com
WebSockets (p. 47).

É possível usar o Amazon Transcribe para criar e gerenciar vocabulários personalizados para sua solução.
Um vocabulário personalizado fornece ao Amazon Transcribe mais informações sobre como processar a
fala em um clipe de áudio.

• CreateVocabulary (p. 95) – cria um vocabulário personalizado que pode ser usado nos trabalhos de
transcrição.
• DeleteVocabulary (p. 101) – exclui um vocabulário personalizado de sua conta.
• GetVocabulary (p. 105) – obtém informações sobre um vocabulário personalizado e um URL que você
pode usar para fazer download do conteúdo de um vocabulário.
• ListVocabularies (p. 111) – obtém uma lista de vocabulários personalizados em sua conta.
• UpdateVocabulary (p. 118) – atualiza um vocabulário existente.

É possível transcrever a fala em qualquer um dos seguintes idiomas:

• Árabe padrão moderno (ar-SA)


• Mandarim (China Continental) (ZH-CN)
• Inglês australiano (en-AU)
• Inglês britânico (en-GB)
• Inglês indiano (es-IN)
• Inglês EUA (en-US)
• Francês (fr-FR)
• Francês canadense (fr-CA)

4
Amazon Transcribe Guia do desenvolvedor
Entrada de voz

• Alemão (de-DE)
• Hindi indiano (hi-IN)
• Italiano (it-IT)
• Coreano (ko-KR)
• Português do Brasil (pt-BR)
• Russo (ru-RU)
• Espanhol (es-ES)
• Espanhol dos EUA (es-US)

Você pode usar o streaming de transcrição para os seguintes idiomas:

• Inglês australiano (en-AU)


• Inglês britânico (en-GB)
• Inglês EUA (en-US)
• Francês (fr-FR)
• Francês canadense (fr-CA)
• Espanhol dos EUA (es-US)

Tópicos
• Entrada de voz (p. 5)
• Transcrição de números (p. 5)
• Identificar oradores (p. 7)
• Transcrever streaming de áudio (p. 8)
• Identificação de canal (p. 8)
• Vocabulários personalizados (p. 10)

Entrada de voz
Para transcrever um arquivo de áudio, você usa um trabalho de transcrição. O arquivo é armazenado
como um objeto em um bucket do Amazon S3. O arquivo de entrada deve estar:

• No formato de arquivo FLAC, MP3, MP4 ou WAV


• Menos de 4 horas de duração ou menos de 2 GB de dados de áudio

É necessário especificar o idioma e o formato do arquivo de entrada.

Para obter os melhores resultados:

• Use um formato sem perda, como FLAC ou WAV, com a codificação de PCM de 16 bits.
• Use uma taxa de amostragem de 8000 Hz para áudio de telefone.

Transcrição de números
Quando você está transcrevendo áudio em inglês dos EUA, inglês australiano, inglês britânico ou inglês
indiano usando a operação StartTranscriptionJob (p. 114), os números são transcritos como dígitos,

5
Amazon Transcribe Guia do desenvolvedor
Transcrição de números

em vez de palavras. Para a transcrição de streaming, os números são transcritos como dígitos apenas
em inglês dos EUA e inglês britânico. Por exemplo, o número falado "mil duzentos e quarenta e dois" é
transcrito como "1242".

Em todos os outros idiomas, os números são transcritos em forma de palavras.

Os números são transcritos de acordo com as seguintes regras:

Regra Descrição

Converter números cardinais maiores que 10 em • "Cinquenta e cinco" > 55


numerais • "cem" > 100
• "Mil e trinta um" > 1031
• “Cento e vinte e três milhões, quatrocentos e
cinquenta e seis mil, setecentos e oitenta e
nove” > 123.456.789

Converter números cardinais seguidos de “milhão” • “cem milhões” > 100 milhões
ou “bilhão” em numerais seguidos de uma palavra • “um bilhão” > 1 bilhão
quando “milhão” ou “bilhão” não for seguido por um
• “dois vírgula três milhões” > 2,3 milhões
número.

Converter números ordinais maiores que 10 em • "Quadragésimo terceiro" > 43º


números • "vigésima sexta avenida" > 26ª avenida

Converter frações no respectivo formato numérico. • "um quarto" > 1/4


• "três dezesseis avos" > 3/16
• "um meio" > 1/2
• "um centésimo" > 1/100

Converter números menores que 10 dígitos se • "três quatro cinco" > 345
houver mais de um em uma linha. • "Meu número de telefone é quatro dois
cinco cinco cinco cinco um dois um dois" >
4255551212

Os decimais são indicados por "ponto". • "trezentos e três ponto cinco" > 303.5
• "três ponto vinte e três" > 3.23
• "zero ponto quatro" > 0.4
• "zero ponto três" > 0.3

Converter a palavra "por cento" após um número • "vinte e três por cento" > 23%
em um sinal de porcentagem (%). • "vinte e três ponto quatro cinco por cento" >
23.45%

Converter as palavras "dólar", "dólar americano" ou • "um dólar e quinze centavos" > $ 1,15
"USD" após um número em um cifrão ($) antes do • “vinte e três USD” > $ 23
número.
• “vinte e três dólares australianos” > $ 23

Converter as palavras “libras”, “libras esterlinas” ou • “vinte e três libras” > £ 23


“GDB” após um número em sinal de libra (£) antes • “Eu tenho duas mil libras” > Eu tenho £ 2.000
do número.
• “cinco libras e trinta e três centavos” > £ 5,33

Converter as palavras “rúpias”, “rúpias indianas” • “vinte e três rúpias” > #23
ou “INR” após um número no símbolo de rúpia (#) • “cinquenta rúpias e trinta paisas” > # 50,30
antes do número.

6
Amazon Transcribe Guia do desenvolvedor
Identificar oradores

Regra Descrição

Converter horas em números. • "sete a m do horário padrão do leste" > 7 am do


horário padrão do leste
• "doze e trinta p m" > 12:30 p.m:

Combinar anos expressos como dois dígitos em • "mil novecentos e sessenta e dois" > 1962
quatro. • "o ano é dois mil e doze" > o ano é 2012
Válido somente para os séculos 20, 21 e 22. • "dois mil e dezenove" > 2019
• "dois mil cento e trinta" > 2130

Converter datas em números. • "quinto dia de maio de dois mil e doze" > 5 de
maio de 2012
• "cinco de maio de dois mil e doze" > 5 de maio
de 2012
• "cinco maio dois mil e doze" > 5 de maio de 2012

Separar intervalos de números pela palavra "a". • "vinte e três a trinta sete" > 23 a 37

Identificar oradores
É possível configurar o Amazon Transcribe para identificar os diferentes oradores em um clipe de áudio,
um processo conhecido como diarização ou identificação do orador. Quando você habilita a identificação
do orador, o Amazon Transcribe marca cada fragmento com o orador identificado.

Você pode especificar que o Amazon Transcribe deve identificar entre 2 e 10 oradores no clipe de áudio.
Você obtém o melhor desempenho quando o número de oradores que pede para identificar corresponde
ao número de oradores no áudio de entrada.

Para ativar a identificação do orador, defina os campos MaxSpeakerLabels e ShowSpeakerLabels do


campo Settings quando você fizer uma chamada para a operação StartTranscriptionJob (p. 114). Você
deve definir ambos os campos ou o Amazon Transcribe retornará uma exceção.

Quando o Amazon Transcribe encerra um trabalho de transcrição, ele cria um arquivo JSON que contém
os resultados e salva o arquivo em um bucket do S3. O arquivo é identificado por URI específico do
usuário. Use o URI para obter os resultados.

A seguir encontra-se o arquivo JSON de um pequeno arquivo de áudio:

{
"jobName": "job ID",
"accountId": "account ID",
"results": {
"transcripts": [{
"transcript": "Professional answer."
}],
"speaker_labels": {
"speakers": 1,
"segments": [{
"start_time": "0.000000",
"speaker_label": "spk_0",
"end_time": "1.430",
"items": [{
"start_time": "0.100",
"speaker_label": "spk_0",
"end_time": "0.690"

7
Amazon Transcribe Guia do desenvolvedor
Transcrever streaming de áudio

}, {
"start_time": "0.690",
"speaker_label": "spk_0",
"end_time": "1.210"
}]
}]
},
"items": [{
"start_time": "0.100",
"end_time": "0.690",
"alternatives": [{
"confidence": "0.8162",
"content": "Professional"
}],
"type": "pronunciation"
}, {
"start_time": "0.690",
"end_time": "1.210",
"alternatives": [{
"confidence": "0.9939",
"content": "answer"
}],
"type": "pronunciation"
}, {
"alternatives": [{
"content": "."
}],
"type": "punctuation"
}]
},
"status": "COMPLETED"
}

Transcrever streaming de áudio


A transcrição de streaming pega um streaming dos dados de áudio e os transcreve em tempo real.
Ela usa fluxos de HTTP/2 ou WebSocket para que os resultados da transcrição sejam retornados ao
aplicativo enquanto você envia mais áudios ao Amazon Transcribe. Use a transcrição de streaming quando
quiser disponibilizar os resultados de uma transcrição de áudio ao vivo imediatamente, ou quando quiser
processar um arquivo de áudio enquanto ele é transcrito.

Você pode usar o streaming de transcrição com os seguintes idiomas:

• Inglês britânico (en-GB)


• Inglês EUA (en-US)
• Francês (fr-FR)
• Francês canadense (fr-CA)
• Espanhol dos EUA (es-US)

Para saber mais, consulte Transcrição de streaming (p. 44).

Identificação de canal
Quando um arquivo de áudio tiver vários canais que você deseja transcrever em transcrições separadas
com a identificação do canal que contém a fala, use a identificação de canal. Por exemplo, se você tiver

8
Amazon Transcribe Guia do desenvolvedor
Identificação de canal

um representante do atendimento ao cliente em um canal e um cliente em outro, use a identificação de


canal para criar uma transcrição identificada por cada canal e uma única transcrição que os combina.

O Amazon Transcribe divide o arquivo de áudio em vários canais e transcreve os canais separadamente.
Após transcrever todos os canais, o Amazon Transcribe também mescla as transcrições para criar uma
única transcrição. Ele retorna todas as transcrições em um único arquivo de resultado.

As falas dos oradores são ordenadas pela hora de início. Uma fala é uma unidade de voz no canal de
áudio que é normalmente separada de outras falas por silêncio. Se uma fala em um canal se sobrepor a
outra em outro canal, o Amazon Transcribe vai ordená-las na transcrição pela hora de início. As falas que
se sobrepõem no áudio de entrada não se sobrepõem na saída da transcrição.

É possível habilitar a identificação de canal no console do Amazon Transcribe ou com a API. No


console, selecione Channel identification (Identificação de canal) ao criar o trabalho de transcrição.
Ao usar a API, defina o sinalizador ChannelIdentification quando chamar a operação
StartTranscriptionJob (p. 114).

Veja a seguir a saída abreviada para uma conversa em dois canais:

{
"jobName": "job id",
"accountId": "account id",
"results": {
"transcripts": [
{
"transcript": "When you try ... It seems to ..."
}
],
"channel_labels": {
"channels": [
{
"channel_label": "ch_0",
"items": [
{
"start_time": "12.282",
"end_time": "12.592",
"alternatives": [
{
"confidence": "1.0000",
"content": "When"
}
],
"type": "pronunciation"
},
{
"start_time": "12.592",
"end_time": "12.692",
"alternatives": [
{
"confidence": "0.8787",
"content": "you"
}
],
"type": "pronunciation"
},
{
"start_time": "12.702",
"end_time": "13.252",
"alternatives": [
{
"confidence": "0.8318",
"content": "try"
}

9
Amazon Transcribe Guia do desenvolvedor
Vocabulários personalizados

],
"type": "pronunciation"
},
Transcription abbreviated
]
},
{
"channel_label": "ch_1",
"items": [
{
"start_time": "12.379",
"end_time": "12.589",
"alternatives": [
{
"confidence": "0.5645",
"content": "It"
}
],
"type": "pronunciation"
},
{
"start_time": "12.599",
"end_time": "12.659",
"alternatives": [
{
"confidence": "0.2907",
"content": "seems"
}
],
"type": "pronunciation"
},
{
"start_time": "12.669",
"end_time": "13.029",
"alternatives": [
{
"confidence": "0.2497",
"content": "to"
}
],
"type": "pronunciation"
},
Transcription abbreviated
]
}
}

Vocabulários personalizados
Tópicos
• Criar um vocabulário personalizado usando uma lista (p. 11)
• Criar um vocabulário personalizado usando uma tabela (p. 12)
• Conjuntos de caracteres para vocabulários personalizados (p. 13)

Você pode fornecer ao Amazon Transcribe mais informações sobre como processar a fala em seu arquivo
de entrada criando um vocabulário personalizado. Um vocabulário personalizado é uma lista de palavras
específicas que você deseja que o Amazon Transcribe reconheça na entrada de áudio. São geralmente
palavras e expressões específicas do domínio, palavras que o Amazon Transcribe não está reconhecendo
ou nomes próprios.

10
Amazon Transcribe Guia do desenvolvedor
Criar um vocabulário personalizado usando uma lista

Vocabulários personalizados funcionam melhor quando usados para atingir palavras ou frases específicas.
Recomendamos que você crie pequenos vocabulários separados personalizados para gravações de
áudio específicos em vez de criar um único vocabulário com muitos termos para usar em todas as suas
gravações. É possível ter até 100 vocabulários na sua conta. O limite de tamanho de um vocabulário
personalizado é 50 Kb.

Você especifica o vocabulário personalizado em um arquivo de texto. Você pode especificar uma lista
de palavras no vocabulário, ou uma tabela de quatro colunas que oferece a você mais controle sobre a
entrada e a saída das palavras no vocabulário personalizado.

Para obter mais informações sobre a criação de vocabulário personalizado, consulte Criar um
vocabulário personalizado usando uma lista (p. 11) e Criar um vocabulário personalizado usando uma
tabela (p. 12).

Para criar um vocabulário personalizado, use a operação CreateVocabulary (p. 95) ou o console
do Amazon Transcribe. Após enviar a solicitação CreateVocabulary, o Amazon Transcribe
processará o vocabulário. Para ver o status de processamento do vocabulário, use o console ou a
GetVocabulary (p. 105) operação.
Note

Se você estiver fazendo upload de um vocabulário personalizado usando o console do Amazon


Transcribe, você deve usar uma lista de vocabulário em vez de uma tabela. Para usar o console
para criar um vocabulário personalizado usando uma tabela de vocabulário, o arquivo de origem
deve estar em um bucket do Amazon S3.

Para usar o vocabulário personalizado, defina o campo VocabularyName do campo Settings ao


chamar a operação StartTranscriptionJob (p. 114) ou escolha o vocabulário no console ao criar o
trabalho de transcrição.

Criar um vocabulário personalizado usando uma lista


Você pode criar um vocabulário personalizado usando uma lista de palavras ou frases em um arquivo de
texto. Você pode colocar cada palavra em sua própria linha ou inserir várias palavras em uma única linha,
separando as palavras ou frases entre si com uma vírgula.

Cada entrada deve conter:

• Menos de 256 caracteres, incluindo hifens


• Apenas caracteres do conjunto de caracteres permitidos

Para conjuntos de caracteres válidos, consulte Conjuntos de caracteres para vocabulários


personalizados (p. 13).

Se uma entrada na lista for uma frase, separe as palavras da frase com um hífen. Por exemplo, se a frase
for Los Angeles, você deve inseri-la no arquivo como Los-Angeles.

Insira acrônimos ou outras palavras cujas letras devem ser pronunciadas individualmente como letras
únicas separadas por pontos, como A.B.C. ou F.B.I.. Para especificar a forma plural de um acrônimo,
como "ABCs", separe o "s" do acrônimo com um hífen: A.B.C.-s. É possível usar letras maiúsculas ou
minúsculas para inserir um acrônimo. Somente inglês dos EUA (en-US) oferece suporte a acrônimos.

O exemplo a seguir mostra um arquivo de entrada com as palavras do vocabulário e frases em linhas
separadas:

Los-Angeles
F.B.I.
Etienne

11
Amazon Transcribe Guia do desenvolvedor
Criar um vocabulário personalizado usando uma tabela

O exemplo a seguir mostra um arquivo de entrada com as palavras do vocabulário e frases em uma única
linha, separadas por vírgulas:

Los-Angeles,F.B.I.,Etienne

Criar um vocabulário personalizado usando uma


tabela
Você pode criar um vocabulário personalizado criando uma tabela em um arquivo de texto. Cada linha na
tabela é uma palavra ou frase seguida pelos campos opcionais IPA, SoundsLike, e DisplayAs. Cada
campo deve conter:

• Menos de 256 caracteres, incluindo hifens


• Apenas caracteres do conjunto de caracteres permitidos

Para conjuntos de caracteres válidos, consulte Conjuntos de caracteres para vocabulários


personalizados (p. 13)

Coloque cada palavra ou frase em seu arquivo de texto em uma linha separada. Separe os campos com
caracteres TAB. Salve o arquivo com a extensão .txt em um bucket do Amazon S3 na mesma região em
que você está chamando a API.

Os exemplos a seguir são arquivos de entrada em formato de texto. Os exemplos usam espaços para
alinhar as colunas. Seus arquivos de entrada devem usar caracteres TAB para separar as colunas. Inclua
espaços somente nas colunas DisplayAs e IPA. Se você copiar estes exemplos, remova os espaços
extras entre as colunas e substitua “[TAB]” por um caractere TAB.

Phrase [TAB]IPA [TAB]SoundsLike[TAB]DisplayAs


Los-Angeles[TAB] [TAB] [TAB]Los Angeles
F.B.I. [TAB]ɛ f b i aɛ[TAB] [TAB]FBI
Etienne [TAB] [TAB]eh-tee-en [TAB]

As colunas podem ser inseridas em qualquer ordem. A seguir estão estruturas também válidas para o
arquivo de entrada de vocabulário personalizado.

Phrase [TAB]SoundsLike[TAB]IPA [TAB]DisplayAs


Los-Angeles[TAB] [TAB] [TAB]Los Angeles
F.B.I [TAB] [TAB]ɛ f b i aɛ[TAB]FBI
Etienne [TAB]eh-tee-en [TAB] [TAB]

DisplayAs [TAB]SoundsLike[TAB]IPA [TAB]Phrase


Los Angeles[TAB] [TAB] [TAB]Los-Angeles
FBI [TAB] [TAB]ɛ f b i aɛ[TAB]F.B.I.
[TAB]eh-tee-en [TAB] [TAB]Etienne

• Frase – A palavra ou frase que deve ser reconhecida.

Se a entrada for uma frase, separe as palavras com um hífen (-). Por exemplo, digite Los Angeles
como Los-Angeles.

Insira acrônimos ou outras palavras cujas letras devem ser pronunciadas individualmente como letras
únicas seguidas por pontos, como A.B.C. ou F.B.I.. Para especificar a forma plural de um acrônimo,

12
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

como "ABCs", separe o "s" do acrônimo com um hífen: "A.B.C.-s". É possível usar letras maiúsculas
ou minúsculas para inserir um acrônimo.

O campo Phrase é obrigatório. Você pode usar qualquer um dos caracteres permitidos para o idioma
de entrada. Para ver a lista de caracteres permitidos, consulte cada idioma. Se você não especificar o
campo DisplayAs, o Amazon Transcribe usa o conteúdo do campo Phrase no arquivo de saída.
• AFI – para especificar a pronúncia da palavra ou frase, você pode incluir caracteres no Alfabeto Fonético
Internacional (AFI) nesse campo. O campo IPA não pode conter espaços no início nem no final, e você
deve usar um único espaço para separar cada fonema na entrada. Por exemplo, em inglês, a expressão
Los-Angeles seria inserida como l ɔ s æ n ɔ ɔ l ɔ s. A frase F.B.I. seria inserida como
ɔ f b i aɔ.

Se você não especificar o conteúdo do campo IPA, você deve incluir um campo IPA em branco. Se
você especificar o campo IPA, você não pode especificar o campo SoundsLike.

Para obter uma lista de caracteres do AFI permitidos para um idioma específico, consulte a tabela para
cada idioma.
• SoundsLike – Você pode quebrar uma palavra ou frase em partes menores e fornecer uma pronúncia
para cada parte usando a ortografia padrão do idioma para imitar o som da palavra. Por exemplo, em
inglês, você pode fornecer dicas de pronúncia para a frase Los-Angeles desta forma: loss-ann-
gel-es. A dica para a palavra Etienne teria a seguinte aparência: eh-tee-en. Você separa cada
parte da dica com um hífen (-).

Se você não especificar o campo SoundsLike, você deve incluir um campo SoundsLike em branco.
Se você especificar o campo SoundsLike, você não pode especificar o campo IPA.

Você pode usar qualquer um dos caracteres permitidos para o idioma de entrada. Para ver a lista de
caracteres permitidos, consulte cada idioma.
• DisplayAs – Define como a palavra ou frase fica na saída. Por exemplo, se a palavra ou frase for Los-
Angeles, você poderá especificar a forma de exibição como "Los Angeles" para que o hífen não esteja
presente na saída.

Se você não especificar o campo DisplayAs, o Amazon Transcribe usará o campo Phrase do arquivo
de entrada na saída.

Você pode usar qualquer caractere UTF-8 no campo DisplayAs.

Conjuntos de caracteres para vocabulários


personalizados
O Amazon Transcribe limita os caracteres que podem ser usados para criar vocabulários personalizados.
Você pode usar os seguintes conjuntos de caracteres para cada idioma.

Tópicos
• Conjunto de caracteres árabes (p. 14)
• Conjunto de caracteres chineses (p. 15)
• Conjunto de caracteres em inglês (p. 16)
• Conjunto de caracteres em francês (p. 17)
• Conjunto de caracteres em alemão (p. 19)
• Conjunto de caracteres hindi (p. 20)
• Conjunto de caracteres em italiano (p. 22)
• Conjunto de caracteres em coreano (p. 24)

13
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

• Conjunto de caracteres em português (p. 24)


• Conjunto de caracteres em russo (p. 26)
• Conjunto de caracteres em espanhol (p. 28)

Conjunto de caracteres árabes


Para vocabulários personalizados em árabe, você pode usar os seguintes caracteres Unicode nos campos
Phrase e SoundsLike:

Caractere Código Caractere Código

‫ء‬ 0621 ‫س‬ 0633

‫آ‬ 0622 ‫ش‬ 0634

‫أ‬ 0623 ‫ص‬ 0635

‫ؤ‬ 0624 ‫ض‬ 0636

‫إ‬ 0625 ‫ط‬ 0637

‫ئ‬ 0626 ‫ظ‬ 0638

‫ا‬ 0627 ‫ع‬ 0639

‫ب‬ 0628 ‫غ‬ 063A

‫ة‬ 0629 ‫ف‬ 0641

‫ت‬ 062A ‫ق‬ 0642

‫ث‬ 062B ‫ك‬ 0643

‫ج‬ 062C ‫ل‬ 0644

‫ح‬ 062D ‫م‬ 0645

‫خ‬ 062E ‫ن‬ 0646

‫د‬ 062F ‫ه‬ 0647

‫ذ‬ 0630 ‫و‬ 0648

‫ر‬ 0631 ‫ى‬ 0649

‫ز‬ 0632 ‫ي‬ 064A

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada de vocabulário:

Caractere Código Caractere Código

a 0061 uː 0075 02D0

aː 0061 02D0 w 0077

aj 0061 006A x 0078

14
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

aw 0061 0077 z 007A

b 0062 zˤ 007A 02E4

d 0064 ð 00F0

dˤ 0064 02E4 ð` 00F0 0060

f 0066 ðˤ 00F0 02E4

h 0068 ħ 0127

i 0069 ɖ 0256

iː 0069 02D0 ɣ 0263

j 006A ɪ 026A

k 006B ɫ 026B

l 006C ɭ 026D

m 006D ʂ 0282

n 006E ʃ 0283

p 0070 ʈ 0288

q 0071 ʒ 0292

r 0072 ʔ 0294

s 0073 ʔ` 0294 0060

sˤ 0073 02E4 ʕ 0295

t 0074 θ 03B8

tˤ 0074 02E4 χ 03C7

u 0075    

Conjunto de caracteres chineses


Para vocabulários personalizados chineses, o campo Phrase pode usar qualquer um dos caracteres
listados no arquivo a seguir no GitHub.

• chinese-character-set.txt

O campo SoundsLike pode conter as sílabas pinyin listadas no arquivo a seguir no GitHub.

• pinyin-set.txt

Quando você usar sílabas pinyin no campo SoundsLike, separe-as com um hífen (-).

O Amazon Transcribe representa os quatro tons em chinês mandarim usando números. A tabela a seguir
mostra como as marcas de tom são mapeadas para a palavra “ma“.

15
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Tom Marca de tom Número do tom

Tom 1 mā ma1

Tom 2 má ma2

Tom 3 mǎ ma3

Tom 4 mà ma4

Os vocabulários personalizados chineses não usam o campo IPA, mas você ainda deve incluir o
cabeçalho IPA na tabela de vocabulário.

Veja a seguir um exemplo de arquivo de entrada em formato de texto. O exemplo usa espaços para alinhar
as colunas. Seus arquivos de entrada devem usar caracteres TAB para separar as colunas. Inclua espaços
apenas na coluna DisplayAs.

Phrase SoundsLike IPA DisplayAs


ɛɛ kang1-jian4
ɛɛ qian3-ze2
ɛɛɛɛ guo2-fang2-da4-chen2
ɛɛɛɛɛ shi4-jie4-bo4-lan3-hui4 ɛɛɛ

Conjunto de caracteres em inglês


Para vocabulários personalizados em inglês, você pode usar os seguintes caracteres nos campos Phrase
e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)
• - (hífen)
• . (ponto final)

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada de vocabulário:

Caractere Código Caractere Código

aʊ 0061 028A w 0077

aɪ 0061 026A z 007A

b 0062 æ 00E6

d 0064 ð 00F0

eɪ 0065 026A ŋ 014B

f 0066 ɑ 0251

g 0067 ɔ 0254

h 0068 ɔɪ 0254 026A

16
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

i 0069 ə 0259

j 006A ɛ 025B

k 006B ɝ 025D

l 006C ɡ 0261

l̩ 006C 0329 ɪ 026A

m 006D ɹ 0279

n 006E ʃ 0283

n̩ 006E 0329 ʊ 028A

oʊ 006F 028A ʌ 028C

p 0070 ʍ 028D

s 0073 ʒ 0292

t 0074 ʤ 02A4

u 0075 ʧ 02A7

v 0076 θ 03B8

Conjunto de caracteres em francês


Para vocabulários personalizados em francês, você pode usar os seguintes caracteres nos campos
Phrase e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)
• - (hífen)
• . (ponto final)

Você também pode usar os seguintes caracteres Unicode nos campos Phrase e SoundsLike:

Caractere Código Caractere Código

À 00C0 à 00E0

 00C2 â 00E2

Ç 00C7 ç 00E7

È 00C8 è 00E8

É 00C9 é 00E9

Ê 00CA ê 00EA

Ë 00CB ë 00EB

17
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

Î 00CE î 00EE

Ï 00CF ï 00EF

Ô 00D4 ô 00F4

Ö 00D6 ö 00F6

Ù 00D9 ù 00F9

Û 00DB û 00FB

Ü 00DC ü 00FC

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
vocabulário:

Caractere Código Caractere Código

a 0061 z 007A

b 0062 ã 00E3

d 0064 õ 00F5

e 0065 ø 00F8

f 0066 ŋ 014B

i 0069 œ 0153

j 006A œ̃ 0153 0303

k 006B ɐ 0250

l 006C ɔ 0254

m 006D ə 0259

n 006E ɛ 025B

o 006F ɡ 0261

p 0070 ɥ 0265

s 0073 ɲ 0272

t 0074 ʁ 0281

u 0075 ʃ 0283

v 0076 ʒ 0292

w 0077 ẽ 1EBD

y 0079    

18
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Conjunto de caracteres em alemão


Para vocabulários personalizados em alemão, você pode usar os seguintes caracteres nos campos
Phrase e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)
• - (hífen)
• . (ponto final)

Você também pode usar os seguintes caracteres Unicode nos campos Phrase e SoundsLike:

Caractere Código Caractere Código

ä 00E4 Ä 00C4

ö 00F6 Ö 00D6

ü 00FC Ü 00DC

ß 00DF    

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada de vocabulário:

Caractere Código Caractere Código

a 0061 ts 0074 0073

aɪ 0061 026A uː 0075 02D0

aʊ 0061 028A v 0076

aː 0061 02D0 x 0078

b 0062 z 007A

d 0064 yː 0079 02D0

eː 0065 02D0 ã 00E3

f 0066 ç 00E7

g 0067 øː 00F8 02D0

h 0068 ŋ 014B

iː 0069 02D0 œ 0153

j 006A ɐ̯ 0250 032F

k 006B ɔ 0254

l 006C ɔʏ 0254 028F

l̩ 006C 0329 ə 0259

19
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

m 006D ɛ 025B

m̩ 006D 0329 ɛː 025B 02D0

n 006E ɪ 026A

n̩ 006E 0329 ʁ 0281

oː 006F 02D0 ʃ 0283

p 0070 ʊ 028A

pf 0070 0066 ʏ 028F

s 0073 ʧ 02A7

t 0074    

Conjunto de caracteres hindi


Para vocabulários personalizados em hindi, você pode usar os seguintes caracteres nos campos Phrase
e SoundsLike:

Caractere Código Caractere Código

– 002D थ 0925

. 002E द 0926

ँ 0901 ध 0927

ं 0902 न 0928

ः 0903 प 092A

अ 0905 फ 092B

आ 0906 ब 092C

इ 0907 भ 092D

ई 0908 म 092E

उ 0909 य 092F

ऊ 090A र 0930

ऋ 090B ल 0932

ए 090F व 0935

ऐ 0910 श 0936

ओ 0913 ष 0937

औ 0914 स 0938

क 0915 ह 0939

20
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

ख 0916 ा 093E

ग 0917 ि 093F

घ 0918 ी 0940

ङ 0919 ु 0941

च 091A ू 0942

छ 091B ृ 0943

ज 091C ॅ 0945

झ 091D े 0947

ञ 091E ै 0948

ट 091F ॉ 0949

ठ 0920 ो 094B

ड 0921 ौ 094C

ढ 0922 ् 094D

ण 0923 ज़ 095B

त 0924 ‘ 2018

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

aː 0097 0720 ŋ 0331

b 0098 ɖ 0598

bʱ 0098 0689 ɔː 0596 0720

d 0100 ɖʱ 0598 0689

dʱ 0100 0689 ə 0601

eː 0101 0720 ɛː 0603 0720

f 0102 ɡ 0609

iː 0105 0720 ɡʱ 0609 0689

j 0106 ɦ 0614

k 0107 ɪ 0618

kʰ 0107 0688 ɲ 0626

l 0108 ɳ 0627

21
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

m 0109 ɾ 0638

n 0110 ʂ 0642

oː 0111 0720 ʃ 0643

p 0112 ʈ 0648

pʰ 0112 0688 ʈʰ 0648 0688

r 0114 ʊ 0650

s 0115 ʋ 0651

t 0116 ʤ 0676

tʰ 0116 0688 ʤʱ 0676 0689

uː 0117 0720 ʧ 0679

z 0122 ʧʰ 0679 0688

Conjunto de caracteres em italiano


Para vocabulários personalizados em italiano, você pode usar os seguintes caracteres nos campos
Phrase e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)
• - (hífen)
• . (ponto final)

Você também pode usar os seguintes caracteres Unicode nos campos Phrase e SoundsLike:

Caractere Código Caractere Código

À 00C0 à 00E0

Ä 00C4 ä 00E4

Ç 00C7 ç 00E7

È 00C8 è 00E8

É 00C9 é 00E9

Ê 00CA ê 00EA

Ë 00CB ë 00EB

Ì 00CC ì 00EC

Ò 00D2 ò 00F2

Ù 00D9 ù 00F9

22
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

Ü 00DC ü 00FC

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

a 0061 ss 0073 0073

b 0062 t 0074

bb 0062 0062 tt 0074 0074

d 0064 u 0075

dd 0064 0064 v 0076

e 0065 vv 0076 0076

f 0066 w 0077

ff 0066 0066 z 007A

gg 0067 0067 ɔ 0254

i 0069 ɛ 025B

j 006A ɡ 0261

k 006B ɲ 0272

kk 006B 006B ɲɲ 0272 0272

l 006C ʃ 0283

ll 006C 006C ʃʃ 0283 0283

m 006D ʎ 028E

mm 006D 006D ʎʎ 028e 028e

n 006E ʣ 02A3

nn 006E 06E ʣʣ 02A3 02A3

o 006F ʤ 02A4

p 0070 ʤʤ 02A4 02A4

pp 0070 0070 ʦ 02A6

r 0072 ʦʦ 02A6 02A6

rr 0072 0072 ʧ 02A7

s 0073 ʧʧ 02A7 02A7

23
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Conjunto de caracteres em coreano


Para vocabulários personalizados em coreano, você pode usar qualquer uma das sílabas Hangul nos
campos SoundsLike e Phrase. Para obter mais informações, consulte sílabas Hangul na Wikipédia.

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

a 00061 s# 0073 0348

e 00065 t 0074

h 00068 tɕ 0074 0255

i 00069 tɕʰ 0074 0255 02B0

je 006A 0065 tʰ 0074 02B0

jo 006A 006F t# 0074 0348

ju 006A 0075 t#ɕ 0074 0348 0255

jɛ 006A 025B u 0075

jʌ 006A 028C we 0077 0065

ja 006A 0061 wi 0077 0069

k 006B wɛ 0077 025B

kʰ 006B 02B0 wʌ 0077 028C

k# 006B 0348 wa 0077 0061

l 006C ø 00F8

m 006D ŋ 0014B

n 006E ɛ 0025B

o 006F ɯ 026F

p 0070 ɯi 006F 0069

pʰ 0070 02B0 ɾ 027E

p# 0070 0348 ʌ 028C

s 0073    

Conjunto de caracteres em português


Para vocabulários personalizados em português, você pode usar os seguintes caracteres nos campos
Phrase e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)

24
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

• - (hífen)
• . (ponto final)

Você também pode usar os seguintes caracteres Unicode nos campos Phrase e SoundsLike:

Caractere Código Caractere Código

À 00C0 à 00E0

Á 00C1 á 00E1

 00C2 â 00E2

à 00C3 ã 00E3

Ä 00C4 ä 00E4

Ç 00C7 ç 00E7

È 00C8 è 00E8

É 00C9 é 00E9

Ê 00CA ê 00EA

Ë 00CB ë 00EB

Í 00CD í 00ED

Ñ 00D1 ñ 00F1

Ó 00D3 ó 00F3

Ô 00D4 ô 00F4

Õ 00D5 õ 00F5

Ö 00D6 ö 00F6

Ú 00DA ú 00FA

Ü 00DC ü 00FC

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

a 0061 v 0076

b 0062 w 0077

d 0064 w̃ 0077 0303

e 0065 z 007A

f 0066 õ 00F5

g 0067 ĩ 00129

25
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

i 0069 ũ 00169

j 006A ɐ̃ 0250 0303

k 006B ɔ 0254

l 006C ɛ 025B

m 006D ɲ 0272

n 006E ɾ 027E

o 006F ʁ 0281

p 0070 ʃ 0283

s 0073 ʎ 028E

t 0074 ʒ 0292

tʃ 0074 0283 ʤ 02A4

u 0075 ẽ 1EBD

Conjunto de caracteres em russo


Para vocabulários personalizados em russo, você pode usar os seguintes caracteres nos campos Phrase
e SoundsLike:

Caractere Código Caractere Código

' 0027 п 043F

– 002D р 0440

. 002E с 0441

а 0430 т 0442

б 0431 у 0443

в 0432 ф 0444

г 0433 х 0445

д 0434 ц 0446

е 0435 ч 0447

ж 0436 ш 0448

з 0437 щ 0449

и 0438 ъ 044A

й 0439 ы 044B

к 043A ь 044C

26
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

л 043B э 044D

м 043C ю 044E

н 043D я 044F

о 043E ё 0451

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

b 0062 t 0074

bʲ 0062 02B2 tʃ 0074 0283

d 0064 tʲ 0074 02B2

dʲ 0064 02B2 u 0075

f 0066 v 0076

fʲ 0066 02B2 vʲ 0076 02B2

g 0067 x 0078

gʲ 067 02B2 xʲ 0078 02B2

i 0069 z 007A

j 006A zʲ 007A 02B2

k 006B æ 00E6

kʲ 006B 02B2 ə 0259

l 006C ɛ 025B

lʲ 006C 02B2 ɨ 0268

m 006D ʃ 0283

mʲ 006D 02B2 ʃʲ 0283 02B2

n 006E ʊ 028A

nʲ 006E 02B2 ʌ 028C

p 0070 ʒ 0292

pʲ 0070 02B2 ˈi 02C8 0069

r 0072 ˈo 02C8 006F

rʲ 0072 02B2 ˈv 02C8 0075

s 0073 ˈɛ 02C8 025B

27
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

sʲ 0073 02B2 ˈɨ 02C8 0268

ts 0074 0073 ˈa 02C8 0061

Conjunto de caracteres em espanhol


Para vocabulários personalizados em espanhol, você pode usar os seguintes caracteres nos campos
Phrase e SoundsLike:

• a-z
• A-Z
• ' (apóstrofo)
• - (hífen)
• . (ponto final)

Você também pode usar os seguintes caracteres Unicode nos campos Phrase e SoundsLike:

Caractere Código Caractere Código

Á 00C1 á 00E1

É 00C9 é 00E9

Í 00CD ë 00ED

Ó 00D3 ó 0XF3

Ú 00DA ú 00FA

Ñ 00D1 ñ 0XF1

ü 00FC    

Você pode usar os seguintes caracteres do Alfabeto Fonético Internacional no campo IPA do arquivo de
entrada:

Caractere Código Caractere Código

a 0061 r 0072

b 0062 s 0073

d 0064 t 0074

e 0065 u 0075

f 0066 v 0076

g 0067 w 0077

h 0068 x 0078

i 0069 z 007A

28
Amazon Transcribe Guia do desenvolvedor
Conjuntos de caracteres para vocabulários personalizados

Caractere Código Caractere Código

j 006A ŋ 014B

k 006B ɲ 0272

l 006C ɾ 027E

m 006D ʃ 0283

n 006E ʝ 029D

o 006F ʧ 02A7

p 0070 θ 03B8

29
Amazon Transcribe Guia do desenvolvedor
Etapa 1: Configurar uma conta

Conceitos básicos do Amazon


Transcribe
Para começar a usar o Amazon Transcribe, configure uma conta da AWS e crie um usuário do AWS
Identity and Access Management (IAM). Para usar a AWS Command Line Interface (AWS CLI), baixe-a e
configure-a.

Tópicos
• Etapa 1: Configurar uma conta da AWS e criar um usuário administrador (p. 30)
• Etapa 2: Configurar a AWS Command Line Interface (AWS CLI) (p. 31)
• Etapa 3: conceitos básicos do uso do console (p. 32)
• Etapa 4: Conceitos básicos do uso da API (p. 36)
• Etapa 5: Conceitos básicos do streaming de áudio (p. 40)

Etapa 1: Configurar uma conta da AWS e criar um


usuário administrador
Antes de usar o Amazon Transcribe pela primeira vez, execute as seguintes tarefas:

1. Cadastre-se na AWS (p. 30)


2. Criar um usuário do IAM (p. 31)

Cadastre-se na AWS
Ao se cadastrar na Amazon Web Services (AWS), sua conta da AWS será automaticamente cadastrada
em todos os serviços da AWS, incluindo o Amazon Transcribe. Você será cobrado apenas pelos serviços
que usar.

Com o Amazon Transcribe, você paga apenas pelos recursos que usa. Se você for um cliente novo da
AWS, poderá começar a usar o Amazon Transcribe gratuitamente. Para obter mais informações, consulte
Nível de uso gratuito da AWS.

Se você já tem uma conta da AWS, vá para a próxima seção.

Para criar uma conta da AWS

1. Abra https://portal.aws.amazon.com/billing/signup.
2. Siga as instruções online.

Parte do procedimento de cadastro envolve uma chamada telefônica e a digitação de um código de


verificação usando o teclado do telefone.

30
Amazon Transcribe Guia do desenvolvedor
Criar um usuário do IAM

Registre o ID de sua conta da AWS, pois precisará dele na próxima tarefa.

Criar um usuário do IAM


Os serviços na AWS, como o Amazon Transcribe, exigem que você forneça credenciais ao acessá-los.
Isso permite que o serviço determine se você tem permissões para acessar os recursos dele.

Recomendamos que você acesse a AWS usando o AWS Identity and Access Management (IAM), em
vez das credenciais de sua conta da AWS. Para usar o IAM a fim de acessar a AWS, crie um usuário
do IAM, adicione o usuário a um grupo do IAM com permissões administrativas e, em seguida, conceda
permissões administrativas ao usuário do IAM. Em seguida, você pode acessar a AWS usando um URL
especial e as credenciais do usuário do IAM.

Os exercícios de conceitos básicos deste guia pressupõem que você tenha um usuário com privilégios de
administrador, adminuser.

Para criar um usuário administrador e fazer login no console

1. Crie um usuário administrador chamado adminuser na conta da AWS. Para obter instruções,
consulte Criar o primeiro usuário do IAM e grupo de administradores no Guia do usuário do IAM.
2. Faça login no Console de gerenciamento da AWS usando um URL especial. Para obter mais
informações, consulte Como os usuários fazem login em sua conta no Guia do usuário do IAM.

Para obter mais informações sobre IAM, consulte o seguinte:

• AWS Identity and Access Management (IAM)


• Conceitos básicos
• Guia do usuário do IAM

Próxima etapa
Etapa 2: Configurar a AWS Command Line Interface (AWS CLI) (p. 31)

Etapa 2: Configurar a AWS Command Line


Interface (AWS CLI)
Você não precisa da AWS CLI para executar as etapas nos exercícios de Conceitos básicos. No entanto,
alguns dos outros exercícios neste guia a requerem. Se preferir, pode pular esta etapa e configurar a AWS
CLI posteriormente.

Para configurar a AWS CLI

1. Baixe e configure a AWS CLI. Para obter instruções, consulte os tópicos a seguir no Guia do usuário
do AWS Command Line Interface:

• Começar a usar a AWS Command Line Interface


• Configuração do AWS Command Line Interface
2. No arquivo AWS CLI da config, adicione um perfil nomeado para o usuário administrador:

[profile adminuser]

31
Amazon Transcribe Guia do desenvolvedor
Próxima etapa

aws_access_key_id = adminuser access key ID


aws_secret_access_key = adminuser secret access key
region = aws-region

Você pode usar esse perfil ao executar os comandos da AWS CLI. Para obter mais informações sobre
perfis nomeados, consulte Perfis nomeados no Guia do usuário do AWS Command Line Interface.
Para obter uma lista das regiões da AWS, consulte Regiões e endpoints no Referência geral do
Amazon Web Services.
3. Verifique a configuração digitando o seguinte comando de ajuda no prompt de comando:

aws help

Próxima etapa
Etapa 3: conceitos básicos do uso do console (p. 32)

Etapa 3: conceitos básicos do uso do console


A forma mais fácil de começar a usar o Amazon Transcribe é enviar um trabalho usando o console para
transcrever um arquivo de áudio. Se você ainda não revisou os conceitos e a terminologia em Como o
Amazon Transcribe funciona (p. 4), recomendamos fazer isso antes de continuar.

Tópicos
• Como criar um trabalho de transcrição (p. 32)
• Como exibir um trabalho de transcrição (p. 33)

Como criar um trabalho de transcrição


Use o console do Amazon Transcribe para criar um trabalho de transcrição de seus arquivos de áudio.

1. Forneça as informações a seguir:

• Transcription job name (Nome do trabalho de transcrição) — um nome para o trabalho. O nome
deve ser exclusivo em sua conta da AWS.
• Amazon S3input URL (URL de entrada do Amazon S3) — o local do Amazon S3 do arquivo de
áudio de entrada. O local deve estar na mesma região que o endpoint que você estiver chamando.
• Idioma— escolha o idioma de seu arquivo de entrada.
• Format (Formato) — o formato do arquivo de áudio. Para obter os melhores resultados, você deve
usar um formato sem perda como FLAC ou WAV com codificação de PCM de 16 bits.
• Media sampling rate (Hz) (Taxa de amostragem da mídia (Hz)) — opcional. A taxa de amostragem
de bits do arquivo de áudio. O Amazon Transcribe aceita taxas de amostra entre 8000 Hz e 48000
Hz. Para obter os melhores resultados, você deve usar 8.000 Hz para áudio de baixa fidelidade e
16.000 Hz para áudio de alta fidelidade.

A seguir encontra-se o formulário Create Transcription Job (Criar trabalho de transcrição) preenchido
para um trabalho de exemplo.

32
Amazon Transcribe Guia do desenvolvedor
Como exibir um trabalho de transcrição

2. Selecione Create (Criar) para enviar o trabalho para processamento.

Como exibir um trabalho de transcrição


Os trabalhos de transcrição concluídos são exibidos em uma lista que contém uma breve descrição do
trabalho. A coluna Availability (Disponibilidade) mostra o tempo restante durante o qual os resultados de
trabalho serão mantidos no servidor. Os trabalhos são mantidos por 90 dias e excluídos do sistema.

33
Amazon Transcribe Guia do desenvolvedor
Como exibir um trabalho de transcrição

Escolha um trabalho na lista para visualizar informações sobre o trabalho em questão.

A página de informações sobre o trabalho de transcrição tem três seções. A seção Detail (Detalhes)
fornece detalhes sobre o trabalho de transcrição, como nome, informações sobre quando o trabalho será
excluído do servidor e os URLs de entrada e saída. Use o URL de saída para fazer download do resultado
de seu trabalho de transcrição.

A seção Output (Saída) contém a transcrição do áudio enviado ao Amazon Transcribe. Você pode fazer
download da transcrição escolhendo o botão Download transcription (Fazer download da transcrição).

A seção Code samples (Exemplos de código) contém a entrada JSON da operação


StartTranscriptionJob (p. 114) e a saída da operação GetTranscriptionJob (p. 103).

34
Amazon Transcribe Guia do desenvolvedor
Como exibir um trabalho de transcrição

Próxima etapa

Etapa 4: Conceitos básicos do uso da API (p. 36)

35
Amazon Transcribe Guia do desenvolvedor
Etapa 4: Conceitos básicos do uso da API

Etapa 4: Conceitos básicos do uso da API


Esta seção contém exemplos que demonstram como se usa a API do Amazon Transcribe. Você pode usar
esses exemplos para saber mais sobre a API ou como criar blocos em seus aplicativos.

Tópicos
• Conceitos básicos (AWS Command Line Interface) (p. 36)
• Conceitos básicos (AWS SDK for Python (Boto)) (p. 38)

Conceitos básicos (AWS Command Line Interface)


No exercício a seguir, use a AWS Command Line Interface (AWS CLI) para transcrever voz em texto. Para
concluir este exercício, você precisa:

• Ter um editor de texto.


• Familiarizar-se com a AWS CLI. Para obter mais informações, consulte Etapa 2: Configurar a AWS
Command Line Interface (AWS CLI) (p. 31).
• Ter um arquivo de voz no formato .WAV ou .MP4 armazenado em um bucket do S3 que tenha as
permissões apropriadas. Para obter mais informações sobre as permissões necessárias para o Amazon
Transcribe, consulte Permissões necessárias para funções de usuários do IAM (p. 79).

Para transcrever texto, é necessário fornecer parâmetros de entrada em um arquivo JSON.

Para transcrever texto

1. Copie a entrada de voz em um bucket S3. O local deve estar na mesma região que o endpoint que
você está chamando. Este exemplo supõe que o arquivo é um bucket do S3 denominado test-
transcribe e que o nome do arquivo é answer2.wav.
2. Crie um arquivo JSON denominado test-start-command.json que contenha os parâmetros de
entrada para a operação StartTranscriptionJob (p. 114).

{
"TranscriptionJobName": "request ID",
"LanguageCode": "en-US",
"MediaFormat": "wav",
"Media": {
"MediaFileUri": "https://S3 endpoint/test-transcribe/answer2.wav"
}
}

3. Na AWS CLI, execute o seguinte comando. O exemplo é formatado para Unix, Linux e macOS. Para
Windows, substitua o caractere de continuação Unix de barra invertida (\) no final de cada linha por um
circunflexo (^).

aws transcribe start-transcription-job \


--region region \
--cli-input-json file://test-start-command.json

O Amazon Transcribe responde com o seguinte:

{
"TranscriptionJob": {
"TranscriptionJobName": "request ID",
"LanguageCode": "en-US",

36
Amazon Transcribe Guia do desenvolvedor
Conceitos básicos (AWS CLI)

"TranscriptionJobStatus": "IN_PROGRESS",
"Media": {
"MediaFileUri": "https://S3 endpoint/test-transcribe/answer2.wav"
},
"CreationTime": timestamp,
"MediaFormat": "wav"
}
}

Para listar trabalhos de transcrição

• Execute o seguinte comando:

aws transcribe list-transcription-jobs \


--region region \
--status IN_PROGRESS

O Amazon Transcribe responde com o seguinte:

{
"Status": "IN_PROGRESS",
"TranscriptionJobSummaries": [
{
"TranscriptionJobName": "request ID",
"LanguageCode": "en-US",
"CreationTime": timestamp,
"TranscriptionJobStatus": "IN_PROGRESS"
}
]
}

Para obter resultados de um trabalho de transcrição

1. Quando o status do trabalho for COMPLETED, obtenha os resultados do trabalho. Digite o seguinte
comando:

aws transcribe get-transcription-job \


--region region \
--transcription-job-name "request ID"

O Amazon Transcribe responde com o seguinte:

{
"TranscriptionJob": {
"TranscriptionJobName": "request ID",
"LanguageCode": "en-US",
"TranscriptionJobStatus": "COMPLETED",
"Media": {
"MediaFileUri": "input URI"
},
"CreationTime": timestamp,
"CompletionTime": timestamp,
"Transcript": {
"TranscriptFileUri": "output URI"
}
}
}

37
Amazon Transcribe Guia do desenvolvedor
Conceitos básicos (SDK for Python)

2. Use o URI de saída para obter texto transcrito de arquivos de áudio. A seguir encontra-se o resultado
da transcrição de um pequeno clipe de áudio:

{
"jobName":"job ID",
"accountId":"account ID",
"results": {
"transcripts":[
{
"transcript":" that's no answer"
}
],
"items":[
{
"start_time":"0.180",
"end_time":"0.470",
"alternatives":[
{
"confidence":0.84,
"content":"that's"
}
],
"type": "pronunciation"
},
{
"start_time":"0.470",
"end_time":"0.710",
"alternatives":[
{
"confidence":0.99,
"content":"no"
}
],
"type": "pronunciation"
},
{
"start_time":"0.710",
"end_time":"1.080",
"alternatives":[
{
"confidence":0.874,
"content":"answer"
}
],
"type": "pronunciation"
}
]
},
"status":"COMPLETED"
}

Conceitos básicos (AWS SDK for Python (Boto))


Neste exercício, você criará o script que usa o SDK for Python para transcrever voz em texto. Para concluir
este exercício, você precisa:

• Instalar a AWS CLI. Para obter mais informações, consulte Etapa 2: Configurar a AWS Command Line
Interface (AWS CLI) (p. 31). Isso instala o AWS SDK for Python (Boto).
• Ter um arquivo de voz no formato .WAV ou .MP4 armazenado em um bucket do S3 que tenha as
permissões apropriadas. Para obter mais informações sobre as permissões necessárias para o Amazon
Transcribe, consulte Permissões necessárias para funções de usuários do IAM (p. 79). O local deve

38
Amazon Transcribe Guia do desenvolvedor
Conceitos básicos (SDK for Python)

estar na mesma região que o endpoint que você está chamando. Este exemplo supõe que o arquivo é
um bucket do Amazon S3 denominado test-transcribe e que o nome do arquivo é answer2.wav.

from __future__ import print_function


import time
import boto3
transcribe = boto3.client('transcribe')
job_name = "job name"
job_uri = "https://S3 endpoint/test-transcribe/answer2.wav"
transcribe.start_transcription_job(
TranscriptionJobName=job_name,
Media={'MediaFileUri': job_uri},
MediaFormat='wav',
LanguageCode='en-US'
)
while True:
status = transcribe.get_transcription_job(TranscriptionJobName=job_name)
if status['TranscriptionJob']['TranscriptionJobStatus'] in ['COMPLETED', 'FAILED']:
break
print("Not ready yet...")
time.sleep(5)
print(status)

Quando o trabalho de transcrição for concluído, o resultado será vinculado ao presigned URL do Amazon
S3 que contém a transcrição em formato JSON:

{
"jobName":"job ID",
"accountId":"account ID",
"results": {
"transcripts":[
{
"transcript":" that's no answer",
"confidence":1.0
}
],
"items":[
{
"start_time":"0.180",
"end_time":"0.470",
"alternatives":[
{
"confidence":0.84,
"word":"that's"
}
]
},
{
"start_time":"0.470",
"end_time":"0.710",
"alternatives":[
{
"confidence":0.99,
"word":"no"
}
]
},
{
"start_time":"0.710",
"end_time":"1.080",
"alternatives":[
{
"confidence":0.87,

39
Amazon Transcribe Guia do desenvolvedor
Etapa 5: Conceitos básicos do streaming de áudio

"word":"answer"
}
]
}
]
},
"status":"COMPLETED"
}

Etapa 5: Conceitos básicos do streaming de áudio


O exemplo a seguir é um programa Java que transcreve streaming de áudio. A entrada vem do microfone
do computador ou de um upload de arquivo, e a saída é apresentada na saída padrão do computador.

Para executar esse exemplo, é necessário o seguinte:

• Você deve usar o AWS SDK para Java 2.x


• Os clientes devem usar o Java 1.8 para ser compatível com o AWS SDK para Java 2.x.

/**
* COPYRIGHT:
* <p>
* Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* <p>
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.transcribestreaming;

import org.reactivestreams.Publisher;
import org.reactivestreams.Subscriber;
import org.reactivestreams.Subscription;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.core.SdkBytes;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
import software.amazon.awssdk.services.transcribestreaming.model.*;

import javax.sound.sampled.*;
import java.io.*;
import java.net.URISyntaxException;
import java.nio.ByteBuffer;
import java.util.List;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicLong;

public class TranscribeStreamingDemoApp {

40
Amazon Transcribe Guia do desenvolvedor
Etapa 5: Conceitos básicos do streaming de áudio

private static final Region REGION = Region.US_EAST_1;


private static Subscription currentSubscription;

private static TranscribeStreamingAsyncClient client;

public static void main(String args[]) throws URISyntaxException, ExecutionException,


InterruptedException, LineUnavailableException {

client = TranscribeStreamingAsyncClient.builder()
.credentialsProvider(getCredentials())
.region(REGION)
.build();

CompletableFuture<Void> result =
client.startStreamTranscription(getRequest(16_000),
new AudioStreamPublisher(getStreamFromMic()),
getResponseHandler());

result.get();
client.close();
}

private static InputStream getStreamFromMic() throws LineUnavailableException {

// Signed PCM AudioFormat with 16kHz, 16 bit sample size, mono


int sampleRate = 16000;
AudioFormat format = new AudioFormat(sampleRate, 16, 1, true, false);
DataLine.Info info = new DataLine.Info(TargetDataLine.class, format);

if (!AudioSystem.isLineSupported(info)) {
System.out.println("Line not supported");
System.exit(0);
}

TargetDataLine line = (TargetDataLine) AudioSystem.getLine(info);


line.open(format);
line.start();

InputStream audioStream = new AudioInputStream(line);


return audioStream;
}

private static AwsCredentialsProvider getCredentials() {


return DefaultCredentialsProvider.create();
}

private static StartStreamTranscriptionRequest getRequest(Integer mediaSampleRateHertz)


{
return StartStreamTranscriptionRequest.builder()
.languageCode(LanguageCode.EN_US.toString())
.mediaEncoding(MediaEncoding.PCM)
.mediaSampleRateHertz(mediaSampleRateHertz)
.build();
}

private static StartStreamTranscriptionResponseHandler getResponseHandler() {


return StartStreamTranscriptionResponseHandler.builder()
.onResponse(r -> {
System.out.println("Received Initial response");
})
.onError(e -> {
System.out.println(e.getMessage());
StringWriter sw = new StringWriter();
e.printStackTrace(new PrintWriter(sw));
System.out.println("Error Occurred: " + sw.toString());
})

41
Amazon Transcribe Guia do desenvolvedor
Etapa 5: Conceitos básicos do streaming de áudio

.onComplete(() -> {
System.out.println("=== All records stream successfully ===");
})
.subscriber(event -> {
List<Result> results = ((TranscriptEvent)
event).transcript().results();
if (results.size() > 0) {
if (!results.get(0).alternatives().get(0).transcript().isEmpty()) {

System.out.println(results.get(0).alternatives().get(0).transcript());
}
}
})
.build();
}

private InputStream getStreamFromFile(String audioFileName) {


try {
File inputFile = new
File(getClass().getClassLoader().getResource(audioFileName).getFile());
InputStream audioStream = new FileInputStream(inputFile);
return audioStream;
} catch (FileNotFoundException e) {
throw new RuntimeException(e);
}
}

private static class AudioStreamPublisher implements Publisher<AudioStream> {


private final InputStream inputStream;

private AudioStreamPublisher(InputStream inputStream) {


this.inputStream = inputStream;
}

@Override
public void subscribe(Subscriber<? super AudioStream> s) {

if (this.currentSubscription == null) {
this.currentSubscription = new SubscriptionImpl(s, inputStream);
} else {
this.currentSubscription.cancel();
this.currentSubscription = new SubscriptionImpl(s, inputStream);
}
s.onSubscribe(currentSubscription);
}
}

public static class SubscriptionImpl implements Subscription {


private static final int CHUNK_SIZE_IN_BYTES = 1024 * 1;
private final Subscriber<? super AudioStream> subscriber;
private final InputStream inputStream;
private ExecutorService executor = Executors.newFixedThreadPool(1);
private AtomicLong demand = new AtomicLong(0);

private SubscriptionImpl(Subscriber<? super AudioStream> s, InputStream


inputStream) {
this.subscriber = s;
this.inputStream = inputStream;
}

@Override
public void request(long n) {
if (n <= 0) {
subscriber.onError(new IllegalArgumentException("Demand must be
positive"));

42
Amazon Transcribe Guia do desenvolvedor
Etapa 5: Conceitos básicos do streaming de áudio

demand.getAndAdd(n);

executor.submit(() -> {
try {
do {
ByteBuffer audioBuffer = getNextEvent();
if (audioBuffer.remaining() > 0) {
AudioEvent audioEvent = audioEventFromBuffer(audioBuffer);
subscriber.onNext(audioEvent);
} else {
subscriber.onComplete();
break;
}
} while (demand.decrementAndGet() > 0);
} catch (Exception e) {
subscriber.onError(e);
}
});
}

@Override
public void cancel() {
executor.shutdown();
}

private ByteBuffer getNextEvent() {


ByteBuffer audioBuffer = null;
byte[] audioBytes = new byte[CHUNK_SIZE_IN_BYTES];

int len = 0;
try {
len = inputStream.read(audioBytes);

if (len <= 0) {
audioBuffer = ByteBuffer.allocate(0);
} else {
audioBuffer = ByteBuffer.wrap(audioBytes, 0, len);
}
} catch (IOException e) {
throw new UncheckedIOException(e);
}

return audioBuffer;
}

private AudioEvent audioEventFromBuffer(ByteBuffer bb) {


return AudioEvent.builder()
.audioChunk(SdkBytes.fromByteBuffer(bb))
.build();
}
}
}

43
Amazon Transcribe Guia do desenvolvedor

Transcrição de streaming
A transcrição de streaming do Amazon Transcribe permite enviar um streaming de áudio e receber um
streaming de texto em tempo real. A API facilita para os desenvolvedores adicionarem o recurso de
conversão de fala em texto em tempo real aos seus aplicativos.

Você pode usar o streaming de transcrição nos seguintes idiomas:

• 8 KHz e 16 KHz
• • Inglês EUA (en-US)
• Espanhol dos EUA (es-US)
• Apenas 8 KHz
• • Inglês australiano (en-AU)
• Inglês britânico (en-GB)
• Francês (fr-FR)
• Francês canadense (fr-CA)

A transcrição de streaming do Amazon Transcribe pode ser usada para diversas finalidades. Por exemplo:

• As transcrições de streaming podem gerar legendas em tempo real para mídia de transmissão ao vivo.
• Os advogados podem fazer anotações em tempo real sobre as transcrições de streaming durante os
depoimentos no tribunal.
• O bate-papo de videogame pode ser transcrito em tempo real para que os hosts possam moderar o
conteúdo ou executar análise em tempo real.
• As transcrições de streaming podem fornecer assistência para deficientes auditivos.

A transcrição de streaming não oferece suporte à identificação de canal ou de alto-falante. Use a operação
StartTranscriptionJob (p. 114) se precisar desses recursos.

Se você estiver usando HTTP/2, fornecemos um cliente de streaming HTTP/2 que lida com as novas
tentativas de conexão quando há problemas temporários na rede. Você pode usar esse cliente como
um ponto de partida para seus próprios aplicativos. Para usar o streaming do Amazon Transcribe com o
protocolo WebSocket, você pode criar seu próprio cliente.

A transcrição de streaming pega um streaming dos dados de áudio e os transcreve em tempo real. A
transcrição é retornada para o aplicativo em um streaming de eventos de transcrição.

O Amazon Transcribe divide o streaming de áudio de entrada com base em segmentos naturais de fala,
como uma mudança de orador ou uma pausa no áudio. A transcrição é retornada progressivamente para
seu aplicativo, com cada resposta contendo mais fala transcrita até que todo o segmento seja transcrito.

No exemplo a seguir, cada linha é um resultado parcial da saída de transcrição do streaming de um


segmento de áudio:

the amazon is the largest


the amazon is the largest
the amazon is the largest
the amazon is the largest rainforest
the amazon is the largest rainforest
the amazon is the largest rainforest
the amazon is the largest rainforest on the
the amazon is the largest rainforest on the

44
Amazon Transcribe Guia do desenvolvedor

the amazon is the largest rainforest on the planet


the amazon is the largest rainforest on the planet
the amazon is the largest rainforest on the planet
the amazon is the largest rainforest on the planet
the amazon is the largest rainforest on the planet covering over
the amazon is the largest rainforest on the planet covering over
the amazon is the largest rainforest on the planet covering over two million

Cada objeto de Resultado na resposta contém um campo chamado IsPartial que indica se a resposta
é uma resposta parcial, com os resultados da transcrição até agora, ou se é uma transcrição completa do
segmento de áudio.

Cada objeto de Resultado também contém o horário de início e de término do período do streaming de
áudio para que você possa, por exemplo, sincronizar a transcrição com o vídeo.

O exemplo a seguir é uma resposta de transcrição parcial.

{
"TranscriptResultStream": {
"TranscriptEvent": {
"Transcript": {
"Results": [
{
"Alternatives": [
{
"Items": [
{
"Content": "the",
"EndTime": 0.3799375,
"StartTime": 0.0299375,
"Type": "pronunciation"
},
{
"Content": "amazon",
"EndTime": 0.5899375,
"StartTime": 0.3899375,
"Type": "pronunciation"
},
{
"Content": "is",
"EndTime": 0.7899375,
"StartTime": 0.5999375,
"Type": "pronunciation"
},
{
"Content": "the",
"EndTime": 0.9199375,
"StartTime": 0.7999375,
"Type": "pronunciation"
},
{
"Content": "largest",
"EndTime": 1.0199375,
"StartTime": 0.9299375,
"Type": "pronunciation"
}
],
"Transcript": "the amazon is the largest"
}
],
"EndTime": 1.02,
"IsPartial": true,
"ResultId": "2db76dc8-d728-11e8-9f8b-f2801f1b9fd1",
"StartTime": 0.0199375

45
Amazon Transcribe Guia do desenvolvedor
Codificação de fluxo de evento

}
]
}
}
}
}

Tópicos
• Codificação de fluxo de evento (p. 46)
• Usar streaming do Amazon Transcribe com WebSockets (p. 47)
• Uso de streaming do Amazon Transcribe com HTTP/2 (p. 54)

Codificação de fluxo de evento


A codificação do fluxo de eventos fornece comunicação bidirecional usando mensagens entre um cliente
e um servidor. Os quadros de dados enviados para o serviço de streaming do Amazon Transcribe são
codificados neste formato. A resposta do Amazon Transcribe também usa essa codificação.

Cada mensagem consiste em duas seções: o prelúdio e os dados. O prelúdio consiste em:

1. O comprimento de byte total da mensagem


2. O comprimento de byte combinado de todos os cabeçalhos

A seção de dados consiste em:

1. Os cabeçalhos
2. Uma carga

Cada seção termina com uma soma de verificação CRC de inteiro de 4 bytes em big-endian. O Amazon
Transcribe usa CRC32 (geralmente conhecido como GZIP CRC32) para calcular as duas CRCs. Para
obter mais informações sobre CRC32, consulte Especificação do formato de arquivo GZIP versão 4.3.

O total de sobrecarga de mensagem, incluindo o prelúdio e ambas as somas de verificação, é de 16 bytes.

O diagrama a seguir mostra os componentes que formam uma mensagem e um cabeçalho. Há vários
cabeçalhos por mensagem.

46
Amazon Transcribe Guia do desenvolvedor
Uso de streaming com WebSocket

Cada mensagem contém os seguintes componentes:

• Prelúdio: Sempre com tamanho fixo de 8 bytes, dois campos de 4 bytes cada.
• Primeiros 4 bytes: O tamanho total de bytes. Este é o número inteiro big-endian de bytes da
mensagem inteira, incluindo o próprio campo de comprimento de 4 bytes.
• Segundo grupo de 4 bytes: O comprimento de bytes do cabeçalho. Este é o comprimento de bytes
integral do big-endian da porção dos cabeçalhos da mensagem, excluindo o próprio comprimento dos
cabeçalhos.
• CRC do prelúdio: a soma de verificação CRC de 4 bytes para a porção do prelúdio da mensagem,
excluindo a própria CRC. O prelúdio tem uma CRC separada da CRC da mensagem para garantir que o
Amazon Transcribe possa detectar informações de comprimento de byte corrompido imediatamente sem
causar erros como as sobrecargas de buffer.
• Cabeçalhos: Metadados que anotam a mensagem, como o tipo de mensagem, tipo de conteúdo, e
assim por diante. As mensagens têm vários cabeçalhos. Cabeçalhos são pares de valor da chave onde
a chave é uma sequência de caracteres UTF-8. Os cabeçalhos podem aparecer em qualquer ordem na
parte dos cabeçalhos da mensagem e um determinado cabeçalho pode aparecer apenas uma vez. Para
os tipos de cabeçalho necessários, consulte as seções a seguir.
• Carga: o conteúdo de áudio a ser transcrito.
• CRC da mensagem: a soma de verificação CRC de 4 bytes desde o início da mensagem até o início da
soma de verificação. Ou seja, tudo na mensagem, exceto a CRC em si.

Cada cabeçalho contém os seguintes componentes. Há vários cabeçalhos por quadro.

• O comprimento de byte do nome do cabeçalho: o comprimento de bytes do nome do cabeçalho.


• Nome do cabeçalho: o nome do cabeçalho que indica o tipo de cabeçalho. Para valores válidos,
consulte as seguintes descrições de quadro.
• Tipo de valor de cabeçalho: uma enumeração que indica o tipo de valor de cabeçalho.
• Comprimento de byte da string de valor: o comprimento de byte da string de valor do cabeçalho.
• Valor do cabeçalho: o valor da string do cabeçalho. Os valores válidos para esse campo dependem do
tipo de cabeçalho. Para valores válidos, consulte as seguintes descrições de quadro.

Usar streaming do Amazon Transcribe com


WebSockets
Quando você usa o protocolo WebSocket para fazer streaming de áudio, o Amazon Transcribe transcreve
o fluxo em tempo real. Você codifica o áudio com a codificação de fluxo de evento, o Amazon Transcribe
responde com uma estrutura JSON que também é codificada usando a codificação de fluxo de evento.
Para mais informações, consulte Codificação de fluxo de evento (p. 46). Você pode usar as informações
nesta seção para criar aplicativos usando a biblioteca WebSocket de sua escolha.

Tópicos
• Adicionar uma política para solicitações WebSocket à sua função do IAM (p. 48)
• Criação de uma Pre-Signed URL (p. 48)
• Manipular a resposta de atualização do WebSocket (p. 52)
• Criar uma solicitação de streaming WebSocket (p. 52)
• Manipular uma resposta de streaming WebSocket (p. 53)
• Manipular erros de streaming WebSocket (p. 53)

47
Amazon Transcribe Guia do desenvolvedor
Adicionar uma política para solicitações
WebSocket à sua função do IAM

Adicionar uma política para solicitações WebSocket à


sua função do IAM
Para usar o protocolo WebSocket para chamar o Amazon Transcribe, você precisa anexar a política a
seguir à função do AWS Identity and Access Management (IAM) que faz a solicitação.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "transcribestreaming",
"Effect": "Allow",
"Action": "transcribe:StartStreamTranscriptionWebSocket",
"Resource": "*"
}
]
}

Criação de uma Pre-Signed URL


Crie um URL para sua solicitação WebSocket contendo as informações necessárias para configurar a
comunicação entre o seu aplicativo e o Amazon Transcribe. O streaming WebSocket usa o processo do
Amazon Signature versão 4 para assinar solicitações. Assinar a solicitação ajuda a verificar a identidade
do solicitante e a proteger seus dados de áudio em trânsito. Também protege contra possíveis ataques de
repetição. Para obter mais informações sobre o Signature versão 4, consulte Assinar solicitações de API
da AWS na Referência geral da Amazon Web Services.

O URL tem o seguinte formato: Quebras de linha foram adicionadas para uma melhor leitura.

GET https://transcribestreaming.region.amazonaws.com:8443/stream-transcription-websocket
?language-code=languageCode
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=Signature Version 4 credential scope
&X-Amz-Date=date
&X-Amz-Expires=time in seconds until expiration
&X-Amz-Security-Token=security-token
&X-Amz-Signature=Signature Version 4 signature
&X-Amz-SignedHeaders=host
&media-encoding=mediaEncoding
&sample-rate=mediaSampleRateHertz
&session-id=sessionId
&vocabulary-name=vocabularyName

Use os seguintes valores para os parâmetros do URL:

• language-code – o código do idioma do áudio de entrada. Os valores válidos são en-GB, en-US, es-
US, fr-CA, e fr-FR.
• media-encoding – a codificação usada para o áudio de entrada. O único valor válido é pcm.
• sample-rate – a taxa da amostragem do áudio de entrada em Hertz. Sugerimos que você use 8000 Hz
para áudio de baixa qualidade e 16000 Hz para áudio de alta qualidade. A taxa de amostragem deve
corresponder à taxa de amostragem no arquivo de áudio.
• sessionId – opcional. Um identificador para a sessão de transcrição. Se você não fornecer um ID de
sessão, o Amazon Transcribe gerará um para você e o retornará na resposta.
• vocabulary-name – opcional. O nome do vocabulário a ser usado no processamento da tarefa de
transcrição, se houver.

48
Amazon Transcribe Guia do desenvolvedor
Criação de uma Pre-Signed URL

Os parâmetros a seguir são parâmetros do Signature versão 4.

• X-Amz-Algorithm – o algoritmo que você está usando no processo de assinatura. O único valor válido é
AWS4-HMAC-SHA256.
• X-Amz-Credential – uma string separada por barras ("/"), formada concatenando seu ID de chave
de acesso e seus componentes de escopo de credencial. O escopo de credencial inclui a data no
formato AAAAMMDD, a Região da AWS, o nome do serviço e uma string de encerramento especial
(aws4_request).
• X-Amz-Date – a data e a hora em que a assinatura foi criada. Gere a data e a hora seguindo as
instruções em Tratamento de datas no Signature versão 4 na Referência geral da Amazon Web
Services.
• X-Amz-Expires – o tempo, em segundos, até que as credenciais expirem. O valor máximo é 300
segundos (5 minutos).
• X-Amz-Security-Token – opcional. Um token Signature versão 4 para credenciais temporárias. Se você
especificar esse parâmetro, inclua-o na solicitação canônica. Para obter mais informações, consulte
Solicitação de credenciais de segurança temporárias no Guia do usuário do AWS Identity and Access
Management.
• X-Amz-Signature – a assinatura do Signature versão 4 que você gerou para a solicitação.
• X-Amz-SignedHeaders – os cabeçalhos que são assinados ao criar a assinatura para a solicitação. O
único valor válido é host.

Para criar o URL para a solicitação e criar a assinatura do Signature versão 4, siga as etapas a seguir. Os
exemplos estão em pseudocódigo.

Tarefa 1: Criar uma solicitação canônica

Crie uma string que inclua as informações da solicitação em um formato padronizado. Isso garante que,
quando a AWS receber a solicitação, ela poderá calcular a mesma assinatura que você calcular na Tarefa
3. Para obter mais informações, consulte Criar uma solicitação canônica para o Signature versão 4 na
Referência geral da Amazon Web Services.

1. Defina variáveis para a solicitação no seu aplicativo.

ɛ HTTP verb
method = "GET"
ɛ Service name
service = "transcribe"
ɛ AWS Region
region = "AWS Region"
ɛ Amazon Transcribe streaming endpoint
endpoint = "https://transcribestreaming.region.amazonaws.com:8443"
ɛ Host
host = "transcribestreaming.region.amazonaws.com:8443"
ɛ Date and time of request
amz-date = YYYMMDD'T'HHMMSS'Z'
ɛ Date without time for credential scope
datestamp = YYYYMMDD

2. Crie um URI canônico. O URI canônico é a parte do URI entre o domínio e a string de consulta.

canonical_uri = "/stream-transcription-websocket"

3. Crie cabeçalhos canônicos e cabeçalhos assinados. Observe o "\n" que vem no final dos cabeçalhos
canônicos.

canonical_headers = "host:" + host + "\n"

49
Amazon Transcribe Guia do desenvolvedor
Criação de uma Pre-Signed URL

signed_headers = "host"

4. Faça uma correspondência entre o algoritmo e o algoritmo de hash. Você deve usar SHA-256.

algorithm = "AWS4-HMAC-SHA256"

5. Crie o escopo da credencial, que define o escopo da chave derivada como a data, a Região e o
serviço ao qual a solicitação foi feita.

credential_scope = datestamp + "/" + region + "/" + service + "/" + "aws4_request"

6. Crie a string de consulta canônica. Os valores de string de consulta devem ser codificados pelo URL e
classificados por nome.

canonical_querystring = "X-Amz-Algorithm=" + algorithm


canonical_querystring += "&X-Amz-Credentials="+ access key + "/" + credential_scope
canonical_querystring += "&X-Amz-Date=" + amz_date
canonical_querystring += "&X-Amz-Expires=300"
canonical_querystring += "&X-Amz-Security-Token=" + token
canonical_querystring += "&X-Amz-SignedHeaders=" + signed_headers
canonical_querystring += "&language-code=en-US&media-encoding=pcm&sample-rate=16000"

7. Crie um hash da carga. Para uma solicitação GET, a carga é uma string vazia.

payload_hash = HashSHA256(("").Encode("utf-8")).HexDigest()

8. Por fim, combine todos os elementos para criar a solicitação canônica.

canonical_request = method + '\n'


+ canonical_uri + '\n'
+ canonical_querystring + '\n'
+ canonical_headers + '\n'
+ signed_headers + '\n'
+ payload_hash

Tarefa 2: Criar a string para assinar

A string para assinar inclui metainformações sobre sua solicitação. Você usará a string para assinar na
próxima etapa, quando calcular a assinatura da solicitação. Para obter mais informações, consulte Criar
uma string de assinatura para o Signature versão 4 na Referência geral da Amazon Web Services.

• Crie a string.

string_to_sign=algorithm + "\n"
+ amz_date + "\n"
+ credential_scope + "\n"
+ HashSHA256(canonical_request.Encode("utf-8").HexDigest()

Tarefa 3: Calcular a assinatura

Você derivará uma chave de assinatura da sua chave de acesso secreta da AWS. Para obter um grau
maior de proteção, a chave derivada é específica à data, ao serviço e à Região da AWS. Você usa a
chave derivada para assinar a solicitação. Para obter mais informações, consulte Calcular a assinatura do
Signature versão 4 da AWS na Referência geral da Amazon Web Services.

50
Amazon Transcribe Guia do desenvolvedor
Criação de uma Pre-Signed URL

O código pressupõe que você tenha implementado a função GetSignatureKey para gerar uma chave de
assinatura. Para obter mais informações e exemplos de funções, consulte Exemplos de como derivar uma
chave de assinatura do Signature versão 4 na Referência geral da Amazon Web Services.

A função HMAC(key, data) representa uma função HMAC-SHA256 que retorna os resultados em
formato binário.

• Crie a chave de assinatura e assine a string para assinar.

ɛCreate the signing key.


signing_key = GetSignatureKey(secret_key, datestamp, region, service)

ɛ Sign the string_to_sign using the signing key


signature = HMAC.new(signing_key, (string_to_sign).Encode("utf-8"), Sha256()).HexDigest

Tarefa 4: Adicionar informações de assinatura à solicitação e criar o URL da solicitação

Depois de calcular a assinatura, adicione-a à string de consulta. Para obter mais informações, consulte
Adicione a assinatura à solicitação HTTP na Referência geral da Amazon Web Services.

1. Adicione as informações de autenticação à string de consulta.

canonical_querystring += "&X-Amz-Signature=" + signature

2. Crie o URL para a solicitação.

request_url = endpoint + canonical_uri + "?" + canonical_querystring

Você usa o URL solicitado com sua biblioteca WebSocket para fazer a solicitação ao serviço do Amazon
Transcribe.

Incluir cabeçalhos de solicitação WebSocket


A solicitação ao Amazon Transcribe deve incluir os cabeçalhos a seguir. Geralmente, esses cabeçalhos
são gerenciados pela sua biblioteca de cliente WebSocket.

Host: transcribestreaming.region.amazonaws.com:8443
Connection: Upgrade
Upgrade: websocket
Origin: request source
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: random key

Use os seguintes valores para os cabeçalhos:

• Connection – sempre Upgrade.


• Upgrade – sempre websocket.
• Origin – o URI do cliente WebSocket.
• Sec-WebSocket-Version – a versão do protocolo WebSocket a ser usada.
• Sec-WebSocket-chave – uma string codificada com base-64 e gerada aleatoriamente que identifica a
solicitação.

51
Amazon Transcribe Guia do desenvolvedor
Manipular a resposta de atualização do WebSocket

Manipular a resposta de atualização do WebSocket


Quando o Amazon Transcribe receber sua solicitação WebSocket, ele responderá com uma resposta
de atualização WebSocket. Em geral, sua biblioteca WebSocket gerencia essa resposta e configura um
soquete para as comunicações com o Amazon Transcribe

Veja a seguir a resposta do Amazon Transcribe. Quebras de linha foram adicionadas ao cabeçalho
websocket-location para uma melhor leitura.

HTTP/1.1 101 Web Socket Protocol Handshake

Connection: upgrade
Upgrade: websocket
websocket-origin: https://transcribestreaming.region.amazonaws.com:8443
websocket-location: transcribestreaming.region.amazonaws.com:8443/stream-transcription-
websocket?
X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIDEXAMPLE%2F20190117%2Fregion%2Ftranscribe
%2Faws4_request
&X-Amz-Date=date and time
&X-Amz-Expires=expiration length
&X-Amz-SignedHeaders=host
&language-code=language code
&media-encoding=media encoding
&sample-rate=media sample rate
&X-Amz-Signature=signature
x-amzn-RequestId: RequestId
x-amzn-SessionId: SessionId
Strict-Transport-Security: max-age=31536000
sec-websocket-accept: token

A resposta tem os seguintes valores:

• Connection – sempre Upgrade.


• Upgrade – sempre websocket.
• websocket-origin – o URI do servidor WebSocket que respondeu à solicitação.
• websocket-location – o conteúdo do URI da solicitação enviado ao servidor. Para ver uma descrição
do conteúdo, consulte Criação de uma Pre-Signed URL (p. 48).
• x-amzn-RequestId – um identificador da solicitação.
• x-amzn-SessionId – um identificador de uma sessão de transcrição
• Strict-Transport-Security – um cabeçalho que informa aos navegadores para acessar o
endpoint usando apenas HTTPS.
• sec-websocket-accept – o hash do cabeçalho Sec-WebSocket-Key enviado na solicitação.

Criar uma solicitação de streaming WebSocket


Após a conexão WebSocket ser estabelecida, o cliente pode começar a enviar uma sequência de quadros
WebSocket binários. Cada quadro contém um quadro de dados com codificação de fluxo de evento. Para
mais informações, consulte Codificação de fluxo de evento (p. 46).

Cada quadro de dados contém três cabeçalhos combinados com um bloco de bytes de áudio bruto. A
tabela a seguir lista e descreve os cabeçalhos.

52
Amazon Transcribe Guia do desenvolvedor
Manipular uma resposta de streaming WebSocket

Comprimento em Nome do Tipo de valor de Comprimento em String de valor


bytes do nome do cabeçalho (string) cabeçalho bytes da string de (UTF-8)
cabeçalho valor

13 :content-type 7 24 application/
octet-stream

11 :event-type 7 10 AudioEvent

13 :message-type 7 5 event

Para finalizar o fluxo de dados de áudio, envie um bloco de áudio vazio em uma mensagem com
codificação de fluxo de evento.

Manipular uma resposta de streaming WebSocket


A resposta contém bytes brutos com codificação de fluxo de evento na carga. Ela contém o prelúdio
padrão e os seguintes cabeçalhos:

Comprimento em Nome do Tipo de valor de Comprimento em String de valor


bytes do nome do cabeçalho (string) cabeçalho bytes da string de (UTF-8)
cabeçalho valor

13 :content-type 7 24 application/octet-
stream

11 :event-type 7 15 TranscriptEvent

13 :message-type 7 5 event

Quando você decodifica a resposta binária, você obtém uma estrutura JSON com os resultados da
transcrição. Para obter um exemplo de resposta JSON, consulte Transcrição de streaming (p. 44).

Manipular erros de streaming WebSocket


Se uma exceção ocorrer durante o processamento da sua solicitação, o Amazon Transcribe responderá
com um quadro WebSocket terminal contendo uma resposta com codificação de fluxo de evento. A
resposta tem os cabeçalhos descritos na tabela a seguir, e o corpo da resposta contém uma mensagem
de erro descritiva. Depois de enviar a resposta de exceção, o Amazon Transcribe envia uma quadro de
fechamento.

Comprimento em Nome do Tipo de valor de Comprimento em String de valor


bytes do nome do cabeçalho (string) cabeçalho bytes da string de (UTF-8)
cabeçalho valor

13 :content-type 7 24 application/octet-
stream

15 :exception- 7 varia varia, veja abaixo


type

13 :message-type 7 9 exception

O cabeçalho exception-type contém um dos seguintes valores.

53
Amazon Transcribe Guia do desenvolvedor
Uso de streaming com HTTP/2

• BadRequestException – ocorreu um erro de cliente quando o fluxo foi criado ou ocorreu um erro
durante o streaming de dados. Certifique-se de que seu cliente esteja pronto para aceitar dados e tente
sua solicitação novamente.
• InternalFailureException – o Amazon Transcribe teve um problema durante o handshake com o
cliente. Tente sua solicitação novamente.
• LimitExceededException – o cliente excedeu o limite de fluxo simultâneo. Para obter mais
informações, consulte Limites do Amazon Transcribe na Referência geral da Amazon Web Services.
Reduza o número de fluxos que você está transcrevendo.
• UnrecognizedClientException – a solicitação de atualização WebSocket foi assinada com uma
chave de acesso ou uma chave secreta incorreta. Certifique-se de que você esteja criando corretamente
a chave de acesso e tente sua solicitação novamente.

Além disso, o Amazon Transcribe pode retornar qualquer erro de serviço comum. Para obter uma lista,
consulte Erros comuns.

Uso de streaming do Amazon Transcribe com


HTTP/2
O Amazon Transcribe usa um formato chamado de codificação de fluxo de evento para a transcrição de
streaming. Esse formato codificou dados binários com informações de cabeçalho que descreve o conteúdo
de cada evento. Para mais informações, consulte Codificação de fluxo de evento (p. 46). Você pode
usar essas informações para aplicativos que chamem o endpoint do Amazon Transcribe sem usar o SDK
do Amazon Transcribe.

Quando o Amazon Transcribe usa o protocolo HTTP/2 para a transcrição de streamings, os componentes
principais da solicitação do streaming são:

• Um quadro de cabeçalho. Ele contém os cabeçalhos HTTP/2 para a solicitação e uma assinatura no
cabeçalho authorization que o Amazon Transcribe usa como assinatura de propagação para assinar
os seguintes quadros de dados.
• Um ou mais quadros de mensagem na codificação de fluxo de evento. O quadro contém metadados e os
bytes de áudio brutos.
• Um quadro final. Esta é uma mensagem assinada na codificação do fluxo de eventos com um corpo
vazio.

Solicitação de streaming
Para fazer uma solicitação de streaming, utilize a operação StartStreamTranscription (p. 122).

Quadro de cabeçalho
O quadro do cabeçalho é o quadro da autorização para a transcrição de streaming. O Amazon Transcribe
usa o valor do cabeçalho authorization como a propagação para gerar uma cadeia de cabeçalhos de
autorização para os quadros de dados na solicitação.

Cabeçalhos obrigatórios
O quadro de cabeçalho de uma solicitação para o Amazon Transcribe requer os seguintes cabeçalhos
HTTP/2:

POST /stream-transcription HTTP/2.0

54
Amazon Transcribe Guia do desenvolvedor
Solicitação de streaming

host: transcribestreaming.region.amazonaws.com
authorization: Generated value
content-type: application/vnd.amazon.eventstream
x-amz-target: com.amazonaws.transcribe.Transcribe.StartStreamTranscription
x-amz-content-sha256: STREAMING-AWS4-HMAC-SHA256-EVENTS
x-amz-date: Date
x-amzn-transcribe-language-code: en-US
x-amzn-transcribe-media-encoding: pcm
x-amzn-transcribe-sample-rate: Sample rate
transfer-encoding: chunked

Na solicitação, use os seguintes valores para os cabeçalhos host, authorization e x-amz-date:

• host: Use a região da AWS em que você está chamando o Amazon Transcribe. Para obter uma lista
das regiões válidas, consulte Regiões e endpoints da AWS na Referência geral da Amazon Web
Services.
• authorization: A assinatura do Signature versão 4 para a solicitação. Para obter mais informações
sobre como criar uma assinatura, consulte Assinatura de solicitações da AWS com Signature versão 4
na Referência geral da Amazon Web Services.
• x-amz-date: Gerar uma data e hora para a solicitação seguindo as instruções em Tratamento de datas
no Signature versão 4 na Referência geral da Amazon Web Services.

Para obter mais informações sobre os cabeçalhos específicos do Amazon Transcribe, consulte a operação
StartStreamTranscription (p. 122).

Quadros de dados
Cada solicitação contém um ou mais quadros de dados. Os quadros de dados usam codificação de fluxo
de evento. A codificação oferece suporte a transmissão de dados bidirecional entre um cliente e um
servidor.

Existem duas etapas para criar um quadro de dados:

1. Combine os dados de áudio brutos com metadados para criar a carga da solicitação.
2. Combine a carga com uma assinatura para formar a mensagem de evento enviada para o Amazon
Transcribe.

O diagrama a seguir mostra como isso funciona.

Crie o evento de áudio


Para criar a mensagem a ser enviada para o Amazon Transcribe, crie o evento de áudio. Combine os
cabeçalhos descritos na tabela a seguir com um bloco de bytes de áudio em uma mensagem codificada
pelo evento.

55
Amazon Transcribe Guia do desenvolvedor
Solicitação de streaming

Para criar a carga para a mensagem do evento, use um buffer no formato de byte bruto.

Crie a mensagem
Crie um quadro de dados usando a carga do evento de áudio para enviar para o Amazon Transcribe.
O quadro de dados contém os cabeçalhos de codificação de evento que incluem a data atual e uma
assinatura para o bloco de áudio e para o evento de áudio. Para indicar para o Amazon Transcribe
que o fluxo de áudio está concluído, envie um quadro de dados vazio que contenha apenas a data e a
assinatura.

Para criar a assinatura para o quadro de dados, primeiro crie uma string para assinar e depois calcule a
assinatura para o evento. Construa a string para que assine como a seguir:

String stringToSign =
"AWS4-HMAC-SHA256-PAYLOAD" +
"\n" +
DATE +
"\n" +
KEYPATH +
"\n" +
Hex(priorSignature) +
"\n" +
HexHash(nonSignatureHeaders) +
"\n" +
HexHash(payload);

• DATE: A data e a hora atuais em Tempo Universal Coordenado (UTC) e usando o formato ISO 8601.
Não inclua milissegundos na data. Por exemplo, 20190127T223754Z é 22:37:54 em 1/27/2019.
• KEYPATH: O escopo da assinatura no formato date/region/service/aws4_request. Por exemplo,
20190127/us-east-1/transcribe/aws4_request.
• priorSignature: A assinatura para o quadro anterior. Para o primeiro quadro de dados, use a
assinatura do quadro do cabeçalho.
• nonSignatureHeaders: O cabeçalho DATE codificado como uma string.
• payload: O buffer de byte contendo os dados do evento de áudio.
• Hex: uma função que codifica sua entrada em uma representação hexadecimal.
• HexHash: uma função que primeiro cria um hash SHA-256 da sua entrada e usa a função Hex para
codificar o hash.

56
Amazon Transcribe Guia do desenvolvedor
Resposta de streaming

Depois que você tiver construído a string para assinar, assine usando a chave que você obteve para o
Signature versão 4, da seguinte forma. Para obter detalhes, consulte Exemplos de como obter uma chave
de assinatura do Signature versão 4 na Referência geral da Amazon Web Services.

String signature = HMACSHA256(derivedSigningKey, stringToSign);

• HMACSHA256: uma função que cria uma assinatura usando a função de hash SHA-256.
• derivedSigningKey: a chave de assinatura do Signature versão 4.
• stringToSign: A string que você calculou para os dados do quadro.

Depois de ter calculado a assinatura para o quadro de dados, construa um buffer de bytes que contenha a
data, a assinatura e a carga do evento de áudio. Envie a matriz de bytes para o Amazon Transcribe para
transcrição.

End Frame
Para indicar que o fluxo de áudio está concluído, envie um quadro final para o Amazon Transcribe. O
quadro final é um quadro de dados com uma carga vazia. Você pode construir o quadro final da mesma
forma que constrói um quadro de dados.

Resposta de streaming
As respostas do Amazon Transcribe também são enviadas usando codificação de fluxo de evento. Use
essas informações para decodificar uma resposta da operação StartStreamTranscription (p. 122).

Resposta da transcrição
Uma resposta de transcrição tem codificação de fluxo de evento. Ela contém o prelúdio padrão e os
seguintes cabeçalhos:

Para obter mais detalhes, consulte Codificação de fluxo de evento (p. 46).

Quando a resposta é decodificada, ela contém as seguintes informações:

:content-type: "application/json"
:event-type: "TranscriptEvent"
:message-type: "event"

JSON transcription information

Para ver um exemplo de estrutura JSON retornada pelo Amazon Transcribe, consulte Uso de streaming do
Amazon Transcribe com HTTP/2 (p. 54).

57
Amazon Transcribe Guia do desenvolvedor
Exemplo de solicitação e resposta

Resposta de exceção
Se houver um erro no processamento do seu fluxo de transcrição, o Amazon Transcribe envia uma
resposta de exceção. A resposta tem codificação de fluxo de evento. Para obter mais detalhes, consulte
Codificação de fluxo de evento (p. 46).

A resposta contém o prelúdio padrão e os seguintes cabeçalhos:

Quando a resposta de exceção é decodificada, ela contém as seguintes informações:

:content-type: "application/json"
:event-type: "BadRequestException"
:message-type: "exception"

Exception message

Exemplo de solicitação e resposta


Este é um exemplo de ponta a ponta de uma solicitação de transcrição de streaming. Neste exemplo,
dados binários são representados em strings codificadas por base64. Em uma resposta real, os dados são
bytes brutos.

Etapa 1: Inicie a sessão com o Amazon Transcribe


Para iniciar a sessão HTTP/2, envie uma solicitação HTTP/2 para o Amazon Transcribe:

POST /stream-transcription HTTP/2.0


host: transcribestreaming.region.amazonaws.com
authorization: Generated value
content-type: application/vnd.amazon.eventstream
x-amz-content-sha256: STREAMING-AWS4-HMAC-SHA256-EVENTS
x-amz-date: Date
x-amzn-transcribe-language-code: en-US
x-amzn-transcribe-media-encoding: pcm
x-amzn-transcribe-sample-rate: Sample rate
transfer-encoding: chunked

Etapa 2: Envie informações de autenticação para o Amazon


Transcribe
O Amazon Transcribe envia a seguinte resposta:

HTTP/2.0 200

58
Amazon Transcribe Guia do desenvolvedor
Exemplo de solicitação e resposta

x-amzn-transcribe-language-code: en-US
x-amzn-transcribe-sample-rate: Sample rate
x-amzn-request-id: 8a08df7d-5998-48bf-a303-484355b4ab4e
x-amzn-transcribe-session-id: b4526fcf-5eee-4361-8192-d1cb9e9d6887
x-amzn-transcribe-media-encoding: pcm
x-amzn-RequestId: 8a08df7d-5998-48bf-a303-484355b4ab4e
content-type: application/vnd.amazon.eventstream

Etapa 3: Crie um evento de áudio


Crie um evento de áudio que contenha os dados de áudio a serem enviados. Para obter mais detalhes,
consulte Codificação de fluxo de evento (p. 46). Os dados binários nesta solicitação são codificados em
base64. Em uma solicitação real, os dados são bytes brutos.

:content-type: "application/octet-stream"
:event-type: "AudioEvent"
:message-type: "event"

UklGRjzxPQBXQVZFZm10IBAAAAABAAEAgD4AAAB9AAACABAAZGF0YVTwPQAAAAAAAAAAAAAAAAD//wIA/f8EAA==

Etapa 4: Crie uma mensagem de evento de áudio


Crie uma mensagem de áudio que contenha os dados de áudio a serem enviados para o Amazon
Transcribe. Para obter mais detalhes, consulte Codificação de fluxo de evento (p. 46). Os dados do
evento de áudio neste exemplo são codificados em base64. Em uma solicitação real, os dados são bytes
brutos.

:date: 2019-01-29T01:56:17.291Z
:chunk-signature: signature

AAAA0gAAAIKVoRFcTTcjb250ZW50LXR5cGUHABhhcHBsaWNhdGlvbi9vY3RldC1zdHJlYW0LOmV2ZW50LXR5
cGUHAApBdWRpb0V2ZW50DTptZXNzYWdlLXR5cGUHAAVldmVudAxDb256ZW50LVR5cGUHABphcHBsaWNhdGlv
bi94LWFtei1qc29uLTEuMVJJRkY88T0AV0FWRWZtdCAQAAAAAQABAIA+AAAAfQAAAgAQAGRhdGFU8D0AAAAA
AAAAAAAAAAAA//8CAP3/BAC7QLFf

Etapa 5: Use a Resposta do Amazon Transcribe


O Amazon Transcribe cria um fluxo de eventos de transcrição que ele envia para seu aplicativo. Os
eventos são enviados no formato de byte bruto. Neste exemplo, os bytes são codificados em base64.

A resposta do Amazon Transcribe é:

AAAAUwAAAEP1RHpYBTpkYXRlCAAAAWiXUkMLEDpjaHVuay1zaWduYXR1cmUGACCt6Zy+uymwEK2SrLp/zVBI
5eGn83jdBwCaRUBJA+eaDafqjqI=

Para ver os resultados de transcrição, decodifique os bytes brutos usando a codificação de fluxo de
eventos:

59
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

:event-type: "TranscriptEvent"
:content-type: "application/json"
:message-type: "event"

{"Transcript":{"Results":[results]}}

Para ver um exemplo de estrutura JSON retornada pelo Amazon Transcribe, consulte Codificação de fluxo
de evento (p. 46).

Etapa 6: Encerre o streaming de transcrição


Por fim, envie um evento de áudio vazio para o Amazon Transcribe para finalizar o streaming da
transcrição. Crie o evento de áudio exatamente como qualquer outro, mas com uma carga vazia. Assine o
evento e inclua a assinatura no cabeçalho :chunk-signature, da seguinte forma:

:date: 2019-01-29T01:56:17.291Z
:chunk-signature: signature

Cliente de nova tentativa de streaming HTTP/2


É possível usar o código a seguir em seus aplicativos para processar a lógica de novas tentativas para
a transcrição de streaming do Amazon Transcribe. O código fornece tolerância a falhas intermitentes na
conexão com o Amazon Transcribe. Há duas partes do cliente: uma interface que você implementa para o
seu aplicativo e o cliente de nova tentativa em si.

Código do cliente de nova tentativa de streaming


Esse código implementa um cliente de nova tentativa de streaming. Ele gerencia a conexão com o Amazon
Transcribe e tenta enviar dados novamente quando há erros na conexão. Por exemplo, se houver um erro
temporário na rede, esse cliente reenviará a solicitação que falhou.

O cliente de nova tentativa tem duas propriedades que controlam o comportamento do cliente. É possível
definir:

• O número máximo de vezes que o cliente deve tentar antes de falhar. Reduza esse valor para que o
aplicativo pare de tentar novamente mais cedo quando houver problemas de rede. O padrão é 10.
• O tempo em milissegundos que o cliente deve esperar entre novas tentativas. Períodos mais longos
aumentam o risco de perda de dados, e períodos mais curtos aumentam o risco de seu aplicativo ser
limitado. O padrão é 100 milissegundos.

Veja o cliente a seguir. É possível copiar esse código para o aplicativo ou usá-lo como ponto de partida
para seu próprio cliente.

/**
* COPYRIGHT:
* <p>
* Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* <p>
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* or in the "license" file accompanying this file. This file is distributed

60
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either


* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.transcribestreaming.retryclient;

import org.reactivestreams.Publisher;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.auth.signer.EventStreamAws4Signer;
import software.amazon.awssdk.core.client.config.SdkAdvancedClientOption;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
import software.amazon.awssdk.services.transcribestreaming.model.AudioStream;
import software.amazon.awssdk.services.transcribestreaming.model.BadRequestException;
import
software.amazon.awssdk.services.transcribestreaming.model.StartStreamTranscriptionRequest;
import
software.amazon.awssdk.services.transcribestreaming.model.StartStreamTranscriptionResponseHandler;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Arrays;
import java.util.List;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

/**
* Build a client wrapper around the Amazon Transcribe client to retry
* on an exception that can be retried.
*/
public class TranscribeStreamingRetryClient {

private static final int DEFAULT_MAX_RETRIES = 10;


private static final int DEFAULT_MAX_SLEEP_TIME_MILLS = 100;
private static final Logger log =
LoggerFactory.getLogger(TranscribeStreamingRetryClient.class);
private final TranscribeStreamingAsyncClient client;
List<Class<?>> nonRetriableExceptions = Arrays.asList(BadRequestException.class);
private int maxRetries = DEFAULT_MAX_RETRIES;
private int sleepTime = DEFAULT_MAX_SLEEP_TIME_MILLS;

/**
* Create a TranscribeStreamingRetryClient with given credential and configuration
*
* @param creds Creds to use for transcription
* @param endpoint Endpoint to use for transcription
* @param region Region to use for transcriptions
* @throws URISyntaxException if the endpoint is not a URI
*/
public TranscribeStreamingRetryClient(AwsCredentialsProvider creds,
String endpoint, Region region) throws
URISyntaxException {
this(TranscribeStreamingAsyncClient.builder()
.overrideConfiguration(
c -> c.putAdvancedOption(
SdkAdvancedClientOption.SIGNER,
EventStreamAws4Signer.create()))
.credentialsProvider(creds)
.endpointOverride(new URI(endpoint))
.region(region)
.build());
}

/**

61
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

* Initiate TranscribeStreamingRetryClient with TranscribeStreamingAsyncClient


*
* @param client TranscribeStreamingAsyncClient
*/

public TranscribeStreamingRetryClient(TranscribeStreamingAsyncClient client) {


this.client = client;
}

/**
* Get Max retries
*
* @return Max retries
*/
public int getMaxRetries() {
return maxRetries;
}

/**
* Set Max retries
*
* @param maxRetries Max retries
*/
public void setMaxRetries(int maxRetries) {
this.maxRetries = maxRetries;
}

/**
* Get sleep time
*
* @return sleep time between retries
*/
public int getSleepTime() {
return sleepTime;
}

/**
* Set sleep time between retries
*
* @param sleepTime sleep time
*/
public void setSleepTime(int sleepTime) {
this.sleepTime = sleepTime;
}

/**
* Initiate a Stream Transcription with retry.
*
* @param request StartStreamTranscriptionRequest to use to start transcription
* @param publisher The source audio stream as Publisher
* @param responseHandler StreamTranscriptionBehavior object that defines how the
response needs to be handled.
* @return Completable future to handle stream response.
*/

public CompletableFuture<Void> startStreamTranscription(final


StartStreamTranscriptionRequest request,
final Publisher<AudioStream>
publisher,
final
StreamTranscriptionBehavior responseHandler) {

CompletableFuture<Void> finalFuture = new CompletableFuture<>();

recursiveStartStream(rebuildRequestWithSession(request), publisher,
responseHandler, finalFuture, 0);

62
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

return finalFuture;
}

/**
* Recursively call startStreamTranscription() to be called till the request is
completed or till we run out of retries.
*
* @param request StartStreamTranscriptionRequest
* @param publisher The source audio stream as Publisher
* @param responseHandler StreamTranscriptionBehavior object that defines how the
response needs to be handled.
* @param finalFuture final future to finish on completing the chained futures.
* @param retryAttempt Current attempt number
*/
private void recursiveStartStream(final StartStreamTranscriptionRequest request,
final Publisher<AudioStream> publisher,
final StreamTranscriptionBehavior responseHandler,
final CompletableFuture<Void> finalFuture,
final int retryAttempt) {
CompletableFuture<Void> result = client.startStreamTranscription(request,
publisher,
getResponseHandler(responseHandler));
result.whenComplete((r, e) -> {
if (e != null) {
log.debug("Error occured:", e);

if (retryAttempt <= maxRetries && isExceptionRetriable(e)) {


log.debug("Retriable error occurred and will be retried.");
log.debug("Sleeping for sometime before retrying...");
try {
Thread.sleep(sleepTime);
} catch (InterruptedException e1) {
log.debug("Unable to sleep. Failed with exception: ", e);
e1.printStackTrace();
}
log.debug("Making retry attempt: " + (retryAttempt + 1));
recursiveStartStream(request, publisher, responseHandler, finalFuture,
retryAttempt + 1);
} else {
log.error("Encountered unretriable exception or ran out of retries. ");
responseHandler.onError(e);
finalFuture.completeExceptionally(e);
}
} else {
responseHandler.onComplete();
finalFuture.complete(null);
}
});
}

private StartStreamTranscriptionRequest
rebuildRequestWithSession(StartStreamTranscriptionRequest request) {
return StartStreamTranscriptionRequest.builder()
.languageCode(request.languageCode())
.mediaEncoding(request.mediaEncoding())
.mediaSampleRateHertz(request.mediaSampleRateHertz())
.sessionId(UUID.randomUUID().toString())
.build();
}

/**
* StartStreamTranscriptionResponseHandler implements subscriber of transcript stream
* Output is printed to standard output
*/
private StartStreamTranscriptionResponseHandler getResponseHandler(

63
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

StreamTranscriptionBehavior transcriptionBehavior) {
final StartStreamTranscriptionResponseHandler build =
StartStreamTranscriptionResponseHandler.builder()
.onResponse(r -> {
transcriptionBehavior.onResponse(r);
})
.onError(e -> {
//Do nothing here. Don't close any streams that shouldn't be cleaned up
yet.
})
.onComplete(() -> {
//Do nothing here. Don't close any streams that shouldn't be cleaned up
yet.
})

.subscriber(event -> transcriptionBehavior.onStream(event))


.build();
return build;
}

/**
* Check if the exception can be retried.
*
* @param e Exception that occurred
* @return True if the exception is retriable
*/
private boolean isExceptionRetriable(Throwable e) {
e.printStackTrace();

return nonRetriableExceptions.contains(e.getClass());
}

public void close() {


this.client.close();
}

Código da interface do cliente de nova tentativa de streaming


Essa interface é semelhante ao manipulador de resposta usado no exemplo de conceitos básicos. Ela
implementa os mesmos manipuladores de eventos. Implemente essa interface para usar o cliente de nova
tentativa de streaming.

/**
* COPYRIGHT:
* <p>
* Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* <p>
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.transcribestreaming.retryclient;

64
Amazon Transcribe Guia do desenvolvedor
Cliente de nova tentativa HTTP/2

import
software.amazon.awssdk.services.transcribestreaming.model.StartStreamTranscriptionResponse;
import software.amazon.awssdk.services.transcribestreaming.model.TranscriptResultStream;

/**
* Defines how a stream response should be handled.
* You should build a class implementing this interface to define the behavior.
*/
public interface StreamTranscriptionBehavior {
/**
* Defines how to respond when encountering an error on the stream transcription.
*
* @param e The exception
*/
void onError(Throwable e);

/**
* Defines how to respond to the Transcript result stream.
*
* @param e The TranscriptResultStream event
*/
void onStream(TranscriptResultStream e);

/**
* Defines what to do on initiating a stream connection with the service.
*
* @param r StartStreamTranscriptionResponse
*/
void onResponse(StartStreamTranscriptionResponse r);

/**
* Defines what to do on stream completion
*/
void onComplete();
}

Veja a seguir uma implementação de exemplo da interface StreamTranscriptionBehavior. Você


pode usar essa implementação ou usá-la como ponto de partida para sua própria implementação.

package com.amazonaws.transcribestreaming.retryclient;

import com.amazonaws.transcribestreaming.retryclient.StreamTranscriptionBehavior;
import software.amazon.awssdk.services.transcribestreaming.model.Result;
import
software.amazon.awssdk.services.transcribestreaming.model.StartStreamTranscriptionResponse;
import software.amazon.awssdk.services.transcribestreaming.model.TranscriptEvent;
import software.amazon.awssdk.services.transcribestreaming.model.TranscriptResultStream;

import java.util.List;

/**
* Implementation of StreamTranscriptionBehavior to define how a stream response should be
handled.
*
* COPYRIGHT:
*
* Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.

65
Amazon Transcribe Guia do desenvolvedor
Uso do cliente de nova tentativa HTTP/2

* A copy of the License is located at


*
* http://www.apache.org/licenses/LICENSE-2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
public class StreamTranscriptionBehaviorImpl implements StreamTranscriptionBehavior {

@Override
public void onError(Throwable e) {
System.out.println("=== Failure Encountered ===");
e.printStackTrace();
}

@Override
public void onStream(TranscriptResultStream e) {
// EventResultStream has other fields related to the the timestamp of the
transcripts in it.
// Please refer to the javadoc of TranscriptResultStream for more details
List<Result> results = ((TranscriptEvent) e).transcript().results();
if (results.size() > 0) {
if (results.get(0).alternatives().size() > 0)
if (!results.get(0).alternatives().get(0).transcript().isEmpty()) {
System.out.println(results.get(0).alternatives().get(0).transcript());
}
}
}

@Override
public void onResponse(StartStreamTranscriptionResponse r) {

System.out.println(String.format("=== Received Initial response. Request Id: %s


===", r.requestId()));
}

@Override
public void onComplete() {
System.out.println("=== All records stream successfully ===");
}

Próxima etapa
Uso do cliente de nova tentativa HTTP/2 (p. 66)

Uso do cliente de nova tentativa HTTP/2


Veja a seguir um aplicativo de exemplo que usa o cliente de nova tentativa para transcrever o áudio de um
arquivo ou do microfone. Você pode usar esse aplicativo para testar o cliente, ou usá-lo como ponto de
partida para seus próprios aplicativos.

Para executar o exemplo, faça o seguinte:

• Copie o cliente de nova tentativa para seu espaço de trabalho. Consulte Código do cliente de nova
tentativa de streaming (p. 60).
• Copie a interface do cliente de nova tentativa para seu espaço de trabalho. Implemente a interface,
ou use a implementação de exemplo. Consulte Código da interface do cliente de nova tentativa de
streaming (p. 64).
• Copie o aplicativo de exemplo para seu espaço de trabalho Compile e execute o aplicativo.

66
Amazon Transcribe Guia do desenvolvedor
Uso do cliente de nova tentativa HTTP/2

/**
* COPYRIGHT:
* <p>
* Copyright 2018-2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
* <p>
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
* <p>
* http://www.apache.org/licenses/LICENSE-2.0
* <p>
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.transcribestreaming.retryclient;

import com.amazonaws.transcribestreaming.TranscribeStreamingDemoApp;
import org.reactivestreams.Publisher;
import org.reactivestreams.Subscriber;
import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider;
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.transcribestreaming.model.AudioStream;
import software.amazon.awssdk.services.transcribestreaming.model.LanguageCode;
import
software.amazon.awssdk.services.transcribestreaming.model.StartStreamTranscriptionRequest;

import javax.sound.sampled.LineUnavailableException;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.InputStream;
import java.net.URISyntaxException;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

import static com.amazonaws.transcribestreaming.TranscribeStreamingDemoApp.getCredentials;

public class StreamingRetryApp {


private static final String endpoint = "endpoint";
private static final Region region = Region.US_EAST_1;
private static final int sample_rate = 28800;
private static final String encoding = " ";
private static final String language = LanguageCode.EN_US.toString();

public static void main(String args[]) throws URISyntaxException, ExecutionException,


InterruptedException, LineUnavailableException, FileNotFoundException {
/**
* Create Transcribe streaming retry client using AWS credentials.
*/

TranscribeStreamingRetryClient client = new


TranscribeStreamingRetryClient(EnvironmentVariableCredentialsProvider.create() ,endpoint,
region);

StartStreamTranscriptionRequest request = StartStreamTranscriptionRequest.builder()


.languageCode(language)
.mediaEncoding(encoding)
.mediaSampleRateHertz(sample_rate)
.build();
/**
* Start real-time speech recognition. The Transcribe streaming java client uses
the Reactive-streams

67
Amazon Transcribe Guia do desenvolvedor
Uso do cliente de nova tentativa HTTP/2

* interface. For reference on Reactive-streams:


* https://github.com/reactive-streams/reactive-streams-jvm
*/
CompletableFuture<Void> result = client.startStreamTranscription(
/**
* Request parameters. Refer to API documentation for details.
*/
request,
/**
* Provide an input audio stream.
* For input from a microphone, use getStreamFromMic().
* For input from a file, use getStreamFromFile().
*/
new AudioStreamPublisher(
new FileInputStream(new File("FileName"))),
/**
* Object that defines the behavior on how to handle the stream
*/
new StreamTranscriptionBehaviorImpl());

/**
* Synchronous wait for stream to close, and close client connection
*/
result.get();
client.close();
}

private static class AudioStreamPublisher implements Publisher<AudioStream> {


private final InputStream inputStream;

private AudioStreamPublisher(InputStream inputStream) {


this.inputStream = inputStream;
}

@Override
public void subscribe(Subscriber<? super AudioStream> s) {
if (s.currentSubscription == null) {
this.currentSubscription = new
TranscribeStreamingDemoApp.SubscriptionImpl(s, inputStream);
} else {
this.currentSubscription.cancel();
this.currentSubscription = new
TranscribeStreamingDemoApp.SubscriptionImpl(s, inputStream);
}
s.onSubscribe(currentSubscription);
}
}
}

68
Amazon Transcribe Guia do desenvolvedor
Proteção de dados

Segurança no Amazon Transcribe


A segurança da nuvem na AWS é a nossa maior prioridade. Como cliente da AWS, você se beneficiará
de um datacenter e de uma arquitetura de rede criados para atender aos requisitos das empresas com as
maiores exigências de segurança.

A segurança é uma responsabilidade compartilhada entre a AWS e você. O modelo de responsabilidade


compartilhada descreve a segurança da nuvem e a segurança na nuvem:

• Segurança da nuvem – A AWS é responsável pela proteção da infraestrutura que executa serviços
da AWS na nuvem da AWS. A AWS também fornece serviços que você pode usar com segurança.
Auditores de terceiros testam e verificam regularmente a eficácia da nossa segurança como parte dos
programas de conformidade da AWS. Para saber mais sobre os programas de conformidade que se
aplicam ao Amazon Transcribe, consulte Serviços da AWS no escopo pelo programa de conformidade.
• Segurança na nuvem – Sua responsabilidade é determinada pelo serviço da AWS que você usa. Você
também é responsável por outros fatores, incluindo a confidencialidade de seus dados, os requisitos de
sua empresa e as leis e regulamentos aplicáveis.

Esta seção ajuda você a entender como aplicar o modelo de responsabilidade compartilhada ao usar o
Amazon Transcribe. Os tópicos a seguir mostram como configurar o Amazon Transcribe para atender a
seus objetivos de segurança e conformidade. Você também aprende a usar outros serviços da AWS que
ajudam a monitorar e a proteger os recursos do Amazon Transcribe.

Tópicos
• Proteção de dados no Amazon Transcribe (p. 69)
• Identity and Access Management para Amazon Transcribe (p. 71)
• Registro em log e monitoramento no Amazon Transcribe (p. 83)
• Validação de conformidade do Amazon Transcribe (p. 88)
• Resiliência no Amazon Transcribe (p. 88)
• Segurança da infraestrutura no Amazon Transcribe (p. 89)

Proteção de dados no Amazon Transcribe


O Amazon Transcribe está em conformidade com o modelo de responsabilidade compartilhada da
AWS, que inclui regulamentos e diretrizes de proteção de dados. A AWS é responsável por proteger a
infraestrutura global que executa todos os serviços da AWS. A AWS mantém controle sobre os dados
hospedados nessa infraestrutura, incluindo os controles de configuração de segurança para lidar com o
conteúdo e os dados pessoais do cliente. Os clientes da AWS e os parceiros do APN, que atuam como
controladores ou processadores de dados, são responsáveis por todos os dados pessoais que colocam na
Nuvem AWS.

Para fins de proteção de dados, recomendamos que você proteja as credenciais da conta da AWS e
configure contas de usuário individuais com o AWS Identity and Access Management (IAM), de modo que
cada usuário receba somente as permissões necessárias para cumprir suas funções. Recomendamos
também que você proteja seus dados das seguintes formas:

• Use uma autenticação multifator (MFA) com cada conta.


• Use SSL/TLS para se comunicar com os recursos da AWS.

69
Amazon Transcribe Guia do desenvolvedor
Criptografia em repouso

• Configure a API e o registro em log das atividades do usuário com o AWS CloudTrail.
• Use as soluções de criptografia da AWS, juntamente com todos os controles de segurança padrão nos
serviços da AWS.
• Use serviços gerenciados de segurança avançada, como o Amazon Macie, que ajudam a localizar e
proteger dados pessoais que são armazenados no Amazon Simple Storage Service (Amazon S3).

É altamente recomendável que você nunca coloque informações de identificação confidenciais, como os
números de contas de seus clientes, em campos de formato livre, como um campo Name (Nome). Isso
inclui quando você trabalhar com o Amazon Transcribe ou outros serviços da AWS usando o console,
a API, a AWS CLI ou os AWS SDKs. Todos os dados inseridos por você no Amazon Transcribe ou em
outros serviços podem ser separados para inclusão em logs de diagnóstico. Ao fornecer um URL para um
servidor externo, não inclua informações de credenciais no URL para validar a solicitação a esse servidor.

Para obter mais informações sobre a proteção de dados, consulte a postagem AWS Shared Responsibility
Model and GDPR no Blog de segurança da AWS.

Tópicos
• Criptografia em repouso (p. 70)
• Criptografia em trânsito (p. 70)
• Gerenciamento de chaves (p. 70)

Criptografia em repouso
O Amazon Transcribe usa a chave padrão do Amazon S3 (SSE-S3) para a criptografia no lado do servidor
de transcrições colocadas em seu bucket do S3.

Ao usar a operação StartTranscriptionJob (p. 114), você pode especificar sua própria chave AWS Key
Management Service para criptografar a saída de uma tarefa de transcrição.

O Amazon Transcribe usa um volume do Amazon EBS criptografado com a chave padrão.

Criptografia em trânsito
Amazon Transcribe usa o TLS 1.2 com certificados AWS para criptografar dados em trânsito. Isso inclui a
transcrição de streaming.

Gerenciamento de chaves
O Amazon Transcribe trabalha com o AWS Key Management Service (KMS) para fornecer criptografia
aprimorada para seus dados. O Amazon S3 já permite criptografar o áudio de entrada ao criar
uma tarefa de transcrição. A integração com o KMS permite criptografar a saída da operação
StartTranscriptionJob (p. 114).

Se você não especificar uma chave de criptografia, a saída da tarefa de transcrição será criptografada com
a chave padrão do Amazon S3 (SSE-S3).

Criptografia KMS com o Console AWS


Para criptografar a saída da tarefa de transcrição, você pode optar entre usar uma chave de criptografia
para a conta que está fazendo a solicitação ou usar uma chave de criptografia de outra conta.

Se você não especificar uma chave de criptografia, a saída da tarefa de transcrição será criptografada com
a chave padrão do Amazon S3 (SSE-S3).

70
Amazon Transcribe Guia do desenvolvedor
Identity and Access Management

Para habilitar a criptografia de resultado de saída

1. Em Output data (Dados de saída), escolha Encryption (Criptografia).

2. Escolha se a chave gerenciada pelo cliente KMS (CMK) é da conta que você está usando no
momento ou de uma conta diferente. Se desejar usar uma chave da conta atual, escolha a chave
de KMS key ID (ID da chave KMS). Se estiver usando uma chave de uma conta diferente, você
precisará inserir o ARN da chave. Para usar uma chave de uma conta diferente, o chamador deve ter
permissões kms:Encrypt para a chave KMS.

Criptografia KMS com a API


Para usar a criptografia de saída com a API, defina o parâmetro OutputEncryptionKMSKeyId da
operação StartTranscriptionJob (p. 114). Você pode usar uma chave de criptografia da conta atual ou
usar uma chave de outra conta. A conta que você está usando para criar a tarefa deve ter permissões
kms:Encrypt para a chave KMS.

Você pode usar uma das seguintes opções para identificar uma chave KMS na conta atual:

• ID da chave KMS: “1234abcd-12ab-34cd-56ef-1234567890ab”


• Alias da chave KMS: "alias/ExampleAlias"

Você pode usar uma das seguintes opções para identificar uma chave KMS na conta atual ou em outra
conta:

• Nome de recurso da Amazon (ARN) de uma chave KMS: "arn:aws:kms:region:account


ID:key/1234abcd-12ab-34cd-56ef-1234567890ab"
• ARN de um alias de chave KMS: “arn:aws:kms:region:account ID:alias/ExampleAlias”

Identity and Access Management para Amazon


Transcribe
O AWS Identity and Access Management (IAM) é um serviço da AWS que ajuda um administrador a
controlar com segurança o acesso aos recursos da AWS. Os administradores do IAM controlam quem
pode ser autenticado (conectado) e autorizado (ter permissões) para usar os recursos do Amazon
Transcribe. O IAM é um serviço da AWS que pode ser usado sem custo adicional.

Tópicos
• Público (p. 72)
• Autenticação com identidades (p. 72)

71
Amazon Transcribe Guia do desenvolvedor
Público

• Gerenciamento do acesso usando políticas (p. 74)


• Como o Amazon Transcribe funciona com o IAM (p. 76)
• Exemplos de políticas baseadas em identidade do Amazon Transcribe (p. 77)
• Solução de problemas de identidade e acesso do Amazon Transcribe (p. 81)

Público
O uso do AWS Identity and Access Management (IAM) varia, dependendo do trabalho que você realiza no
Amazon Transcribe.

Usuário do serviço – se você usar o Amazon Transcribe para fazer sua tarefa, o administrador fornecerá as
credenciais e as permissões de que você precisa. À medida que usar mais recursos do Amazon Transcribe
para fazer seu trabalho, você poderá precisar de permissões adicionais. Entender como o acesso é
gerenciado pode ajudar você a solicitar as permissões corretas ao seu administrador. Se não for possível
acessar um recurso no Amazon Transcribe, consulte Solução de problemas de identidade e acesso do
Amazon Transcribe (p. 81).

Administrador do serviço – se você for o responsável pelos recursos do Amazon Transcribe em sua
empresa, você provavelmente terá acesso total ao Amazon Transcribe. Seu trabalho é determinar
quais recursos do Amazon Transcribe seus funcionários devem acessar. Assim, é necessário enviar
solicitações ao administrador do IAM para alterar as permissões dos usuários de seu serviço. Revise as
informações nesta página para entender os conceitos básicos do IAM. Para saber mais sobre como sua
empresa pode usar o IAM com o Amazon Transcribe, consulte Como o Amazon Transcribe funciona com o
IAM (p. 76).

Administrador do IAM – se você é um administrador do IAM, talvez queira saber detalhes sobre como pode
escrever políticas para gerenciar o acesso ao Amazon Transcribe. Para visualizar exemplos de políticas
baseadas em identidade do Amazon Transcribe que podem ser usadas no IAM, consulte Exemplos de
políticas baseadas em identidade do Amazon Transcribe (p. 77).

Autenticação com identidades


A autenticação é a forma como você faz login na AWS usando suas credenciais de identidade. Para obter
mais informações sobre como fazer login usando o Console de gerenciamento da AWS, consulte A página
de login e do console do IAM no Guia do usuário do IAM.

Você deve ser autenticado (fazer login na AWS) como o Usuário raiz da conta da AWS, um usuário do
IAM, ou assumindo uma função do IAM. Também é possível usar a autenticação de logon único da sua
empresa, ou até mesmo fazer login usando o Google ou o Facebook. Nesses casos, seu administrador
configurou anteriormente a federação de identidades usando funções do IAM. Ao acessar a AWS usando
credenciais de outra empresa, você estará assumindo uma função indiretamente.

Para fazer login diretamente no Console de gerenciamento da AWS, use sua senha com o e-mail do
usuário raiz ou seu nome de usuário do IAM. É possível acessar a AWS de maneira programática usando
seu usuário raiz ou as chaves de acesso do usuário do IAM. A AWS fornece ferramentas do SDK ou da
linha de comando para assinar sua solicitação de forma criptográfica usando suas credenciais. Se você
não utilizar ferramentas da AWS, cadastre a solicitação você mesmo. Faça isso usando o Signature versão
4, um protocolo para autenticação de solicitações de API de entrada. Para obter mais informações sobre a
autenticação de solicitações, consulte Processo de cadastramento do Signature versão 4 na AWS General
Reference.

Independentemente do método de autenticação usado, também pode ser exigido que você forneça
informações adicionais de segurança. Por exemplo, a AWS recomenda o uso da autenticação multifator
(MFA) para aumentar a segurança de sua conta. Para saber mais, consulte Usar o Multi-Factor
Authentication (MFA) na AWS no Guia do usuário do IAM.

72
Amazon Transcribe Guia do desenvolvedor
Autenticação com identidades

Usuário raiz da conta da AWS


Ao criar uma conta da AWS, você começa com uma única identidade de login que tenha acesso total a
todos os recursos e serviços da AWS na conta. Essa identidade é chamada de AWS da conta da usuário
raiz e é acessada pelo login com o endereço de e-mail e a senha que você usou para criar a conta.
Recomendamos que não use o usuário raiz para suas tarefas diárias, nem mesmo as administrativas.
Em vez disso, siga as melhores práticas de uso do usuário raiz somente para criar seu primeiro usuário
do IAM. Depois, armazene as credenciais usuário raiz com segurança e use-as para executar apenas
algumas tarefas de gerenciamento de contas e de serviços.

Grupos e usuários do IAM


Um usuário do IAM é uma identidade em sua conta da AWS que tem permissões específicas para uma
única pessoa ou um único aplicativo. Um usuário do IAM pode ter credenciais de longo prazo, como um
nome de usuário e uma senha ou um conjunto de chaves de acesso. Para saber como gerar chaves de
acesso, consulte Gerenciar chaves de acesso para usuários do IAM no Guia do usuário do IAM. Ao gerar
chaves de acesso para um usuário do IAM, visualize e salve o par de chaves de maneira segura. Não será
possível recuperar a chave de acesso secreta futuramente. Em vez disso, você deverá gerar outro par de
chaves de acesso.

Um grupo do IAM é uma identidade que especifica uma coleção de usuários do IAM. Não é possível
fazer login como um grupo. É possível usar grupos para especificar permissões para vários usuários de
uma vez. Os grupos facilitam o gerenciamento de permissões para grandes conjuntos de usuários. Por
exemplo, você pode ter um grupo chamado Administradores do IAM e atribuir a esse grupo permissões
para administrar recursos do IAM.

Usuários são diferentes de funções. Um usuário é exclusivamente associado a uma pessoa ou a um


aplicativo, mas uma função pode ser assumida por qualquer pessoa que precisar dela. Os usuários têm
credenciais permanentes de longo prazo, mas as funções fornecem credenciais temporárias. Para saber
mais, consulte Quando criar um usuário do IAM (em vez de uma função) no Guia do usuário do IAM.

Funções do IAM
Uma função do IAM é uma identidade dentro de sua conta da AWS que tem permissões específicas.
Ela é semelhante a um usuário do IAM, mas não está associada a uma pessoa específica. É possível
assumir temporariamente uma função do IAM no Console de gerenciamento da AWS alternando funções.
É possível assumir uma função chamando uma operação de API da AWS CLI ou da AWS, ou usando um
URL personalizado. Para obter mais informações sobre os métodos para o uso de funções, consulte Usar
funções do IAM no Guia do usuário do IAM.

As funções do IAM com credenciais temporária são úteis nas seguintes situações:

• Permissões temporárias para usuários do IAM – um usuário do IAM pode assumir uma função do IAM
para obter temporariamente permissões diferentes para uma tarefa específica.
• Acesso de usuário federado – Em vez de criar um usuário do IAM, você pode usar identidades
existentes do AWS Directory Service, do diretório de usuário da sua empresa ou de um provedor de
identidades da Web. Estes são conhecidos como usuários federados. A AWS atribui uma função a um
usuário federado quando o acesso é solicitado por meio de um provedor de identidades. Para obter mais
informações sobre usuários federados, consulte Usuários federados e funções no Guia do usuário do
IAM.
• Acesso entre contas – é possível usar uma função do IAM para permitir que alguém (um principal
confiável) em outra conta acesse recursos em sua conta. As funções são a principal forma de conceder
acesso entre contas. No entanto, alguns serviços da AWS permitem que você anexe uma política
diretamente a um recurso (em vez de usar uma função como proxy). Para saber a diferença entre
funções e políticas baseadas em recurso para acesso entre contas, consulte Como as funções do IAM
diferem das políticas baseadas em recurso no Guia do usuário do IAM.

73
Amazon Transcribe Guia do desenvolvedor
Gerenciamento do acesso usando políticas

• Acesso a serviços da AWS – Uma função de serviço é uma função do IAM que um serviço assume
para realizar ações em seu nome na sua conta. Ao configurar alguns ambientes de serviço da AWS,
você deve definir uma função a ser assumida pelo serviço. Essa função de serviço deve incluir todas
as permissões necessárias para o serviço acessar os recursos da AWS de que precisa. As funções de
serviço variam de acordo com o serviço, mas muitas permitem que você escolha as permissões, desde
que atenda aos requisitos documentados para esse serviço. As funções de serviço fornecem acesso
apenas dentro de sua conta e não podem ser usadas para conceder acesso a serviços em outras
contas. Você pode criar, modificar e excluir uma função de serviço no IAM. Por exemplo, você pode
criar uma função que permita que Amazon Redshift acesse um bucket do Amazon S3 em seu nome e
carregue dados desse bucket em um cluster Amazon Redshift. Para obter mais informações, consulte
Criar uma função para delegar permissões a um serviço da AWS no Guia do usuário do IAM.
• Aplicativos em execução no Amazon EC2 –Você pode usar uma função do IAM para gerenciar
credenciais temporárias para aplicativos que estão sendo executados em uma instância do EC2 e que
fazem solicitações de API da AWS CLI ou AWS. É preferível fazer isso do que armazenar chaves de
acesso na instância do EC2. Para atribuir uma função da AWS a uma instância do EC2 e disponibilizá-
la para todos os seus aplicativos, crie um perfil de instância que esteja anexado à instância. Um perfil
de instância contém a função e permite que programas que estão em execução na instância do EC2
obtenham credenciais temporárias. Para mais informações, consulte Uso de uma função do IAM para
conceder permissões aos aplicativos em execução nas instâncias do Amazon EC2 no Guia do usuário
do IAM.

Para saber se você deve usar funções do IAM, consulte Quando criar uma função do IAM (em vez de um
usuário) no Guia do usuário do IAM.

Gerenciamento do acesso usando políticas


Você controla o acesso na AWS criando políticas e anexando-as às identidades do IAM ou aos recursos
da AWS. Uma política é um objeto na AWS que, quando associado a uma identidade ou a um recurso,
define suas permissões. A AWS avalia essas políticas quando uma entidade (usuário raiz, usuário do
IAM ou função do IAM) faz uma solicitação. As permissões nas políticas determinam se a solicitação será
permitida ou negada. A maioria das políticas são armazenadas na AWS como documentos JSON. Para
obter mais informações sobre a estrutura e o conteúdo de documentos de políticas JSON, consulte Visão
geral de políticas JSON no Guia do usuário do IAM.

Um administrador do IAM pode usar políticas para especificar quem tem acesso aos recursos da AWS e
quais ações essas pessoas podem executar nesses recursos. Cada entidade do IAM (usuário ou função)
começa sem permissões. Em outras palavras, por padrão, os usuários não podem fazer nada, nem mesmo
alterar sua própria senha. Para dar permissão a um usuário para fazer algo, um administrador deve anexar
uma política de permissões ao usuário. Ou o administrador pode adicionar o usuário a um grupo que tenha
as permissões pretendidas. Quando um administrador concede permissões a um grupo, todos os usuários
desse grupo recebem essas permissões.

As políticas do IAM definem permissões para uma ação, independentemente do método usado
para executar a operação. Por exemplo, suponha que você tenha uma política que permite a ação
iam:GetRole. Um usuário com essa política pode obter informações de funções do Console de
gerenciamento da AWS, da AWS CLI ou da API da AWS.

Políticas baseadas em identidade


As políticas baseadas em identidade são documentos JSON de políticas de permissões que você pode
anexar a uma entidade, como um usuário, uma função ou um grupo do IAM. Essas políticas controlam
quais ações cada identidade pode realizar, em quais recursos e em que condições. Para saber como criar
uma política baseada em identidade, consulte Criar políticas do IAM no Guia do usuário do IAM.

As políticas baseadas em identidade podem ser categorizadas ainda mais como políticas em linha ou
políticas gerenciadas. As políticas em linha são anexadas diretamente a um único usuário, grupo ou

74
Amazon Transcribe Guia do desenvolvedor
Gerenciamento do acesso usando políticas

função. As políticas gerenciadas são políticas independentes que podem ser anexadas a vários usuários,
grupos e funções em sua conta da AWS. As políticas gerenciadas incluem políticas gerenciadas pela AWS
e políticas gerenciadas pelo cliente. Para saber como escolher entre uma política gerenciada ou uma
política em linha, consulte Escolher entre políticas gerenciadas e políticas em linha no Guia do usuário do
IAM.

Políticas com base em recurso


Políticas baseadas em recursos são documentos de política JSON que você anexa a um recurso, como
um bucket do Amazon S3. Os administradores do serviço podem usar essas políticas para definir quais
ações um principal especificado (função, usuário ou membro da conta) pode executar nesse recurso e sob
quais condições. As políticas baseadas em recurso são políticas em linha. Não há políticas baseadas em
recurso gerenciadas.

Listas de controle de acesso (ACLs)


As políticas de controle de acesso (ACLs) controlam quais principais (membros, usuários ou funções da
conta) têm permissões para acessar um recurso. As ACLs são semelhantes às políticas baseadas em
recurso, embora sejam o único tipo de política que não usa o formato de documento de política JSON.
O Amazon S3, o AWS WAF e a Amazon VPC são exemplos de serviços que oferecem suporte a ACLs.
Para saber mais sobre as ACLs, consulte Visão geral da lista de controle de acesso (ACL) no Guia do
desenvolvedor do Amazon Simple Storage Service.

Outros tipos de política


A AWS oferece suporte a outros tipos de política menos comuns. Esses tipos de política podem definir o
máximo de permissões concedidas a você pelos tipos de política mais comuns.

• Limites de permissões – um limite de permissões é um recurso avançado no qual você define o


máximo de permissões que uma política baseada em identidade pode conceder a uma entidade do
IAM (usuário ou função do IAM). É possível definir um limite de permissões para uma entidade. As
permissões resultantes são a interseção das políticas baseadas em identidade da entidade e seus
limites de permissões. As políticas baseadas em recurso que especificam o usuário ou a função no
campo Principal não são limitadas pelo limite de permissões. Uma negação explícita em qualquer
uma dessas políticas substitui a permissão. Para obter mais informações sobre limites de permissões,
consulte Limites de permissões para entidades do IAM no Guia do usuário do IAM.
• Políticas de controle de serviço (SCPs – Service control policies) – SCPs são políticas JSON que
especificam o máximo de permissões para uma organização ou unidade organizacional (UO) no
AWS Organizations. O AWS Organizations é um serviço para agrupamento e gerenciamento central
das várias contas da AWS que sua empresa possui. Se você habilitar todos os recursos em uma
organização, poderá aplicar políticas de controle de serviço (SCPs) a qualquer uma ou a todas as
contas. O SCP limita as permissões para entidades em contas-membro, incluindo cada Usuário raiz
da conta da AWS. Para obter mais informações sobre Organizações e SCPs, consulte Como SCPs
funcionam no Guia do usuário do AWS Organizations.
• Políticas de sessão – as políticas de sessão são políticas avançadas que você transmite como um
parâmetro quando cria de forma programática uma sessão temporária para uma função ou um usuário
federado. As permissões da sessão resultante são a interseção das políticas baseadas em identidade
do usuário ou da função e das políticas de sessão. As permissões também podem ser provenientes de
uma política baseada em recurso. Uma negação explícita em qualquer uma dessas políticas substitui a
permissão. Para obter mais informações, consulte Políticas de sessão no Guia do usuário do IAM.

Vários tipos de política


Quando vários tipos de política s aplicam a uma solicitação, é mais complicado compreender as
permissões resultantes. Para saber como a AWS determina se deve permitir uma solicitação quando

75
Amazon Transcribe Guia do desenvolvedor
Como o Amazon Transcribe funciona com o IAM

vários tipos de política estão envolvidos, consulte Lógica de avaliação de políticas no Guia do usuário do
IAM.

Para obter mais informações sobre o Identity and Access Management para o Amazon Transcribe,
continue nas seguintes páginas:

• Como o Amazon Transcribe funciona com o IAM (p. 76)


• Solução de problemas de identidade e acesso do Amazon Transcribe (p. 81)

Como o Amazon Transcribe funciona com o IAM


Antes de usar o IAM para gerenciar o acesso ao Amazon Transcribe, você deve entender quais recursos
do IAM estão disponíveis para uso com o Amazon Transcribe. Para obter uma visão de alto nível de como
o Amazon Transcribe e outros serviços da AWS funcionam com o IAM, consulte Serviços da AWS que
funcionam com o IAM no Guia do usuário do IAM.

Tópicos
• Políticas baseadas em identidade do Amazon Transcribe (p. 76)
• Funções do IAM do Amazon Transcribe (p. 77)

Políticas baseadas em identidade do Amazon Transcribe


Com as políticas baseadas em identidade do IAM, você pode especificar ações e recursos permitidos
ou negados, bem como as condições sob as quais as ações são permitidas ou negadas. O Amazon
Transcribe oferece suporte a ações, recursos e chaves de condição específicos. Para saber mais sobre
todos os elementos que você usa em uma política JSON, consulte Referência de elementos de política
JSON do IAM no Guia do usuário do IAM.

Ações
O elemento Action de uma política baseada em identidade do IAM descreve a ação ou ações específicas
que serão permitidas ou negadas pela política. As ações de política geralmente têm o mesmo nome que
a operação de API da AWS associada. A ação é usada em uma política para conceder permissões para
executar a operação associada.

As ações de políticas no Amazon Transcribe usam o seguinte prefixo antes da ação: transcribe:.
Por exemplo, para conceder a alguém permissão para executar uma instância do Amazon EC2
com a operação da API StartTranscriptionJob do Amazon Transcribe, inclua a ação
transcribe:StartTranscriptionJob na política da pessoa. As declarações de política devem incluir
um elemento Action ou NotAction. O Amazon Transcribe define ações que descrevem as tarefas que
podem ser executadas com esse serviço.

Para especificar várias ações em uma única declaração, separe-as com vírgulas, da seguinte forma.

"Action": [
"transcribe:action1",
"transcribe:action2"

Você também pode especificar várias ações usando caracteres curinga (*). Por exemplo, para especificar
todas as ações que começam com a palavra List, inclua a seguinte ação.

"Action": "transcribe:List*"

76
Amazon Transcribe Guia do desenvolvedor
Exemplos de políticas baseadas em identidade

Para obter uma lista de ações do Amazon Transcribe, consulte Actions Defined by Amazon Transcribe no
Guia do usuário do IAM.

Recursos
O Amazon Transcribe não oferece suporte a especificação de ARNs de recursos em uma política.

Chaves de condição
O Amazon Transcribe não fornece nenhuma chave de condição específica ao serviço, mas oferece suporte
ao uso de algumas chaves de condição globais. Para todas as chaves de condição globais da AWS,
consulte Chaves de contexto de condição globais da AWS no Guia do usuário do IAM.

Exemplos

Para obter exemplos de políticas baseadas em identidade do Amazon Transcribe, consulte Exemplos de
políticas baseadas em identidade do Amazon Transcribe (p. 77).

Políticas baseadas em recursos do Amazon Transcribe


O Amazon Transcribe não oferece suporte a políticas baseadas em recursos.

Funções do IAM do Amazon Transcribe


Uma função do IAM é uma entidade dentro de sua conta da AWS que tem permissões específicas.

Usar credenciais temporárias com o Amazon Transcribe


Você pode usar credenciais temporárias para fazer login com federação, assumir uma função do
IAM ou assumir uma função entre contas. As credenciais temporárias de segurança são obtidas
chamando operações da API do AWS Security Token Service (AWS STS), como AssumeRole ou
GetFederationToken.

O Amazon Transcribe oferece suporte ao uso de credenciais temporárias.

Funções vinculadas ao serviço


Funções vinculadas ao serviço permitem que os serviços da AWS acessem recursos em outros serviços
para concluir uma ação em seu nome. As funções vinculadas ao serviço aparecem em sua conta do
IAM e são de propriedade do serviço. Um administrador do IAM pode visualizar, mas não pode editar, as
permissões de funções vinculadas ao serviço.

O Amazon Transcribe não oferece suporte a funções vinculadas ao serviço.

Funções de serviço
Você pode permitir que um serviço assuma uma função de serviço em seu nome. A função permite que o
serviço acesse recursos em outros serviços para concluir uma ação em seu nome. As funções de serviço
aparecem em sua conta do IAM e são de propriedade da conta. Isso significa que um administrador do
IAM pode alterar as permissões para essa função. No entanto, isso pode impedir que o serviço funcione
como o esperado.

O Amazon Transcribe não oferece suporte a funções de serviço.

Exemplos de políticas baseadas em identidade do


Amazon Transcribe
Por padrão, os usuários e funções do IAM não têm permissão para criar ou modificar recursos do Amazon
Transcribe. Eles também não podem executar tarefas usando o Console de gerenciamento da AWS,

77
Amazon Transcribe Guia do desenvolvedor
Exemplos de políticas baseadas em identidade

a AWS CLI ou a API da AWS. Um administrador do IAM deve criar políticas do IAM que concedam
aos usuários e às funções permissão para executarem operações específicas da API nos recursos
especificados de que precisam. O administrador deve anexar essas políticas aos usuários ou grupos do
IAM que exigem essas permissões.

Para saber como criar uma política baseada em identidade do IAM usando esses exemplos de
documentos de política JSON, consulte Criar políticas no guia JSON no Guia do usuário do IAM.

Tópicos
• Melhores práticas de políticas (p. 78)
• Usar o console do Amazon Transcribe (p. 78)
• Políticas gerenciadas (predefinidas) pela AWS para o Amazon Transcribe (p. 79)
• Permissões necessárias para funções de usuários do IAM (p. 79)
• Permissões necessárias para chaves de criptografia do Amazon S3 (p. 80)
• Permitir que os usuários visualizem suas próprias permissões (p. 80)

Melhores práticas de políticas


As políticas baseadas em identidade são muito eficientes. Elas determinam se alguém pode criar, acessar
ou excluir recursos do Amazon Transcribe em sua conta. Essas ações podem incorrer em custos para sua
conta da AWS. Ao criar ou editar políticas baseadas em identidade, siga estas diretrizes e recomendações:

• Comece usando políticas gerenciadas pela AWS – para começar a usar o Amazon Transcribe
rapidamente, use as políticas gerenciadas pela AWS para conceder a seus funcionários as permissões
de que precisam. Essas políticas já estão disponíveis em sua conta e são mantidas e atualizadas pela
AWS. Para obter mais informações, consulte Conceitos básicos do uso de permissões com políticas
gerenciadas pela AWS no Guia do usuário do IAM.
• Conceder privilégio mínimo – ao criar políticas personalizadas, conceda apenas as permissões
necessárias para executar uma tarefa. Comece com um conjunto mínimo de permissões e conceda
permissões adicionais conforme necessário. Fazer isso é mais seguro do que começar com permissões
que são muito lenientes e tentar restringi-las posteriormente. Para obter mais informações, consulte
Conceder privilégio mínimo, no Guia do usuário do IAM.
• Habilitar o MFA para operações confidenciais – para segurança adicional, exija que os usuários do IAM
usem a autenticação multifator (MFA) para acessar recursos ou operações de API confidenciais. Para
obter mais informações, consulte Usar a autenticação multifator (MFA) na AWS no Guia do usuário do
IAM.
• Usar condições de política para segurança adicional – na medida do possível, defina as condições sob
as quais suas políticas baseadas em identidade permitem o acesso a um recurso. Por exemplo, você
pode gravar condições para especificar um intervalo de endereços IP permitidos do qual a solicitação
deve partir. Você também pode escrever condições para permitir somente solicitações em uma data
especificada ou período ou para exigir o uso de SSL ou MFA. Para obter mais informações, consulte
Elementos da política JSON do IAM: condição no Guia do usuário do IAM.

Usar o console do Amazon Transcribe


Para acessar o console do Amazon Transcribe, você deve ter um conjunto mínimo de permissões para
o console. Essas permissões devem permitir que você liste e visualize detalhes sobre os recursos do
Amazon Transcribe em sua conta da AWS. Se você criar uma política baseada em identidade que seja
mais restritiva que as permissões mínimas necessárias, o console não funcionará como pretendido para
entidades (usuários ou funções do IAM) com essa política.

Para garantir que essas entidades possam usar o console do Amazon Transcribe, anexe a seguinte
política gerenciada pela AWS a elas.

78
Amazon Transcribe Guia do desenvolvedor
Exemplos de políticas baseadas em identidade

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"transcribe:*"
],
"Resource": "*",
"Effect": "Allow"
}
]
}

Não é necessário conceder permissões mínimas do console para usuários que fazem chamadas somente
da AWS CLI ou da API da AWS. Em vez disso, permita o acesso somente às ações que correspondem à
operação da API que você está tentando executar.

Para obter mais informações, consulte Adicionar permissões a um usuário no Guia do usuário do IAM:

Políticas gerenciadas (predefinidas) pela AWS para o Amazon


Transcribe
A AWS aborda muitos casos de uso comuns, fornecendo políticas do IAM autônomas criadas e
administradas pela AWS. Essas políticas são chamadas de políticas gerenciadas pela AWS. As
políticas gerenciadas facilitam a atribuição de permissões apropriadas a usuários, grupos e funções em
comparação com a elaboração de suas próprias políticas. Para obter mais informações, consulte Políticas
gerenciadas pela AWS no Guia do usuário do IAM.

As seguintes políticas gerenciadas pela AWS, que você pode associar a usuários, funções e grupos em
sua conta, são específicas do Amazon Transcribe:

• ReadOnly – concede acesso somente leitura a recursos do Amazon Transcribe para que você possa
obter e listar trabalhos de transcrição e vocabulários personalizados.
• FullAccess – concede acesso total para criar, ler, atualizar, excluir e executar todos os recursos do
Amazon Transcribe. Também permite o acesso a buckets do Amazon Simple Storage Service (Amazon
S3) com transcribe no nome do bucket.

Note

Você pode analisar as políticas de permissões gerenciadas fazendo login no console do IAM e
pesquisando pelo nome da política.

Além disso, também é possível criar políticas do IAM personalizadas para conceder permissões para
ações da API do Amazon Transcribe. Você pode anexar essas políticas personalizadas a usuários,
funções ou grupos do IAM que exijam essas permissões.

Permissões necessárias para funções de usuários do IAM


Ao criar um usuário do IAM para chamar o Amazon Transcribe, a identidade deve ter permissão para
acessar o bucket do S3 e a chave do AWS Key Management Service (AWS KMS) usada para criptografar
o conteúdo do bucket, caso tenha fornecido uma.

O usuário deve ter a seguinte política do IAM para descriptografar permissões no nome de recurso da
Amazon (ARN) do KMS.

79
Amazon Transcribe Guia do desenvolvedor
Exemplos de políticas baseadas em identidade

"Version": "2012-10-17",
"Statement": [
{
"Action": [
"kms:Decrypt"
],
"Resource": "KMS key ARN",
"Effect": "Allow"
}
]
}

A política do IAM do usuário deve ter permissões do Amazon S3 para acessar o bucket do S3 em que os
arquivos de áudio são armazenados e as transcrições são salvas.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
“s3:GetObject”,
],
"Resource": "S3 bucket location"
}
]
}

Permissões necessárias para chaves de criptografia do Amazon


S3
Se você estiver usando uma chave do AWS KMS para criptografar um bucket do Amazon S3, inclua o
seguinte na política de chave do AWS KMS. Isso fornece ao Amazon Transcribe acesso ao conteúdo do
bucket.

{
"Sid": "Allow-Transcribe",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::account id:root",
},
"Action": [
"kms:Decrypt"
],
"Resource": "KMS key ARN"
}

Para obter mais informações sobre como permitir acesso às chaves mestras de clientes, consulte Permitir
que contas externas da AWS acessem uma CMK no Guia do desenvolvedor do AWS KMS.

Permitir que os usuários visualizem suas próprias permissões


Este exemplo mostra como você pode criar uma política que permite que os usuários do IAM visualizem
as políticas gerenciadas e em linha anexadas à identidade de usuário. Essa política inclui permissões para
concluir essa ação no console ou de forma programática usando a AWS CLI ou a API da AWS.

{
"Version": "2012-10-17",
"Statement": [

80
Amazon Transcribe Guia do desenvolvedor
Solução de problemas

{
"Sid": "ViewOwnUserInfo",
"Effect": "Allow",
"Action": [
"iam:GetUserPolicy",
"iam:ListGroupsForUser",
"iam:ListAttachedUserPolicies",
"iam:ListUserPolicies",
"iam:GetUser"
],
"Resource": [
"arn:aws:iam::*:user/${aws:username}"
]
},
{
"Sid": "NavigateInConsole",
"Effect": "Allow",
"Action": [
"iam:GetGroupPolicy",
"iam:GetPolicyVersion",
"iam:GetPolicy",
"iam:ListAttachedGroupPolicies",
"iam:ListGroupPolicies",
"iam:ListPolicyVersions",
"iam:ListPolicies",
"iam:ListUsers"
],
"Resource": "*"
}
]
}

Solução de problemas de identidade e acesso do


Amazon Transcribe
Use as seguintes informações para diagnosticar e corrigir problemas comuns que podem ser encontrados
ao trabalhar com o Amazon Transcribe e o AWS Identity and Access Management (IAM).

Tópicos
• Não tenho autorização para executar uma ação no Amazon Transcribe (p. 81)
• Não tenho autorização para executar iam:PassRole (p. 82)
• Quero visualizar minhas chaves de acesso (p. 82)
• Sou administrador e desejo conceder acesso ao Amazon Transcribe para outros usuários. (p. 82)
• Quero permitir que as pessoas fora da minha conta da AWS acessem meus recursos do Amazon
Transcribe (p. 83)

Não tenho autorização para executar uma ação no Amazon


Transcribe
Se estiver usando o Console de gerenciamento da AWS e receber uma mensagem informando que você
não está autorizado a executar uma ação, entre em contato com o administrador para obter assistência. O
administrador é a pessoa que lhe forneceu seu nome de usuário e senha.

Por exemplo, o seguinte erro ocorre quando um usuário do IAM chamado mateojackson IAM tenta
usar o console para visualizar detalhes sobre um trabalho de transcrição, mas não tem permissões para
transcribe:GetTranscriptionJob.

81
Amazon Transcribe Guia do desenvolvedor
Solução de problemas

User: arn:aws:iam::123456789012:user/mateojackson is not authorized to perform:


transcribe:GetTranscriptionJob

Mateo deve solicitar que o administrador atualize suas políticas para permitir que ele acesse a operação
GetTranscriptionJob usando a ação transcribe:GetTrascriptionJob.

Não tenho autorização para executar iam:PassRole


Se você receber uma mensagem de erro informando que não está autorizado a executar a ação
iam:PassRole, entre em contato com o administrador para obter assistência. O administrador é a pessoa
que forneceu a você o seu nome de usuário e senha. Peça a essa pessoa para atualizar suas políticas
para permitir que você passe uma função para o Amazon Transcribe.

Alguns serviços da AWS permitem que você passe uma função existente para o serviço, em vez de
criar uma nova função de serviço ou função vinculada ao serviço. Para fazer isso, um usuário deve ter
permissões para passar a função para o serviço.

O erro de exemplo a seguir ocorre quando uma usuária do IAM chamada marymajor tenta usar o console
para executar uma ação no Amazon Transcribe. No entanto, a ação exige que o serviço tenha permissões
concedidas por uma função de serviço. Mary não tem permissões para passar a função para o serviço.

User: arn:aws:iam::123456789012:user/marymajor is not authorized to perform: iam:PassRole

Neste caso, Mary pede ao administrador para atualizar suas políticas para permitir que ela execute a ação
iam:PassRole.

Quero visualizar minhas chaves de acesso


Depois de criar suas chaves de acesso de usuário do IAM, é possível visualizar seu ID de chave de acesso
a qualquer momento. No entanto, você não pode visualizar sua chave de acesso secreta novamente. Se
você perder sua chave secreta, crie um novo par de chaves de acesso.

As chaves de acesso consistem em duas partes: um ID de chave de acesso (por exemplo,


AKIAIOSFODNN7EXAMPLE) e uma chave de acesso secreta (por exemplo, wJalrXUtnFEMI/K7MDENG/
bPxRfiCYEXAMPLEKEY). Como um nome de usuário e uma senha, você deve usar o ID da chave de
acesso e a chave de acesso secreta em conjunto para autenticar suas solicitações. Gerencie suas chaves
de acesso de forma tão segura quanto você gerencia seu nome de usuário e sua senha.
Important

Não forneça as chaves de acesso a terceiros, mesmo que seja para ajudar a encontrar seu ID de
usuário canônico. Ao fazer isso, você pode dar a alguém acesso permanente à sua conta.

Ao criar um par de chaves de acesso, você é solicitado a guardar o ID da chave de acesso e a chave de
acesso secreta em um local seguro. A chave de acesso secreta só está disponível no momento em que é
criada. Se você perder sua chave de acesso secreta, você deverá adicionar novas chaves de acesso para
seu usuário do IAM. Você pode ter no máximo duas chaves de acesso. Se você já tiver duas, você deverá
excluir um par de chaves para poder criar um novo. Para visualizar as instruções, consulte Gerenciar
chaves de acesso no Guia do usuário do IAM.

Sou administrador e desejo conceder acesso ao Amazon


Transcribe para outros usuários.
Para permitir que outros usuários acessem o Amazon Transcribe, é necessário criar uma entidade do
IAM (usuário ou função) para a pessoa ou o aplicativo que precisa do acesso. Eles usarão as credenciais

82
Amazon Transcribe Guia do desenvolvedor
Monitoramento do Amazon Transcribe

dessa entidade para acessar a AWS. Você deve anexar uma política à entidade que concede a eles as
permissões corretas no Amazon Transcribe.

Para começar a usar imediatamente, consulte Criar os primeiros usuário e grupo delegados do IAM no
Guia do usuário do IAM.

Quero permitir que as pessoas fora da minha conta da AWS


acessem meus recursos do Amazon Transcribe
É possível criar uma função que os usuários de outras contas ou pessoas fora da sua organização podem
usar para acessar seus recursos. Você pode especificar quem é confiável para assumir a função. Para
serviços que oferecem suporte a políticas baseadas em recursos ou listas de controle de acesso (ACLs),
você pode usar essas políticas para conceder às pessoas acesso a seus recursos.

Para saber mais, consulte o seguinte:

• Para saber se o Amazon Transcribe oferece suporte a esses recursos, consulte Como o Amazon
Transcribe funciona com o IAM (p. 76).
• Para saber como conceder acesso aos seus recursos em todas as contas da AWS pertencentes a você,
consulte Conceder acesso a um usuário do IAM em outra conta da AWS pertencente a você no Guia do
usuário do IAM.
• Para saber como conceder acesso aos seus recursos para contas da AWS de terceiros, consulte
Conceder acesso a contas da AWS pertencentes a terceiros no Guia do usuário do IAM.
• Para saber como fornecer acesso por meio de federação de identidades, consulte Fornecer acesso a
usuários autenticados externamente (federação de identidades) no Guia do usuário do IAM.
• Para saber a diferença entre usar funções e políticas baseadas em recurso para acesso entre contas,
consulte Como as funções do IAM diferem de políticas baseadas em recursos no Guia do usuário do
IAM.

Registro em log e monitoramento no Amazon


Transcribe
O monitoramento é uma parte importante para manter a confiabilidade, a disponibilidade e o desempenho
dos aplicativos do Amazon Transcribe. Para monitorar as chamadas da API do Amazon Transcribe,
você pode usar o AWS CloudTrail. Para monitorar o status de seus trabalhos, use o Eventos do Amazon
CloudWatch.

Tópicos
• Monitorar chamadas da API do Amazon Transcribe com o AWS CloudTrail (p. 83)
• Uso do Eventos do Amazon CloudWatch com o Amazon Transcribe (p. 86)

Monitorar chamadas da API do Amazon Transcribe


com o AWS CloudTrail
O Amazon Transcribe é integrado ao AWS CloudTrail, um serviço que fornece um registro de ações
realizadas no Amazon Transcribe por um usuário, uma função do AWS Identity and Access Management
(IAM) ou por um serviço da AWS. O CloudTrail captura todas as chamadas de API do Amazon Transcribe,
incluindo chamadas do console do Amazon Transcribe e chamadas de código às APIs do Amazon
Transcribe, como eventos. Ao criar uma trilha, é possível habilitar a entrega contínua de eventos do

83
Amazon Transcribe Guia do desenvolvedor
Monitorar o Amazon Transcribe com o CloudTrail

CloudTrail, incluindo eventos do Amazon Transcribe, para um bucket do Amazon Simple Storage Service
(Amazon S3). Se você não criar uma trilha, ainda poderá visualizar os eventos mais recentes no console
do CloudTrail em Event history (Histórico de eventos). Usando as informações coletadas pelo CloudTrail,
é possível ver cada solicitação que foi feita ao Amazon Transcribe, o endereço IP do qual a solicitação foi
feita, quem fez a solicitação, quando ela foi feita e outros detalhes.

Para saber mais sobre CloudTrail, consulte o AWS CloudTrail User Guide.

Informações sobre o Amazon Transcribe no CloudTrail


O CloudTrail é habilitado em sua conta da AWS quando você cria a conta. Quando ocorre uma atividade
no Amazon Transcribe, ela é registrada em um evento do CloudTrail junto com outros eventos de serviços
da AWS no Event history (Histórico de eventos) do CloudTrail. Você pode visualizar, pesquisar e fazer
download de eventos recentes em sua conta da AWS. Para obter mais informações, consulte Visualizar
eventos com o histórico de eventos do CloudTrail.

Para obter um registro contínuo de eventos em sua conta da AWS, incluindo eventos do Amazon
Transcribe, crie uma trilha. Uma trilha é uma configuração que permite que o CloudTrail entregue eventos
como arquivos de log a um bucket do S3 especificado. Por padrão, quando você cria uma trilha no
console, ela é aplicada a todas as regiões da AWS. A trilha registra eventos de todas as regiões na
partição da AWS e entrega os arquivos de log para o bucket do S3 especificado. Além disso, é possível
configurar outros serviços da AWS para análise mais profunda e ação sobre os dados de eventos
coletados nos logs do CloudTrail. Para obter mais informações, consulte:

• Visão geral da criação de uma trilha


• CloudTrail Serviços compatíveis e integrações do
• Configuração de notificações do Amazon SNS para o CloudTrail
• Recebimento de arquivos de log do CloudTrail de várias regiões e Recebimento de arquivos de log do
CloudTrail de várias contas

O CloudTrail registra todas as ações do Amazon Transcribe, que são documentadas no Referência
da API (p. 94). Por exemplo, as chamadas para as operações CreateVocabulary,
GetTranscriptionJob e StartTranscriptionJob geram entradas nos arquivos de log do
CloudTrail.

Cada evento ou entrada no log contém informações sobre quem gerou a solicitação. As informações
ajudam a determinar:

• Se a solicitação foi feita com credenciais do usuário raiz ou do IAM


• Se a solicitação foi feita com credenciais de segurança temporárias de uma função do IAM ou de um
usuário federado
• Se a solicitação foi feita por outro serviço da AWS

Para obter mais informações, consulte Elemento userIdentity do CloudTrail.

Também é possível agregar arquivos de log do Amazon Transcribe de várias regiões da AWS e várias
contas da AWS em um único bucket do S3. Para obter mais informações, consulte Recebimento de
arquivos de log do CloudTrail de várias regiões e Recebimento de arquivos de log do CloudTrail de várias
contas.

Exemplo: entradas no arquivo de log do Amazon Transcribe


Uma trilha é uma configuração que permite a entrega de eventos como arquivos de log em um bucket
do S3 especificado. Os arquivos de log do CloudTrail contêm uma ou mais entradas no log. Um evento
representa uma única solicitação de qualquer origem e inclui informações sobre a ação solicitada, a data e

84
Amazon Transcribe Guia do desenvolvedor
Monitorar o Amazon Transcribe com o CloudTrail

hora da ação, os parâmetros da solicitação e assim por diante. Os arquivos de log do CloudTrail não são
um rastreamento de pilha ordenada das chamadas da API pública, portanto, eles não são exibidos em uma
ordem específica.

As chamadas para as operações GetTranscriptionJob e StartTranscriptionJob criam a seguinte


entrada.

{
"Records": [
{
"eventVersion": "1.05",
"userIdentity": {
"type": "AssumedRole | FederatedUser | IAMUser | Root | SAMLUser |
WebIdentityUser",
"principalId": "principal ID",
"arn": "ARN",
"accountId": "account ID",
"accessKeyId": "access key",
"userName": "user name"
},
"eventTime": "timestamp",
"eventSource": "transcribe.amazonaws.com",
"eventName": "StartTranscriptionJob",
"awsRegion": "region",
"sourceIPAddress": "source IP address",
"userAgent": "user agent",
"requestParameters": {
"mediaFormat": "flac | mp3 | mp4 | wav",
"languageCode": "en-US | es-US",
"transcriptionJobName": "unique job name",
"media": {
"mediaFileUri": ""
}
},
"responseElements": {
"transcriptionJob": {
"transcriptionJobStatus": "IN_PROGRESS",
"mediaFormat": "flac | mp3 | mp4 | wav",
"creationTime": "timestamp",
"transcriptionJobName": "unique job name",
"languageCode": "en-US | es-US",
"media": {
"mediaFileUri": ""
}
}
},
"requestID": "request ID",
"eventID": "event ID",
"eventType": "AwsApiCall",
"recipientAccountId": "account id"
},
{
"eventVersion": "1.05",
"userIdentity": {
"type": "AssumedRole | FederatedUser | IAMUser | Root | SAMLUser |
WebIdentityUser",
"principalId": "principal ID",
"arn": "ARN",
"accountId": "account ID",
"accessKeyId": "access key",
"userName": "user name"
},
"eventTime": "timestamp",
"eventSource": "transcribe.amazonaws.com",
"eventName": "GetTranscriptionJob",

85
Amazon Transcribe Guia do desenvolvedor
Eventos do CloudWatch

"awsRegion": "region",
"sourceIPAddress": "source IP address",
"userAgent": "user agent",
"requestParameters": {
"transcriptionJobName": "unique job name"
},
"responseElements": {
"transcriptionJob": {
"settings": {

},
"transcriptionJobStatus": "COMPLETED | FAILED | IN_PROGRESS",
"mediaFormat": "flac | mp3 | mp4 | wav",
"creationTime": "timestamp",
"transcriptionJobName": "unique job name",
"languageCode": "en-US | es-US",
"media": {
"mediaFileUri": ""
},
"transcript": {
"transcriptFileUri": ""
}
}
},
"requestID": "request ID",
"eventID": "event ID",
"eventType": "AwsApiCall",
"recipientAccountId": "account id"
}
]
}

Uso do Eventos do Amazon CloudWatch com o


Amazon Transcribe
Com o Eventos do Amazon CloudWatch, é possível responder a alterações de estado em seus trabalhos
do Amazon Transcribe acionando eventos em outros serviços da AWS. Quando um trabalho de transcrição
muda de estado, o Eventos do CloudWatch envia automaticamente um evento a um fluxo de eventos.
Você pode criar regras que definem os eventos que você deseja monitorar no fluxo de eventos, e a ação
que o Eventos do CloudWatch deve executar quando esses eventos ocorrerem. Por exemplo, rotear o
evento para outro serviço (ou destino), que pode executar uma ação. Por exemplo, é possível configurar
uma regra para rotear um evento para uma função do AWS Lambda quando um trabalho de transcrição for
concluído com êxito.

Antes de usar o Eventos do CloudWatch, é necessário compreender os seguintes conceitos:

• Evento – um evento indica uma alteração no estado de um dos trabalhos de transcrição. Por exemplo,
quando o TranscriptionJobStatus de um trabalho muda de IN_PROGRESS para COMPLETED.
• Destino – um destino é um outro serviço da AWS que processa um evento. Por exemplo, o AWS
Lambda ou o Amazon Simple Notification Service (Amazon SNS). Um destino recebe eventos no
formato JSON.
• Regra – uma regra corresponde eventos de entrada que você deseja que o Eventos do CloudWatch
monitore e roteia-os para um destino ou destinos para processamento. Se uma regra rotear um evento
para vários destinos, os destinos processarão o evento em paralelo. Uma regra pode personalizar o
JSON enviado ao destino.

Para obter mais informações sobre como criar e gerenciar eventos do Eventos do CloudWatch, consulte O
que é o Eventos do Amazon CloudWatch no Guia do usuário do Amazon CloudWatch.

86
Amazon Transcribe Guia do desenvolvedor
Eventos do CloudWatch

Definição de regras do Eventos do CloudWatch


Para definir regras do Eventos do CloudWatch, use o Console do Eventos do CloudWatch. Ao definir uma
regra, use o Amazon Transcribe como o nome do serviço. Para obter um exemplo de como criar uma regra
do Eventos do CloudWatch, consulte Criar uma regra do Eventos do CloudWatch que é acionada em um
evento no Guia do usuário do Amazon CloudWatch.

Veja a seguir um exemplo de uma regra do Eventos do CloudWatch para o Amazon Transcribe. Ela é
acionada quando o status de um trabalho de transcrição muda para COMPLETED ou FAILED.

{
"source": [
"aws.transcribe"
],
"detail-type": [
"Transcribe Job State Change"
],
"detail": {
"TranscriptionJobStatus": [
"COMPLETED",
"FAILED"
]
}
}

A regra contém os seguintes campos:

• source – a origem do evento. Para o Amazon Transcribe, isso é sempre aws.transcribe.


• detail-type – um identificador dos detalhes do evento. Para o Amazon Transcribe, isso é sempre
Transcribe Job State Change.
• detail – o novo status do trabalho de transcrição. Neste exemplo, a regra aciona um evento quando
o status do trabalho muda para COMPLETED ou FAILED. Para obter uma lista dos valores de status,
consulte o campo TranscriptionJobStatus do tipo de dados TranscriptionJob (p. 131).

Evento do Amazon Transcribe


Quando o estado de um trabalho muda de IN_PROGRESS para COMPLETED ou FAILED, o Amazon
Transcribe gera um evento. Para identificar o trabalho que mudou de estado e acionou o evento em seu
destino, use o campo TranscriptionJobName do evento. Um evento do Amazon Transcribe contém as
seguintes informações.

{
"version": "0",
"id": "event ID",
"detail-type":"Transcribe Job State Change",
"source": "aws.transcribe",
"account": "account ID",
"time": "timestamp",
"region": "region",
"resources": [],
"detail": {
"TranscriptionJobName": "unique job name",
"TranscriptionJobStatus": "status"
}
}

O evento transmitido para o destino contém as seguintes informações:

87
Amazon Transcribe Guia do desenvolvedor
Validação de conformidade

• version – a versão dos dados do evento. Esse valor é sempre 0.


• id – um identificador exclusivo gerado pelo Eventos do CloudWatch para o evento.
• detail-type – um identificador dos detalhes do evento. Para o Amazon Transcribe, isso é sempre
Transcribe Job State Change.
• source – a origem do evento. Para o Amazon Transcribe, isso é sempre Transcribe Job State
Change.
• account ID – o ID da conta da AWS que gerou a chamada de API.
• timestamp – a data e hora em que a chamada de API foi feita.
• region – a região da AWS em que a chamada da API foi feita.
• resources – os recursos usados pela chamada da API. No Amazon Transcribe, este campo está
sempre vazio.
• detail – detalhes sobre o evento. Contém os seguintes campos:
• TranscriptionJobName – o nome exclusivo que você deu ao trabalho.
• TranscriptionJobStatus – o novo status do trabalho de transcrição. Para obter uma
lista dos valores de status, consulte o campo TranscriptionJobStatus do tipo de dados
TranscriptionJob (p. 131).

Validação de conformidade do Amazon Transcribe


Auditores de terceiros avaliam a segurança e a conformidade do Amazon Transcribe como parte de
vários programas de conformidade da AWS. Isso inclui PCI, FedRAMP, HIPAA e outros. Você pode fazer
download de relatórios de auditoria de terceiros usando o AWS Artifact. Para obter mais informações,
consulte Download de relatórios no AWS Artifact.

Sua responsabilidade de conformidade ao usar o Amazon Transcribe é determinada pela confidencialidade


de seus dados, pelos objetivos de conformidade de sua empresa e pelos regulamentos e leis aplicáveis. A
AWS fornece os seguintes recursos para ajudar com a conformidade:

• Guias Quick Start de segurança e conformidade – esses guias de implantação abordam as


considerações de arquitetura e fornecem etapas para implantação de ambientes de linha de base
focados em conformidade e segurança na AWS.
• Whitepaper Arquitetura para segurança e conformidade com HIPAA – esse whitepaper descreve como
as empresas podem usar a AWS para criar aplicativos em conformidade com a HIPAA.
• Recursos de conformidade da AWS – esta coleção de manuais e guias pode ser aplicada ao seu setor e
ao seu local.
• AWS Config – esse serviço da AWS avalia até que ponto suas configurações de recursos estão em
conformidade com práticas internas e diretrizes e regulamentações do setor.
• AWS Security Hub – esse serviço da AWS fornece uma visão abrangente do estado da segurança na
AWS que ajuda você a verificar sua conformidade com padrões e melhores práticas de segurança do
setor.

Para obter uma lista de serviços da AWS no escopo de programas de conformidade específicos, consulte
Serviços da AWS em escopo por programa de conformidade. Para obter informações gerais, consulte
Programas de conformidade da AWS.

Resiliência no Amazon Transcribe


A infraestrutura global da AWS é criada com base em regiões e zonas de disponibilidade da AWS. As
regiões da AWS fornecem várias zonas de disponibilidade separadas e isoladas fisicamente, que são

88
Amazon Transcribe Guia do desenvolvedor
Segurança da infraestrutura

conectadas com baixa latência, altas taxas de transferência e redes altamente redundantes. Com as zonas
de disponibilidade, você pode projetar e operar aplicativos e bancos de dados que executam o failover
automaticamente entre as zonas de disponibilidade sem interrupção. As zonas de disponibilidade são mais
altamente disponíveis, tolerantes a falhas e escaláveis que uma ou várias infraestruturas de data center
tradicionais.

Para obter mais informações sobre regiões e zonas de disponibilidade da AWS, consulte Infraestrutura
global da AWS.

Segurança da infraestrutura no Amazon Transcribe


Como um serviço gerenciado, o Amazon Transcribe é protegido pelos procedimentos de segurança da
rede global da AWS que estão descritos no whitepaper Amazon Web Services: visão geral dos processos
de segurança.

Para acessar o Amazon Transcribe por meio da rede, use chamadas de APIs publicadas da AWS. Os
clientes devem oferecer suporte ao Transport Layer Security (TLS) 1.0 ou posterior. Recomendamos o
TLS 1.2 ou posterior. Os clientes também devem oferecer suporte a pacotes de criptografia com Perfect
Forward Secrecy (PFS — Sigilo de encaminhamento perfeito), como Ephemeral Diffie-Hellman (DHE) ou
Ephemeral Elliptic Curve Diffie-Hellman (ECDHE). A maioria dos sistemas modernos, como o Java 7 e
versões posteriores, oferece suporte a esses modos.

Além disso, as solicitações devem ser assinadas usando um ID da chave de acesso e uma chave de
acesso secreta associada a uma entidade principal do AWS Identity and Access Management (IAM).
Ou você pode usar o AWS Security Token Service (AWS STS) para gerar credenciais de segurança
temporárias para assinar solicitações.

89
Amazon Transcribe Guia do desenvolvedor
Regiões compatíveis

Diretrizes e limites
Regiões compatíveis
Para obter uma lista de regiões da AWS onde o Amazon Transcribe está disponível, consulte Regiões e
endpoints da AWS na Referência geral da Amazon Web Services.

Limitação
Para obter informações sobre a limitação do Amazon Transcribe e para solicitar um aumento de limite,
consulte Limites do Amazon Transcribe no Referência geral do Amazon Web Services.

Diretrizes
Para obter os melhores resultados:

• Use um formato sem perda, como FLAC ou WAV, com a codificação de PCM de 16 bits.
• Use uma taxa de amostragem de 8.000 Hz para áudio de baixa fidelidade e 16.000 Hz para áudio de alta
fidelidade.

O Amazon Transcribe pode armazenar seu conteúdo para melhorar continuamente a qualidade dos
modelos de análise. Consulte as Perguntas frequentes do Amazon Transcribe para saber mais. Para
solicitar a exclusão do conteúdo que pode ter sido armazenado pelo Amazon Transcribe, abra um caso
com o AWS Support.

Limites
O Amazon Transcribe tem as seguintes limitações:

Descrição Limite

Duração máxima do arquivo de áudio 4 horas

Tamanho máximo do arquivo de áudio 2 GB

Tamanho máximo de um vocabulário personalizado 50 KB

Tamanho máximo de uma expressão do vocabulário personalizado 256 caracteres

Número de dias que os registros de tarefa são retidos 90

90
Amazon Transcribe Guia do desenvolvedor

Histórico do documento do Amazon


Transcribe
• Última atualização da documentação: 25 de outubro de 2019

A tabela a seguir descreve as alterações importantes em cada versão do Amazon Transcribe. Para receber
notificações sobre atualizações dessa documentação, você pode se inscrever em um feed RSS.

update-history-change update-history-description update-history-date

Novo idioma O Amazon Transcribe agora October 25, 2019


oferece suporte à transcrição de
streaming em inglês australiano
(en-AU).

Expansão de região O Amazon Transcribe agora está October 9, 2019


disponível nas regiões China
(Pequim) (cn-north-1) e China
(Ningxia) (cn-northwest-1).

Novo recurso O Amazon Transcribe permite September 24, 2019


que você forneça sua própria
chave AWS Key Management
Service para criptografar seus
arquivos de saída de transcrição.
Para obter mais informações,
consulte o parâmetro
OutputEncryptionKMSKeyId
da operação
StartStreamTranscription.

Novos idiomas O Amazon Transcribe adiciona August 23, 2019


suporte para mandarim (China
Continental) e russo.

Novo recurso O Amazon Transcribe inclui July 19, 2019


suporte à transcrição de
streaming de áudio usando o
protocolo WebSocket. Para
obter mais informações, consulte
Transcrição de streaming.

Novo recurso O AWS CloudTrail agora registra July 19, 2019


eventos para a operação
StartStreamTranscription.

Expansão de região Agora o Amazon Transcribe está June 27, 2019


disponível na região Oeste dos
EUA (Norte da Califórnia) (us-
west-1).

Novo idioma O Amazon Transcribe adiciona May 28, 2019


suporte para o árabe padrão
moderno.

91
Amazon Transcribe Guia do desenvolvedor

Novo recurso O Amazon Transcribe agora May 23, 2019


transcreve palavras numéricas
em números para inglês dos
EUA. Por exemplo, "quarenta e
dois" é transcrito como "42". Para
obter mais informações, consulte
Transcrição de números.

Novo idioma O Amazon Transcribe adiciona May 15, 2019


suporte para hindi e inglês
indiano.

Novo SDK O AWS SDK para C++ agora May 8, 2019


oferece suporte ao Amazon
Transcribe.

Novo idioma Amazon Transcribe adiciona April 19, 2019


suporte para o espanhol.

Expansão de região Agora o Amazon Transcribe April 18, 2019


está disponível nas regiões UE
(Frankfurt) (eu-central-1) e Ásia-
Pacífico (Seul) (ap-northeast-2).

Novo idioma Amazon Transcribe adiciona April 5, 2019


suporte para streaming de
transcrição em inglês britânico,
francês e francês canadense.

Novo recurso O AWS SDK para Ruby V3 agora March 25, 2019
é compatível com o Amazon
Transcribe

Novo recurso O Amazon Transcribe agora March 25, 2019


permite criar vocabulário
personalizado, listas de palavras
específicas que o Amazon
Transcribe deve reconhecer na
entrada de áudio. Para obter
mais informações, consulte
Vocabulários personalizados.

Novos idiomas Amazon Transcribe adiciona March 22, 2019


suporte para alemão e coreano.

Novo idioma O Amazon Transcribe agora February 7, 2019


oferece suporte a transcrição
de streaming para espanhol dos
EUA (es-US).

Expansão de região O Amazon Transcribe agora está February 7, 2019


disponível na região América do
Sul (São Paulo) (sa-east-1).

92
Amazon Transcribe Guia do desenvolvedor

Expansão de região O Amazon Transcribe agora January 24, 2019


está disponível na região Ásia-
Pacífico (Mumbai) (ap-south-1),
Ásia-Pacífico (Singapura) (ap-
southeast-1), UE (Londres) (eu-
west-2) e UE (Paris) (eu-west3).

Novos idiomas O Amazon Transcribe adiciona December 20, 2018


suporte para francês, italiano e
português do Brasil.

Novo recurso Agora, o Amazon Transcribe November 19, 2018


oferece suporte a transcrição
de streamings de áudio. Para
obter mais informações, consulte
Transcrição de streaming.

Novos idiomas O Amazon Transcribe adiciona November 15, 2018


suporte para o inglês australiano,
inglês britânico e francês
canadense.

Expansão de região Agora, o Amazon Transcribe está July 17, 2018


disponível no Canadá (Central)
(ca-central-1) e Ásia-Pacífico
(Sydney) (ap-southeast-2).

Novo recurso Agora é possível especificar seu July 11, 2018


próprio local para armazenar
a saída de um trabalho de
transcrição. Para obter mais
informações, consulte o tipo de
dados TranscriptionJobSummary.

Novo recurso Adicionada integração do AWS June 28, 2018


CloudTrail com o Eventos do
Amazon CloudWatch. Para obter
mais informações, consulte
Monitoramento do Amazon
Transcribe.

Novo recurso (p. 91) O Amazon Transcribe adiciona April 4, 2018


suporte para vocabulários
personalizados. Para obter mais
informações, consulte Criar um
vocabulário personalizado.

Novo guia (p. 91) Esta é a primeira versão do Guia November 29, 2017
do desenvolvedor do Amazon
Transcribe.

93
Amazon Transcribe Guia do desenvolvedor
Actions

Referência da API
Esta seção contém a documentação de referência da API.

Tópicos

• Actions (p. 94)


• Data Types (p. 125)

Actions
The following actions are supported by Amazon Transcribe Service:

• CreateVocabulary (p. 95)


• DeleteTranscriptionJob (p. 99)
• DeleteVocabulary (p. 101)
• GetTranscriptionJob (p. 103)
• GetVocabulary (p. 105)
• ListTranscriptionJobs (p. 108)
• ListVocabularies (p. 111)
• StartTranscriptionJob (p. 114)
• UpdateVocabulary (p. 118)

The following actions are supported by Amazon Transcribe Streaming Service:

• StartStreamTranscription (p. 122)

Amazon Transcribe Service


The following actions are supported by Amazon Transcribe Service:

• CreateVocabulary (p. 95)


• DeleteTranscriptionJob (p. 99)
• DeleteVocabulary (p. 101)
• GetTranscriptionJob (p. 103)
• GetVocabulary (p. 105)
• ListTranscriptionJobs (p. 108)
• ListVocabularies (p. 111)
• StartTranscriptionJob (p. 114)
• UpdateVocabulary (p. 118)

94
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

CreateVocabulary
Service: Amazon Transcribe Service

Creates a new custom vocabulary that you can use to change the way Amazon Transcribe handles
transcription of an audio file.

Request Syntax

{
"LanguageCode": "string",
"Phrases": [ "string" ],
"VocabularyFileUri": "string",
"VocabularyName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

LanguageCode (p. 95)

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE

Required: Yes
Phrases (p. 95)

An array of strings that contains the vocabulary entries.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: .+

Required: No
VocabularyFileUri (p. 95)

The S3 location of the text file that contains the definition of the custom vocabulary. The URI must be in
the same region as the API endpoint that you are calling. The general form is

https://s3.<aws-region>.amazonaws.com/<bucket-name>/<keyprefix>/<objectkey>

For example:

https://s3.us-east-1.amazonaws.com/examplebucket/vocab.txt

For more information about S3 object names, see Object Keys in the Amazon S3 Developer Guide.

For more information about custom vocabularies, see Custom Vocabularies.

Type: String

95
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: (s3://|http(s*)://).+

Required: No
VocabularyName (p. 95)

The name of the vocabulary. The name must be unique within an AWS account. The name is case-
sensitive.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Syntax

{
"FailureReason": "string",
"LanguageCode": "string",
"LastModifiedTime": number,
"VocabularyName": "string",
"VocabularyState": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

FailureReason (p. 96)

If the VocabularyState field is FAILED, this field contains information about why the job failed.

Type: String
LanguageCode (p. 96)

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE
LastModifiedTime (p. 96)

The date and time that the vocabulary was created.

Type: Timestamp
VocabularyName (p. 96)

The name of the vocabulary.

Type: String

96
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+
VocabularyState (p. 96)

The processing state of the vocabulary. When the VocabularyState field contains READY the
vocabulary is ready to be used in a StartTranscriptionJob request.

Type: String

Valid Values: PENDING | READY | FAILED

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


ConflictException

When you are using the CreateVocabulary operation, the JobName field is a duplicate of a
previously entered job name. Resend your request with a different name.

When you are using the UpdateVocabulary operation, there are two jobs running at the same time.
Resend the second request later.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

97
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

• AWS SDK for Ruby V2

98
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

DeleteTranscriptionJob
Service: Amazon Transcribe Service

Deletes a previously submitted transcription job along with any other generated results such as the
transcription, models, and so on.

Request Syntax

{
"TranscriptionJobName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

TranscriptionJobName (p. 99)

The name of the transcription job to be deleted.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400

99
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

100
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

DeleteVocabulary
Service: Amazon Transcribe Service

Deletes a vocabulary from Amazon Transcribe.

Request Syntax

{
"VocabularyName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

VocabularyName (p. 101)

The name of the vocabulary to delete.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400


NotFoundException

We can't find the requested resource. Check the name and try your request again.

101
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

102
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

GetTranscriptionJob
Service: Amazon Transcribe Service

Returns information about a transcription job. To see the status of the job, check the
TranscriptionJobStatus field. If the status is COMPLETED, the job is finished and you can find the
results at the location specified in the TranscriptionFileUri field.

Request Syntax

{
"TranscriptionJobName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

TranscriptionJobName (p. 103)

The name of the job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Syntax

{
"TranscriptionJob": {
"CompletionTime": number,
"CreationTime": number,
"FailureReason": "string",
"LanguageCode": "string",
"Media": {
"MediaFileUri": "string"
},
"MediaFormat": "string",
"MediaSampleRateHertz": number,
"Settings": {
"ChannelIdentification": boolean,
"MaxAlternatives": number,
"MaxSpeakerLabels": number,
"ShowAlternatives": boolean,
"ShowSpeakerLabels": boolean,
"VocabularyName": "string"
},
"Transcript": {
"TranscriptFileUri": "string"
},
"TranscriptionJobName": "string",
"TranscriptionJobStatus": "string"
}
}

103
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

TranscriptionJob (p. 103)

An object that contains the results of the transcription job.

Type: TranscriptionJob (p. 131) object

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400


NotFoundException

We can't find the requested resource. Check the name and try your request again.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

104
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

GetVocabulary
Service: Amazon Transcribe Service

Gets information about a vocabulary.

Request Syntax

{
"VocabularyName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

VocabularyName (p. 105)

The name of the vocabulary to return information about. The name is case-sensitive.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Syntax

{
"DownloadUri": "string",
"FailureReason": "string",
"LanguageCode": "string",
"LastModifiedTime": number,
"VocabularyName": "string",
"VocabularyState": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

DownloadUri (p. 105)

The S3 location where the vocabulary is stored. Use this URI to get the contents of the vocabulary. The
URI is available for a limited time.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: (s3://|http(s*)://).+
FailureReason (p. 105)

If the VocabularyState field is FAILED, this field contains information about why the job failed.

105
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String
LanguageCode (p. 105)

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE
LastModifiedTime (p. 105)

The date and time that the vocabulary was last modified.

Type: Timestamp
VocabularyName (p. 105)

The name of the vocabulary to return.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+
VocabularyState (p. 105)

The processing state of the vocabulary.

Type: String

Valid Values: PENDING | READY | FAILED

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400


NotFoundException

We can't find the requested resource. Check the name and try your request again.

106
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

107
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

ListTranscriptionJobs
Service: Amazon Transcribe Service

Lists transcription jobs with the specified status.

Request Syntax

{
"JobNameContains": "string",
"MaxResults": number,
"NextToken": "string",
"Status": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

JobNameContains (p. 108)

When specified, the jobs returned in the list are limited to jobs whose name contains the specified
string.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No
MaxResults (p. 108)

The maximum number of jobs to return in the response. If there are fewer results in the list, this
response contains only the actual results.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
NextToken (p. 108)

If the result of the previous request to ListTranscriptionJobs was truncated, include the
NextToken to fetch the next set of jobs.

Type: String

Length Constraints: Maximum length of 8192.

Pattern: .+

Required: No
Status (p. 108)

When specified, returns only transcription jobs with the specified status. Jobs are ordered by creation
date, with the newest jobs returned first. If you don’t specify a status, Amazon Transcribe returns all
transcription jobs ordered by creation date.

108
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String

Valid Values: IN_PROGRESS | FAILED | COMPLETED

Required: No

Response Syntax

{
"NextToken": "string",
"Status": "string",
"TranscriptionJobSummaries": [
{
"CompletionTime": number,
"CreationTime": number,
"FailureReason": "string",
"LanguageCode": "string",
"OutputLocationType": "string",
"TranscriptionJobName": "string",
"TranscriptionJobStatus": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

NextToken (p. 109)

The ListTranscriptionJobs operation returns a page of jobs at a time. The maximum size
of the page is set by the MaxResults parameter. If there are more jobs in the list than the page
size, Amazon Transcribe returns the NextPage token. Include the token in the next request to the
ListTranscriptionJobs operation to return in the next page of jobs.

Type: String

Length Constraints: Maximum length of 8192.

Pattern: .+
Status (p. 109)

The requested status of the jobs returned.

Type: String

Valid Values: IN_PROGRESS | FAILED | COMPLETED


TranscriptionJobSummaries (p. 109)

A list of objects containing summary information for a transcription job.

Type: Array of TranscriptionJobSummary (p. 134) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

109
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

110
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

ListVocabularies
Service: Amazon Transcribe Service

Returns a list of vocabularies that match the specified criteria. If no criteria are specified, returns the entire
list of vocabularies.

Request Syntax

{
"MaxResults": number,
"NameContains": "string",
"NextToken": "string",
"StateEquals": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

MaxResults (p. 111)

The maximum number of vocabularies to return in the response. If there are fewer results in the list,
this response contains only the actual results.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No
NameContains (p. 111)

When specified, the vocabularies returned in the list are limited to vocabularies whose name
contains the specified string. The search is case-insensitive, ListVocabularies will return both
"vocabularyname" and "VocabularyName" in the response list.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No
NextToken (p. 111)

If the result of the previous request to ListVocabularies was truncated, include the NextToken to
fetch the next set of jobs.

Type: String

Length Constraints: Maximum length of 8192.

Pattern: .+

Required: No

111
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

StateEquals (p. 111)

When specified, only returns vocabularies with the VocabularyState field equal to the specified
state.

Type: String

Valid Values: PENDING | READY | FAILED

Required: No

Response Syntax

{
"NextToken": "string",
"Status": "string",
"Vocabularies": [
{
"LanguageCode": "string",
"LastModifiedTime": number,
"VocabularyName": "string",
"VocabularyState": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

NextToken (p. 112)

The ListVocabularies operation returns a page of vocabularies at a time. The maximum size
of the page is set by the MaxResults parameter. If there are more jobs in the list than the page
size, Amazon Transcribe returns the NextPage token. Include the token in the next request to the
ListVocabularies operation to return in the next page of jobs.

Type: String

Length Constraints: Maximum length of 8192.

Pattern: .+
Status (p. 112)

The requested vocabulary state.

Type: String

Valid Values: IN_PROGRESS | FAILED | COMPLETED


Vocabularies (p. 112)

A list of objects that describe the vocabularies that match the search criteria in the request.

Type: Array of VocabularyInfo (p. 136) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

112
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

113
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

StartTranscriptionJob
Service: Amazon Transcribe Service

Starts an asynchronous job to transcribe speech to text.

Request Syntax

{
"LanguageCode": "string",
"Media": {
"MediaFileUri": "string"
},
"MediaFormat": "string",
"MediaSampleRateHertz": number,
"OutputBucketName": "string",
"OutputEncryptionKMSKeyId": "string",
"Settings": {
"ChannelIdentification": boolean,
"MaxAlternatives": number,
"MaxSpeakerLabels": number,
"ShowAlternatives": boolean,
"ShowSpeakerLabels": boolean,
"VocabularyName": "string"
},
"TranscriptionJobName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

LanguageCode (p. 114)

The language code for the language used in the input media file.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE

Required: Yes
Media (p. 114)

An object that describes the input media for a transcription job.

Type: Media (p. 127) object

Required: Yes
MediaFormat (p. 114)

The format of the input media file.

Type: String

Valid Values: mp3 | mp4 | wav | flac

Required: No

114
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

MediaSampleRateHertz (p. 114)

The sample rate, in Hertz, of the audio track in the input media file.

If you do not specify the media sample rate, Amazon Transcribe determines the sample rate. If you
specify the sample rate, it must match the sample rate detected by Amazon Transcribe. In most cases,
you should leave the MediaSampleRateHertz field blank and let Amazon Transcribe determine the
sample rate.

Type: Integer

Valid Range: Minimum value of 8000. Maximum value of 48000.

Required: No
OutputBucketName (p. 114)

The location where the transcription is stored.

If you set the OutputBucketName, Amazon Transcribe puts the transcription in the specified S3
bucket. When you call the GetTranscriptionJob (p. 103) operation, the operation returns this location in
the TranscriptFileUri field. The S3 bucket must have permissions that allow Amazon Transcribe
to put files in the bucket. For more information, see Permissions Required for IAM User Roles.

You can specify an AWS Key Management Service (KMS) key to encrypt the output of your
transcription using the OutputEncryptionKMSKeyId parameter. If you don't specify a KMS key,
Amazon Transcribe uses the default Amazon S3 key for server-side encryption of transcripts that are
placed in your S3 bucket.

If you don't set the OutputBucketName, Amazon Transcribe generates a pre-signed URL,
a shareable URL that provides secure access to your transcription, and returns it in the
TranscriptFileUri field. Use this URL to download the transcription.

Type: String

Length Constraints: Maximum length of 64.

Pattern: [a-z0-9][\.\-a-z0-9]{1,61}[a-z0-9]

Required: No
OutputEncryptionKMSKeyId (p. 114)

The Amazon Resource Name (ARN) of the AWS Key Management Service (KMS) key used to encrypt
the output of the transcription job. The user calling the StartTranscriptionJob operation must
have permission to use the specified KMS key.

You can use either of the following to identify a KMS key in the current account:
• KMS Key ID: "1234abcd-12ab-34cd-56ef-1234567890ab"
• KMS Key Alias: "alias/ExampleAlias"

You can use either of the following to identify a KMS key in the current account or another account:
• Amazon Resource Name (ARN) of a KMS Key: "arn:aws:kms:region:account
ID:key/1234abcd-12ab-34cd-56ef-1234567890ab"
• ARN of a KMS Key Alias: "arn:aws:kms:region:account ID:alias/ExampleAlias"

If you don't specify an encryption key, the output of the transcription job is encrypted with the default
Amazon S3 key (SSE-S3).

If you specify a KMS key to encrypt your output, you must also specify an output location in the
OutputBucketName parameter.

115
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Pattern: ^[A-Za-z0-9][A-Za-z0-9:_/+=,@.-]{0,2048}$

Required: No
Settings (p. 114)

A Settings object that provides optional settings for a transcription job.

Type: Settings (p. 128) object

Required: No
TranscriptionJobName (p. 114)

The name of the job. Note that you can't use the strings "." or ".." by themselves as the job name. The
name must also be unique within an AWS account.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Syntax

{
"TranscriptionJob": {
"CompletionTime": number,
"CreationTime": number,
"FailureReason": "string",
"LanguageCode": "string",
"Media": {
"MediaFileUri": "string"
},
"MediaFormat": "string",
"MediaSampleRateHertz": number,
"Settings": {
"ChannelIdentification": boolean,
"MaxAlternatives": number,
"MaxSpeakerLabels": number,
"ShowAlternatives": boolean,
"ShowSpeakerLabels": boolean,
"VocabularyName": "string"
},
"Transcript": {
"TranscriptFileUri": "string"
},
"TranscriptionJobName": "string",
"TranscriptionJobStatus": "string"
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

116
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

TranscriptionJob (p. 116)

An object containing details of the asynchronous transcription job.

Type: TranscriptionJob (p. 131) object

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


ConflictException

When you are using the CreateVocabulary operation, the JobName field is a duplicate of a
previously entered job name. Resend your request with a different name.

When you are using the UpdateVocabulary operation, there are two jobs running at the same time.
Resend the second request later.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

117
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

UpdateVocabulary
Service: Amazon Transcribe Service

Updates an existing vocabulary with new values. The UpdateVocabulary operation overwrites all of the
existing information with the values that you provide in the request.

Request Syntax

{
"LanguageCode": "string",
"Phrases": [ "string" ],
"VocabularyFileUri": "string",
"VocabularyName": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common Parameters (p. 147).

The request accepts the following data in JSON format.

LanguageCode (p. 118)

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE

Required: Yes
Phrases (p. 118)

An array of strings containing the vocabulary entries.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: .+

Required: No
VocabularyFileUri (p. 118)

The S3 location of the text file that contains the definition of the custom vocabulary. The URI must be in
the same region as the API endpoint that you are calling. The general form is

https://s3.<aws-region>.amazonaws.com/<bucket-name>/<keyprefix>/<objectkey>

For example:

https://s3.us-east-1.amazonaws.com/examplebucket/vocab.txt

For more information about S3 object names, see Object Keys in the Amazon S3 Developer Guide.

For more information about custom vocabularies, see Custom Vocabularies.

118
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: (s3://|http(s*)://).+

Required: No
VocabularyName (p. 118)

The name of the vocabulary to update. The name is case-sensitive.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: Yes

Response Syntax

{
"LanguageCode": "string",
"LastModifiedTime": number,
"VocabularyName": "string",
"VocabularyState": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

LanguageCode (p. 119)

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE
LastModifiedTime (p. 119)

The date and time that the vocabulary was updated.

Type: Timestamp
VocabularyName (p. 119)

The name of the vocabulary that was updated.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

119
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

VocabularyState (p. 119)

The processing state of the vocabulary. When the VocabularyState field contains READY the
vocabulary is ready to be used in a StartTranscriptionJob request.

Type: String

Valid Values: PENDING | READY | FAILED

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

BadRequestException

Your request didn't pass one or more validation tests. For example, if the transcription you're trying to
delete doesn't exist or if it is in a non-terminal state (for example, it's "in progress"). See the exception
Message field for more information.

HTTP Status Code: 400


ConflictException

When you are using the CreateVocabulary operation, the JobName field is a duplicate of a
previously entered job name. Resend your request with a different name.

When you are using the UpdateVocabulary operation, there are two jobs running at the same time.
Resend the second request later.

HTTP Status Code: 400


InternalFailureException

There was an internal error. Check the error message and try your request again.

HTTP Status Code: 500


LimitExceededException

Either you have sent too many requests or your input file is too long. Wait before you resend your
request, or use a smaller file and resend the request.

HTTP Status Code: 400


NotFoundException

We can't find the requested resource. Check the name and try your request again.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript

120
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

• AWS SDK for PHP V3


• AWS SDK for Python
• AWS SDK for Ruby V2

Amazon Transcribe Streaming Service


The following actions are supported by Amazon Transcribe Streaming Service:

• StartStreamTranscription (p. 122)

121
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

StartStreamTranscription
Service: Amazon Transcribe Streaming Service

Starts a bidirectional HTTP2 stream where audio is streamed to Amazon Transcribe and the transcription
results are streamed to your application.

The following are encoded as HTTP2 headers:

• x-amzn-transcribe-language-code
• x-amzn-transcribe-media-encoding
• x-amzn-transcribe-sample-rate
• x-amzn-transcribe-session-id

Request Syntax

POST /stream-transcription HTTP/2


x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-session-id: SessionId
Content-type: application/json

{
"AudioStream": {
"AudioEvent": {
"AudioChunk": blob
}
}
}

URI Request Parameters


The request requires the following URI parameters.

LanguageCode (p. 122)

Indicates the source language used in the input audio stream.

Valid Values: en-US


MediaEncoding (p. 122)

The encoding used for the input audio.

Valid Values: pcm


MediaSampleRateHertz (p. 122)

The sample rate, in Hertz, of the input audio. We suggest that you use 8000 Hz for low quality audio
and 16000 Hz for high quality audio.

Valid Range: Minimum value of 8000. Maximum value of 48000.


SessionId (p. 122)

A identifier for the transcription session. Use this parameter when you want to retry a session. If you
don't provide a session ID, Amazon Transcribe will generate one for you and return it in the response.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-
F0-9]{12}

122
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

VocabularyName (p. 122)

The name of the vocabulary to use when processing the transcription job.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Request Body
The request accepts the following data in JSON format.

AudioStream (p. 122)

PCM-encoded stream of audio blobs. The audio stream is encoded as an HTTP2 data frame.

Type: AudioStream (p. 140) object

Required: Yes

Response Syntax

HTTP/2 200
x-amzn-request-id: RequestId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
x-amzn-transcribe-vocabulary-name: VocabularyName
x-amzn-transcribe-session-id: SessionId
Content-type: application/json

{
"TranscriptResultStream": {
"BadRequestException": {
},
"ConflictException": {
},
"InternalFailureException": {
},
"LimitExceededException": {
},
"TranscriptEvent": {
"Transcript": {
"Results": [
{
"Alternatives": [
{
"Items": [
{
"Content": "string",
"EndTime": number,
"StartTime": number,
"Type": "string"
}
],
"Transcript": "string"
}
],
"EndTime": number,
"IsPartial": boolean,
"ResultId": "string",
"StartTime": number

123
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

}
]
}
}
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

LanguageCode (p. 123)

The language code for the input audio stream.

Valid Values: en-US


MediaEncoding (p. 123)

The encoding used for the input audio stream.

Valid Values: pcm


MediaSampleRateHertz (p. 123)

The sample rate for the input audio stream. Use 8000 Hz for low quality audio and 16000 Hz for high
quality audio.

Valid Range: Minimum value of 8000. Maximum value of 48000.


RequestId (p. 123)

An identifier for the streaming transcription.


SessionId (p. 123)

An identifier for a specific transcription session.

Pattern: [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-
F0-9]{12}
VocabularyName (p. 123)

The name of the vocabulary used when processing the job.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

The following data is returned in JSON format by the service.

TranscriptResultStream (p. 123)

Represents the stream of transcription events from Amazon Transcribe to your application.

Type: TranscriptResultStream (p. 145) object

Errors
For information about the errors that are common to all actions, see Common Errors (p. 146).

124
Amazon Transcribe Guia do desenvolvedor
Data Types

BadRequestException

One or more arguments to the StartStreamTranscription operation was invalid. For example,
MediaEncoding was not set to pcm or LanguageCode was not set to a valid code. Check the
parameters and try your request again.

HTTP Status Code: 400


ConflictException

A new stream started with the same session ID. The current stream has been terminated.

HTTP Status Code: 409


InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing. Try your
request again.

HTTP Status Code: 500


LimitExceededException

You have exceeded the maximum number of concurrent transcription streams, are starting
transcription streams too quickly, or the maximum audio length of 4 hours. Wait until a stream has
finished processing, or break your audio stream into smaller chunks and try your request again.

HTTP Status Code: 429

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface


• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

Data Types
The following data types are supported by Amazon Transcribe Service:

• Media (p. 127)


• Settings (p. 128)
• Transcript (p. 130)
• TranscriptionJob (p. 131)
• TranscriptionJobSummary (p. 134)
• VocabularyInfo (p. 136)

The following data types are supported by Amazon Transcribe Streaming Service:

125
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

• Alternative (p. 138)


• AudioEvent (p. 139)
• AudioStream (p. 140)
• Item (p. 141)
• Result (p. 142)
• Transcript (p. 143)
• TranscriptEvent (p. 144)
• TranscriptResultStream (p. 145)

Amazon Transcribe Service


The following data types are supported by Amazon Transcribe Service:

• Media (p. 127)


• Settings (p. 128)
• Transcript (p. 130)
• TranscriptionJob (p. 131)
• TranscriptionJobSummary (p. 134)
• VocabularyInfo (p. 136)

126
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Media
Service: Amazon Transcribe Service

Describes the input media file in a transcription request.

Contents
MediaFileUri

The S3 location of the input media file. The URI must be in the same region as the API endpoint that
you are calling. The general form is:

https://s3.<aws-region>.amazonaws.com/<bucket-name>/<keyprefix>/<objectkey>

For example:

https://s3.us-east-1.amazonaws.com/examplebucket/example.mp4

https://s3.us-east-1.amazonaws.com/examplebucket/mediadocs/example.mp4

For more information about S3 object names, see Object Keys in the Amazon S3 Developer Guide.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: (s3://|http(s*)://).+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

127
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Settings
Service: Amazon Transcribe Service

Provides optional settings for the StartTranscriptionJob operation.

Contents
ChannelIdentification

Instructs Amazon Transcribe to process each audio channel separately and then merge the
transcription output of each channel into a single transcription.

Amazon Transcribe also produces a transcription of each item detected on an audio channel,
including the start time and end time of the item and alternative transcriptions of the item including the
confidence that Amazon Transcribe has in the transcription.

You can't set both ShowSpeakerLabels and ChannelIdentification in the same request. If you
set both, your request returns a BadRequestException.

Type: Boolean

Required: No
MaxAlternatives

The number of alternative transcriptions that the service should return. If you specify the
MaxAlternatives field, you must set the ShowAlternatives field to true.

Type: Integer

Valid Range: Minimum value of 2. Maximum value of 10.

Required: No
MaxSpeakerLabels

The maximum number of speakers to identify in the input audio. If there are more speakers in the
audio than this number, multiple speakers will be identified as a single speaker. If you specify the
MaxSpeakerLabels field, you must set the ShowSpeakerLabels field to true.

Type: Integer

Valid Range: Minimum value of 2. Maximum value of 10.

Required: No
ShowAlternatives

Determines whether the transcription contains alternative transcriptions. If you set the
ShowAlternatives field to true, you must also set the maximum number of alternatives to return in
the MaxAlternatives field.

Type: Boolean

Required: No
ShowSpeakerLabels

Determines whether the transcription job uses speaker recognition to identify different speakers
in the input audio. Speaker recognition labels individual speakers in the audio file. If you set the
ShowSpeakerLabels field to true, you must also set the maximum number of speaker labels
MaxSpeakerLabels field.

128
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

You can't set both ShowSpeakerLabels and ChannelIdentification in the same request. If you
set both, your request returns a BadRequestException.

Type: Boolean

Required: No
VocabularyName

The name of a vocabulary to use when processing the transcription job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

129
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Transcript
Service: Amazon Transcribe Service

Identifies the location of a transcription.

Contents
TranscriptFileUri

The location where the transcription is stored.

Use this URI to access the transcription. If you specified an S3 bucket in the OutputBucketName
field when you created the job, this is the URI of that bucket. If you chose to store the transcription in
Amazon Transcribe, this is a shareable URL that provides secure access to that location.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: (s3://|http(s*)://).+

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

130
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

TranscriptionJob
Service: Amazon Transcribe Service

Describes an asynchronous transcription job that was created with the StartTranscriptionJob
operation.

Contents
CompletionTime

A timestamp that shows when the job was completed.

Type: Timestamp

Required: No
CreationTime

A timestamp that shows when the job was created.

Type: Timestamp

Required: No
FailureReason

If the TranscriptionJobStatus field is FAILED, this field contains information about why the job
failed.

The FailureReason field can contain one of the following values:


• Unsupported media format - The media format specified in the MediaFormat field of the
request isn't valid. See the description of the MediaFormat field for a list of valid values.
• The media format provided does not match the detected media format - The
media format of the audio file doesn't match the format specified in the MediaFormat field in the
request. Check the media format of your media file and make sure that the two values match.
• Invalid sample rate for audio file - The sample rate specified in the
MediaSampleRateHertz of the request isn't valid. The sample rate must be between 8000 and
48000 Hertz.
• The sample rate provided does not match the detected sample rate - The sample
rate in the audio file doesn't match the sample rate specified in the MediaSampleRateHertz field
in the request. Check the sample rate of your media file and make sure that the two values match.
• Invalid file size: file size too large - The size of your audio file is larger than
Amazon Transcribe can process. For more information, see Limits in the Amazon Transcribe
Developer Guide.
• Invalid number of channels: number of channels too large - Your audio contains
more channels than Amazon Transcribe is configured to process. To request additional channels,
see Amazon Transcribe Limits in the Amazon Web Services General Reference.

Type: String

Required: No
LanguageCode

The language code for the input speech.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-

131
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |


he-IL | ms-MY | ja-JP | ar-AE

Required: No
Media

An object that describes the input media for the transcription job.

Type: Media (p. 127) object

Required: No
MediaFormat

The format of the input media file.

Type: String

Valid Values: mp3 | mp4 | wav | flac

Required: No
MediaSampleRateHertz

The sample rate, in Hertz, of the audio track in the input media file.

Type: Integer

Valid Range: Minimum value of 8000. Maximum value of 48000.

Required: No
Settings

Optional settings for the transcription job. Use these settings to turn on speaker recognition, to set the
maximum number of speakers that should be identified and to specify a custom vocabulary to use
when processing the transcription job.

Type: Settings (p. 128) object

Required: No
Transcript

An object that describes the output of the transcription job.

Type: Transcript (p. 130) object

Required: No
TranscriptionJobName

The name of the transcription job.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No
TranscriptionJobStatus

The status of the transcription job.

132
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String

Valid Values: IN_PROGRESS | FAILED | COMPLETED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

133
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

TranscriptionJobSummary
Service: Amazon Transcribe Service

Provides a summary of information about a transcription job.

Contents
CompletionTime

A timestamp that shows when the job was completed.

Type: Timestamp

Required: No
CreationTime

A timestamp that shows when the job was created.

Type: Timestamp

Required: No
FailureReason

If the TranscriptionJobStatus field is FAILED, a description of the error.

Type: String

Required: No
LanguageCode

The language code for the input speech.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE

Required: No
OutputLocationType

Indicates the location of the output of the transcription job.

If the value is CUSTOMER_BUCKET then the location is the S3 bucket specified in the
outputBucketName field when the transcription job was started with the StartTranscriptionJob
operation.

If the value is SERVICE_BUCKET then the output is stored by Amazon Transcribe and can be retrieved
using the URI in the GetTranscriptionJob response's TranscriptFileUri field.

Type: String

Valid Values: CUSTOMER_BUCKET | SERVICE_BUCKET

Required: No
TranscriptionJobName

The name of the transcription job.

134
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No
TranscriptionJobStatus

The status of the transcription job. When the status is COMPLETED, use the GetTranscriptionJob
operation to get the results of the transcription.

Type: String

Valid Values: IN_PROGRESS | FAILED | COMPLETED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

135
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Service

VocabularyInfo
Service: Amazon Transcribe Service

Provides information about a custom vocabulary.

Contents
LanguageCode

The language code of the vocabulary entries.

Type: String

Valid Values: en-US | es-US | en-AU | fr-CA | en-GB | de-DE | pt-BR | fr-FR |
it-IT | ko-KR | es-ES | en-IN | hi-IN | ar-SA | ru-RU | zh-CN | nl-NL | id-
ID | ta-IN | fa-IR | en-IE | en-AB | en-WL | pt-PT | te-IN | tr-TR | de-CH |
he-IL | ms-MY | ja-JP | ar-AE

Required: No
LastModifiedTime

The date and time that the vocabulary was last modified.

Type: Timestamp

Required: No
VocabularyName

The name of the vocabulary.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: ^[0-9a-zA-Z._-]+

Required: No
VocabularyState

The processing state of the vocabulary. If the state is READY you can use the vocabulary in a
StartTranscriptionJob request.

Type: String

Valid Values: PENDING | READY | FAILED

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

136
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

Amazon Transcribe Streaming Service


The following data types are supported by Amazon Transcribe Streaming Service:

• Alternative (p. 138)


• AudioEvent (p. 139)
• AudioStream (p. 140)
• Item (p. 141)
• Result (p. 142)
• Transcript (p. 143)
• TranscriptEvent (p. 144)
• TranscriptResultStream (p. 145)

137
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

Alternative
Service: Amazon Transcribe Streaming Service

A list of possible transcriptions for the audio.

Contents
Items

One or more alternative interpretations of the input audio.

Type: Array of Item (p. 141) objects

Required: No
Transcript

The text that was transcribed from the audio.

Type: String

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

138
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

AudioEvent
Service: Amazon Transcribe Streaming Service

Provides a wrapper for the audio chunks that you are sending.

Contents
AudioChunk

An audio blob that contains the next part of the audio that you want to transcribe.

Type: Base64-encoded binary data object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

139
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

AudioStream
Service: Amazon Transcribe Streaming Service

Represents the audio stream from your application to Amazon Transcribe.

Contents
AudioEvent

A blob of audio from your application. You audio stream consists of one or more audio events.

Type: AudioEvent (p. 139) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

140
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

Item
Service: Amazon Transcribe Streaming Service

A word or phrase transcribed from the input audio.

Contents
Content

The word or punctuation that was recognized in the input audio.

Type: String

Required: No
EndTime

The offset from the beginning of the audio stream to the end of the audio that resulted in the item.

Type: Double

Required: No
StartTime

The offset from the beginning of the audio stream to the beginning of the audio that resulted in the item.

Type: Double

Required: No
Type

The type of the item. PRONUNCIATION indicates that the item is a word that was recognized in the
input audio. PUNCTUATION indicates that the item was interpreted as a pause in the input audio.

Type: String

Valid Values: PRONUNCIATION | PUNCTUATION

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

141
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

Result
Service: Amazon Transcribe Streaming Service

The result of transcribing a portion of the input audio stream.

Contents
Alternatives

A list of possible transcriptions for the audio. Each alternative typically contains one item that contains
the result of the transcription.

Type: Array of Alternative (p. 138) objects

Required: No
EndTime

The offset in seconds from the beginning of the audio stream to the end of the result.

Type: Double

Required: No
IsPartial

Amazon Transcribe divides the incoming audio stream into segments at natural points in the audio.
Transcription results are returned based on these segments.

The IsPartial field is true to indicate that Amazon Transcribe has additional transcription data to
send, false to indicate that this is the last transcription result for the segment.

Type: Boolean

Required: No
ResultId

A unique identifier for the result.

Type: String

Required: No
StartTime

The offset in seconds from the beginning of the audio stream to the beginning of the result.

Type: Double

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

142
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

Transcript
Service: Amazon Transcribe Streaming Service

The transcription in a TranscriptEvent (p. 144).

Contents
Results

Result (p. 142) objects that contain the results of transcribing a portion of the input audio stream. The
array can be empty.

Type: Array of Result (p. 142) objects

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

143
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

TranscriptEvent
Service: Amazon Transcribe Streaming Service

Represents a set of transcription results from the server to the client. It contains one or more segments of
the transcription.

Contents
Transcript

The transcription of the audio stream. The transcription is composed of all of the items in the results
list.

Type: Transcript (p. 143) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

144
Amazon Transcribe Guia do desenvolvedor
Amazon Transcribe Streaming Service

TranscriptResultStream
Service: Amazon Transcribe Streaming Service

Represents the transcription result stream from Amazon Transcribe to your application.

Contents
BadRequestException

A client error occurred when the stream was created. Check the parameters of the request and try your
request again.

Type: Exception
HTTP Status Code: 400

Required: No
ConflictException

A new stream started with the same session ID. The current stream has been terminated.

Type: Exception
HTTP Status Code: 409

Required: No
InternalFailureException

A problem occurred while processing the audio. Amazon Transcribe terminated processing.

Type: Exception
HTTP Status Code: 500

Required: No
LimitExceededException

Your client has exceeded one of the Amazon Transcribe limits, typically the limit on audio length. Break
your audio stream into smaller chunks and try your request again.

Type: Exception
HTTP Status Code: 429

Required: No
TranscriptEvent

A portion of the transcription of the audio stream. Events are sent periodically from Amazon Transcribe
to your application. The event can be a partial transcription of a section of the audio stream, or it can be
the entire transcription of that portion of the audio stream.

Type: TranscriptEvent (p. 144) object

Required: No

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS SDK for C++


• AWS SDK for Go

145
Amazon Transcribe Guia do desenvolvedor
Common Errors

• AWS SDK for Java


• AWS SDK for Ruby V2

Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400


IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400


InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500


InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400


InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403


InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400


InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400


InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400


MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404


MissingAction

The request is missing an action or a required parameter.

146
Amazon Transcribe Guia do desenvolvedor
Common Parameters

HTTP Status Code: 400


MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403


MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400


OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403


RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on
the request is more than 15 minutes in the future.

HTTP Status Code: 400


ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503


ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400


ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests with
a query string. Any action-specific parameters are listed in the topic for that action. For more information
about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General
Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

147
Amazon Transcribe Guia do desenvolvedor
Common Parameters

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string instead
of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string instead
of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing
requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not required.
When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see
Handling Dates in Signature Version 4 in the Amazon Web Services General Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing
key.

148
Amazon Transcribe Guia do desenvolvedor
Common Parameters

Condition: Specify this parameter when you include authentication information in a query string instead
of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string instead
of in the HTTP authorization header.

Type: string

Required: Conditional

149
Amazon Transcribe Guia do desenvolvedor

AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.

150