Transloadit

Otimizar o tamanho de arquivos de imagem

🤖/image/optimize reduz o tamanho dos arquivos de imagem com ferramentas de compressão específicas para cada formato.

Robot /image/optimize

Este Robot reduz o tamanho dos arquivos de imagens JPEG, PNG, GIF, WebP e SVG usando ferramentas de compressão específicas para cada formato. Dependendo do formato e das configurações, a otimização pode ser sem perdas ou com perdas.

Este Robot permite que você reduza seus custos de armazenamento e largura de banda, além de melhorar a experiência do usuário e a monetização ao reduzir o tempo de carregamento de páginas web com muitas imagens.

Ele funciona bem em conjunto com 🤖/image/resize para levar todo o potencial das imagens redimensionadas e otimizadas ao seu site ou aplicativo.

Para arquivos JPEG, as configurações padrão de priority: "compression-ratio" e preserve_meta_data: true comparam um resultado sem perdas do jpegtran com um resultado com perdas do MozJPEG cjpeg e selecionam o menor resultado válido. O codificador cjpeg usa sua qualidade padrão de 75, portanto o resultado selecionado pode introduzir artefatos de compressão. Isso não significa que todos os arquivos JPEG sejam recodificados com qualidade 75: um resultado sem perdas pode ser selecionado.

Para otimizar arquivos JPEG sem perda adicional de qualidade, use priority: "conversion-speed", que executa o jpegoptim no modo sem perdas. A própria conversão para JPEG progressivo também pode ocorrer sem perdas. Por exemplo:

{
  "steps": {
    "optimized": {
      "robot": "/image/optimize",
      "use": ":original",
      "priority": "conversion-speed",
      "progressive": true,
      "preserve_meta_data": true
    }
  }
}

Com essas configurações, o jpegoptim pode manter o JPEG original se o resultado progressivo for maior; portanto, a saída progressiva não é garantida. Para fluxos de trabalho sensíveis a artefatos de compressão, como imagens usadas como entrada para gerar vídeos com IA, use as configurações de JPEG sem perdas acima ou mantenha as imagens originais.

Exemplo de uso

Otimize as imagens enviadas por upload:

{
  "steps": {
    "optimized": {
      "robot": "/image/optimize",
      "use": ":original"
    }
  }
}

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"
    }
  ]
}

  • priority

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

    Seleciona as ferramentas de otimização de JPEG. O padrão, "compression-ratio", favorece arquivos menores e pode usar recodificação com perdas na qualidade 75 quando preserve_meta_data: true. Use "conversion-speed" para otimização de JPEG sem perdas com jpegoptim. Este parâmetro não altera as ferramentas usadas para outros formatos de imagem.

  • progressive

    boolean(padrão: false)

    Solicita uma saída progressiva ou entrelaçada das ferramentas selecionadas quando definido como true. Os navegadores podem então exibir uma imagem inicial com poucos detalhes e refiná-la à medida que mais dados chegam. Para arquivos JPEG, a conversão progressiva por si só não exige perda de qualidade; a configuração priority determina se a recodificação com perdas é permitida. Com priority: "conversion-speed", o jpegoptim pode manter o JPEG original se a conversão progressiva aumentar o tamanho do arquivo.

  • preserve_meta_data

    boolean(padrão: true)

    Especifica se os metadados da imagem devem ser preservados durante a otimização. Se não forem preservados, o tamanho do arquivo será reduzido ainda mais. Mas saiba que isso pode remover as informações de direitos autorais de um fotógrafo, o que, por motivos óbvios, pode ser malvisto.

  • fix_breaking_images

    boolean(padrão: true)

    Se definido como true, este parâmetro tenta corrigir imagens que, de outra forma, fariam a ferramenta subjacente gerar um erro e, assim, causar falhas nas suas Assemblies. No entanto, isso às vezes pode resultar em um arquivo maior.

  • lossy

    boolean(padrão: false)

    Quando definido como false (o padrão), apenas otimizadores de PNG sem perdas são usados, desabilitando o pngquant para preservar a fidelidade das cores.

    Quando definido como true, os otimizadores de PNG com e sem perdas competem, e o menor resultado vence. Isso permite o uso do pngquant, um compressor com perdas que reduz PNGs a uma paleta de 256 cores, o que pode causar alterações perceptíveis de cor em imagens com paletas de cores ricas, gradientes sutis ou cores específicas de uma marca.

Demonstrações

Publicações relacionadas no blog