Transformar Medios
Usa esta acción cuando tengas un archivo de audio o vídeo en el almacenamiento de tu empresa y quieras convertirlo a otro formato.
Ideal para
- Reconvertir un vídeo que descargaste o generaste a un mp4 estándar
- Convertir un archivo de audio a un formato concreto — Opus, WAV o FLAC
- Extraer el audio de un vídeo: apunta uno de los preajustes de audio a un archivo de vídeo y obtienes su banda sonora
Usa otra cosa cuando
| Quieres | Usa |
|---|---|
| Solo leer la duración o las dimensiones de un archivo | Inspeccionar Medios — es más barato y gratuito la segunda vez |
| Una transcripción del habla | Transcribir Audio — ya convierte el audio por ti |
| Redimensionar o convertir una imagen | Ejecutar Código, en Python. Pillow está disponible allí |
Campos principales
| Campo | Qué hace |
|---|---|
| Archivo | El archivo de audio o vídeo a convertir, normalmente step(0).file de un paso anterior |
| Bucket y Ruta completa | Una alternativa a Archivo cuando quieras apuntar directamente al objeto |
| Preajuste | El formato a producir — mira la tabla de abajo |
| Propósito | Etiqueta opcional para lo que hace este paso, visible en los registros |
Preajustes
| Preajuste | Obtienes |
|---|---|
mp4 | Vídeo reconvertido a H.264 con audio AAC, listo para reproducirse casi en cualquier sitio |
ogg_opus | Audio en Opus dentro de un contenedor Ogg — ligero, bueno para voz |
wav | Audio sin comprimir |
flac_16k_mono | Audio mono sin pérdidas a 16 kHz, el formato que suelen esperar las herramientas de voz |
Qué pueden usar los pasos posteriores
| Valor | Qué es |
|---|---|
step(N).jobId | El ID del trabajo de conversión |
step(N).jobStatus | El estado del trabajo al encolarse — normalmente pending |
step(N).preset | El preajuste con el que se encoló el trabajo |
Esta acción encola el trabajo — no espera a que termine
El paso devuelve un ID de trabajo y termina de inmediato. Convertir un vídeo grande puede tardar minutos, así que ocurre en segundo plano.
Eso significa que el archivo convertido no está disponible para el paso siguiente de la misma ejecución. No intentes enviar step(N).output — todavía no hay nada ahí.
Para usar el resultado, consulta el trabajo hasta que termine:
- la herramienta
get_transcode_joboGET /v1/transcodes/{id}, con el ID del trabajo; o - un flujo de trabajo programado que busque trabajos de conversión con estado
done.
Cuando el trabajo termina, output.fullPath y output.bucket son el archivo convertido.
También puedes consultar un trabajo en cualquier momento mediante la API (GET /v1/transcodes/{id}) o la herramienta get_transcode_job.
Límites
| Límite | Valor |
|---|---|
| Tamaño del archivo | 512 MiB (536.870.912 bytes) |
| Duración, preajustes de vídeo | 30 minutos |
| Duración, preajustes de audio | 4 horas |
| Trabajos encolados a la vez | 10 por empresa |
Si necesitas comprobar la duración de un archivo antes de convertirlo, usa Inspeccionar Medios primero y ramifica según step(N).durationSeconds.
Coste
La conversión de medios se factura como tiempo de transcodificación, contra la cuota de transcodificación de tu plan. Los archivos más largos y más grandes cuestan más.
Convertir el mismo archivo al mismo preajuste otra vez es gratis. El resultado se guarda y se reutiliza, así que un flujo que se ejecuta repetidamente sobre el mismo archivo paga una sola vez. Cambiar el archivo cambia el resultado, así que un archivo actualizado se vuelve a convertir.
Cuando un trabajo falla
Un trabajo fallido lleva el motivo en doc.errorCode. Estos son los que tienes más probabilidad de ver:
| Código | Qué pasó |
|---|---|
too_large | El archivo supera los 512 MiB |
too_long | El archivo es más largo de lo que permite el preajuste |
undecodable | El archivo no pudo leerse como medio, o este preajuste no puede producirlo. Reintentar no ayuda |
output_too_large | El archivo convertido resultó demasiado grande |
storage_quota_exceeded | Se superaría tu cuota de almacenamiento, así que el archivo convertido no se pudo guardar. Permanente hasta que liberes espacio |
unavailable | No se pudo contactar con el servicio de conversión. Merece la pena reintentar |
busy | El servicio de conversión estuvo saturado demasiado tiempo — mira más abajo |
max_attempts | El trabajo se tomó y se perdió una y otra vez, sin llegar a terminar nunca, así que se abandonó |
El errorCode por sí solo no prueba que haya habido un fallo: un trabajo que simplemente volvió a la cola también lleva uno — busy, o company_lookup_failed — mientras su status ha vuelto a pending. Lee primero el status, y el errorCode solo para explicarlo.
La lista no está cerrada, y unavailable cubre más que una caída del servicio. Un rechazo que el paso de conversión levanta con un código propio conserva ese código. Todo lo demás acaba en unavailable — incluido un rechazo de plan o de crédito levantado después de que el trabajo empezara: la cuota se comprueba otra vez cuando el worker toma el trabajo, justo antes de codificar, así que si tu cuota de transcodificación se agotó (o el monedero de pago por uso llegó a su suelo) después de encolarlo, el trabajo se registra como unavailable, no como un error de facturación. Así que unavailable merece un reintento solo después de comprobar que sigues dentro de tu cuota de transcodificación — si no, la misma comprobación rechaza el reintento de plano.
Si el servicio de conversión simplemente está ocupado, el trabajo normalmente no falla: vuelve a la cola con un pequeño retraso y se ejecuta poco después, sin gastar ninguno de sus intentos. Eso vale hasta cierto punto, no para siempre: después de 20 vueltas a la cola, el trabajo deja de esperar y falla con busy. Esas 20 son un presupuesto compartido — el mismo contador lo gastan también las vueltas a la cola por motivos internos no relacionados — así que un trabajo que ya fue devuelto una o dos veces por otra cosa se rinde antes de completar 20 esperas por saturación.