Migrar da Mux para a Transloadit

A Mux ingere vídeo, codifica e empacota para reprodução em HLS⁠. A Transloadit é uma plataforma de processamento de mídia mais ampla: você pode fazer upload ou importar arquivos, gerar múltiplas renderizações, criar saídas em HLS ou MPEG-DASH, produzir miniaturas, adicionar legendas, transcrever áudio e armazenar os resultados no seu próprio armazenamento.

Este guia aborda um catálogo de vídeo sob demanda: ingestão, codificação, miniaturas, exportação para o seu próprio armazenamento e as mudanças na aplicação em torno delas. Ele identifica decisões sobre metadados, uploads, webhooks e segurança. A implementação do SDK do player, análise de reprodução, streaming ao vivo, DRM, empacotamento de faixas multilíngues e a reconstrução de fluxos de IA estão fora do exemplo trabalhado.

Escopo de armazenamento e DAM. O fluxo abaixo exporta para o seu bucket S3 e CDN. A migração de DAM hospedado, a importação de pastas e metadados, a transição de entrega tlcdn.com, os dry runs/manifestos de migração, os papéis da Biblioteca de Mídia, os widgets e as integrações com CMS/editores exigem um plano de migração separado. Este guia não fornece um importador de DAM hospedado.

Mapa de migração

Uma Assembly não recria um asset da Mux, seus IDs de reprodução, políticas de acesso ou histórico de análises. Decida qual aplicação é responsável por cada uma dessas tarefas antes de mover os bytes de mídia.

Escolha entre codificação antecipada ou sob demanda

Migração de presets e URLs. Atualmente a Mux nomeia seus níveis de qualidade de basic, plus e premium; plus usa codificação por título. A escada fixa de três renderizações abaixo não reproduz esse comportamento. Compare qualidade, tamanho de arquivo, proporção de tela, taxa de quadros e a maior resolução necessária em vídeos representativos antes de escolher seus próprios presets. Veja o guia de níveis de qualidade da Mux⁠. Faça um inventário das opções de URL de miniatura⁠, como tempo do quadro, dimensões e modo de ajuste, e gere as saídas correspondentes deliberadamente; carregar essas strings de consulta para uma imagem exportada não aplica transformações.

Para catálogos previsíveis, codifique as variantes antecipadamente com /video/encode e /video/adaptive. Para catálogos grandes em que apenas uma fração dos vídeos é assistida, avalie /video/ondemand com a Smart CDN para que os assets HLS sejam gerados conforme os espectadores os solicitam. Esse Robot precisa de um Template de Smart CDN compatível separado cuja ramificação de resposta termine em /file/serve. Assine as URLs no seu backend para proteger seu orçamento de codificação contra abusos. O Template de upload e exportação abaixo é para codificação antecipada, não para Smart CDN.

Exemplo de Template de vídeo adaptativo

Este Template recebe um vídeo, codifica três renderizações, as segmenta, grava playlists de variantes e uma playlist multivariante, cria uma miniatura e armazena o pacote no S3. Use um vídeo de origem por Assembly neste exemplo e escolha as renderizações apropriadas para a resolução dele; os três presets não adicionam detalhes ausentes a uma origem de baixa resolução:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded_480p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/480p",
      "ffmpeg_stack": "v7"
    },
    "encoded_720p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/720p",
      "ffmpeg_stack": "v7"
    },
    "encoded_1080p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/1080p",
      "ffmpeg_stack": "v7"
    },
    "hls": {
      "use": {
        "steps": ["encoded_480p", "encoded_720p", "encoded_1080p"],
        "bundle_steps": true
      },
      "robot": "/video/adaptive",
      "technique": "hls",
      "playlist_name": "playlist.m3u8",
      "result": true
    },
    "poster": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 1,
      "result": true
    },
    "exported_hls": {
      "use": "hls",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/${file.meta.relative_path}/${file.name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    },
    "exported_poster": {
      "use": "poster",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/posters/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

/video/adaptive define relative_path nas suas saídas. Preserve isso no caminho de exportação para que as referências da playlist sejam resolvidas. Configure Credenciais de terceiros e uma CDN que possa ler a raiz do bucket; url_prefix não configura a entrega nem concede acesso. acl: "bucket-default" não envia ACL de objeto; configure o acesso através da sua política de bucket e do acesso de origem da CDN.

Defina notify_url na sua requisição de Assembly assinada, verifique as assinaturas das notificações e exija ASSEMBLY_COMPLETED. A exportação atualiza URLs sob os Steps que as produzem: results.hls lista os segmentos e playlists; selecione a entrada chamada playlist.m3u8 com um meta.relative_path vazio. Leia a miniatura em results.poster, verificando is_temp_url: false antes de persistir sua URL. URLs temporárias da Transloadit expiram após 24 horas e não devem ser usadas para reprodução; veja salvando resultados do processamento de arquivos. Teste o manifesto exportado, as playlists de variantes e os segmentos pela sua CDN no player HLS pretendido antes de mudar o tráfego.

Importar arquivos de origem existentes da Mux

Exportação da Mux. Liste os assets em cada ambiente⁠ e siga a paginação. Mantenha os IDs de reprodução, a política, as faixas, os metadados e as configurações de processamento de cada asset em um manifesto de migração. Prefira seus arquivos originais retidos quando precisar dos bytes originais. Se a Mux tiver a única cópia, ative o acesso temporário ao master⁠ com master_access: "temporary", aguarde master.status: "ready" ou video.asset.master.ready, e use o master.url retornado para a importação. A URL dura 24 horas; solicite acesso novamente antes de tentar uma importação expirada. A Mux descreve o master como equivalente em qualidade à entrada, com a resolução controlada por max_resolution_tier, em vez de prometer os bytes originais. O MP4 inclui o vídeo e a faixa de áudio principal; preserve o áudio alternativo e baixe as faixas de texto separadamente⁠. Veja o guia de download de master da Mux⁠.

As renderizações MP4 estáticas⁠ são arquivos de entrega codificados no nível de qualidade do asset. Use o acesso ao master para o preenchimento retroativo quando você precisar do master da Mux; uma renderização estática é uma escolha separada, com suas próprias restrições de qualidade e resolução.

Se você ainda tiver arquivos de vídeo de origem no S3, use o 🤖/s3/import. Se sua aplicação armazena URLs HTTPS de origem temporárias, use o 🤖/http/import. Salve uma variante de preenchimento retroativo do Template: substitua o Step de upload :original por um Step de importação chamado imported, e altere todas as quatro referências use: ":original" (três codificações e o pôster) para use: "imported". Configure esse Step de importação com uma URL de origem autorizada ou chave S3 por Assembly. Para /s3/import, configure seu próprio credentials e path de origem; para /http/import, configure url. Por exemplo, o Step de importação HTTPS pode ler uma URL de origem selecionada pelo backend a partir do fields.source_url da sua requisição de Assembly assinada:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.source_url}"
    }
  }
}

Este é o Step de entrada substituto, não o Template de processamento completo. Use apenas URLs de origem às quais você está autorizado a acessar. URLs de origem temporárias devem permanecer válidas até a conclusão da importação; renove URLs expiradas antes de tentar novamente. Após uma exportação bem-sucedida e verificação de reprodução, grave a nova URL de reprodução no seu banco de dados, mantendo o ID do asset de origem para reconciliação.

Metadados, organização e versões. Copie para o seu catálogo os campos meta.title, meta.creator_id e meta.external_id⁠ da Mux, junto com passthrough⁠, se usado. Preserve as tags, caminhos de pasta, associações de coleções e histórico de revisões da sua aplicação no mesmo manifesto. Um Step de importação transfere mídia, não essas relações de catálogo. Atribua novas chaves de objeto a cada revisão e mantenha o mapeamento dos IDs antigos de asset e reprodução para as novas URLs de manifesto, pôster e faixa de texto. O exemplo usa o ID da Assembly como prefixo de saída, portanto novas tentativas também precisam de reconciliação antes de você publicar uma revisão substituta.

Lista de verificação

Widget de upload. O Mux Uploader usa URLs de Upload Direto da Mux⁠. Substitua esse fluxo de interface e endpoint pelo Uppy e seu plugin Transloadit usando o guia de integração com frameworks⁠. Autorize o usuário e selecione o Template permitido no seu servidor antes de retornar opções de Assembly assinadas de curta duração. Mantenha o progresso do upload distinto da conclusão do processamento; publique a URL de reprodução apenas após a exportação ser bem-sucedida.

Webhooks e automação. O evento video.asset.ready⁠ da Mux sinaliza a prontidão para reprodução; ele não sinaliza que um download de master separado ou uma renderização estática está pronta. A Mux assina webhooks no cabeçalho mux-signature⁠, e sua entrega pode incluir duplicatas e novas tentativas⁠. Implemente a verificação de notificação da Transloadit a partir da própria documentação dela. Deduplique as atualizações do catálogo por revisão de origem e ID da Assembly, trate falhas e mantenha um registro de novas tentativas antes de substituir seus manipuladores de eventos da Mux. Não reutilize o verificador de assinatura da Mux para as Assembly Notifications.

Segurança. A reprodução assinada da Mux usa JWTs gerados no seu servidor⁠. Esses tokens não autorizam a sua CDN substituta. Reconstrua a autorização do espectador usando o mecanismo da sua CDN de destino, proteja manifestos, playlists, segmentos, pôsteres e legendas em HLS, e teste requisições permitidas e negadas. As assinaturas de requisição de Assembly autorizam o processamento; elas não concedem nem restringem o acesso aos arquivos exportados. Mantenha as políticas de acesso do S3 e as permissões de origem da CDN alinhadas com a visibilidade de cada asset. Adicione o 🤖/file/virusscan se sua política de upload exigir varredura de malware; o exemplo acima não tem fluxo de varredura ou quarentena. Moderação de conteúdo e varredura de malware precisam de regras de aceitação separadas.

Robots da Mux e fluxos de IA. Os Robots da Mux⁠ fornecem fluxos de IA hospedados, incluindo legendas, resumos, capítulos e moderação; as Directives⁠ podem ordenar fluxos e acioná-los quando os assets ficam prontos. Faça um inventário dos trabalhos, dependências, saídas e decisões de moderação que sua aplicação usa. O Template de codificação acima não substitui esses fluxos. Mantenha suas saídas e a automação existente até que você tenha testado os idiomas, o esquema, a precisão, os limiares e o custo de cada substituição. Um Template da Transloadit torna os Steps de processamento inspecionáveis; ele não torna as previsões de IA determinísticas. Acompanhe a revisão do Template, os IDs de Assembly, falhas e caminhos de exportação, meça os gastos em um piloto e limite os lotes de preenchimento retroativo de acordo. Confirme as regiões de processamento e armazenamento e os requisitos de conformidade com sua equipe antes da transição.

Estimativa de esforço. Como estimativa de planejamento, reserve de dois a cinco dias úteis de engenharia para uma integração pública de vídeo sob demanda quando um desenvolvedor já tiver os originais, entrega via S3/CDN e um player HLS compatível já configurados. Isso cobre o Template, o fluxo de upload/assinatura, o manipulador de notificações e a transição piloto do catálogo; exclui o tempo de transferência em massa. Masters exclusivos da Mux, reprodução privada, mudanças de CMS, legendas, áudio alternativo e fluxos de IA exigem trabalho adicional. Meça o throughput de importação, codificação e exportação em arquivos representativos para estimar a duração total do preenchimento retroativo.

1. Decida se os vídeos devem ser codificados antecipadamente ou sob demanda.
2. Faça um inventário dos arquivos de origem, IDs de asset/reprodução, visibilidade, faixas, metadados, opções de URL e automação.
3. Crie e teste um Template para as renderizações, miniaturas e exportações necessárias. Planeje o empacotamento de faixas de texto separadamente.
4. Configure credenciais de armazenamento, acesso à CDN, CORS para reprodução em HLS e controles de entrega privada quando necessário.
5. Substitua o uploader e a integração de webhook para um piloto, mantendo o mapeamento de entrega antigo para rollback.
6. Faça o preenchimento retroativo em lotes limitados; compare duração, resolução, reprodução, pôsteres, permissões e contagens de catálogo antes de publicar cada mapeamento.
7. Atualize os registros da aplicação e do CMS para o manifesto exportado ou a URL da Smart CDN. Para URLs em um domínio que você controla, configure e teste redirecionamentos lá; atualize as referências a URLs hospedadas pela Mux na sua aplicação.
8. Verifique players incorporados, favoritos, legendas e requisições de segmentos da CDN, depois expanda a implantação. Mantenha os assets antigos disponíveis até que sua janela de rollback e os tempos de vida do cache tenham passado.