beta

Gerar uma miniatura de pré-visualização

🤖/file/preview gera uma miniatura para qualquer arquivo enviado, permitindo pré-visualizar seu conteúdo, de forma semelhante às miniaturas dos gerenciadores de arquivos para desktop.

Exemplo de uso

{
  "steps": {
    "previewed": {
      "format": "png",
      "height": 400,
      "robot": "/file/preview",
      "use": ":original",
      "width": 300
    }
  }
}

Parâmetros

• interpolate

  boolean | Record<string, boolean>

  Controla se as Assembly Variables são interpoladas em campos individuais de instruções.

  Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como false para tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual como false para tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso como true ou defina o caminho desse campo como true para voltar a usar a interpolação.

  Use nomes de campos como path ou caminhos com pontos como ffmpeg.vf para objetos aninhados.

• output_meta

  Record<string, boolean> | boolean | Array<string>

  Permite especificar um conjunto de metadados cujo cálculo é mais custoso para a CPU e que, por isso, vem desativado por padrão para manter o processamento das suas Assemblies rápido.

  Para imagens, você pode adicionar "has_transparency": true neste objeto para extrair se a imagem contém partes transparentes e "dominant_colors": true para extrair um array de códigos de cores hexadecimais da imagem.

  Para imagens, você também pode adicionar "blurhash": true para extrair uma string BlurHash⁠, uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.

  Para imagens, "thumbhash": true em vez disso extrai um ThumbHash⁠ codificado em base64 em meta.thumbhash, junto com meta.has_alpha (se existe um canal alfa, mesmo quando totalmente opaco). Ele descreve pixels orientados por EXIF e usa o primeiro quadro de imagens animadas. A extração é feita em regime de melhor esforço: imagens acima de 40 megapixels, formatos não suportados ou uma decodificação com falha/limitada não geram placeholder. Uma extração bem-sucedida adiciona uma cobrança de metadados equivalente a 20% dos bytes desse arquivo. Nenhuma sobretaxa de ThumbHash se aplica quando desativado ou quando nenhum hash é gerado.

  Defina essa opção no Step que produz a imagem, como /upload/handle para originais enviados por upload ou /image/resize para saídas processadas. Defini-la apenas em /transloadit/store não solicita a extração: o armazenamento preserva os metadados do produtor. O Transloadit Storage persiste um hash gerado com sua versão imutável e o retorna em resultados armazenados e em leituras nativas de ativos. Uploads diretos para o S3 não geram placeholders. Um placeholder contém informações da imagem, portanto proteja-o com os mesmos controles de acesso da imagem completa.

  Para vídeos, você pode adicionar o parâmetro "colorspace": true para extrair o espaço de cores do vídeo de saída.

  Para vídeos, você também pode adicionar "interlaced": true para detectar se o vídeo é entrelaçado. Isso combina a flag barata do ffprobe field_order com uma passagem de amostragem idet limitada sobre os primeiros quadros da origem, expondo interlaced, field_order e um objeto de diagnóstico interlace_detection em file.meta. Isso é computacionalmente caro e cobrado de acordo.

  Para áudio, você pode adicionar "mean_volume": true para obter um único valor que representa o volume médio do arquivo de áudio.

  Você também pode definir isso como false para pular a extração de metadados e acelerar a transcodificação.

• user_meta

  Record<string, any>(padrão: {})

  Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.

  A herança depende do Robot. Os valores são mesclados com o user_meta existente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.

  Nos Steps de processamento, ${file.*} se refere à primeira entrada e ${result.*} ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em :original, os valores são avaliados para cada upload antes da extração de metadados.

  Os Steps subsequentes leem ${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.

• result

  boolean(padrão: false)

  Se os resultados deste Step devem estar presentes no Assembly Status JSON

• queue

  batch

  Definir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila

• force_accept

  boolean(padrão: false)

  Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

  Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

  Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

• ignore_errors

  boolean | Array<meta | execute>(padrão: [])

  Ignorar erros durante fases específicas do processamento.

  Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

  Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

  Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

• use

  string | Array<string> | Array<object> | object

  Especifica quais Steps usar como entrada.

  • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
  • Você pode fornecer vários Steps como entrada usando arrays:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Dica

  Provavelmente é tudo o que você precisa saber sobre use, mas você pode ver os casos de uso avançados.

• format

  avif | gif | jpeg | jpg | png | webp(padrão: "png")

  O formato de saída da imagem de miniatura gerada. Se um clipe de vídeo curto for gerado usando a estratégia clip, o formato dele é definido por clip_format.

• quality

  string | number

  Qualidade de compressão para pré-visualizações estáticas, de 1 a 100. Quando especificada, o redimensionamento final da imagem codifica diretamente no formato solicitado com essa qualidade e remove os metadados incorporados. Omita este parâmetro para manter o comportamento de codificação padrão. Os clipes animados usam suas próprias configurações de codificação. Se optimize estiver ativado, a otimização é executada após essa codificação.

• width

  number(padrão: 300)

  Largura da miniatura, em pixels.

• height

  number(padrão: 200)

  Altura da miniatura, em pixels.

• resize_strategy

  crop | fit | fillcrop | min_fit | pad | stretch(padrão: "pad")

  Para alcançar as dimensões desejadas da miniatura de pré-visualização, o Robot pode precisar redimensionar a imagem gerada. Isso acontece, por exemplo, quando as dimensões de um quadro extraído de um vídeo não correspondem aos parâmetros width e height escolhidos.

  Veja a lista de estratégias de redimensionamento disponíveis para mais detalhes.

• background

  string(padrão: "#ffffffff")

  O código hexadecimal da cor usada para preencher o fundo (usado apenas na estratégia de redimensionamento pad). O formato é #rrggbb[aa] (vermelho, verde, azul, alfa). Use #00000000 para um preenchimento transparente.

• zoom

  boolean(padrão: true)

  Se definido como false, imagens menores não serão esticadas até os valores desejados de width e height. Isso é útil se você quiser manter as dimensões originais da imagem e apenas limitar a saída a um tamanho máximo. Para detalhes sobre o impacto do zoom na estratégia de redimensionamento de sua preferência, consulte a lista de estratégias de redimensionamento disponíveis.

  Observe que este parâmetro afeta apenas estratégias que produzem uma imagem estática. Clipes animados gerados pela estratégia clip não são afetados.

• strategy

  object

  Definição do processo de geração de miniaturas por categoria de arquivo. Cada chave seleciona uma categoria de arquivo, e seu valor é um array ordenado de estratégias:

  Categoria de arquivo	Estratégias disponíveis
  audio	artwork, waveform, icon
  video	artwork, frame, clip, icon
  image	image, embedded-preview, icon
  document	page, icon
  archive	icon
  webpage	render, icon
  unknown	icon

  artwork extrai a arte de capa incorporada, waveform desenha uma forma de onda do áudio, frame extrai um quadro do vídeo e clip cria uma pré-visualização animada do vídeo. Para imagens, image redimensiona o original e embedded-preview extrai uma pré-visualização incorporada, quando disponível. page renderiza a primeira página do documento, render captura uma página web e icon gera um ícone do tipo de arquivo.

  Para cada arquivo, o Robot tentará usar a primeira estratégia para gerar a miniatura. Se esse processo falhar (por exemplo, porque não há arte de capa disponível em um arquivo de vídeo), a próxima estratégia será tentada. Isso se repete até que uma miniatura seja gerada ou a lista se esgote. Selecionar a estratégia icon como última entrada fornece um mecanismo de fallback que garante que sempre haja uma estratégia apropriada disponível.

  Por padrão, o parâmetro usa a seguinte definição:

  {
    "archive": [
      "icon"
    ],
    "audio": [
      "artwork",
      "waveform",
      "icon"
    ],
    "document": [
      "page",
      "icon"
    ],
    "image": [
      "image",
      "embedded-preview",
      "icon"
    ],
    "unknown": [
      "icon"
    ],
    "video": [
      "artwork",
      "frame",
      "icon"
    ],
    "webpage": [
      "render",
      "icon"
    ]
  }
  

• artwork_outer_color

  string

  A cor usada nas partes externas do gradiente da arte de capa.

• artwork_center_color

  string

  A cor usada no centro do gradiente da arte de capa.

• waveform_center_color

  string(padrão: "#000000ff")

  A cor usada no centro do gradiente da forma de onda. O formato é #rrggbb[aa] (vermelho, verde, azul, alfa). Este parâmetro só é usado se a estratégia waveform for aplicada a arquivos de áudio.

• waveform_outer_color

  string(padrão: "#000000ff")

  A cor usada nas partes externas do gradiente da forma de onda. O formato é #rrggbb[aa] (vermelho, verde, azul, alfa). Este parâmetro só é usado se a estratégia waveform for aplicada a arquivos de áudio.

• waveform_height

  string | number(padrão: 100)

  Altura da forma de onda, em pixels. Este parâmetro só é usado se a estratégia waveform for aplicada a arquivos de áudio. Ele pode ser usado para garantir que a forma de onda ocupe apenas uma parte da miniatura de pré-visualização.

• waveform_width

  string | number(padrão: 300)

  Largura da forma de onda, em pixels. Usada somente se a estratégia waveform para arquivos de áudio for aplicada. Pode ser usada para garantir que a forma de onda ocupe apenas uma parte da miniatura de pré-visualização.

• icon_style

  square | with-text(padrão: "with-text")

  O estilo do ícone gerado se a estratégia icon for aplicada. O estilo padrão, with-text, inclui um ícone que mostra o tipo de arquivo e, abaixo dele, uma caixa de texto cujo conteúdo pode ser controlado pelo parâmetro icon_text_content e que, por padrão, mostra a extensão do arquivo (por exemplo, MP4, JPEG). O estilo square inclui apenas uma variante quadrada do ícone que mostra o tipo de arquivo. Abaixo estão exemplos de pré-visualizações geradas para um arquivo de texto com os diferentes estilos:

  
  
  Estilo with-text:
  
  
  Estilo square:
  

• icon_text_color

  string(padrão: "#a2a2a2")

  A cor do texto usado no ícone. O formato é #rrggbb[aa]. Este parâmetro só é usado se a estratégia icon for aplicada.

• icon_text_font

  string(padrão: "Roboto")

  A família de fontes do texto usado no ícone. Este parâmetro só é usado se a estratégia icon for aplicada. Aqui está uma lista de todas as fontes suportadas.

• icon_text_content

  extension | none(padrão: "extension")

  O conteúdo da caixa de texto nos ícones gerados. Este parâmetro só é usado se o parâmetro icon_style estiver definido como with-text. O valor padrão, extension, adiciona a extensão do arquivo (por exemplo, MP4, JPEG) ao ícone. O valor none deixa a caixa de texto vazia, mas reserva espaço para uma sobreposição de texto personalizada, por exemplo, usando HTML na sua aplicação.

• optimize

  boolean(padrão: true)

  Especifica se a imagem de pré-visualização gerada deve ser otimizada para reduzir o tamanho do arquivo, mantendo a qualidade visual. Se esta opção estiver ativada, a imagem será otimizada usando o 🤖/image/optimize.

• optimize_priority

  compression-ratio | conversion-speed(padrão: "conversion-speed")

  Especifica se a velocidade de conversão ou a taxa de compressão tem prioridade ao otimizar imagens. Este parâmetro só é usado se optimize estiver ativado. Consulte a documentação do 🤖/image/optimize para mais detalhes.

• optimize_progressive

  boolean(padrão: false)

  Especifica se as imagens devem ser entrelaçadas, o que faz a imagem resultante carregar progressivamente nos navegadores. Este parâmetro só é usado se optimize estiver ativado. Consulte a documentação do 🤖/image/optimize para mais detalhes.

• clip_format

  apng | avif | gif | webp(padrão: "webp")

  O formato de imagem animada do clipe de vídeo gerado. Este parâmetro só é usado se a estratégia clip for aplicada a arquivos de vídeo.

  Consulte a MDN Web Docs⁠ para informações detalhadas sobre os formatos de imagem e suas características. O GIF tem amplo suporte em softwares, mas suporta apenas uma paleta de cores limitada. O APNG suporta várias profundidades de cor, mas sua compressão sem perdas produz imagens grandes para vídeos. O AVIF oferece compressão eficiente, mas o suporte a animação varia entre navegadores. O WebP oferece um equilíbrio entre arquivos pequenos e qualidade visual e é o formato de clipe padrão.

• clip_offset

  string | number(padrão: 1)

  A posição inicial, em segundos, a partir da qual o clipe é cortado. Este parâmetro só é usado se a estratégia clip for aplicada a arquivos de vídeo. Em vídeos grandes, apenas partes do arquivo podem ser importadas para aumentar a velocidade. Um deslocamento fora dos dados de mídia disponíveis pode impedir a geração do clipe.

• clip_duration

  string | number(padrão: 5)

  A duração, em segundos, do clipe de vídeo gerado. Este parâmetro só é usado se a estratégia clip for aplicada a arquivos de vídeo. Lembre-se de que uma duração de clipe maior também resulta em um arquivo maior, o que pode ser indesejável para pré-visualizações.

• clip_framerate

  string | number(padrão: 5)

  A taxa de quadros do clipe de vídeo gerado. Este parâmetro só é usado se a estratégia clip for aplicada a arquivos de vídeo. Lembre-se de que uma taxa de quadros mais alta parece mais suave, mas também resulta em um arquivo maior, o que pode ser indesejável para pré-visualizações.

• clip_loop

  boolean(padrão: true)

  Especifica se a imagem animada gerada deve se repetir indefinidamente (true) ou parar após reproduzir a animação uma vez (false). Este parâmetro só é usado se a estratégia clip for aplicada a arquivos de vídeo.

Publicações relacionadas no blog