Pré-visualizações de mídia sob demanda com o Smart CDN

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos · Mostrar biografia

Um navegador de arquivos raramente precisa baixar um vídeo inteiro só para mostrar o que ele contém. Uma miniatura, uma forma de onda de áudio ou um ícone de tipo de arquivo pode fornecer esse contexto com uma resposta muito menor.

O Robot /file/preview EN (English) gera essas pré-visualizações. O Smart CDN pode executar o fluxo de processamento quando uma pré-visualização é solicitada e armazenar o resultado em cache. Este artigo combina uma demonstração funcional, um Template com limites definidos e a assinatura de URLs no servidor.

O que é o Smart CDN da Transloadit?

O Smart CDN conecta uma URL de entrega a uma Assembly da Transloadit. Em um cache miss (quando ainda não há resultado em cache), a Transloadit importa a origem, executa o Template e entrega o resultado. Uma requisição posterior pode reutilizar um derivado em cache enquanto ele continuar disponível e armazenável em cache.

Uma resposta com cache aquecido e um cache miss têm custos e latência diferentes. A localização da origem, o formato do arquivo, a estratégia de pré-visualização, o tempo de vida do cache e o padrão de requisições influenciam o resultado. Nossas medições de desempenho publicadas descrevem uma configuração de teste específica, não uma garantia de latência para todo arquivo.

O que é o recurso de pré-visualização de arquivos?

O Robot tenta as estratégias de pré-visualização configuradas para cada categoria de arquivo. Por exemplo, ele pode procurar uma arte de capa incorporada antes de extrair um quadro do vídeo. Um ícone pode ser o último fallback quando não houver uma pré-visualização mais rica. A referência do Robot EN (English) é a fonte oficial para formatos suportados, ordem das estratégias, limites e parâmetros.

Principais recursos

• Imagens podem virar miniaturas redimensionadas.
• Vídeos podem usar a arte de capa, um quadro ou outras estratégias de vídeo suportadas.
• Áudios podem usar a arte de capa ou uma forma de onda.
• Documentos podem usar uma página renderizada.
• Páginas web podem usar uma captura de tela.
• Pacotes de arquivos e conteúdo não suportado podem usar um ícone quando esse fallback estiver configurado.

Estas são pré-visualizações, não versões completas do original. Uma forma de onda não é um player de áudio, e uma miniatura não é um download de vídeo. Teste seus próprios formatos e mantenha um fallback utilizável para falhas.

Benefícios das pré-visualizações de arquivos

Gerar pré-visualizações sob demanda pode evitar trabalho com arquivos que ninguém visualiza. O cache pode reduzir o processamento repetido, e respostas menores podem reduzir a banda de entrega. O pré-processamento continua útil quando todo arquivo precisa de uma pré-visualização antes da publicação ou quando um atraso de processamento na primeira visualização é inaceitável.

A economia depende da carga de trabalho. Uma pré-visualização pode até ser maior que uma imagem de origem minúscula, então meça os bytes entregues em vez de presumir um percentual fixo de redução.

Demonstração interativa

A demonstração usa quatro arquivos de exemplo públicos. Ela só busca uma pré-visualização quando você envia o formulário. Ela não faz upload dos seus arquivos, não baixa o vídeo ou o áudio original para o seu navegador nem executa uma consulta de metadados de uma Assembly.

A demonstração pública roda no Workspace my-app da Transloadit, com um Template existente que aceita w, h, f, r, vs e v. O exemplo de produção abaixo usa um Template separado e mais restrito, que aceita apenas size como campo de query.

Como usar a demonstração

Escolha uma origem, as dimensões e o formato. Selecione a opção Estratégia de redimensionamento e depois selecione Gerar pré-visualização. Alterações feitas pelo teclado e por toque usam a mesma ação de envio. A URL e as medições exibidas correspondem ao último resultado enviado, não a configurações que você alterou sem enviar.

O tempo de busca observado inclui o recebimento do corpo da pré-visualização no seu navegador. É uma única observação, não um benchmark controlado com cache frio ou com cache aquecido. O cache do navegador, sua conexão e o processamento podem afetá-lo.

A comparação de entrega é uma estimativa à parte: ela aplica um único preço de banda escolhido e uma única contagem de requisições aos dois arquivos. Ela exclui processamento, armazenamento, taxas por requisição, planos, impostos e novas tentativas. Não é uma comparação entre faturas completas da Transloadit e da AWS. Baixar um vídeo original também não equivale a exibir uma pré-visualização estática.

Como começar

1. Cadastre-se na Transloadit

Crie uma conta e confira os planos e limites atuais.

2. Crie um Workspace

Os exemplos usam o Workspace de exemplo your-workspace. Substitua-o pelo seu próprio Workspace ao criar URLs. O Workspace da demonstração pública é separado da sua conta.

3. Crie um Template

Crie um Template chamado preview. Esta versão fixa deliberadamente o formato de saída e a estratégia de redimensionamento e aceita apenas um campo de tamanho. Substitua my-website.com por uma origem HTTPS que você controla. Publique lá os dois arquivos de exemplo usados abaixo ou altere o mapa de arquivos mantido pelo servidor para seus próprios nomes de objetos imutáveis.

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "https://my-website.com/${fields.input}"
    },
    "previewed": {
      "robot": "/file/preview",
      "use": "imported",
      "format": "png",
      "width": "${fields.size}",
      "height": "${fields.size}",
      "resize_strategy": "fit",
      "zoom": false
    },
    "served": {
      "robot": "/file/serve",
      "use": "previewed",
      "cache_duration": 3600
    }
  }
}

O programa de assinatura abaixo permite apenas três tamanhos e duas entradas conhecidas. O Template sozinho não impõe essa lista de permissões. Defina require_signature_auth como 1 pela API de Templates, como um atributo do Template fora de steps. Antes de publicar o Template, verifique se requisições sem assinatura e adulteradas são rejeitadas. Não exponha uma URL de importação arbitrária nem um endpoint de transformação de uso geral.

4. Use o Smart CDN

A estrutura de URL sem assinatura para este Template é:

https://your-workspace.tlcdn.com/preview/photo-v1.jpg?size=320

O caminho identifica o Workspace, o Template e a entrada. A entrada se torna ${fields.input}, e a query fornece ${fields.size}. Este exemplo estrutural não é um token de autorização utilizável. Use a URL assinada retornada pelo programa executado no servidor, apresentado na próxima seção.

Inclua uma versão nos nomes dos arquivos de origem ao alterar seu conteúdo, como photo-v2.jpg. Substituir um objeto com o mesmo nome não faz todos os derivados em cache desaparecerem imediatamente.

5. Implemente medidas de segurança

Use a Auth Key do Workspace habilitada para o Smart CDN e o respectivo Auth Secret. O Auth Secret precisa ficar no servidor. Configure as variáveis de ambiente pelo seu processo habitual de gerenciamento de segredos, e não em um bundle do navegador ou em um arquivo versionado.

Esta é uma CLI para operadores confiáveis, não uma implementação de autenticação HTTP. Ela assina uma pequena lista de permissões mantida pelo servidor sem fazer nenhuma requisição de rede. Use o Node.js 24 ou mais recente e instale o SDK oficial:

yarn add @transloadit/node@4.12.0

Salve isto como sign-preview.mjs:

import { Transloadit } from '@transloadit/node'

const inputs = new Map([
  ['photo', 'photo-v1.jpg'],
  ['audio', 'audio-v1.mp3'],
])
const sizes = new Set(['160', '320', '640'])

function main() {
  const [name, size, ...extra] = process.argv.slice(2)
  const input = inputs.get(name)
  if (!input || !sizes.has(size) || extra.length !== 0) {
    throw new Error('Expected one known file name and preview size')
  }
  const authKey = process.env.TRANSLOADIT_AUTH_KEY
  const authSecret = process.env.TRANSLOADIT_AUTH_SECRET
  const workspace = process.env.TRANSLOADIT_WORKSPACE
  if (!authKey || !authSecret || !workspace || !/^[a-z0-9-]+$/.test(workspace)) {
    throw new Error('Missing or invalid server configuration')
  }
  const client = new Transloadit({ authKey, authSecret })
  const url = client.getSignedSmartCDNUrl({
    workspace,
    template: 'preview',
    input,
    urlParams: { size: Number(size) },
    expiresAt: Date.now() + 60 * 60 * 1000,
  })
  process.stdout.write(url + '\n')
}

try {
  main()
} catch {
  console.error('Could not sign preview. Check the file, size, and server configuration.')
  process.exitCode = 1
}

Com essas três variáveis de ambiente configuradas, execute:

node sign-preview.mjs photo 320

A saída é uma URL do tipo bearer: qualquer pessoa que a obtenha pode usá-la durante seu período de validade. Não a coloque em ferramentas de analytics, relatórios de erro ou logs públicos. Este exemplo a imprime intencionalmente para o operador; uma aplicação deve entregá-la apenas ao solicitante autorizado.

Em um endpoint de aplicação, autentique primeiro o usuário, resolva um identificador de ativo pelo seu banco de dados e verifique o acesso a esse ativo específico antes de assinar. Limite as variantes permitidas e a frequência de emissão. Não trate o conhecimento de um nome de arquivo como prova de autorização e não aceite origens, Templates, assinaturas ou tempos de expiração fornecidos pelo chamador.

O SDK gera a assinatura e os parâmetros de query de autenticação. A expiração é expressa em milissegundos desde a época UNIX. Aqui, ela é definida explicitamente para uma hora. O tempo de vida efetivo do cache também é limitado pelo tempo de vida restante da assinatura; escolha-o de acordo com a sensibilidade do conteúdo e as necessidades de cache. Consulte assinatura e tempo de vida do cache para conhecer o contrato atual.

6. Personalize o comportamento

Adicione parâmetros de forma deliberada depois de validá-los no seu servidor. Mantenha pequenas as combinações permitidas para limitar a quantidade de derivados e o custo. Consulte as estratégias de redimensionamento e a referência de estratégias de pré-visualização EN (English).

Para conteúdo sensível ou enviado por usuários, revise o acesso de importação, os limites de processamento e o que uma pré-visualização pode revelar. Uma miniatura ou uma página extraída também pode conter informações privadas.

Use seu próprio armazenamento

Use o Robot de importação adequado e as Credenciais de Template para armazenamento privado na nuvem. Mantenha as credenciais de armazenamento nessa configuração no servidor. Não coloque credenciais de bucket nem uma URL de origem pré-assinada arbitrária em um link público de pré-visualização.

Use seu próprio CDN

Um CDN existente exige uma configuração deliberada de origem, chave de cache, assinatura e tratamento de erros. Entre em contato para saber das opções de integração atuais para sua carga de trabalho. Não presuma que colocar outro CDN na frente de uma URL assinada preserva a semântica de controle de acesso ou de expiração dessa URL.

Pré-processamento

Você também pode executar o /file/preview em uma Assembly comum e exportar os derivados para o seu próprio armazenamento. Isso troca trabalho no momento do upload por disponibilidade previsível depois. É útil quando a publicação precisa esperar até que as pré-visualizações estejam prontas ou quando um CDN estático deve servir um conjunto fixo de arquivos.

Recursos atuais

Este artigo não mantém mais um roadmap separado. Consulte a referência do Robot EN (English) para ver os formatos de saída e as estratégias atuais, incluindo recursos que eram experimentais quando este post foi publicado pela primeira vez.

Preços

Processamento e entrega são partes distintas da carga de trabalho. Estime-os com base nos seus Templates reais, tamanhos de arquivo, contagens de requisições, comportamento do cache e nos preços atuais. Os limites da conta e as restrições de saída variam conforme o plano. A tarifa de banda ajustável da demonstração é uma suposição, não uma tarifa cotada pela Transloadit.

Chamada de demonstração

Converse com nossa equipe sobre seus tipos de arquivo, o tráfego esperado, os requisitos de privacidade e o armazenamento existente.

Conclusão

Comece com alguns arquivos representativos e um Template de pré-visualização com limites definidos. Confira as imagens retornadas, meça os tamanhos reais das respostas, teste falhas e cache misses e verifique o acesso assinado. Amplie as variantes permitidas quando o fluxo de trabalho e seus custos fizerem sentido para sua aplicação.