API de Transcrição¶

A API de Transcrição permite controlar o processo de transcrição sobre os arquivos cadastrados. O processo é executado individualmente para cada arquivo, independente do lote. A ordem de processamento é definida por uma fila interna de trabalho. Cada arquivo possui um atributo de controle que indica se ele deve ser colocado em uma das várias filas de trabalho que executam o processo de transcrição. O atributo de controle do processo possui os valores:

IDLE: o arquivo está ocioso e não está na fila de trabalho;

RUNNING: o arquivo está na fila de trabalho;

PAUSED: o arquivo foi colocado em espera. A etapa atual do processo será concluída;

FINISHED: o arquivo foi finalizado;

FAILED: ocorreu uma falha em alguma etapa do processo e o arquivo não será processado;

Obs: em caso de falha, o arquivo deve ser verificado pois pode ter havido alguma incompatibilidade de formato ou falha genérica. O processo pode ser reiniciado após a operação de reset.

Quando um arquivo está no estado RUNNING ele será colocado em uma fila de trabalho de acordo com a etapa do processo de transcrição. A etapa em que o arquivo se encontra está definida em um atributo de estado do processo, e pode ter um dos seguintes valores:

INITIAL: o arquivo está no estado inicial, após a criação do registro ou reset;

NORMALIZING: o arquivo está na fila de trabalho de normalização;

NORMALIZED: o arquivo foi normalizado e a diarização ainda não iniciou;

DIARIZING: o arquivo está na fila de trabalho de diarização;

DIARIZED: o arquivo foi diarizado e o reconhecimento ainda não iniciou;

RECOGNIZING: o arquivo está na fila de trabalho do reconhecimento;

RECOGNIZED: o arquivo foi reconhecido;

Quando o arquivo atinge o estado “RECOGNIZED”, a transcrição é considerada finalizada. A partir desse momento, o resultado da transcrição pode ser consultado com segurança, pois todos os dados estarão completos. O resultado pode ser consultado a qualquer momento, porém poderão apresentar resultados parciais.

A transcrição de um lote de arquivos é considerado finalizado quando todos os arquivos associados ao lote possuem estado RECOGNIZED. No entanto, esse conceito é relativo pois a qualquer momento novos arquivos podem ser adicionados ao lote.

Iniciar transcrição de arquivo¶

Inicia a transcrição de um arquivo. O arquivo deve estar depositado no diretório de trabalho e cadastrado no sistema. O controle do arquivo deve estar em “IDLE” ou “PAUSED”, e após a operação será colocado em “RUNNING”.

Requisição

GET /trd/transcription/start/audiofile/{id}

Parâmetros da requisição

A requisição contém a variável de path:

id: identificação do arquivo cadastrado no sistema.

Resultado

O resultado é o registro do arquivo, e possui a seguinte estrutura:

audioChannels: informação adicional sobre o canal de áudio, gerado após a normalização (opcional)

batch: nome da pasta do lote de arquivos

control: controle do processo de transcrição

create_date: data de criação do cadastro do arquivo

filename: nome do arquivo

format: formato do arquivo

info: informações adicionais sobre o arquivo de áudio, geradas após a normalização (opcional)

md5: hash MD5 do arquivo, gerado no momento do cadastro

size: tamanho do arquivo (em bytes)

status: etapa do processo de transcrição

A informação de canal é uma lista e cada elemento possui a seguinte estrutura:

bandwidth: largura de banda (kbps)

channel: identificação do canal

duration: tempo de fala (seg)

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/start/audiofile/5b76faed4d27fc0001331dcc

Resultado JSON:

{
  "audioChannels": [
    {
      "bandwidth": "4000",
      "channel": 1,
      "duration": 520
    }
  ],
  "batch": "folder1",
  "control": "FINISHED",
  "create_date": "Fri, 08 Mar 2019 18:02:16 GMT",
  "filename": "file1.wav",
  "format": "wav",
  "info": {
    "BitRate": "128000",
    "BitRateMode": "Constant",
    "Channels": "1",
    "Codec": "PCM",
    "Comment": "",
    "Compression_Mode": "",
    "Duration": "00:08:40.000",
    "EncodedLibrary": "",
    "FileCreatedDate": "",
    "FileModifiedDate": "UTC 2019-03-08 18:02:16",
    "FileSize": "8320044",
    "Format": "Wave",
    "InputSamplingRate": "8000",
    "OutputSamplingRate": "8000",
    "ReduntantChannel": false,
    "Track": ""
  },
  "last_update": "Fri, 08 Mar 2019 18:02:16 GMT",
  "md5": "bee0c78600f52fdf65edc1a742970313",
  "size": 8320044,
  "status": "RECOGNIZED"
}

Iniciar transcrição de lote¶

Inicia a transcrição de um lote de arquivos. Os arquivos devem estar depositados no diretório de trabalho e cadastrados no sistema. Os arquivos que estiverem com controle em “IDLE” ou “PAUSED” serão colocados em “RUNNING”. Arquivos em “RUNNING” serão ignorados.

Requisição

GET /trd/transcription/start/batch/{batch}

Parâmetros da requisição

A requisição contém a variável de path:

batch: nome da pasta do lote no diretório de trabalho.

Resultado

O resultado é uma lista com a URL dos arquivos do lote.

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/start/batch/folder1

Resultado JSON:

{
  "file1.wav":"http://localhost:8080/trd/audiofile/5b9bdfc2be077700018e768b",
  "file2.wav":"http://localhost:8080/trd/audiofile/5b76faed4d27fc0001331dcc"
}

Interromper transcrição de arquivo¶

Interrompe a transcrição de um arquivo. O controle do arquivo deve estar em “RUNNING” e após a operação será colocado em “PAUSED”. Se o arquivo estiver na fila de trabalho, a transcrição será interrompida somente após o término da etapa atual. Esse processo pode demorar dependendo do tamanho da fila de trabalho.

Requisição

GET /trd/transcription/stop/audiofile/{id}

Parâmetros da requisição

A requisição contém a variável de path:

id: identificação do arquivo cadastrado no sistema.

Resultado

O resultado é o registro do arquivo (ver resultado do comando “/start/audiofile/”).

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/stop/audiofile/5b76faed4d27fc0001331dcc

Interromper transcrição de lote¶

Interrompe a transcrição de um lote de arquivos. Os arquivos que estiverem com controle em “RUNNING” serão colocados em “PAUSED”. Se o arquivo estiver na fila de trabalho, a transcrição será interrompida somente após o término da etapa atual. Esse processo pode demorar dependendo do tamanho da fila de trabalho.

Requisição

GET /trd/transcription/stop/batch/{batch}

Parâmetros da requisição

A requisição contém a variável de path:

batch: nome da pasta do lote no diretório de trabalho.

Resultado

O resultado é uma lista com a URL dos arquivos do lote (ver resultado do comando “/start/batch/”).

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/stop/batch/folder1

Estado da transcrição de arquivo¶

Obtém o estado (andamento) da transcrição de um arquivo.

Requisição

GET /trd/transcription/status/audiofile/{id}

Parâmetros da requisição

A requisição contém a variável de path:

id: identificação do arquivo cadastrado no sistema.

Resultado

O resultado é um objeto que possui a seguinte estrutura:

accounted_speech: contabilização de segmentos de fala processados. Ele possui os atributos:

RECOGNIZED: acumulado dos segmentos reconhecidos

seconds: total de fala reconhecida

segments: total de segmentos reconhecidos

NO_MATCH: acumulado dos segmentos que não puderam ser reconhecidos

seconds: total de fala não reconhecida

segments: total de segmentos não reconhecidos

PROCESSING: acumulado dos segmentos ainda em processamento

seconds: total de fala em processamento

segments: total de segmentos em processamento

FAILURE: acumulado dos segmentos onde ocorreram falha genérica de reconhecimento

seconds: total de fala não reconhecida

segments: total de segmentos com falha

total_segments: número total de segmentos identificados após a diarização

total_speech: duração total da fala identificada após a diarização

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/status/audiofile/5b76faed4d27fc0001331dcc

Resultado JSON:

{
  "accounted_speech": {
    "RECOGNIZED": {
      "seconds": 81.847,
      "segments": 30
    }
  },
  "total_segments": 30,
  "total_speech": 81.847
}

Estado da transcrição de lote¶

Obtém o estado (andamento) da transcrição de um lote de arquivos.

Requisição

GET /trd/transcription/status/batch/{batch}

Parâmetros da requisição

A requisição contém a variável de path:

batch: nome da pasta do lote no diretório de trabalho.

Resultado

O resultado é um objeto que possui a seguinte estrutura:

ETA: estimativa do tempo de término do lote (em segundos), com base na carga de trabalho atual do sistema. Esse valor pode mudar de acordo com alterações de volume de transcrição o disponibilidade de recursos do sistema

accounted_recognition: contabilização de segmentos por estado de reconhecimento. Possui os mesmos atributos da requisição de estado de transcrição de arquivo.

accounted_control: contabilização de arquivos por estado de controle. Ele possui os atributos:

[CONTROL]: acumulado dos arquivos por cada um dos estados de controle (IDLE, RUNNING…)

bytes: total de bytes

files: total de arquivos

accounted_control: contabilização de arquivos por status de transcrição. Ele possui os atributos:

[STATUS]: acumulado dos arquivos por cada um dos estados de processo (INITIAL, NORMALIZING…)

bytes: total de bytes

files: total de arquivos

RECOGNIZED: acumulado dos arquivos reconhecidos

bytes: total de bytes

files: total de arquivos

batch: nome da pasta do lote de arquivos

diarization: indicador de progresso da etapa de diarização sobre o total de arquivos do lote

normalization: indicador de progresso da etapa de normalização sobre o total de arquivos do lote

progress: indicador de progresso do processo geral sobre o total de arquivos do lote

recognition: indicador de progresso do processo geral sobre o total de arquivos do lote

speech2audio_rate: relação entre o total de fala e duração do áudio

speech2audio_rate_ch: relação entre o total de fala e duração do áudio para o canal

total_audio: duração total de áudio de todos os arquivos do lote

total_bytes: número de bytes de todos os arquivos do lote

total_files: número de arquivos do lote

total_segments: número total de segmentos dos arquivos do lote

total_speech: duração total de fala dos arquivos do lote

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/status/batch/folder1

Resultado JSON:

{
  "ETA": 0,
  "accounted_control": {
    "FINISHED": {
      "bytes": 1.1115492E7,
      "files": 3
    }
  },
  "accounted_recognition": {
    "RECOGNIZED": {
      "seconds": 542.775,
      "segments": 144
    }
  },
  "accounted_status": {
    "RECOGNIZED": {
      "bytes": 1.1115492E7,
      "files": 3
    }
  },
  "batch": "teste",
  "diarization": 1,
  "normalization": 1,
  "progress": 1,
  "recognition": 1,
  "speech2audio_rate": 0.7812972,
  "speech2audio_rate_ch": 0.7812972,
  "total_audio": 694.71,
  "total_audio_ch": 694.71,
  "total_bytes": 1.1115492E7,
  "total_files": 3,
  "total_segments": 144,
  "total_speech": 542.775
}

Reset da transcrição de arquivo¶

A operação de reset apaga os dados da transcrição de um arquivo e restaura o controle para “IDLE” e o estado para “INITIAL”. É uma operação útil para repetir a transcrição sobre um arquivo. A operação de reset retorna um novo id de arquivo.

Requisição

GET /trd/transcription/reset/audiofile/{id}

Parâmetros da requisição

A requisição contém a variável de path:

id: identificação do arquivo cadastrado no sistema.

Resultado

O resultado são as informações do novo arquivo de áudio, com novo ID e em estado inicial.

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/reset/audiofile/5b76faed4d27fc0001331dcc

Reset da transcrição de lote¶

A operação de reset apaga os dados da transcrição de um lote de arquivos, para aqueles arquivos que não finalizaram ou estão em falha. Opcionalmente, arquivos finalizados também podem ser afetados, o que indica que todos os dados do lote serão apagados.

Requisição

GET /trd/transcription/reset/batch/{batch}

Parâmetros da requisição

A requisição contém a variável de path:

batch: nome da pasta do lote no diretório de trabalho.

Opcionalmente, a requisição contém a variável de query:

hard: indica se arquivos finalizados devem ser afetados (valor default = false) (opcional).

Resultado

O resultado é o status da transcrição do lote.

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/reset/batch/folder1?hard=true

Resultado da transcrição de arquivo¶

Obtém o resultado da transcrição de um arquivo.

Requisição

GET /trd/transcription/result/audiofile/{id}

Parâmetros da requisição

A requisição contém a variável de path:

id: identificação do arquivo cadastrado no sistema.

Opcionalmente, a requisição contém a variável de query:

format: indica o formato CSV ou JSON (valor default = json) (opcional)

Resultado

O resultado pode ser um objeto JSON ou CSV. O objeto JSON possui a seguinte estrutura:

audioChannels: informação adicional sobre o canal de áudio, gerado após a normalização

batch: nome da pasta do lote de arquivos

control: controle do processo de transcrição

create_date: data de criação do cadastro do arquivo

filename: nome do arquivo

format: formato do arquivo

info: informações adicionais sobre o arquivo de áudio, geradas após a normalização (opcional)

md5: hash MD5 do arquivo, gerado no momento do cadastro

size: tamanho do arquivo (em bytes)

segments: lista com os segmentos de fala. Cada elemento possui a seguinte estrutura:

channel: identificação do canal

end: fim da fala (seg)

score: índice de confiança

speaker: identificação do locutor

start: início da fala (seg)

status: status do reconhecimento:

RECOGNIZED

NO_MATCH

NO_INPUT_TIMEOUT

RECOGNITION_TIMEOUT

NO_SPEECH

FAILURE

text: texto reconhecido

words: lista de palavras com detalhes de alinhamento temporal e confiança

O objeto CSV devolve uma versão simplificada do resultado para visualização por parte do usuário, com as seguintes campos:

contador: número sequencial do segmento de fala

canal: número do canal de áudio (1 ou 2)

início: marca temporal de início do segmento de fala (mm:ss:sss)

fim: marca temporal de fim do segmento de fala (mm:ss:sss)

speaker: identificação do locutor

texto: texto transcrito

score: índice de confiança da transcrição

reservado 1: campo reservado

reservado 2: campo reservado

bitrate: taxa do áudio (kbps)

reservado 3: campo reservado

Exemplos

Chamada REST:

curl -X GET http://localhost:8080/trd/transcription/result/audiofile/5b76faed4d27fc0001331dcc

Resultado JSON:

{
  "audioChannels": [
    {
      "bandwidth": "4000",
      "channel": 1,
      "duration": 103.773
    }
  ],
  "batch": null,
  "control": "FINISHED",
  "create_date": "Fri, 08 Mar 2019 18:02:15 GMT",
  "domain_id": null,
  "filename": "file1.wav",
  "format": "wav",
  "info": {
    "BitRate": "128000",
    "BitRateMode": "Constant",
    "Channels": 1,
    "Codec": "PCM",
    "Comment": "",
    "Compression_Mode": "",
    "Duration": "00:01:43.773",
    "EncodedLibrary": "",
    "FileCreatedDate": "",
    "FileModifiedDate": "UTC 2019-03-08 18:02:15",
    "FileSize": "1660412",
    "Format": "Wave",
    "InputSamplingRate": "8000",
    "OutputSamplingRate": "8000",
    "RedundantChannel": false,
    "Track": ""
  },
  "last_update": "Fri, 08 Mar 2019 18:02:15 GMT",
  "md5": "780480f5ad082b345b3ef15ccefde9f4",
  "segments": [
    {
      "channel": 1,
      "end": 7.4,
      "score": 97,
      "speaker": "1",
      "start": 0.56,
      "status": "RECOGNIZED",
      "text": "boa tarde eu posso falar com a sabrina",
      "words": []
    }
}

Resultado da transcrição de lote¶

Realiza o download do resultado da transcrição de um lote em formato ZIP. O resultado da transcrição de cada arquivo é empacotado em um arquivo ZIP, no formato JSON ou CSV.

Requisição

GET /trd/transcription/result/batch/{batch}

Parâmetros da requisição

A requisição contém a variável de path:

batch: nome da pasta do lote no diretório de trabalho.

lm.uri: Identificador do modelo de língua.

hints.words: Lista de words hints.

Opcionalmente, a requisição contém a variável de query:

format: indica o formatos csv , json ou json-array (valor default = json) (opcional)

Resultado

Download do arquivo ZIP

Exemplos

Chamada REST:

curl -X GET 'http://localhost:8080/trd/transcription/result/batch/<nome_lote>?format=csv' --output <nome_lote>.zip