managing-media

What this skill does

# 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

```bash
# 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:
```bash
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

```bash
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

```bash
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

```bash
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

```bash
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