Gerar prévias informativas de arquivos

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos ·

Temos orgulho de apresentar nosso novo Robot /file/preview, um recurso da Transloadit desenvolvido para criar automaticamente prévias de formatos de arquivo compatíveis, com um ícone como alternativa. Seja para miniaturas de vídeo, capas de álbuns ou formas de onda de áudio, prévias de páginas de documentos, capturas de tela de sites ou ícones de pacotes de arquivos, este Robot pode fornecer prévias que ajudam as pessoas a identificar arquivos rapidamente. Nós cuidamos da complexidade dos vários tipos de arquivo, enquanto você pode se concentrar em desenvolver seu aplicativo.

O Robot pode ser implementado com poucas linhas de JSON e usa estratégias específicas para cada tipo de arquivo nos bastidores. Ele pode simplificar a geração de prévias e ajudar os usuários a reconhecer arquivos no seu aplicativo.

Um banner de blog com o texto “Meaningful file previews” e uma ilustração de um ícone genérico de arquivo sendo transformado em uma prévia detalhada

O que ele pode fazer?

O 🤖/file/preview foi desenvolvido para criar prévias informativas que ajudam os usuários a identificar rapidamente o conteúdo dos arquivos. Ele oferece suporte a:

Imagens: miniaturas otimizadas para imagens compatíveis, incluindo formatos RAW:
Vídeos: quadros extraídos ou clipes curtos: (ou um ícone alternativo quando não for possível gerar uma prévia do conteúdo: )
Áudio: capa incorporada (ou visualização da forma de onda se a capa não estiver disponível: )
Documentos: prévias da primeira página
Páginas da web: capturas de tela de páginas
Pacotes de arquivos: ícones específicos para cada tipo

A prévia disponível depende do formato, do codec e dos dados de mídia do arquivo. Não é possível gerar uma prévia do conteúdo de todos os arquivos.

Com as estratégias padrão, o Robot usa um ícone específico para o tipo de arquivo como alternativa quando uma prévia mais detalhada não está disponível, como no exemplo de pacote de arquivos acima. Consulte a documentação das estratégias para conhecer as estratégias compatíveis e a ordem das alternativas.

O Robot foi desenvolvido para oferecer padrões práticos e bonitos desde o início, mas seu comportamento pode ser totalmente personalizado. Veja mais sobre isso abaixo.

Por que a Transloadit?

Gerar prévias para uma grande variedade de arquivos é complexo devido à enorme diversidade de formatos de imagem, codecs de vídeo e tipos de documento. Essa complexidade é especialmente marcante para clientes de nichos específicos, como fotógrafos que trabalham com formatos de imagem RAW ou usuários que lidam com vários documentos do Microsoft Office. Como os formatos de imagem e vídeo evoluem constantemente, é necessário investir continuamente para acompanhar e oferecer suporte aos formatos mais recentes. Consulte nossos formatos compatíveis e a referência do Robot para conhecer as conversões disponíveis.

Desenvolver internamente uma solução própria para gerar prévias de arquivos exige recursos consideráveis de engenharia para cobrir até mesmo uma parte dos inúmeros tipos de arquivo. Esses recursos ficam comprometidos a longo prazo, pois a solução interna precisa de manutenção e atualizações para novos formatos. Além disso, processar arquivos enviados por usuários é uma questão delicada que pode tornar sua infraestrutura suscetível a vulnerabilidades nas várias ferramentas de processamento de arquivos. Considere terceirizar a geração de prévias de arquivos para a Transloadit, transferindo esse processamento para fora dos servidores da sua aplicação e permitindo que sua equipe de engenharia se concentre em criar o melhor serviço possível para seus clientes, enquanto a Transloadit cuida da parte complexa das prévias de arquivos.

O 🤖/file/preview pode ser combinado com outros Robots para criar fluxos de trabalho específicos para seu negócio, e esses fluxos podem transformar qualquer parte do seu pipeline de arquivos. A Transloadit pode trabalhar diretamente com os uploads dos seus usuários finais, importar grandes bibliotecas de mídia ou até converter arquivos sob demanda, transmitindo resultados otimizados diretamente para os navegadores com nosso Smart CDN.

Opções de implementação

Há várias maneiras de implementar o 🤖/file/preview, mas a melhor forma de começar é criar um Template que faça referência a esse Robot. Um Template é uma receita em JSON na sua conta que descreve o que a Transloadit deve fazer com seus arquivos. Você pode criar um Template no Template Editor da sua conta ou pelo nosso plugin do provedor Terraform.

Pré-processamento

Com o pré-processamento, você cria e salva as prévias no seu armazenamento. Isso normalmente é feito quando o usuário faz o upload do arquivo pela primeira vez, muito antes de solicitar uma prévia. Esse tipo de pré-processamento pode reduzir a latência da primeira solicitação, em troca de custos maiores de codificação e armazenamento, além de uma integração mais complexa do que a sob demanda.

A Transloadit pode cuidar dos uploads dos originais, gerar prévias e depois salvá-las no seu armazenamento. Para que a Transloadit cuide dos uploads, faça referência ao 🤖/upload/handle no seu Template assim:

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "previewed": {
      "robot": "/file/preview",
      "use": ":original",
      "width": 300,
      "height": 200
    },
    "stored": {
      "use": ["previewed", ":original"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Substitua YOUR_AWS_CREDENTIALS pelo nome da sua Credencial de Template salva. O prefixo exclusivo dá a cada original e prévia seu próprio caminho de objeto. acl: "bucket-default" omite o cabeçalho ACL gerado; configure a política de acesso do seu bucket separadamente. Siga as orientações de configuração e permissões do S3 antes de usar este Template.

Os uploads normalmente vêm de navegadores (por exemplo, via Uppy), mas SDKs de back-end também podem fazer upload de arquivos.

Vamos examinar primeiro o caso de uso no navegador.

Uploads no front-end

A Transloadit poderia cuidar dos uploads que os usuários finais fazem pelo navegador usando o Uppy, nossa ferramenta de upload de arquivos de código aberto para navegadores. Ao aceitar os arquivos, a Transloadit seguirá as Instructions do Template, gerando as prévias e armazenando-as no seu bucket S3. Os originais também serão salvos, pois no Step "stored" tínhamos: "use": ["previewed", ":original"].

Antes de executar o código do navegador, implemente um manipulador protegido para POST /api/transloadit/assembly-options na sua própria aplicação. Ele deve autenticar seu usuário, autorizar o upload, verificar a origem da solicitação ou o token CSRF da sua aplicação e aplicar seus limites de upload. Vincule-o ao ID fixo do Template de upload acima; não assine Templates ou Instructions arbitrários fornecidos pelo navegador. Ative a Signature Authentication para seu Workspace e mantenha allow_steps_override: false no Template salvo.

Nesse back-end, use o exemplo de geração de assinatura para retornar { params, signature } com um auth.expires de curta duração. Retorne a string serializada params sem alterações e mantenha o Auth Secret no servidor. Esse endpoint pertence à sua aplicação; ele não é um endpoint da API da Transloadit.

Instale @uppy/core, @uppy/dashboard e @uppy/transloadit com Yarn no seu projeto para navegador e adicione um elemento com id="uppy-dashboard" à página. Inclua este código por meio do seu bundler:

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'

const uppy = new Uppy()
  .use(Dashboard, {
    inline: true,
    // This is the element where the dashboard will be rendered:
    target: '#uppy-dashboard',
  })
  .use(Transloadit, {
    waitForEncoding: true,
    assemblyOptions: async () => {
      const response = await fetch('/api/transloadit/assembly-options', {
        method: 'POST',
        credentials: 'same-origin',
      })
      if (!response.ok) {
        throw new Error(`Could not authorize the upload (HTTP ${response.status})`)
      }
      return response.json()
    },
  })

uppy.on('transloadit:complete', (assembly) => {
  const preview = assembly.results?.previewed?.[0]
  if (preview) {
    console.log('Preview object URL:', preview.ssl_url)
  } else {
    console.log('No previews were generated.')
  }
})

A exportação para o S3 atualiza os resultados no Step que os produziu, previewed. Um ssl_url retornado não concede acesso a um objeto privado do S3 nem garante uma URL de download permanente. Autorize os downloads na sua aplicação, por exemplo, com URLs de download do S3 de curta duração geradas pelo seu back-end.

O Uppy foi criado pela Transloadit. Ele reúne mais recursos do que cabe neste artigo, então consulte o site do Uppy para saber mais.

Também há SDKs para Android e iOS, caso você queira integrar com aplicativos móveis nativos.

Uploads no back-end

Back-ends também podem fazer upload para a Transloadit. Veja como seria em Node.js:

Instale @transloadit/node com yarn add @transloadit/node. Salve o exemplo como upload.mjs e execute-o com node upload.mjs. Primeiro, defina TRANSLOADIT_KEY, TRANSLOADIT_SECRET e TRANSLOADIT_TEMPLATE_ID no ambiente do servidor, usando o ID do Template de upload acima, e substitua ./file.mp4 por um arquivo local com permissão de leitura. Mantenha o Auth Secret fora do código do navegador e do controle de versão.

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  files: { file: './file.mp4' },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

Há SDKs para muitas outras linguagens de back-end que facilitam a integração, mas você também pode interagir diretamente com nossa REST API.

Importações

Em vez de deixar a Transloadit cuidar dos uploads, a Transloadit pode importar arquivos de fontes na nuvem como o S3, gerar prévias e exportá-las de volta para o S3 ou para outros provedores de armazenamento. Isso pode ser feito para um único arquivo ou para buckets inteiros contendo muitos terabytes de arquivos.

Apenas como exemplo, também adicionaremos o 🤖/file/filter ao Template abaixo para mostrar como você pode filtrar por tipo de arquivo e, neste caso, gerar prévias apenas de arquivos de áudio. Isso pode ser adaptado para filtrar por outras propriedades, como tamanho do arquivo, taxa de bits, tipo de mídia etc. Este é o Template completo que você criaria no Template Editor da sua conta:

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "my_source_folder/"
    },
    "audio_filtered": {
      "use": "imported",
      "robot": "/file/filter",
      "accepts": [["${file.type}", "==", "audio"]],
      "error_on_decline": false
    },
    "previewed": {
      "robot": "/file/preview",
      "use": "audio_filtered",
      "width": 300,
      "height": 200,
      "format": "png"
    },
    "stored": {
      "use": "previewed",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Você pode fazer referência a este Template e executá-lo com qualquer um dos nossos SDKs. Para Node.js, use o mesmo pacote e a mesma configuração de ambiente do servidor descritos acima, mas defina TRANSLOADIT_TEMPLATE_ID com o ID deste Template de importação. Salve o exemplo a seguir como import.mjs e execute node import.mjs. Não é necessário fazer upload de um arquivo local. Se o filtro não encontrar nenhum arquivo de áudio, não haverá prévias para ler:

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

Sob demanda

Por fim, você também pode gerar prévias sob demanda usando nosso Smart CDN. Isso significa que a Transloadit não faz nenhum trabalho até que um usuário solicite a prévia. A Transloadit então importa o arquivo original do seu armazenamento, gera a prévia e a entrega diretamente ao usuário final. Armazenamos o resultado em cache próximo ao usuário final.

Isso oferece os seguintes benefícios:

A prévia só é criada quando os usuários a solicitam, economizando custos com arquivos de mídia que não são efetivamente solicitados.
Um resultado em cache pode ser entregue sem uma nova cobrança de codificação enquanto permanecer disponível e apto a ser armazenado em cache. A entrega a partir do cache ainda gera cobranças de largura de banda. Um resultado expirado ou removido do cache pode precisar de novo processamento, com novas cobranças de processamento.
A integração é mais simples, pois você não precisa gerenciar as prévias por conta própria (salvá-las, armazenar referências etc.). Basta criar um Template e adicionar uma URL do Smart CDN para o recurso à sua página da web ou ao seu aplicativo.
Você pode adaptar a prévia ao dispositivo, à resolução, à largura de banda etc. do usuário final. Assim, você não desperdiça bytes em uma entrega que não melhora a experiência do usuário. Isso economiza largura de banda, bateria e tempo.

Para saber mais sobre prévias sob demanda, URLs assinadas e medições de entrega, consulte nosso artigo: Prévias de mídia sob demanda com o Smart CDN.

Este é um exemplo de Template que instrui a Transloadit a importar um arquivo de mídia do S3, gerar uma prévia e entregá-la usando nosso Smart CDN:

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "${fields.input}"
    },
    "previewed": {
      "use": "imported",
      "robot": "/file/preview",
      "width": "${fields.w}"
    },
    "served": {
      "use": "previewed",
      "robot": "/file/serve"
    }
  }
}

A estrutura da URL para este Template é:

https://my-workspace.tlcdn.com/my-template/file.mp4?w=300

Use o nome da sua Credencial de Template salva em YOUR_AWS_CREDENTIALS e coloque o arquivo de origem em file.mp4 nesse bucket S3. Aqui, my-template é o nome do Template, ${fields.input} recebe file.mp4 e ${fields.w} recebe 300 da URL. Substitua os espaços reservados de Workspace e Template pelos seus próprios valores. Isso mostra a estrutura da URL; para uma entrega protegida, autorize o arquivo e as dimensões solicitados no seu back-end e gere uma URL assinada com prazo de expiração antes de enviá-la ao navegador. Siga o guia de assinatura do Smart CDN. Defina require_signature_auth como 1 usando a API de Templates; essa é uma configuração do Template fora do JSON das Instructions acima. Não exponha um endpoint de assinatura de uso geral que aceite caminhos ou transformações arbitrários.

Personalize a prévia

Embora o 🤖/file/preview ofereça padrões práticos e bonitos desde o início, você pode controlar sua saída usando vários parâmetros para combinar com a aparência do seu aplicativo:

format: formato de saída da miniatura
width e height: dimensões em pixels
resize_strategy: como ajustar a prévia às dimensões
background: cor de fundo para o preenchimento em formato hexadecimal (#rrggbb[aa])
strategy: personalizar a geração de prévias por tipo de arquivo (áudio, vídeo, imagem etc.)

Para formas de onda de áudio:

waveform_center_color e waveform_outer_color: cores do gradiente em formato hexadecimal
waveform_height e waveform_width: dimensões da forma de onda

Para ícones:

icon_style: aparência do ícone alternativo
icon_text_color: cor do texto em formato hexadecimal
icon_text_font: família da fonte
icon_text_content: texto exibido no ícone

Para clipes de vídeo:

clip_format: formato da animação
clip_offset: posição inicial em segundos
clip_duration: duração em segundos
clip_framerate: quadros por segundo
clip_loop: se a animação deve se repetir

Para otimização de imagens:

optimize: ativar a otimização do tamanho do arquivo
optimize_priority: equilíbrio entre a velocidade de conversão e a taxa de compressão
optimize_progressive: ativar o carregamento progressivo

Para conhecer os valores aceitos, os padrões, os limites e o comportamento específico de cada estratégia, consulte a documentação do 🤖/file/preview.

Considerações de segurança

Para proteger seus arquivos e controlar o acesso à funcionalidade de prévias, recomendamos implementar a assinatura de solicitações nas integrações de front-end (Uppy, Smart CDN, dispositivos móveis). Especificamente para a entrega pelo Smart CDN, autorize o acesso ao arquivo e à transformação solicitados antes de assinar uma URL do Smart CDN. A assinatura protege a URL; qualquer pessoa que a obtiver poderá usá-la enquanto ela permanecer válida.

Para informações detalhadas, incluindo exemplos em várias linguagens de programação, consulte nossa documentação sobre URLs assinadas do Smart CDN.

Lembre-se de:

Sempre gerar URLs assinadas no seu back-end,
Nunca expor seu Auth Secret no código do lado do cliente e
Implementar um prazo de expiração para suas URLs assinadas.

Prazos de expiração mais curtos reduzem a janela de reutilização da URL. Um prazo de expiração maior permite que uma URL continue utilizável por mais tempo; isso não garante retenção em cache, acertos de cache ou custos menores de processamento. A entrega a partir do cache continua sujeita a cobrança, e resultados expirados ou removidos do cache podem exigir novo processamento.

Casos de uso avançados

Embora este artigo cubra as formas básicas de usar o 🤖/file/preview, há muitas maneiras de integrá-lo a pipelines mais complexos:

Geração automatizada em lote: agende a geração de prévias para buckets de armazenamento inteiros para manter prévias atualizadas em escala.
Integrações orientadas a eventos: acione o processamento de prévias automaticamente sempre que novos arquivos chegarem, garantindo que as prévias estejam sempre prontas quando necessárias.
Componha fluxos de trabalho híbridos: combine o 🤖/file/preview com outros Robots da Transloadit, como o 🤖/image/facedetect ou o 🤖/video/encode, para criar transformações com vários Steps em um único fluxo de trabalho.
Mais opções de armazenamento: além do AWS S3, você pode integrar facilmente com todos os principais provedores de armazenamento na nuvem, assim como com sua própria infraestrutura personalizada (armazenamento compatível com S3 ou SFTP).
Cache personalizável: combine o 🤖/file/preview com configurações do Smart CDN que atendam aos seus requisitos de desempenho e confiabilidade.
Use sua própria CDN: em implementações de alto volume, os clientes podem aproveitar contratos e infraestrutura existentes combinando nossa plataforma de codificação com sua própria CDN.

Preços e disponibilidade

Consulte nossa página de preços para conhecer os planos, as tarifas e as restrições atuais dos planos, além da documentação do Robot sobre preços.

Leituras adicionais

Você pode se interessar por nossas

Demonstrações (English) para ter uma ideia de outros recursos e de como você pode combiná-los.
Informações sobre o Smart CDN para saber mais sobre como entregar arquivos, prévias e outras conversões sob demanda.
Prévias de mídia sob demanda com o Smart CDN para uma demonstração, medições de entrega e um exemplo de assinatura no lado do servidor.

Próximos passos

Para começar, siga estas etapas:

Cadastre-se para ter uma conta na Transloadit.
Crie seu primeiro Template com o 🤖/file/preview.
Teste diferentes opções de prévia e integração usando nosso Template Editor.
Integre as prévias à sua aplicação.

Precisa de ajuda para começar? Criamos Robots, mas somos pessoas de verdade que gostam de ajudar! Fique à vontade para falar conosco em support@transloadit.com.

No mais, bom transloading 🙂