Transformar Mídia
Use esta ação quando tiver um arquivo de áudio ou vídeo no storage da sua empresa e quiser convertê-lo para outro formato.
Melhor para
- Reconverter um vídeo que você baixou ou gerou para um mp4 padrão
- Converter um arquivo de áudio para um formato específico — Opus, WAV ou FLAC
- Extrair o áudio de um vídeo: aponte um dos presets de áudio para um arquivo de vídeo e você recebe a trilha sonora
Use outra coisa quando
| Você quer | Use |
|---|---|
| Apenas ler a duração ou as dimensões de um arquivo | Inspecionar Mídia — é mais barato e gratuito na segunda vez |
| Uma transcrição da fala | Transcrever Áudio — ela já converte o áudio para você |
| Redimensionar ou converter uma imagem | Executar Código, em Python. O Pillow está disponível lá |
Campos principais
| Campo | O que faz |
|---|---|
| Arquivo | O arquivo de áudio ou vídeo a converter, normalmente step(0).file de um passo anterior |
| Bucket e Caminho completo | Uma alternativa a Arquivo quando quiser apontar diretamente para o objeto |
| Predefinição | O formato a produzir — veja a tabela abaixo |
| Finalidade | Rótulo opcional para o que este passo faz, exibido nos registros |
Predefinições
| Predefinição | Você recebe |
|---|---|
mp4 | Vídeo reconvertido para H.264 com áudio AAC, pronto para tocar em quase qualquer lugar |
ogg_opus | Áudio em Opus dentro de um contêiner Ogg — pequeno, bom para voz |
wav | Áudio sem compressão |
flac_16k_mono | Áudio mono sem perdas a 16 kHz, o formato que as ferramentas de fala costumam esperar |
O que passos posteriores podem usar
| Valor | O que é |
|---|---|
step(N).jobId | O ID do trabalho de conversão |
step(N).jobStatus | O status do trabalho no momento em que foi enfileirado — normalmente pending |
step(N).preset | A predefinição com que o trabalho foi enfileirado |
Esta ação enfileira o trabalho — ela não espera por ele
O passo devolve um ID de trabalho e termina imediatamente. Converter um vídeo grande pode levar minutos, então isso acontece em segundo plano.
Ou seja, o arquivo convertido não está disponível para o passo seguinte da mesma execução. Não tente enviar step(N).output — ainda não há nada ali.
Para usar o resultado, acompanhe o trabalho até ele terminar:
- a ferramenta
get_transcode_jobouGET /v1/transcodes/{id}, usando o ID do trabalho; ou - um workflow agendado que procure trabalhos de conversão com status
done.
Quando o trabalho termina, output.fullPath e output.bucket são o arquivo convertido.
Você também pode consultar um trabalho a qualquer momento pela API (GET /v1/transcodes/{id}) ou pela ferramenta get_transcode_job.
Limites
| Limite | Valor |
|---|---|
| Tamanho do arquivo | 512 MiB (536.870.912 bytes) |
| Duração, predefinições de vídeo | 30 minutos |
| Duração, predefinições de áudio | 4 horas |
| Trabalhos enfileirados ao mesmo tempo | 10 por empresa |
Se precisar verificar a duração de um arquivo antes de converter, use Inspecionar Mídia primeiro e ramifique a partir de step(N).durationSeconds.
Custo
A conversão de mídia é cobrada como tempo de transcodificação, descontada da franquia de transcodificação do seu plano. Arquivos maiores e mais longos custam mais.
Converter o mesmo arquivo para a mesma predefinição de novo é gratuito. O resultado é guardado e reaproveitado, então um workflow que roda várias vezes sobre o mesmo arquivo paga apenas uma vez. Alterar o arquivo altera o resultado, então um arquivo atualizado é convertido novamente.
Quando um trabalho falha
Um trabalho que falhou traz o motivo em doc.errorCode. Estes são os que você tem mais chance de ver:
| Código | O que aconteceu |
|---|---|
too_large | O arquivo passa de 512 MiB |
too_long | O arquivo é mais longo do que a predefinição permite |
undecodable | O arquivo não pôde ser lido como mídia, ou esta predefinição não consegue produzi-lo. Tentar de novo não ajuda |
output_too_large | O arquivo convertido ficou grande demais |
storage_quota_exceeded | A sua franquia de armazenamento seria estourada, então o arquivo convertido não pôde ser guardado. Permanente até você liberar espaço |
unavailable | O serviço de conversão não pôde ser alcançado. Vale tentar de novo |
busy | O serviço de conversão ficou lotado tempo demais — veja abaixo |
max_attempts | O trabalho foi pego e perdido várias vezes seguidas, sem nunca terminar, e por isso foi abandonado |
O errorCode sozinho não prova que houve falha: um trabalho que apenas voltou para a fila também carrega um — busy, ou company_lookup_failed — enquanto o status dele voltou para pending. Leia o status primeiro, e o errorCode só para explicá-lo.
A lista não é fechada, e unavailable cobre mais do que uma indisponibilidade. Uma recusa que a etapa de conversão levanta com um código próprio mantém esse código. Todo o resto cai em unavailable — inclusive uma recusa de plano ou de crédito levantada depois que o trabalho começou: a franquia é conferida de novo quando o worker pega o trabalho, logo antes de codificar, então se a sua franquia de transcodificação tiver acabado (ou a carteira de pagamento por uso tiver chegado ao piso) depois de você enfileirar o trabalho, ele é registrado como unavailable, e não como um erro de cobrança. Por isso, unavailable só vale a pena retentar depois de você confirmar que ainda está dentro da franquia de transcodificação — caso contrário a mesma verificação recusa a retentativa de saída.
Se o serviço de conversão estiver apenas ocupado, o trabalho normalmente não falha: ele volta para a fila com um pequeno atraso e roda logo em seguida, sem gastar nenhuma das suas tentativas. Isso vale até um certo ponto, não para sempre: depois de 20 voltas para a fila, o trabalho para de esperar e falha com busy. Essas 20 são um orçamento compartilhado — o mesmo contador também é gasto por voltas para a fila por motivos internos não relacionados — então um trabalho que já foi devolvido uma ou duas vezes por outra coisa desiste antes de completar 20 esperas por lotação.