Managing Media

Managing Media & Files

Purpose

This skill provides systematic patterns for implementing media and file management components across all formats (images, videos, audio, documents). It covers upload workflows, display patterns, player controls, optimization strategies, and accessibility requirements to ensure performant, accessible, and user-friendly media experiences.

When to Use

Activate this skill when:

• Implementing file upload (single, multiple, drag-and-drop)
• Building image galleries, carousels, or lightboxes
• Creating video or audio players
• Displaying PDF or document viewers
• Optimizing media for performance (responsive images, lazy loading)
• Handling large file uploads (chunked, resumable)
• Integrating cloud storage (S3, Cloudinary)
• Implementing media accessibility (alt text, captions, transcripts)
• Designing empty states for missing media

Quick Decision Framework

Select implementation based on media type and requirements:

Images                  → Gallery pattern + lazy loading + responsive srcset
Videos                  → Player with controls + captions + adaptive streaming
Audio                   → Player with waveform + playlist support
Documents (PDF)         → Viewer with navigation + search + download
File Upload (<10MB)     → Basic drag-drop with preview
File Upload (>10MB)     → Chunked upload with progress + resume
Multiple Files          → Queue management + parallel uploads

For detailed selection criteria, reference references/implementation-guide.md.

File Upload Patterns

Basic Upload (<10MB)

For small files with simple requirements:

• Drag-and-drop zone with visual feedback
• Click to browse fallback
• File type and size validation
• Preview thumbnails for images
• Progress indicator
• Reference references/upload-patterns.md

Example: examples/basic-upload.tsx

Advanced Upload (>10MB)

For large files requiring reliability:

• Chunked uploads (resume on failure)
• Parallel uploads for multiple files
• Upload queue management
• Cancel and retry controls
• Client-side compression
• Reference references/advanced-upload.md

Example: examples/chunked-upload.tsx

Image-Specific Upload

For image files with editing requirements:

• Crop and rotate tools
• Client-side resize before upload
• Format conversion (PNG → WebP)
• Alt text input field (accessibility)
• Reference references/image-upload.md

Example: examples/image-upload-crop.tsx

Image Display Components

Image Gallery

For collections of images:

• Grid or masonry layout
• Lazy loading (native or custom)
• Lightbox on click
• Zoom and pan controls
• Keyboard navigation (arrow keys)
• Responsive design
• Reference references/gallery-patterns.md

Example: examples/image-gallery.tsx

Carousel/Slider

For sequential image display:

• Auto-play (optional, pausable for accessibility)
• Dot or thumbnail navigation
• Touch/swipe support
• ARIA roles for accessibility
• Infinite loop option
• Reference references/carousel-patterns.md

Example: examples/carousel.tsx

Image Optimization

Essential optimization strategies:

• Responsive images using srcset and sizes
• Modern formats (WebP with JPG fallback)
• Progressive JPEGs
• Blur-up placeholders
• CDN integration
• Reference references/image-optimization.md

Video Components

Video Player

For custom video playback:

• Custom controls or native
• Play/pause, volume, fullscreen
• Captions/subtitles (VTT format)
• Playback speed control
• Picture-in-picture support
• Keyboard shortcuts
• Reference references/video-player.md

Example: examples/video-player.tsx

Video Optimization

Performance strategies for video:

• Adaptive streaming (HLS, DASH)
• Thumbnail preview on hover
• Lazy loading off-screen videos
• Preload strategies (metadata, auto, none)
• Multiple quality levels
• Reference references/video-optimization.md

Audio Components

Audio Player

For audio playback:

• Play/pause, seek, volume controls
• Waveform visualization (optional)
• Playlist support
• Download option
• Playback speed control
• Visual indicators for accessibility
• Reference references/audio-player.md

Example: examples/audio-player.tsx

Document Viewers

PDF Viewer

For PDF document display:

• Page navigation (prev/next, jump to page)
• Zoom in/out controls
• Text search within document
• Download and print options
• Thumbnail sidebar
• Reference references/pdf-viewer.md

Example: examples/pdf-viewer.tsx

Office Document Preview

For DOCX, XLSX, PPTX files:

• Read-only preview or editable
• Cloud-based rendering (Google Docs Viewer, Office Online)
• Local rendering (limited support)
• Download option
• Reference references/office-viewer.md

Performance Optimization

File Size Guidelines

Validate client-side before upload:

• Images: <5MB recommended
• Videos: <100MB for web, larger for cloud
• Audio: <10MB
• Documents: <25MB
• Provide clear error messages
• Suggest compression tools

Image Optimization Checklist

# Generate optimized image set
python scripts/optimize_images.py --input image.jpg --formats webp,jpg,avif

Strategies:

• Compress before upload (client or server)
• Generate multiple sizes (thumbnails, medium, large)
• Use responsive srcset for device targeting
• Convert to modern formats (WebP, AVIF)
• Serve via CDN with edge caching

Reference references/performance-optimization.md for complete guide.

Video Optimization Checklist

Strategies:

• Transcode to multiple qualities (360p, 720p, 1080p)
• Implement adaptive bitrate streaming
• Use CDN with edge caching
• Lazy load videos outside viewport
• Provide poster images

Accessibility Requirements

Images

Essential patterns:

• Alt text required for meaningful images
• Empty alt (alt="") for decorative images
• Use <figure> and <figcaption> for context
• Sufficient color contrast for overlays
• Reference references/accessibility-images.md

Videos

Essential patterns:

• Captions/subtitles for all speech
• Transcript link provided
• Keyboard controls (space, arrows, M for mute)
• Pause auto-play (WCAG requirement)
• Audio description track (if applicable)
• Reference references/accessibility-video.md

Audio

Essential patterns:

• Transcripts available
• Visual indicators (playing, paused, volume)
• Keyboard controls
• ARIA labels for controls
• Reference references/accessibility-audio.md

To validate accessibility:

node scripts/validate_media_accessibility.js

For complete requirements, reference references/accessibility-patterns.md.

Library Recommendations

Image Gallery: react-image-gallery

Best for feature-complete galleries:

• Mobile swipe support
• Fullscreen mode
• Thumbnail navigation
• Lazy loading built-in
• Responsive out of the box

npm install react-image-gallery

See examples/gallery-react-image.tsx for implementation. Reference /xiaolin/react-image-gallery for documentation.

Alternative: LightGallery (more features, larger bundle)

Video: video.js

Best for custom video players:

• Plugin ecosystem
• HLS and DASH support
• Accessible controls
• Theming support
• Extensive documentation

npm install video.js

See examples/video-js-player.tsx for implementation.

Audio: wavesurfer.js

Best for waveform visualization:

• Beautiful waveform display
• Timeline interactions
• Plugin support
• Responsive
• Lightweight

npm install wavesurfer.js

See examples/audio-waveform.tsx for implementation.

PDF: react-pdf

Best for PDF rendering in React:

• Page-by-page rendering
• Text selection support
• Annotations (premium)
• Worker-based for performance

npm install react-pdf

See examples/pdf-react.tsx for implementation.

For detailed comparison, reference references/library-comparison.md.

Design Token Integration

All media components use the design-tokens skill for theming:

• Color tokens for backgrounds, overlays, controls
• Spacing tokens for padding and gaps
• Border tokens for thumbnails and containers
• Shadow tokens for elevation
• Motion tokens for animations

Supports light, dark, high-contrast, and custom themes. Reference the design-tokens skill for theme switching.

Example token usage:

.upload-zone {
  border: var(--upload-zone-border);
  background: var(--upload-zone-bg);
  padding: var(--upload-zone-padding);
  border-radius: var(--upload-zone-border-radius);
}

.image-gallery {
  gap: var(--gallery-gap);
}

.video-player {
  background: var(--video-player-bg);
  border-radius: var(--video-border-radius);
}

Responsive Strategies

Image Galleries

Four responsive approaches: 1. Grid layout - CSS Grid with auto-fit columns 2. Masonry layout - Pinterest-style with variable heights 3. Carousel - Single image on mobile, multiple on desktop 4. Stack - Vertical list on mobile, grid on desktop

See examples/responsive-gallery.tsx for implementations.

Video Players

Responsive considerations:

• 16:9 aspect ratio container
• Full-width on mobile
• Constrained width on desktop
• Picture-in-picture for multitasking
• Touch-friendly controls (larger hit areas)

Reference references/responsive-media.md for patterns.

Cloud Storage Integration

Client-Side Direct Upload

For AWS S3, Cloudinary, etc.: 1. Request signed URL from backend 2. Upload directly to cloud storage 3. Notify backend of completion 4. Display uploaded media

Benefits:

• Reduces server load
• Faster uploads (direct to CDN)
• No file size limits on your server

See examples/s3-direct-upload.tsx for implementation. Reference references/cloud-storage.md for setup.

Testing Tools

Generate mock media:

# Generate test images
python scripts/generate_mock_images.py --count 50 --sizes thumb,medium,large

# Generate test video metadata
python scripts/generate_video_metadata.py --duration 300

Validate media accessibility:

node scripts/validate_media_accessibility.js

Analyze performance:

node scripts/analyze_media_performance.js --files images/*.jpg

Working Examples

Start with the example matching the requirements:

basic-upload.tsx              # Simple drag-drop upload
chunked-upload.tsx            # Large file upload with resume
image-upload-crop.tsx         # Image upload with cropping
image-gallery.tsx             # Grid gallery with lightbox
carousel.tsx                  # Image carousel/slider
video-player.tsx              # Custom video player
audio-player.tsx              # Audio player with controls
audio-waveform.tsx            # Audio with waveform visualization
pdf-viewer.tsx                # PDF document viewer
s3-direct-upload.tsx          # Direct upload to S3
responsive-gallery.tsx        # Responsive image gallery patterns

Resources

Scripts (Token-Free Execution)

• scripts/optimize_images.py - Batch image optimization
• scripts/generate_mock_images.py - Test image generation
• scripts/validate_media_accessibility.js - Accessibility validation
• scripts/analyze_media_performance.js - Performance analysis

References (Detailed Documentation)

• references/upload-patterns.md - File upload implementations
• references/gallery-patterns.md - Image gallery designs
• references/video-player.md - Video player features
• references/audio-player.md - Audio player patterns
• references/pdf-viewer.md - Document viewer setup
• references/accessibility-patterns.md - Media accessibility
• references/performance-optimization.md - Optimization strategies
• references/cloud-storage.md - Cloud integration guides
• references/library-comparison.md - Library analysis

Examples (Implementation Code)

• See examples/ directory for working implementations

Assets (Templates and Configs)

• assets/upload-config.json - Upload constraints and settings
• assets/media-templates/ - Placeholder images and icons

Cross-Skill Integration

This skill works with other component skills:

• Forms: File input fields, validation, submission
• Feedback: Upload progress, success/error messages
• AI Chat: Image attachments, file sharing
• Dashboards: Media widgets, thumbnails
• Design Tokens: All visual styling via token system

Next Steps

1. Identify the media type (images, video, audio, documents) 2. Determine upload requirements (size, quantity, editing) 3. Choose display pattern (gallery, carousel, player, viewer) 4. Select library or implement custom solution 5. Implement accessibility requirements 6. Apply optimization strategies 7. Test performance and responsive behavior 8. Integrate with cloud storage (optional)

Media & File Management Skill

This skill implements comprehensive media and file management components following Anthropic's Skills best practices.

Skill Overview

Name: managing-media

Purpose: Provides systematic patterns for implementing media and file management components across all formats (images, videos, audio, documents).

Coverage:

• File upload (drag-drop, multi-file, resumable)
• Image galleries (lightbox, carousel, masonry)
• Video players (custom controls, captions, streaming)
• Audio players (waveform, playlists)
• Document viewers (PDF, Office)
• Optimization strategies (compression, responsive images, CDN)

Structure

media/
├── SKILL.md                    # Main skill file (474 lines)
├── README.md                   # This file
├── init.md                     # Master plan (preserved from planning phase)
├── references/                 # Detailed documentation
│   ├── implementation-guide.md
│   ├── upload-patterns.md
│   ├── gallery-patterns.md
│   ├── video-player.md
│   ├── library-comparison.md
│   ├── accessibility-patterns.md
│   └── performance-optimization.md
├── examples/                   # Working code examples
│   ├── basic-upload.tsx
│   ├── image-gallery.tsx
│   └── video-player.tsx
├── scripts/                    # Utility scripts (token-free execution)
│   ├── optimize_images.py
│   └── validate_media_accessibility.js
└── assets/                     # Configuration and templates
    ├── upload-config.json
    └── media-templates/

Usage

This skill activates when:

• Implementing file upload features
• Building image galleries or carousels
• Creating video or audio players
• Displaying PDF or document viewers
• Optimizing media for performance
• Handling large file uploads
• Implementing media accessibility

Progressive Disclosure

The skill follows Anthropic's progressive disclosure pattern: 1. SKILL.md - Core guidance and quick decision frameworks (474 lines) 2. references/ - Detailed documentation loaded as needed 3. scripts/ - Executable utilities (no context cost) 4. examples/ - Working implementations

Key Features

Decision Frameworks

• Media type selection guide
• Upload strategy by file size
• Performance optimization thresholds
• Accessibility requirements

Library Recommendations

• Images: react-image-gallery, LightGallery
• Video: video.js, Plyr
• Audio: wavesurfer.js, Howler.js
• PDF: react-pdf
• Upload: react-dropzone, Uppy

Optimization Strategies

• Responsive images (srcset, sizes)
• Modern formats (WebP, AVIF)
• Lazy loading
• Adaptive streaming
• CDN integration

Accessibility Patterns

• WCAG 2.1 compliance
• Alt text guidelines
• Caption/subtitle requirements
• Keyboard navigation
• ARIA patterns

Integration

This skill integrates with:

• design-tokens - Visual styling via token system
• forms - File input fields and validation
• feedback - Upload progress and error messages
• ai-chat - Image attachments and file sharing
• dashboards - Media widgets and thumbnails

Line Count

SKILL.md: 474 lines (under 500-line requirement ✓)

Validation

The skill has been validated against Anthropic's best practices checklist:

Core Quality ✓

• Description includes WHAT and WHEN
• SKILL.md under 500 lines
• No time-sensitive information
• Consistent terminology
• Concrete examples
• One-level deep references

Naming and Structure ✓

• Gerund form name: managing-media
• Lowercase, hyphens only
• Description under 1024 chars
• Forward slashes in paths
• Descriptive file names

Progressive Disclosure ✓

• Main file concise
• References for details
• Scripts for deterministic operations
• Clear execution intent

Development Status

• [x] SKILL.md created (474 lines)
• [x] Directory structure created
• [x] Core reference files created
• [x] Example implementations created
• [x] Utility scripts created
• [x] Configuration assets created
• [ ] Full example implementations (to be expanded)
• [ ] Additional reference documentation (to be expanded)

Next Steps

To expand this skill: 1. Add more working examples (chunked upload, carousel, etc.) 2. Expand reference documentation 3. Add more utility scripts 4. Create evaluation scenarios 5. Test across models (Haiku, Sonnet, Opus)

License

Part of the ai-design-components project. See root LICENSE file.

Audio Accessibility

Transcripts, visual indicators, and keyboard controls for accessible audio content.

Transcript (Required)

<div>
  <audio controls>
    <source src="podcast.mp3" />
  </audio>

  <details className="mt-4">
    <summary>Transcript</summary>
    <div className="prose">
      <p><strong>Host:</strong> Welcome to our podcast...</p>
      <p><strong>Guest:</strong> Thank you for having me...</p>
    </div>
  </details>
</div>

Visual Play Indicator

function AudioWithVisual({ src }: { src: string }) {
  const [isPlaying, setIsPlaying] = useState(false);

  return (
    <div className="flex items-center gap-4">
      <audio
        src={src}
        onPlay={() => setIsPlaying(true)}
        onPause={() => setIsPlaying(false)}
      />

      {isPlaying && (
        <div className="flex gap-1">
          <div className="w-1 h-4 bg-blue-500 animate-pulse" />
          <div className="w-1 h-6 bg-blue-500 animate-pulse animation-delay-75" />
          <div className="w-1 h-4 bg-blue-500 animate-pulse animation-delay-150" />
        </div>
      )}
    </div>
  );
}

Keyboard Controls

useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === ' ') {
      e.preventDefault();
      audioRef.current?.paused ? audioRef.current?.play() : audioRef.current?.pause();
    }
    if (e.key === 'ArrowLeft') {
      audioRef.current!.currentTime -= 5;  // Skip back 5s
    }
    if (e.key === 'ArrowRight') {
      audioRef.current!.currentTime += 5;  // Skip forward 5s
    }
  };

  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, []);

Best Practices

1. Transcript required - Text alternative (WCAG Level A) 2. Visual feedback - For deaf/hard-of-hearing users 3. Keyboard controls - Space, arrows 4. No autoplay - User-initiated only 5. Volume control - Accessible to keyboard

Resources

• WCAG Audio: https://www.w3.org/WAI/media/av/

Image Accessibility

WCAG 2.1 compliance for images including alt text, captions, and decorative images.

Alt Text

// Informative images
<img src="chart.png" alt="Bar chart showing 30% revenue increase in Q4 2025" />

// Functional images (buttons, links)
<a href="/search">
  <img src="search-icon.svg" alt="Search" />
</a>

// Decorative images (no information)
<img src="border.png" alt="" role="presentation" />

Complex Images

<figure>
  <img
    src="data-visualization.png"
    alt="Sales data visualization"
    aria-describedby="chart-description"
  />
  <figcaption id="chart-description">
    Sales increased 30% from Q3 to Q4 2025. Electronics: $120K, Clothing: $85K, Home: $62K.
  </figcaption>
</figure>

SVG Accessibility

<svg role="img" aria-labelledby="chart-title chart-desc">
  <title id="chart-title">Revenue Chart</title>
  <desc id="chart-desc">Revenue grew from $50K to $80K over 6 months</desc>
  {/* SVG content */}
</svg>

Best Practices

1. Descriptive alt text - Convey information, not "image of..." 2. Empty alt for decorative - alt="" to hide from screen readers 3. Long descriptions - Use aria-describedby for complex images 4. Avoid text in images - Use real text with CSS 5. Color contrast - Text overlays must have 4.5:1 contrast

Resources

• WCAG Images: https://www.w3.org/WAI/tutorials/images/

Media Accessibility Patterns

Table of Contents

• WCAG 2.1 Requirements for Media
• Level A (Minimum)
• Level AA (Recommended)
• Level AAA (Enhanced)
• Images
• Alt Text Guidelines
• Color Contrast
• Video
• Captions
• Audio Descriptions
• Transcripts
• Keyboard Controls
• ARIA Attributes
• Audio
• Transcripts Required
• Visual Indicators
• ARIA Labels
• Controls
• File Upload
• Accessibility Requirements
• Image Galleries
• Keyboard Navigation
• Focus Management
• Screen Reader Support
• ARIA Carousel
• PDF Viewers
• Accessible PDFs
• Viewer Controls
• Screen Reader Announcements
• Testing Checklist
• Images
• Video
• Audio
• Upload
• Galleries
• Validation Tools
• Automated Testing
• Manual Testing
• Resources
• See Also

WCAG 2.1 Requirements for Media

Level A (Minimum)

• Audio-only and video-only alternatives
• Captions for prerecorded video
• Audio descriptions or alternative
• Keyboard accessible controls

Level AA (Recommended)

• Captions for live video
• Audio descriptions for prerecorded video
• Contrast ratios for overlays

Level AAA (Enhanced)

• Sign language interpretation
• Extended audio descriptions
• Media alternative for text

Images

Alt Text Guidelines

Informative Images:

<img src="chart.png" alt="Bar chart showing 40% increase in sales in Q4 2024">

Decorative Images:

<img src="divider.png" alt="">

Functional Images:

<img src="search-icon.png" alt="Search">

Complex Images:

<figure>
  <img src="complex-chart.png" alt="Sales trends by region">
  <figcaption>
    Detailed description: The chart shows sales increasing in the North region...
  </figcaption>
</figure>

Color Contrast

Overlays and text on images:

• Normal text: 4.5:1 minimum
• Large text (18pt+): 3:1 minimum
• Use semi-transparent backgrounds for text overlays

Video

Captions

Requirements:

• Synchronized with audio
• Identify speakers
• Include sound effects
• Readable font size
• High contrast

VTT Format:

WEBVTT

00:00:01.000 --> 00:00:04.000
[Music playing]

00:00:04.000 --> 00:00:08.000
<v John>Hello everyone, welcome to the tutorial.</v>

Audio Descriptions

Describe visual content during natural pauses:

WEBVTT

00:00:10.000 --> 00:00:14.000
[Audio description: John points to the chart on screen]

Transcripts

Provide full text alternative:

• All dialogue
• Sound effects
• Visual information
• Speaker identification

Example structure:

Video Transcript

[0:00] Background music plays
[0:04] John (on camera): "Hello everyone..."
[0:15] [Screen shows code editor]

Keyboard Controls

Essential shortcuts:

• Space - Play/pause
• ←/→ - Rewind/forward
• ↑/↓ - Volume
• M - Mute
• F - Fullscreen
• C - Captions

ARIA Attributes

<div role="region" aria-label="Video player">
  <video id="main-video">...</video>
  <div role="group" aria-label="Playback controls">
    <button aria-label="Play">▶</button>
    <button aria-label="Pause">⏸</button>
    <button aria-label="Mute">🔇</button>
  </div>
</div>

Audio

Transcripts Required

Provide text alternative for all audio:

<audio controls>
  <source src="podcast.mp3" type="audio/mpeg">
</audio>
<a href="podcast-transcript.html">View transcript</a>

Visual Indicators

For deaf/hard of hearing:

• Visual play/pause state
• Waveform visualization
• Progress indicator
• Volume level display

ARIA Labels

<button
  aria-label="Play episode"
  aria-pressed="false"
>
  ▶
</button>

Controls

• Large hit areas (44x44px minimum)
• Keyboard accessible
• Clear focus indicators
• Screen reader announcements

File Upload

Accessibility Requirements

File Input:

<label for="file-upload">
  Choose files to upload
  <input
    type="file"
    id="file-upload"
    multiple
    aria-describedby="file-requirements"
  >
</label>
<div id="file-requirements">
  Maximum 10MB per file. Accepts JPG, PNG, WebP.
</div>

Drag-and-Drop:

<div
  role="button"
  tabindex="0"
  aria-label="Drag and drop files or click to browse"
  class="upload-zone"
>
  <p>Drop files here or click to browse</p>
</div>

Progress Announcements:

<div role="status" aria-live="polite">
  Uploading: 45% complete
</div>

Error Messages:

<div role="alert" aria-live="assertive">
  Upload failed: File too large. Maximum size is 10MB.
</div>

Image Galleries

Keyboard Navigation

• Arrow keys - Navigate between images
• Enter - Open lightbox
• ESC - Close lightbox
• Tab - Navigate controls

Focus Management

Lightbox pattern: 1. Save focus before opening 2. Move focus to first control 3. Trap focus within lightbox 4. Restore focus on close

Screen Reader Support

<figure>
  <img src="photo1.jpg" alt="Description">
  <figcaption>
    Image 1 of 24
  </figcaption>
</figure>

ARIA Carousel

<div
  role="region"
  aria-roledescription="carousel"
  aria-label="Image gallery"
>
  <div role="group" aria-roledescription="slide" aria-label="1 of 10">
    <img src="..." alt="...">
  </div>
</div>

PDF Viewers

Accessible PDFs

Ensure source PDFs are accessible:

• Tagged PDF structure
• Reading order defined
• Alt text for images
• Form labels
• Table headers

Viewer Controls

• Keyboard navigation between pages
• Search function keyboard accessible
• Zoom controls accessible
• Download button labeled

Screen Reader Announcements

<div role="status" aria-live="polite">
  Page 5 of 42
</div>

Testing Checklist

Images

• [ ] Alt text provided for all meaningful images
• [ ] Empty alt for decorative images
• [ ] Complex images have long descriptions
• [ ] Text on images has sufficient contrast

Video

• [ ] Captions available
• [ ] Audio descriptions provided (if needed)
• [ ] Transcript available
• [ ] Keyboard controls work
• [ ] No auto-play or can be paused

Audio

• [ ] Transcript provided
• [ ] Visual playback indicators
• [ ] Keyboard controls
• [ ] ARIA labels on controls

Upload

• [ ] File input labeled
• [ ] Drag-drop keyboard accessible
• [ ] Progress announced
• [ ] Errors announced
• [ ] Success confirmed

Galleries

• [ ] Keyboard navigation works
• [ ] Focus managed in lightbox
• [ ] Current position announced
• [ ] Controls labeled

Validation Tools

Automated Testing

# Run accessibility validation
node scripts/validate_media_accessibility.js

Manual Testing

• Keyboard-only navigation
• Screen reader testing (NVDA, JAWS, VoiceOver)
• High contrast mode
• Zoom to 200%

Resources

• WCAG 2.1 Guidelines
• WebAIM: Alternative Text
• WebAIM: Captions
• ARIA Authoring Practices

See Also

• accessibility-images.md - Image-specific patterns
• accessibility-video.md - Video-specific patterns
• accessibility-audio.md - Audio-specific patterns

Video Accessibility

Captions, transcripts, audio descriptions, and keyboard controls for accessible video.

Captions (Required)

<video controls>
  <source src="video.mp4" type="video/mp4" />
  <track kind="captions" src="captions-en.vtt" srclang="en" label="English" default />
  <track kind="captions" src="captions-es.vtt" srclang="es" label="Spanish" />
</video>

WebVTT Format

WEBVTT

00:00:00.000 --> 00:00:03.000
Welcome to our tutorial

00:00:03.500 --> 00:00:06.000
In this video, we'll cover...

Audio Descriptions

<video controls>
  <source src="video.mp4" />
  <track kind="descriptions" src="descriptions.vtt" srclang="en" label="Descriptions" />
</video>

Transcript

<div>
  <video controls>
    <source src="video.mp4" />
  </video>

  <details className="mt-4">
    <summary>Transcript</summary>
    <p>Full text transcript of the video...</p>
  </details>
</div>

Keyboard Controls

• Space: Play/Pause
• Arrow Left/Right: Skip 5s
• Arrow Up/Down: Volume
• F: Fullscreen
• M: Mute

Best Practices

1. Captions required - WCAG Level A 2. Transcript provided - Full text alternative 3. Audio descriptions - For visual-only content 4. Keyboard controls - All functions accessible 5. No autoplay - Let users control

Resources

• WCAG Media: https://www.w3.org/WAI/media/av/

Advanced Upload Patterns

Chunked uploads, resumable uploads, and multi-file queue management for large files.

Table of Contents

• Chunked Upload (Large Files >100MB)
• Resumable Upload
• Parallel Upload Queue
• Best Practices
• Resources

Chunked Upload (Large Files >100MB)

async function uploadInChunks(file: File, chunkSize = 5 * 1024 * 1024) {  // 5MB chunks
  const totalChunks = Math.ceil(file.size / chunkSize);

  for (let i = 0; i < totalChunks; i++) {
    const start = i * chunkSize;
    const end = Math.min(start + chunkSize, file.size);
    const chunk = file.slice(start, end);

    await fetch('/api/upload/chunk', {
      method: 'POST',
      headers: {
        'X-Upload-ID': uploadId,
        'X-Chunk-Index': i.toString(),
        'X-Total-Chunks': totalChunks.toString(),
      },
      body: chunk,
    });

    setProgress(((i + 1) / totalChunks) * 100);
  }
}

Resumable Upload

function ResumableUpload({ file }: { file: File }) {
  const [uploadedChunks, setUploadedChunks] = useState<Set<number>>(new Set());

  const resume = async () => {
    // Get already uploaded chunks from server
    const { uploadedChunks: existing } = await fetch(`/api/upload/status/${uploadId}`).then(r => r.json());

    setUploadedChunks(new Set(existing));

    // Upload remaining chunks
    for (let i = 0; i < totalChunks; i++) {
      if (!uploadedChunks.has(i)) {
        await uploadChunk(i);
      }
    }
  };

  return (
    <div>
      <button onClick={resume}>Resume Upload</button>
      <span>{uploadedChunks.size} / {totalChunks} chunks uploaded</span>
    </div>
  );
}

Parallel Upload Queue

import PQueue from 'p-queue';

function MultiFileUpload({ files }: { files: File[] }) {
  const [queue] = useState(() => new PQueue({ concurrency: 3 }));  // 3 simultaneous uploads
  const [progress, setProgress] = useState<Map<string, number>>(new Map());

  const uploadFiles = async () => {
    const tasks = files.map((file) =>
      queue.add(async () => {
        await uploadFile(file, (percent) => {
          setProgress((prev) => new Map(prev).set(file.name, percent));
        });
      })
    );

    await Promise.all(tasks);
  };

  return (
    <div>
      {files.map((file) => (
        <div key={file.name}>
          <span>{file.name}</span>
          <progress value={progress.get(file.name) || 0} max={100} />
        </div>
      ))}
    </div>
  );
}

Best Practices

1. Chunk large files - >100MB files into 5-10MB chunks 2. Resume capability - Track uploaded chunks 3. Parallel uploads - Limit concurrency (3-5 max) 4. Progress tracking - Per-file and overall 5. Error retry - Exponential backoff 6. Cancel capability - Allow user to abort

Resources

• tus.js (resumable): https://github.com/tus/tus-js-client
• Uppy: https://uppy.io/

Audio Player Implementation

Custom audio players with waveform visualization, playlists, and controls.

Table of Contents

• Native HTML5 Audio
• Custom Audio Player
• Waveform Visualization
• Playlist
• Resources

Native HTML5 Audio

<audio controls>
  <source src="audio.mp3" type="audio/mpeg" />
  <source src="audio.ogg" type="audio/ogg" />
  Your browser does not support audio.
</audio>

Custom Audio Player

function AudioPlayer({ src }: { src: string }) {
  const audioRef = useRef<HTMLAudioElement>(null);
  const [isPlaying, setIsPlaying] = useState(false);
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);

  const togglePlay = () => {
    if (isPlaying) {
      audioRef.current?.pause();
    } else {
      audioRef.current?.play();
    }
    setIsPlaying(!isPlaying);
  };

  return (
    <div className="audio-player">
      <audio
        ref={audioRef}
        src={src}
        onTimeUpdate={(e) => setCurrentTime(e.currentTarget.currentTime)}
        onDurationChange={(e) => setDuration(e.currentTarget.duration)}
        onEnded={() => setIsPlaying(false)}
      />

      <button onClick={togglePlay}>
        {isPlaying ? '⏸' : '▶'}
      </button>

      <input
        type="range"
        min={0}
        max={duration}
        value={currentTime}
        onChange={(e) => {
          const time = parseFloat(e.target.value);
          audioRef.current!.currentTime = time;
          setCurrentTime(time);
        }}
        className="flex-1"
      />

      <span>{formatTime(currentTime)} / {formatTime(duration)}</span>
    </div>
  );
}

function formatTime(seconds: number): string {
  const mins = Math.floor(seconds / 60);
  const secs = Math.floor(seconds % 60);
  return `${mins}:${secs.toString().padStart(2, '0')}`;
}

Waveform Visualization

import WaveSurfer from 'wavesurfer.js';

function WaveformPlayer({ src }: { src: string }) {
  const waveformRef = useRef<HTMLDivElement>(null);
  const wavesurfer = useRef<WaveSurfer | null>(null);

  useEffect(() => {
    wavesurfer.current = WaveSurfer.create({
      container: waveformRef.current!,
      waveColor: '#4F4A85',
      progressColor: '#3B82F6',
      cursorColor: '#3B82F6',
      height: 80,
    });

    wavesurfer.current.load(src);

    return () => wavesurfer.current?.destroy();
  }, [src]);

  return (
    <div>
      <div ref={waveformRef} />
      <button onClick={() => wavesurfer.current?.playPause()}>
        Play/Pause
      </button>
    </div>
  );
}

Playlist

function Playlist({ tracks }: { tracks: Track[] }) {
  const [currentTrack, setCurrentTrack] = useState(0);

  return (
    <div>
      <AudioPlayer
        src={tracks[currentTrack].url}
        onEnded={() => setCurrentTrack((currentTrack + 1) % tracks.length)}
      />

      <div className="playlist">
        {tracks.map((track, i) => (
          <div
            key={track.id}
            onClick={() => setCurrentTrack(i)}
            className={currentTrack === i ? 'active' : ''}
          >
            {track.title} - {track.artist}
          </div>
        ))}
      </div>
    </div>
  );
}

Resources

• WaveSurfer.js: https://wavesurfer-js.org/
• Howler.js: https://howlerjs.com/

Carousel and Slider Patterns

Image carousels, sliders, and slideshow implementations with accessibility.

Basic Carousel

function Carousel({ images }: { images: string[] }) {
  const [currentIndex, setCurrentIndex] = useState(0);

  const next = () => setCurrentIndex((currentIndex + 1) % images.length);
  const prev = () => setCurrentIndex((currentIndex - 1 + images.length) % images.length);

  return (
    <div className="relative">
      <img src={images[currentIndex]} alt={`Slide ${currentIndex + 1}`} />

      <button onClick={prev} className="absolute left-4 top-1/2 -translate-y-1/2">
        ←
      </button>
      <button onClick={next} className="absolute right-4 top-1/2 -translate-y-1/2">
        →
      </button>

      <div className="absolute bottom-4 left-1/2 -translate-x-1/2 flex gap-2">
        {images.map((_, i) => (
          <button
            key={i}
            onClick={() => setCurrentIndex(i)}
            className={`w-2 h-2 rounded-full ${i === currentIndex ? 'bg-white' : 'bg-white/50'}`}
          />
        ))}
      </div>
    </div>
  );
}

Swiper.js Integration

import { Swiper, SwiperSlide } from 'swiper/react';
import { Navigation, Pagination, Autoplay } from 'swiper/modules';
import 'swiper/css';

<Swiper
  modules={[Navigation, Pagination, Autoplay]}
  navigation
  pagination={{ clickable: true }}
  autoplay={{ delay: 3000 }}
  loop
>
  {images.map((img, i) => (
    <SwiperSlide key={i}>
      <img src={img} alt={`Slide ${i + 1}`} />
    </SwiperSlide>
  ))}
</Swiper>

Keyboard Navigation

useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'ArrowLeft') prev();
    if (e.key === 'ArrowRight') next();
  };

  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, []);

Best Practices

1. Keyboard navigation - Arrow keys, Home, End 2. Touch gestures - Swipe on mobile 3. Pagination dots - Show current slide 4. Lazy load - Load adjacent slides only 5. Pause on hover - Stop autoplay 6. ARIA labels - For screen readers 7. Performance - Limit simultaneous slides in DOM

Resources

• Swiper: https://swiperjs.com/
• Embla Carousel: https://www.embla-carousel.com/

Cloud Storage Integration

S3, R2, and GCS integration for media upload and delivery.

S3 Direct Upload (Pre-signed URLs)

Backend (Generate Pre-signed URL)

import boto3
from datetime import timedelta

s3 = boto3.client('s3')

def generate_presigned_upload(filename: str) -> dict:
    key = f"uploads/{uuid.uuid4()}/{filename}"

    presigned_data = s3.generate_presigned_post(
        Bucket='my-bucket',
        Key=key,
        ExpiresIn=3600,  # 1 hour
        Conditions=[
            ['content-length-range', 0, 10485760],  # Max 10MB
            ['starts-with', '$Content-Type', 'image/'],
        ]
    )

    return {
        'url': presigned_data['url'],
        'fields': presigned_data['fields'],
        'key': key,
    }

Frontend (Upload Directly to S3)

async function uploadToS3(file: File) {
  // 1. Get pre-signed URL from backend
  const { url, fields, key } = await fetch('/api/upload/presign', {
    method: 'POST',
    body: JSON.stringify({ filename: file.name }),
  }).then(r => r.json());

  // 2. Upload directly to S3
  const formData = new FormData();
  Object.entries(fields).forEach(([k, v]) => formData.append(k, v as string));
  formData.append('file', file);

  await fetch(url, {
    method: 'POST',
    body: formData,
  });

  return key;
}

Cloudflare R2

// Backend
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

const r2 = new S3Client({
  region: 'auto',
  endpoint: `https://${ACCOUNT_ID}.r2.cloudflarestorage.com`,
  credentials: {
    accessKeyId: R2_ACCESS_KEY_ID,
    secretAccessKey: R2_SECRET_ACCESS_KEY,
  },
});

await r2.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: key,
  Body: buffer,
  ContentType: 'image/jpeg',
}));

Best Practices

1. Pre-signed URLs - Direct upload to S3/R2 2. CDN in front - CloudFront, Cloudflare 3. Lifecycle policies - Auto-delete temp files 4. Access control - Signed URLs for private content 5. Compression - Client-side before upload

Resources

• AWS S3: https://aws.amazon.com/s3/
• Cloudflare R2: https://developers.cloudflare.com/r2/

Image Gallery Patterns

Grid Gallery

CSS Grid Layout

.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: var(--gallery-gap);
}

Features

• Responsive columns
• Lazy loading
• Click to lightbox
• Keyboard navigation

Masonry Layout

Pinterest-Style

• Variable height items
• Optimal packing
• Libraries: Masonry.js, react-masonry-css

Implementation Considerations

• More complex than grid
• Better for varied aspect ratios
• Performance impact with many images

Lightbox

Core Features

• Overlay background
• Full-size image display
• Previous/next navigation
• Zoom and pan
• Close on ESC or click outside

Accessibility

• Focus trap within lightbox
• Arrow key navigation
• ESC to close
• Keyboard accessible controls

Lazy Loading

Native Lazy Loading

<img src="image.jpg" loading="lazy" alt="Description" />

Intersection Observer

For more control:

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const img = entry.target;
      img.src = img.dataset.src;
      observer.unobserve(img);
    }
  });
});

Responsive Images

Srcset and Sizes

<img
  src="image-800.jpg"
  srcset="
    image-400.jpg 400w,
    image-800.jpg 800w,
    image-1200.jpg 1200w
  "
  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
  alt="Description"
/>

Performance Optimization

• Load thumbnails first
• Lazy load off-screen images
• Use WebP with JPG fallback
• Preload next/previous in lightbox
• Limit initial gallery size

See Also

• carousel-patterns.md - Carousel implementations
• image-optimization.md - Image optimization strategies
• accessibility-images.md - Image accessibility

Image Optimization Guide

Reduce file sizes and improve load times with responsive images, modern formats, and lazy loading.

Table of Contents

• Modern Image Formats
• Responsive Images
• Next.js Image Component
• Lazy Loading
• Client-Side Compression
• CDN Integration
• Best Practices
• Tools

Modern Image Formats

Responsive Images

<img
  srcset="
    image-320.webp 320w,
    image-640.webp 640w,
    image-1280.webp 1280w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
  src="image-640.jpg"
  alt="Description"
/>

Next.js Image Component

import Image from 'next/image';

<Image
  src="/photos/sunset.jpg"
  alt="Sunset"
  width={800}
  height={600}
  quality={85}  // 0-100, default 75
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."
  loading="lazy"
/>

Lazy Loading

<img
  src="image.jpg"
  loading="lazy"  // Native lazy loading
  alt="Description"
/>

Client-Side Compression

async function optimizeImage(file: File): Promise<Blob> {
  const img = await createImageBitmap(file);
  const canvas = document.createElement('canvas');

  // Resize to max 1920px width
  const scale = Math.min(1, 1920 / img.width);
  canvas.width = img.width * scale;
  canvas.height = img.height * scale;

  const ctx = canvas.getContext('2d')!;
  ctx.drawImage(img, 0, 0, canvas.width, canvas.height);

  return new Promise((resolve) => {
    canvas.toBlob((blob) => resolve(blob!), 'image/webp', 0.85);
  });
}

CDN Integration

// Cloudflare Images
const cloudflareUrl = (imageId: string, variant: string) =>
  `https://imagedelivery.net/${ACCOUNT_HASH}/${imageId}/${variant}`;

<img src={cloudflareUrl('img-id', 'public')} alt="..." />

// With transformations
<img src={cloudflareUrl('img-id', 'thumbnail')} alt="Thumbnail" />

Best Practices

1. Use WebP/AVIF - 30-50% smaller than JPEG 2. Responsive images - srcset for different screen sizes 3. Lazy loading - Below-the-fold images 4. Compress before upload - Client-side optimization 5. CDN delivery - Global edge caching 6. Placeholder - Blur or solid color while loading 7. Alt text - Always include for accessibility 8. Dimensions - Prevent layout shift

Tools

• Sharp (Node.js): https://sharp.pixelplumbing.com/
• ImageMagick: https://imagemagick.org/
• Cloudflare Images: https://developers.cloudflare.com/images/

Image Upload Patterns

Client-side image upload with validation, preview, and optimization.

Table of Contents

• Basic Upload with Preview
• Drag and Drop
• Client-Side Compression
• Multiple File Upload
• Progress Indicator
• Best Practices

Basic Upload with Preview

function ImageUpload({ onUpload }: { onUpload: (file: File) => void }) {
  const [preview, setPreview] = useState<string | null>(null);

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Validate
    if (!file.type.startsWith('image/')) {
      alert('Please upload an image');
      return;
    }

    if (file.size > 10 * 1024 * 1024) {  // 10MB
      alert('Image must be <10MB');
      return;
    }

    // Preview
    const reader = new FileReader();
    reader.onload = (e) => setPreview(e.target?.result as string);
    reader.readAsDataURL(file);

    onUpload(file);
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={handleFileChange} />
      {preview && <img src={preview} alt="Preview" style={{ maxWidth: '300px' }} />}
    </div>
  );
}

Drag and Drop

function DragDropUpload({ onUpload }: Props) {
  const [isDragging, setIsDragging] = useState(false);

  return (
    <div
      onDragOver={(e) => { e.preventDefault(); setIsDragging(true); }}
      onDragLeave={() => setIsDragging(false)}
      onDrop={(e) => {
        e.preventDefault();
        setIsDragging(false);
        const files = Array.from(e.dataTransfer.files);
        files.forEach(onUpload);
      }}
      className={`border-2 border-dashed p-8 ${isDragging ? 'border-blue-500 bg-blue-50' : 'border-gray-300'}`}
    >
      Drag images here or click to upload
    </div>
  );
}

Client-Side Compression

async function compressImage(file: File, maxWidth: number = 1920): Promise<Blob> {
  return new Promise((resolve) => {
    const img = new Image();
    img.onload = () => {
      const canvas = document.createElement('canvas');
      const scale = Math.min(1, maxWidth / img.width);

      canvas.width = img.width * scale;
      canvas.height = img.height * scale;

      const ctx = canvas.getContext('2d')!;
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);

      canvas.toBlob((blob) => resolve(blob!), 'image/jpeg', 0.85);
    };
    img.src = URL.createObjectURL(file);
  });
}

Multiple File Upload

function MultipleImageUpload() {
  const [files, setFiles] = useState<File[]>([]);

  const handleMultipleFiles = (e: React.ChangeEvent<HTMLInputElement>) => {
    const selected = Array.from(e.target.files || []);
    setFiles((prev) => [...prev, ...selected]);
  };

  return (
    <div>
      <input type="file" multiple accept="image/*" onChange={handleMultipleFiles} />

      <div className="grid grid-cols-3 gap-4 mt-4">
        {files.map((file, i) => (
          <div key={i} className="relative">
            <img src={URL.createObjectURL(file)} alt={file.name} />
            <button
              onClick={() => setFiles(files.filter((_, idx) => idx !== i))}
              className="absolute top-2 right-2 bg-red-500 text-white rounded-full w-6 h-6"
            >
              ×
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

Progress Indicator

function UploadWithProgress({ file }: { file: File }) {
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const xhr = new XMLHttpRequest();

    xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        setProgress((e.loaded / e.total) * 100);
      }
    });

    const formData = new FormData();
    formData.append('file', file);

    xhr.open('POST', '/api/upload');
    xhr.send(formData);
  }, [file]);

  return (
    <div className="w-full bg-gray-200 rounded">
      <div
        className="bg-blue-500 h-2 rounded transition-all"
        style={{ width: `${progress}%` }}
      />
      <span className="text-sm">{Math.round(progress)}%</span>
    </div>
  );
}

Best Practices

1. Validate client-side - File type, size, dimensions 2. Show preview - Let users confirm before upload 3. Compress images - Reduce bandwidth 4. Progress indicator - For uploads >1MB 5. Allow removal - Before submission 6. Handle errors - Network failures, validation 7. Multiple files - Support batch upload 8. Drag and drop - Better UX than file picker

Media Implementation Guide

Decision Framework

This guide helps select the appropriate media implementation based on requirements.

File Upload Selection

Basic Upload (<10MB)

• Single file upload
• Simple validation
• Preview capability
• Progress indicator

Advanced Upload (>10MB)

• Chunked uploads
• Resume capability
• Queue management
• Multiple files

Cloud Direct Upload

• Large files (>100MB)
• Reduced server load
• CDN integration
• Client-side signing

Image Display Selection

Static Gallery

• Fixed number of images
• Grid layout
• Click to expand

Dynamic Gallery

• Lazy loading
• Infinite scroll
• Search/filter

Carousel/Slider

• Sequential display
• Auto-play option
• Navigation controls

Video Implementation Selection

Native HTML5

• Simple requirements
• Basic controls
• No streaming needed

Custom Player (video.js)

• Advanced features
• Plugin support
• Adaptive streaming

Cloud Video (Vimeo/YouTube)

• Hosted solution
• No transcoding
• Embed controls

Performance Thresholds

See Also

• upload-patterns.md - Upload implementations
• gallery-patterns.md - Gallery designs
• video-player.md - Video player setup

Media Library Comparison

Table of Contents

• Image Galleries
• react-image-gallery
• LightGallery
• React Image Lightbox
• Video Players
• video.js
• Plyr
• ReactPlayer
• Audio Players
• wavesurfer.js
• Howler.js
• react-h5-audio-player
• PDF Viewers
• react-pdf
• PDF.js (Mozilla)
• Cloud Viewers
• File Upload
• react-dropzone
• Uppy
• Filepond
• Selection Guide
• Choose react-image-gallery when:
• Choose video.js when:
• Choose wavesurfer.js when:
• Choose react-pdf when:
• Choose react-dropzone when:
• Performance Comparison
• Accessibility Comparison
• See Also

Image Galleries

react-image-gallery

Trust Score: 8.6/10 Code Snippets: 11+ Bundle Size: ~30KB

Pros:

• Feature complete out of the box
• Mobile swipe support
• Fullscreen mode
• Good documentation

Cons:

• Larger bundle size
• Less customization than headless

Best For: Complete gallery solution with minimal setup

---

LightGallery

Trust Score: 9.6/10 Code Snippets: 429+

Pros:

• Extensive features
• Excellent documentation
• Plugin ecosystem
• Touch gestures

Cons:

• Large bundle size (~100KB+)
• Commercial license for some features

Best For: Feature-rich galleries, enterprises

---

React Image Lightbox

Bundle Size: ~15KB

Pros:

• Lightweight
• Simple API
• Good keyboard support

Cons:

• Limited features
• Less active maintenance

Best For: Simple lightbox needs, small bundle

---

Video Players

video.js

Trust Score: 9.0+/10 Community: Very active

Pros:

• Industry standard
• Plugin ecosystem
• HLS/DASH support
• Excellent accessibility
• Free and open source

Cons:

• Larger learning curve
• More setup required

Best For: Professional video needs, streaming

---

Plyr

Bundle Size: ~30KB

Pros:

• Beautiful default UI
• Simple setup
• Good accessibility
• Multiple providers (YouTube, Vimeo)

Cons:

• Less extensible than video.js
• Smaller community

Best For: Quick setup, embedded videos

---

ReactPlayer

Bundle Size: ~64KB

Pros:

• Supports many sources
• React-first API
• Simple integration

Cons:

• Less customization
• Depends on external players

Best For: Multi-source video (YouTube, Vimeo, files)

---

Audio Players

wavesurfer.js

Trust Score: 8.5+/10

Pros:

• Beautiful waveforms
• Plugin support
• Responsive
• Good documentation

Cons:

• Performance with very long audio
• Setup complexity

Best For: Waveform visualization, music apps

---

Howler.js

Bundle Size: ~9KB

Pros:

• Lightweight
• Audio sprite support
• Web Audio API
• Cross-browser

Cons:

• No built-in UI
• Manual waveform needed

Best For: Audio playback without UI, games

---

react-h5-audio-player

Bundle Size: ~20KB

Pros:

• Ready-to-use UI
• Responsive
• Accessible
• Playlist support

Cons:

• Limited customization
• No waveform

Best For: Standard audio player with UI

---

PDF Viewers

react-pdf

Trust Score: 9.0+/10

Pros:

• Renders in browser
• Text selection
• Worker-based
• Customizable

Cons:

• Bundle size (~150KB)
• Setup complexity

Best For: Full-featured PDF rendering

---

PDF.js (Mozilla)

Pros:

• Industry standard
• Complete feature set
• Free and open source

Cons:

• Large bundle
• Complex API

Best For: Advanced PDF needs

---

Cloud Viewers

Google Docs Viewer, Office Online

Pros:

• No client-side processing
• Supports many formats
• No bundle impact

Cons:

• Requires internet
• Privacy concerns
• Less control

Best For: Simple preview, public documents

---

File Upload

react-dropzone

Trust Score: 9.0+/10

Pros:

• Headless (full control)
• Small bundle (~10KB)
• Excellent API
• Accessible

Cons:

• No UI provided
• Manual styling needed

Best For: Custom upload UI