Practical Guide to Image Processing with Sharp

Advanced Integration Scenarios

Responsive Image Service

Building a complete responsive image service that generates the right image for every device and screen.

graph TD
    A[Client Request] -->|URL with Parameters| B[Express Server]
    B -->|Parse Parameters| C{Image in Cache?}
    C -->|Yes| D[Serve Cached Image]
    C -->|No| E[Sharp Processing]
    E -->|Resize| F[Apply Optimizations]
    F -->|Format Conversion| G[Save to Cache]
    G --> D
    D -->|Send Response| H[Client Rendering]
                

const express = require('express');
const sharp = require('sharp');
const path = require('path');
const fs = require('fs');
const crypto = require('crypto');
const NodeCache = require('node-cache');

const app = express();

// In-memory cache for recently accessed images
const memoryCache = new NodeCache({ 
  stdTTL: 3600, // 1 hour default cache
  checkperiod: 600 // Check for expired every 10 minutes
});

// Helper to create deterministic cache keys
function createCacheKey(params) {
  const keyString = Object.entries(params)
    .sort((a, b) => a[0].localeCompare(b[0]))
    .map(([key, value]) => `${key}=${value}`)
    .join('&');
  
  return crypto.createHash('md5').update(keyString).digest('hex');
}

// Main image processing endpoint
app.get('/images/:preset/:filename', async (req, res) => {
  try {
    const { preset, filename } = req.params;
    const {
      w, h, q, fm, fit, 
      blur, sharpen, flip, flop, 
      bg, tint, grayscale, format
    } = req.query;
    
    // Validate filename to prevent path traversal
    if (filename.includes('../') || filename.includes('..\\')) {
      return res.status(400).send('Invalid filename');
    }
    
    // Base image path
    const originalImagePath = path.join(__dirname, 'uploads', filename);
    
    // Check if original exists
    if (!fs.existsSync(originalImagePath)) {
      return res.status(404).send('Image not found');
    }
    
    // Apply preset configurations
    let presetConfig = {};
    switch (preset) {
      case 'thumbnail':
        presetConfig = { width: 200, height: 200, fit: 'cover', quality: 80 };
        break;
      case 'preview':
        presetConfig = { width: 600, quality: 70 };
        break;
      case 'banner':
        presetConfig = { width: 1200, height: 400, fit: 'cover', quality: 85 };
        break;
      case 'avatar':
        presetConfig = { width: 150, height: 150, fit: 'cover', quality: 85 };
        break;
      case 'custom':
        // Use query parameters directly
        break;
      default:
        return res.status(400).send('Invalid preset');
    }
    
    // Merge preset with query parameters (query overrides preset)
    const params = {
      width: parseInt(w) || presetConfig.width,
      height: parseInt(h) || presetConfig.height,
      quality: parseInt(q) || presetConfig.quality || 80,
      format: fm || format || path.extname(filename).substring(1) || 'jpeg',
      fit: fit || presetConfig.fit || 'cover',
      background: bg ? bg.split(',').map(Number) : undefined,
      blur: blur ? parseInt(blur) : undefined,
      sharpen: sharpen === 'true',
      flip: flip === 'true',
      flop: flop === 'true',
      grayscale: grayscale === 'true',
      tint: tint ? tint.split(',').map(Number) : undefined
    };
    
    // Create a deterministic cache key
    const cacheKey = createCacheKey({
      filename,
      ...params
    });
    
    // Check memory cache first (fastest)
    const cachedBuffer = memoryCache.get(cacheKey);
    if (cachedBuffer) {
      res.type(`image/${params.format}`);
      return res.send(cachedBuffer);
    }
    
    // Check disk cache (fallback)
    const cacheDir = path.join(__dirname, 'cache');
    const cachePath = path.join(cacheDir, `${cacheKey}.${params.format}`);
    
    if (fs.existsSync(cachePath)) {
      const cachedImage = fs.readFileSync(cachePath);
      
      // Store in memory cache for future requests
      memoryCache.set(cacheKey, cachedImage);
      
      res.type(`image/${params.format}`);
      return res.send(cachedImage);
    }
    
    // Process the image with Sharp
    let image = sharp(originalImagePath);
    
    // Apply resizing
    if (params.width || params.height) {
      image = image.resize({
        width: params.width,
        height: params.height,
        fit: params.fit ? sharp.fit[params.fit] : sharp.fit.cover,
        background: params.background ? 
          { r: params.background[0], g: params.background[1], b: params.background[2], alpha: 1 } : 
          { r: 255, g: 255, b: 255, alpha: 1 }
      });
    }
    
    // Apply transformations if requested
    if (params.flip) image = image.flip();
    if (params.flop) image = image.flop();
    if (params.grayscale) image = image.grayscale();
    if (params.blur) image = image.blur(params.blur);
    if (params.sharpen) image = image.sharpen();
    if (params.tint) {
      image = image.tint({
        r: params.tint[0],
        g: params.tint[1],
        b: params.tint[2]
      });
    }
    
    // Apply format conversion
    switch (params.format.toLowerCase()) {
      case 'jpeg':
      case 'jpg':
        image = image.jpeg({ quality: params.quality });
        break;
      case 'webp':
        image = image.webp({ quality: params.quality });
        break;
      case 'png':
        image = image.png({ quality: params.quality });
        break;
      case 'avif':
        image = image.avif({ quality: params.quality });
        break;
      default:
        image = image.jpeg({ quality: params.quality });
    }
    
    // Process the image
    const outputBuffer = await image.toBuffer();
    
    // Save to disk cache
    if (!fs.existsSync(cacheDir)) {
      fs.mkdirSync(cacheDir, { recursive: true });
    }
    fs.writeFileSync(cachePath, outputBuffer);
    
    // Save to memory cache
    memoryCache.set(cacheKey, outputBuffer);
    
    // Send processed image
    res.type(`image/${params.format}`);
    res.send(outputBuffer);
    
  } catch (error) {
    console.error('Image processing error:', error);
    res.status(500).send('Error processing image');
  }
});

// Helper endpoint to generate HTML for responsive images
app.get('/responsive-html/:filename', (req, res) => {
  const { filename } = req.params;
  const { sizes = '400,800,1200,1600', alt = '' } = req.query;
  
  const sizesArray = sizes.split(',').map(size => parseInt(size.trim()));
  
  const srcset = sizesArray
    .map(size => `/images/custom/${filename}?w=${size} ${size}w`)
    .join(', ');
  
  const imgTag = `<img
  src="/images/custom/${filename}?w=${sizesArray[0]}"
  srcset="${srcset}"
  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
  alt="${alt}"
  loading="lazy"
>`;
  
  res.json({
    html: imgTag,
    srcset,
    src: `/images/custom/${filename}?w=${sizesArray[0]}`
  });
});

// Cache management endpoints (for admin use)
app.post('/cache/clear', (req, res) => {
  memoryCache.flushAll();
  res.send({ success: true, message: 'Memory cache cleared' });
});

app.post('/cache/clear-disk', (req, res) => {
  const cacheDir = path.join(__dirname, 'cache');
  if (fs.existsSync(cacheDir)) {
    fs.readdirSync(cacheDir).forEach(file => {
      fs.unlinkSync(path.join(cacheDir, file));
    });
  }
  res.send({ success: true, message: 'Disk cache cleared' });
});

// Health check endpoint
app.get('/health', (req, res) => {
  res.send({
    status: 'OK',
    memoryCache: {
      keys: memoryCache.keys().length,
      stats: memoryCache.getStats()
    }
  });
});

// Start server
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Image service running on port ${PORT}`);
});
            

This responsive image service is like a smart photo printer that automatically adjusts each image for the specific device viewing it. Key features include:

• Preset configurations: Common configurations like thumbnails, banners, etc.
• Multi-level caching: Using both memory and disk caching for optimal performance.
• Comprehensive transformations: Supporting a wide range of adjustments through URL parameters.
• Client utilities: Helper endpoint to generate proper HTML for responsive images.

This approach significantly improves web performance by serving the optimal image size for each device while reducing bandwidth usage and server load through aggressive caching.

Video Thumbnail Generator

Using Sharp in conjunction with FFmpeg to extract and process video thumbnails:

const { spawn } = require('child_process');
const sharp = require('sharp');
const fs = require('fs');
const path = require('path');
const { promisify } = require('util');
const stream = require('stream');
const pipeline = promisify(stream.pipeline);

/**
 * Extract a frame from a video and process it with Sharp
 * @param {string} videoPath - Path to video file
 * @param {object} options - Options for extraction and processing
 * @returns {Promise} - Processed thumbnail buffer
 */
async function generateVideoThumbnail(videoPath, options = {}) {
  const {
    timeOffset = '00:00:05', // 5 seconds into video
    width = 640,
    height = 360,
    format = 'webp',
    quality = 80,
    blur = 0,
    sharpen = false,
    grayscale = false,
    tempDir = path.join(__dirname, 'temp')
  } = options;
  
  // Ensure temp directory exists
  if (!fs.existsSync(tempDir)) {
    fs.mkdirSync(tempDir, { recursive: true });
  }
  
  // Create a temp file path for the extracted frame
  const tempFilePath = path.join(tempDir, `${path.basename(videoPath, path.extname(videoPath))}_thumb_${Date.now()}.jpg`);
  
  // Extract frame using FFmpeg
  await new Promise((resolve, reject) => {
    const ffmpeg = spawn('ffmpeg', [
      '-i', videoPath,           // Input file
      '-ss', timeOffset,         // Time offset
      '-frames:v', '1',          // Extract a single frame
      '-q:v', '2',               // High quality
      tempFilePath               // Output file
    ]);
    
    let ffmpegError = '';
    
    ffmpeg.stderr.on('data', (data) => {
      ffmpegError += data.toString();
    });
    
    ffmpeg.on('close', (code) => {
      if (code !== 0) {
        reject(new Error(`FFmpeg exited with code ${code}: ${ffmpegError}`));
      } else {
        resolve();
      }
    });
  });
  
  // Process the extracted frame with Sharp
  let image = sharp(tempFilePath);
  
  // Apply transformations
  image = image.resize({
    width,
    height,
    fit: 'cover',
    position: 'entropy' // Focus on the interesting part
  });
  
  if (blur > 0) image = image.blur(blur);
  if (sharpen) image = image.sharpen();
  if (grayscale) image = image.grayscale();
  
  // Convert to specified format
  switch (format.toLowerCase()) {
    case 'webp':
      image = image.webp({ quality });
      break;
    case 'jpeg':
    case 'jpg':
      image = image.jpeg({ quality });
      break;
    case 'png':
      image = image.png({ quality });
      break;
    case 'avif':
      image = image.avif({ quality });
      break;
    default:
      image = image.webp({ quality });
  }
  
  // Process the image
  const outputBuffer = await image.toBuffer();
  
  // Clean up the temporary file
  fs.unlinkSync(tempFilePath);
  
  return outputBuffer;
}

/**
 * Generate a thumbnail grid from multiple points in a video
 * @param {string} videoPath - Path to video file
 * @param {object} options - Options for grid generation
 * @returns {Promise} - Processed grid buffer
 */
async function generateVideoThumbnailGrid(videoPath, options = {}) {
  const {
    timePoints = ['00:00:10', '00:00:30', '00:01:00', '00:01:30'],
    cols = 2,
    rows = 2,
    thumbnailWidth = 320,
    thumbnailHeight = 180,
    spacing = 10,
    format = 'webp',
    quality = 80,
    tempDir = path.join(__dirname, 'temp')
  } = options;
  
  // Calculate grid dimensions
  const gridWidth = (thumbnailWidth * cols) + (spacing * (cols + 1));
  const gridHeight = (thumbnailHeight * rows) + (spacing * (rows + 1));
  
  // Generate individual thumbnails
  const thumbnails = await Promise.all(
    timePoints.slice(0, cols * rows).map((timeOffset, index) => 
      generateVideoThumbnail(videoPath, {
        timeOffset,
        width: thumbnailWidth,
        height: thumbnailHeight,
        format: 'jpeg', // Use JPEG for intermediates
        quality: 90,     // Higher quality for intermediates
        tempDir
      })
    )
  );
  
  // Create a blank canvas
  const canvas = sharp({
    create: {
      width: gridWidth,
      height: gridHeight,
      channels: 4,
      background: { r: 0, g: 0, b: 0, alpha: 1 }
    }
  });
  
  // Position each thumbnail in the grid
  const composites = thumbnails.map((buffer, index) => {
    const row = Math.floor(index / cols);
    const col = index % cols;
    
    return {
      input: buffer,
      left: spacing + col * (thumbnailWidth + spacing),
      top: spacing + row * (thumbnailHeight + spacing)
    };
  });
  
  // Compose the grid and convert to requested format
  let output = canvas.composite(composites);
  
  // Apply final format conversion
  switch (format.toLowerCase()) {
    case 'webp':
      output = output.webp({ quality });
      break;
    case 'jpeg':
    case 'jpg':
      output = output.jpeg({ quality });
      break;
    case 'png':
      output = output.png({ quality });
      break;
    case 'avif':
      output = output.avif({ quality });
      break;
    default:
      output = output.webp({ quality });
  }
  
  return output.toBuffer();
}

// Express endpoint example
const express = require('express');
const app = express();

app.get('/video-thumbnail/:videoId', async (req, res) => {
  try {
    const { videoId } = req.params;
    const { time, width, height, format } = req.query;
    
    const videoPath = path.join(__dirname, 'videos', `${videoId}.mp4`);
    
    if (!fs.existsSync(videoPath)) {
      return res.status(404).send('Video not found');
    }
    
    const thumbnail = await generateVideoThumbnail(videoPath, {
      timeOffset: time || '00:00:05',
      width: width ? parseInt(width) : 640,
      height: height ? parseInt(height) : 360,
      format: format || 'webp'
    });
    
    res.type(`image/${format || 'webp'}`);
    res.send(thumbnail);
  } catch (error) {
    console.error('Error generating thumbnail:', error);
    res.status(500).send('Error generating thumbnail');
  }
});

app.get('/video-grid/:videoId', async (req, res) => {
  try {
    const { videoId } = req.params;
    const { times, cols, rows, format } = req.query;
    
    const videoPath = path.join(__dirname, 'videos', `${videoId}.mp4`);
    
    if (!fs.existsSync(videoPath)) {
      return res.status(404).send('Video not found');
    }
    
    const timePoints = times ? times.split(',') : undefined;
    
    const grid = await generateVideoThumbnailGrid(videoPath, {
      timePoints,
      cols: cols ? parseInt(cols) : 2,
      rows: rows ? parseInt(rows) : 2,
      format: format || 'webp'
    });
    
    res.type(`image/${format || 'webp'}`);
    res.send(grid);
  } catch (error) {
    console.error('Error generating thumbnail grid:', error);
    res.status(500).send('Error generating thumbnail grid');
  }
});

app.listen(3000, () => {
  console.log('Video thumbnail service running on port 3000');
});
            

This video thumbnail generator demonstrates how Sharp can work with other tools like FFmpeg to create more complex media processing pipelines. The application is similar to how video streaming services generate preview thumbnails for videos, allowing users to see what's happening at different points in the content.