Skip to content

BlurHash for faster contentful paint #72

@Zorlin

Description

@Zorlin

Summary

Add BlurHash placeholders for images to improve First Contentful Paint (FCP) and perceived
loading performance.

Problem

Currently, images load with empty space or skeleton placeholders until the full image
arrives from IPFS/CDN. This delays FCP and makes the site feel slower than it could be.

Solution

Implement BlurHash - a compact representation of an image placeholder
(~20-30 characters) that can be:

  • Stored in release metadata alongside thumbnail/artwork CIDs
  • Inlined directly in the initial HTML render (no network request)
  • Decoded client-side to a blurred preview in <1ms

Benefits

  • Lower FCP - Blur placeholders render instantly as "contentful paint"
  • Better perceived performance - Users see content immediately instead of empty boxes
  • Minimal storage overhead - ~30 bytes per image in existing metadata fields
  • Smooth UX - Blurred preview fades into sharp image when loaded

Implementation

Phase 1: Display Support

  • Add blurhash-decode package to renderer
  • Create BlurHashImage component that shows blur while loading
  • Update contentCard.vue to use BlurHash when available
  • Add smooth fade transition when real image loads

Phase 2: Generation

  • Add blurhash-encode to upload/admin tooling
  • Generate BlurHash when thumbnails are uploaded via release form
  • Store in metadata.thumbnailBlurHash and metadata.artworkBlurHash

Phase 3: Backfill (Optional)

  • Admin tool to batch-generate BlurHashes for existing releases
  • Or: lazy-generate on first CDN access and cache

Metadata Schema Addition

interface ReleaseMetadata {
  // ... existing fields
  thumbnailBlurHash?: string;  // e.g., "LEHV6nWB2yk8pyo0adR*.7kCMdnj"
  artworkBlurHash?: string;
}

References

- https://github.com/woltapp/blurhash
- https://evanw.github.io/thumbhash/ (alternative worth considering)
- Used by: Mastodon, Figma, Unsplash

Metadata

Metadata

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions